X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/8e30cc93fcf10cc99533d7ed3161b6c4a0fabd93..8b56266921d2bcc160536b9d155b4e5394e1d735:/pod/perlfunc.pod

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 69dd5aa..370353b 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -129,13 +129,16 @@ C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec>
 =item Functions for filehandles, files, or directories
 
 C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
-C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>, C<readlink>,
-C<rename>, C<rmdir>, C<stat>, C<symlink>, C<umask>, C<unlink>, C<utime>
+C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
+C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<umask>,
+C<unlink>, C<utime>
 
 =item Keywords related to the control flow of your perl program
 
-C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>,
-C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>
+C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<else>, C<elsif>,
+C<eval>, C<exit>, C<for>, C<foreach>, C<goto>, C<if>, C<last>,
+C<next>, C<redo>, C<return>, C<sub>, C<unless>, C<wantarray>,
+C<while>, C<until>
 
 =item Keywords related to scoping
 
@@ -206,6 +209,34 @@ C<dbmclose>, C<dbmopen>
 
 =back
 
+=head2 Portability
+
+Perl was born in UNIX and therefore it can access all the common UNIX
+system calls.  In non-UNIX environments the functionality of many
+UNIX system calls may not be available or the details of the available
+functionality may be slightly different.  The Perl functions affected
+by this are:
+
+C<-X>, C<binmode>, C<chmod>, C<chown>, C<chroot>, C<crypt>,
+C<dbmclose>, C<dbmopen>, C<dump>, C<endgrent>, C<endhostent>,
+C<endnetent>, C<endprotoent>, C<endpwent>, C<endservent>, C<exec>,
+C<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostent>,
+C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
+C<getppid>, C<getprgp>, C<getpriority>, C<getprotobynumber>,
+C<getprotoent>, C<getpwent>, C<getpwnam>, C<getpwuid>,
+C<getservbyport>, C<getservent>, C<getsockopt>, C<glob>, C<ioctl>,
+C<kill>, C<link>, C<lstat>, C<msgctl>, C<msgget>, C<msgrcv>,
+C<msgsnd>, C<open>, C<pipe>, C<readlink>, C<select>, C<semctl>,
+C<semget>, C<semop>, C<setgrent>, C<sethostent>, C<setnetent>,
+C<setpgrp>, C<setpriority>, C<setprotoent>, C<setpwent>,
+C<setservent>, C<setsockopt>, C<shmctl>, C<shmget>, C<shmread>,
+C<shmwrite>, C<socketpair>, C<stat>, C<symlink>, C<syscall>,
+C<sysopen>, C<system>, C<times>, C<truncate>, C<umask>, C<utime>,
+C<wait>, C<waitpid>
+
+For more information about the portability of these functions, see
+L<perlport> and other available platform-specific documentation.
+
 =head2 Alphabetical Listing of Perl Functions
 
 =over 8
@@ -225,6 +256,8 @@ the undefined value if the file doesn't exist.  Despite the funny
 names, precedence is the same as any other named unary operator, and
 the argument may be parenthesized like any other unary operator.  The
 operator may be any of:
+X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p>
+X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
 
     -r	File is readable by effective uid/gid.
     -w	File is writable by effective uid/gid.
@@ -260,15 +293,6 @@ operator may be any of:
     -A	Same for access time.
     -C	Same for inode change time.
 
-The interpretation of the file permission operators C<-r>, C<-R>, C<-w>,
-C<-W>, C<-x>, and C<-X> is based solely on the mode of the file and the
-uids and gids of the user.  There may be other reasons you can't actually
-read, write, or execute the file, such as AFS access control lists.  Also note that, for the superuser,
-C<-r>, C<-R>, C<-w>, and C<-W> always return C<1>, and C<-x> and C<-X> return
-C<1> if any execute bit is set in the mode.  Scripts run by the superuser may
-thus need to do a C<stat()> to determine the actual mode of the
-file, or temporarily set the uid to something else.
-
 Example:
 
     while (<>) {
@@ -277,6 +301,31 @@ Example:
 	#...
     }
 
+The interpretation of the file permission operators C<-r>, C<-R>,
+C<-w>, C<-W>, C<-x>, and C<-X> is by default based solely on the mode
+of the file and the uids and gids of the user.  There may be other
+reasons you can't actually read, write, or execute the file.  Such
+reasons may be for example network filesystem access controls, ACLs
+(access control lists), read-only filesystems, and unrecognized
+executable formats.
+
+Also note that, for the superuser on the local filesystems, C<-r>,
+C<-R>, C<-w>, and C<-W> always return 1, and C<-x> and C<-X> return 1
+if any execute bit is set in the mode.  Scripts run by the superuser
+may thus need to do a stat() to determine the actual mode of the file,
+or temporarily set the uid to something else.
+
+If you are using ACLs, there is a pragma called C<filetest> that may
+produce more accurate results than the bare stat() mode bits.
+
+When under the C<use filetest 'access'> the above-mentioned filetests
+will test whether the permission can (not) be granted using the
+access() family of system calls.  Also note that the C<-x> and C<-X> may
+under this pragma return true even if there are no execute permission
+bits set (nor any extra execute permission ACLs).  This strangeness is
+due to the underlying system calls' definitions.  Read the
+documentation for the C<filetest> pragma for more information.
+
 Note that C<-s/a/b/> does not do a negated substitution.  Saying
 C<-exp($foo)> still works as expected, however--only single letters
 following a minus are interpreted as file tests.
