X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=89123011ca0dc372d0409050ada19aad58b585ef;hb=2975d2266cd5007c9c9ffad3ff137d0cd9a1bceb;hp=ad20884a8b823688ec1e26191fb47518b0869e53;hpb=4a4eefd0ee0da7b6a2b5b0d021684bca80971b79;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index ad20884..8912301 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -91,7 +91,7 @@ functions, like some keywords and named operators)
 arranged by category.  Some functions appear in more
 than one place.
 
-=over
+=over 4
 
 =item Functions for SCALARs or strings
 
@@ -146,11 +146,11 @@ C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>
 
 =item Keywords related to scoping
 
-C<caller>, C<import>, C<local>, C<my>, C<package>, C<use>
+C<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<use>
 
 =item Miscellaneous functions
 
-C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<reset>,
+C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>, C<reset>,
 C<scalar>, C<undef>, C<wantarray>
 
 =item Functions for processes and process groups
@@ -172,7 +172,7 @@ C<untie>, C<use>
 
 C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
 C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
-C<socket>, C<socketpair>
+C<sockatmark>, C<socket>, C<socketpair>
 
 =item System V interprocess communication functions
 
@@ -200,8 +200,8 @@ C<gmtime>, C<localtime>, C<time>, C<times>
 =item Functions new in perl5
 
 C<abs>, C<bless>, C<chomp>, C<chr>, C<exists>, C<formline>, C<glob>,
-C<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<prototype>, C<qx>,
-C<qw>, C<readline>, C<readpipe>, C<ref>, C<sub*>, C<sysopen>, C<tie>,
+C<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<our>, C<prototype>,
+C<qx>, C<qw>, C<readline>, C<readpipe>, C<ref>, C<sub*>, C<sysopen>, C<tie>,
 C<tied>, C<uc>, C<ucfirst>, C<untie>, C<use>
 
 * - C<sub> was a keyword in perl4, but in perl5 it is an
@@ -234,8 +234,9 @@ C<msgsnd>, C<open>, C<pipe>, C<readlink>, C<rename>, 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<socket>, C<socketpair>, C<stat>, C<symlink>, C<syscall>,
-C<sysopen>, C<system>, C<times>, C<truncate>, C<umask>, C<unlink>,
+C<shmwrite>, C<sockatmark>, C<socket>, C<socketpair>,
+C<stat>, C<symlink>, C<syscall>, C<sysopen>, C<system>,
+C<times>, C<truncate>, C<umask>, C<unlink>,
 C<utime>, C<wait>, C<waitpid>
 
 For more information about the portability of these functions, see
@@ -274,8 +275,8 @@ X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
     -O	File is owned by real uid.
 
     -e	File exists.
-    -z	File has zero size.
-    -s	File has nonzero size (returns size).
+    -z	File has zero size (is empty).
+    -s	File has nonzero size (returns size in bytes).
 
     -f	File is a plain file.
     -d	File is a directory.
@@ -300,7 +301,7 @@ X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
 Example:
 
     while (<>) {
-	chop;
+	chomp;
 	next unless -f $_;	# ignore specials
 	#...
     }
@@ -397,8 +398,9 @@ on the previous timer.
 For delays of finer granularity than one second, you may use Perl's
 four-argument version of select() leaving the first three arguments
 undefined, or you might be able to use the C<syscall> interface to
-access setitimer(2) if your system supports it.  The Time::HiRes module
-from CPAN may also prove useful.
+access setitimer(2) if your system supports it.  The Time::HiRes
+module (from CPAN, and starting from Perl 5.8 part of the standard
+distribution) may also prove useful.
 
 It is usually a mistake to intermix C<alarm> and C<sleep> calls.
 (C<sleep> may be internally implemented in your system with C<alarm>)
@@ -473,22 +475,22 @@ representation matches the internal representation, but on some
 platforms the external representation of C<\n> is made up of more than
 one character.
 
-Mac OS and all variants of Unix use a single character to end each line
-in the external representation of text (even though that single
-character is not necessarily the same across these platforms).
-Consequently binmode() has no effect on these operating systems.  In
-other systems like VMS, MS-DOS and the various flavors of MS-Windows
-your program sees a C<\n> as a simple C<\cJ>, but what's stored in text
-files are the two characters C<\cM\cJ>.  That means that, if you don't
-use binmode() on these systems, C<\cM\cJ> sequences on disk will be
-converted to C<\n> on input, and any C<\n> in your program will be
-converted back to C<\cM\cJ> on output.  This is what you want for text
-files, but it can be disastrous for binary files.
+Mac OS, all variants of Unix, and Stream_LF files on VMS use a single
+character to end each line in the external representation of text (even
+though that single character is CARRIAGE RETURN on Mac OS and LINE FEED
+on Unix and most VMS files).  Consequently binmode() has no effect on
+these operating systems.  In other systems like OS/2, DOS and the various
+flavors of MS-Windows your program sees a C<\n> as a simple C<\cJ>, but
+what's stored in text files are the two characters C<\cM\cJ>.  That means
+that, if you don't use binmode() on these systems, C<\cM\cJ> sequences on
+disk will be converted to C<\n> on input, and any C<\n> in your program
+will be converted back to C<\cM\cJ> on output.  This is what you want for
+text files, but it can be disastrous for binary files.
 
 Another consequence of using binmode() (on some systems) is that
 special end-of-file markers will be seen as part of the data stream.
 For systems from the Microsoft family this means that if your binary
-data contains C<\cZ>, the I/O subsystem will ragard it as the end of
+data contains C<\cZ>, the I/O subsystem will regard it as the end of
 the file, unless you use binmode().
 
 binmode() is not only important for readline() and print() operations,
@@ -539,9 +541,10 @@ Here $subroutine may be C<(eval)> if the frame is not a subroutine
 call, but an C<eval>.  In such a case additional elements $evaltext and
 C<$is_require> are set: C<$is_require> is true if the frame is created by a
 C<require> or C<use> statement, $evaltext contains the text of the
-C<eval EXPR> statement.  In particular, for a C<eval BLOCK> statement,
+C<eval EXPR> statement.  In particular, for an C<eval BLOCK> statement,
 $filename is C<(eval)>, but $evaltext is undefined.  (Note also that
 each C<use> statement creates a C<require> frame inside an C<eval EXPR>)
+frame.  C<$hasargs> is true if a new instance of C<@_> was set up for the
 frame.  C<$hints> and C<$bitmask> contain pragmatic hints that the caller
 was compiled with.  The C<$hints> and C<$bitmask> values are subject to
 change between versions of Perl, and are not meant for external use.
@@ -553,7 +556,7 @@ arguments with which the subroutine was invoked.
 Be aware that the optimizer might have optimized call frames away before
 C<caller> had a chance to get the information.  That means that C<caller(N)>
 might not return information about the call frame you expect it do, for
-C<< N > 1 >>.  In particular, C<@DB::args> might have information from the 
+C<< N > 1 >>.  In particular, C<@DB::args> might have information from the
 previous time C<caller> was called.
 
 =item chdir EXPR
@@ -602,7 +605,7 @@ that the final record may be missing its newline.  When in paragraph
 mode (C<$/ = "">), it removes all trailing newlines from the string.
 When in slurp mode (C<$/ = undef>) or fixed-length record mode (C<$/> is
 a reference to an integer or the like, see L<perlvar>) chomp() won't
-remove anything.  
+remove anything.
 If VARIABLE is omitted, it chomps C<$_>.  Example:
 
     while (<>) {
@@ -611,6 +614,8 @@ If VARIABLE is omitted, it chomps C<$_>.  Example:
 	# ...
     }
 
+If VARIABLE is a hash, it chomps the hash's values, but not its keys.
+
 You can actually chomp anything that's an lvalue, including an assignment:
 
     chomp($cwd = `pwd`);
@@ -626,21 +631,11 @@ characters removed is returned.
 =item chop
 
 Chops off the last character of a string and returns the character
-chopped.  It's used primarily to remove the newline from the end of an
-input record, but is much more efficient than C<s/\n//> because it neither
+chopped.  It is much more efficient than C<s/.$//s> because it neither
 scans nor copies the string.  If VARIABLE is omitted, chops C<$_>.
-Example:
-
-    while (<>) {
-	chop;	# avoid \n on last field
-	@array = split(/:/);
-	#...
-    }
+If VARIABLE is a hash, it chops the hash's values, but not its keys.
 
-You can actually chop anything that's an lvalue, including an assignment:
-
-    chop($cwd = `pwd`);
-    chop($answer = <STDIN>);
+You can actually chop anything that's an lvalue, including an assignment.
 
 If you chop a list, each element is chopped.  Only the value of the
 last C<chop> is returned.
@@ -687,8 +682,11 @@ On POSIX systems, you can detect this condition this way:
 
 Returns the character represented by that NUMBER in the character set.
 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>.  
+chr(0x263a) is a Unicode smiley face. Within the scope of C<use utf8>,
+characters higher than 127 are encoded in Unicode; if you don't want
+this, temporarily C<use bytes> or use C<pack("C*",...)>
+
+For the reverse, use L</ord>.
 See L<utf8> for more about Unicode.
 
 If NUMBER is omitted, uses C<$_>.
