X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=80f1fe0cc821c3225994ecc6960bb55cb06e07d2;hb=f4dad39ef1a76c1f6bbf6733d7c2ee209381be78;hp=823355b363a937d83f6c7353f41afea497bea186;hpb=03136e130d992186c97de0acd23f4857b1a277da;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 823355b..80f1fe0 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,23 +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.  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 problem was
-that the program exited non-zero $! will be set to 0.)
-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.
 
@@ -633,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
@@ -646,7 +657,7 @@ Breaks the binding between a DBM file and a hash.
 
 [This function has been superseded by the tie() function.]
 
-This binds a dbm(3), ndbm(3), sdbm(3), gdbm(), or Berkeley DB file to a
+This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file to a
 hash.  HASH is the name of the hash.  (Unlike normal open, the first
 argument is I<NOT> a filehandle, even though it looks like one).  DBNAME
 is the name of the database (without the F<.dir> or F<.pag> extension if
@@ -803,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
 
@@ -830,12 +858,14 @@ 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>
 libraries if the file isn't in the current directory (see also the @INC
-array in L<perlvar/Predefined Names>).  It's the same, however, in that it does
+array in L<perlvar/Predefined Names>).  It is also different in how
+code evaluated with C<do FILENAME> doesn't see lexicals in the enclosing
+scope like C<eval STRING> does.  It's the same, however, in that it does
 reparse the file every time you call it, so you probably don't want to
 do this inside a loop.
 
@@ -948,22 +978,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())
@@ -1001,8 +1047,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
@@ -1030,19 +1076,32 @@ 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.
+=item exec PROGRAM LIST
+
+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).
+
+Since it's a common mistake to use system() instead of exec(), Perl
+warns you if there is a following statement which isn't die(), warn()
+or exit() (if C<-w> is set  -  but you always do that).   If you
+I<really> want to follow an exec() with some other statement, you
+can use one of these styles to avoid the warning:
+
+    exec ('foo') or print STDERR "couldn't exec foo";
+    { exec ('foo') }; print STDERR "couldn't exec foo";
 
 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";
@@ -1061,6 +1120,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
@@ -1132,6 +1195,12 @@ that doesn't implement flock(2), fcntl(2) locking, or lockf(3).  flock()
 is Perl's portable file locking interface, although it locks only entire
 files, not records.
 
+On many platforms (including most versions or clones of Unix), locks
+established by flock() are B<merely advisory>.  This means that files
+locked with flock() may be modified by programs which do not also use
+flock().  Windows NT and OS/2, however, are among the platforms which
+supply mandatory locking.  See your local documentation for details.
+
 OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with
 LOCK_NB.  These constants are traditionally valued 1, 2, 8 and 4, but
 you can use the symbolic names if import them from the Fcntl module,
@@ -1219,7 +1288,7 @@ you're done.  You should reopen those to /dev/null if it's any issue.
 
 =item format
 
-Declare a picture format with use by the write() function.  For
+Declare a picture format for use by the write() function.  For
 example:
 
     format Something =
@@ -1392,7 +1461,7 @@ system library.  Within a list context, the return values from the
 various get routines are as follows:
 
     ($name,$passwd,$uid,$gid,
-       $quota,$comment,$gcos,$dir,$shell) = getpw*
+       $quota,$comment,$gcos,$dir,$shell,$expire) = getpw*
     ($name,$passwd,$gid,$members) = getgr*
     ($name,$aliases,$addrtype,$length,@addrs) = gethost*
     ($name,$aliases,$addrtype,$net) = getnet*
@@ -1413,6 +1482,22 @@ lookup by name, in which case you get the other thing, whatever it is.
     $name = getgrent
     etc.
 
+In I<getpw*()> the fields $quota, $comment, and $expire are special
+cases in the sense that in many systems they are unsupported.  If the
+$quota is unsupported, it is an empty scalar.  If it is supported, it
+usually encodes the disk quota.  If the $comment field is unsupported,
+it is an empty scalar.  If it is supported it usually encodes some
+administrative comment about the user.  In some systems the $quota
+field may be $change or $age, fields that have to do with password
+aging.  In some systems the $comment field may be $class.  The $expire
+field, if present, encodes the expiration period of the account or the
+password.  For the availability and the exact meaning of these fields
+in your system, please consult your getpwnam(3) documentation and your
+<pwd.h> file.  You can also find out from within Perl which meaning
+your $quota and $comment fields have and whether you have the $expire
+field by using the Config module and the values d_pwquota, d_pwage,
+d_pwchange, d_pwcomment, and d_pwexpire.
+
 The $members value returned by I<getgr*()> is a space separated list of
 the login names of the members of the group.
 
