X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=db90b86879c33faf931691ea0e06b949f66c1b3a;hb=91331b4fc62e0ad9094741aa6359fb89e2fc5554;hp=39798fdf8f91e7bd824b5a75c92599ebc620efa3;hpb=8d2a6795a8433e9623ccf677a19bf470170549e9;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 39798fd..db90b86 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -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
@@ -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
@@ -335,7 +335,7 @@ following a minus are interpreted as file tests.
 
 The C<-T> and C<-B> switches work as follows.  The first block or so of the
 file is examined for odd characters such as strange control codes or
-characters with the high bit set.  If too many strange characters (E<gt>30%)
+characters with the high bit set.  If too many strange characters (>30%)
 are found, it's a C<-B> file, otherwise it's a C<-T> file.  Also, any file
 containing null in the first block is considered a binary file.  If C<-T>
 or C<-B> is used on a filehandle, the current stdio buffer is examined
@@ -427,7 +427,7 @@ modulo the caveats given in L<perlipc/"Signals">.
 
 Returns the arctangent of Y/X in the range -PI to PI.
 
-For the tangent operation, you may use the C<POSIX::tan()>
+For the tangent operation, you may use the C<Math::Trig::tan>
 function, or use the familiar relation:
 
     sub tan { sin($_[0]) / cos($_[0])  }
@@ -439,47 +439,63 @@ does.  Returns true if it succeeded, false otherwise.  NAME should be a
 packed address of the appropriate type for the socket.  See the examples in
 L<perlipc/"Sockets: Client/Server Communication">.
 
+=item binmode FILEHANDLE, DISCIPLINE
+
 =item binmode FILEHANDLE
 
-Arranges for FILEHANDLE to be read or written in "binary" mode on
-systems whose run-time libraries force the programmer to guess
-between binary and text files.  If FILEHANDLE is an expression, the
-value is taken as the name of the filehandle.  binmode() should be
-called after the C<open> but before any I/O is done on the filehandle.
-The only way to reset binary mode on a filehandle is to reopen the
-file.
+Arranges for FILEHANDLE to be read or written in "binary" or "text" mode
+on systems where the run-time libraries distinguish between binary and
+text files.  If FILEHANDLE is an expression, the value is taken as the
+name of the filehandle.  DISCIPLINE can be either of C<":raw"> for
+binary mode or C<":crlf"> for "text" mode.  If the DISCIPLINE is
+omitted, it defaults to C<":raw">.
+
+binmode() should be called after open() but before any I/O is done on
+the filehandle.
+
+On many systems binmode() currently has no effect, but in future, it
+will be extended to support user-defined input and output disciplines.
+On some systems binmode() is necessary when you're not working with a
+text file.  For the sake of portability it is a good idea to always use
+it when appropriate, and to never use it when it isn't appropriate.
+
+In other words:  Regardless of platform, use binmode() on binary
+files, and do not use binmode() on text files.
+
+The C<open> pragma can be used to establish default disciplines.
+See L<open>.
 
 The operating system, device drivers, C libraries, and Perl run-time
-system all conspire to let the programmer conveniently treat a
-simple, one-byte C<\n> as the line terminator, irrespective of its
-external representation.  On Unix and its brethren, the native file
-representation exactly matches the internal representation, making
-everyone's lives unbelievably simpler.  Consequently, L<binmode>
-has no effect under Unix, Plan9, or Mac OS, all of which use C<\n>
-to end each line.  (Unix and Plan9 think C<\n> means C<\cJ> and
-C<\r> means C<\cM>, whereas the Mac goes the other way--it uses
-C<\cM> for c<\n> and C<\cJ> to mean C<\r>.  But that's ok, because
-it's only one byte, and the internal and external representations
-match.)
-
-In legacy systems like MS-DOS and its embellishments, your program
-sees a C<\n> as a simple C<\cJ> (just as in Unix), but oddly enough,
-that's not what's physically stored on disk.  What's worse, these
-systems refuse to help you with this; it's up to you to remember
-what to do.  And you mustn't go applying binmode() with wild abandon,
-either, because if your system does care about binmode(), then using
-it when you shouldn't is just as perilous as failing to use it when
-you should.
-
-That means that on any version of Microsoft WinXX that you might
-care to name (or not), binmode() causes C<\cM\cJ> sequences on disk
-to be converted to C<\n> when read into your program, and causes
-any C<\n> in your program to be converted back to C<\cM\cJ> on
-output to disk.  This sad discrepancy leads to no end of
-problems in not just the readline operator, but also when using
-seek(), tell(), and read() calls.  See L<perlport> for other painful
-details.  See the C<$/> and C<$\> variables in L<perlvar> for how
-to manually set your input and output line-termination sequences.
+system all work together to let the programmer treat a single
+character (C<\n>) as the line terminator, irrespective of the external
+representation.  On many operating systems, the native text file
+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.
+
+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 regard it as the end of
+the file, unless you use binmode().
+
+binmode() is not only important for readline() and print() operations,
+but also when using read(), seek(), sysread(), syswrite() and tell()
+(see L<perlport> for more details).  See the C<$/> and C<$\> variables
+in L<perlvar> for how to manually set your input and output
+line-termination sequences.
 
 =item bless REF,CLASSNAME
 