@@ -721,9 +719,9 @@ counter (C<$.>), while the implicit close done by C<open> does not.
 If the file handle came from a piped open C<close> will additionally
 return false if one of the other system calls involved fails or if the
 program exits with non-zero status.  (If the only problem was that the
-program exited non-zero C<$!> will be set to C<0>.)  Closing a pipe 
+program exited non-zero C<$!> will be set to C<0>.)  Closing a pipe
 also waits for the process executing on the pipe to complete, in case you
-want to look at the output of the pipe afterwards, and 
+want to look at the output of the pipe afterwards, and
 implicitly puts the exit status value of that command into C<$?>.
 
 Prematurely closing the read end of a pipe (i.e. before the process
@@ -791,6 +789,8 @@ to check the condition at the top of the loop.
 
 =item cos EXPR
 
+=item cos
+
 Returns the cosine of EXPR (expressed in radians).  If EXPR is omitted,
 takes cosine of C<$_>.
 
@@ -913,7 +913,10 @@ element to return happens to be C<undef>.
 
 You may also use C<defined(&func)> to check whether subroutine C<&func>
 has ever been defined.  The return value is unaffected by any forward
-declarations of C<&foo>.
+declarations of C<&foo>.  Note that a subroutine which is not defined
+may still be callable: its package may have an C<AUTOLOAD> method that
+makes it spring into existence the first time that it is called -- see
+L<perlsub>.
 
 Use of C<defined> on aggregates (hashes and arrays) is deprecated.  It
 used to report whether memory for that aggregate has ever been
@@ -958,7 +961,7 @@ See also L</undef>, L</exists>, L</ref>.
 Given an expression that specifies a hash element, array element, hash slice,
 or array slice, deletes the specified element(s) from the hash or array.
 In the case of an array, if the array elements happen to be at the end,
-the size of the array will shrink to the highest element that tests 
+the size of the array will shrink to the highest element that tests
 true for exists() (or 0 if no such element exists).
 
 Returns each element so deleted or the undefined value if there was no such
@@ -1055,7 +1058,7 @@ If C<$@> is empty then the string C<"Died"> is used.
 die() can also be called with a reference argument.  If this happens to be
 trapped within an eval(), $@ contains the reference.  This behavior permits
 a more elaborate exception handling implementation using objects that
-maintain arbitary state about the nature of the exception.  Such a scheme
+maintain arbitrary state about the nature of the exception.  Such a scheme
 is sometimes preferable to matching particular string values of $@ using
 regular expressions.  Here's an example:
 
@@ -1088,7 +1091,7 @@ nothing in such situations, put
 
 as the first line of the handler (see L<perlvar/$^S>).  Because
 this promotes strange action at a distance, this counterintuitive
-behavior may be fixed in a future release.  
+behavior may be fixed in a future release.
 
 =item do BLOCK
 
@@ -1115,7 +1118,7 @@ from a Perl subroutine library.
 
 is just like
 
-    scalar eval `cat stat.pl`;
+    eval `cat stat.pl`;
 
 except that it's more efficient and concise, keeps track of the current
 filename for error messages, searches the @INC libraries, and updates
@@ -1138,9 +1141,9 @@ and raise an exception if there's a problem.
 You might like to use C<do> to read in a program configuration
 file.  Manual error checking can be done this way:
 
-    # read in config files: system first, then user 
+    # read in config files: system first, then user
     for $file ("/share/prog/defaults.rc",
-               "$ENV{HOME}/.someprogrc") 
+               "$ENV{HOME}/.someprogrc")
    {
 	unless ($return = do $file) {
 	    warn "couldn't parse $file: $@" if $@;
@@ -1165,7 +1168,7 @@ If C<LABEL> is omitted, restarts the program from the top.
 
 B<WARNING>: Any files opened at the time of the dump will I<not>
 be open any more when the program is reincarnated, with possible
-resulting confusion on the part of Perl.  
+resulting confusion on the part of Perl.
 
 This function is now largely obsolete, partly because it's very
 hard to convert a core file into an executable, and because the
@@ -1177,13 +1180,13 @@ generating bytecode or native C code as described in L<perlcc>.  If
 you're just trying to accelerate a CGI script, consider using the
 C<mod_perl> extension to B<Apache>, or the CPAN module, Fast::CGI.
 You might also consider autoloading or selfloading, which at least
-make your program I<appear> to run faster.  
+make your program I<appear> to run faster.
 
 =item each HASH
 
 When called in list context, returns a 2-element list consisting of the
 key and value for the next element of a hash, so that you can iterate over
-it.  When called in scalar context, returns the key for only the "next"
+it.  When called in scalar context, returns only the key for the next
 element in the hash.
 
 Entries are returned in an apparently random order.  The actual random
@@ -1198,7 +1201,14 @@ 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
 reading all the elements from the hash, or by evaluating C<keys HASH> or
 C<values HASH>.  If you add or delete elements of a hash while you're
-iterating over it, you may get entries skipped or duplicated, so don't.
+iterating over it, you may get entries skipped or duplicated, so
+don't.  Exception: It is always safe to delete the item most recently
+returned by C<each()>, which means that the following code will work:
+
+        while (($key, $value) = each %hash) {
+          print $key, "\n";
+          delete $hash{$key};   # This is safe
+        }
 
 The following prints out your environment like the printenv(1) program,
 only in a different order:
@@ -1237,7 +1247,7 @@ last file.  Examples:
 
     # reset line numbering on each input file
     while (<>) {
-	next if /^\s*#/;	# skip comments 
+	next if /^\s*#/;	# skip comments
 	print "$.\t$_";
     } continue {
 	close ARGV  if eof;	# Not eof()!
@@ -1264,11 +1274,11 @@ there was an error.
 In the first form, the return value of EXPR is parsed and executed as if it
 were a little Perl program.  The value of the expression (which is itself
 determined within scalar context) is first parsed, and if there weren't any
-errors, executed in the context of the current Perl program, so that any
-variable settings or subroutine and format definitions remain afterwards.
-Note that the value is parsed every time the eval executes.  If EXPR is
-omitted, evaluates C<$_>.  This form is typically used to delay parsing
-and subsequent execution of the text of EXPR until run time.
+errors, executed in the lexical context of the current Perl program, so
+that any variable settings or subroutine and format definitions remain
+afterwards.  Note that the value is parsed every time the eval executes.
+If EXPR is omitted, evaluates C<$_>.  This form is typically used to
+delay parsing and subsequent execution of the text of EXPR until run time.
 
 In the second form, the code within the BLOCK is parsed only once--at the
 same time the code surrounding the eval itself was parsed--and executed
@@ -1391,7 +1401,7 @@ the argument is checked for shell metacharacters, and if there are any,
 the entire argument is passed to the system's command shell for parsing
 (this is C</bin/sh -c> on Unix platforms, but varies on other platforms).
 If there are no shell metacharacters in the argument, it is split into
-words and passed directly to C<execvp>, which is more efficient.  
+words and passed directly to C<execvp>, which is more efficient.
 Examples:
 
     exec '/bin/echo', 'Your arguments are: ', @ARGV;
@@ -1462,7 +1472,10 @@ it exists, but the reverse doesn't necessarily hold true.
 Given an expression that specifies the name of a subroutine,
 returns true if the specified subroutine has ever been declared, even
 if it is undefined.  Mentioning a subroutine name for exists or defined
-does not count as declaring it.
+does not count as declaring it.  Note that a subroutine which does not
+exist may still be callable: its package may have an C<AUTOLOAD>
+method that makes it spring into existence the first time that it is
+called -- see L<perlsub>.
 
     print "Exists\n" 	if exists &subroutine;
     print "Defined\n" 	if defined &subroutine;
@@ -1530,7 +1543,7 @@ See L<perlmod> for details.
 
 =item exp
 
-Returns I<e> (the natural logarithm base) to the power of EXPR.  
+Returns I<e> (the natural logarithm base) to the power of EXPR.
 If EXPR is omitted, gives C<exp($_)>.
 
 =item fcntl FILEHANDLE,FUNCTION,SCALAR
@@ -1540,7 +1553,7 @@ Implements the fcntl(2) function.  You'll probably have to say
     use Fcntl;
 
 first to get the correct constant definitions.  Argument processing and
-value return works just like C<ioctl> below.  
+value return works just like C<ioctl> below.
 For example:
 
     use Fcntl;
@@ -1565,12 +1578,16 @@ bitmaps for C<select> and low-level POSIX tty-handling operations.
 If FILEHANDLE is an expression, the value is taken as an indirect
 filehandle, generally its name.
 
-You can use this to find out whether two handles refer to the 
+You can use this to find out whether two handles refer to the
 same underlying descriptor:
 
     if (fileno(THIS) == fileno(THAT)) {
 	print "THIS and THAT are dups\n";
-    } 
+    }
+
+(Filehandles connected to memory objects via new features of C<open> may
+return undefined even though they are open.)
+
 
 =item flock FILEHANDLE,OPERATION
 
@@ -1859,6 +1876,14 @@ various get routines are as follows:
 
 (If the entry doesn't exist you get a null list.)
 
+The exact meaning of the $gcos field varies but it usually contains
+the real name of the user (as opposed to the login name) and other
+information pertaining to the user.  Beware, however, that in many
+system users are able to change this information and therefore it
+cannot be trusted and therefore the $gcos is tainted (see
+L<perlsec>).  The $passwd and $shell, user's encrypted password and
+login shell, are also tainted, because of the same reason.
+
 In scalar context, you get the name, unless the function was a
 lookup by name, in which case you get the other thing, whatever it is.
 (If the entry doesn't exist you get the undefined value.)  For example:
@@ -1871,26 +1896,27 @@ lookup by name, in which case you get the other thing, whatever it is.
     $name  = getgrent();
     #etc.
 
-In I<getpw*()> the fields $quota, $comment, and $expire are
-special cases in the sense that in many systems they are unsupported.
-If the $quota is unsupported, it is an empty scalar.  If it is
-supported, it usually encodes the disk quota.  If the $comment
-field is unsupported, it is an empty scalar.  If it is supported it
-usually encodes some administrative comment about the user.  In some
-systems the $quota field may be $change or $age, fields that have
-to do with password aging.  In some systems the $comment field may
-be $class.  The $expire field, if present, encodes the expiration
-period of the account or the password.  For the availability and the
-exact meaning of these fields in your system, please consult your
-getpwnam(3) documentation and your F<pwd.h> file.  You can also find
-out from within Perl what your $quota and $comment fields mean
-and whether you have the $expire field by using the C<Config> module
-and the values C<d_pwquota>, C<d_pwage>, C<d_pwchange>, C<d_pwcomment>,
-and C<d_pwexpire>.  Shadow password files are only supported if your
-vendor has implemented them in the intuitive fashion that calling the
-regular C library routines gets the shadow versions if you're running
-under privilege.  Those that incorrectly implement a separate library
-call are not supported.
+In I<getpw*()> the fields $quota, $comment, and $expire are special
+cases in the sense that in many systems they are unsupported.  If the
+$quota is unsupported, it is an empty scalar.  If it is supported, it
+usually encodes the disk quota.  If the $comment field is unsupported,
+it is an empty scalar.  If it is supported it usually encodes some
+administrative comment about the user.  In some systems the $quota
+field may be $change or $age, fields that have to do with password
+aging.  In some systems the $comment field may be $class.  The $expire
+field, if present, encodes the expiration period of the account or the
+password.  For the availability and the exact meaning of these fields
+in your system, please consult your getpwnam(3) documentation and your
+F<pwd.h> file.  You can also find out from within Perl what your
+$quota and $comment fields mean and whether you have the $expire field
+by using the C<Config> module and the values C<d_pwquota>, C<d_pwage>,
+C<d_pwchange>, C<d_pwcomment>, and C<d_pwexpire>.  Shadow password
+files are only supported if your vendor has implemented them in the
+intuitive fashion that calling the regular C library routines gets the
+shadow versions if you're running under privilege or if there exists
+the shadow(3) functions as found in System V ( this includes Solaris
+and Linux.)  Those systems which implement a proprietary shadow password
+facility are unlikely to be supported.
 
 The $members value returned by I<getgr*()> is a space separated list of
 the login names of the members of the group.
@@ -1925,8 +1951,8 @@ for each field.  For example:
    use User::pwent;
    $is_his = (stat($filename)->uid == pwent($whoever)->uid);
 
-Even though it looks like they're the same method calls (uid), 
-they aren't, because a C<File::stat> object is different from 
+Even though it looks like they're the same method calls (uid),
+they aren't, because a C<File::stat> object is different from
 a C<User::pwent> object.
 
 =item getsockname SOCKET
@@ -1938,7 +1964,7 @@ IPs that the connection might have come in on.
     use Socket;
     $mysockaddr = getsockname(SOCK);
     ($port, $myaddr) = sockaddr_in($mysockaddr);
-    printf "Connect to %s [%s]\n", 
+    printf "Connect to %s [%s]\n",
        scalar gethostbyaddr($myaddr, AF_INET),
        inet_ntoa($myaddr);
 
@@ -1965,7 +1991,7 @@ Converts a time as returned by the time function to a 8-element list
 with the time localized for the standard Greenwich time zone.
 Typically used as follows:
 
-    #  0    1    2     3     4    5     6     7  
+    #  0    1    2     3     4    5     6     7
     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday) =
 					    gmtime(time);
 
@@ -1976,7 +2002,7 @@ itself, in the range C<0..11> with 0 indicating January and 11
 indicating December.  $year is the number of years since 1900.  That
 is, $year is C<123> in year 2023.  $wday is the day of the week, with
 0 indicating Sunday and 3 indicating Wednesday.  $yday is the day of
-the year, in the range C<1..365> (or C<1..366> in leap years.)  
+the year, in the range C<0..364> (or C<0..365> in leap years.)
 
 Note that the $year element is I<not> simply the last two digits of
 the year.  If you assume it is, then you create non-Y2K-compliant
@@ -2068,9 +2094,9 @@ or equivalently,
 
     @foo = grep {!/^#/} @bar;    # weed out comments
 
-Note that, because C<$_> is a reference into the list value, it can
-be used to modify the elements of the array.  While this is useful and
-supported, it can cause bizarre results if the LIST is not a named array.
+Note that C<$_> is an alias to the list value, so it can be used to
+modify the elements of the LIST.  While this is useful and supported,
+it can cause bizarre results if the elements of LIST are not variables.
 Similarly, grep returns aliases into the original list, much as a for
 loop's index variable aliases the list elements.  That is, modifying an
 element of a list returned by grep (for example, in a C<foreach>, C<map>
@@ -2098,7 +2124,7 @@ integer overflow trigger a warning.
 There is no builtin C<import> function.  It is just an ordinary
 method (subroutine) defined (or inherited) by modules that wish to export
 names to another module.  The C<use> function calls the C<import> method
-for the package used.  See also L</use()>, L<perlmod>, and L<Exporter>.
+for the package used.  See also L</use>, L<perlmod>, and L<Exporter>.
 
 =item index STR,SUBSTR,POSITION
 
@@ -2142,7 +2168,7 @@ has no string value but does have a numeric value, that value will be
 passed rather than a pointer to the string value.  To guarantee this to be
 true, add a C<0> to the scalar before using it.)  The C<pack> and C<unpack>
 functions may be needed to manipulate the values of structures used by
-C<ioctl>.  
+C<ioctl>.
 
 The return value of C<ioctl> (and C<fcntl>) is as follows:
 
@@ -2197,7 +2223,7 @@ Here is yet another way to print your environment:
 
     @keys = keys %ENV;
     @values = values %ENV;
-    while (@keys) { 
+    while (@keys) {
 	print pop(@keys), '=', pop(@values), "\n";
     }
 
@@ -2207,6 +2233,9 @@ or how about sorted by key:
 	print $key, '=', $ENV{$key}, "\n";
     }
 
+The returned values are copies of the original keys in the hash, so
+modifying them will not affect the original hash.  Compare L</values>.
+
 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:
 
@@ -2302,25 +2331,26 @@ If EXPR is omitted, uses C<$_>.
 =item length
 
 Returns the length in characters of the value of EXPR.  If EXPR is
-omitted, returns length of C<$_>.  Note that this cannot be used on 
+omitted, returns length of C<$_>.  Note that this cannot be used on
 an entire array or hash to find out how many elements these have.
 For that, use C<scalar @array> and C<scalar keys %hash> respectively.
 
 =item link OLDFILE,NEWFILE
 
 Creates a new filename linked to the old filename.  Returns true for
-success, false otherwise. 
+success, false otherwise.
 
 =item listen SOCKET,QUEUESIZE
 
 Does the same thing that the listen system call does.  Returns true if
-it succeeded, false otherwise.  See the example in L<perlipc/"Sockets: Client/Server Communication">.
+it succeeded, false otherwise.  See the example in
+L<perlipc/"Sockets: Client/Server Communication">.
 
 =item local EXPR
 
 You really probably want to be using C<my> instead, because C<local> isn't
-what most people think of as "local".  See L<perlsub/"Private Variables
-via my()"> for details.
+what most people think of as "local".  See
+L<perlsub/"Private Variables via my()"> for details.
 
 A local modifies the listed variables to be local to the enclosing
 block, file, or eval.  If more than one value is listed, the list must
@@ -2344,7 +2374,7 @@ itself, in the range C<0..11> with 0 indicating January and 11
 indicating December.  $year is the number of years since 1900.  That
 is, $year is C<123> in year 2023.  $wday is the day of the week, with
 0 indicating Sunday and 3 indicating Wednesday.  $yday is the day of
-the year, in the range C<1..365> (or C<1..366> in leap years.)  $isdst
+the year, in the range C<0..364> (or C<0..365> in leap years.)  $isdst
 is true if the specified time occurs during daylight savings time,
 false otherwise.
 
@@ -2404,12 +2434,10 @@ divided by the natural log of N.  For example:
     sub log10 {
 	my $n = shift;
 	return log($n)/log(10);
-    } 
+    }
 
 See also L</exp> for the inverse operation.
 
-=item lstat FILEHANDLE
-
 =item lstat EXPR
 
 =item lstat
@@ -2449,13 +2477,36 @@ is just a funny way to write
 	$hash{getkey($_)} = $_;
     }
 
-Note that, because C<$_> is a reference into the list value, it can
-be used to modify the elements of the array.  While this is useful and
-supported, it can cause bizarre results if the LIST is not a named array.
+Note that C<$_> is an alias to the list value, so it can be used to
+modify the elements of the LIST.  While this is useful and supported,
+it can cause bizarre results if the elements of LIST are not variables.
 Using a regular C<foreach> loop for this purpose would be clearer in
 most cases.  See also L</grep> for an array composed of those items of
 the original list for which the BLOCK or EXPR evaluates to true.
 
+C<{> starts both hash references and blocks, so C<map { ...> could be either
+the start of map BLOCK LIST or map EXPR, LIST. Because perl doesn't look
+ahead for the closing C<}> it has to take a guess at which its dealing with
+based what it finds just after the C<{>. Usually it gets it right, but if it
+doesn't it won't realize something is wrong until it gets to the C<}> and
+encounters the missing (or unexpected) comma. The syntax error will be
+reported close to the C<}> but you'll need to change something near the C<{>
+such as using a unary C<+> to give perl some help:
+
+    %hash = map {  "\L$_", 1  } @array  # perl guesses EXPR.  wrong
+    %hash = map { +"\L$_", 1  } @array  # perl guesses BLOCK. right
+    %hash = map { ("\L$_", 1) } @array  # this also works
+    %hash = map {  lc($_), 1  } @array  # as does this.
+    %hash = map +( lc($_), 1 ), @array  # this is EXPR and works!
+
+    %hash = map  ( lc($_), 1 ), @array  # evaluates to (1, @array)
+
+or to force an anon hash constructor use C<+{>
+
+   @hashes = map +{ lc($_), 1 }, @array # EXPR, so needs , at end
+
+and you get list of anonymous hashes each with only 1 entry.
+
 =item mkdir FILENAME,MASK
 
 =item mkdir FILENAME
@@ -2472,6 +2523,11 @@ 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 MASK in more detail.
 
+Note that according to the POSIX 1003.1-1996 the FILENAME may have any
+number of trailing slashes.  Some operating and filesystems do not get
+this right, so Perl automatically removes all trailing slashes to keep
+everyone happy.
+
 =item msgctl ID,CMD,ARG
 
 Calls the System V IPC function msgctl(2).  You'll probably have to say
@@ -2482,30 +2538,34 @@ first to get the correct constant definitions.  If CMD is C<IPC_STAT>,
 then ARG must be a variable which will hold the returned C<msqid_ds>
 structure.  Returns like C<ioctl>: the undefined value for error,
 C<"0 but true"> for zero, or the actual return value otherwise.  See also
-C<IPC::SysV> and C<IPC::Semaphore> documentation.
+L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::Semaphore> documentation.
 
 =item msgget KEY,FLAGS
 
 Calls the System V IPC function msgget(2).  Returns the message queue
-id, or the undefined value if there is an error.  See also C<IPC::SysV>
-and C<IPC::Msg> documentation.
-
-=item msgsnd ID,MSG,FLAGS
-
-Calls the System V IPC function msgsnd to send the message MSG to the
-message queue ID.  MSG must begin with the native long integer message
-type, which may be created with C<pack("l!", $type)>.  Returns true if
-successful, or false if there is an error.  See also C<IPC::SysV> and
-C<IPC::SysV::Msg> documentation.
+id, or the undefined value if there is an error.  See also
+L<perlipc/"SysV IPC"> and C<IPC::SysV> and C<IPC::Msg> documentation.
 
 =item msgrcv ID,VAR,SIZE,TYPE,FLAGS
 
 Calls the System V IPC function msgrcv to receive a message from
 message queue ID into variable VAR with a maximum message size of
-SIZE.  Note that if a message is received, the message type will be
-the first thing in VAR, and the maximum length of VAR is SIZE plus the
-size of the message type.  Returns true if successful, or false if
-there is an error.  See also C<IPC::SysV> and C<IPC::SysV::Msg> documentation.
+SIZE.  Note that when a message is received, the message type as a
+native long integer will be the first thing in VAR, followed by the
+actual message.  This packing may be opened with C<unpack("l! a*")>.
+Taints the variable.  Returns true if successful, or false if there is
+an error.  See also L<perlipc/"SysV IPC">, C<IPC::SysV>, and
+C<IPC::SysV::Msg> documentation.
+
+=item msgsnd ID,MSG,FLAGS
+
+Calls the System V IPC function msgsnd to send the message MSG to the
+message queue ID.  MSG must begin with the native long integer message
+type, and be followed by the length of the actual message, and finally
+the message itself.  This kind of packing can be achieved with
+C<pack("l! a*", $type, $message)>.  Returns true if successful,
+or false if there is an error.  See also C<IPC::SysV>
+and C<IPC::SysV::Msg> documentation.
 
 =item my EXPR
 
@@ -2569,25 +2629,32 @@ to be converted into a file mode, for example. (Although perl will
 automatically convert strings into numbers as needed, this automatic
 conversion assumes base 10.)
 
-=item open FILEHANDLE,MODE,LIST
-
 =item open FILEHANDLE,EXPR
 
+=item open FILEHANDLE,MODE,EXPR
+
+=item open FILEHANDLE,MODE,EXPR,LIST
+
 =item open FILEHANDLE
 
 Opens the file whose filename is given by EXPR, and associates it with
-FILEHANDLE.  If FILEHANDLE is an expression, its value is used as the
-name of the real filehandle wanted.  If EXPR is omitted, the scalar
+FILEHANDLE.  If FILEHANDLE is an undefined lexical (C<my>) variable the variable is
+assigned a reference to a new anonymous filehandle, otherwise if FILEHANDLE is an expression,
+its value is used as the name of the real filehandle wanted.  (This is considered a symbolic
+reference, so C<use strict 'refs'> should I<not> be in effect.)
+
+If EXPR is omitted, the scalar
 variable of the same name as the FILEHANDLE contains the filename.
 (Note that lexical variables--those declared with C<my>--will not work
 for this purpose; so if you're using C<my>, specify EXPR in your call
 to open.)  See L<perlopentut> for a kinder, gentler explanation of opening
 files.
 
-If MODE is C<< '<' >> or nothing, the file is opened for input.
+If three or more arguments are specified then the mode of opening and the file name
+are separate. If MODE is C<< '<' >> or nothing, the file is opened for input.
 If MODE is C<< '>' >>, the file is truncated and opened for
 output, being created if necessary.  If MODE is C<<< '>>' >>>,
-the file is opened for appending, again being created if necessary. 
+the file is opened for appending, again being created if necessary.
 You can put a C<'+'> in front of the C<< '>' >> or C<< '<' >> to indicate that
 you want both read and write access to the file; thus C<< '+<' >> is almost
 always preferred for read/write updates--the C<< '+>' >> mode would clobber the
@@ -2601,7 +2668,8 @@ C<'w'>, C<'w+'>, C<'a'>, and C<'a+'>.
 
 In the 2-arguments (and 1-argument) form of the call the mode and
 filename should be concatenated (in this order), possibly separated by
-spaces.  It is possible to omit the mode if the mode is C<< '<' >>.
+spaces.  It is possible to omit the mode in these forms if the mode is
+C<< '<' >>.
 
 If the filename begins with C<'|'>, the filename is interpreted as a
 command to which output is to be piped, and if the filename ends with a
@@ -2612,17 +2680,21 @@ that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>,
 and L<perlipc/"Bidirectional Communication with Another Process">
 for alternatives.)
 
-If MODE is C<'|-'>, the filename is interpreted as a
+For three or more arguments if MODE is C<'|-'>, the filename is interpreted as a
 command to which output is to be piped, and if MODE is
 C<'-|'>, the filename is interpreted as a command which pipes output to
 us.  In the 2-arguments (and 1-argument) form one should replace dash
 (C<'-'>) with the command.  See L<perlipc/"Using open() for IPC">
 for more examples of this.  (You are not allowed to C<open> to a command
 that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>,
-and L<perlipc/"Bidirectional Communication"> for alternatives.)
+and L<perlipc/"Bidirectional Communication"> for alternatives.) In 3+ arg form of
+pipe opens then if LIST is specified (extra arguments after the command name) then
+LIST becomes arguments to the command invoked if the platform supports it.
+The meaning of C<open> with more than three arguments for non-pipe modes
+is not yet specified. Experimental "layers" may give extra LIST arguments meaning.
 
 In the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN
-and opening C<< '>-' >> opens STDOUT.  
+and opening C<< '>-' >> opens STDOUT.
 
 Open returns
 nonzero upon success, the undefined value otherwise.  If the C<open>
@@ -2637,6 +2709,10 @@ and those that don't is their text file formats.  Systems like Unix, MacOS, and
 Plan9, which delimit lines with a single character, and which encode that
 character in C as C<"\n">, do not need C<binmode>.  The rest need it.
 
+In the three argument form MODE may also contain a list of IO "layers" (see L<open> and
+L<PerlIO> for more details) to be applied to the handle. This can be used to achieve the
+effect of C<binmode> as well as more complex behaviours.
+
 When opening a file, it's usually a bad idea to continue normal execution
 if the request failed, so C<open> is frequently used in connection with
 C<die>.  Even if C<die> won't do what you want (say, in a CGI script,
@@ -2645,6 +2721,14 @@ modules that can help with that problem)) you should always check
 the return value from opening a file.  The infrequent exception is when
 working with an unopened filehandle is actually what you want to do.
 
