X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=0570c8fe64b2015f8784f32734992dfc46ac57a0;hb=b74bceb9cc5d8f31510279b2c34ea465fe21fd8f;hp=913f6f8fbddf29125a4e7368a2cdb27ff9678ab5;hpb=74a7701791a30556a92328b89e5a00414a4ce4a3;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 913f6f8..0570c8f 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1,3 +1,4 @@
+
 =head1 NAME
 
 perlfunc - Perl builtin functions
@@ -79,117 +80,120 @@ than one place.
 
 =item Functions for SCALARs or strings
 
-chomp, chop, chr, crypt, hex, index, lc, lcfirst, length,
-oct, ord, pack, q/STRING/, qq/STRING/, reverse, rindex,
-sprintf, substr, tr///, uc, ucfirst, y///
+C<chomp>, C<chop>, C<chr>, C<crypt>, C<hex>, C<index>, C<lc>, C<lcfirst>,
+C<length>, C<oct>, C<ord>, C<pack>, C<q>/STRING/, C<qq>/STRING/, C<reverse>,
+C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y>///
 
 =item Regular expressions and pattern matching
 
-m//, pos, quotemeta, s///, split, study
+C<m>//, C<pos>, C<quotemeta>, C<s>///, C<split>, C<study>
 
 =item Numeric functions
 
-abs, atan2, cos, exp, hex, int, log, oct, rand, sin, sqrt,
-srand
+C<abs>, C<atan2>, C<cos>, C<exp>, C<hex>, C<int>, C<log>, C<oct>, C<rand>,
+C<sin>, C<sqrt>, C<srand>
 
 =item Functions for real @ARRAYs
 
-pop, push, shift, splice, unshift
+C<pop>, C<push>, C<shift>, C<splice>, C<unshift>
 
 =item Functions for list data
 
-grep, join, map, qw/STRING/, reverse, sort, unpack
+C<grep>, C<join>, C<map>, C<qw>/STRING/, C<reverse>, C<sort>, C<unpack>
 
 =item Functions for real %HASHes
 
-delete, each, exists, keys, values
+C<delete>, C<each>, C<exists>, C<keys>, C<values>
 
 =item Input and output functions
 
-binmode, close, closedir, dbmclose, dbmopen, die, eof,
-fileno, flock, format, getc, print, printf, read, readdir,
-rewinddir, seek, seekdir, select, syscall, sysread, sysseek,
-syswrite, tell, telldir, truncate, warn, write
+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<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>, C<truncate>,
+C<warn>, C<write>
 
 =item Functions for fixed length data or records
 
-pack, read, syscall, sysread, syswrite, unpack, vec
+C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec>
 
 =item Functions for filehandles, files, or directories
 
-I<-X>, chdir, chmod, chown, chroot, fcntl, glob, ioctl, link,
-lstat, mkdir, open, opendir, readlink, rename, rmdir,
-stat, symlink, umask, unlink, utime
+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>
 
 =item Keywords related to the control flow of your perl program
 
-caller, continue, die, do, dump, eval, exit, goto, last,
-next, redo, return, sub, wantarray
+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 scoping
 
-caller, import, local, my, package, use
+C<caller>, C<import>, C<local>, C<my>, C<package>, C<use>
 
 =item Miscellaneous functions
 
-defined, dump, eval, formline, local, my, reset, scalar,
-undef, wantarray
+C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<reset>,
+C<scalar>, C<undef>, C<wantarray>
 
 =item Functions for processes and process groups
 
-alarm, exec, fork, getpgrp, getppid, getpriority, kill,
-pipe, qx/STRING/, setpgrp, setpriority, sleep, system,
-times, wait, waitpid
+C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>,
+C<pipe>, C<qx>/STRING/, C<setpgrp>, C<setpriority>, C<sleep>, C<system>,
+C<times>, C<wait>, C<waitpid>
 
 =item Keywords related to perl modules
 
-do, import, no, package, require, use
+C<do>, C<import>, C<no>, C<package>, C<require>, C<use>
 
 =item Keywords related to classes and object-orientedness
 
