X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=174ff60f27eecf1de1601a9087d02cd3a32d4c40;hb=bbd5c0f5ad81733b079008f34cd05cd9aef7d917;hp=7aaeaf3d3bdd69c8e0a4ead6f103eb1c026f2fd5;hpb=b76cc8ba45957a82b545cf2a7b818233e6c0d507;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 7aaeaf3..174ff60 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -69,7 +69,7 @@ last value in the list.  Some operators return a count of successful
 operations.  In general, they do what you want, unless you want
 consistency.
 
-An named array in scalar context is quite different from what would at
+A named array in scalar context is quite different from what would at
 first glance appear to be a list in scalar context.  You can't get a list
 like C<(1,2,3)> into being in scalar context, because the compiler knows
 the context at compile time.  It would generate the scalar comma operator
@@ -172,7 +172,7 @@ C<untie>, C<use>
 
 C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
 C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
-C<socket>, C<socketpair>
+C<sockatmark>, C<socket>, C<socketpair>
 
 =item System V interprocess communication functions
 
@@ -234,8 +234,9 @@ C<msgsnd>, C<open>, C<pipe>, C<readlink>, C<rename>, C<select>, C<semctl>,
 C<semget>, C<semop>, C<setgrent>, C<sethostent>, C<setnetent>,
 C<setpgrp>, C<setpriority>, C<setprotoent>, C<setpwent>,
 C<setservent>, C<setsockopt>, C<shmctl>, C<shmget>, C<shmread>,
-C<shmwrite>, C<socket>, C<socketpair>, C<stat>, C<symlink>, C<syscall>,
-C<sysopen>, C<system>, C<times>, C<truncate>, C<umask>, C<unlink>,
+C<shmwrite>, C<sockatmark>, C<socket>, C<socketpair>,
+C<stat>, C<symlink>, C<syscall>, C<sysopen>, C<system>,
+C<times>, C<truncate>, C<umask>, C<unlink>,
 C<utime>, C<wait>, C<waitpid>
 
 For more information about the portability of these functions, see
@@ -290,7 +291,7 @@ X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
     -g	File has setgid bit set.
     -k	File has sticky bit set.
 
-    -T	File is an ASCII text file.
+    -T	File is an ASCII text file (heuristic guess).
     -B	File is a "binary" file (opposite of -T).
 
     -M	Age of file in days when script started.
@@ -397,8 +398,9 @@ on the previous timer.
 For delays of finer granularity than one second, you may use Perl's
 four-argument version of select() leaving the first three arguments
 undefined, or you might be able to use the C<syscall> interface to
-access setitimer(2) if your system supports it.  The Time::HiRes module
-from CPAN may also prove useful.
+access setitimer(2) if your system supports it.  The Time::HiRes
+module (from CPAN, and starting from Perl 5.8 part of the standard
+distribution) may also prove useful.
 
 It is usually a mistake to intermix C<alarm> and C<sleep> calls.
 (C<sleep> may be internally implemented in your system with C<alarm>)
@@ -448,13 +450,12 @@ 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">.
+omitted, it defaults to C<":raw">.  Returns true on success, C<undef> on
+failure.
 
 binmode() should be called after open() but before any I/O is done on
 the filehandle.
 
-On many systems binmode() currently has no effect, but in future, it
-will be extended to support user-defined input and output disciplines.
 On some systems binmode() is necessary when you're not working with a
 text file.  For the sake of portability it is a good idea to always use
 it when appropriate, and to never use it when it isn't appropriate.
@@ -473,17 +474,17 @@ representation matches the internal representation, but on some
 platforms the external representation of C<\n> is made up of more than
 one character.
 
-Mac OS and all variants of Unix use a single character to end each line
-in the external representation of text (even though that single
-character is not necessarily the same across these platforms).
-Consequently binmode() has no effect on these operating systems.  In
-other systems like VMS, MS-DOS and the various flavors of MS-Windows
-your program sees a C<\n> as a simple C<\cJ>, but what's stored in text
-files are the two characters C<\cM\cJ>.  That means that, if you don't
-use binmode() on these systems, C<\cM\cJ> sequences on disk will be
-converted to C<\n> on input, and any C<\n> in your program will be
-converted back to C<\cM\cJ> on output.  This is what you want for text
-files, but it can be disastrous for binary files.
+Mac OS, all variants of Unix, and Stream_LF files on VMS use a single
+character to end each line in the external representation of text (even
+though that single character is CARRIAGE RETURN on Mac OS and LINE FEED
+on Unix and most VMS files).  Consequently binmode() has no effect on
+these operating systems.  In other systems like OS/2, DOS and the various
+flavors of MS-Windows your program sees a C<\n> as a simple C<\cJ>, but
+what's stored in text files are the two characters C<\cM\cJ>.  That means
+that, if you don't use binmode() on these systems, C<\cM\cJ> sequences on
+disk will be converted to C<\n> on input, and any C<\n> in your program
+will be converted back to C<\cM\cJ> on output.  This is what you want for
+text files, but it can be disastrous for binary files.
 
 Another consequence of using binmode() (on some systems) is that
 special end-of-file markers will be seen as part of the data stream.