@@ -517,18 +533,19 @@ print a stack trace.  The value of EXPR indicates how many call frames
 to go back before the current one.
 
     ($package, $filename, $line, $subroutine, $hasargs,
-    $wantarray, $evaltext, $is_require, $hints) = caller($i);
+    $wantarray, $evaltext, $is_require, $hints, $bitmask) = caller($i);
 
 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<$hints> contains pragmatic hints that the caller was
-compiled with.  The C<$hints> value is subject to change between versions
-of Perl, and is not meant for external use.
+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.
 
 Furthermore, when called from within the DB package, caller returns more
 detailed information: it sets the list variable C<@DB::args> to be the
@@ -537,7 +554,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 E<gt> 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
@@ -563,6 +580,14 @@ successfully changed.  See also L</oct>, if all you have is a string.
     $mode = '0644'; chmod oct($mode), 'foo'; # this is better
     $mode = 0644;   chmod $mode, 'foo';      # this is best
 
+You can also import the symbolic C<S_I*> constants from the Fcntl
+module:
+
+    use Fcntl ':mode';
+
+    chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
+    # This is identical to the chmod 0755 of the above example.
+
 =item chomp VARIABLE
 
 =item chomp LIST
@@ -587,6 +612,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`);
@@ -613,6 +640,8 @@ Example:
 	#...
     }
 
+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`);
@@ -663,8 +692,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<$_>.
@@ -767,10 +799,12 @@ 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<$_>.
 
-For the inverse cosine operation, you may use the C<POSIX::acos()>
+For the inverse cosine operation, you may use the C<Math::Trig::acos()>
 function, or use this relation:
 
     sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
@@ -987,8 +1021,8 @@ lookup:
 
 Outside an C<eval>, prints the value of LIST to C<STDERR> and
 exits with the current value of C<$!> (errno).  If C<$!> is C<0>,
-exits with the value of C<($? E<gt>E<gt> 8)> (backtick `command`
-status).  If C<($? E<gt>E<gt> 8)> is C<0>, exits with C<255>.  Inside
+exits with the value of C<<< ($? >> 8) >>> (backtick `command`
+status).  If C<<< ($? >> 8) >>> is C<0>, exits with C<255>.  Inside
 an C<eval(),> the error message is stuffed into C<$@> and the
 C<eval> is terminated with the undefined value.  This makes
 C<die> the way to raise an exception.
@@ -1031,7 +1065,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:
 
@@ -1160,9 +1194,7 @@ make your program I<appear> to run faster.
 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"
-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.)
+element in the hash.
 
 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
@@ -1204,12 +1236,12 @@ as terminals may lose the end-of-file condition if you do.
 An C<eof> without an argument uses the last file read.  Using C<eof()>
 with empty parentheses is very different.  It refers to the pseudo file
 formed from the files listed on the command line and accessed via the
-C<E<lt>E<gt>> operator.  Since C<E<lt>E<gt>> isn't explicitly opened,
-as a normal filehandle is, an C<eof()> before C<E<lt>E<gt>> has been
+C<< <> >> operator.  Since C<< <> >> isn't explicitly opened,
+as a normal filehandle is, an C<eof()> before C<< <> >> has been
 used will cause C<@ARGV> to be examined to determine if input is
 available.
 
-In a C<while (E<lt>E<gt>)> loop, C<eof> or C<eof(ARGV)> can be used to
+In a C<< while (<>) >> loop, C<eof> or C<eof(ARGV)> can be used to
 detect the end of each file, C<eof()> will only detect the end of the
 last file.  Examples:
 
@@ -1242,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
@@ -1410,6 +1442,12 @@ program, passing it C<"surprise"> an argument.  The second version
 didn't--it tried to run a program literally called I<"echo surprise">,
 didn't find it, and set C<$?> to a non-zero value indicating failure.
 
