X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=3a17659ea49df43c78e2baaf3caf3f99b176c531;hb=c23d1eb0e18a49361001d26c686323d50b0c6d21;hp=c04cc482c85ba2e03f15c5732f3f99bc72c3e43d;hpb=dd36d13c89140c2d9d7954b9f1de583003154c13;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index c04cc48..3a17659 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -136,8 +136,8 @@ C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec>
 
 C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
 C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
-C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<umask>,
-C<unlink>, C<utime>
+C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<sysopen>,
+C<umask>, C<unlink>, C<utime>
 
 =item Keywords related to the control flow of your perl program
 
@@ -172,7 +172,7 @@ C<untie>, C<use>
 
 C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
 C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
-C<sockatmark>, C<socket>, C<socketpair>
+C<socket>, C<socketpair>
 
 =item System V interprocess communication functions
 
@@ -224,8 +224,8 @@ by this are:
 C<-X>, C<binmode>, C<chmod>, C<chown>, C<chroot>, C<crypt>,
 C<dbmclose>, C<dbmopen>, C<dump>, C<endgrent>, C<endhostent>,
 C<endnetent>, C<endprotoent>, C<endpwent>, C<endservent>, C<exec>,
-C<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostent>,
-C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
+C<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostbyname>,
+C<gethostent>, C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
 C<getppid>, C<getprgp>, C<getpriority>, C<getprotobynumber>,
 C<getprotoent>, C<getpwent>, C<getpwnam>, C<getpwuid>,
 C<getservbyport>, C<getservent>, C<getsockopt>, C<glob>, C<ioctl>,
@@ -234,7 +234,7 @@ C<msgsnd>, C<open>, C<pipe>, C<readlink>, C<rename>, C<select>, C<semctl>,
 C<semget>, C<semop>, C<setgrent>, C<sethostent>, C<setnetent>,
 C<setpgrp>, C<setpriority>, C<setprotoent>, C<setpwent>,
 C<setservent>, C<setsockopt>, C<shmctl>, C<shmget>, C<shmread>,
-C<shmwrite>, C<sockatmark>, C<socket>, C<socketpair>,
+C<shmwrite>, C<socket>, C<socketpair>,
 C<stat>, C<symlink>, C<syscall>, C<sysopen>, C<system>,
 C<times>, C<truncate>, C<umask>, C<unlink>,
 C<utime>, C<wait>, C<waitpid>
@@ -246,11 +246,11 @@ L<perlport> and other available platform-specific documentation.
 
 =over 8
 
-=item I<-X> FILEHANDLE
+=item -X FILEHANDLE
 
-=item I<-X> EXPR
+=item -X EXPR
 
-=item I<-X>
+=item -X
 
 A file test, where X is one of the letters listed below.  This unary
 operator takes one argument, either a filename or a filehandle, and
@@ -429,6 +429,8 @@ modulo the caveats given in L<perlipc/"Signals">.
     	# didn't
     }
 
+For more information see L<perlipc>.
+
 =item atan2 Y,X
 
 Returns the arctangent of Y/X in the range -PI to PI.
@@ -445,36 +447,60 @@ 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, LAYER
 
 =item binmode FILEHANDLE
 
-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>.  Returns true on success, C<undef> on
-failure.  The C<:raw> are C<:clrf>, and any other directives of the
-form C<:...>, are called I/O I<disciplines>.
-
-The C<open> pragma can be used to establish default I/O disciplines.
-See L<open>.
+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.  Returns true on success,
+otherwise it returns C<undef> and sets C<$!> (errno).
+
+On some systems (in general, DOS and Windows-based 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.  Also, people can
+set their I/O to be by default UTF-8 encoded Unicode, not bytes.
+
+In other words: regardless of platform, use binmode() on binary data,
+like for example images.
+
+If LAYER is present it is a single string, but may contain multiple
+directives. The directives alter the behaviour of the file handle.
+When LAYER is present using binmode on text file makes sense.
+
+If LAYER is omitted or specified as C<:raw> the filehandle is made
+suitable for passing binary data. This includes turning off possible CRLF
+translation and marking it as bytes (as opposed to Unicode characters).
+Note that as despite what may be implied in I<"Programming Perl">
+(the Camel) or elsewhere C<:raw> is I<not> the simply inverse of C<:crlf>
+-- other layers which would affect binary nature of the stream are
+I<also> disabled. See L<PerlIO>, L<perlrun> and the discussion about the
+PERLIO environment variable.
+
+The C<:bytes>, C<:crlf>, and C<:utf8>, and any other directives of the
+form C<:...>, are called I/O I<layers>.  The C<open> pragma can be used to
+establish default I/O layers.  See L<open>.
+
+I<The LAYER parameter of the binmode() function is described as "DISCIPLINE"
+in "Programming Perl, 3rd Edition".  However, since the publishing of this
+book, by many known as "Camel III", the consensus of the naming of this
+functionality has moved from "discipline" to "layer".  All documentation
+of this version of Perl therefore refers to "layers" rather than to
+"disciplines".  Now back to the regularly scheduled documentation...>
+
+To mark FILEHANDLE as UTF-8, use C<:utf8>.
 
 In general, binmode() should be called after open() but before any I/O
-is done on the filehandle.  Calling binmode() will flush any possibly
-pending buffered input or output data on the handle.  The only
-exception to this is the C<:encoding> discipline that changes
-the default character encoding of the handle, see L<open>.
-The C<:encoding> discipline sometimes needs to be called in
-mid-stream, and it doesn't flush the stream.
-
-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.
+is done on the filehandle.  Calling binmode() will normally flush any
+pending buffered output data (and perhaps pending input data) on the
+handle.  An exception to this is the C<:encoding> layer that
+changes the default character encoding of the handle, see L<open>.
+The C<:encoding> layer sometimes needs to be called in
+mid-stream, and it doesn't flush the stream.  The C<:encoding>
+also implicitly pushes on top of itself the C<:utf8> layer because
+internally Perl will operate on UTF-8 encoded Unicode characters.
 
 The operating system, device drivers, C libraries, and Perl run-time
 system all work together to let the programmer treat a single
@@ -487,14 +513,13 @@ one character.
 Mac OS, all variants of Unix, and Stream_LF files on VMS use a single
 character to end each line in the external representation of text (even
 though that single character is CARRIAGE RETURN on Mac OS and LINE FEED
-on Unix and most VMS files).  Consequently binmode() has no effect on
-these operating systems.  In other systems like OS/2, DOS and the various
-flavors of MS-Windows your program sees a C<\n> as a simple C<\cJ>, but
-what's stored in text files are the two characters C<\cM\cJ>.  That means
-that, if you don't use binmode() on these systems, C<\cM\cJ> sequences on
-disk will be converted to C<\n> on input, and any C<\n> in your program
-will be converted back to C<\cM\cJ> on output.  This is what you want for
-text files, but it can be disastrous for binary files.
+on Unix and most VMS files). In other systems like OS/2, DOS and the
+various flavors of MS-Windows your program sees a C<\n> as a simple C<\cJ>,
+but what's stored in text files are the two characters C<\cM\cJ>.  That
+means that, if you don't use binmode() on these systems, C<\cM\cJ>
+sequences on disk will be converted to C<\n> on input, and any C<\n> in
+your program will be converted back to C<\cM\cJ> on output.  This is what
+you want for text files, but it can be disastrous for binary files.
 
 Another consequence of using binmode() (on some systems) is that
 special end-of-file markers will be seen as part of the data stream.
@@ -552,11 +577,13 @@ 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 an C<eval BLOCK> statement,
 $filename is C<(eval)>, but $evaltext is undefined.  (Note also that
-each C<use> statement creates a C<require> frame inside an C<eval EXPR>)
-frame.  C<$hasargs> is true if a new instance of C<@_> was set up for the
-frame.  C<$hints> and C<$bitmask> contain pragmatic hints that the caller
-was compiled with.  The C<$hints> and C<$bitmask> values are subject to
-change between versions of Perl, and are not meant for external use.
+each C<use> statement creates a C<require> frame inside an C<eval EXPR>
+frame.)  $subroutine may also be C<(unknown)> if this particular
+subroutine happens to have been deleted from the symbol table.
+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
@@ -634,6 +661,13 @@ You can actually chomp anything that's an lvalue, including an assignment:
 If you chomp a list, each element is chomped, and the total number of
 characters removed is returned.
 
+Note that parentheses are necessary when you're chomping anything
+that is not a simple variable.  This is because C<chomp $cwd = `pwd`;>
+is interpreted as C<(chomp $cwd) = `pwd`;>, rather than as
+C<chomp( $cwd = `pwd` )> which you might expect.  Similarly,
+C<chomp $a, $b> is interpreted as C<chomp($a), $b> rather than
+as C<chomp($a, $b)>.
+
 =item chop VARIABLE
 
 =item chop( LIST )
@@ -653,6 +687,8 @@ last C<chop> is returned.
 Note that C<chop> returns the last character.  To return all but the last
 character, use C<substr($string, 0, -1)>.
 
+See also L</chomp>.
+
 =item chown LIST
 
 Changes the owner (and group) of a list of files.  The first two