+As a special case the 3 arg form with a read/write mode and the third argument
+being C<undef>:
+
+    open(TMP, "+>", undef) or die ...
+
+opens a filehandle to an anonymous temporary file.
+
+
 Examples:
 
     $ARTICLE = 100;
@@ -2700,14 +2784,14 @@ duped and opened.  You may use C<&> after C<< > >>, C<<< >> >>>,
 C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>.  The
 mode you specify should match the mode of the original filehandle.
 (Duping a filehandle does not take into account any existing contents of
-stdio buffers.)  Duping file handles is not yet supported for 3-argument
-open().
+stdio buffers.) If you use the 3 arg form then you can pass either a number,
+the name of a filehandle or the normal "reference to a glob".
 
 Here is a script that saves, redirects, and restores STDOUT and
 STDERR:
 
     #!/usr/bin/perl
-    open(OLDOUT, ">&STDOUT");
+    open(my $oldout, ">&", \*STDOUT);
     open(OLDERR, ">&STDERR");
 
     open(STDOUT, '>', "foo.out") || die "Can't redirect stdout";
@@ -2733,12 +2817,13 @@ equivalent of C's C<fdopen> of that file descriptor; this is more
 parsimonious of file descriptors.  For example:
 
     open(FILEHANDLE, "<&=$fd")