+Beginning with v5.6.0, Perl will attempt to flush all files opened for
+output before the exec, but this may not be supported on some platforms
+(see L<perlport>).  To be safe, you may need to set C<$|> ($AUTOFLUSH
+in English) or call the C<autoflush()> method of C<IO::Handle> on any
+open handles in order to avoid lost output.
+
 Note that C<exec> will not call your C<END> blocks, nor will it call
 any C<DESTROY> methods in your objects.
 
@@ -1452,7 +1490,7 @@ operation is a hash or array key lookup or subroutine name:
 
 Although the deepest nested array or hash will not spring into existence
 just because its existence was tested, any intervening ones will.
-Thus C<$ref-E<gt>{"A"}> and C<$ref-E<gt>{"A"}-E<gt>{"B"}> will spring
+Thus C<< $ref->{"A"} >> and C<< $ref->{"A"}->{"B"} >> will spring
 into existence due to the existence test for the $key element above.
 This happens anywhere the arrow operator is used, including even:
 
@@ -1464,8 +1502,8 @@ This surprising autovivification in what does not at first--or even
 second--glance appear to be an lvalue context may be fixed in a future
 release.
 
-See L<perlref/"Pseudo-hashes"> for specifics on how exists() acts when
-used on a pseudo-hash.
+See L<perlref/"Pseudo-hashes: Using an array as a hash"> for specifics
+on how exists() acts when used on a pseudo-hash.
 
 Use of a subroutine call, rather than a subroutine name, as an argument
 to exists() is an error.
@@ -1628,7 +1666,11 @@ fork(), great care has gone into making it extremely efficient (for
 example, using copy-on-write technology on data pages), making it the
 dominant paradigm for multitasking over the last few decades.
 
-All files opened for output are flushed before forking the child process.
+Beginning with v5.6.0, Perl will attempt to flush all files opened for
+output before forking the child process, but this may not be supported
+on some platforms (see L<perlport>).  To be safe, you may need to set
+C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
+C<IO::Handle> on any open handles in order to avoid duplicate output.
 
 If you C<fork> without ever waiting on your children, you will
 accumulate zombies.  On some systems, you can avoid this by setting
@@ -1827,6 +1869,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:
@@ -1839,26 +1889,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.
@@ -1920,27 +1971,35 @@ Returns the socket option requested, or undef if there is an error.
 
 Returns the value of EXPR with filename expansions such as the
 standard Unix shell F</bin/csh> would do.  This is the internal function
-implementing the C<E<lt>*.cE<gt>> operator, but you can use it directly.
-If EXPR is omitted, C<$_> is used.  The C<E<lt>*.cE<gt>> operator is
+implementing the C<< <*.c> >> operator, but you can use it directly.
+If EXPR is omitted, C<$_> is used.  The C<< <*.c> >> operator is
 discussed in more detail in L<perlop/"I/O Operators">.
 
+Beginning with v5.6.0, this operator is implemented using the standard
+C<File::Glob> extension.  See L<File::Glob> for details.
+
 =item gmtime EXPR
 
-Converts a time as returned by the time function to a 9-element list
+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     8
-    ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
+    #  0    1    2     3     4    5     6     7  
+    ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday) =
 					    gmtime(time);
 
