X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=a56b4a889b7b585bf73889a6152a515c4e6100b9;hb=7ed149c909e2812f62b12bd7d09f4ccfb79e0041;hp=6b47fc7a417e5f7140c6f284d775bb6be3e6c2e6;hpb=e902a9797e486747cb6f7d090925b6ed8d7801d8;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 6b47fc7..a56b4a8 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
@@ -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
@@ -671,8 +688,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<$_>.
@@ -995,8 +1015,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.
@@ -1039,7 +1059,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:
 
@@ -1210,12 +1230,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:
 
@@ -1248,11 +1268,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
@@ -1416,6 +1436,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.
 
@@ -1458,7 +1484,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:
 
@@ -1470,8 +1496,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.
@@ -1634,7 +1660,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
@@ -1833,6 +1863,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:
@@ -1845,26 +1883,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.
@@ -1926,27 +1965,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:
 
@@ -1956,9 +2003,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"
 
@@ -2034,9 +2081,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>
@@ -2099,7 +2146,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
@@ -2173,6 +2220,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:
 
@@ -2303,13 +2353,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:
 
@@ -2319,9 +2376,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"
 
@@ -2367,8 +2424,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
@@ -2408,18 +2463,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
@@ -2438,30 +2496,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
 
@@ -2525,7 +2587,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
 
@@ -2533,31 +2595,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
@@ -2565,7 +2630,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
@@ -2577,7 +2643,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>
@@ -2649,10 +2715,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
@@ -2683,7 +2749,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:
 
@@ -2719,8 +2785,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>.
 
@@ -2747,7 +2818,7 @@ otherwise it's necessary to protect any leading and trailing whitespace:
     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
+conscientiously choose between the I<magic> and 3-arguments form
 of open():
 
     open IN, $ARGV[0];
@@ -2860,7 +2931,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()).
@@ -3079,10 +3150,10 @@ 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
@@ -3092,12 +3163,12 @@ 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", $_ }
@@ -3133,6 +3204,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
@@ -3357,7 +3437,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.)
@@ -3419,8 +3499,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>;
@@ -3546,9 +3626,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
@@ -3747,7 +3836,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:
@@ -3841,7 +3930,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
@@ -3852,15 +3941,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
 
@@ -3875,8 +3968,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
 
@@ -3922,7 +4016,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.
 
@@ -3936,13 +4030,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
 
@@ -3954,8 +4048,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
 
@@ -4050,7 +4144,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
@@ -4058,9 +4152,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.
@@ -4146,7 +4240,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;
@@ -4157,15 +4251,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;
 
@@ -4224,11 +4315,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
@@ -4287,6 +4376,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');
@@ -4301,9 +4393,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
@@ -4334,10 +4435,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:
 
@@ -4363,9 +4460,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
@@ -4373,6 +4474,13 @@ 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>.
@@ -4394,7 +4502,7 @@ 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
@@ -4436,7 +4544,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
@@ -4558,7 +4666,7 @@ The commonly available S_IF* constants are
     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
@@ -4573,7 +4681,7 @@ 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
@@ -4858,7 +4966,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
@@ -5174,8 +5286,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).
@@ -5219,12 +5331,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,
@@ -5235,13 +5349,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
@@ -5257,7 +5376,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 ();
 
@@ -5268,15 +5388,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);
@@ -5296,7 +5420,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
 
@@ -5320,12 +5446,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>.