@@ -696,10 +732,14 @@ chr(0x263a) is a Unicode smiley face.  Note that characters from 127
 to 255 (inclusive) are by default not encoded in Unicode for backward
 compatibility reasons (but see L<encoding>).
 
+If NUMBER is omitted, uses C<$_>.
+
 For the reverse, use L</ord>.
-See L<perlunicode> and L<encoding> for more about Unicode.
 
-If NUMBER is omitted, uses C<$_>.
+Note that under the C<bytes> pragma the NUMBER is masked to
+the low eight bits.
+
+See L<perlunicode> and L<encoding> for more about Unicode.
 
 =item chroot FILENAME
 
@@ -758,9 +798,6 @@ filehandle, usually the real filehandle name.
 Closes a directory opened by C<opendir> and returns the success of that
 system call.
 
-DIRHANDLE may be an expression whose value can be used as an indirect
-dirhandle, usually the real dirhandle name.
-
 =item connect SOCKET,NAME
 
 Attempts to connect to a remote socket, just as the connect system call
@@ -817,7 +854,7 @@ extirpated as a potential munition).  This can prove useful for checking
 the password file for lousy passwords, amongst other things.  Only the
 guys wearing white hats should do this.
 
-Note that C<crypt> is intended to be a one-way function, much like
+Note that L<crypt|/crypt> is intended to be a one-way function, much like
 breaking eggs to make an omelette.  There is no (known) corresponding
 decrypt function (in other words, the crypt() is a one-way hash
 function).  As a result, this function isn't all that useful for
@@ -825,7 +862,7 @@ cryptography.  (For that, see your nearby CPAN mirror.)
 
 When verifying an existing encrypted string you should use the
 encrypted text as the salt (like C<crypt($plain, $crypted) eq
-$crypted>).  This allows your code to work with the standard C<crypt>
+$crypted>).  This allows your code to work with the standard L<crypt|/crypt>
 and with more exotic implementations.  In other words, do not assume
 anything about the returned string itself, or how many bytes in
 the encrypted string matter.