-All list elements are numeric, and come straight out of a struct tm.
-In particular this means that $mon has the range C<0..11> and $wday
-has the range C<0..6> with sunday as day C<0>.  Also, $year is the
-number of years since 1900, that is, $year is C<123> in year 2023,
-I<not> simply the last two digits of the year.  If you assume it is,
-then you create non-Y2K-compliant programs--and you wouldn't want to do
-that, would you?
+All list elements are numeric, and come straight out of the C `struct
+tm'.  $sec, $min, and $hour are the seconds, minutes, and hours of the
+specified time.  $mday is the day of the month, and $mon is the month
+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<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
+programs--and you wouldn't want to do that, would you?
 
 The proper way to get a complete 4-digit year is simply:
 
@@ -1950,9 +2009,9 @@ And to get the last two digits of the year (e.g., '01' in 2001) do:
 
 	$year = sprintf("%02d", $year % 100);
 
-If EXPR is omitted, does C<gmtime(time())>.
+If EXPR is omitted, C<gmtime()> uses the current time (C<gmtime(time)>).
 
-In scalar context, returns the ctime(3) value:
+In scalar context, C<gmtime()> returns the ctime(3) value:
 
     $now_string = gmtime;  # e.g., "Thu Oct 13 04:54:34 1994"
 
@@ -2028,9 +2087,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>
@@ -2093,7 +2152,7 @@ Implements the ioctl(2) function.  You'll probably first have to say
 
 to get the correct function definitions.  If F<ioctl.ph> doesn't
 exist or doesn't have the correct definitions you'll have to roll your
-own, based on your C header files such as F<E<lt>sys/ioctl.hE<gt>>.
+own, based on your C header files such as F<< <sys/ioctl.h> >>.
 (There is a Perl script called B<h2ph> that comes with the Perl kit that
 may help you in this, but it's nontrivial.)  SCALAR will be read and/or
 written depending on the FUNCTION--a pointer to the string value of SCALAR
@@ -2167,6 +2226,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:
 
@@ -2297,13 +2359,20 @@ follows:
     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
 						localtime(time);
 
-All list elements are numeric, and come straight out of a struct tm.
-In particular this means that $mon has the range C<0..11> and $wday
-has the range C<0..6> with sunday as day C<0>.  Also, $year is the
-number of years since 1900, that is, $year is C<123> in year 2023,
-and I<not> simply the last two digits of the year.  If you assume it is,
-then you create non-Y2K-compliant programs--and you wouldn't want to do
-that, would you?
+All list elements are numeric, and come straight out of the C `struct
+tm'.  $sec, $min, and $hour are the seconds, minutes, and hours of the
+specified time.  $mday is the day of the month, and $mon is the month
+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<0..364> (or C<0..365> in leap years.)  $isdst
+is true if the specified time occurs during daylight savings time,
+false otherwise.
+
+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
+programs--and you wouldn't want to do that, would you?
 
 The proper way to get a complete 4-digit year is simply:
 
@@ -2313,9 +2382,9 @@ And to get the last two digits of the year (e.g., '01' in 2001) do:
 
 	$year = sprintf("%02d", $year % 100);
 
-If EXPR is omitted, uses the current time (C<localtime(time)>).
+If EXPR is omitted, C<localtime()> uses the current time (C<localtime(time)>).
 
-In scalar context, returns the ctime(3) value:
+In scalar context, C<localtime()> returns the ctime(3) value:
 
     $now_string = localtime;  # e.g., "Thu Oct 13 04:54:34 1994"
 
@@ -2323,7 +2392,7 @@ This scalar value is B<not> locale dependent, see L<perllocale>, but
 instead a Perl builtin.  Also see the C<Time::Local> module
 (to convert the second, minutes, hours, ... back to seconds since the
 stroke of midnight the 1st of January 1970, the value returned by
-time()), and the strftime(3) and mktime(3) function available via the
+time()), and the strftime(3) and mktime(3) functions available via the
 POSIX module.  To get somewhat similar but locale dependent date
 strings, set up your locale environment variables appropriately
 (please see L<perllocale>) and try for example:
@@ -2361,8 +2430,6 @@ divided by the natural log of N.  For example:
 
 See also L</exp> for the inverse operation.
 
-=item lstat FILEHANDLE
-
 =item lstat EXPR
 
 =item lstat
@@ -2402,18 +2469,21 @@ 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.
 
 =item mkdir FILENAME,MASK
 
+=item mkdir FILENAME
+
 Creates the directory specified by FILENAME, with permissions
 specified by MASK (as modified by C<umask>).  If it succeeds it
 returns true, otherwise it returns false and sets C<$!> (errno).
+If omitted, MASK defaults to 0777.
 
 In general, it is better to create directories with permissive MASK,
 and let the user modify that with their C<umask>, than it is to supply
@@ -2432,30 +2502,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 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
 
@@ -2519,7 +2593,7 @@ 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,EXPR
+=item open FILEHANDLE,MODE,LIST
 
 =item open FILEHANDLE,EXPR
 
@@ -2527,31 +2601,34 @@ conversion assumes base 10.)
 
 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
+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<'E<lt>'> or nothing, the file is opened for input.
-If MODE is C<'E<gt>'>, the file is truncated and opened for
-output, being created if necessary.  If MODE is C<'E<gt>E<gt>'>,
+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. 
-You can put a C<'+'> in front of the C<'E<gt>'> or C<'E<lt>'> to indicate that
-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
+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
 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.  The file is created with
 permissions of C<0666> modified by the process' C<umask> value.
 
-These various prefixes correspond to the fopen(3) modes of C<'r'>, C<'r+'>, C<'w'>,
-C<'w+'>, C<'a'>, and C<'a+'>.
+These various prefixes correspond to the fopen(3) modes of C<'r'>, C<'r+'>,
+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<'E<lt>'>.
+spaces.  It is possible to omit the mode 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
@@ -2559,7 +2636,8 @@ C<'|'>, the filename is interpreted as a command which pipes output to
 us.  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 with Another Process">