+or
+    open(FILEHANDLE, "<&=", $fd)
 
-Note that this feature depends on the fdopen() C library function.
-On many UNIX systems, fdopen() is known to fail when file descriptors
+Note that if perl is using the standard C libaries fdopen() then on many UNIX systems,
+fdopen() is known to fail when file descriptors
 exceed a certain value, typically 255. If you need more file
-descriptors than that, consider rebuilding Perl to use the C<sfio>
-library.
+descriptors than that, consider rebuilding Perl to use the C<PerlIO>.
 
 If you open a pipe on the command C<'-'>, i.e., either C<'|-'> or C<'-|'>
 with 2-arguments (or 1-argument) form of open(), then
@@ -2757,10 +2842,15 @@ The following triples are more or less equivalent:
     open(FOO, "|tr '[a-z]' '[A-Z]'");
     open(FOO, '|-', "tr '[a-z]' '[A-Z]'");
     open(FOO, '|-') || exec 'tr', '[a-z]', '[A-Z]';
+    open(FOO, '|-', "tr", '[a-z]', '[A-Z]');
 
     open(FOO, "cat -n '$file'|");
     open(FOO, '-|', "cat -n '$file'");
     open(FOO, '-|') || exec 'cat', '-n', $file;
+    open(FOO, '-|', "cat", '-n', $file);
+
+The last example in each block shows the pipe as "list form", which is
+not yet supported on all platforms.
 
 See L<perlipc/"Safe Pipe Opens"> for more examples of this.
 