@@ -559,11 +560,12 @@ previous time C<caller> was called.
 
 =item chdir EXPR
 
-Changes the working directory to EXPR, if possible.  If EXPR is omitted,
+Changes the working directory to EXPR, if possible. If EXPR is omitted,
 changes to the directory specified by C<$ENV{HOME}>, if set; if not,
-changes to the directory specified by C<$ENV{LOGDIR}>.  If neither is
-set, C<chdir> does nothing.  It returns true upon success, false
-otherwise.  See the example under C<die>.
+changes to the directory specified by C<$ENV{LOGDIR}>. (Under VMS, the
+variable C<$ENV{SYS$LOGIN}> is also checked, and used if it is set.) If
+neither is set, C<chdir> does nothing. It returns true upon success,
+false otherwise. See the example under C<die>.
 
 =item chmod LIST
 
@@ -680,12 +682,12 @@ On POSIX systems, you can detect this condition this way:
 
 Returns the character represented by that NUMBER in the character set.
 For example, C<chr(65)> is C<"A"> in either ASCII or Unicode, and
-chr(0x263a) is a Unicode smiley face. Within the scope of C<use utf8>,
-characters higher than 127 are encoded in Unicode; if you don't want
-this, temporarily C<use bytes> or use C<pack("C*",...)>
+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>).
 
 For the reverse, use L</ord>.
-See L<utf8> for more about Unicode.
+See L<perlunicode> and L<encoding> for more about Unicode.
 
 If NUMBER is omitted, uses C<$_>.
 
@@ -805,17 +807,29 @@ 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 breaking
-eggs to make an omelette.  There is no (known) corresponding decrypt
-function.  As a result, this function isn't all that useful for
+Note that C<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
 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> and with more
-exotic implementations.  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]>).
+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>
+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.
+
+Traditionally the result is a string of 13 bytes: two first bytes of
+the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only
+the first eight bytes of the encrypted string mattered, but
+alternative hashing schemes (like MD5), higher level security schemes
+(like C2), and implementations on non-UNIX platforms may produce
+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]>).
 
 Here's an example that makes sure that whoever runs this program knows
 their own password:
@@ -843,6 +857,11 @@ 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
 modules.
 
+If using crypt() on a Unicode string (which potentially has
+characters with codepoints above 255), Perl tries to make sense of
+the situation by using only the low eight bits of the characters when
+calling crypt().
+
 =item dbmclose HASH
 
 [This function has been largely superseded by the C<untie> function.]
@@ -1116,7 +1135,7 @@ from a Perl subroutine library.
 
 is just like
 
-    scalar eval `cat stat.pl`;
+    eval `cat stat.pl`;
 
 except that it's more efficient and concise, keeps track of the current
 filename for error messages, searches the @INC libraries, and updates
@@ -1985,7 +2004,7 @@ C<File::Glob> extension.  See L<File::Glob> for details.
 
 =item gmtime EXPR
 
-Converts a time as returned by the time function to a 8-element list
+Converts a time as returned by the time function to an 8-element list
 with the time localized for the standard Greenwich time zone.
 Typically used as follows:
 
@@ -2115,7 +2134,8 @@ L</oct>.)  If EXPR is omitted, uses C<$_>.
     print hex 'aF';   # same
 
 Hex strings may only represent integers.  Strings that would cause
-integer overflow trigger a warning.
+integer overflow trigger a warning.  Leading whitespace is not stripped,
+unlike oct().
 
 =item import
 
@@ -2307,10 +2327,10 @@ C<redo> work.
 
 =item lc
 
-Returns an lowercased version of EXPR.  This is the internal function
-implementing the C<\L> escape in double-quoted strings.
-Respects current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>
-and L<utf8>.
+Returns a lowercased version of EXPR.  This is the internal function
+implementing the C<\L> escape in double-quoted strings.  Respects
+current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>
+and L<perlunicode> for more details about locale and Unicode support.
 
 If EXPR is omitted, uses C<$_>.
 
@@ -2318,9 +2338,11 @@ If EXPR is omitted, uses C<$_>.
 
 =item lcfirst
 