-bless, dbmclose, dbmopen, package, ref, tie, tied, untie, use
+C<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>,
+C<untie>, C<use>
 
 =item Low-level socket functions
 
-accept, bind, connect, getpeername, getsockname,
-getsockopt, listen, recv, send, setsockopt, shutdown,
-socket, socketpair
+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>
 
 =item System V interprocess communication functions
 
-msgctl, msgget, msgrcv, msgsnd, semctl, semget, semop,
-shmctl, shmget, shmread, shmwrite
+C<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<semctl>, C<semget>, C<semop>,
+C<shmctl>, C<shmget>, C<shmread>, C<shmwrite>
 
 =item Fetching user and group info
 
-endgrent, endhostent, endnetent, endpwent, getgrent,
-getgrgid, getgrnam, getlogin, getpwent, getpwnam,
-getpwuid, setgrent, setpwent
+C<endgrent>, C<endhostent>, C<endnetent>, C<endpwent>, C<getgrent>,
+C<getgrgid>, C<getgrnam>, C<getlogin>, C<getpwent>, C<getpwnam>,
+C<getpwuid>, C<setgrent>, C<setpwent>
 
 =item Fetching network info
 
-endprotoent, endservent, gethostbyaddr, gethostbyname,
-gethostent, getnetbyaddr, getnetbyname, getnetent,
-getprotobyname, getprotobynumber, getprotoent,
-getservbyname, getservbyport, getservent, sethostent,
-setnetent, setprotoent, setservent
+C<endprotoent>, C<endservent>, C<gethostbyaddr>, C<gethostbyname>,
+C<gethostent>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
+C<getprotobyname>, C<getprotobynumber>, C<getprotoent>,
+C<getservbyname>, C<getservbyport>, C<getservent>, C<sethostent>,
+C<setnetent>, C<setprotoent>, C<setservent>
 
 =item Time-related functions
 
-gmtime, localtime, time, times
+C<gmtime>, C<localtime>, C<time>, C<times>
 
 =item Functions new in perl5
 
-abs, bless, chomp, chr, exists, formline, glob, import, lc,
-lcfirst, map, my, no, prototype, qx, qw, readline, readpipe,
-ref, sub*, sysopen, tie, tied, uc, ucfirst, untie, use
+C<abs>, C<bless>, C<chomp>, C<chr>, C<exists>, C<formline>, C<glob>,
+C<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<prototype>, C<qx>,
+C<qw>, C<readline>, C<readpipe>, C<ref>, C<sub*>, C<sysopen>, C<tie>,
+C<tied>, C<uc>, C<ucfirst>, C<untie>, C<use>
 
 * - C<sub> was a keyword in perl4, but in perl5 it is an
 operator which can be used in expressions.
 
 =item Functions obsoleted in perl5
 
-dbmclose, dbmopen
+C<dbmclose>, C<dbmopen>
 
 =back
 
@@ -197,11 +201,11 @@ dbmclose, dbmopen
 
 =over 8
 
-=item -X FILEHANDLE
+=item I<-X> FILEHANDLE
 
-=item -X EXPR
+=item I<-X> EXPR
 
-=item -X
+=item I<-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
@@ -448,7 +452,7 @@ successfully changed.  See also L</oct>, if all you have is a string.
 
 =item chomp
 
-This is a slightly safer version of chop (see below).  It removes any
+This is a slightly safer version of L</chop>.  It removes any
 line ending that corresponds to the current value of C<$/> (also known as
 $INPUT_RECORD_SEPARATOR in the C<English> module).  It returns the total
 number of characters removed from all its arguments.  It's often used to
@@ -551,19 +555,30 @@ omitted, does chroot to $_.
 
 Closes the file or pipe associated with the file handle, returning TRUE
 only if stdio successfully flushes buffers and closes the system file