@@ -2780,7 +2870,7 @@ child to finish, and returns the status value in C<$?>.
 The filename passed to 2-argument (or 1-argument) form of open()
 will have leading and trailing
 whitespace deleted, and the normal redirection characters
-honored.  This property, known as "magic open", 
+honored.  This property, known as "magic open",
 can often be used to good effect.  A user could specify a filename of
 F<"rsh cat file |">, or you could change certain filenames as needed:
 
@@ -2796,8 +2886,8 @@ otherwise it's necessary to protect any leading and trailing whitespace:
     $file =~ s#^(\s)#./$1#;
     open(FOO, "< $file\0");
 
-(this may not work on some bizzare filesystems).  One should
-conscientiously choose between the the I<magic> and 3-arguments form
+(this may not work on some bizarre filesystems).  One should
+conscientiously choose between the I<magic> and 3-arguments form
 of open():
 
     open IN, $ARGV[0];
@@ -2819,7 +2909,7 @@ another way to protect your filenames from interpretation.  For example:
     sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL)
 	or die "sysopen $path: $!";
     $oldfh = select(HANDLE); $| = 1; select($oldfh);
-    print HANDLE "stuff $$\n");
+    print HANDLE "stuff $$\n";
     seek(HANDLE, 0, 0);
     print "File contains: ", <HANDLE>;
 
@@ -2859,6 +2949,8 @@ See L<utf8> for more about Unicode.
 
 =item our EXPR
 
+=item our EXPR : ATTRIBUTES
+
 An C<our> declares the listed variables to be valid globals within
 the enclosing block, file, or C<eval>.  That is, it has the same
 scoping rules as a "my" declaration, but does not create a local
@@ -2897,6 +2989,28 @@ package, Perl will emit warnings if you have asked for them.
 
     our $bar;		# emits warning
 
+An C<our> declaration may also have a list of attributes associated
+with it.  B<WARNING>: This is an experimental feature that may be
+changed or removed in future releases of Perl.  It should not be
+relied upon.
+
+The only currently recognized attribute is C<shared> which indicates
+that a single copy of the global is to be used by all interpreters
+should the program happen to be running in a multi-interpreter
+environment. (The default behaviour would be for each interpreter to
+have its own copy of the global.)  In such an environment, this
+attribute also has the effect of making the global readonly.
+Examples:
+
+    our @EXPORT : shared = qw(foo);
+    our %EXPORT_TAGS : shared = (bar => [qw(aa bb cc)]);
+    our $VERSION : shared = "1.00";
+
+Multi-interpreter environments can come to being either through the
+fork() emulation on Windows platforms, or by embedding perl in a
+multi-threaded application.  The C<shared> attribute does nothing in
+all other environments.
+
 =item pack TEMPLATE,LIST
 
 Takes a LIST of values and converts it into a string using the rules
@@ -2910,7 +3024,7 @@ sequence of characters that give the order and type of values, as
 follows:
 
     a	A string with arbitrary binary data, will be null padded.
-    A	An ascii string, will be space padded.
+    A	An ASCII string, will be space padded.
     Z	A null terminated (asciz) string, will be null padded.
 
     b	A bit string (ascending bit order inside each byte, like vec()).
@@ -3120,23 +3234,24 @@ L<Config>:
        print $Config{longlongsize}, "\n";
 
 (The C<$Config{longlongsize}> will be undefine if your system does
-not support long longs.) 
+not support long longs.)
 
 =item *
 
 The integer formats C<s>, C<S>, C<i>, C<I>, C<l>, and C<L>
 are inherently non-portable between processors and operating systems
 because they obey the native byteorder and endianness.  For example a
-4-byte integer 0x12345678 (305419896 decimal) be ordered natively
+4-byte integer 0x12345678 (305419896 decimal) would be ordered natively
 (arranged in and handled by the CPU registers) into bytes as
 
- 	0x12 0x34 0x56 0x78	# little-endian
- 	0x78 0x56 0x34 0x12	# big-endian
+ 	0x12 0x34 0x56 0x78	# big-endian
+ 	0x78 0x56 0x34 0x12	# little-endian
 
-Basically, the Intel, Alpha, and VAX CPUs are little-endian, while
-everybody else, for example Motorola m68k/88k, PPC, Sparc, HP PA,
-Power, and Cray are big-endian.  MIPS can be either: Digital used it
-in little-endian mode; SGI uses it in big-endian mode.
+Basically, the Intel and VAX CPUs are little-endian, while everybody
+else, for example Motorola m68k/88k, PPC, Sparc, HP PA, Power, and
+Cray are big-endian.  Alpha and MIPS can be either: Digital/Compaq
+used/uses them in little-endian mode; SGI/Cray uses them in big-endian
+mode.
 
 The names `big-endian' and `little-endian' are comic references to
 the classic "Gulliver's Travels" (via the paper "On Holy Wars and a
@@ -3163,7 +3278,7 @@ Byteorders C<'1234'> and C<'12345678'> are little-endian, C<'4321'>
 and C<'87654321'> are big-endian.
 
 If you want portable packed integers use the formats C<n>, C<N>,
-C<v>, and C<V>, their byte endianness and size is known.
+C<v>, and C<V>, their byte endianness and size are known.
 See also L<perlport>.
 
 =item *
@@ -3183,6 +3298,15 @@ equal $foo).
 
 =item *
 
+If the pattern begins with a C<U>, the resulting string will be treated
+as Unicode-encoded. You can force UTF8 encoding on in a string with an
+initial C<U0>, and the bytes that follow will be interpreted as Unicode
+characters. If you don't want this to happen, you can begin your pattern
+with C<C0> (or anything else) to force Perl not to UTF8 encode your
+string, and then follow this with a C<U*> somewhere in your pattern.
+
+=item *
+
 You must yourself do any alignment or padding by inserting for example
 enough C<'x'>es while packing.  There is no way to pack() and unpack()
 could know where the bytes are going to or coming from.  Therefore
@@ -3253,10 +3377,10 @@ Examples:
 
 The same template may generally also be used in unpack().
 
-=item package 
-
 =item package NAMESPACE
 
+=item package
+
 Declares the compilation unit as being in the given namespace.  The scope
 of the package declaration is from the declaration itself through the end
 of the enclosing block, file, or eval (the same as the C<my> operator).
@@ -3314,7 +3438,7 @@ array in subroutines, just like C<shift>.
 =item pos
 
 Returns the offset of where the last C<m//g> search left off for the variable
-is in question (C<$_> is used when the variable is not specified).  May be
+in question (C<$_> is used when the variable is not specified).  May be
 modified to change that offset.  Such modification will also influence
 the C<\G> zero-width assertion in regular expressions.  See L<perlre> and
 L<perlop>.