-Returns the value of EXPR with the first character lowercased.  This is
-the internal function implementing the C<\l> escape in double-quoted strings.
-Respects current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>.
+Returns the value of EXPR with the first character lowercased.  This
+is the internal function implementing the C<\l> escape in
+double-quoted strings.  Respects current LC_CTYPE locale if C<use
+locale> in force.  See L<perllocale> and L<perlunicode> for more
+details about locale and Unicode support.
 
 If EXPR is omitted, uses C<$_>.
 
@@ -2611,8 +2633,9 @@ See the L</use> function, which C<no> is the opposite of.
 Interprets EXPR as an octal string and returns the corresponding
 value.  (If EXPR happens to start off with C<0x>, interprets it as a
 hex string.  If EXPR starts off with C<0b>, it is interpreted as a
-binary string.)  The following will handle decimal, binary, octal, and
-hex in the standard Perl or C notation:
+binary string.  Leading whitespace is ignored in all three cases.)
+The following will handle decimal, binary, octal, and hex in the standard
+Perl or C notation:
 
     $val = oct($val) if $val =~ /^0/;
 
@@ -2627,15 +2650,18 @@ to be converted into a file mode, for example. (Although perl will
 automatically convert strings into numbers as needed, this automatic
 conversion assumes base 10.)
 
-=item open FILEHANDLE,MODE,LIST
-
 =item open FILEHANDLE,EXPR
 
+=item open FILEHANDLE,MODE,EXPR
+
+=item open FILEHANDLE,MODE,EXPR,LIST
+
 =item open FILEHANDLE
 
 Opens the file whose filename is given by EXPR, and associates it with
-FILEHANDLE.  If FILEHANDLE is an expression, its value is used as the
-name of the real filehandle wanted.  (This is considered a symbolic
+FILEHANDLE.  If FILEHANDLE is an undefined lexical (C<my>) variable the variable is
+assigned a reference to a new anonymous filehandle, otherwise if FILEHANDLE is an expression,
+its value is used as the name of the real filehandle wanted.  (This is considered a symbolic
 reference, so C<use strict 'refs'> should I<not> be in effect.)
 
 If EXPR is omitted, the scalar
@@ -2645,7 +2671,8 @@ for this purpose; so if you're using C<my>, specify EXPR in your call
 to open.)  See L<perlopentut> for a kinder, gentler explanation of opening
 files.
 
-If MODE is C<< '<' >> or nothing, the file is opened for input.
+If three or more arguments are specified then the mode of opening and the file name
+are separate. If MODE is C<< '<' >> or nothing, the file is opened for input.
 If MODE is C<< '>' >>, the file is truncated and opened for
 output, being created if necessary.  If MODE is C<<< '>>' >>>,
 the file is opened for appending, again being created if necessary.
@@ -2662,7 +2689,8 @@ C<'w'>, C<'w+'>, C<'a'>, and C<'a+'>.
 
 In the 2-arguments (and 1-argument) form of the call the mode and
 filename should be concatenated (in this order), possibly separated by
-spaces.  It is possible to omit the mode if the mode is C<< '<' >>.
+spaces.  It is possible to omit the mode in these forms if the mode is
+C<< '<' >>.
 
 If the filename begins with C<'|'>, the filename is interpreted as a
 command to which output is to be piped, and if the filename ends with a
@@ -2673,14 +2701,18 @@ that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>,
 and L<perlipc/"Bidirectional Communication with Another Process">
 for alternatives.)
 
-If MODE is C<'|-'>, the filename is interpreted as a
+For three or more arguments if MODE is C<'|-'>, the filename is interpreted as a
 command to which output is to be piped, and if MODE is
 C<'-|'>, the filename is interpreted as a command which pipes output to
 us.  In the 2-arguments (and 1-argument) form one should replace dash
 (C<'-'>) with the command.  See L<perlipc/"Using open() for IPC">
 for more examples of this.  (You are not allowed to C<open> to a command
 that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>,
-and L<perlipc/"Bidirectional Communication"> for alternatives.)
+and L<perlipc/"Bidirectional Communication"> for alternatives.) In 3+ arg form of
+pipe opens then if LIST is specified (extra arguments after the command name) then
+LIST becomes arguments to the command invoked if the platform supports it.
+The meaning of C<open> with more than three arguments for non-pipe modes
+is not yet specified. Experimental "layers" may give extra LIST arguments meaning.
 
 In the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN
 and opening C<< '>-' >> opens STDOUT.
@@ -2698,6 +2730,10 @@ and those that don't is their text file formats.  Systems like Unix, MacOS, and
 Plan9, which delimit lines with a single character, and which encode that
 character in C as C<"\n">, do not need C<binmode>.  The rest need it.
 