+for alternatives.)
 
 If MODE is C<'|-'>, the filename is interpreted as a
 command to which output is to be piped, and if MODE is
@@ -2571,7 +2649,7 @@ that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>,
 and L<perlipc/"Bidirectional Communication"> for alternatives.)
 
 In the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN
-and opening C<'E<gt>-'> opens STDOUT.  
+and opening C<< '>-' >> opens STDOUT.  
 
 Open returns
 nonzero upon success, the undefined value otherwise.  If the C<open>
@@ -2643,10 +2721,10 @@ Examples:
     }
 
 You may also, in the Bourne shell tradition, specify an EXPR beginning
-with C<'E<gt>&'>, in which case the rest of the string is interpreted as the
+with C<< '>&' >>, in which case the rest of the string is interpreted as the
 name of a filehandle (or file descriptor, if numeric) to be
-duped and opened.  You may use C<&> after C<E<gt>>, C<E<gt>E<gt>>,
-C<E<lt>>, C<+E<gt>>, C<+E<gt>E<gt>>, and C<+E<lt>>.  The
+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
@@ -2677,7 +2755,7 @@ STDERR:
     print STDOUT "stdout 2\n";
     print STDERR "stderr 2\n";
 
-If you specify C<'E<lt>&=N'>, where C<N> is a number, then Perl will do an
+If you specify C<< '<&=N' >>, where C<N> is a number, then Perl will do an
 equivalent of C's C<fdopen> of that file descriptor; this is more
 parsimonious of file descriptors.  For example:
 
@@ -2713,8 +2791,13 @@ The following triples are more or less equivalent:
 
 See L<perlipc/"Safe Pipe Opens"> for more examples of this.
 
-NOTE: On any operation that may do a fork, all files opened for output
-are flushed before the fork is attempted.  On systems that support a
+Beginning with v5.6.0, Perl will attempt to flush all files opened for
+output before any operation that may do a fork, but this may not be
+supported on some platforms (see L<perlport>).  To be safe, you may need
+to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
+of C<IO::Handle> on any open handles.
+
+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>.
 
@@ -2740,8 +2823,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];
@@ -2854,7 +2937,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()).
@@ -3073,25 +3156,25 @@ 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
 (arranged in and handled by the CPU registers) into bytes as
- 
- 	0x12 0x34 0x56 0x78	# little-endian
- 	0x78 0x56 0x34 0x12	# big-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.
+
+ 	0x12 0x34 0x56 0x78	# big-endian
+ 	0x78 0x56 0x34 0x12	# little-endian
+
+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
 Plea for Peace" by Danny Cohen, USC/ISI IEN 137, April 1, 1980) and
 the egg-eating habits of the Lilliputians.
- 
+
 Some systems may have even weirder byte orders such as
- 
+
  	0x56 0x78 0x12 0x34
  	0x34 0x12 0x78 0x56
- 
+
 You can see your system's preference with
 
  	print join(" ", map { sprintf "%#02x", $_ }
@@ -3127,6 +3210,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
@@ -3197,10 +3289,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).
@@ -3258,7 +3350,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>.
@@ -3351,7 +3443,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.)
@@ -3413,8 +3505,8 @@ When C<$/> is set to C<undef>, when readline() is in scalar
 context (i.e. file slurp mode), and when an empty file is read, it
 returns C<''> the first time, followed by C<undef> subsequently.
 
-This is the internal function implementing the C<E<lt>EXPRE<gt>>
-operator, but you can use it directly.  The C<E<lt>EXPRE<gt>>
+This is the internal function implementing the C<< <EXPR> >>
+operator, but you can use it directly.  The C<< <EXPR> >>
 operator is discussed in more detail in L<perlop/"I/O Operators">.
 
     $line = <STDIN>;
@@ -3540,9 +3632,18 @@ rename(2) manpage or equivalent system documentation for details.
 =item require
 
 Demands some semantics specified by EXPR, or by C<$_> if EXPR is not
-supplied.  If a version number or tuple is specified, or if EXPR is
-numeric, demands that the current version of Perl
-(C<$^V> or C<$]> or $PERL_VERSION) be equal or greater than EXPR.
+supplied.
+
+If a VERSION is specified as a literal of the form v5.6.1,
+demands that the current version of Perl (C<$^V> or $PERL_VERSION) be
+at least as recent as that version, at run time.  (For compatibility
+with older versions of Perl, a numeric argument will also be interpreted
+as VERSION.)  Compare with L</use>, which can do a similar check at
+compile time.
+
+    require v5.6.1;	# run time version check
+    require 5.6.1;	# ditto
+    require 5.005_03;	# float version allowed for compatibility
 
 Otherwise, demands that a library file be included if it hasn't already
 been included.  The file is included via the do-FILE mechanism, which is