@@ -839,7 +876,10 @@ different strings.
 
 When choosing a new salt create a random two character string whose
 characters come from the set C<[./0-9A-Za-z]> (like C<join '', ('.',
-'/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>).
+'/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>).  This set of
+characters is just a recommendation; the characters allowed in
+the salt depend solely on your system's crypt library, and Perl can't
+restrict what salts C<crypt()> accepts.
 
 Here's an example that makes sure that whoever runs this program knows
 their own password:
@@ -861,7 +901,7 @@ their own password:
 Of course, typing in your own password to whoever asks you
 for it is unwise.
 
-The L<crypt> function is unsuitable for encrypting large quantities
+The L<crypt|/crypt> function is unsuitable for encrypting large quantities
 of data, not least of all because you can't get the information
 back.  Look at the F<by-module/Crypt> and F<by-module/PGP> directories
 on your favorite CPAN mirror for a slew of potentially useful
@@ -942,7 +982,7 @@ element to return happens to be C<undef>.
 
 You may also use C<defined(&func)> to check whether subroutine C<&func>
 has ever been defined.  The return value is unaffected by any forward
-declarations of C<&foo>.  Note that a subroutine which is not defined
+declarations of C<&func>.  Note that a subroutine which is not defined
 may still be callable: its package may have an C<AUTOLOAD> method that
 makes it spring into existence the first time that it is called -- see
 L<perlsub>.
@@ -1085,7 +1125,7 @@ This is useful for propagating exceptions:
 If LIST is empty and C<$@> contains an object reference that has a
 C<PROPAGATE> method, that method will be called with additional file
 and line number parameters.  The return value replaces the value in
-C<$@>.  ie. as if C<<$@ = eval { $@->PROPAGATE(__FILE__, __LINE__) };>> 
+C<$@>.  ie. as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >>
 were called.
 
 If C<$@> is empty then the string C<"Died"> is used.
@@ -1227,9 +1267,11 @@ it.  When called in scalar context, returns only the key for the next
 element in the hash.
 
 Entries are returned in an apparently random order.  The actual random
-order is subject to change in future versions of perl, but it is guaranteed
-to be in the same order as either the C<keys> or C<values> function
-would produce on the same (unmodified) hash.
+order is subject to change in future versions of perl, but it is
+guaranteed to be in the same order as either the C<keys> or C<values>
+function would produce on the same (unmodified) hash.  Since Perl
+5.8.1 the ordering is different even between different runs of Perl
+for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
 
 When the hash is entirely read, a null array is returned in list context
 (which when assigned produces a false (C<0>) value), and C<undef> in
@@ -1276,7 +1318,7 @@ formed from the files listed on the command line and accessed via the
 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.   Similarly, an C<eof()> after C<< <> >> has returned 
+available.   Similarly, an C<eof()> after C<< <> >> has returned
 end-of-file will assume you are processing another C<@ARGV> list,
 and if you haven't set C<@ARGV>, will read input from C<STDIN>;
 see L<perlop/"I/O Operators">.
@@ -1295,12 +1337,11 @@ last file.  Examples:
 
     # insert dashes just before last line of last file
     while (<>) {
-	if (eof()) {		# check for end of current file
+	if (eof()) {		# check for end of last file
 	    print "--------------\n";
-	    close(ARGV);	# close or last; is needed if we
-				# are reading from the terminal
 	}
 	print;
+	last if eof();          # needed if we're reading from a terminal
     }
 
 Practical hint: you almost never need to use C<eof> in Perl, because the
@@ -1417,6 +1458,11 @@ in case 6.
 C<eval BLOCK> does I<not> count as a loop, so the loop control statements
 C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
 
+Note that as a very special case, an C<eval ''> executed within the C<DB>
+package doesn't see the usual surrounding lexical scope, but rather the
+scope of the first non-DB piece of code that called it. You don't normally
+need to worry about this unless you are writing a Perl debugger.
+
 =item exec LIST
 
 =item exec PROGRAM LIST
@@ -1546,9 +1592,6 @@ 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: 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.
 
@@ -1601,7 +1644,7 @@ For example:
     fcntl($filehandle, F_GETFL, $packed_return_buffer)
 	or die "can't fcntl F_GETFL: $!";
 
-You don't have to check for C<defined> on the return from C<fnctl>.
+You don't have to check for C<defined> on the return from C<fcntl>.
 Like C<ioctl>, it maps a C<0> return from the system call into
 C<"0 but true"> in Perl.  This string is true in boolean context and C<0>
 in numeric context.  It is also exempt from the normal B<-w> warnings
@@ -1776,11 +1819,11 @@ C<formline> always returns true.  See L<perlform> for other examples.
 =item getc
 
 Returns the next character from the input file attached to FILEHANDLE,
-or the undefined value at end of file, or if there was an error.
-If FILEHANDLE is omitted, reads from STDIN.  This is not particularly
-efficient.  However, it cannot be used by itself to fetch single
-characters without waiting for the user to hit enter.  For that, try
-something more like:
+or the undefined value at end of file, or if there was an error (in
+the latter case C<$!> is set).  If FILEHANDLE is omitted, reads from
+STDIN.  This is not particularly efficient.  However, it cannot be
+used by itself to fetch single characters without waiting for the user
+to hit enter.  For that, try something more like:
 
     if ($BSD_STYLE) {
 	system "stty cbreak </dev/tty >/dev/tty 2>&1";
@@ -1841,6 +1884,13 @@ does not accept a PID argument, so only C<PID==0> is truly portable.
 
 Returns the process id of the parent process.
 
+Note for Linux users: on Linux, the C functions C<getpid()> and
+C<getppid()> return different values from different threads. In order to
+be portable, this behavior is not reflected by the perl-level function
+C<getppid()>, that returns a consistent value across threads. If you want
+to call the underlying C<getppid()>, you may use the CPAN module
+C<Linux::Pid>.
+
 =item getpriority WHICH,WHO
 
 Returns the current priority for a process, a process group, or a user.
@@ -1937,7 +1987,7 @@ lookup by name, in which case you get the other thing, whatever it is.
     $name  = getpwuid($num);
     $name  = getpwent();
     $gid   = getgrnam($name);
-    $name  = getgrgid($num;
+    $name  = getgrgid($num);
     $name  = getgrent();
     #etc.
 
@@ -2021,11 +2071,13 @@ Returns the socket option requested, or undef if there is an error.
 
 =item glob
 
-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<< <*.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">.
+In list context, returns a (possibly empty) list of filename expansions on
+the value of EXPR such as the standard Unix shell F</bin/csh> would do. In
+scalar context, glob iterates through such filename expansions, returning
+undef when the list is exhausted. This is the internal function
+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.
@@ -2261,13 +2313,19 @@ first argument.  Compare L</split>.
 
 =item keys HASH
 
-Returns a list consisting of all the keys of the named hash.  (In
-scalar context, returns the number of keys.)  The keys are returned in
-an apparently random order.  The actual random order is subject to
-change in future versions of perl, but it is guaranteed to be the same
-order as either the C<values> or C<each> function produces (given
-that the hash has not been modified).  As a side effect, it resets
-HASH's iterator.
+Returns a list consisting of all the keys of the named hash.
+(In scalar context, returns the number of keys.)
+
+The keys are returned in an apparently random order.  The actual
+random order is subject to change in future versions of perl, but it
+is guaranteed to be the same order as either the C<values> or C<each>
+function produces (given that the hash has not been modified).  Since
+Perl 5.8.1 the ordering is different even between different runs of
+Perl for security reasons (see L<perlsec/"Algorithmic Complexity
+Attacks">).
+
+As a side effect, calling keys() resets the HASH's internal iterator,
+see L</each>.
 
 Here is yet another way to print your environment:
 
@@ -2320,7 +2378,7 @@ same as the number actually killed).
     kill 9, @goners;
 
 If SIGNAL is zero, no signal is sent to the process.  This is a
-useful way to check that the process is alive and hasn't changed
+useful way to check that a child process is alive and hasn't changed
 its UID.  See L<perlport> for notes on the portability of this
 construct.
 
@@ -2328,7 +2386,9 @@ Unlike in the shell, if SIGNAL is negative, it kills
 process groups instead of processes.  (On System V, a negative I<PROCESS>
 number will also kill process groups, but that's not portable.)  That
 means you usually want to use positive not negative signals.  You may also
-use a signal name in quotes.  See L<perlipc/"Signals"> for details.
+use a signal name in quotes.
+
+See L<perlipc/"Signals"> for more details.
 
 =item last LABEL
 
@@ -2382,11 +2442,15 @@ If EXPR is omitted, uses C<$_>.
 
 =item length
 
-Returns the length in characters of the value of EXPR.  If EXPR is
+Returns the length in I<characters> of the value of EXPR.  If EXPR is
 omitted, returns length of C<$_>.  Note that this cannot be used on
 an entire array or hash to find out how many elements these have.
 For that, use C<scalar @array> and C<scalar keys %hash> respectively.
 
+Note the I<characters>: if the EXPR is in Unicode, you will get the
+number of characters, not the number of bytes.  To get the length
+in bytes, use C<do { use bytes; length(EXPR) }>, see L<bytes>.
+
 =item link OLDFILE,NEWFILE
 
 Creates a new filename linked to the old filename.  Returns true for
@@ -2465,12 +2529,13 @@ and the month of the year, may not necessarily be three characters wide.
 
 =item lock THING
 
-This function places an advisory lock on a variable, subroutine,
-or referenced object contained in I<THING> until the lock goes out
-of scope.  This is a built-in function only if your version of Perl
-was built with threading enabled, and if you've said C<use Thread>.
-Otherwise a user-defined function by this name will be called.
-See L<Thread>.
+This function places an advisory lock on a shared variable, or referenced
+object contained in I<THING> until the lock goes out of scope.
+
+lock() is a "weak keyword" : this means that if you've defined a function
+by this name (before any calls to it), that function will be called
+instead. (However, if you've said C<use threads>, lock() is always a
+keyword.) See L<threads>.
 
 =item log EXPR
 
@@ -2495,7 +2560,8 @@ See also L</exp> for the inverse operation.
 Does the same thing as the C<stat> function (including setting the
 special C<_> filehandle) but stats a symbolic link instead of the file
 the symbolic link points to.  If symbolic links are unimplemented on
-your system, a normal C<stat> is done.
+your system, a normal C<stat> is done.  For much more detailed
+information, please see the documentation for C<stat>.
 
 If EXPR is omitted, stats C<$_>.
 
@@ -2619,12 +2685,22 @@ and C<IPC::SysV::Msg> documentation.
 
 =item my EXPR
 
-=item my EXPR : ATTRIBUTES
+=item my TYPE EXPR
+
+=item my EXPR : ATTRS
+
+=item my TYPE EXPR : ATTRS
 
 A C<my> declares the listed variables to be local (lexically) to the
-enclosing block, file, or C<eval>.  If
-more than one value is listed, the list must be placed in parentheses.  See
-L<perlsub/"Private Variables via my()"> for details.
+enclosing block, file, or C<eval>.  If more than one value is listed,
+the list must be placed in parentheses.
+
+The exact semantics and interface of TYPE and ATTRS are still
+evolving.  TYPE is currently bound to the use of C<fields> pragma,
+and attributes are handled using the C<attributes> pragma, or starting
+from Perl 5.8.0 also via the C<Attribute::Handlers> module.  See
+L<perlsub/"Private Variables via my()"> for details, and L<fields>,
+L<attributes>, and L<Attribute::Handlers>.
 
 =item next LABEL
 
@@ -2660,7 +2736,7 @@ C<redo> work.
 
 =item no Module
 
-See the L</use> function, which C<no> is the opposite of.
+See the C<use> function, which C<no> is the opposite of.
 
 =item oct EXPR
 
@@ -2702,16 +2778,16 @@ FILEHANDLE.
 (The following is a comprehensive reference to open(): for a gentler
 introduction you may consider L<perlopentut>.)
 
-If FILEHANDLE is an undefined lexical (C<my>) variable the variable is
-assigned a reference to a new anonymous filehandle, otherwise if
-FILEHANDLE is an expression, its value is used as the name of the real
-filehandle wanted.  (This is considered a symbolic reference, so C<use
-strict 'refs'> should I<not> be in effect.)
+If FILEHANDLE is an undefined scalar variable (or array or hash element)
+the variable is assigned a reference to a new anonymous filehandle,
+otherwise if FILEHANDLE is an expression, its value is used as the name of
+the real filehandle wanted.  (This is considered a symbolic reference, so
+C<use strict 'refs'> should I<not> be in effect.)
 
 If EXPR is omitted, the scalar variable of the same name as the
 FILEHANDLE contains the filename.  (Note that lexical variables--those
 declared with C<my>--will not work for this purpose; so if you're
-using C<my>, specify EXPR in your call to open.) 
+using C<my>, specify EXPR in your call to open.)
 
 If three or more arguments are specified then the mode of opening and
 the file name are separate. If MODE is C<< '<' >> or nothing, the file
@@ -2765,14 +2841,17 @@ meaning.
 In the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN
 and opening C<< '>-' >> opens STDOUT.
 
-You may use the three-argument form of open to specify
-I<I/O disciplines> that affect how the input and output
-are processed: see L</binmode> and L<open>.  For example
+You may use the three-argument form of open to specify IO "layers"
+(sometimes also referred to as "disciplines") to be applied to the handle
+that affect how the input and output are processed (see L<open> and
+L<PerlIO> for more details). For example
 
   open(FH, "<:utf8", "file")
 
 will open the UTF-8 encoded file containing Unicode characters,
-see L<perluniintro>.
+see L<perluniintro>. (Note that if layers are specified in the
+three-arg form then default layers set by the C<open> pragma are
+ignored.)
 
 Open returns nonzero upon success, the undefined value otherwise.  If
 the C<open> involved a pipe, the return value happens to be the pid of
@@ -2782,15 +2861,10 @@ If you're running Perl on a system that distinguishes between text
 files and binary files, then you should check out L</binmode> for tips
 for dealing with this.  The key distinction between systems that need
 C<binmode> and those that don't is their text file formats.  Systems
-like Unix, MacOS, and Plan9, which delimit lines with a single
+like Unix, Mac OS, and Plan 9, which delimit lines with a single
 character, and which encode that character in C as C<"\n">, do not
 need C<binmode>.  The rest need it.
 
-In the three argument form MODE may also contain a list of IO "layers"
-(see L<open> and L<PerlIO> for more details) to be applied to the
-handle. This can be used to achieve the effect of C<binmode> as well
-as more complex behaviours.
-
 When opening a file, it's usually a bad idea to continue normal execution
 if the request failed, so C<open> is frequently used in connection with
 C<die>.  Even if C<die> won't do what you want (say, in a CGI script,
@@ -2804,11 +2878,20 @@ argument being C<undef>:
 
     open(TMP, "+>", undef) or die ...
 
-opens a filehandle to an anonymous temporary file.
+opens a filehandle to an anonymous temporary file.  Also using "+<"
+works for symmetry, but you really should consider writing something
+to the temporary file first.  You will need to seek() to do the
+reading.
 
 File handles can be opened to "in memory" files held in Perl scalars via:
 
-    open($fh,'>', \$variable) || ..
+    open($fh, '>', \$variable) || ..
+
+Though if you try to re-open C<STDOUT> or C<STDERR> as an "in memory"
+file, you have to close it first:
+
+    close STDOUT;
+    open STDOUT, '>', \$variable or die "Can't open STDOUT: $!";
 
 Examples:
 
@@ -2879,7 +2962,7 @@ C<STDERR> using various methods:
     #!/usr/bin/perl
     open my $oldout, ">&STDOUT"     or die "Can't dup STDOUT: $!";
     open OLDERR,     ">&", \*STDERR or die "Can't dup STDERR: $!";
- 
+
     open STDOUT, '>', "foo.out" or die "Can't redirect STDOUT: $!";
     open STDERR, ">&STDOUT"     or die "Can't dup STDOUT: $!";
 
@@ -2942,7 +3025,9 @@ The following triples are more or less equivalent:
     open(FOO, '-|', "cat", '-n', $file);
 
 The last example in each block shows the pipe as "list form", which is
-not yet supported on all platforms.
+not yet supported on all platforms.  A good rule of thumb is that if
+your platform has true C<fork()> (in other words, if your platform is
+UNIX) you can use the list form.
 
 See L<perlipc/"Safe Pipe Opens"> for more examples of this.
 
@@ -3024,19 +3109,16 @@ them, and automatically close whenever and however you leave that scope:
 
 See L</seek> for some details about mixing reading and writing.
 
-=item opendir DIRHANDLE,MODE,EXPR
-
 =item opendir DIRHANDLE,EXPR
 
 Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
 C<seekdir>, C<rewinddir>, and C<closedir>.  Returns true if successful.
+DIRHANDLE may be an expression whose value can be used as an indirect
+dirhandle, usually the real dirhandle name.  If DIRHANDLE is an undefined
+scalar variable (or array or hash element), the variable is assigned a
+reference to a new anonymous dirhandle.
 DIRHANDLEs have their own namespace separate from FILEHANDLEs.
 
-In three-argument form the middle argument may be C<:utf8> to force
-the filenames returned by readdir() to be in UTF-8 encoding of Unicode.
-This naturally works only if your filesystem returns UTF-8 filenames.
-The encoding pragma affects this feature, see L<encoding>.
-
 =item ord EXPR
 
 =item ord
@@ -3050,7 +3132,11 @@ See L<perlunicode> and L<encoding> for more about Unicode.
 
 =item our EXPR
 
-=item our EXPR : ATTRIBUTES
+=item our EXPR TYPE
+
+=item our EXPR : ATTRS
+
+=item our TYPE EXPR : ATTRS
 
 An C<our> declares the listed variables to be valid globals within
 the enclosing block, file, or C<eval>.  That is, it has the same
@@ -3091,22 +3177,29 @@ package, Perl will emit warnings if you have asked for them.
     our $bar;		# emits warning
 
 An C<our> declaration may also have a list of attributes associated
-with it.  B<WARNING>: This is an experimental feature that may be
-changed or removed in future releases of Perl.  It should not be
-relied upon.
-
-The only currently recognized attribute is C<unique> which indicates
-that a single copy of the global is to be used by all interpreters
-should the program happen to be running in a multi-interpreter
-environment. (The default behaviour would be for each interpreter to
-have its own copy of the global.)  In such an environment, this
-attribute also has the effect of making the global readonly.
-Examples:
+with it.
+
+The exact semantics and interface of TYPE and ATTRS are still
+evolving.  TYPE is currently bound to the use of C<fields> pragma,
+and attributes are handled using the C<attributes> pragma, or starting
+from Perl 5.8.0 also via the C<Attribute::Handlers> module.  See
+L<perlsub/"Private Variables via my()"> for details, and L<fields>,
+L<attributes>, and L<Attribute::Handlers>.
+
+The only currently recognized C<our()> attribute is C<unique> which
+indicates that a single copy of the global is to be used by all
+interpreters should the program happen to be running in a
+multi-interpreter environment. (The default behaviour would be for
+each interpreter to have its own copy of the global.)  Examples:
 
     our @EXPORT : unique = qw(foo);
     our %EXPORT_TAGS : unique = (bar => [qw(aa bb cc)]);
     our $VERSION : unique = "1.00";
 
+Note that this attribute also has the effect of making the global
+readonly when the first new interpreter is cloned (for example,
+when the first new thread is created).
+
 Multi-interpreter environments can come to being either through the
 fork() emulation on Windows platforms, or by embedding perl in a
 multi-threaded application.  The C<unique> attribute does nothing in
@@ -3194,7 +3287,8 @@ of values, as follows:
 
     x	A null byte.
     X	Back up a byte.
-    @	Null fill to absolute position.
+    @	Null fill to absolute position, counted from the start of
+        the innermost ()-group.
     (	Start of a ()-group.
 
 The following rules apply:
@@ -3312,9 +3406,11 @@ how the length value is packed.  The ones likely to be of most use are
 integer-packing ones like C<n> (for Java strings), C<w> (for ASN.1 or
 SNMP) and C<N> (for Sun XDR).
 
-The I<string-item> must, at present, be C<"A*">, C<"a*"> or C<"Z*">.
-For C<unpack> the length of the string is obtained from the I<length-item>,
-but if you put in the '*' it will be ignored.
+For C<pack>, the I<string-item> must, at present, be C<"A*">, C<"a*"> or
+C<"Z*">. For C<unpack> the length of the string is obtained from the
+I<length-item>, but if you put in the '*' it will be ignored. For all other
+codes, C<unpack> applies the length value to the next item, which must not
+have a repeat count.
 
     unpack 'C/a', "\04Gurusamy";        gives 'Guru'
     unpack 'a3/A* A*', '007 Bond  J ';  gives (' Bond','J')
@@ -3352,7 +3448,7 @@ L<Config>:
        print $Config{longsize},     "\n";
        print $Config{longlongsize}, "\n";
 
-(The C<$Config{longlongsize}> will be undefine if your system does
+(The C<$Config{longlongsize}> will be undefined if your system does
 not support long longs.)
 
 =item *
@@ -3435,8 +3531,14 @@ sequences of bytes.
 =item *
 
 A ()-group is a sub-TEMPLATE enclosed in parentheses.  A group may
-take a repeat count, both as postfix, and via the C</> template
-character.
+take a repeat count, both as postfix, and for unpack() also via the C</>
+template character. Within each repetition of a group, positioning with
+C<@> starts again at 0. Therefore, the result of
+
+    pack( '@1A((@2A)@3A)', 'a', 'b', 'c' )
+
+is the string "\0a\0\0bc".
+
 
 =item *
 
@@ -3453,6 +3555,8 @@ both result in no-ops.
 =item *
 
 A comment in a TEMPLATE starts with C<#> and goes to the end of line.
+White space may be used to separate pack codes from each other, but
+a C<!> modifier and a repeat count must follow immediately.
 
 =item *
 
@@ -3686,8 +3790,10 @@ If EXPR is omitted, uses C<$_>.
 
 Returns a random fractional number greater than or equal to C<0> and less
 than the value of EXPR.  (EXPR should be positive.)  If EXPR is
-omitted, or a C<0>, the value C<1> is used.  Automatically calls C<srand>
-unless C<srand> has already been called.  See also C<srand>.
+omitted, the value C<1> is used.  Currently EXPR with the value C<0> is
+also special-cased as C<1> - this has not been documented before perl 5.8.0
+and is subject to change in future versions of perl.  Automatically calls
+C<srand> unless C<srand> has already been called.  See also C<srand>.
 
 Apply C<int()> to the value returned by C<rand()> if you want random
 integers instead of random fractional numbers.  For example,
@@ -3706,19 +3812,28 @@ with the wrong number of RANDBITS.)
 
 Attempts to read LENGTH I<characters> of data into variable SCALAR
 from the specified FILEHANDLE.  Returns the number of characters
-actually read, C<0> at end of file, or undef if there was an error.
-SCALAR will be grown or shrunk to the length actually read.  If SCALAR
-needs growing, the new bytes will be zero bytes.  An OFFSET may be
-specified to place the read data into some other place in SCALAR than
-the beginning.  The call is actually implemented in terms of either
-Perl's or system's fread() call.  To get a true read(2) system call,
-see C<sysread>.
+actually read, C<0> at end of file, or undef if there was an error (in
+the latter case C<$!> is also set).  SCALAR will be grown or shrunk 
+so that the last character actually read is the last character of the
+scalar after the read.
+
+An OFFSET may be specified to place the read data at some place in the
+string other than the beginning.  A negative OFFSET specifies
+placement at that many characters counting backwards from the end of
+the string.  A positive OFFSET greater than the length of SCALAR
+results in the string being padded to the required size with C<"\0">
+bytes before the result of the read is appended.
+
+The call is actually implemented in terms of either Perl's or system's
+fread() call.  To get a true read(2) system call, see C<sysread>.
 
 Note the I<characters>: depending on the status of the filehandle,
 either (8-bit) bytes or characters are read.  By default all
 filehandles operate on bytes, but for example if the filehandle has
-been opened with the C<:utf8> discipline (see L</open>, and the C<open>
-pragma, L<open>), the I/O will operate on characters, not bytes.
+been opened with the C<:utf8> I/O layer (see L</open>, and the C<open>
+pragma, L<open>), the I/O will operate on UTF-8 encoded Unicode
+characters, not bytes.  Similarly for the C<:encoding> pragma:
+in that case pretty much any characters can be read.
 
 =item readdir DIRHANDLE
 
@@ -3735,10 +3850,6 @@ C<chdir> there, it would have been testing the wrong file.
     @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
     closedir DIR;
 
-In some filesystems it is possible to return UTF-8 encoded filenames.
-To get readdir() to return such filenames, you must use C<:utf8> with
-the three-argument form of opendir(), see L</opendir>.
-
 =item readline EXPR
 
 Reads from the filehandle whose typeglob is contained in EXPR.  In scalar
@@ -3759,6 +3870,21 @@ operator is discussed in more detail in L<perlop/"I/O Operators">.
     $line = <STDIN>;
     $line = readline(*STDIN);		# same thing
 
+If readline encounters an operating system error, C<$!> will be set with the
+corresponding error message.  It can be helpful to check C<$!> when you are
+reading from filehandles you don't trust, such as a tty or a socket.  The
+following example uses the operator form of C<readline>, and takes the necessary
+steps to ensure that C<readline> was successful.
+
+    for (;;) {
+        undef $!;
+        unless (defined( $line = <> )) {
+            die $! if $!;
+            last; # reached EOF
+        }
+        # ...
+    }
+
 =item readlink EXPR
 
 =item readlink
@@ -3793,8 +3919,10 @@ See L<perlipc/"UDP: Message Passing"> for examples.
 Note the I<characters>: depending on the status of the socket, either
 (8-bit) bytes or characters are received.  By default all sockets
 operate on bytes, but for example if the socket has been changed using
-binmode() to operate with the C<:utf8> discipline (see the C<open>
-pragma, L<open>), the I/O will operate on characters, not bytes.
+binmode() to operate with the C<:utf8> I/O layer (see the C<open>
+pragma, L<open>), the I/O will operate on UTF-8 encoded Unicode
+characters, not bytes.  Similarly for the C<:encoding> pragma:
+in that case pretty much any characters can be read.
 
 =item redo LABEL
 
@@ -3959,6 +4087,15 @@ will complain about not finding "F<Foo::Bar>" there.  In this case you can do:
 
         eval "require $class";
 
+Now that you understand how C<require> looks for files in the case of
+a bareword argument, there is a little extra functionality going on
+behind the scenes.  Before C<require> looks for a "F<.pm>" extension,
+it will first look for a filename with a "F<.pmc>" extension.  A file
+with this extension is assumed to be Perl bytecode generated by
+L<B::Bytecode|B::Bytecode>.  If this file is found, and it's modification
+time is newer than a coinciding "F<.pm>" non-compiled file, it will be
+loaded in place of that non-compiled file ending in a "F<.pm>" extension.
+
 You can also insert hooks into the import facility, by putting directly
 Perl code into the @INC array.  There are three forms of hooks: subroutine
 references, array references and blessed objects.
@@ -4090,9 +4227,9 @@ last occurrence at or before that position.
 
 =item rmdir
 
-Deletes the directory specified by FILENAME if that directory is empty.  If it
-succeeds it returns true, otherwise it returns false and sets C<$!> (errno).  If
-FILENAME is omitted, uses C<$_>.
+Deletes the directory specified by FILENAME if that directory is
+empty.  If it succeeds it returns true, otherwise it returns false and
+sets C<$!> (errno).  If FILENAME is omitted, uses C<$_>.
 
 =item s///
 
@@ -4141,7 +4278,7 @@ otherwise.
 
 Note the I<in bytes>: even if the filehandle has been set to
 operate on characters (for example by using the C<:utf8> open
-discipline), tell() will return byte offsets, not character offsets
+layer), tell() will return byte offsets, not character offsets
 (because implementing that would render seek() and tell() rather slow).
 
 If you want to position file for C<sysread> or C<syswrite>, don't use
@@ -4252,6 +4389,9 @@ You can effect a sleep of 250 milliseconds this way:
 
     select(undef, undef, undef, 0.25);
 
+Note that whether C<select> gets restarted after signals (say, SIGALRM)
+is implementation-dependent.
+
 B<WARNING>: One should not attempt to mix buffered I/O (like C<read>
 or <FH>) with C<select>, except as permitted by POSIX, and even
 then only on POSIX systems.  You have to use C<sysread> instead.
@@ -4310,9 +4450,10 @@ L<perlipc/"UDP: Message Passing"> for examples.
 Note the I<characters>: depending on the status of the socket, either
 (8-bit) bytes or characters are sent.  By default all sockets operate
 on bytes, but for example if the socket has been changed using
-binmode() to operate with the C<:utf8> discipline (see L</open>, or
-the C<open> pragma, L<open>), the I/O will operate on characters, not
-bytes.
+binmode() to operate with the C<:utf8> I/O layer (see L</open>, or the
+C<open> pragma, L<open>), the I/O will operate on UTF-8 encoded
+Unicode characters, not bytes.  Similarly for the C<:encoding> pragma:
+in that case pretty much any characters can be sent.
 
 =item setpgrp PID,PGRP
 
@@ -4433,26 +4574,6 @@ help.
 
 See also the POSIX module's C<pause> function.
 
-=item sockatmark SOCKET
-
-Returns true if the socket is positioned at the out-of-band mark
-(also known as the urgent data mark), false otherwise.  Use right
-after reading from the socket.
-
-Not available directly, one has to import the function from
-the IO::Socket extension
-
-    use IO::Socket 'sockatmark';
-
-Even this doesn't guarantee that sockatmark() really is available,
-though, because sockatmark() is a relatively recent addition to
-the family of socket functions.  If it is unavailable, attempt to
-use it will fail
-
-	IO::Socket::atmark not implemented on this architecture ...
-
-See also L<IO::Socket>.
-
 =item socket SOCKET,DOMAIN,TYPE,PROTOCOL
 
 Opens a socket of the specified kind and attaches it to filehandle
@@ -4494,16 +4615,18 @@ sockets but not socketpair.
 
 =item sort LIST
 
-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<< <=> >> 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
-of a SUBNAME, you can provide a BLOCK as an anonymous, in-line sort
-subroutine.
+In list context, this sorts the LIST and returns the sorted list value.
+In scalar context, the behaviour of C<sort()> is undefined.
+
+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<<
+<=> >> 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 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.  This is
@@ -4534,7 +4657,7 @@ the original quicksort was faster.  5.8 has a sort pragma for
 limited control of the sort.  Its rather blunt control of the
 underlying algorithm may not persist into future perls, but the
 ability to characterize the input or output in implementation
-independent ways quite probably will.  See L</use>.
+independent ways quite probably will.  See L<sort>.
 
 Examples:
 
@@ -4625,12 +4748,6 @@ Examples:
     use sort '_mergesort';  # note discouraging _
     @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
 
-    # Similar to the previous example, but demand stability as well
-    # Because of the way quicksort is "stabilized", this combination
-    # is not threadsafe
-    use sort qw( _quicksort stable );
-    @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
-
 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 and type
@@ -4647,6 +4764,15 @@ inconsistent results (sometimes saying C<$x[1]> is less than C<$x[2]> and
 sometimes saying the opposite, for example) the results are not
 well-defined.
 
+Because C<< <=> >> returns C<undef> when either operand is C<NaN>
+(not-a-number), and because C<sort> will trigger a fatal error unless the
+result of a comparison is defined, when sorting with a comparison function
+like C<< $a <=> $b >>, be careful about lists that might contain a C<NaN>.
+The following example takes advantage of the fact that C<NaN != NaN> to
+eliminate any C<NaN>s from the input.
+
+    @result = sort { $a <=> $b } grep { $_ == $_ } @input;
+
 =item splice ARRAY,OFFSET,LENGTH,LIST
 
 =item splice ARRAY,OFFSET,LENGTH
@@ -4668,13 +4794,13 @@ If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is
 past the end of the array, perl issues a warning, and splices at the
 end of the array.
 
-The following equivalences hold (assuming C<$[ == 0>):
+The following equivalences hold (assuming C<< $[ == 0 and $#a >= $i >> )
 
     push(@a,$x,$y)	splice(@a,@a,0,$x,$y)
     pop(@a)		splice(@a,-1)
     shift(@a)		splice(@a,0,1)
     unshift(@a,$x,$y)	splice(@a,0,0,$x,$y)
-    $a[$x] = $y		splice(@a,$x,1,$y)
+    $a[$i] = $y		splice(@a,$i,1,$y)
 
 Example, assuming array lengths are passed before arrays:
 
@@ -4745,8 +4871,8 @@ The LIMIT parameter can be used to split a line partially
 
     ($login, $passwd, $remainder) = split(/:/, $_, 3);
 
-When assigning to a list, if LIMIT is omitted, Perl supplies a LIMIT
-one larger than the number of variables in the list, to avoid
+When assigning to a list, if LIMIT is omitted, or zero, Perl supplies
+a LIMIT one larger than the number of variables in the list, to avoid
 unnecessary work.  For the list above LIMIT would have been 4 by
 default.  In time critical applications it behooves you not to split
 into more fields than you really need.
@@ -4770,13 +4896,13 @@ The pattern C</PATTERN/> may be replaced with an expression to specify
 patterns that vary at runtime.  (To do runtime compilation only once,
 use C</$variable/o>.)
 
-As a special case, specifying a PATTERN of space (C<' '>) will split on
-white space just as C<split> with no arguments does.  Thus, C<split(' ')> can
-be used to emulate B<awk>'s default behavior, whereas C<split(/ /)>
+As a special case, specifying a PATTERN of space (S<C<' '>>) will split on
+white space just as C<split> with no arguments does.  Thus, S<C<split(' ')>> can
+be used to emulate B<awk>'s default behavior, whereas S<C<split(/ /)>>
 will give you as many null initial fields as there are leading spaces.
-A C<split> on C</\s+/> is like a C<split(' ')> except that any leading
+A C<split> on C</\s+/> is like a S<C<split(' ')>> except that any leading
 whitespace produces a null first field.  A C<split> with no arguments
-really does a C<split(' ', $_)> internally.
+really does a S<C<split(' ', $_)>> internally.
 
 A PATTERN of C</^/> is treated as if it were C</^/m>, since it isn't
 much use otherwise.
@@ -4856,109 +4982,220 @@ 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
+Note that the number of exponent digits in the scientific notation produced
+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:
+Between the C<%> and the format letter, you may specify a number of
+additional attributes controlling the interpretation of the format.
+In order, these are:
+
+=over 4
+
+=item format parameter index
+
+An explicit format parameter index, such as C<2$>. By default sprintf
+will format the next unused argument in the list, but this allows you
+to take the arguments out of order. Eg:
 
+  printf '%2$d %1$d', 12, 34;      # prints "34 12"
+  printf '%3$d %d %1$d', 1, 2, 3;  # prints "3 1 1"
+
+=item flags
+
+one or more of:
    space   prefix positive number with a space
    +       prefix positive number with a plus sign
    -       left-justify within the field
    0       use zeros, not spaces, to right-justify
-   #       prefix non-zero octal with "0", non-zero hex with "0x"
-   number  minimum field width
-   .number "precision": digits after decimal point for
-           floating-point, max length for string, minimum length
-           for integer
-   l       interpret integer as C type "long" or "unsigned long"
-   h       interpret integer as C type "short" or "unsigned short"
-           If no flags, interpret integer as C type "int" or "unsigned"
-
-Perl supports parameter ordering, in other words, fetching the
-parameters in some explicitly specified "random" ordering as opposed
-to the default implicit sequential ordering.  The syntax is, instead
-of the C<%> and C<*>, to use C<%>I<digits>C<$> and C<*>I<digits>C<$>,
-where the I<digits> is the wanted index, from one upwards.  For example:
-
-   printf "%2\$d %1\$d\n", 12, 34;		# will print "34 12\n"
-   printf "%*2\$d\n",      12, 3;		# will print " 12\n"
-
-Note that using the reordering syntax does not interfere with the usual
-implicit sequential fetching of the parameters:
-
-   printf "%2\$d %d\n",    12, 34;		# will print "34 12\n"
-   printf "%2\$d %d %d\n", 12, 34;		# will print "34 12 34\n"
-   printf "%3\$d %d %d\n", 12, 34, 56;		# will print "56 12 34\n"
-   printf "%2\$*3\$d %d\n", 12, 34, 3;		# will print " 34 12\n"
-   printf "%*3\$2\$d %d\n", 12, 34, 3;		# will print " 34 12\n"
-
-There are also two Perl-specific flags:
-
-    V       interpret integer as Perl's standard integer type
-    v       interpret string as a vector of integers, output as
-            numbers separated either by dots, or by an arbitrary
-	    string received from the argument list when the flag
-	    is preceded by "*"
-
-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
-list as the given number (that is, as the field width or precision).
+   #       prefix non-zero octal with "0", non-zero hex with "0x",
+           non-zero binary with "0b"
+
+For example:
+
+  printf '<% d>', 12;   # prints "< 12>"
+  printf '<%+d>', 12;   # prints "<+12>"
+  printf '<%6s>', 12;   # prints "<    12>"
+  printf '<%-6s>', 12;  # prints "<12    >"
+  printf '<%06s>', 12;  # prints "<000012>"
+  printf '<%#x>', 12;   # prints "<0xc>"
+
+=item vector flag
+
+The vector flag C<v>, optionally specifying the join string to use.
+This flag tells perl to interpret the supplied string as a vector
+of integers, one for each character in the string, separated by
+a given string (a dot C<.> by default). This can be useful for
+displaying ordinal values of characters in arbitrary strings:
+
+  printf "version is v%vd\n", $^V;     # Perl's version
+
+Put an asterisk C<*> before the C<v> to override the string to
+use to separate the numbers:
+
+  printf "address is %*vX\n", ":", $addr;   # IPv6 address
+  printf "bits are %0*v8b\n", " ", $bits;   # random bitstring
+
+You can also explicitly specify the argument number to use for
+the join string using eg C<*2$v>:
+
+  printf '%*4$vX %*4$vX %*4$vX', @addr[1..3], ":";   # 3 IPv6 addresses
+
+=item (minimum) width
+
+Arguments are usually formatted to be only as wide as required to
+display the given value. You can override the width by putting
+a number here, or get the width from the next argument (with C<*>)
+or from a specified argument (with eg C<*2$>):
+
+  printf '<%s>', "a";       # prints "<a>"
+  printf '<%6s>', "a";      # prints "<     a>"
+  printf '<%*s>', 6, "a";   # prints "<     a>"
+  printf '<%*2$s>', "a", 6; # prints "<     a>"
+  printf '<%2s>', "long";   # prints "<long>" (does not truncate)
+
 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:
+=item precision, or maximum width
 
-    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
+You can specify a precision (for numeric conversions) or a maximum
+width (for string conversions) by specifying a C<.> followed by a number.
+For floating point formats, with the exception of 'g' and 'G', this specifies
+the number of decimal places to show (the default being 6), eg:
 
-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>.
+  # these examples are subject to system-specific variation
+  printf '<%f>', 1;    # prints "<1.000000>"
+  printf '<%.1f>', 1;  # prints "<1.0>"
+  printf '<%.0f>', 1;  # prints "<1>"
+  printf '<%e>', 10;   # prints "<1.000000e+01>"
+  printf '<%.1e>', 10; # prints "<1.0e+01>"
 
-If Perl understands "quads" (64-bit integers) (this requires
-either that the platform natively support quads or that Perl
-be specifically compiled to support quads), the characters
+For 'g' and 'G', this specifies the maximum number of digits to show,
+including prior to the decimal point as well as after it, eg:
 
-	d u o x X b i D U O
+  # these examples are subject to system-specific variation
+  printf '<%g>', 1;        # prints "<1>"
+  printf '<%.10g>', 1;     # prints "<1>"
+  printf '<%g>', 100;      # prints "<100>"
+  printf '<%.1g>', 100;    # prints "<1e+02>"
+  printf '<%.2g>', 100.01; # prints "<1e+02>"
+  printf '<%.5g>', 100.01; # prints "<100.01>"
+  printf '<%.4g>', 100.01; # prints "<100>"
 
-print quads, and they may optionally be preceded by
+For integer conversions, specifying a precision implies that the
+output of the number itself should be zero-padded to this width:
 
-	ll L q
+  printf '<%.6x>', 1;      # prints "<000001>"
+  printf '<%#.6x>', 1;     # prints "<0x000001>"
+  printf '<%-10.6x>', 1;   # prints "<000001    >"
 
-For example
+For string conversions, specifying a precision truncates the string
+to fit in the specified width:
 
-	%lld %16LX %qo
+  printf '<%.5s>', "truncated";   # prints "<trunc>"
+  printf '<%10.5s>', "truncated"; # prints "<     trunc>"
 
-You can find out whether your Perl supports quads via L<Config>:
+You can also get the precision from the next argument using C<.*>:
 
-	use Config;
-	($Config{use64bitint} eq 'define' || $Config{longsize} == 8) &&
-		print "quads\n";
+  printf '<%.6x>', 1;       # prints "<000001>"
+  printf '<%.*x>', 6, 1;    # prints "<000001>"
 
-If Perl understands "long doubles" (this requires that the platform
-support long doubles), the flags
+You cannot currently get the precision from a specified number,
+but it is intended that this will be possible in the future using
+eg C<.*2$>:
 
-	e f g E F G
+  printf '<%.*2$x>', 1, 6;   # INVALID, but in future will print "<000001>"
 
-may optionally be preceded by
+=item size
 
-	ll L
+For numeric conversions, you can specify the size to interpret the
+number as using C<l>, C<h>, C<V>, C<q>, C<L>, or C<ll>. For integer
+conversions (C<d u o x X b i D U O>), numbers are usually assumed to be
+whatever the default integer size is on your platform (usually 32 or 64
+bits), but you can override this to use instead one of the standard C types,
+as supported by the compiler used to build Perl:
 
-For example
+   l           interpret integer as C type "long" or "unsigned long"
+   h           interpret integer as C type "short" or "unsigned short"
+   q, L or ll  interpret integer as C type "long long", "unsigned long long".
+               or "quads" (typically 64-bit integers)
 
-	%llf %Lg
+The last will produce errors if Perl does not understand "quads" in your
+installation. (This requires that either the platform natively supports quads
+or Perl was specifically compiled to support quads.) You can find out
+whether your Perl supports quads via L<Config>:
 
-You can find out whether your Perl supports long doubles via L<Config>:
+	use Config;
+	($Config{use64bitint} eq 'define' || $Config{longsize} >= 8) &&
+		print "quads\n";
+
+For floating point conversions (C<e f g E F G>), numbers are usually assumed
+to be the default floating point size on your platform (double or long double),
+but you can force 'long double' with C<q>, C<L>, or C<ll> if your
+platform supports them. You can find out whether your Perl supports long
+doubles via L<Config>:
 
 	use Config;
 	$Config{d_longdbl} eq 'define' && print "long doubles\n";
 
+You can find out whether Perl considers 'long double' to be the default
+floating point size to use on your platform via L<Config>:
+
+        use Config;
+        ($Config{uselongdouble} eq 'define') &&
+                print "long doubles by default\n";
+
+It can also be the case that long doubles and doubles are the same thing:
+
+        use Config;
+        ($Config{doublesize} == $Config{longdblsize}) &&
+                print "doubles are long doubles\n";
+
+The size specifier C<V> has no effect for Perl code, but it is supported
+for compatibility with XS code; it means 'use the standard size for
+a Perl integer (or floating-point number)', which is already the
+default for Perl code.
+
+=item order of arguments
+
+Normally, sprintf takes the next unused argument as the value to
+format for each format specification. If the format specification
+uses C<*> to require additional arguments, these are consumed from
+the argument list in the order in which they appear in the format
+specification I<before> the value to format. Where an argument is
+specified using an explicit index, this does not affect the normal
+order for the arguments (even when the explicitly specified index
+would have been the next argument in any case).
+
+So:
+
+  printf '<%*.*s>', $a, $b, $c;
+
+would use C<$a> for the width, C<$b> for the precision and C<$c>
+as the value to format, while:
+
+  print '<%*1$.*s>', $a, $b;
+
+would use C<$a> for the width and the precision, and C<$b> as the
+value to format.
+
+Here are some more examples - beware that when using an explicit
+index, the C<$> may need to be escaped:
+
+  printf "%2\$d %d\n",    12, 34;		# will print "34 12\n"
+  printf "%2\$d %d %d\n", 12, 34;		# will print "34 12 34\n"
+  printf "%3\$d %d %d\n", 12, 34, 56;		# will print "56 12 34\n"
+  printf "%2\$*3\$d %d\n", 12, 34, 3;		# will print " 34 12\n"
+
+=back
+
+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>.
+
 =item sqrt EXPR
 
 =item sqrt
@@ -4989,7 +5226,7 @@ Most programs won't even call srand() at all, except those that
 need a cryptographically-strong starting point rather than the
 generally acceptable default, which is based on time of day,
 process ID, and memory allocation, or the F</dev/urandom> device,
-if available. 
+if available.
 
 You can call srand($seed) with the same $seed to reproduce the
 I<same> sequence from rand(), but this is usually reserved for
@@ -5059,12 +5296,16 @@ meaning of the fields:
   7 size     total size of file, in bytes
   8 atime    last access time in seconds since the epoch
   9 mtime    last modify time in seconds since the epoch
- 10 ctime    inode change time (NOT creation time!) in seconds since the epoch
+ 10 ctime    inode change time in seconds since the epoch (*)
  11 blksize  preferred block size for file system I/O
  12 blocks   actual number of blocks allocated
 
 (The epoch was at 00:00 January 1, 1970 GMT.)
 
+(*) The ctime field is non-portable, in particular you cannot expect
+it to be a "creation time", see L<perlport/"Files and Filesystems">
+for details.
+
 If stat is passed the special filehandle consisting of an underline, no
 stat is done, but the current contents of the stat structure from the
 last stat or filetest are returned.  Example:
@@ -5106,7 +5347,7 @@ You can import symbolic mode constants (C<S_IF*>) and functions
     $group_read    = ($mode & S_IRGRP) >> 3;
     $other_execute =  $mode & S_IXOTH;
 
-    printf "Permissions are %04o\n", S_ISMODE($mode), "\n";
+    printf "Permissions are %04o\n", S_IMODE($mode), "\n";
 
     $is_setuid     =  $mode & S_ISUID;
     $is_setgid     =  S_ISDIR($mode);
@@ -5120,7 +5361,8 @@ The commonly available S_IF* constants are
     S_IRWXG S_IRGRP S_IWGRP S_IXGRP
     S_IRWXO S_IROTH S_IWOTH S_IXOTH
 
-    # Setuid/Setgid/Stickiness.
+    # Setuid/Setgid/Stickiness/SaveText.
+    # Note that the exact meaning of these is system dependent.
 
     S_ISUID S_ISGID S_ISVTX S_ISTXT
 
@@ -5134,7 +5376,7 @@ The commonly available S_IF* constants are
 
 and the S_IF* functions are
 
-    S_IFMODE($mode)	the part of $mode containing the permission bits
+    S_IMODE($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
@@ -5153,7 +5395,8 @@ and the S_IF* functions are
     S_ISENFMT($mode) S_ISWHT($mode)
 
 See your native chmod(2) and stat(2) documentation for more details
-about the S_* constants.
+about the S_* constants.  To get status info for a symbolic link
+instead of the target file behind the link, use the C<lstat> function.
 
 =item study SCALAR
 
@@ -5214,17 +5457,22 @@ out the names of those files that contain a match:
 	print $file, "\n";
     }
 
-=item sub BLOCK
+=item sub NAME BLOCK
 
-=item sub NAME
+=item sub NAME (PROTO) BLOCK
 
-=item sub NAME BLOCK
+=item sub NAME : ATTRS BLOCK
 
-This is subroutine definition, not a real function I<per se>.  With just a
-NAME (and possibly prototypes or attributes), it's just a forward declaration.
-Without a NAME, it's an anonymous function declaration, and does actually
-return a value: the CODE ref of the closure you just created.  See L<perlsub>
-and L<perlref> for details.
+=item sub NAME (PROTO) : ATTRS BLOCK
+
+This is subroutine definition, not a real function I<per se>.
+Without a BLOCK it's just a forward declaration.  Without a NAME,
+it's an anonymous function declaration, and does actually return
+a value: the CODE ref of the closure you just created.
+
+See L<perlsub> and L<perlref> for details about subroutines and
+references, and L<attributes> and L<Attribute::Handlers> for more
+information about attributes.
 
 =item substr EXPR,OFFSET,LENGTH,REPLACEMENT
 
@@ -5263,6 +5511,16 @@ replacement string as the 4th argument.  This allows you to replace
 parts of the EXPR and return what was there before in one operation,
 just as you can with splice().
 
+If the lvalue returned by substr is used after the EXPR is changed in
+any way, the behaviour may not be as expected and is subject to change.
+This caveat includes code such as C<print(substr($foo,$a,$b)=$bar)> or
+C<(substr($foo,$a,$b)=$bar)=$fud> (where $foo is changed via the
+substring assignment, and then the substr is used again), or where a
+substr() is aliased via a C<foreach> loop or passed as a parameter or
+a reference to it is taken and then the alias, parameter, or deref'd
+reference either is used after the original EXPR has been changed or
+is assigned to and then used a second time.
+
 =item symlink OLDFILE,NEWFILE
 
 Creates a new filename symbolically linked to the old filename.
@@ -5272,7 +5530,7 @@ use eval:
 
     $symlink_exists = eval { symlink("",""); 1 };
 
-=item syscall LIST
+=item syscall NUMBER, LIST
 
 Calls the system call specified as the first element of the list,
 passing the remaining elements as arguments to the system call.  If
@@ -5363,20 +5621,15 @@ See L<perlopentut> for a kinder, gentler explanation of opening files.
 
 =item sysread FILEHANDLE,SCALAR,LENGTH
 
-Attempts to read LENGTH I<characters> of data into variable SCALAR from
-the specified FILEHANDLE, using the system call read(2).  It bypasses
+Attempts to read LENGTH bytes of data into variable SCALAR from the
+specified FILEHANDLE, using the system call read(2).  It bypasses
 buffered IO, so mixing this with other kinds of reads, C<print>,
-C<write>, C<seek>, C<tell>, or C<eof> can cause confusion because
-stdio usually buffers data.  Returns the number of characters actually
-read, C<0> at end of file, or undef if there was an error.  SCALAR
-will be grown or shrunk so that the last byte actually read is the
-last byte of the scalar after the read.
-
-Note the I<characters>: depending on the status of the filehandle,
-either (8-bit) bytes or characters are read.  By default all
-filehandles operate on bytes, but for example if the filehandle has
-been opened with the C<:utf8> discipline (see L</open>, and the C<open>
-pragma, L<open>), the I/O will operate on characters, not bytes.
+C<write>, C<seek>, C<tell>, or C<eof> can cause confusion because the
+perlio or stdio layers usually buffers data.  Returns the number of
+bytes actually read, C<0> at end of file, or undef if there was an
+error (in the latter case C<$!> is also set).  SCALAR will be grown or
+shrunk so that the last byte actually read is the last byte of the
+scalar after the read.
 
 An OFFSET may be specified to place the read data at some place in the
 string other than the beginning.  A negative OFFSET specifies
@@ -5389,9 +5642,15 @@ There is no syseof() function, which is ok, since eof() doesn't work
 very well on device files (like ttys) anyway.  Use sysread() and check
 for a return value for 0 to decide whether you're done.
 
+Note that if the filehandle has been marked as C<:utf8> Unicode
+characters are read instead of bytes (the LENGTH, OFFSET, and the
+return value of sysread() are in Unicode characters).
+The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
+See L</binmode>, L</open>, and the C<open> pragma, L<open>.
+
 =item sysseek FILEHANDLE,POSITION,WHENCE
 
-Sets FILEHANDLE's system position I<in bytes> using the system call
+Sets FILEHANDLE's system position in bytes using the system call
 lseek(2).  FILEHANDLE may be an expression whose value gives the name
 of the filehandle.  The values for WHENCE are C<0> to set the new
 position to POSITION, C<1> to set the it to the current position plus
@@ -5399,11 +5658,11 @@ POSITION, and C<2> to set it to EOF plus POSITION (typically
 negative).
 
 Note the I<in bytes>: even if the filehandle has been set to operate
-on characters (for example by using the C<:utf8> discipline), tell()
+on characters (for example by using the C<:utf8> I/O layer), tell()
 will return byte offsets, not character offsets (because implementing
 that would render sysseek() very slow).
 
-sysseek() bypasses normal buffered io, so mixing this with reads (other
+sysseek() bypasses normal buffered IO, so mixing this with reads (other
 than C<sysread>, for example &gt;&lt or read()) C<print>, C<write>,
 C<seek>, C<tell>, or C<eof> may cause confusion.
 
@@ -5412,7 +5671,7 @@ and C<SEEK_END> (start of the file, current position, end of the file)
 from the Fcntl module.  Use of the constants is also more portable
 than relying on 0, 1, and 2.  For example to define a "systell" function:
 
-	use Fnctl 'SEEK_CUR';
+	use Fcntl 'SEEK_CUR';
 	sub systell { sysseek($_[0], 0, SEEK_CUR) }
 
 Returns the new position, or the undefined value on failure.  A position
@@ -5482,13 +5741,14 @@ See L<perlop/"`STRING`"> and L</exec> for details.
 
 =item syswrite FILEHANDLE,SCALAR
 
-Attempts to write LENGTH characters of data from variable SCALAR to
-the specified FILEHANDLE, using the system call write(2).  If LENGTH
-is not specified, writes whole SCALAR.  It bypasses buffered IO, so
+Attempts to write LENGTH bytes of data from variable SCALAR to the
+specified FILEHANDLE, using the system call write(2).  If LENGTH is
+not specified, writes whole SCALAR.  It bypasses buffered IO, so
 mixing this with reads (other than C<sysread())>, C<print>, C<write>,
-C<seek>, C<tell>, or C<eof> may cause confusion because stdio usually
-buffers data.  Returns the number of characters actually written, or
-C<undef> if there was an error.  If the LENGTH is greater than the
+C<seek>, C<tell>, or C<eof> may cause confusion because the perlio and
+stdio layers usually buffers data.  Returns the number of bytes
+actually written, or C<undef> if there was an error (in this case the
+errno variable C<$!> is also set).  If the LENGTH is greater than the
 available data in the SCALAR after the OFFSET, only as much data as is
 available will be written.
 
@@ -5497,11 +5757,11 @@ string other than the beginning.  A negative OFFSET specifies writing
 that many characters counting backwards from the end of the string.
 In the case the SCALAR is empty you can use OFFSET but only zero offset.
 
-Note the I<characters>: depending on the status of the filehandle,
-either (8-bit) bytes or characters are written.  By default all
-filehandles operate on bytes, but for example if the filehandle has
-been opened with the C<:utf8> discipline (see L</open>, and the open
-pragma, L<open>), the I/O will operate on characters, not bytes.
+Note that if the filehandle has been marked as C<:utf8>, Unicode
+characters are written instead of bytes (the LENGTH, OFFSET, and the
+return value of syswrite() are in UTF-8 encoded Unicode characters).
+The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
+See L</binmode>, L</open>, and the C<open> pragma, L<open>.
 
 =item tell FILEHANDLE
 
@@ -5514,7 +5774,7 @@ last read.
 
 Note the I<in bytes>: even if the filehandle has been set to
 operate on characters (for example by using the C<:utf8> open
-discipline), tell() will return byte offsets, not character offsets
+layer), tell() will return byte offsets, not character offsets
 (because that would render seek() and tell() rather slow).
 
 The return value of tell() for the standard streams like the STDIN
@@ -5636,14 +5896,15 @@ package.
 =item time
 
 Returns the number of non-leap seconds since whatever time the system
-considers to be the epoch (that's 00:00:00, January 1, 1904 for MacOS,
+considers to be the epoch (that's 00:00:00, January 1, 1904 for Mac OS,
 and 00:00:00 UTC, January 1, 1970 for most other systems).
 Suitable for feeding to C<gmtime> and C<localtime>.
 
 For measuring time in better granularity than one second,
-you may use either the Time::HiRes module from CPAN, or
-if you have gettimeofday(2), you may be able to use the
-C<syscall> interface of Perl, see L<perlfaq8> for details.
+you may use either the Time::HiRes module (from CPAN, and starting from
+Perl 5.8 part of the standard distribution), or if you have
+gettimeofday(2), you may be able to use the C<syscall> interface of Perl.
+See L<perlfaq8> for details.
 
 =item times
 
@@ -5667,6 +5928,9 @@ specified length.  Produces a fatal error if truncate isn't implemented
 on your system.  Returns true if successful, the undefined value
 otherwise.
 
+The behavior is undefined if LENGTH is greater than the length of the
+file.
+
 =item uc EXPR
 
 =item uc
@@ -5735,7 +5999,7 @@ string of octal digits.  See also L</oct>, if all you have is a string.
 
 Undefines the value of EXPR, which must be an lvalue.  Use only on a
 scalar value, an array (using C<@>), a hash (using C<%>), a subroutine
-(using C<&>), or a typeglob (using <*>).  (Saying C<undef $hash{$key}>
+(using C<&>), or a typeglob (using C<*>).  (Saying C<undef $hash{$key}>
 will probably not do what you expect on most predefined variables or
 DBM list values, so don't do that; see L<delete>.)  Always returns the
 undefined value.  You can omit the EXPR, in which case nothing is
@@ -5775,10 +6039,14 @@ If LIST is omitted, uses C<$_>.
 
 =item unpack TEMPLATE,EXPR
 
+=item unpack TEMPLATE
+
 C<unpack> does the reverse of C<pack>: it takes a string
 and expands it out into a list of values.
 (In scalar context, it returns merely the first value produced.)
 
+If EXPR is omitted, unpacks the C<$_> string.
+
 The string is broken into chunks described by the TEMPLATE.  Each chunk
 is converted separately to a value.  Typically, either the string is a result
 of C<pack>, or the bytes of the string represent a C structure of some
@@ -5820,15 +6088,19 @@ has no way of checking whether the value passed to C<unpack()>
 corresponds to a valid memory location, passing a pointer value that's
 not known to be valid is likely to have disastrous consequences.
 
-If the repeat count of a field is larger than what the remainder of
-the input string allows, repeat count is decreased.  If the input string
-is longer than one described by the TEMPLATE, the rest is ignored.
+If there are more pack codes or if the repeat count of a field or a group
+is larger than what the remainder of the input string allows, the result
+is not well defined: in some cases, the repeat count is decreased, or
+C<unpack()> will produce null strings or zeroes, or terminate with an
+error. If the input string is longer than one described by the TEMPLATE,
+the rest is ignored.
 
 See L</pack> for more examples and notes.
 
 =item untie VARIABLE
 
 Breaks the binding between a variable and a package.  (See C<tie>.)
+Has no effect if the variable is not tied.
 
 =item unshift ARRAY,LIST
 
@@ -5933,8 +6205,6 @@ by C<use>, i.e., it calls C<unimport Module LIST> instead of C<import>.
     no strict 'refs';
     no warnings;
 
-If no C<unimport> method can be found the call fails with a fatal error.
-
 See L<perlmodlib> for a list of standard modules and pragmas.  See L<perlrun>
 for the C<-M> and C<-m> command-line options to perl that give C<use>
 functionality from the command-line.
@@ -5945,28 +6215,39 @@ Changes the access and modification times on each file of a list of
 files.  The first two elements of the list must be the NUMERICAL access
 and modification times, in that order.  Returns the number of files
 successfully changed.  The inode change time of each file is set
-to the current time.  This code has the same effect as the C<touch>
-command if the files already exist:
+to the current time.  For example, this code has the same effect as the
+Unix touch(1) command when the files I<already exist>.
 
     #!/usr/bin/perl
     $now = time;
     utime $now, $now, @ARGV;
 
-If the first two elements of the list are C<undef>, then the utime(2)
-function in the C library will be called with a null second argument.
-On most systems, this will set the file's access and modification
-times to the current time.  (i.e. equivalent to the example above.)
+B<Note:>  Under NFS, touch(1) uses the time of the NFS server, not
+the time of the local machine.  If there is a time synchronization
+problem, the NFS server and local machine will have different times.
+
+Since perl 5.7.2, if the first two elements of the list are C<undef>, then
+the utime(2) function in the C library will be called with a null second
+argument. On most systems, this will set the file's access and
+modification times to the current time (i.e. equivalent to the example
+above.)
 
     utime undef, undef, @ARGV;
 
 =item values HASH
 
-Returns a list consisting of all the values of the named hash.  (In a
-scalar context, returns the number of values.)  The values are
-returned in an apparently random order.  The actual random order is
-subject to change in future versions of perl, but it is guaranteed to
-be the same order as either the C<keys> or C<each> function would
-produce on the same (unmodified) hash.
+Returns a list consisting of all the values of the named hash.
+(In a scalar context, returns the number of values.)
+
+The values are returned in an apparently random order.  The actual
+random order is subject to change in future versions of perl, but it
+is guaranteed to be the same order as either the C<keys> or C<each>
+function would produce on the same (unmodified) hash.  Since Perl
+5.8.1 the ordering is different even between different runs of Perl
+for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
+
+As a side effect, calling values() resets the HASH's internal iterator,
+see L</each>.
 
 Note that the values are not copied, which means modifying them will
 modify the contents of the hash:
@@ -5974,7 +6255,6 @@ modify the contents of the hash:
     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>.
 
 =item vec EXPR,OFFSET,BITS