+In the three argument form MODE may also contain a list of IO "layers" (see L<open> and
+L<PerlIO> for more details) to be applied to the handle. This can be used to achieve the
+effect of C<binmode> as well as more complex behaviours.
+
 When opening a file, it's usually a bad idea to continue normal execution
 if the request failed, so C<open> is frequently used in connection with
 C<die>.  Even if C<die> won't do what you want (say, in a CGI script,
@@ -2713,6 +2749,7 @@ being C<undef>:
 
 opens a filehandle to an anonymous temporary file.
 
+
 Examples:
 
     $ARTICLE = 100;
@@ -2796,19 +2833,25 @@ STDERR:
     print STDOUT "stdout 2\n";
     print STDERR "stderr 2\n";
 
-If you specify C<< '<&=N' >>, where C<N> is a number, then Perl will do an
-equivalent of C's C<fdopen> of that file descriptor; this is more
-parsimonious of file descriptors.  For example:
+If you specify C<< '<&=N' >>, where C<N> is a number, then Perl will
+do an equivalent of C's C<fdopen> of that file descriptor; this is
+more parsimonious of file descriptors.  For example:
 
     open(FILEHANDLE, "<&=$fd")
+
 or
+
     open(FILEHANDLE, "<&=", $fd)
 
-Note that if perl is using the standard C libaries fdopen() then on many UNIX systems,
-fdopen() is known to fail when file descriptors
+Note that if Perl is using the standard C libraries' fdopen() then on
+many UNIX systems, fdopen() is known to fail when file descriptors
 exceed a certain value, typically 255. If you need more file
 descriptors than that, consider rebuilding Perl to use the C<PerlIO>.
 
+You can see whether Perl has been compiled with PerlIO or not by
+running C<perl -V> and looking for C<useperlio=> line.  If C<useperlio>
+is C<define>, you have PerlIO, otherwise you don't.
+
 If you open a pipe on the command C<'-'>, i.e., either C<'|-'> or C<'-|'>
 with 2-arguments (or 1-argument) form of open(), then
 there is an implicit fork done, and the return value of open is the pid
@@ -2927,12 +2970,17 @@ DIRHANDLEs have their own namespace separate from FILEHANDLEs.
 
 =item ord
 
-Returns the numeric (ASCII or Unicode) value of the first character of EXPR.  If
-EXPR is omitted, uses C<$_>.  For the reverse, see L</chr>.
-See L<utf8> for more about Unicode.
+Returns the numeric (the native 8-bit encoding, like ASCII or EBCDIC,
+or Unicode) value of the first character of EXPR.  If EXPR is omitted,
+uses C<$_>.
+
+For the reverse, see L</chr>.
+See L<perlunicode> and L<encoding> for more about Unicode.
 
 =item our EXPR
 
+=item our EXPR : ATTRIBUTES
+
 An C<our> declares the listed variables to be valid globals within
 the enclosing block, file, or C<eval>.  That is, it has the same
 scoping rules as a "my" declaration, but does not create a local
@@ -2971,6 +3019,28 @@ package, Perl will emit warnings if you have asked for them.
 
     our $bar;		# emits warning
 
+An C<our> declaration may also have a list of attributes associated
+with it.  B<WARNING>: This is an experimental feature that may be
+changed or removed in future releases of Perl.  It should not be
+relied upon.
+
+The only currently recognized attribute is C<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:
+
+    our @EXPORT : unique = qw(foo);
+    our %EXPORT_TAGS : unique = (bar => [qw(aa bb cc)]);
+    our $VERSION : unique = "1.00";
+
+Multi-interpreter environments can come to being either through the
+fork() emulation on Windows platforms, or by embedding perl in a
+multi-threaded application.  The C<unique> attribute does nothing in
+all other environments.
+
 =item pack TEMPLATE,LIST
 
 Takes a LIST of values and converts it into a string using the rules
@@ -2984,8 +3054,8 @@ sequence of characters that give the order and type of values, as
 follows:
 
     a	A string with arbitrary binary data, will be null padded.
-    A	An ASCII string, will be space padded.
-    Z	A null terminated (asciz) string, will be null padded.
+    A	A text (ASCII) string, will be space padded.
+    Z	A null terminated (ASCIZ) string, will be null padded.
 
     b	A bit string (ascending bit order inside each byte, like vec()).
     B	A bit string (descending bit order inside each byte).
@@ -3034,8 +3104,8 @@ follows:
     P	A pointer to a structure (fixed-length string).
 
     u	A uuencoded string.