@@ -3723,9 +3824,8 @@ filehandle.  The values for WHENCE are C<0> to set the new position to
 POSITION, C<1> to set 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>
-(start of the file, current position, end of the file) from any of the
-modules Fcntl, C<IO::Seekable>, or POSIX.  Returns C<1> upon success,
-C<0> otherwise.
+(start of the file, current position, end of the file) from the Fcntl
+module.  Returns C<1> upon success, C<0> otherwise.
 
 If you want to position file for C<sysread> or C<syswrite>, don't use
 C<seek>--buffering makes its effect on the file's system position
@@ -3742,7 +3842,7 @@ This is also useful for applications emulating C<tail -f>.  Once you hit
 EOF on your read, and then sleep for a while, you might have to stick in a
 seek() to reset things.  The C<seek> doesn't change the current position,
 but it I<does> clear the end-of-file condition on the handle, so that the
-next C<E<lt>FILEE<gt>> makes Perl try again to read something.  We hope.
+next C<< <FILE> >> makes Perl try again to read something.  We hope.
 
 If that doesn't work (some stdios are particularly cantankerous), then
 you may need something more like this:
@@ -3836,7 +3936,7 @@ You can effect a sleep of 250 milliseconds this way:
     select(undef, undef, undef, 0.25);
 
 B<WARNING>: One should not attempt to mix buffered I/O (like C<read>
-or E<lt>FHE<gt>) with C<select>, except as permitted by POSIX, and even
+or <FH>) with C<select>, except as permitted by POSIX, and even
 then only on POSIX systems.  You have to use C<sysread> instead.
 
 =item semctl ID,SEMNUM,CMD,ARG
@@ -3847,15 +3947,19 @@ Calls the System V IPC function C<semctl>.  You'll probably have to say
 
 first to get the correct constant definitions.  If CMD is IPC_STAT or
 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.  See also C<IPC::SysV> and C<IPC::Semaphore> documentation.
+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 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
 
@@ -3870,8 +3974,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
 
@@ -3917,7 +4022,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.
 
@@ -3931,13 +4036,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
 
@@ -3949,8 +4054,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
 
@@ -3974,7 +4079,7 @@ processes.
 Returns the sine of EXPR (expressed in radians).  If EXPR is omitted,
 returns sine of C<$_>.
 
-For the inverse sine operation, you may use the C<POSIX::asin>
+For the inverse sine operation, you may use the C<Math::Trig::asin>
 function, or use this relation:
 
     sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
@@ -4000,7 +4105,7 @@ 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.
 
-See also the POSIX module's C<sigpause> function.
+See also the POSIX module's C<pause> function.
 
 =item socket SOCKET,DOMAIN,TYPE,PROTOCOL
 
@@ -4045,7 +4150,7 @@ Sorts the LIST and returns the sorted list value.  If SUBNAME or BLOCK
 is omitted, C<sort>s in standard string comparison order.  If SUBNAME is
 specified, it gives the name of a subroutine that returns an integer
 less than, equal to, or greater than C<0>, depending on how the elements
-of the list are to be ordered.  (The C<E<lt>=E<gt>> and C<cmp>
+of the list are to be ordered.  (The C<< <=> >> and C<cmp>
 operators are extremely useful in such routines.)  SUBNAME may be a
 scalar variable name (unsubscripted), in which case the value provides
 the name of (or a reference to) the actual subroutine to use.  In place
@@ -4053,9 +4158,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.
@@ -4141,7 +4246,7 @@ Examples:
                            ||
                   $a->[2] cmp $b->[2]
            } map { [$_, /=(\d+)/, uc($_)] } @old;
-    
+
     # using a prototype allows you to use any comparison subroutine
     # as a sort subroutine (including other package's subroutines)
     package other;
@@ -4152,15 +4257,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
-
-    @articles = sort {$main::b <=> $main::a} @files;
-
-or just
-
-    @articles = sort {$::b <=> $::a} @files;
-
-but if you're in the C<FooPack> package, it's
+if you're in the C<main> package and type
+  
+    @articles = sort {$b <=> $a} @files;
+  
+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;
 
@@ -4175,6 +4277,8 @@ well-defined.
 
 =item splice ARRAY,OFFSET
 
+=item splice ARRAY
+
 Removes the elements designated by OFFSET and LENGTH from an array, and
 replaces them with the elements of LIST, if any.  In list context,
 returns the elements removed from the array.  In scalar context,
