X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=85701ea9bfb78dcbbb5e1d7284bfbafc3894c915;hb=e40b81a3dd247b1a29fc78399677b77b78b5f183;hp=1efdefd4f6c8894e09c06e48532d8900a2e60d22;hpb=c106e8bbff313f9d3ffd1a9a1b0a6bd6129af87b;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 1efdefd..85701ea 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -134,7 +134,7 @@ X<I/O> X<input> X<output> X<dbm>
 
 C<binmode>, C<close>, C<closedir>, C<dbmclose>, C<dbmopen>, C<die>, C<eof>,
 C<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>,
-C<readdir>, C<rewinddir>, C<seek>, C<seekdir>, C<select>, C<syscall>,
+C<readdir>, C<rewinddir>, C<say>, C<seek>, C<seekdir>, C<select>, C<syscall>,
 C<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>, C<truncate>,
 C<warn>, C<write>
 
@@ -156,14 +156,25 @@ X<control flow>
 C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>,
 C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>
 
+=item Keywords related to switch
+
+C<break>, C<continue>, C<given>, C<when>, C<default>
+
+(These are only available if you enable the "switch" feature.
+See L<feature> and L<perlsyn/"Switch statements">.)
+
 =item Keywords related to scoping
 
-C<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<use>
+C<caller>, C<import>, C<local>, C<my>, C<our>, C<state>, C<package>,
+C<use>
+
+(C<state> is only available if the "state" feature is enabled. See
+L<feature>.)
 
 =item Miscellaneous functions
 
-C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>, C<reset>,
-C<scalar>, C<undef>, C<wantarray>
+C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>,
+C<reset>, C<scalar>, C<state>, C<undef>, C<wantarray>
 
 =item Functions for processes and process groups
 X<process> X<pid> X<process id>
@@ -220,10 +231,11 @@ C<gmtime>, C<localtime>, C<time>, C<times>
 =item Functions new in perl5
 X<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<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<abs>, C<bless>, C<break>, C<chomp>, C<chr>, C<continue>, C<default>, 
+C<exists>, C<formline>, C<given>, C<glob>, C<import>, C<lc>, C<lcfirst>,
+C<lock>, C<map>, C<my>, C<no>, C<our>, C<prototype>, C<qr>, C<qw>, C<qx>,
+C<readline>, C<readpipe>, C<ref>, C<sub>*, C<sysopen>, C<tie>, C<tied>, C<uc>,
+C<ucfirst>, C<untie>, C<use>, C<when>
 
 * - C<sub> was a keyword in perl4, but in perl5 it is an
 operator, which can be used in expressions.
@@ -274,11 +286,13 @@ X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
 
 =item -X EXPR
 
+=item -X DIRHANDLE
+
 =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
-tests the associated file to see if something is true about it.  If the
+operator takes one argument, either a filename, a filehandle, or a dirhandle, 
+and tests the associated file to see if something is true about it.  If the
 argument is omitted, tests C<$_>, except for C<-t>, which tests STDIN.
 Unless otherwise documented, it returns C<1> for true and C<''> for false, or
 the undefined value if the file doesn't exist.  Despite the funny
@@ -512,8 +526,8 @@ 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, 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
+Camel) or elsewhere, C<:raw> is I<not> simply the inverse of C<:crlf>
+-- other layers which would affect the binary nature of the stream are
 I<also> disabled. See L<PerlIO>, L<perlrun> and the discussion about the
 PERLIO environment variable.
 
@@ -592,6 +606,13 @@ that CLASSNAME is a true value.
 
 See L<perlmod/"Perl Modules">.
 
+=item break
+
+Break out of a C<given()> block.
+
+This keyword is enabled by the "switch" feature: see L<feature>
+for more information.
+
 =item caller EXPR
 X<caller> X<call stack> X<stack> X<stack trace>
 
@@ -602,14 +623,19 @@ returns the caller's package name if there is a caller, that is, if
 we're in a subroutine or C<eval> or C<require>, and the undefined value
 otherwise.  In list context, returns
 
+    # 0         1          2
     ($package, $filename, $line) = caller;
 
 With EXPR, it returns some extra information that the debugger uses to
 print a stack trace.  The value of EXPR indicates how many call frames
 to go back before the current one.
 
+    #  0         1          2      3            4
     ($package, $filename, $line, $subroutine, $hasargs,
-    $wantarray, $evaltext, $is_require, $hints, $bitmask) = caller($i);
+
+    #  5          6          7            8       9         10
+    $wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
+     = 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
@@ -625,6 +651,10 @@ 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.
 