@@ -1524,10 +1609,13 @@ 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.  Similarly, grep returns aliases into the original list,
-much like the way that L<Foreach Loops>'s index variable aliases the list
+much like the way that a for 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
@@ -1731,10 +1819,10 @@ 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
+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
 via my()"> for details.
 
 =item localtime EXPR
@@ -1758,8 +1846,18 @@ In a scalar context, returns the ctime(3) value:
 
     $now_string = localtime;  # e.g., "Thu Oct 13 04:54:34 1994"
 
-Also see the Time::Local module, and the strftime(3) and mktime(3)
-function available via the POSIX module.
+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.  To
+get somewhat similar but locale dependent date strings, set up your
+locale environment variables appropriately (please see L<perllocale>)
+and try for example
+
+	use POSIX qw(strftime)
+	$now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
+
+Note that the C<%a> and C<%b>, the short forms of the day of the week
+and the month of the year, may not necessarily be three characters wide.
 
 =item log EXPR
 
@@ -1806,6 +1904,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
@@ -1926,6 +2030,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;
@@ -1933,12 +2045,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
 
@@ -2150,8 +2266,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
@@ -2281,7 +2402,8 @@ you will have to use a block returning its value instead:
 
 =item printf FORMAT, LIST
 
-Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>.  The first argument
+Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that $\
+(the output record separator) is not appended.  The first argument
 of the list will be interpreted as the 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>.
@@ -2296,6 +2418,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
@@ -2335,10 +2464,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
@@ -2371,6 +2500,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
@@ -2380,11 +2519,22 @@ 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
 data into variable SCALAR from the specified SOCKET filehandle.
-Actually does a C recvfrom(), so that it can returns the address of the
+Actually does a C recvfrom(), so that it can return the address of the
 sender.  Returns the undefined value if there's an error.  SCALAR will
 be grown or shrunk to the length actually read.  Takes the same flags
 as the system call of the same name.
@@ -2495,8 +2645,26 @@ replaces "F<::>" with "F</>" in the filename for you,
 to make it easy to load standard modules.  This form of loading of
 modules does not risk altering your namespace.
 
-For a yet-more-powerful import facility, see L</use> and
-L<perlmod>.
+In other words, if you try this:
+
+        require Foo::Bar ; # a splendid bareword 
+
+The require function will actually look for the "Foo/Bar.pm" file in the 
+directories specified in the @INC array.
+
+But if you try this :
+
+        $class = 'Foo::Bar';
+        require $class ; # $class is not a bareword
+or
+        require "Foo::Bar" ; # not a bareword because of the ""
+
+The require function will look for the "Foo::Bar" file in the @INC array and 
+will complain about not finding "Foo::Bar" there. In this case you can do :
+
+        eval "require $class";
+
+For a yet-more-powerful import facility, see L</use> and L<perlmod>.
 
 =item reset EXPR
 
@@ -2778,10 +2946,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
 
@@ -2838,7 +3008,7 @@ always sleep the full amount.
 
 For delays of finer granularity than one second, you may use Perl's
 syscall() interface to access setitimer(2) if your system supports it,
-or else see L</select()> below.
+or else see L</select()> above.
 
 See also the POSIX module's sigpause() function.
 
@@ -2986,10 +3156,12 @@ sanity checks in the interest of speed.
 =item splice ARRAY,OFFSET
 
 Removes the elements designated by OFFSET and LENGTH from an array, and