@@ -3407,7 +3531,7 @@ Generalized quotes.  See L<perlop/"Regexp Quote-Like Operators">.
 
 =item quotemeta
 
-Returns the value of EXPR with all non-alphanumeric
+Returns the value of EXPR with all non-"word"
 characters backslashed.  (That is, all characters not matching
 C</[A-Za-z_0-9]/> will be preceded by a backslash in the
 returned string, regardless of any locale settings.)
@@ -3422,8 +3546,15 @@ If EXPR is omitted, uses C<$_>.
 
 Returns a random fractional number greater than or equal to C<0> and less
 than the value of EXPR.  (EXPR should be positive.)  If EXPR is
-omitted, the value C<1> is used.  Automatically calls C<srand> unless
-C<srand> has already been called.  See also C<srand>.
+omitted, or a C<0>, the value C<1> is used.  Automatically calls C<srand>
+unless C<srand> has already been called.  See also C<srand>.
+
+Apply C<int()> to the value returned by C<rand()> if you want random
+integers instead of random fractional numbers.  For example,
+
+    int(rand(10))
+
+returns a random integer between C<0> and C<9>, inclusive.
 
 (Note: If your rand function consistently returns numbers that are too
 large or too small, then your version of Perl was probably compiled
@@ -3434,12 +3565,13 @@ with the wrong number of RANDBITS.)
 =item read FILEHANDLE,SCALAR,LENGTH
 
 Attempts to read LENGTH bytes of data into variable SCALAR from the
-specified FILEHANDLE.  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 to the length actually read.  An OFFSET may be specified to
-place the read data at some other place than the beginning of the
-string.  This call is actually implemented in terms of stdio's fread(3)
-call.  To get a true read(2) system call, see C<sysread>.
+specified FILEHANDLE.  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 to the length actually read.  If SCALAR needs growing, the
+new bytes will be zero bytes.  An OFFSET may be specified to place
+the read data into some other place in SCALAR than the beginning.
+The call is actually implemented in terms of stdio's fread(3) call.
+To get a true read(2) system call, see C<sysread>.
 
 =item readdir DIRHANDLE
 
@@ -3573,7 +3705,7 @@ name is returned instead.  You can think of C<ref> as a C<typeof> operator.
     }
     if (UNIVERSAL::isa($r, "HASH")) {  # for subclassing
 	print "r is a reference to something that isa hash.\n";
-    } 
+    }
 
 See also L<perlref>.
 
@@ -3649,9 +3781,9 @@ modules does not risk altering your namespace.
 
 In other words, if you try this:
 
-        require Foo::Bar;    # a splendid bareword 
+        require Foo::Bar;    # a splendid bareword
 
-The require function will actually look for the "F<Foo/Bar.pm>" file in the 
+The require function will actually look for the "F<Foo/Bar.pm>" file in the
 directories specified in the C<@INC> array.
 
 But if you try this:
@@ -3661,7 +3793,7 @@ But if you try this:
     #or
         require "Foo::Bar";  # not a bareword because of the ""
 
-The require function will look for the "F<Foo::Bar>" file in the @INC array and 
+The require function will look for the "F<Foo::Bar>" file in the @INC array and
 will complain about not finding "F<Foo::Bar>" there.  In this case you can do:
 
         eval "require $class";
@@ -3695,7 +3827,7 @@ See L</my>.
 
 =item return
 
-Returns from a subroutine, C<eval>, or C<do FILE> with the value 
+Returns from a subroutine, C<eval>, or C<do FILE> with the value
 given in EXPR.  Evaluation of EXPR may be in list, scalar, or void
 context, depending on how the return value will be used, and the context
 may vary from one execution to the next (see C<wantarray>).  If no EXPR
@@ -3914,14 +4046,16 @@ GETALL, then ARG must be a variable which will hold the returned
 semid_ds structure or semaphore value array.  Returns like C<ioctl>:
 the undefined value for error, "C<0 but true>" for zero, or the actual
 return value otherwise.  The ARG must consist of a vector of native
-short integers, which may may be created with C<pack("s!",(0)x$nsem)>.
-See also C<IPC::SysV> and C<IPC::Semaphore> documentation.
+short integers, which may be created with C<pack("s!",(0)x$nsem)>.
+See also L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::Semaphore>
+documentation.
 
 =item semget KEY,NSEMS,FLAGS
 
 Calls the System V IPC function semget.  Returns the semaphore id, or
-the undefined value if there is an error.  See also C<IPC::SysV> and
-C<IPC::SysV::Semaphore> documentation.
+the undefined value if there is an error.  See also
+L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::SysV::Semaphore>
+documentation.
 
 =item semop KEY,OPSTRING
 
@@ -3936,8 +4070,9 @@ following code waits on semaphore $semnum of semaphore id $semid:
     $semop = pack("sss", $semnum, -1, 0);
     die "Semaphore trouble: $!\n" unless semop($semid, $semop);
 
-To signal the semaphore, replace C<-1> with C<1>.  See also C<IPC::SysV>
-and C<IPC::SysV::Semaphore> documentation.
+To signal the semaphore, replace C<-1> with C<1>.  See also
+L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::SysV::Semaphore>
+documentation.
 
 =item send SOCKET,MSG,FLAGS,TO
 
@@ -3983,7 +4118,7 @@ C<@ARGV> array at file scopes or within the lexical scopes established by
 the C<eval ''>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>, and C<END {}>
 constructs.
 
-See also C<unshift>, C<push>, and C<pop>.  C<Shift()> and C<unshift> do the
+See also C<unshift>, C<push>, and C<pop>.  C<shift> and C<unshift> do the
 same thing to the left end of an array that C<pop> and C<push> do to the
 right end.
 
@@ -3997,13 +4132,13 @@ first to get the correct constant definitions.  If CMD is C<IPC_STAT>,
 then ARG must be a variable which will hold the returned C<shmid_ds>
 structure.  Returns like ioctl: the undefined value for error, "C<0> but
 true" for zero, or the actual return value otherwise.
-See also C<IPC::SysV> documentation.
+See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
 
 =item shmget KEY,SIZE,FLAGS
 
 Calls the System V IPC function shmget.  Returns the shared memory
 segment id, or the undefined value if there is an error.
-See also C<IPC::SysV> documentation.
+See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
 
 =item shmread ID,VAR,POS,SIZE
 
@@ -4015,8 +4150,8 @@ detaching from it.  When reading, VAR must be a variable that will
 hold the data read.  When writing, if STRING is too long, only SIZE
 bytes are used; if STRING is too short, nulls are written to fill out
 SIZE bytes.  Return true if successful, or false if there is an error.
-See also C<IPC::SysV> documentation and the C<IPC::Shareable> module
-from CPAN.
+shmread() taints the variable. See also L<perlipc/"SysV IPC">,
+C<IPC::SysV> documentation, and the C<IPC::Shareable> module from CPAN.
 
 =item shutdown SOCKET,HOW
 
@@ -4029,7 +4164,7 @@ has the same interpretation as in the system call of the same name.
 
 This is useful with sockets when you want to tell the other
 side you're done writing but not done reading, or vice versa.
-It's also a more insistent form of close because it also 
+It's also a more insistent form of close because it also
 disables the file descriptor in any forked copies in other
 processes.
 
@@ -4063,10 +4198,31 @@ busy multitasking system.
 
 For delays of finer granularity than one second, you may use Perl's
 C<syscall> interface to access setitimer(2) if your system supports
-it, or else see L</select> above.  The Time::HiRes module from CPAN
-may also help.
+it, or else see L</select> above.  The Time::HiRes module (from CPAN,
+and starting from Perl 5.8 part of the standard distribution) may also
+help.
+
+See also the POSIX module's C<pause> function.
+
+=item sockatmark SOCKET
 
-See also the POSIX module's C<sigpause> function.
+Returns true if the socket is positioned at the out-of-band mark
+(also known as the urgent data mark), false otherwise.  Use right
+after reading from the socket.
+
+Not available directly, one has to import the function from
+the IO::Socket extension
+
+    use IO::Socket 'sockatmark';
+
+Even this doesn't guarantee that sockatmark() really is available,
+though, because sockatmark() is a relatively recent addition to
+the family of socket functions.  If it is unavailable, attempt to
+use it will fail
+
+	IO::Socket::atmark not implemented on this architecture ...
+
+See also L<IO::Socket>.
 
 =item socket SOCKET,DOMAIN,TYPE,PROTOCOL
 
@@ -4119,9 +4275,9 @@ of a SUBNAME, you can provide a BLOCK as an anonymous, in-line sort
 subroutine.
 
 If the subroutine's prototype is C<($$)>, the elements to be compared
-are passed by reference in C<@_>, as for a normal subroutine.  If not,
-the normal calling code for subroutines is bypassed in the interests of
-efficiency, and the elements to be compared are passed into the subroutine
+are passed by reference in C<@_>, as for a normal subroutine.  This is
+slower than unprototyped subroutines, where the elements to be
+compared are passed into the subroutine
 as the package global variables $a and $b (see example below).  Note that
 in the latter case, it is usually counter-productive to declare $a and
 $b as lexicals.