-descriptor.  You don't have to close FILEHANDLE if you are immediately
-going to do another open() on it, because open() will close it for you.  (See
+descriptor.
+
+You don't have to close FILEHANDLE if you are immediately going to do
+another open() on it, because open() will close it for you.  (See
 open().)  However, an explicit close on an input file resets the line
-counter ($.), while the implicit close done by open() does not.  Also,
-closing a pipe will wait for the process executing on the pipe to
-complete, in case you want to look at the output of the pipe
-afterwards.  Closing a pipe explicitly also puts the status value of
-the command into C<$?>.  Example:
+counter ($.), while the implicit close done by open() does not.
+
+If the file handle came from a piped open C<close> will additionally
+return FALSE if one of the other system calls involved fails or if the
+program exits with non-zero status.  (If the only problem was that the
+program exited non-zero $! will be set to 0.) Also, closing a pipe will
+wait for the process executing on the pipe to complete, in case you
+want to look at the output of the pipe afterwards.  Closing a pipe
+explicitly also puts the exit status value of the command into C<$?>.
+Example:
 
-    open(OUTPUT, '|sort >foo');	# pipe to sort
+    open(OUTPUT, '|sort >foo')  # pipe to sort
+        or die "Can't start sort: $!";
     ...				# print stuff to output
-    close OUTPUT;		# wait for sort to finish
-    open(INPUT, 'foo');		# get sort's results
+    close OUTPUT		# wait for sort to finish
+        or warn $! ? "Error closing sort pipe: $!"
+                   : "Exit status $? from sort";
+    open(INPUT, 'foo')		# get sort's results
+        or die "Can't open 'foo' for input: $!";
 
 FILEHANDLE may be an expression whose value gives the real filehandle name.
 
@@ -629,7 +644,7 @@ their own password:
 	print "ok\n";
     }
 
-Of course, typing in your own password to whomever asks you
+Of course, typing in your own password to whoever asks you
 for it is unwise.
 
 =item dbmclose HASH
@@ -799,11 +814,28 @@ produce, respectively
 
 See also exit() and warn().
 
+If LIST is empty and $@ already contains a value (typically from a
+previous eval) that value is reused after appending "\t...propagated".
+This is useful for propagating exceptions:
+
+    eval { ... };
+    die unless $@ =~ /Expected exception/;
+
+If $@ is empty then the string "Died" is used.
+
 You can arrange for a callback to be called just before the die() does
 its deed, by setting the C<$SIG{__DIE__}> hook.  The associated handler
 will be called with the error text and can change the error message, if
-it sees fit, by calling die() again.  See L<perlvar> for details on
-setting C<%SIG> entries, and eval() for some examples.
+it sees fit, by calling die() again.  See L<perlvar/$SIG{expr}> for details on
+setting C<%SIG> entries, and L<"eval BLOCK"> for some examples.
+
+Note that the C<$SIG{__DIE__}> hook is called even inside eval()ed
+blocks/strings.  If one wants the hook to do nothing in such
+situations, put
+
+	die @_ if $^S;
+
+as the first line of the handler (see L<perlvar/$^S>).
 
 =item do BLOCK
 
@@ -826,7 +858,7 @@ from a Perl subroutine library.
 
 is just like
 
-    eval `cat stat.pl`;
+    scalar eval `cat stat.pl`;
 
 except that it's more efficient, more concise, keeps track of the
 current filename for error messages, and searches all the B<-I>
@@ -944,22 +976,38 @@ input operators return undef when they run out of data.
 
 =item eval BLOCK
 
-EXPR is parsed and executed as if it were a little Perl program.  It
-is executed in the context of the current Perl program, so that any
+In the first form, the return value of EXPR is parsed and executed as if it
+were a little Perl program.  The value of the expression (which is itself
+determined within a scalar context) is first parsed, and if there are no
+errors, executed in the context of the current Perl program, so that any
 variable settings or subroutine and format definitions remain afterwards.