+C<$hinthash> is a reference to a hash containing the value of C<%^H> when the
+caller was compiled, or C<undef> if C<%^H> was empty. Do not modify the values
+of this hash, as they are the actual values stored in the optree.
+
 Furthermore, when called from within the DB package, caller returns more
 detailed information: it sets the list variable C<@DB::args> to be the
 arguments with which the subroutine was invoked.
@@ -638,6 +668,7 @@ previous time C<caller> was called.
 =item chdir EXPR
 X<chdir>
 X<cd>
+X<directory, change>
 
 =item chdir FILEHANDLE
 
@@ -674,7 +705,9 @@ successfully changed.  See also L</oct>, if all you have is a string.
 
 On systems that support fchmod, you might pass file handles among the
 files.  On systems that don't support fchmod, passing file handles
-produces a fatal error at run time.
+produces a fatal error at run time.   The file handles must be passed
+as globs or references to be recognized.  Barewords are considered
+file names.
 
     open(my $fh, "<", "foo");
     my $perm = (stat $fh)[2] & 07777;
@@ -770,7 +803,9 @@ successfully changed.
 
 On systems that support fchown, you might pass file handles among the
 files.  On systems that don't support fchown, passing file handles
-produces a fatal error at run time.
+produces a fatal error at run time.  The file handles must be passed
+as globs or references to be recognized.  Barewords are considered
+file names.
 
 Here's an example that looks up nonnumeric uids in the passwd file:
 
@@ -835,10 +870,11 @@ X<close>
 
 =item close
 
-Closes the file or pipe associated with the file handle, returning
-true only if IO buffers are successfully flushed and closes the system
-file descriptor.  Closes the currently selected filehandle if the
-argument is omitted.
+Closes the file or pipe associated with the file handle, flushes the IO
+buffers, and closes the system file descriptor.  Returns true if those
+operations have succeeded and if no error was reported by any PerlIO
+layer.  Closes the currently selected filehandle if the argument is
+omitted.
 
 You don't have to close FILEHANDLE if you are immediately going to do
 another C<open> on it, because C<open> will close it for you.  (See
@@ -890,6 +926,8 @@ L<perlipc/"Sockets: Client/Server Communication">.
 =item continue BLOCK
 X<continue>
 
+=item continue
+
 C<continue> is actually a flow control statement rather than a function.  If
 there is a C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
 C<foreach>), it is always executed just before the conditional is about to
@@ -917,6 +955,12 @@ Omitting the C<continue> section is semantically equivalent to using an
 empty one, logically enough.  In that case, C<next> goes directly back
 to check the condition at the top of the loop.
 
+If the "switch" feature is enabled, C<continue> is also a
+function that will break out of the current C<when> or C<default>
+block, and fall through to the next case. See L<feature> and
+L<perlsyn/"Switch statements"> for more information.
+
+
 =item cos EXPR
 X<cos> X<cosine> X<acos> X<arccosine>
 
@@ -932,7 +976,7 @@ function, or use this relation:
 
 =item crypt PLAINTEXT,SALT
 X<crypt> X<digest> X<hash> X<salt> X<plaintext> X<password>