@@ -405,6 +454,12 @@ Always use the two-argument version if the function doing the blessing
 might be inherited by a derived class.  See L<perltoot> and L<perlobj>
 for more about the blessing (and blessings) of objects.
 
+Creating objects in lowercased CLASSNAMEs should be avoided.  Such 
+namespaces should be considered reserved for Perl pragmata and objects
+that may be created to implement internal operations.
+
+See L<perlmod/"Perl Modules">.
+
 =item caller EXPR
 
 =item caller
@@ -553,7 +608,9 @@ restrictions may be relaxed, but this is not a portable assumption.
 =item chr
 
 Returns the character represented by that NUMBER in the character set.
-For example, C<chr(65)> is C<"A"> in ASCII.  For the reverse, use L</ord>.
+For example, C<chr(65)> is C<"A"> in either ASCII or Unicode, and
+chr(0x263a) is a Unicode smiley face (but only within the scope of a
+C<use utf8>).  For the reverse, use L</ord>.
 
 If NUMBER is omitted, uses C<$_>.
 
@@ -622,14 +679,14 @@ L<perlipc/"Sockets: Client/Server Communication">.
 =item continue BLOCK
 
 Actually a flow control statement rather than a function.  If there is a
-C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
-C<foreach>), it is always executed just before the conditional is about to
-be evaluated again, just like the third part of a C<for> loop in C.  Thus
+C<continue> BLOCK attached to a BLOCK (typically in a L</while> or
+L</foreach>), it is always executed just before the conditional is about to
+be evaluated again, just like the third part of a L</for> loop in C.  Thus
 it can be used to increment a loop variable, even when the loop has been
 continued via the C<next> statement (which is similar to the C C<continue>
 statement).
 
-C<last>, C<next>, or C<redo> may appear within a C<continue>
+L</last>, L</next>, or L</redo> may appear within a C<continue>
 block. C<last> and C<redo> will behave as if they had been executed within
 the main block. So will C<next>, but since it will execute a C<continue>
 block, it may be more entertaining.
@@ -648,6 +705,8 @@ Omitting the C<continue> section is semantically equivalent to using an
 empty one, logically enough. In that case, C<next> goes directly back
 to check the condition at the top of the loop.
 
+See also L<perlsyn>.
+
 =item cos EXPR
 
 Returns the cosine of EXPR (expressed in radians).  If EXPR is omitted,
@@ -671,19 +730,25 @@ eggs to make an omelette.  There is no (known) corresponding decrypt
 function.  As a result, this function isn't all that useful for
 cryptography.  (For that, see your nearby CPAN mirror.)
 