-The value returned is the value of the last expression evaluated, or a
-return statement may be used, just as with subroutines.  The last
-expression is evaluated in scalar or array context, depending on the
-context of the eval.
+Note that the value is parsed every time the eval executes.  If EXPR is
+omitted, evaluates C<$_>.  This form is typically used to delay parsing
+and subsequent execution of the text of EXPR until run time.
+
+In the second form, the code within the BLOCK is parsed only once--at the
+same time the code surrounding the eval itself was parsed--and executed
+within the context of the current Perl program.  This form is typically
+used to trap exceptions more efficiently than the first (see below), while
+also providing the benefit of checking the code within BLOCK at compile
+time.
+
+The final semicolon, if any, may be omitted from the value of EXPR or within
+the BLOCK.
+
+In both forms, the value returned is the value of the last expression
+evaluated inside the mini-program, or a return statement may be used, just
+as with subroutines.  The expression providing the return value is evaluated
+in void, scalar or array context, depending on the context of the eval itself.
+See L</wantarray> for more on how the evaluation context can be determined.
 
 If there is a syntax error or runtime error, or a die() statement is
 executed, an undefined value is returned by eval(), and C<$@> is set to the
 error message.  If there was no error, C<$@> is guaranteed to be a null
-string.  If EXPR is omitted, evaluates C<$_>.  The final semicolon, if
-any, may be omitted from the expression.  Beware that using eval()
-neither silences perl from printing warnings to STDERR, nor does it
-stuff the text of warning messages into C<$@>.  To do either of those,
-you have to use the C<$SIG{__WARN__}> facility.  See warn() and L<perlvar>.
+string.  Beware that using eval() neither silences perl from printing
+warnings to STDERR, nor does it stuff the text of warning messages into C<$@>.
+To do either of those, you have to use the C<$SIG{__WARN__}> facility.  See
+L</warn> and L<perlvar>.
 
 Note that, because eval() traps otherwise-fatal errors, it is useful for
 determining whether a particular feature (such as socket() or symlink())
@@ -997,8 +1045,8 @@ die() again, which has the effect of changing their error messages:
     # __DIE__ hooks may modify error messages
     {
        local $SIG{'__DIE__'} = sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
-       eval { die "foo foofs here" };
-       print $@ if $@;                # prints "bar barfs here"
+       eval { die "foo lives here" };
+       print $@ if $@;                # prints "bar lives here"
     }
 
 With an eval(), you should be especially careful to remember what's
@@ -1026,19 +1074,21 @@ in case 6.
 
 =item exec LIST
 
-The exec() function executes a system command I<AND NEVER RETURNS>,
-unless the command does not exist and is executed directly instead of
-via C</bin/sh -c> (see below).  Use system() instead of exec() if you
-want it to return.
+The exec() function executes a system command I<AND NEVER RETURNS> -
+use system() instead of exec() if you want it to return. It fails and
+returns FALSE only if the command does not exist I<and> it is executed
+directly instead of via your system's command shell (see below).
 
 If there is more than one argument in LIST, or if LIST is an array with
 more than one value, calls execvp(3) with the arguments in LIST.  If
 there is only one scalar argument, the argument is checked for shell
-metacharacters.  If there are any, the entire argument is passed to
-C</bin/sh -c> for parsing.  If there are none, the argument is split
-into words and passed directly to execvp(), which is more efficient.
-Note: exec() and system() do not flush your output buffer, so you may
-need to set C<$|> to avoid lost output.  Examples:
+metacharacters, and if there are any, the entire argument is passed to
+the system's command shell for parsing (this is C</bin/sh -c> on Unix
+platforms, but varies on other platforms).  If there are no shell
+metacharacters in the argument, it is split into words and passed
+directly to execvp(), which is more efficient.  Note: exec() and
+system() do not flush your output buffer, so you may need to set C<$|>
+to avoid lost output.  Examples:
 
     exec '/bin/echo', 'Your arguments are: ', @ARGV;
     exec "sort $outfile | uniq";
@@ -1057,6 +1107,10 @@ or, more directly,
 
     exec {'/bin/csh'} '-sh';	# pretend it's a login shell
 