-X<decrypt> X<cryptography> X<passwd>
+X<decrypt> X<cryptography> X<passwd> X<encrypt>
 
 Creates a digest string exactly like the crypt(3) function in the C
 library (assuming that you actually have a version there that has not
@@ -1245,13 +1289,17 @@ trapped within an eval(), $@ contains the reference.  This behavior permits
 a more elaborate exception handling implementation using objects that
 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:
+regular expressions.  Because $@ is a global variable, and eval() may be
+used within object implementations, care must be taken that analyzing the
+error object doesn't replace the reference in the global variable.  The
+easiest solution is to make a local copy of the reference before doing
+other manipulations.  Here's an example:
 
     use Scalar::Util 'blessed';
 
     eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
-    if ($@) {
-        if (blessed($@) && $@->isa("Some::Module::Exception")) {
+    if (my $ev_err = $@) {
+        if (blessed($ev_err) && $ev_err->isa("Some::Module::Exception")) {
             # handle Some::Module::Exception
         }
         else {
@@ -1470,6 +1518,7 @@ there was an error.
 
 =item eval EXPR
 X<eval> X<try> X<catch> X<evaluate> X<parse> X<execute>
+X<error, handling> X<exception, handling>
 
 =item eval BLOCK
 
@@ -1963,7 +2012,7 @@ character may be taken to mean the beginning of an array name.
 C<formline> always returns true.  See L<perlform> for other examples.
 
 =item getc FILEHANDLE
-X<getc> X<getchar>
+X<getc> X<getchar> X<character> X<file, read>
 
 =item getc
 
@@ -2277,49 +2326,12 @@ X<gmtime> X<UTC> X<Greenwich>
 
 =item gmtime
 
-Converts a time as returned by the time function to an 9-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) =
-					    gmtime(time);
-
-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 always C<0>.
-
-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:
+Works just like L<localtime> but the returned values are
+localized for the standard Greenwich time zone.
 
-	$year += 1900;
-
-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, C<gmtime()> uses the current time (C<gmtime(time)>).
-
-In scalar context, C<gmtime()> returns the ctime(3) value:
-
-    $now_string = gmtime;  # e.g., "Thu Oct 13 04:54:34 1994"
-
-If you need local time instead of GMT use the L</localtime> builtin. 
-See also the C<timegm> function provided by the C<Time::Local> module,
-and the strftime(3) and mktime(3) functions available via the L<POSIX> module.
-
-This scalar value is B<not> locale dependent (see L<perllocale>), but is
-instead a Perl builtin.  To get somewhat similar but locale dependent date
-strings, see the example in L</localtime>.
+Note: when called in list context, $isdst, the last value
+returned by gmtime is always C<0>.  There is no
+Daylight Saving Time in GMT.
 
 See L<perlport/gmtime> for portability concerns.
 
@@ -2441,7 +2453,7 @@ you've set the C<$[> variable to--but don't do that).  If the substring
 is not found, C<index> returns one less than the base, ordinarily C<-1>.
 
 =item int EXPR
-X<int> X<integer> X<truncate> X<trunc>
+X<int> X<integer> X<truncate> X<trunc> X<floor>
 
 =item int
 
@@ -2571,10 +2583,12 @@ same as the number actually killed).
     $cnt = kill 1, $child1, $child2;
     kill 9, @goners;
 
-If SIGNAL is zero, no signal is sent to the process.  This is a
-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.
+If SIGNAL is zero, no signal is sent to the process, but the kill(2)
+system call will check whether it's possible to send a signal to it (that
+means, to be brief, that the process is owned by the same user, or we are
+the super-user).  This is a useful way to check that a child process is
+alive (even if only as a zombie) and hasn't changed its UID.  See
+L<perlport> for notes on the portability of this construct.
 
 Unlike in the shell, if SIGNAL is negative, it kills
 process groups instead of processes.  (On System V, a negative I<PROCESS>
@@ -2675,7 +2689,7 @@ be placed in parentheses.  See L<perlsub/"Temporary Values via local()">
 for details, including issues with tied arrays and hashes.
 
 =item localtime EXPR
-X<localtime>
+X<localtime> X<ctime>
 
 =item localtime
 
@@ -2705,6 +2719,9 @@ to get a complete 4-digit year is simply:
 
     $year += 1900;
 
+Otherwise you create non-Y2K-compliant programs--and you wouldn't want
+to do that, would you?
+
 To get the last two digits of the year (e.g., '01' in 2001) do:
 
     $year = sprintf("%02d", $year % 100);
@@ -2742,6 +2759,13 @@ and the month of the year, may not necessarily be three characters wide.
 
 See L<perlport/localtime> for portability concerns.
 
+The L<Time::gmtime> and L<Time::localtime> modules provides a convenient,
+by-name access mechanism to the gmtime() and localtime() functions,
+respectively.
+
+For a comprehensive date and time representation look at the
+L<DateTime> module on CPAN.
+
 =item lock THING
 X<lock>
 
@@ -2872,6 +2896,9 @@ number of trailing slashes.  Some operating and filesystems do not get
 this right, so Perl automatically removes all trailing slashes to keep
 everyone happy.
 
+In order to recursively create a directory structure look at
+the C<mkpath> function of the L<File::Path> module.
+
 =item msgctl ID,CMD,ARG
 X<msgctl>
 
@@ -3086,9 +3113,9 @@ L<PerlIO> for more details). For example
   open(FH, "<:utf8", "file")
 
 will open the UTF-8 encoded file containing Unicode characters,
-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.)
+see L<perluniintro>. Note that if layers are specified in the
+three-arg form then default layers stored in ${^OPEN} (see L<perlvar>;
+usually set by the B<open> pragma or the switch B<-CioD>) 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
@@ -3394,7 +3421,7 @@ See L<perlunicode> and L<encoding> for more about Unicode.
 =item our EXPR
 X<our> X<global>
 