@@ -4135,6 +4291,12 @@ loop control operators described in L<perlsyn> or with C<goto>.
 When C<use locale> is in effect, C<sort LIST> sorts LIST according to the
 current collation locale.  See L<perllocale>.
 
+Perl does B<not> guarantee that sort is stable.  (A I<stable> sort
+preserves the input order of elements that compare equal.)  5.7 and
+5.8 happen to use a stable mergesort, but 5.6 and earlier used quicksort,
+which is not stable.  Do not assume that future perls will continue to
+use a stable sort.
+
 Examples:
 
     # sort lexically
@@ -4218,15 +4380,12 @@ Examples:
 
 If you're using strict, you I<must not> declare $a
 and $b as lexicals.  They are package globals.  That means
-if you're in the C<main> package, it's
+if you're in the C<main> package and type
 
-    @articles = sort {$main::b <=> $main::a} @files;
-
-or just
-
-    @articles = sort {$::b <=> $::a} @files;
+    @articles = sort {$b <=> $a} @files;
 
-but if you're in the C<FooPack> package, it's
+then C<$a> and C<$b> are C<$main::a> and C<$main::b> (or C<$::a> and C<$::b>),
+but if you're in the C<FooPack> package, it's the same as typing
 
     @articles = sort {$FooPack::b <=> $FooPack::a} @files;
 
@@ -4285,22 +4444,24 @@ Example, assuming array lengths are passed before arrays:
 Splits a string into a list of strings and returns that list.  By default,
 empty leading fields are preserved, and empty trailing ones are deleted.
 
-If not in list context, returns the number of fields found and splits into
-the C<@_> array.  (In list context, you can force the split into C<@_> by
-using C<??> as the pattern delimiters, but it still returns the list
-value.)  The use of implicit split to C<@_> is deprecated, however, because
-it clobbers your subroutine arguments.
+In scalar context, returns the number of fields found and splits into
+the C<@_> array.  Use of split in scalar context is deprecated, however,
+because it clobbers your subroutine arguments.
 
 If EXPR is omitted, splits the C<$_> string.  If PATTERN is also omitted,
 splits on whitespace (after skipping any leading whitespace).  Anything
 matching PATTERN is taken to be a delimiter separating the fields.  (Note
 that the delimiter may be longer than one character.)
 
-If LIMIT is specified and positive, splits into no more than that
-many fields (though it may split into fewer).  If LIMIT is unspecified
-or zero, trailing null fields are stripped (which potential users
-of C<pop> would do well to remember).  If LIMIT is negative, it is
-treated as if an arbitrarily large LIMIT had been specified.
+If LIMIT is specified and positive, it represents the maximum number
+of fields the EXPR will be split into, though the actual number of
+fields returned depends on the number of times PATTERN matches within
+EXPR.  If LIMIT is unspecified or zero, trailing null fields are
+stripped (which potential users of C<pop> would do well to remember).
+If LIMIT is negative, it is treated as if an arbitrarily large LIMIT
+had been specified.  Note that splitting an EXPR that evaluates to the
+empty string always returns the empty list, regardless of the LIMIT
+specified.
 
 A pattern matching the null string (not to be confused with
 a null pattern C<//>, which is just one member of the set of patterns
@@ -4311,6 +4472,15 @@ characters at each point it matches that way.  For example:
 
 produces the output 'h:i:t:h:e:r:e'.
 
+Empty leading (or trailing) fields are produced when there positive width
+matches at the beginning (or end) of the string; a zero-width match at the
+beginning (or end) of the string does not produce an empty field.  For
+example:
+
+   print join(':', split(/(?=\w)/, 'hi there!'));
+
+produces the output 'h:i :t:h:e:r:e!'.
+
 The LIMIT parameter can be used to split a line partially
 
     ($login, $passwd, $remainder) = split(/:/, $_, 3);
@@ -4348,23 +4518,34 @@ A C<split> on C</\s+/> is like a C<split(' ')> except that any leading
 whitespace produces a null first field.  A C<split> with no arguments
 really does a C<split(' ', $_)> internally.
 
+A PATTERN of C</^/> is treated as if it were C</^/m>, since it isn't
+much use otherwise.
+
 Example:
 
     open(PASSWD, '/etc/passwd');
     while (<PASSWD>) {
-	($login, $passwd, $uid, $gid,
+        chomp;
+        ($login, $passwd, $uid, $gid,
          $gcos, $home, $shell) = split(/:/);
 	#...
     }
 
-(Note that $shell above will still have a newline on it.  See L</chop>,
-L</chomp>, and L</join>.)
 
 =item sprintf FORMAT, LIST
 
-Returns a string formatted by the usual C<printf> conventions of the
-C library function C<sprintf>.  See L<sprintf(3)> or L<printf(3)>
-on your system for an explanation of the general principles.
+Returns a string formatted by the usual C<printf> conventions of the C
+library function C<sprintf>.  See below for more details
+and see L<sprintf(3)> or L<printf(3)> on your system for an explanation of
+the general principles.
+
+For example:
+
+        # Format number with up to 8 leading zeroes
+        $result = sprintf("%08d", $number);
+
+        # Round number to 3 digits after decimal point
+        $rounded = sprintf("%.3f", $number);
 
 Perl does its own C<sprintf> formatting--it emulates the C
 function C<sprintf>, but it doesn't use it (except for floating-point
@@ -4372,6 +4553,12 @@ numbers, and even then only the standard modifiers are allowed).  As a
 result, any non-standard extensions in your local C<sprintf> are not
 available from Perl.
 
+Unlike C<printf>, C<sprintf> does not do what you probably mean when you
+pass it an array as your first argument. The array is given scalar context,
+and instead of using the 0th element of the array as the format, Perl will
+use the count of elements in the array as the format, which is almost never
+useful.
+
 Perl's C<sprintf> permits the following universally-known conversions:
 
    %%	a percent sign
@@ -4393,7 +4580,7 @@ In addition, Perl permits the following widely-supported conversions:
    %b	an unsigned integer, in binary
    %p	a pointer (outputs the Perl value's address in hexadecimal)
    %n	special: *stores* the number of characters output so far
-        into the next variable in the parameter list 
+        into the next variable in the parameter list
 
 Finally, for backward (and we do mean "backward") compatibility, Perl
 permits these unnecessary but widely-supported conversions:
@@ -4404,6 +4591,12 @@ permits these unnecessary but widely-supported conversions:
    %O	a synonym for %lo
    %F	a synonym for %f
 
+Note that the number of exponent digits in the scientific notation by
+C<%e>, C<%E>, C<%g> and C<%G> for numbers with the modulus of the
+exponent less than 100 is system-dependent: it may be three or less
+(zero-padded as necessary).  In other words, 1.23 times ten to the
+99th may be either "1.23e99" or "1.23e099".
+
 Perl permits the following universally-known flags between the C<%>
 and the conversion letter:
 
@@ -4420,13 +4613,31 @@ and the conversion letter:
    h       interpret integer as C type "short" or "unsigned short"
            If no flags, interpret integer as C type "int" or "unsigned"
 
+Perl supports parameter ordering, in other words, fetching the
+parameters in some explicitly specified "random" ordering as opposed
+to the default implicit sequential ordering.  The syntax is, instead
+of the C<%> and C<*>, to use C<%>I<digits>C<$> and C<*>I<digits>C<$>,
+where the I<digits> is the wanted index, from one upwards.  For example:
+
+   printf "%2\$d %1\$d\n", 12, 34;		# will print "34 12\n"
+   printf "%*2\$d\n",      12, 3;		# will print " 12\n"
+
+Note that using the reordering syntax does not interfere with the usual
+implicit sequential fetching of the parameters:
+
+   printf "%2\$d %d\n",    12, 34;		# will print "34 12\n"
+   printf "%2\$d %d %d\n", 12, 34;		# will print "34 12 34\n"
+   printf "%3\$d %d %d\n", 12, 34, 56;		# will print "56 12 34\n"
+   printf "%2\$*3\$d %d\n", 12, 34, 3;		# will print " 34 12\n"
+   printf "%*3\$2\$d %d\n", 12, 34, 3;		# will print " 34 12\n"
+
 There are also two Perl-specific flags:
 
-   V       interpret integer as Perl's standard integer type
-   v       interpret string as a vector of integers, output as
-           numbers separated either by dots, or by an arbitrary
-	   string received from the argument list when the flag
-	   is preceded by C<*>
+    V       interpret integer as Perl's standard integer type
+    v       interpret string as a vector of integers, output as
+            numbers separated either by dots, or by an arbitrary
+	    string received from the argument list when the flag
+	    is preceded by C<*>
 
 Where a number would appear in the flags, an asterisk (C<*>) may be
 used instead, in which case Perl uses the next item in the parameter
@@ -4584,7 +4795,7 @@ last stat or filetest are returned.  Example:
 under NFS.)
 
 Because the mode contains both the file type and its permissions, you
-should mask off the file type portion and (s)printf using a C<"%o"> 
+should mask off the file type portion and (s)printf using a C<"%o">
 if you want to see the real permissions.
 
     $mode = (stat($filename))[2];
@@ -4598,7 +4809,7 @@ The File::stat module provides a convenient, by-name access mechanism:
 
     use File::stat;
     $sb = stat($filename);
-    printf "File is %s, size is %s, perm %04o, mtime %s\n", 
+    printf "File is %s, size is %s, perm %04o, mtime %s\n",
 	$filename, $sb->size, $sb->mode & 07777,
 	scalar localtime $sb->mtime;
 
@@ -4641,11 +4852,11 @@ The commonly available S_IF* constants are
 
 and the S_IF* functions are
 
-    S_IFMODE($mode)	the part of $mode containg the permission bits
+    S_IFMODE($mode)	the part of $mode containing the permission bits
 			and the setuid/setgid/sticky bits
 
     S_IFMT($mode)	the part of $mode containing the file type
-			which can be bit-anded with e.g. S_IFREG 
+			which can be bit-anded with e.g. S_IFREG
                         or with the following functions
 
     # The operators -f, -d, -l, -b, -c, -p, and -s.
@@ -4810,7 +5021,7 @@ check the value of C<$!> if syscall returns C<-1>.
 
 There's a problem with C<syscall(&SYS_pipe)>: it returns the file
 number of the read end of the pipe it creates.  There is no way
-to retrieve the file number of the other end.  You can avoid this 
+to retrieve the file number of the other end.  You can avoid this
 problem by using C<pipe> instead.
 
 =item sysopen FILEHANDLE,FILENAME,MODE
@@ -4985,9 +5196,13 @@ case the SCALAR is empty you can use OFFSET but only zero offset.
 
 =item tell
 
-Returns the current position for FILEHANDLE.  FILEHANDLE may be an
-expression whose value gives the name of the actual filehandle.  If
-FILEHANDLE is omitted, assumes the file last read.  
+Returns the current position for FILEHANDLE, or -1 on error.  FILEHANDLE
+may be an expression whose value gives the name of the actual filehandle.
+If FILEHANDLE is omitted, assumes the file last read.
+
+The return value of tell() for the standard streams like the STDIN
+depends on the operating system: it may return -1 or something else.
+tell() on pipes, fifos, and sockets usually returns -1.
 
 There is no C<systell> function.  Use C<sysseek(FH, 0, 1)> for that.
 
@@ -5033,6 +5248,7 @@ A class implementing a hash should have the following methods:
     FIRSTKEY this
     NEXTKEY this, lastkey
     DESTROY this
+    UNTIE this
 
 A class implementing an ordinary array should have the following methods:
 
@@ -5049,6 +5265,7 @@ A class implementing an ordinary array should have the following methods:
     SPLICE this, offset, length, LIST
     EXTEND this, count
     DESTROY this
+    UNTIE this
 
 A class implementing a file handle should have the following methods:
 
@@ -5059,8 +5276,15 @@ A class implementing a file handle should have the following methods:
     WRITE this, scalar, length, offset
     PRINT this, LIST
     PRINTF this, format, LIST
+    BINMODE this
+    EOF this
+    FILENO this
+    SEEK this, position, whence
+    TELL this
+    OPEN this, mode, LIST
     CLOSE this
     DESTROY this
+    UNTIE this
 
 A class implementing a scalar should have the following methods:
 
@@ -5068,6 +5292,7 @@ A class implementing a scalar should have the following methods:
     FETCH this,
     STORE this, value
     DESTROY this
+    UNTIE 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>.
@@ -5271,7 +5496,7 @@ not known to be valid is likely to have disastrous consequences.
 
 If the repeat count of a field is larger than what the remainder of
 the input string allows, repeat count is decreased.  If the input string
-is longer than one described by the TEMPLATE, the rest is ignored. 
+is longer than one described by the TEMPLATE, the rest is ignored.
 
 See L</pack> for more examples and notes.
 
@@ -5336,7 +5561,8 @@ derive their C<import> method via inheritance from the C<Exporter> class that
 is defined in the C<Exporter> module.  See L<Exporter>.  If no C<import>
 method can be found then the call is skipped.
 
-If you don't want your namespace altered, explicitly supply an empty list:
+If you do not want to call the package's C<import> method (for instance,
+to stop your namespace from being altered), explicitly supply the empty list:
 
     use Module ();
 