+When the arguments get executed via the system shell, results will
+be subject to its quirks and capabilities.  See L<perlop/"`STRING`">
+for details.
+
 =item exists EXPR
 
 Returns TRUE if the specified hash key exists in its hash array, even
@@ -1522,8 +1576,11 @@ supported, it can cause bizarre results if the LIST is not a named
 array.  Similarly, grep returns aliases into the original list,
 much like the way that L<Foreach Loops>'s index variable aliases the list
 elements.  That is, modifying an element of a list returned by grep
+(for example, in a C<foreach>, C<map> or another C<grep>)
 actually modifies the element in the original list.
 
+See also L</map> for an array composed of the results of the BLOCK or EXPR.
+
 =item hex EXPR
 
 =item hex
@@ -1727,7 +1784,7 @@ it succeeded, FALSE otherwise.  See example in L<perlipc/"Sockets: Client/Server
 A local modifies the listed variables to be local to the enclosing block,
 subroutine, C<eval{}>, or C<do>.  If more than one value is listed, the
 list must be placed in parentheses.  See L<perlsub/"Temporary Values via
-local()"> for details.
+local()"> for details, including issues with tied arrays and hashes.
 
 But you really probably want to be using my() instead, because local() isn't
 what most people think of as "local").  See L<perlsub/"Private Variables
@@ -1754,6 +1811,8 @@ In a scalar context, returns the ctime(3) value:
 
     $now_string = localtime;  # e.g., "Thu Oct 13 04:54:34 1994"
 
+This scalar value is B<not> locale dependent, see L<perllocale>,
+but instead a Perl builtin.
 Also see the Time::Local module, and the strftime(3) and mktime(3)
 function available via the POSIX module.
 
@@ -1802,6 +1861,12 @@ is just a funny way to write
 	$hash{getkey($_)} = $_;
     }
 
+Note that, because $_ is a reference into the list value, it can be used
+to modify the elements of the array.  While this is useful and
+supported, it can cause bizarre results if the LIST is not a named
+array.  See also L</grep> for an array composed of those items of the 
+original list for which the BLOCK or EXPR evaluates to true.
+
 =item mkdir FILENAME,MODE
 
 Creates the directory specified by FILENAME, with permissions specified
@@ -1922,6 +1987,14 @@ and those that don't is their text file formats.  Systems like Unix and
 Plan9 that delimit lines with a single character, and that encode that
 character in C as '\n', do not need C<binmode>.  The rest need it.
 
+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,
+where you want to make a nicely formatted error message (but there are
+modules which can help with that problem)) you should always check
+the return value from opening a file. The infrequent exception is when
+working with an unopened filehandle is actually what you want to do.
+
 Examples:
 
     $ARTICLE = 100;