-=item our EXPR TYPE
+=item our TYPE EXPR
 
 =item our EXPR : ATTRS
 
@@ -3462,30 +3489,6 @@ 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
-all other environments.
-
-Warning: the current implementation of this attribute operates on the
-typeglob associated with the variable; this means that C<our $x : unique>
-also has the effect of C<our @x : unique; our %x : unique>. This may be
-subject to change.
-
 =item pack TEMPLATE,LIST
 X<pack>
 
@@ -3529,7 +3532,7 @@ of values, as follows:
     I	A unsigned integer value.
 	  (This 'integer' is _at_least_ 32 bits wide.  Its exact
            size depends on what a local C compiler calls 'int'.)
- 
+
     n	An unsigned short (16-bit) in "network" (big-endian) order.
     N	An unsigned long (32-bit) in "network" (big-endian) order.
     v	An unsigned short (16-bit) in "VAX" (little-endian) order.
@@ -3718,29 +3721,32 @@ so will result in a fatal error.
 The C</> template character allows packing and unpacking of a sequence of
 items where the packed structure contains a packed item count followed by 
 the packed items themselves.
-You write I<length-item>C</>I<sequence-item>.
 
-The I<length-item> can be any C<pack> template letter, and describes
-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).
+For C<pack> you write I<length-item>C</>I<sequence-item> and the
+I<length-item> describes 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).
 
 For C<pack>, the I<sequence-item> may have a repeat count, in which case
 the minimum of that and the number of available items is used as argument
 for the I<length-item>. If it has no repeat count or uses a '*', the number
-of available items is used. For C<unpack> the repeat count is always obtained
-by decoding the packed item count, and the I<sequence-item> must not have a
-repeat count.
+of available items is used.
+
+For C<unpack> an internal stack of integer arguments unpacked so far is
+used. You write C</>I<sequence-item> and the repeat count is obtained by
+popping off the last element from the stack. The I<sequence-item> must not
+have a repeat count.
 
 If the I<sequence-item> refers to a string type (C<"A">, C<"a"> or C<"Z">),
 the I<length-item> is a string length, not a number of strings. If there is
 an explicit repeat count for pack, the packed string will be adjusted to that
 given length.
 
-    unpack 'W/a', "\04Gurusamy";        gives ('Guru')
-    unpack 'a3/A* A*', '007 Bond  J ';  gives (' Bond', 'J')
-    pack 'n/a* w/a','hello,','world';   gives "\000\006hello,\005world"
-    pack 'a/W2', ord('a') .. ord('z');  gives '2ab'
+    unpack 'W/a', "\04Gurusamy";            gives ('Guru')
+    unpack 'a3/A A*', '007 Bond  J ';       gives (' Bond', 'J')
+    unpack 'a3 x2 /A A*', '007: Bond, J.';  gives ('Bond, J', '.')
+    pack 'n/a* w/a','hello,','world';       gives "\000\006hello,\005world"
+    pack 'a/W2', ord('a') .. ord('z');      gives '2ab'
 
 The I<length-item> is not returned explicitly from C<unpack>.
 
@@ -4126,9 +4132,10 @@ X<printf>
 Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that C<$\>
 (the output record separator) is not appended.  The first argument
 of the list will be interpreted as the C<printf> format. See C<sprintf>
-for an explanation of the format argument. 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>.
+for an explanation of the format argument.  If C<use locale> is in effect,
+and POSIX::setlocale() has been called, the character used for the decimal
+separator in formatted floating point numbers is affected by the LC_NUMERIC
+locale.  See L<perllocale> and L<POSIX>.
 
 Don't fall into the trap of using a C<printf> when a simple
 C<print> would do.  The C<print> is more efficient and less
@@ -4212,7 +4219,7 @@ large or too small, then your version of Perl was probably compiled
 with the wrong number of RANDBITS.)
 
 =item read FILEHANDLE,SCALAR,LENGTH,OFFSET
-X<read>
+X<read> X<file, read>
 
 =item read FILEHANDLE,SCALAR,LENGTH
 
@@ -4392,6 +4399,10 @@ Builtin types include:
     REF
     GLOB
     LVALUE