-replaces them with the elements of LIST, if any.  Returns the elements
-removed from the array.  The array grows or shrinks as necessary.  If
-LENGTH is omitted, removes everything from OFFSET onward.  The
-following equivalences hold (assuming C<$[ == 0>):
+replaces them with the elements of LIST, if any.  In a list context,
+returns the elements removed from the array.  In a scalar context,
+returns the last element removed, or C<undef> if no elements are
+removed.  The array grows or shrinks as necessary.  If LENGTH is
+omitted, removes everything from OFFSET onward.  The following
+equivalences hold (assuming C<$[ == 0>):
 
     push(@a,$x,$y)	splice(@a,$#a+1,0,$x,$y)
     pop(@a)		splice(@a,-1)
@@ -3028,12 +3200,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 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 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
@@ -3067,7 +3240,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,
@@ -3118,19 +3291,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
@@ -3143,17 +3316,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 non-zero octal with "0", non-zero hex with "0x"
    number  minimum field width
    .number "precision": digits after decimal point for floating-point,
            max length for string, minimum length for integer
    l       interpret integer as C type "long" or "unsigned long"
-
-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
 
@@ -3183,7 +3353,7 @@ omitted, uses a semi-random value 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 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.
+C<time ^ ($$ + ($$ E<lt>E<lt> 15))>), but that isn't necessary any more.
 
 In fact, it's usually not necessary to call srand() at all, because if
 it is not called explicitly, it is called implicitly at the first use of
@@ -3333,17 +3503,23 @@ a NAME, it's an anonymous function declaration, and does actually return a
 value: the CODE ref of the closure you just created.  See L<perlsub> and
 L<perlref> for details.
 
+=item substr EXPR,OFFSET,LEN,REPLACEMENT
+
 =item substr EXPR,OFFSET,LEN
 
 =item substr EXPR,OFFSET
 
 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
@@ -3351,6 +3527,12 @@ something longer than LEN, the string will grow to accommodate it.  To
 keep the string the same length you may need to pad or chop your value
 using sprintf().
 
+An alternative to using substr() as an lvalue is to specify the
+replacement string as the 4th argument.  This allows you to replace
+parts of the EXPR and return what was there before in one operation.
+In this case LEN can be C<undef> if you want to affect everything to
+the end of the string.
+
 =item symlink OLDFILE,NEWFILE
 
 Creates a new filename symbolically linked to the old filename.
@@ -3368,17 +3550,32 @@ unimplemented, produces a fatal error.  The arguments are interpreted
 as follows: if a given argument is numeric, the argument is passed as
 an int.  If not, the pointer to the string value is passed.  You are
 responsible to make sure a string is pre-extended long enough to
-receive any result that might be written into a string.  If your
+receive any result that might be written into a string.  You can't use a
+string literal (or other read-only string) as an argument to syscall()
+because Perl has to assume that any string pointer might be written
+through.  If your
 integer arguments are not literals and have never been interpreted in a
 numeric context, you may need to add 0 to them to force them to look
 like numbers.
 
     require 'syscall.ph';		# may need to run h2ph
-    syscall(&SYS_write, fileno(STDOUT), "hi there\n", 9);
+    $s = "hi there\n";
+    syscall(&SYS_write, fileno(STDOUT), $s, length $s);
 
 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 C<$!> 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
@@ -3408,12 +3605,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
@@ -3441,6 +3638,8 @@ the new position.
 
 =item system LIST
 
+=item system PROGRAM LIST
+
 Does exactly the same thing as "exec LIST" except that a fork is done
 first, and the parent process waits for the child process to complete.
 Note that argument processing varies depending on the number of
@@ -3450,6 +3649,9 @@ returned by the wait() call.  To get the actual exit value divide by
 the output from a command, for that you should use merely backticks or
 qx//, as described in L<perlop/"`STRING`">.
 
+Like exec(), system() allows you to lie to a program about its name if
+you use the "system PROGRAM LIST" syntax.  Again, see L</exec>.
+
 Because system() and backticks block SIGINT and SIGQUIT, killing the
 program they're running doesn't actually interrupt your program.
 
@@ -3461,15 +3663,20 @@ Here's a more elaborate example of analysing the return value from
 system() on a Unix system to check for all possibilities, including for
 signals and core dumps.
 
-    $rc = 0xffff & system @args;
+    $! = 0;
+    $rc = system @args;
     printf "system(%s) returned %#04x: ", "@args", $rc;
     if ($rc == 0) {
 	print "ran with normal exit\n";
     }
     elsif ($rc == 0xff00) {
-	print "command failed: $!\n";
+	# Note that $! can be an empty string if the command that
+	# system() tried to execute was not found, not executable, etc.
+	# These errors occur in the child process after system() has
+	# forked, so the errno value is not visible in the parent.
+	printf "command failed: %s\n", ($! || "Unknown system() error");
     }
-    elsif ($rc > 0x80) {
+    elsif (($rc & 0xff) == 0) {
 	$rc >>= 8;
 	print "ran with non-zero exit status $rc\n";
     }
@@ -3483,6 +3690,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
@@ -3490,14 +3701,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
 
@@ -3568,6 +3781,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
@@ -3591,7 +3806,7 @@ seconds, for this process and the children of this process.
 
 =item tr///
 
-The translation operator.  Same as y///. See L<perlop>.
+The transliteration operator.  Same as y///. See L<perlop>.
 
 =item truncate FILEHANDLE,LENGTH
 
@@ -3599,7 +3814,8 @@ The translation operator.  Same as y///. See L<perlop>.
 
 Truncates the file opened on FILEHANDLE, or named by EXPR, to the
 specified length.  Produces a fatal error if truncate isn't implemented
-on your system.
+on your system.  Returns TRUE if successful, the undefined value
+otherwise.
 
 =item uc EXPR
 
@@ -3626,7 +3842,8 @@ If EXPR is omitted, uses $_.
 =item umask
 
 Sets the umask for the process to EXPR and returns the previous value.
-If EXPR is omitted, merely returns the current umask.  Remember that a
+If EXPR is omitted, merely returns the current umask.  If umask(2) is
+not implemented on your system, returns C<undef>.  Remember that a
 umask is a number, usually given in octal; it is I<not> a string of octal
 digits.  See also L</oct>, if all you have is a string.
 
@@ -3635,19 +3852,21 @@ digits.  See also L</oct>, if all you have is a string.
 =item undef
 
 Undefines the value of EXPR, which must be an lvalue.  Use only on a
-scalar value, an entire array, an entire hash, or a subroutine name (using
-"&").  (Using undef() will probably not do what you expect on most
-predefined variables or DBM list values, so don't do that.)  Always
-returns the undefined value.  You can omit the EXPR, in which case
-nothing is undefined, but you still get an undefined value that you
-could, for instance, return from a subroutine, assign to a variable or
-pass as a parameter.  Examples:
+scalar value, an array (using "@"), a hash (using "%"), a subroutine
+(using "&"), or a typeglob (using "*").  (Saying C<undef $hash{$key}>
+will probably not do what you expect on most predefined variables or
+DBM list values, so don't do that; see L<delete>.)  Always returns the
+undefined value.  You can omit the EXPR, in which case nothing is
+undefined, but you still get an undefined value that you could, for
+instance, return from a subroutine, assign to a variable or pass as a
+parameter.  Examples:
 
     undef $foo;
     undef $bar{'blurfl'};             # Compare to: delete $bar{'blurfl'};
     undef @ary;
     undef %hash;
     undef &mysub;
+    undef *xyz;       # destroys $xyz, @xyz, %xyz, &xyz, etc.
     return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
     select undef, undef, undef, 0.25;
     ($a, $b, undef, $c) = &foo;       # Ignore third value returned
@@ -3796,7 +4015,8 @@ Changes the access and modification times on each file of a list of
 files.  The first two elements of the list must be the NUMERICAL access
 and modification times, in that order.  Returns the number of files
 successfully changed.  The inode modification time of each file is set
-to the current time.  Example of a "touch" command:
+to the current time.  This code has the same effect as the "touch"
+command if the files already exist:
 
     #!/usr/bin/perl
     $now = time;
@@ -3871,6 +4091,13 @@ for no value (void context).
 Produces a message on STDERR just like die(), but doesn't exit or throw
 an exception.
 
+If LIST is empty and $@ already contains a value (typically from a
+previous eval) that value is used after appending "\t...caught"
+to $@. This is useful for staying almost, but not entirely similar to
+die().
+
+If $@ is empty then the string "Warning: Something's wrong" is used.
+
 No message is printed if there is a C<$SIG{__WARN__}> handler
 installed.  It is the handler's responsibility to deal with the message
 as it sees fit (like, for instance, converting it into a die()).  Most
@@ -3933,6 +4160,6 @@ Note that write is I<NOT> the opposite of read.  Unfortunately.
 
 =item y///
 
-The translation operator.  Same as tr///.  See L<perlop>.
+The transliteration operator.  Same as tr///.  See L<perlop>.
 
 =back