+When verifying an existing encrypted string you should use the encrypted
+text as the salt (like C<crypt($plain, $crypted) eq $crypted>).  This
+allows your code to work with the standard C<crypt()> and with more
+exotic implementations.  When choosing a new salt create a random two
+character string whose characters come from the set C<[./0-9A-Za-z]>
+(like C<join '', ('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>).
+
 Here's an example that makes sure that whoever runs this program knows
 their own password:
 
     $pwd = (getpwuid($<))[1];
-    $salt = substr($pwd, 0, 2);
 
     system "stty -echo";
     print "Password: ";
-    chop($word = <STDIN>);
+    chomp($word = <STDIN>);
     print "\n";
     system "stty echo";
 
-    if (crypt($word, $salt) ne $pwd) {
+    if (crypt($word, $pwd) ne $pwd) {
 	die "Sorry...\n";
     } else {
 	print "ok\n";
@@ -887,8 +952,12 @@ as the first line of the handler (see L<perlvar/$^S>).
 
 Not really a function.  Returns the value of the last command in the
 sequence of commands indicated by BLOCK.  When modified by a loop
-modifier, executes the BLOCK once before testing the loop condition.
-(On other statements the loop modifiers test the conditional first.)
+modifier such as L</while> or L</until>, executes the BLOCK once
+before testing the loop condition.  (On other statements the loop
+modifiers test the conditional first.)
+
+C<do BLOCK> does I<not> count as a loop, so the loop control statements
+L</next>, L</last> or L</redo> cannot be used to leave or restart the block.
 
 =item do SUBROUTINE(LIST)
 
@@ -984,9 +1053,13 @@ element in the hash.  (Note: Keys may be C<"0"> or C<"">, which are logically
 false; you may wish to avoid constructs like C<while ($k = each %foo) {}>
 for this reason.)
 
-Entries are returned in an apparently random order.  When the hash is
-entirely read, a null array is returned in list context (which when
-assigned produces a FALSE (C<0>) value), and C<undef> in
+Entries are returned in an apparently random order.  The actual random
+order is subject to change in future versions of perl, but it is guaranteed
+to be in the same order as either the C<keys()> or C<values()> function
+would produce on the same (unmodified) hash.
+
+When the hash is entirely read, a null array is returned in list context
+(which when assigned produces a FALSE (C<0>) value), and C<undef> in
 scalar context.  The next call to C<each()> after that will start iterating
 again.  There is a single iterator for each hash, shared by all C<each()>,
 C<keys()>, and C<values()> function calls in the program; it can be reset by
@@ -1001,7 +1074,13 @@ only in a different order:
 	print "$key=$value\n";
     }
 
-See also C<keys()> and C<values()>.
+See also C<keys()>, C<values()> and C<sort()>.
+
+=item else BLOCK
+
+=item elsif (EXPR) BLOCK
+
+See L</if>.
 
 =item eof FILEHANDLE
 
@@ -1148,6 +1227,10 @@ normally you I<WOULD> like to use double quotes, except that in this
 particular situation, you can just use symbolic references instead, as
 in case 6.
 
+C<eval BLOCK> does I<not> count as a loop, so the loop control statements
+C<next>, C<last> or C<redo> cannot be used to leave or restart the block.
+
+
 =item exec LIST
 
 =item exec PROGRAM LIST
@@ -1370,6 +1453,38 @@ Here's a mailbox appender for BSD systems.
 
 See also L<DB_File> for other flock() examples.
 
+=item for (INITIAL; WHILE; EACH) BLOCK
+
+Do INITIAL, enter BLOCK while EXPR is true, at the end of each round
+do EACH. For example:
+
+	for ($i = 0, $j = 0; $i < 10; $i++) {
+		if ($i % 3 == 0) { $j++ }
+		print "i = $i, j = $j\n";
+	}
+
+See L<perlsyn> for more details.  See also L</foreach>, a twin of
+C<for>, L</while> and L</until>, close cousins of L<for>, and
+L</last>, L</next>, and L</redo> for additional control flow.
+
+=item foreach LOOPVAR (LIST) BLOCK
+
+Enter BLOCK as LOOPVAR set in turn to each element of LIST.
+For example:
+
+	foreach $rolling (@stones) { print "rolling $stone\n" }
+
+	foreach my $file (@files)  { print "file $file\n" }
+
+The LOOPVAR is optional and defaults to C<$_>.  If the elements are
+modifiable (as opposed to constants or tied variables) you can modify them.
+
+	foreach (@words) { tr/abc/xyz/ }
+
+See L<perlsyn> for more details.  See also L</for>, a twin of
+C<foreach>, L</while> and L</until>, close cousins of L<for>, and
+L</last>, L</next>, and L</redo> for additional control flow.
+
 =item fork
 
 Does a fork(2) system call.  Returns the child pid to the parent process,
@@ -1776,6 +1891,21 @@ see L</oct>.)  If EXPR is omitted, uses C<$_>.
     print hex '0xAf'; # prints '175'
     print hex 'aF';   # same
 
+=item if (EXPR) BLOCK
+
+=item if (EXPR) BLOCK else BLOCK2
+
+=item if (EXPR) BLOCK elsif (EXPR2) BLOCK2
+
+Enter BLOCKs conditionally.  The first EXPR to return true
+causes the corresponding BLOCK to be entered, or, in the case
+of C<else>, the fall-through default BLOCK.
+
+Take notice: Perl wants BLOCKS, expressions (like e.g. in C, C++, or
+Pascal) won't do.
+
+See L<perlsyn> for more details.  See also C<unless>.
+
 =item import
 
 There is no builtin C<import()> function.  It is just an ordinary
@@ -1865,9 +1995,11 @@ See L</split>.
 
 Returns a list consisting of all the keys of the named hash.  (In a
 scalar context, returns the number of keys.)  The keys are returned in
-an apparently random order, but it is the same order as either the
-C<values()> or C<each()> function produces (given that the hash has not been
-modified).  As a side effect, it resets HASH's iterator.
+an apparently random order.  The actual random order is subject to
+change in future versions of perl, but it is guaranteed to be the same
+order as either the C<values()> or C<each()> function produces (given
+that the hash has not been modified).  As a side effect, it resets
+HASH's iterator.
 
 Here is yet another way to print your environment:
 
@@ -1883,7 +2015,7 @@ or how about sorted by key:
 	print $key, '=', $ENV{$key}, "\n";
     }
 
-To sort an array by value, you'll need to use a C<sort()> function.
+To sort a hash by value, you'll need to use a C<sort()> function.
 Here's a descending numeric sort of a hash by its values:
 
     foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
@@ -1897,14 +2029,16 @@ an array by assigning a larger number to $#array.)  If you say
 
     keys %hash = 200;
 
-then C<%hash> will have at least 200 buckets allocated for it--256 of them, in fact, since 
-it rounds up to the next power of two.  These
+then C<%hash> will have at least 200 buckets allocated for it--256 of them,
+in fact, since it rounds up to the next power of two.  These
 buckets will be retained even if you do C<%hash = ()>, use C<undef
 %hash> if you want to free the storage while C<%hash> is still in scope.
 You can't shrink the number of buckets allocated for the hash using
 C<keys()> in this way (but you needn't worry about doing this by accident,
 as trying has no effect).
 
+See also C<each()>, C<values()> and C<sort()>.
+
 =item kill LIST
 
 Sends a signal to a list of processes.  The first element of
@@ -1934,8 +2068,13 @@ C<continue> block, if any, is not executed:
 	#...
     }
 