+    FORMAT
+    IO
+    VSTRING
+    Regexp
 
 If the referenced object has been blessed into a package, then that package
 name is returned instead.  You can think of C<ref> as a C<typeof> operator.
@@ -4418,6 +4429,9 @@ for this.  Other restrictions include whether it works on directories,
 open files, or pre-existing files.  Check L<perlport> and either the
 rename(2) manpage or equivalent system documentation for details.
 
+For a platform independent C<move> function look at the L<File::Copy>
+module.
+
 =item require VERSION
 X<require>
 
@@ -4510,14 +4524,12 @@ 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 its 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.
+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 similar filename with a "F<.pmc>" extension. If this file
+is found, it will be loaded in place of any 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
@@ -4527,9 +4539,37 @@ Subroutine references are the simplest case.  When the inclusion system
 walks through @INC and encounters a subroutine, this subroutine gets
 called with two parameters, the first being a reference to itself, and the
 second the name of the file to be included (e.g. "F<Foo/Bar.pm>").  The
-subroutine should return C<undef> or a filehandle, from which the file to
-include will be read.  If C<undef> is returned, C<require> will look at
-the remaining elements of @INC.
+subroutine should return nothing, or a list of up to three values in the
+following order:
+
+=over
+
+=item 1
+
+A filehandle, from which the file will be read.  
+
+=item 2
+
+A reference to a subroutine. If there is no filehandle (previous item),
+then this subroutine is expected to generate one line of source code per
+call, writing the line into C<$_> and returning 1, then returning 0 at
+"end of file". If there is a filehandle, then the subroutine will be
+called to act a simple source filter, with the line as read in C<$_>.
+Again, return 1 for each valid line, and 0 after all lines have been
+returned.
+
+=item 3
+
+Optional state for the subroutine. The state is passed in as C<$_[1]>. A
+reference to the subroutine itself is passed in as C<$_[0]>.
+
+=back
+
+If an empty list, C<undef>, or nothing that matches the first 3 values above
+is returned then C<require> will look at the remaining elements of @INC.
+Note that this file handle must be a real file handle (strictly a typeglob,
+or reference to a typeglob, blessed or unblessed) - tied file handles will be
+ignored and return value processing will stop there.
 
 If the hook is an array reference, its first element must be a subroutine
 reference.  This subroutine is called as above, but the first parameter is
@@ -4556,8 +4596,8 @@ or:
 
 If the hook is an object, it must provide an INC method that will be
 called as above, the first parameter being the object itself.  (Note that
-you must fully qualify the sub's name, as it is always forced into package
-C<main>.)  Here is a typical code layout:
+you must fully qualify the sub's name, as unqualified C<INC> is always forced
+into package C<main>.)  Here is a typical code layout:
 
     # In Foo.pm
     package Foo;
@@ -4649,9 +4689,9 @@ X<rindex>
 
 =item rindex STR,SUBSTR
 
-Works just like index() except that it returns the position of the LAST
+Works just like index() except that it returns the position of the I<last>
 occurrence of SUBSTR in STR.  If POSITION is specified, returns the
-last occurrence at or before that position.
+last occurrence beginning at or before that position.
 
 =item rmdir FILENAME
 X<rmdir> X<rd> X<directory, remove>
@@ -4662,10 +4702,27 @@ 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<$_>.
 
+To remove a directory tree recursively (C<rm -rf> on unix) look at
+the C<rmtree> function of the L<File::Path> module.
+
 =item s///
 
 The substitution operator.  See L<perlop>.
 
+=item say FILEHANDLE LIST
+X<say>
+
+=item say LIST
+
+=item say
+
+Just like C<print>, but implicitly appends a newline.
+C<say LIST> is simply an abbreviation for C<{ local $/ = "\n"; print
+LIST }>.
+
+This keyword is only available when the "say" feature is
+enabled: see L<feature>.
+
 =item scalar EXPR
 X<scalar> X<context>
 
@@ -4926,8 +4983,15 @@ that doesn't implement setpriority(2).
 X<setsockopt>
 
 Sets the socket option requested.  Returns undefined if there is an
-error.  OPTVAL may be specified as C<undef> if you don't want to pass an
-argument.
+error.  Use integer constants provided by the C<Socket> module for
+LEVEL and OPNAME.  Values for LEVEL can also be obtained from
+getprotobyname.  OPTVAL might either be a packed string or an integer.
+An integer OPTVAL is shorthand for pack("i", OPTVAL).
+
+An example disabling the Nagle's algorithm for a socket:
+
+    use Socket qw(IPPROTO_TCP TCP_NODELAY);
+    setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
 
 =item shift ARRAY
 X<shift>