@@ -1929,12 +2002,16 @@ Examples:
     while (<ARTICLE>) {...
 
     open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
+    # if the open fails, output is discarded
 
-    open(DBASE, '+<dbase.mine');	    # open for update
+    open(DBASE, '+<dbase.mine')		    # open for update
+	or die "Can't open 'dbase.mine' for update: $!";
 
-    open(ARTICLE, "caesar <$article |");    # decrypt article
+    open(ARTICLE, "caesar <$article |")     # decrypt article
+	or die "Can't start caesar: $!";
 
-    open(EXTRACT, "|sort >/tmp/Tmp$$");     # $$ is our process id
+    open(EXTRACT, "|sort >/tmp/Tmp$$")      # $$ is our process id
+	or die "Can't start sort: $!";
 
     # process argument list of files along with any includes
 
@@ -2020,12 +2097,13 @@ The following pairs are more or less equivalent:
 
 See L<perlipc/"Safe Pipe Opens"> for more examples of this.
 
-Explicitly closing any piped filehandle causes the parent process to
-wait for the child to finish, and returns the status value in C<$?>.
-Note: on any operation which may do a fork, unflushed buffers remain
+NOTE: On any operation which may do a fork, unflushed buffers remain
 unflushed in both processes, which means you may need to set C<$|> to
 avoid duplicate output.
 
+Closing any piped filehandle causes the parent process to wait for the
+child to finish, and returns the status value in C<$?>.
+
 Using the constructor from the IO::Handle package (or one of its
 subclasses, such as IO::File or IO::Socket),
 you can generate anonymous filehandles which have the scope of whatever
@@ -2145,8 +2223,13 @@ types gobble just one value, but pack it as a string of length count,
 padding with nulls or spaces as necessary.  (When unpacking, "A" strips
 trailing spaces and nulls, but "a" does not.)  Likewise, the "b" and "B"
 fields pack a string that many bits long.  The "h" and "H" fields pack a
-string that many nybbles long.  The "P" packs a pointer to a structure of
-the size indicated by the length.  Real numbers (floats and doubles) are
+string that many nybbles long.  The "p" type packs a pointer to a null-
+terminated string.  You are responsible for ensuring the string is not a
+temporary value (which can potentially get deallocated before you get
+around to using the packed result).  The "P" packs a pointer to a structure
+of the size indicated by the length. A NULL pointer is created if the 
+corresponding value for "p" or "P" is C<undef>.
+Real numbers (floats and doubles) are
 in the native machine format only; due to the multiplicity of floating
 formats around, and the lack of a standard "network" representation, no
 facility for interchange has been made.  This means that packed floating
@@ -2291,6 +2374,13 @@ Returns the prototype of a function as a string (or C<undef> if the
 function has no prototype).  FUNCTION is a reference to, or the name of,
 the function whose prototype you want to retrieve.
 
+If FUNCTION is a string starting with C<CORE::>, the rest is taken as
+a name for Perl builtin.  If builtin is not I<overridable> (such as
+C<qw>) or its arguments cannot be expressed by a prototype (such as
+C<system>) - in other words, the builtin does not behave like a Perl
+function - returns C<undef>.  Otherwise, the string describing the
+equivalent prototype is returned.
+
 =item push ARRAY,LIST
 
 Treats ARRAY as a stack, and pushes the values of LIST
@@ -2330,10 +2420,10 @@ If EXPR is omitted, uses $_.
 
 =item rand
 
-Returns a random fractional number between 0 and the value of EXPR.
-(EXPR should be positive.)  If EXPR is omitted, returns a value between
-0 and 1.  Automatically calls srand() unless srand() has already been
-called.  See also srand().
+Returns a random fractional number greater than or equal to 0 and less
+than the value of EXPR.  (EXPR should be positive.)  If EXPR is
+omitted, the value 1 is used.  Automatically calls srand() unless
+srand() has already been called.  See also srand().
 
 (Note: If your rand function consistently returns numbers that are too
 large or too small, then your version of Perl was probably compiled
@@ -2366,6 +2456,16 @@ chdir() there, it would have been testing the wrong file.
     @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
     closedir DIR;
 
+=item readline EXPR
+
+Reads from the file handle EXPR.  In scalar context, a single line
+is read and returned.  In list context, reads until end-of-file is
+reached and returns a list of lines (however you've defined lines
+with $/ or $INPUT_RECORD_SEPARATOR).
+This is the internal function implementing the C<E<lt>EXPRE<gt>>
+operator, but you can use it directly.  The C<E<lt>EXPRE<gt>>
+operator is discussed in more detail in L<perlop/"I/O Operators">.
+
 =item readlink EXPR
 
 =item readlink
@@ -2375,6 +2475,17 @@ implemented.  If not, gives a fatal error.  If there is some system
 error, returns the undefined value and sets C<$!> (errno).  If EXPR is
 omitted, uses $_.
 
+=item readpipe EXPR
+
+EXPR is interpolated and then executed as a system command.
+The collected standard output of the command is returned.
+In scalar context, it comes back as a single (potentially
+multi-line) string.  In list context, returns a list of lines
+(however you've defined lines with $/ or $INPUT_RECORD_SEPARATOR).
+This is the internal function implementing the C<qx/EXPR/>
+operator, but you can use it directly.  The C<qx/EXPR/>
+operator is discussed in more detail in L<perlop/"I/O Operators">.
+
 =item recv SOCKET,SCALAR,LEN,FLAGS
 
 Receives a message on a socket.  Attempts to receive LENGTH bytes of
@@ -2773,10 +2884,12 @@ argument.
 Shifts the first value of the array off and returns it, shortening the
 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
-@ARGV array in the main program, and the @_ array in subroutines.
-(This is determined lexically.)  See also unshift(), push(), and pop().
-Shift() and unshift() do the same thing to the left end of an array
-that pop() and push() do to the right end.
+@_ array within the lexical scope of subroutines and formats, and the
+@ARGV array at file scopes or within the lexical scopes established by
+the C<eval ''>, C<BEGIN {}>, C<END {}>, and C<INIT {}> constructs.
+See also unshift(), push(), and pop().  Shift() and unshift() do the
+same thing to the left end of an array that pop() and push() do to the
+right end.
 
 =item shmctl ID,CMD,ARG
 
@@ -3023,12 +3136,13 @@ value.)  The use of implicit split to @_ is deprecated, however.
 If EXPR is omitted, splits the $_ string.  If PATTERN is also omitted,
 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 is not negative, splits into no more than that many fields
-(though it may split into fewer).  If LIMIT is unspecified, trailing null
-fields are stripped (which potential users of pop() would do well to
-remember).  If LIMIT is negative, it is treated as if an arbitrarily large
-LIMIT had been specified.
+that the delimiter may be longer than one character.)
+
+If LIMIT is specified and is not negative, splits into no more than
+that many fields (though it may split into fewer).  If LIMIT is
+unspecified, trailing null fields are stripped (which potential users
+of pop() would do well to remember).  If LIMIT is negative, it is
+treated as if an arbitrarily large LIMIT had been 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
@@ -3062,7 +3176,7 @@ If you had the entire header of a normal Unix email message in $header,
 you could split it up into fields and their values this way:
 
     $header =~ s/\n\s+/ /g;  # fix continuation lines
-    %hdrs   =  (UNIX_FROM => split /^(.*?):\s*/m, $header);
+    %hdrs   =  (UNIX_FROM => split /^(\S*?):\s*/m, $header);
 
 The pattern C</PATTERN/> may be replaced with an expression to specify
 patterns that vary at runtime.  (To do runtime compilation only once,
@@ -3113,19 +3227,19 @@ Perl's sprintf() permits the following universally-known conversions:
    %f	a floating-point number, in fixed decimal notation
    %g	a floating-point number, in %e or %f notation
 
-In addition, Perl permits the following ANSI-invented conversions:
+In addition, Perl permits the following widely-supported conversions:
 
-   %i	a synonym for %d
    %X	like %x, but using upper-case letters
    %E	like %e, but using an upper-case "E"
    %G	like %g, but with an upper-case "E" (if applicable)
    %p	a pointer (outputs the Perl value's address in hexadecimal)
-   %n	special: B<stores> into the next variable in the parameter
-        list the number of characters printed so far
+   %n	special: *stores* the number of characters output so far
+        into the next variable in the parameter list 
 
-Finally, for backward (and we do mean "backward") compatibility,
-Perl permits these nonstandard but unaccountably popular conversions:
+Finally, for backward (and we do mean "backward") compatibility, Perl
+permits these unnecessary but widely-supported conversions:
 
+   %i	a synonym for %d
    %D	a synonym for %ld
    %U	a synonym for %lu
    %O	a synonym for %lo
@@ -3138,17 +3252,14 @@ and the conversion letter:
    +       prefix positive number with a plus sign
    -       left-justify within the field
    0       use zeros, not spaces, to right-justify
+   #       prefix octal with "0", 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"
-
-In addition, Perl permits the following ANSI-invented flags:
-
-   #       prefix octal with "0", hex with "0x"
    h       interpret integer as C type "short" or "unsigned short"
 
-Finally, there is one Perl-specific flag:
+There is also one Perl-specific flag:
 
    V       interpret integer as Perl's standard integer type
 
@@ -3334,11 +3445,15 @@ L<perlref> for details.
 
 Extracts a substring out of EXPR and returns it.  First character is at
 offset 0, or whatever you've set C<$[> to (but don't do that).
-If OFFSET is negative, starts
+If OFFSET is negative (or more precisely, less than C<$[>), starts
 that far from the end of the string.  If LEN is omitted, returns
 everything to the end of the string.  If LEN is negative, leaves that
 many characters off the end of the string.
 
+If you specify a substring which is partly outside the string, the part
+within the string is returned.    If the substring is totally outside
+the string a warning is produced.
+
 You can use the substr() function
 as an lvalue, in which case EXPR must be an lvalue.  If you assign
 something shorter than LEN, the string will shrink, and if you assign
@@ -3374,6 +3489,17 @@ like numbers.
 Note that Perl supports passing of up to only 14 arguments to your system call,
 which in practice should usually suffice.
 
+Syscall returns whatever value returned by the system call it calls.
+If the system call fails, syscall returns -1 and sets C<$!> (errno).
+Note that some system calls can legitimately return -1.  The proper
+way to handle such calls is to assign C<$!=0;> before the call and
+check the value of <$!> if syscall returns -1.
+
+There's a problem with C<syscall(&SYS_pipe)>: it returns the file
+number of the read end of the pipe it creates.  There is no way
+to retrieve the file number of the other end.  You can avoid this 
+problem by using C<pipe> instead.
+
 =item sysopen FILEHANDLE,FILENAME,MODE
 
 =item sysopen FILEHANDLE,FILENAME,MODE,PERMS
@@ -3403,12 +3529,12 @@ into that kind of thing.
 =item sysread FILEHANDLE,SCALAR,LENGTH
 
 Attempts to read LENGTH bytes of data into variable SCALAR from the
-specified FILEHANDLE, using the system call read(2).  It bypasses stdio,
-so mixing this with other kinds of reads, print(), write(), seek(), or
-tell() can cause confusion.  Returns the number of bytes actually read,
-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.
+specified FILEHANDLE, using the system call read(2).  It bypasses
+stdio, so mixing this with other kinds of reads, print(), write(),
+seek(), or tell() can cause confusion because stdio usually buffers
+data.  Returns the number of bytes actually read, 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.
 
 An OFFSET may be specified to place the read data at some place in the
 string other than the beginning.  A negative OFFSET specifies
@@ -3478,6 +3604,10 @@ signals and core dumps.
     }
     $ok = ($rc != 0);
 
+When the arguments get executed via the system shell, results will
+be subject to its quirks and capabilities.  See L<perlop/"`STRING`">
+for details.
+
 =item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
 
 =item syswrite FILEHANDLE,SCALAR,LENGTH
@@ -3485,14 +3615,16 @@ signals and core dumps.
 Attempts to write LENGTH bytes of data from variable SCALAR to the
 specified FILEHANDLE, using the system call write(2).  It bypasses
 stdio, so mixing this with reads (other than sysread()), print(),
-write(), seek(), or tell() may cause confusion.  Returns the number of
-bytes actually written, or undef if there was an error.  If the length
-is greater than the available data, only as much data as is available
+write(), seek(), or tell() may cause confusion because stdio usually
+buffers data.  Returns the number of bytes actually written, or undef
+if there was an error.  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.
 
 An OFFSET may be specified to write the data from some part of the
 string other than the beginning.  A negative OFFSET specifies writing
-that many bytes counting backwards from the end of the string.
+that many bytes counting backwards from the end of the string.  In the
+case the SCALAR is empty you can use OFFSET but only zero offset.
 
 =item tell FILEHANDLE
 
@@ -3563,6 +3695,8 @@ Unlike dbmopen(), the tie() function will not use or require a module
 for you--you need to do that explicitly yourself.  See L<DB_File>
 or the F<Config> module for interesting tie() implementations.
 
+For further details see L<perltie>, L<tied VARIABLE>.
+
 =item tied VARIABLE
 
 Returns a reference to the object underlying VARIABLE (the same value