-See also L</continue> for an illustration of how C<last>, C<next>, and
-C<redo> work.
+C<last> cannot be used to exit a block which returns a value such as
+C<eval {}>, C<sub {}> or C<do {}>.
+
+See also L</continue> for an illustration of how C<last>, L</next>, and
+L</redo> work.
+
+See also L<perlsyn>.
 
 =item lc EXPR
 
@@ -1943,7 +2082,7 @@ C<redo> work.
 
 Returns an lowercased version of EXPR.  This is the internal function
 implementing the C<\L> escape in double-quoted strings.
-Respects current C<LC_CTYPE> locale if C<use locale> in force.  See L<perllocale>.
+Respects current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>.
 
 If EXPR is omitted, uses C<$_>.
 
@@ -1953,7 +2092,7 @@ If EXPR is omitted, uses C<$_>.
 
 Returns the value of EXPR with the first character lowercased.  This is
 the internal function implementing the C<\l> escape in double-quoted strings.
-Respects current C<LC_CTYPE> locale if C<use locale> in force.  See L<perllocale>.
+Respects current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>.
 
 If EXPR is omitted, uses C<$_>.
 
@@ -1961,7 +2100,7 @@ If EXPR is omitted, uses C<$_>.
 
 =item length
 
-Returns the length in bytes of the value of EXPR.  If EXPR is
+Returns the length in characters of the value of EXPR.  If EXPR is
 omitted, returns length of C<$_>.
 
 =item link OLDFILE,NEWFILE
@@ -2073,9 +2212,16 @@ original list for which the BLOCK or EXPR evaluates to true.
 
 =item mkdir FILENAME,MODE
 
-Creates the directory specified by FILENAME, with permissions specified
-by MODE (as modified by umask).  If it succeeds it returns TRUE, otherwise
-it returns FALSE and sets C<$!> (errno).
+Creates the directory specified by FILENAME, with permissions
+specified by MODE (as modified by C<umask>).  If it succeeds it
+returns TRUE, otherwise it returns FALSE and sets C<$!> (errno).
+
+In general, it is better to create directories with permissive MODEs,
+and let the user modify that with their C<umask>, than it is to supply
+a restrictive MODE and give the user no way to be more permissive.
+The exceptions to this rule are when the file or directory should be
+kept private (mail files, for instance).  The perlfunc(1) entry on
+C<umask> discusses the choice of MODE in more detail.
 
 =item msgctl ID,CMD,ARG
 
@@ -2135,8 +2281,13 @@ Note that if there were a C<continue> block on the above, it would get
 executed even on discarded lines.  If the LABEL is omitted, the command
 refers to the innermost enclosing loop.
 
-See also L</continue> for an illustration of how C<last>, C<next>, and
-C<redo> work.
+C<next> cannot be used to exit a block which returns a value such as
+C<eval {}>, C<sub {}> or C<do {}>.
+
+See also L</continue> for an illustration of how L</last>, C<next>, and
+L</redo> work.
+
+See also L<perlsyn>.
 
 =item no Module LIST
 
@@ -2179,7 +2330,8 @@ you want both read and write access to the file; thus C<'+E<lt>'> is almost
 always preferred for read/write updates--the C<'+E<gt>'> mode would clobber the
 file first.  You can't usually use either read-write mode for updating
 textfiles, since they have variable length records.  See the B<-i>
-switch in L<perlrun> for a better approach.
+switch in L<perlrun> for a better approach.  The file is created with
+permissions of C<0666> modified by the process' C<umask> value.
 
 The prefix and the filename may be separated with spaces.
 These various prefixes correspond to the fopen(3) modes of C<'r'>, C<'r+'>, C<'w'>,
@@ -2318,7 +2470,9 @@ See L<perlipc/"Safe Pipe Opens"> for more examples of this.
 
 NOTE: On any operation that may do a fork, any unflushed buffers remain
 unflushed in both processes, which means you may need to set C<$|> to
-avoid duplicate output.
+avoid duplicate output.  On systems that support a close-on-exec flag on
+files, the flag will be set for the newly opened file descriptor as
+determined by the value of $^F.  See L<perlvar/$^F>.
 
 Closing any piped filehandle causes the parent process to wait for the
 child to finish, and returns the status value in C<$?>.