@@ -4939,8 +5003,8 @@ array by 1 and moving everything down.  If there are no elements in the
 array, returns the undefined value.  If ARRAY is omitted, shifts the
 C<@_> array within the lexical scope of subroutines and formats, and the
 C<@ARGV> array outside of a subroutine and also within the lexical scopes
-established by the C<eval STRING>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>
-and C<END {}> constructs.
+established by the C<eval STRING>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>,
+C<UNITCHECK {}> and C<END {}> constructs.
 
 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
@@ -5448,6 +5512,7 @@ In addition, Perl permits the following widely-supported conversions:
    %E	like %e, but using an upper-case "E"
    %G	like %g, but with an upper-case "E" (if applicable)
    %b	an unsigned integer, in binary
+   %B	like %b, but using an upper-case "B" with the # flag
    %p	a pointer (outputs the Perl value's address in hexadecimal)
    %n	special: *stores* the number of characters output so far
         into the next variable in the parameter list
@@ -5485,30 +5550,50 @@ to take the arguments out of order, e.g.:
 =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",
-           non-zero binary with "0b"
+   #       ensure the leading "0" for any octal,
+           prefix non-zero hexadecimal with "0x" or "0X",
+           prefix non-zero binary with "0b" or "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>"
+  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 '<%#o>',  12;   # prints "<014>"
+  printf '<%#x>',  12;   # prints "<0xc>"
+  printf '<%#X>',  12;   # prints "<0XC>"
+  printf '<%#b>',  12;   # prints "<0b1100>"
+  printf '<%#B>',  12;   # prints "<0B1100>"
+
+When a space and a plus sign are given as the flags at once,
+a plus sign is used to prefix a positive number.
+
+  printf '<%+ d>', 12;   # prints "<+12>"
+  printf '<% +d>', 12;   # prints "<+12>"
+
+When the # flag and a precision are given in the %o conversion,
+the precision is incremented if it's necessary for the leading "0".
+
+  printf '<%#.5o>', 012;      # prints "<00012>"
+  printf '<%#.5o>', 012345;   # prints "<012345>"
+  printf '<%#.0o>', 0;        # prints "<0>"
 
 =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:
+This flag tells perl to interpret the supplied string as a vector of
+integers, one for each character in the string. Perl applies the format to
+each integer in turn, then joins the resulting strings with a separator (a
+dot C<.> by default). This can be useful for displaying ordinal values of
+characters in arbitrary strings:
 
+  printf "%vd", "AB\x{100}";           # prints "65.66.256"
   printf "version is v%vd\n", $^V;     # Perl's version
 
 Put an asterisk C<*> before the C<v> to override the string to
@@ -5566,11 +5651,22 @@ including prior to the decimal point as well as after it, e.g.:
   printf '<%.4g>', 100.01; # prints "<100>"
 
 For integer conversions, specifying a precision implies that the
-output of the number itself should be zero-padded to this width:
+output of the number itself should be zero-padded to this width,
+where the 0 flag is ignored:
+
+  printf '<%.6d>', 1;      # prints "<000001>"
+  printf '<%+.6d>', 1;     # prints "<+000001>"
+  printf '<%-10.6d>', 1;   # prints "<000001    >"
+  printf '<%10.6d>', 1;    # prints "<    000001>"
+  printf '<%010.6d>', 1;   # prints "<    000001>"
+  printf '<%+10.6d>', 1;   # prints "<   +000001>"
 
   printf '<%.6x>', 1;      # prints "<000001>"
   printf '<%#.6x>', 1;     # prints "<0x000001>"
   printf '<%-10.6x>', 1;   # prints "<000001    >"
+  printf '<%10.6x>', 1;    # prints "<    000001>"
+  printf '<%010.6x>', 1;   # prints "<    000001>"
+  printf '<%#10.6x>', 1;   # prints "<  0x000001>"
 
 For string conversions, specifying a precision truncates the string
 to fit in the specified width:
@@ -5583,6 +5679,18 @@ You can also get the precision from the next argument using C<.*>:
   printf '<%.6x>', 1;       # prints "<000001>"
   printf '<%.*x>', 6, 1;    # prints "<000001>"
 
+If a precision obtained through C<*> is negative, it has the same
+effect as no precision.
+
+  printf '<%.*s>',  7, "string";   # prints "<string>"
+  printf '<%.*s>',  3, "string";   # prints "<str>"
+  printf '<%.*s>',  0, "string";   # prints "<>"
+  printf '<%.*s>', -1, "string";   # prints "<string>"
+
+  printf '<%.*d>',  1, 0;   # prints "<0>"
+  printf '<%.*d>',  0, 0;   # prints "<>"
+  printf '<%.*d>', -1, 0;   # prints "<0>"
+
 You cannot currently get the precision from a specified number,
 but it is intended that this will be possible in the future using
 e.g. C<.*2$>:
@@ -5672,9 +5780,10 @@ index, the C<$> may need to be escaped:
 
 =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>.
+If C<use locale> is in effect, and POSIX::setlocale() has been called,
+the character used for the decimal separator in formatted floating
+point numbers is affected by the LC_NUMERIC locale.  See L<perllocale>
+and L<POSIX>.
 
 =item sqrt EXPR
 X<sqrt> X<root> X<square root>
@@ -5751,16 +5860,18 @@ for a seed can fall prey to the mathematical property that
 one-third of the time.  So don't do that.
 
 =item stat FILEHANDLE
-X<stat> X<file, status>
+X<stat> X<file, status> X<ctime>
 
 =item stat EXPR
 
+=item stat DIRHANDLE
+
 =item stat
 
 Returns a 13-element list giving the status info for a file, either
-the file opened via FILEHANDLE, or named by EXPR.  If EXPR is omitted,
-it stats C<$_>.  Returns a null list if the stat fails.  Typically used
-as follows:
+the file opened via FILEHANDLE or DIRHANDLE, or named by EXPR.  If EXPR is 
+omitted, it stats C<$_>.  Returns a null list if the stat fails.  Typically
+used as follows:
 
     ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
        $atime,$mtime,$ctime,$blksize,$blocks)