@@ -4182,7 +4286,9 @@ returns the last element removed, or C<undef> if no elements are
 removed.  The array grows or shrinks as necessary.
 If OFFSET is negative then it starts that far from the end of the array.
 If LENGTH is omitted, removes everything from OFFSET onward.
-If LENGTH is negative, leave that many elements off the end of the array.
+If LENGTH is negative, leaves that many elements off the end of the array.
+If both OFFSET and LENGTH are omitted, removes everything.
+
 The following equivalences hold (assuming C<$[ == 0>):
 
     push(@a,$x,$y)	splice(@a,@a,0,$x,$y)
@@ -4215,11 +4321,9 @@ 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
@@ -4278,6 +4382,9 @@ 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');
@@ -4292,9 +4399,18 @@ 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
@@ -4302,6 +4418,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
@@ -4325,10 +4447,6 @@ In addition, Perl permits the following widely-supported conversions:
    %n	special: *stores* the number of characters output so far
         into the next variable in the parameter list 
 
-And the following Perl-specific conversion:
-
-   %v   a string, output as a tuple of integers ("Perl" is 80.101.114.108)
-
 Finally, for backward (and we do mean "backward") compatibility, Perl
 permits these unnecessary but widely-supported conversions:
 
@@ -4338,6 +4456,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:
 
@@ -4354,9 +4478,13 @@ 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"
 
-There is also one Perl-specific flag:
+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<*>
 
 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
@@ -4364,13 +4492,20 @@ list as the given number (that is, as the field width or precision).
 If a field width obtained through C<*> is negative, it has the same
 effect as the C<-> flag: left-justification.
 
+The C<v> flag is useful for displaying ordinal values of characters
+in arbitrary strings:
+
+    printf "version is v%vd\n", $^V;		# Perl's version
+    printf "address is %*vX\n", ":", $addr;	# IPv6 address
+    printf "bits are %*vb\n", " ", $bits;	# random bitstring
+
 If C<use locale> is in effect, the character used for the decimal
 point in formatted real numbers is affected by the LC_NUMERIC locale.
 See L<perllocale>.
 
 If Perl understands "quads" (64-bit integers) (this requires
-either that the platform natively supports quads or that Perl
-has been specifically compiled to support quads), the characters
+either that the platform natively support quads or that Perl
+be specifically compiled to support quads), the characters
 
 	d u o x X b i D U O
 
@@ -4385,11 +4520,11 @@ For example
 You can find out whether your Perl supports quads via L<Config>:
 
 	use Config;
-	($Config{use64bits} eq 'define' || $Config{longsize} == 8) &&
+	($Config{use64bitint} eq 'define' || $Config{longsize} == 8) &&
 		print "quads\n";
 
 If Perl understands "long doubles" (this requires that the platform
-supports long doubles), the flags
+support long doubles), the flags
 
 	e f g E F G
 
@@ -4427,7 +4562,7 @@ 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
-C<time ^ ($$ + ($$ E<lt>E<lt> 15))>), but that isn't necessary any more.
+C<time ^ ($$ + ($$ << 15))>), but that isn't necessary any more.
 
 In fact, it's usually not necessary to call C<srand> at all, because if
 it is not called explicitly, it is called implicitly at the first use of
@@ -4503,7 +4638,8 @@ last stat or filetest are returned.  Example:
 	print "$file is executable NFS file\n";
     }
 
-(This works on machines only for which the device number is negative under NFS.)
+(This works on machines only for which the device number is negative
+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"> 
@@ -4524,6 +4660,66 @@ The File::stat module provides a convenient, by-name access mechanism:
 	$filename, $sb->size, $sb->mode & 07777,
 	scalar localtime $sb->mtime;
 
+You can import symbolic mode constants (C<S_IF*>) and functions
+(C<S_IS*>) from the Fcntl module:
+
+    use Fcntl ':mode';
+
+    $mode = (stat($filename))[2];
+
+    $user_rwx      = ($mode & S_IRWXU) >> 6;
+    $group_read    = ($mode & S_IRGRP) >> 3;
+    $other_execute =  $mode & S_IXOTH;
+
+    printf "Permissions are %04o\n", S_ISMODE($mode), "\n";
+
+    $is_setuid     =  $mode & S_ISUID;
+    $is_setgid     =  S_ISDIR($mode);
+
+You could write the last two using the C<-u> and C<-d> operators.
+The commonly available S_IF* constants are
+
+    # Permissions: read, write, execute, for user, group, others.
+
+    S_IRWXU S_IRUSR S_IWUSR S_IXUSR
+    S_IRWXG S_IRGRP S_IWGRP S_IXGRP
+    S_IRWXO S_IROTH S_IWOTH S_IXOTH
+
+    # Setuid/Setgid/Stickiness.
+
+    S_ISUID S_ISGID S_ISVTX S_ISTXT
+
+    # File types.  Not necessarily all are available on your system.
+
+    S_IFREG S_IFDIR S_IFLNK S_IFBLK S_ISCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
+
+    # The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.
+
+    S_IREAD S_IWRITE S_IEXEC
+
+and the S_IF* functions are
+
+    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 
+                        or with the following functions
+
+    # The operators -f, -d, -l, -b, -c, -p, and -s.
+
+    S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)
+    S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)
+
+    # No direct -X operator counterpart, but for the first one
+    # the -g operator is often equivalent.  The ENFMT stands for
+    # record flocking enforcement, a platform-dependent feature.
+
+    S_ISENFMT($mode) S_ISWHT($mode)
+
+See your native chmod(2) and stat(2) documentation for more details
+about the S_* constants.
+
 =item study SCALAR
 
 =item study