-    U	A Unicode character number.  Encodes to UTF-8 internally.
-	Works even if C<use utf8> is not in effect.
+    U	A Unicode character number.  Encodes to UTF-8 internally
+	(or UTF-EBCDIC in EBCDIC platforms).
 
     w	A BER compressed integer.  Its bytes represent an unsigned
 	integer in base 128, most significant digit first, with as
@@ -3201,7 +3271,7 @@ not support long longs.)
 The integer formats C<s>, C<S>, C<i>, C<I>, C<l>, and C<L>
 are inherently non-portable between processors and operating systems
 because they obey the native byteorder and endianness.  For example a
-4-byte integer 0x12345678 (305419896 decimal) be ordered natively
+4-byte integer 0x12345678 (305419896 decimal) would be ordered natively
 (arranged in and handled by the CPU registers) into bytes as
 
  	0x12 0x34 0x56 0x78	# big-endian
@@ -3210,7 +3280,8 @@ because they obey the native byteorder and endianness.  For example a
 Basically, the Intel and VAX CPUs are little-endian, while everybody
 else, for example Motorola m68k/88k, PPC, Sparc, HP PA, Power, and
 Cray are big-endian.  Alpha and MIPS can be either: Digital/Compaq
-used/uses them in little-endian mode; SGI/Cray uses them in big-endian mode.
+used/uses them in little-endian mode; SGI/Cray uses them in big-endian
+mode.
 
 The names `big-endian' and `little-endian' are comic references to
 the classic "Gulliver's Travels" (via the paper "On Holy Wars and a
@@ -3237,7 +3308,7 @@ Byteorders C<'1234'> and C<'12345678'> are little-endian, C<'4321'>
 and C<'87654321'> are big-endian.
 
 If you want portable packed integers use the formats C<n>, C<N>,
-C<v>, and C<V>, their byte endianness and size is known.
+C<v>, and C<V>, their byte endianness and size are known.
 See also L<perlport>.
 
 =item *
@@ -3357,8 +3428,10 @@ C<$::sail> is equivalent to C<$main::sail> (as well as to C<$main'sail>,
 still seen in older code).
 
 If NAMESPACE is omitted, then there is no current package, and all
-identifiers must be fully qualified or lexicals.  This is stricter
-than C<use strict>, since it also extends to function names.
+identifiers must be fully qualified or lexicals.  However, you are
+strongly advised not to make use of this feature. Its use can cause
+unexpected behaviour, even crashing some versions of Perl. It is
+deprecated, and will be removed from a future release.
 
 See L<perlmod/"Packages"> for more information about packages, modules,
 and classes.  See L<perlsub> for other scoping issues.
@@ -3441,9 +3514,10 @@ you will have to use a block returning its value instead:
 
 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.  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>.
+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>.
 
 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
@@ -3505,8 +3579,15 @@ If EXPR is omitted, uses C<$_>.
 
 Returns a random fractional number greater than or equal to C<0> and less
 than the value of EXPR.  (EXPR should be positive.)  If EXPR is
-omitted, the value C<1> is used.  Automatically calls C<srand> unless
-C<srand> has already been called.  See also C<srand>.
+omitted, or a C<0>, the value C<1> is used.  Automatically calls C<srand>
+unless C<srand> has already been called.  See also C<srand>.
+
+Apply C<int()> to the value returned by C<rand()> if you want random
+integers instead of random fractional numbers.  For example,
+
+    int(rand(10))
+
+returns a random integer between C<0> and C<9>, inclusive.
 
 (Note: If your rand function consistently returns numbers that are too
 large or too small, then your version of Perl was probably compiled
@@ -3679,19 +3760,23 @@ rename(2) manpage or equivalent system documentation for details.
 
 =item require
 
-Demands some semantics specified by EXPR, or by C<$_> if EXPR is not
-supplied.
+Demands a version of Perl specified by VERSION, or demands some semantics
+specified by EXPR or by C<$_> if EXPR is not supplied.
+
+VERSION may be either a numeric argument such as 5.006, which will be
+compared to C<$]>, or a literal of the form v5.6.1, which will be compared
+to C<$^V> (aka $PERL_VERSION).  A fatal error is produced at run time if
+VERSION is greater than the version of the current Perl interpreter.
+Compare with L</use>, which can do a similar check at compile time.
 
-If a VERSION is specified as a literal of the form v5.6.1,
-demands that the current version of Perl (C<$^V> or $PERL_VERSION) be
-at least as recent as that version, at run time.  (For compatibility
-with older versions of Perl, a numeric argument will also be interpreted
-as VERSION.)  Compare with L</use>, which can do a similar check at
-compile time.
+Specifying VERSION as a literal of the form v5.6.1 should generally be
+avoided, because it leads to misleading error messages under earlier
+versions of Perl which do not support this syntax.  The equivalent numeric
+version should be used instead.
 
     require v5.6.1;	# run time version check
     require 5.6.1;	# ditto
-    require 5.005_03;	# float version allowed for compatibility
+    require 5.006_001;	# ditto; preferred for backwards compatibility
 
 Otherwise, demands that a library file be included if it hasn't already
 been included.  The file is included via the do-FILE mechanism, which is
@@ -3750,6 +3835,60 @@ will complain about not finding "F<Foo::Bar>" there.  In this case you can do:
 
         eval "require $class";
 
+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.
+
+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.
+
+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
+the array reference.  This enables to pass indirectly some arguments to
+the subroutine.
+
+In other words, you can write:
+
+    push @INC, \&my_sub;
+    sub my_sub {
+	my ($coderef, $filename) = @_;	# $coderef is \&my_sub
+	...
+    }
+
+or:
+
+    push @INC, [ \&my_sub, $x, $y, ... ];
+    sub my_sub {
+	my ($arrayref, $filename) = @_;
+	# Retrieve $x, $y, ...
+	my @parameters = @$arrayref[1..$#$arrayref];
+	...
+    }
+
+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:
+
+    # In Foo.pm
+    package Foo;
+    sub new { ... }
+    sub Foo::INC {
+	my ($self, $filename) = @_;
+	...
+    }
+
+    # In the main program
+    push @INC, new Foo(...);
+
+Note that these hooks are also permitted to set the %INC entry
+corresponding to the files they have loaded. See L<perlvar/%INC>.
+
 For a yet-more-powerful import facility, see L</use> and L<perlmod>.
 
 =item reset EXPR
@@ -3786,7 +3925,7 @@ may vary from one execution to the next (see C<wantarray>).  If no EXPR
 is given, returns an empty list in list context, the undefined value in
 scalar context, and (of course) nothing at all in a void context.
 
-(Note that in the absence of a explicit C<return>, a subroutine, eval,
+(Note that in the absence of an explicit C<return>, a subroutine, eval,
 or do FILE will automatically return the value of the last expression
 evaluated.)
 
@@ -3976,7 +4115,7 @@ calling select() in scalar context just returns $nfound.
 
 Any of the bit masks can also be undef.  The timeout, if specified, is
 in seconds, which may be fractional.  Note: not all implementations are
-capable of returning the$timeleft.  If not, they always return
+capable of returning the $timeleft.  If not, they always return
 $timeleft equal to the supplied $timeout.
 
 You can effect a sleep of 250 milliseconds this way:
@@ -4012,14 +4151,14 @@ documentation.
 =item semop KEY,OPSTRING
 
 Calls the System V IPC function semop to perform semaphore operations
-such as signaling and waiting.  OPSTRING must be a packed array of
+such as signalling and waiting.  OPSTRING must be a packed array of
 semop structures.  Each semop structure can be generated with
-C<pack("sss", $semnum, $semop, $semflag)>.  The number of semaphore
+C<pack("s!3", $semnum, $semop, $semflag)>.  The number of semaphore
 operations is implied by the length of OPSTRING.  Returns true if
 successful, or false if there is an error.  As an example, the
 following code waits on semaphore $semnum of semaphore id $semid:
 
-    $semop = pack("sss", $semnum, -1, 0);
+    $semop = pack("s!3", $semnum, -1, 0);
     die "Semaphore trouble: $!\n" unless semop($semid, $semop);
 
 To signal the semaphore, replace C<-1> with C<1>.  See also
@@ -4150,11 +4289,32 @@ busy multitasking system.
 
 For delays of finer granularity than one second, you may use Perl's
 C<syscall> interface to access setitimer(2) if your system supports
-it, or else see L</select> above.  The Time::HiRes module from CPAN
-may also help.
+it, or else see L</select> above.  The Time::HiRes module (from CPAN,
+and starting from Perl 5.8 part of the standard distribution) may also
+help.
 
 See also the POSIX module's C<pause> function.
 
+=item sockatmark SOCKET
+
+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
@@ -4222,6 +4382,12 @@ loop control operators described in L<perlsyn> or with C<goto>.
 When C<use locale> is in effect, C<sort LIST> sorts LIST according to the
 current collation locale.  See L<perllocale>.
 
+Perl does B<not> guarantee that sort is stable.  (A I<stable> sort
+preserves the input order of elements that compare equal.)  5.7 and
+5.8 happen to use a stable mergesort, but 5.6 and earlier used quicksort,
+which is not stable.  Do not assume that future perls will continue to
+use a stable sort.
+
 Examples:
 
     # sort lexically
@@ -4378,11 +4544,15 @@ splits on whitespace (after skipping any leading whitespace).  Anything
 matching PATTERN is taken to be a delimiter separating the fields.  (Note
 that the delimiter may be longer than one character.)
 
-If LIMIT is specified and positive, splits into no more than that
-many fields (though it may split into fewer).  If LIMIT is unspecified
-or zero, trailing null fields are stripped (which potential users
-of C<pop> would do well to remember).  If LIMIT is negative, it is
-treated as if an arbitrarily large LIMIT had been specified.
+If LIMIT is specified and positive, it represents the maximum number
+of fields the EXPR will be split into, though the actual number of
+fields returned depends on the number of times PATTERN matches within
+EXPR.  If LIMIT is unspecified or zero, trailing null fields are
+stripped (which potential users of C<pop> would do well to remember).
+If LIMIT is negative, it is treated as if an arbitrarily large LIMIT
+had been specified.  Note that splitting an EXPR that evaluates to the
+empty string always returns the empty list, regardless of the LIMIT
+specified.
 
 A pattern matching the null string (not to be confused with
 a null pattern C<//>, which is just one member of the set of patterns
@@ -4393,6 +4563,10 @@ characters at each point it matches that way.  For example:
 
 produces the output 'h:i:t:h:e:r:e'.
 
+Using the empty pattern C<//> specifically matches the null string, and is
+not be confused with the use of C<//> to mean "the last successful pattern
+match".
+
 Empty leading (or trailing) fields are produced when there positive width
 matches at the beginning (or end) of the string; a zero-width match at the
 beginning (or end) of the string does not produce an empty field.  For
@@ -4452,6 +4626,11 @@ Example:
 	#...
     }
 
+As with regular pattern matching, any capturing parentheses that are not
+matched in a C<split()> will be set to C<undef> when returned:
+
+    @fields = split /(A)|B/, "1A2B3";
+    # @fields is (1, 'A', 2, undef, 3)
 
 =item sprintf FORMAT, LIST
 
@@ -4630,19 +4809,42 @@ loaded the standard Math::Complex module.
 
 =item srand
 
-Sets the random number seed for the C<rand> operator.  If EXPR is
-omitted, uses a semi-random value supplied by the kernel (if it supports
-the F</dev/urandom> device) or based on the current time and process
-ID, among other things.  In versions of Perl prior to 5.004 the default
-seed was just the current C<time>.  This isn't a particularly good seed,
-so many old programs supply their own seed value (often C<time ^ $$> or
-C<time ^ ($$ + ($$ << 15))>), but that isn't necessary any more.
+Sets the random number seed for the C<rand> operator.
+
+The point of the function is to "seed" the C<rand> function so that
+C<rand> can produce a different sequence each time you run your
+program.
+
+If srand() is not called explicitly, it is called implicitly at the
+first use of the C<rand> operator.  However, this was not the case in
+versions of Perl before 5.004, so if your script will run under older
+Perl versions, it should call C<srand>.
+
+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. 
+
+You can call srand($seed) with the same $seed to reproduce the
+I<same> sequence from rand(), but this is usually reserved for
+generating predictable results for testing or debugging.
+Otherwise, don't call srand() more than once in your program.
+
+Do B<not> call srand() (i.e. without an argument) more than once in
+a script.  The internal state of the random number generator should
+contain more entropy than can be provided by any seed, so calling
+srand() again actually I<loses> randomness.
 
-In fact, it's usually not necessary to call C<srand> at all, because if
-it is not called explicitly, it is called implicitly at the first use of
-the C<rand> operator.  However, this was not the case in version of Perl
-before 5.004, so if your script will run under older Perl versions, it
-should call C<srand>.
+Most implementations of C<srand> take an integer and will silently
+truncate decimal numbers.  This means C<srand(42)> will usually
+produce the same results as C<srand(42.1)>.  To be safe, always pass
+C<srand> an integer.
+
+In versions of Perl prior to 5.004 the default seed was just the
+current C<time>.  This isn't a particularly good seed, so many old
+programs supply their own seed value (often C<time ^ $$> or C<time ^
+($$ + ($$ << 15))>), but that isn't necessary any more.
 
 Note that you need something much more random than the default seed for
 cryptographic purposes.  Checksumming the compressed output of one or more
@@ -4654,12 +4856,6 @@ example:
 If you're particularly concerned with this, see the C<Math::TrulyRandom>
 module in CPAN.
 
-Do I<not> call C<srand> multiple times in your program unless you know
-exactly what you're doing and why you're doing it.  The point of the
-function is to "seed" the C<rand> function so that C<rand> can produce
-a different sequence each time you run your program.  Just do it once at the
-top of your program, or you I<won't> get random numbers out of C<rand>!
-
 Frequently called programs (like CGI scripts) that simply use
 
     time ^ $$
@@ -5250,6 +5446,8 @@ seconds, for this process and the children of this process.
 
     ($user,$system,$cuser,$csystem) = times;
 
+In scalar context, C<times> returns C<$user>.
+
 =item tr///
 
 The transliteration operator.  Same as C<y///>.  See L<perlop>.
@@ -5268,10 +5466,11 @@ otherwise.
 =item uc
 
 Returns an uppercased version of EXPR.  This is the internal function
-implementing the C<\U> escape in double-quoted strings.
-Respects current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>.
-Under Unicode (C<use utf8>) it uses the standard Unicode uppercase mappings.  (It
-does not attempt to do titlecase mapping on initial letters.  See C<ucfirst> for that.)
+implementing the C<\U> escape in double-quoted strings.  Respects
+current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>
+and L<perlunicode> for more details about locale and Unicode support.
+It does not attempt to do titlecase mapping on initial letters.  See
+C<ucfirst> for that.
 
 If EXPR is omitted, uses C<$_>.
 
@@ -5279,11 +5478,11 @@ If EXPR is omitted, uses C<$_>.
 
 =item ucfirst
 
-Returns the value of EXPR with the first character
-in uppercase (titlecase in Unicode).  This is
-the internal function implementing the C<\u> escape in double-quoted strings.
-Respects current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>
-and L<utf8>.
+Returns the value of EXPR with the first character in uppercase
+(titlecase in Unicode).  This is the internal function implementing
+the C<\u> escape in double-quoted strings.  Respects current LC_CTYPE
+locale if C<use locale> in force.  See L<perllocale> and L<perlunicode>
+for more details about locale and Unicode support.
 
 If EXPR is omitted, uses C<$_>.
 
@@ -5431,7 +5630,7 @@ Does the opposite of a C<shift>.  Or the opposite of a C<push>,
 depending on how you look at it.  Prepends list to the front of the
 array, and returns the new number of elements in the array.
 
-    unshift(ARGV, '-e') unless $ARGV[0] =~ /^-/;
+    unshift(@ARGV, '-e') unless $ARGV[0] =~ /^-/;
 
 Note the LIST is prepended whole, not one element at a time, so the
 prepended elements stay in the same order.  Use C<reverse> to do the
@@ -5455,18 +5654,21 @@ package.  It is exactly equivalent to
 
 except that Module I<must> be a bareword.
 
-VERSION, which can be specified as a literal of the form v5.6.1, demands
-that the current version of Perl (C<$^V> or $PERL_VERSION) be at least
-as recent as that version.  (For compatibility with older versions of Perl,
-a numeric literal will also be interpreted as VERSION.)  If the version
-of the running Perl interpreter is less than VERSION, then an error
-message is printed and Perl exits immediately without attempting to
-parse the rest of the file.  Compare with L</require>, which can do a
-similar check at run time.
+VERSION may be either a numeric argument such as 5.006, which will be
+compared to C<$]>, or a literal of the form v5.6.1, which will be compared
+to C<$^V> (aka $PERL_VERSION.  A fatal error is produced if VERSION is
+greater than the version of the current Perl interpreter; Perl will not
+attempt to parse the rest of the file.  Compare with L</require>, which can
+do a similar check at run time.
+
+Specifying VERSION as a literal of the form v5.6.1 should generally be
+avoided, because it leads to misleading error messages under earlier
+versions of Perl which do not support this syntax.  The equivalent numeric
+version should be used instead.
 
     use v5.6.1;		# compile time version check
     use 5.6.1;		# ditto
-    use 5.005_03;	# float version allowed for compatibility
+    use 5.006_001;	# ditto; preferred for backwards compatibility
 
 This is often useful if you need to check the current Perl version before
 C<use>ing library modules that have changed in incompatible ways from
@@ -5543,6 +5745,13 @@ command if the files already exist:
     $now = time;
     utime $now, $now, @ARGV;
 
+If the first two elements of the list are C<undef>, then the utime(2)
+function in the C library will be called with a null second argument.
+On most systems, this will set the file's access and modification
+times to the current time.  (i.e. equivalent to the example above.)
+
+    utime undef, undef, @ARGV;
+
 =item values HASH
 
 Returns a list consisting of all the values of the named hash.  (In a
@@ -5819,7 +6028,7 @@ The status is returned in C<$?>.  If you say
     use POSIX ":sys_wait_h";
     #...
     do {
-	$kid = waitpid(-1,&WNOHANG);
+	$kid = waitpid(-1, WNOHANG);
     } until $kid == -1;
 
 then you can do a non-blocking wait for all pending zombie processes.