@@ -5811,7 +5922,7 @@ In scalar context, C<stat> returns a boolean value indicating success
 or failure, and, if successful, sets the information associated with
 the special filehandle C<_>.
 
-The File::stat module provides a convenient, by-name access mechanism:
+The L<File::stat> module provides a convenient, by-name access mechanism:
 
     use File::stat;
     $sb = stat($filename);
@@ -5833,7 +5944,7 @@ You can import symbolic mode constants (C<S_IF*>) and functions
     printf "Permissions are %04o\n", S_IMODE($mode), "\n";
 
     $is_setuid     =  $mode & S_ISUID;
-    $is_setgid     =  S_ISDIR($mode);
+    $is_directory  =  S_ISDIR($mode);
 
 You could write the last two using the C<-u> and C<-d> operators.
 The commonly available C<S_IF*> constants are
@@ -5851,7 +5962,7 @@ The commonly available C<S_IF*> constants are
 
     # File types.  Not necessarily all are available on your system.
 
-    S_IFREG S_IFDIR S_IFLNK S_IFBLK S_ISCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
+    S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
 
     # The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.
 
@@ -5881,6 +5992,23 @@ See your native chmod(2) and stat(2) documentation for more details
 about the C<S_*> constants.  To get status info for a symbolic link
 instead of the target file behind the link, use the C<lstat> function.
 
+=item state EXPR
+X<state>
+
+=item state TYPE EXPR
+
+=item state EXPR : ATTRS
+
+=item state TYPE EXPR : ATTRS
+
+C<state> declares a lexically scoped variable, just like C<my> does.
+However, those variables will be initialized only once, contrary to
+lexical variables that are reinitialized each time their enclosing block
+is entered.
+
+C<state> variables are only enabled when the C<feature 'state'> pragma is
+in effect.  See L<feature>.
+
 =item study SCALAR
 X<study>
 
@@ -5973,6 +6101,13 @@ that far from the end of the string.  If LENGTH is omitted, returns
 everything to the end of the string.  If LENGTH is negative, leaves that
 many characters off the end of the string.
 
+    my $s = "The black cat climbed the green tree";
+    my $color  = substr $s, 4, 5;	# black
+    my $middle = substr $s, 4, -11;	# black cat climbed the
+    my $end    = substr $s, 14;		# climbed the green tree
+    my $tail   = substr $s, -4;		# tree
+    my $z      = substr $s, -4, 2;	# tr
+
 You can use the substr() function as an lvalue, in which case EXPR
 must itself be an lvalue.  If you assign something shorter than LENGTH,
 the string will shrink, and if you assign something longer than LENGTH,