@@ -5348,7 +5574,7 @@ If the VERSION argument is present between Module and LIST, then the
 C<use> will call the VERSION method in class Module with the given
 version as an argument.  The default VERSION method, inherited from
 the UNIVERSAL class, croaks if the given version is larger than the
-value of the variable C<$Module::VERSION>. 
+value of the variable C<$Module::VERSION>.
 
 Again, there is a distinction between omitting LIST (C<import> called
 with no arguments) and an explicit empty LIST C<()> (C<import> not
@@ -5357,8 +5583,9 @@ called).  Note that there is no comma after VERSION!
 Because this is a wide-open interface, pragmas (compiler directives)
 are also implemented this way.  Currently implemented pragmas are:
 
-    use integer;
+    use constant;
     use diagnostics;
+    use integer;
     use sigtrap  qw(SEGV BUS);
     use strict   qw(subs vars refs);
     use subs     qw(afunc blurfl);
@@ -5378,7 +5605,9 @@ by C<use>, i.e., it calls C<unimport Module LIST> instead of C<import>.
 
 If no C<unimport> method can be found the call fails with a fatal error.
 
-See L<perlmod> for a list of standard modules and pragmas.
+See L<perlmodlib> for a list of standard modules and pragmas.  See L<perlrun>
+for the C<-M> and C<-m> command-line options to perl that give C<use>
+functionality from the command-line.
 
 =item utime LIST
 
@@ -5393,6 +5622,13 @@ command if the files already exist:
     $now = time;
     utime $now, $now, @ARGV;
 
+If the first two elements of the list are C<undef>, then the utime(2)
+function in the C library will be called with a null second argument.
+On most systems, this will set the file's access and modification
+times to the current time.  (i.e. equivalent to the example above.)
+
+    utime undef, undef, @ARGV;
+
 =item values HASH
 
 Returns a list consisting of all the values of the named hash.  (In a
@@ -5402,12 +5638,11 @@ 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.
 
-Note that you cannot modify the values of a hash this way, because the
-returned list is just a copy.  You need to use a hash slice for that, 
-since it's lvaluable in a way that values() is not.
+Note that the values are not copied, which means modifying them will
+modify the contents of the hash:
 
-    for (values %hash) 	    { s/foo/bar/g }   # FAILS!
-    for (@hash{keys %hash}) { s/foo/bar/g }   # ok
+    for (values %hash) 	    { s/foo/bar/g }   # modifies %hash values
+    for (@hash{keys %hash}) { s/foo/bar/g }   # same
 
 As a side effect, calling values() resets the HASH's internal iterator.
 See also C<keys>, C<each>, and C<sort>.
@@ -5421,11 +5656,11 @@ that are reserved for each element in the bit vector.  This must
 be a power of two from 1 to 32 (or 64, if your platform supports
 that).
 
-If BITS is 8, "elements" coincide with bytes of the input string.  
+If BITS is 8, "elements" coincide with bytes of the input string.
 
 If BITS is 16 or more, bytes of the input string are grouped into chunks
 of size BITS/8, and each group is converted to a number as with
-pack()/unpack() with big-endian formats C<n>/C<N> (and analoguously
+pack()/unpack() with big-endian formats C<n>/C<N> (and analogously
 for BITS==64).  See L<"pack"> for details.
 
 If bits is 4 or less, the string is broken into bytes, then the bits
@@ -5440,9 +5675,18 @@ to give the expression the correct precedence as in
 
     vec($image, $max_x * $x + $y, 8) = 3;
 
-If the selected element is off the end of the string, the value 0 is
-returned.  If an element off the end of the string is written to,
-Perl will first extend the string with sufficiently many zero bytes.
+If the selected element is outside the string, the value 0 is returned.
+If an element off the end of the string is written to, Perl will first
+extend the string with sufficiently many zero bytes.   It is an error
+to try to write off the beginning of the string (i.e. negative OFFSET).
+
+The string should not contain any character with the value > 255 (which
+can only happen if you're using UTF8 encoding).  If it does, it will be
+treated as something which is not UTF8 encoded.  When the C<vec> was
+assigned to, other parts of your program will also no longer consider the
+string to be UTF8 encoded.  In other words, if you do have such characters
+in your string, vec() will operate on the actual byte string, and not the
+conceptual character string.
 
 Strings created with C<vec> can also be manipulated with the logical
 operators C<|>, C<&>, C<^>, and C<~>.  These operators will assume a bit
@@ -5483,7 +5727,7 @@ Here is an example to illustrate how the bits actually fall in place:
     #!/usr/bin/perl -wl
 
     print <<'EOT';
-                                      0         1         2         3  
+                                      0         1         2         3
                        unpack("V",$_) 01234567890123456789012345678901
     ------------------------------------------------------------------
     EOT
@@ -5511,7 +5755,7 @@ Here is an example to illustrate how the bits actually fall in place:
 Regardless of the machine architecture on which it is run, the above
 example should print the following table:
 
-                                      0         1         2         3  
+                                      0         1         2         3
                        unpack("V",$_) 01234567890123456789012345678901
     ------------------------------------------------------------------
     vec($_, 0, 1) = 1   ==          1 10000000000000000000000000000000
@@ -5660,7 +5904,7 @@ The status is returned in C<$?>.  If you say
 
     use POSIX ":sys_wait_h";
     #...
-    do { 
+    do {
 	$kid = waitpid(-1,&WNOHANG);
     } until $kid == -1;