@@ -4763,7 +4959,7 @@ 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 also use the constants C<SEEK_SET>, C<SEEK_CUR>, and
 C<SEEK_END> (start of the file, current position, end of the file)
-from any of the modules Fcntl, C<IO::Seekable>, or POSIX.
+from the Fcntl 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
@@ -4788,7 +4984,11 @@ 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.
 
-All files opened for output are flushed before attempting the exec().
+Beginning with v5.6.0, Perl will attempt to flush all files opened for
+output before any operation that may do a fork, but this may not be
+supported on some platforms (see L<perlport>).  To be safe, you may need
+to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
+of C<IO::Handle> on any open handles.
 
 The return value is the exit status of the program as
 returned by the C<wait> call.  To get the actual exit value divide by
@@ -4891,6 +5091,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:
 
@@ -4907,6 +5108,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:
 
@@ -4917,8 +5119,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:
 
@@ -4926,6 +5135,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>.
@@ -5104,8 +5314,8 @@ and then there's
     sub ordinal { unpack("c",$_[0]); } # same as ord()
 
 In addition to fields allowed in pack(), you may prefix a field with
-a %E<lt>numberE<gt> to indicate that
-you want a E<lt>numberE<gt>-bit checksum of the items instead of the items
+a %<number> to indicate that
+you want a <number>-bit checksum of the items instead of the items
 themselves.  Default is a 16-bit checksum.  Checksum is calculated by
 summing numeric values of expanded values (for string fields the sum of
 C<ord($char)> is taken, for bit fields the sum of zeroes and ones).
@@ -5149,12 +5359,14 @@ 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 use Module VERSION LIST
+
+=item use Module VERSION
+
 =item use Module LIST
 
 =item use Module
 
-=item use Module VERSION LIST
-
 =item use VERSION
 
 Imports some semantics into the current package from the named module,
@@ -5165,13 +5377,18 @@ package.  It is exactly equivalent to
 
 except that Module I<must> be a bareword.
 
-If the first argument to C<use> is a number or a version tuple, it is
-treated as a version instead of a module name.  If the version
-of the Perl interpreter is less than VERSION, then an error message
-is printed and Perl exits immediately.
+VERSION, which can be specified as a literal of the form v5.6.1, demands
+that the current version of Perl (C<$^V> or $PERL_VERSION) be at least
+as recent as that version.  (For compatibility with older versions of Perl,
+a numeric literal will also be interpreted as VERSION.)  If the version
+of the running Perl interpreter is less than VERSION, then an error
+message is printed and Perl exits immediately without attempting to
+parse the rest of the file.  Compare with L</require>, which can do a
+similar check at run time.
 
-    use 5.005_03;	# version number
-    use v5.6.0;		# version tuple
+    use v5.6.1;		# compile time version check
+    use 5.6.1;		# ditto
+    use 5.005_03;	# float version allowed for compatibility
 
 This is often useful if you need to check the current Perl version before
 C<use>ing library modules that have changed in incompatible ways from
@@ -5187,7 +5404,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 ();
 
@@ -5198,15 +5416,19 @@ That is exactly equivalent to
 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>.  (Note that there is not a
-comma after VERSION!)
+the UNIVERSAL class, croaks if the given version is larger than the
+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
+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);
@@ -5226,7 +5448,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<perlmod> 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
 
@@ -5250,12 +5474,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>.
@@ -5273,7 +5496,7 @@ 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
@@ -5288,9 +5511,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