@@ -5997,6 +6132,10 @@ 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().
 
+    my $s = "The black cat climbed the green tree";
+    my $z = substr $s, 14, 7, "jumped from";	# climbed
+    # $s is now "The black cat jumped from the green tree"
+
 Note that the lvalue returned by the 3-arg version of substr() acts as
 a 'magic bullet'; each time it is assigned to, it remembers which part
 of the original string is being modified; for example:
@@ -6009,7 +6148,6 @@ of the original string is being modified; for example:
         $_ = 'pq';  print $x,"\n";	# prints 5pq9
     }
 
-
 Prior to Perl version 5.9.1, the result of using an lvalue multiple times was
 unspecified.
 
@@ -6423,11 +6561,15 @@ a prominent exception being Mac OS Classic which uses 00:00:00, January 1,
 1904 in the current local time zone for its epoch.
 
 For measuring time in better granularity than one second,
-you may use either the Time::HiRes module (from CPAN, and starting from
+you may use either the L<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.
 
+For date and time processing look at the many related modules on CPAN.
+For a comprehensive date and time representation look at the
+L<DateTime> module.
+
 =item times
 X<times>
 
@@ -6438,6 +6580,8 @@ seconds, for this process and the children of this process.
 
 In scalar context, C<times> returns C<$user>.
 
+Note that times for children are included only after they terminate.
+
 =item tr///
 
 The transliteration operator.  Same as C<y///>.  See L<perlop>.
@@ -6455,6 +6599,9 @@ otherwise.
 The behavior is undefined if LENGTH is greater than the length of the
 file.
 
+The position in the file of FILEHANDLE is left unchanged.  You may want to
+call L<seek> before writing to the file.
+
 =item uc EXPR
 X<uc> X<uppercase> X<toupper>
 
@@ -6548,7 +6695,7 @@ parameter.  Examples:
 Note that this is a unary operator, not a list operator.
 
 =item unlink LIST
-X<unlink> X<delete> X<remove> X<rm>
+X<unlink> X<delete> X<remove> X<rm> X<del>
 
 =item unlink
 
@@ -6559,10 +6706,11 @@ deleted.
     unlink @goners;
     unlink <*.bak>;
 
-Note: C<unlink> will not delete directories unless you are superuser and
-the B<-U> flag is supplied to Perl.  Even if these conditions are
+Note: C<unlink> will not attempt to delete directories unless you are superuser
+and the B<-U> flag is supplied to Perl.  Even if these conditions are
 met, be warned that unlinking a directory can inflict damage on your
-filesystem.  Use C<rmdir> instead.
+filesystem.  Finally, using C<unlink> on directories is not supported on 
+many operating systems.  Use C<rmdir> instead.
 
 If LIST is omitted, uses C<$_>.
 
@@ -6782,7 +6930,9 @@ uninitialized warning.
 
 On systems that support futimes, you might pass file handles among the
 files.  On systems that don't support futimes, passing file handles
-produces a fatal error at run time.
+produces a fatal error at run time.  The file handles must be passed
+as globs or references to be recognized.  Barewords are considered
+file names.
 
 =item values HASH
 X<values>
@@ -7072,7 +7222,7 @@ The status is returned in C<$?> and C<{^CHILD_ERROR_NATIVE}>.  If you say
     #...
     do {
 	$kid = waitpid(-1, WNOHANG);
-    } until $kid > 0;
+    } while $kid > 0;
 
 then you can do a non-blocking wait for all pending zombie processes.
 Non-blocking wait is available on machines supporting either the
@@ -7098,16 +7248,16 @@ looking for no value (void context).
     return wantarray ? @a : "@a";
 
 C<wantarray()>'s result is unspecified in the top level of a file,
-in a C<BEGIN>, C<CHECK>, C<INIT> or C<END> block, or in a C<DESTROY>
-method.
+in a C<BEGIN>, C<UNITCHECK>, C<CHECK>, C<INIT> or C<END> block, or
+in a C<DESTROY> method.
 
 This function should have been named wantlist() instead.
 
 =item warn LIST
 X<warn> X<warning> X<STDERR>
 
-Produces a message on STDERR just like C<die>, but doesn't exit or throw
-an exception.
+Prints the value of LIST to STDERR.  If the last element of LIST does
+not end in a newline, appends the same text as C<die> does.
 
 If LIST is empty and C<$@> already contains a value (typically from a
 previous eval) that value is used after appending C<"\t...caught">