@@ -2380,7 +2534,7 @@ DIRHANDLEs have their own namespace separate from FILEHANDLEs.
 
 =item ord
 
-Returns the numeric ascii value of the first character of EXPR.  If
+Returns the numeric (ASCII or Unicode) value of the first character of EXPR.  If
 EXPR is omitted, uses C<$_>.  For the reverse, see L</chr>.
 
 =item pack TEMPLATE,LIST
@@ -2398,7 +2552,7 @@ follows:
     H	A hex string (high nybble first).
 
     c	A signed char value.
-    C	An unsigned char value.
+    C	An unsigned char value.  Only does bytes.  See U for Unicode.
 
     s	A signed short value.
     S	An unsigned short value.
@@ -2424,6 +2578,12 @@ follows:
 	  (These 'shorts' and 'longs' are _exactly_ 16 bits and
 	   _exactly_ 32 bits, respectively.)
 
+    q	A signed quad (64-bit) value.
+    Q	An unsigned quad value.
+	  (Available only if your system supports 64-bit integer values
+	   _and_ if Perl has been compiled to support those.
+           Causes a fatal error otherwise.)
+
     f	A single-precision float in the native format.
     d	A double-precision float in the native format.
 
@@ -2431,6 +2591,8 @@ follows:
     P	A pointer to a structure (fixed-length string).
 
     u	A uuencoded string.
+    U	A Unicode character number.  Encodes to UTF-8 internally.
+	Works even if C<use utf8> is not in effect.
 
     w	A BER compressed integer.  Its bytes represent an unsigned
 	integer in base 128, most significant digit first, with as
@@ -2468,10 +2630,12 @@ C<unpack("f", pack("f", $foo)>) will not in general equal C<$foo>).
 
 Examples:
 
-    $foo = pack("cccc",65,66,67,68);
+    $foo = pack("CCCC",65,66,67,68);
     # foo eq "ABCD"
-    $foo = pack("c4",65,66,67,68);
+    $foo = pack("C4",65,66,67,68);
     # same thing
+    $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9);
+    # same thing with Unicode circled letters
 
     $foo = pack("ccxxcc",65,66,67,68);
     # foo eq "AB\0\0CD"
@@ -2534,6 +2698,10 @@ after each command, depending on the application.
 See L<IPC::Open2>, L<IPC::Open3>, and L<perlipc/"Bidirectional Communication">
 for examples of such things.
 
+On systems that support a close-on-exec flag on files, the flag will be set
+for the newly opened file descriptors as determined by the value of $^F.
+See L<perlvar/$^F>.
+
 =item pop ARRAY
 
 =item pop
@@ -2636,7 +2804,7 @@ but is more efficient.  Returns the new number of elements in the array.
 
 =item qw/STRING/
 
-Generalized quotes.  See L<perlop>.
+Generalized quotes.  See L<perlop/"Regexp Quote-Like Operators">.
 
 =item quotemeta EXPR
 
@@ -2739,7 +2907,7 @@ See L<perlipc/"UDP: Message Passing"> for examples.
 =item redo
 
 The C<redo> command restarts the loop block without evaluating the
-conditional again.  The C<continue> block, if any, is not executed.  If
+conditional again.  The L</continue> block, if any, is not executed.  If
 the LABEL is omitted, the command refers to the innermost enclosing
 loop.  This command is normally used by programs that want to lie to
 themselves about what was just input:
@@ -2761,9 +2929,14 @@ themselves about what was just input:
 	print;
     }
 
-See also L</continue> for an illustration of how C<last>, C<next>, and
+C<redo> cannot be used to retry a block which returns a value such as
+C<eval {}>, C<sub {}> or C<do {}>.
+
+See also L</continue> for an illustration of how L</last>, L</next>, and
 C<redo> work.
 
+See also L<perlsyn>.
+
 =item ref EXPR
 
 =item ref
@@ -2903,13 +3076,13 @@ will automatically return the value of the last expression evaluated.)
 
 In list context, returns a list value consisting of the elements
 of LIST in the opposite order.  In scalar context, concatenates the
-elements of LIST, and returns a string value consisting of those bytes,
-but in the opposite order.
+elements of LIST, and returns a string value with all the characters
+in the opposite order.
 
     print reverse <>;		# line tac, last line first
 
     undef $/;			# for efficiency of <>
-    print scalar reverse <>;	# byte tac, last line tsrif
+    print scalar reverse <>;	# character tac, last line tsrif
 
 This operator is also handy for inverting a hash, although there are some
 caveats.  If a value is duplicated in the original hash, only one of those
@@ -3588,7 +3761,8 @@ root of C<$_>.
 =item srand
 
 Sets the random number seed for the C<rand()> operator.  If EXPR is
-omitted, uses a semi-random value based on the current time and process
+omitted, uses a semi-random value supplied by the kernel (if it supports
+the F</dev/urandom> device) or based on the current time and process
 ID, among other things.  In versions of Perl prior to 5.004 the default
 seed was just the current C<time()>.  This isn't a particularly good seed,
 so many old programs supply their own seed value (often C<time ^ $$> or
@@ -3828,29 +4002,22 @@ FILENAME, MODE, PERMS.
 
 The possible values and flag bits of the MODE parameter are
 system-dependent; they are available via the standard module C<Fcntl>.
-However, for historical reasons, some values are universal: zero means
-read-only, one means write-only, and two means read/write.
+For historical reasons, some values work on almost every system
+supported by perl: zero means read-only, one means write-only, and two
+means read/write.  We know that these values do I<not> work under
+OS/390 & VM/ESA Unix and on the Macintosh; you probably don't want to
+use them in new code.
 
 If the file named by FILENAME does not exist and the C<open()> call creates
 it (typically because MODE includes the C<O_CREAT> flag), then the value of
 PERMS specifies the permissions of the newly created file.  If you omit
 the PERMS argument to C<sysopen()>, Perl uses the octal value C<0666>.
 These permission values need to be in octal, and are modified by your
-process's current C<umask>.  The C<umask> value is a number representing
-disabled permissions bits--if your C<umask> were C<027> (group can't write;
-others can't read, write, or execute), then passing C<sysopen()> C<0666> would
-create a file with mode C<0640> (C<0666 &~ 027> is C<0640>).
-
-If you find this C<umask()> talk confusing, here's some advice: supply a
-creation mode of C<0666> for regular files and one of C<0777> for directories
-(in C<mkdir()>) and executable files.  This gives users the freedom of
-choice: if they want protected files, they might choose process umasks
-of C<022>, C<027>, or even the particularly antisocial mask of C<077>.  Programs
-should rarely if ever make policy decisions better left to the user.
-The exception to this is when writing files that should be kept private:
-mail files, web browser cookies, I<.rhosts> files, and so on.  In short,
-seldom if ever use C<0644> as argument to C<sysopen()> because that takes
-away the user's option to have a more permissive umask.  Better to omit it.
+process's current C<umask>.
+
+Seldom if ever use C<0644> as argument to C<sysopen()> because that
+takes away the user's option to have a more permissive umask.  Better
+to omit it.  See the perlfunc(1) entry on C<umask> for more on this.
 
 The C<IO::File> module provides a more object-oriented approach, if you're
 into that kind of thing.
@@ -3860,12 +4027,13 @@ into that kind of thing.
 =item sysread FILEHANDLE,SCALAR,LENGTH
 
 Attempts to read LENGTH bytes of data into variable SCALAR from the
-specified FILEHANDLE, using the system call read(2).  It bypasses
-stdio, so mixing this with other kinds of reads, C<print()>, C<write()>,
-C<seek()>, or C<tell()> can cause confusion because stdio usually buffers
-data.  Returns the number of bytes actually read, C<0> at end of file,
-or undef if there was an error.  SCALAR will be grown or shrunk so that
-the last byte actually read is the last byte of the scalar after the read.
+specified FILEHANDLE, using the system call read(2).  It bypasses stdio,
+so mixing this with other kinds of reads, C<print()>, C<write()>,
+C<seek()>, C<tell()>, or C<eof()> can cause confusion because stdio
+usually buffers data.  Returns the number of bytes actually read, C<0>
+at end of file, or undef if there was an error.  SCALAR will be grown or
+shrunk so that the last byte actually read is the last byte of the
+scalar after the read.
 
 An OFFSET may be specified to place the read data at some place in the
 string other than the beginning.  A negative OFFSET specifies
@@ -3878,13 +4046,13 @@ the result of the read is appended.
 
 Sets FILEHANDLE's system position using the system call lseek(2).  It
 bypasses stdio, so mixing this with reads (other than C<sysread()>),
-C<print()>, C<write()>, C<seek()>, or C<tell()> may cause confusion.  FILEHANDLE may
-be an expression whose value gives the name of the filehandle.  The
-values for WHENCE are C<0> to set the new position to POSITION, C<1> to set
-the it to the current position plus POSITION, and C<2> to set it to EOF
-plus POSITION (typically negative).  For WHENCE, you may use the
-constants C<SEEK_SET>, C<SEEK_CUR>, and C<SEEK_END> from either the C<IO::Seekable>
-or the POSIX module.
+C<print()>, C<write()>, C<seek()>, C<tell()>, or C<eof()> may cause
+confusion.  FILEHANDLE may be an expression whose value gives the name
+of the filehandle.  The values for WHENCE are C<0> to set the new
+position to POSITION, C<1> to set the it to the current position plus
+POSITION, and C<2> to set it to EOF plus POSITION (typically negative).
+For WHENCE, you may use the constants C<SEEK_SET>, C<SEEK_CUR>, and
+C<SEEK_END> from either the C<IO::Seekable> or the POSIX module.
 
 Returns the new position, or the undefined value on failure.  A position
 of zero is returned as the string "C<0> but true"; thus C<sysseek()> returns
@@ -3939,14 +4107,17 @@ See L<perlop/"`STRING`"> and L</exec> for details.
 
 =item syswrite FILEHANDLE,SCALAR,LENGTH
 
+=item syswrite FILEHANDLE,SCALAR
+
 Attempts to write LENGTH bytes of data from variable SCALAR to the
-specified FILEHANDLE, using the system call write(2).  It bypasses
+specified FILEHANDLE, using the system call write(2).  If LENGTH is
+not specified, writes whole SCALAR. It bypasses
 stdio, so mixing this with reads (other than C<sysread())>, C<print()>,
-C<write()>, C<seek()>, or C<tell()> may cause confusion because stdio usually
-buffers data.  Returns the number of bytes actually written, or C<undef>
-if there was an error.  If the LENGTH is greater than the available
-data in the SCALAR after the OFFSET, only as much data as is available
-will be written.
+C<write()>, C<seek()>, C<tell()>, or C<eof()> may cause confusion
+because stdio usually buffers data.  Returns the number of bytes
+actually written, or C<undef> if there was an error.  If the LENGTH is
+greater than the available data in the SCALAR after the OFFSET, only as
+much data as is available will be written.
 
 An OFFSET may be specified to write the data from some part of the
 string other than the beginning.  A negative OFFSET specifies writing
@@ -3974,11 +4145,11 @@ This function binds a variable to a package class that will provide the
 implementation for the variable.  VARIABLE is the name of the variable
 to be enchanted.  CLASSNAME is the name of a class implementing objects
 of correct type.  Any additional arguments are passed to the "C<new()>"
-method of the class (meaning C<TIESCALAR>, C<TIEARRAY>, or C<TIEHASH>).
-Typically these are arguments such as might be passed to the C<dbm_open()>
-function of C.  The object returned by the "C<new()>" method is also
-returned by the C<tie()> function, which would be useful if you want to
-access other methods in CLASSNAME.
+method of the class (meaning C<TIESCALAR>, C<TIEHANDLE>, C<TIEARRAY>,
+or C<TIEHASH>).  Typically these are arguments such as might be passed
+to the C<dbm_open()> function of C.  The object returned by the "C<new()>"
+method is also returned by the C<tie()> function, which would be useful
+if you want to access other methods in CLASSNAME.
 
 Note that functions such as C<keys()> and C<values()> may return huge lists
 when used on large objects, like DBM files.  You may prefer to use the
@@ -3995,28 +4166,52 @@ C<each()> function to iterate over such.  Example:
 A class implementing a hash should have the following methods:
 
     TIEHASH classname, LIST
-    DESTROY this
     FETCH this, key
     STORE this, key, value
     DELETE this, key
+    CLEAR this
     EXISTS this, key
     FIRSTKEY this
     NEXTKEY this, lastkey
+    DESTROY this
 
 A class implementing an ordinary array should have the following methods:
 
     TIEARRAY classname, LIST
-    DESTROY this
     FETCH this, key
     STORE this, key, value
-    [others TBD]
+    FETCHSIZE this
+    STORESIZE this, count
+    CLEAR this
+    PUSH this, LIST
+    POP this
+    SHIFT this
+    UNSHIFT this, LIST
+    SPLICE this, offset, length, LIST
+    EXTEND this, count
+    DESTROY this
+
+A class implementing a file handle should have the following methods:
+
+    TIEHANDLE classname, LIST
+    READ this, scalar, length, offset
+    READLINE this
+    GETC this
+    WRITE this, scalar, length, offset
+    PRINT this, LIST
+    PRINTF this, format, LIST
+    CLOSE this
+    DESTROY this
 
 A class implementing a scalar should have the following methods:
 
     TIESCALAR classname, LIST
-    DESTROY this
     FETCH this,
     STORE this, value
+    DESTROY this
+
+Not all methods indicated above need be implemented.  See L<perltie>,
+L<Tie::Hash>, L<Tie::Array>, L<Tie::Scalar> and L<Tie::Handle>.
 
 Unlike C<dbmopen()>, the C<tie()> function will not use or require a module
 for you--you need to do that explicitly yourself.  See L<DB_File>
@@ -4065,6 +4260,8 @@ otherwise.
 Returns an uppercased version of EXPR.  This is the internal function
 implementing the C<\U> escape in double-quoted strings.
 Respects current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>.
+Under Unicode (C<use utf8>) it uses the standard Unicode uppercase mappings.  (It
+does not attempt to do titlecase mapping on initial letters.  See C<ucfirst()> for that.)
 
 If EXPR is omitted, uses C<$_>.
 
@@ -4072,7 +4269,8 @@ If EXPR is omitted, uses C<$_>.
 
 =item ucfirst
 
-Returns the value of EXPR with the first character uppercased.  This is
+Returns the value of EXPR with the first character
+in uppercase (titlecase in Unicode).  This is
 the internal function implementing the C<\u> escape in double-quoted strings.
 Respects current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>.
 
@@ -4085,6 +4283,28 @@ If EXPR is omitted, uses C<$_>.
 Sets the umask for the process to EXPR and returns the previous value.
 If EXPR is omitted, merely returns the current umask.
 
+The Unix permission C<rwxr-x---> is represented as three sets of three
+bits, or three octal digits: C<0750> (the leading 0 indicates octal
+and isn't one of the the digits).  The C<umask> value is such a number
+representing disabled permissions bits.  The permission (or "mode")
+values you pass C<mkdir> or C<sysopen> are modified by your umask, so
+even if you tell C<sysopen> to create a file with permissions C<0777>,
+if your umask is C<0022> then the file will actually be created with
+permissions C<0755>.  If your C<umask> were C<0027> (group can't
+write; others can't read, write, or execute), then passing
+C<sysopen()> C<0666> would create a file with mode C<0640> (C<0666 &~
+027> is C<0640>).
+
+Here's some advice: supply a creation mode of C<0666> for regular
+files (in C<sysopen()>) and one of C<0777> for directories (in
+C<mkdir()>) and executable files.  This gives users the freedom of
+choice: if they want protected files, they might choose process umasks
+of C<022>, C<027>, or even the particularly antisocial mask of C<077>.
+Programs should rarely if ever make policy decisions better left to
+the user.  The exception to this is when writing files that should be
+kept private: mail files, web browser cookies, I<.rhosts> files, and
+so on.
+
 If umask(2) is not implemented on your system and you are trying to
 restrict access for I<yourself> (i.e., (EXPR & 0700) > 0), produces a
 fatal error at run time.  If umask(2) is not implemented and you are
@@ -4119,6 +4339,13 @@ parameter.  Examples:
 
 Note that this is a unary operator, not a list operator.
 
+=item unless (EXPR) BLOCK
+
+The negative counterpart of L</if>.  If the EXPR returns false the
+BLOCK is entered.
+
+See also L<perlsyn>.
+
 =item unlink LIST
 
 =item unlink
@@ -4168,10 +4395,6 @@ The following efficiently counts the number of set bits in a bit vector:
 
     $setbits = unpack("%32b*", $selectmask);
 
-=item untie VARIABLE
-
-Breaks the binding between a variable and a package.  (See C<tie()>.)
-
 =item unshift ARRAY,LIST
 
 Does the opposite of a C<shift()>.  Or the opposite of a C<push()>,
@@ -4184,6 +4407,21 @@ Note the LIST is prepended whole, not one element at a time, so the
 prepended elements stay in the same order.  Use C<reverse()> to do the
 reverse.
 
+=item until (EXPR) BLOCK
+
+=item do BLOCK until (EXPR)
+
+Enter BLOCK until EXPR returns false.  The first form may avoid entering
+the BLOCK, the second form enters the BLOCK at least once.
+
+See L</do>, L</while>, and L</for>.
+
+See also L<perlsyn>.
+
+=item untie VARIABLE
+
+Breaks the binding between a variable and a package.  (See C<tie()>.)
+
 =item use Module LIST
 
 =item use Module
@@ -4275,8 +4513,11 @@ command if the files already exist:
 
 Returns a list consisting of all the values of the named hash.  (In a
 scalar context, returns the number of values.)  The values are
-returned in an apparently random order, but it is the same order as
-either the C<keys()> or C<each()> function would produce on the same hash.
+returned in an apparently random order.  The actual random order is
+subject to change in future versions of perl, but it is guaranteed to
+be the same order as either the C<keys()> or C<each()> function would
+produce on the same (unmodified) hash.
+
 As a side effect, it resets HASH's iterator.  See also C<keys()>, C<each()>,
 and C<sort()>.
 
@@ -4324,7 +4565,8 @@ If you know the exact length in bits, it can be used in place of the C<*>.
 
 Waits for a child process to terminate and returns the pid of the
 deceased process, or C<-1> if there are no child processes.  The status is
-returned in C<$?>.
+returned in C<$?>.  Note that a return value of C<-1> could mean that
+child processes are being automatically reaped, as described in L<perlipc>.
 
 =item waitpid PID,FLAGS
 
@@ -4343,7 +4585,8 @@ FLAGS of C<0> is implemented everywhere.  (Perl emulates the system call
 by remembering the status values of processes that have exited but have
 not been harvested by the Perl script yet.)
 
-See L<perlipc> for other examples.
+Note that a return value of C<-1> could mean that child processes are being
+automatically reaped.  See L<perlipc> for details, and for other examples.
 
 =item wantarray
 
@@ -4398,6 +4641,15 @@ warnings (even the so-called mandatory ones).  An example:
 See L<perlvar> for details on setting C<%SIG> entries, and for more
 examples.
 
+=item while (EXPR) BLOCK
+
+=item do BLOCK while (EXPR)
+
+Enter BLOCK while EXPR is true.  The first form may avoid entering the
+BLOCK, the second form enters the BLOCK at least once.
+
+See also L<perlsyn>, L</for>, L</until>, and L</continue>.
+
 =item write FILEHANDLE
 
 =item write EXPR