X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=c1efce7b8506a454bfafa29e0e406894b8e1ca53;hb=8939ba947b65b018b80ecab3fe1366287d07d1d7;hp=7823d4b85b301bea08d91e21f46644a74bb0d9dd;hpb=ad216e6526a9bc3ea5c5c7d22d293d0f80d48c5a;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 7823d4b..c1efce7 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -136,8 +136,8 @@ C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec>
 
 C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
 C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
-C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<umask>,
-C<unlink>, C<utime>
+C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<sysopen>,
+C<umask>, C<unlink>, C<utime>
 
 =item Keywords related to the control flow of your perl program
 
@@ -172,7 +172,7 @@ C<untie>, C<use>
 
 C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
 C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
-C<sockatmark>, C<socket>, C<socketpair>
+C<socket>, C<socketpair>
 
 =item System V interprocess communication functions
 
@@ -234,7 +234,7 @@ C<msgsnd>, C<open>, C<pipe>, C<readlink>, C<rename>, C<select>, C<semctl>,
 C<semget>, C<semop>, C<setgrent>, C<sethostent>, C<setnetent>,
 C<setpgrp>, C<setpriority>, C<setprotoent>, C<setpwent>,
 C<setservent>, C<setsockopt>, C<shmctl>, C<shmget>, C<shmread>,
-C<shmwrite>, C<sockatmark>, C<socket>, C<socketpair>,
+C<shmwrite>, C<socket>, C<socketpair>,
 C<stat>, C<symlink>, C<syscall>, C<sysopen>, C<system>,
 C<times>, C<truncate>, C<umask>, C<unlink>,
 C<utime>, C<wait>, C<waitpid>
@@ -294,9 +294,9 @@ X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
     -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.
+    -M	Script start time minus file modification time, in days.
     -A	Same for access time.
-    -C	Same for inode change time.
+    -C	Same for inode change time (Unix, may differ for other platforms)
 
 Example:
 
@@ -350,7 +350,9 @@ the special filehandle consisting of a solitary underline, then the stat
 structure of the previous file test (or stat operator) is used, saving
 a system call.  (This doesn't work with C<-t>, and you need to remember
 that lstat() and C<-l> will leave values in the stat structure for the
-symbolic link, not the real file.)  Example:
+symbolic link, not the real file.)  (Also, if the stat buffer was filled by
+a C<lstat> call, C<-T> and C<-B> will reset it with the results of C<stat _>).
+Example:
 
     print "Can do.\n" if -r $a || -w _ || -x _;
 
@@ -386,14 +388,16 @@ value of $^F.  See L<perlvar/$^F>.
 =item alarm
 
 Arranges to have a SIGALRM delivered to this process after the
-specified number of seconds have elapsed.  If SECONDS is not specified,
-the value stored in C<$_> is used. (On some machines,
-unfortunately, the elapsed time may be up to one second less than you
-specified because of how seconds are counted.)  Only one timer may be
-counting at once.  Each call disables the previous timer, and an
-argument of C<0> may be supplied to cancel the previous timer without
-starting a new one.  The returned value is the amount of time remaining
-on the previous timer.
+specified number of wallclock seconds have elapsed.  If SECONDS is not
+specified, the value stored in C<$_> is used. (On some machines,
+unfortunately, the elapsed time may be up to one second less or more
+than you specified because of how seconds are counted, and process
+scheduling may delay the delivery of the signal even further.)
+
+Only one timer may be counting at once.  Each call disables the
+previous timer, and an argument of C<0> may be supplied to cancel the
+previous timer without starting a new one.  The returned value is the
+amount of time remaining 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
@@ -448,14 +452,16 @@ L<perlipc/"Sockets: Client/Server Communication">.
 Arranges for FILEHANDLE to be read or written in "binary" or "text" mode
 on systems where the run-time libraries distinguish between binary and
 text files.  If FILEHANDLE is an expression, the value is taken as the
-name of the filehandle.  DISCIPLINE can be either of C<:raw> for
-binary mode or C<:crlf> for "text" mode.  If the DISCIPLINE is
-omitted, it defaults to C<:raw>.  Returns true on success, C<undef> on
-failure.  The C<:raw> are C<:clrf>, and any other directives of the
-form C<:...>, are called I/O I<disciplines>.
+name of the filehandle.
+
+DISCIPLINE can be either of C<:raw> for binary mode or C<:crlf> for
+"text" mode.  If the DISCIPLINE is omitted, it defaults to C<:raw>.
+Returns true on success, C<undef> on failure.  To mark FILEHANDLE as
+UTF-8, use C<:utf8>, and to mark it as bytes, use C<:bytes>.
 
-The C<open> pragma can be used to establish default I/O disciplines.
-See L<open>.
+The C<:raw> are C<:clrf>, and any other directives of the form
+C<:...>, are called I/O I<disciplines>.  The C<open> pragma can be
+used to establish default I/O disciplines.  See L<open>.
 
 In general, binmode() should be called after open() but before any I/O
 is done on the filehandle.  Calling binmode() will flush any possibly
@@ -548,11 +554,13 @@ C<$is_require> are set: C<$is_require> is true if the frame is created by a
 C<require> or C<use> statement, $evaltext contains the text of the
 C<eval EXPR> statement.  In particular, for an C<eval BLOCK> statement,
 $filename is C<(eval)>, but $evaltext is undefined.  (Note also that
-each C<use> statement creates a C<require> frame inside an C<eval EXPR>)
-frame.  C<$hasargs> is true if a new instance of C<@_> was set up for the
-frame.  C<$hints> and C<$bitmask> contain pragmatic hints that the caller
-was compiled with.  The C<$hints> and C<$bitmask> values are subject to
-change between versions of Perl, and are not meant for external use.
+each C<use> statement creates a C<require> frame inside an C<eval EXPR>
+frame.)  $subroutine may also be C<(unknown)> if this particular
+subroutine happens to have been deleted from the symbol table.
+C<$hasargs> is true if a new instance of C<@_> was set up for the frame.
+C<$hints> and C<$bitmask> contain pragmatic hints that the caller was
+compiled with.  The C<$hints> and C<$bitmask> values are subject to change
+between versions of Perl, and are not meant for external use.
 
 Furthermore, when called from within the DB package, caller returns more
 detailed information: it sets the list variable C<@DB::args> to be the
@@ -863,10 +871,12 @@ 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().
+If using crypt() on a Unicode string (which I<potentially> has
+characters with codepoints above 255), Perl tries to make sense
+of the situation by trying to downgrade (a copy of the string)
+the string back to an eight-bit byte string before calling crypt()
+(on that copy).  If that works, good.  If not, crypt() dies with
+C<Wide character in crypt>.
 
 =item dbmclose HASH
 
@@ -1048,16 +1058,16 @@ Equivalent examples:
     die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
     chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
 
-If the value of EXPR does not end in a newline, the current script line
-number and input line number (if any) are also printed, and a newline
-is supplied.  Note that the "input line number" (also known as "chunk")
-is subject to whatever notion of "line" happens to be currently in
-effect, and is also available as the special variable C<$.>.
-See L<perlvar/"$/"> and L<perlvar/"$.">.
+If the last element of LIST does not end in a newline, the current
+script line number and input line number (if any) are also printed,
+and a newline is supplied.  Note that the "input line number" (also
+known as "chunk") is subject to whatever notion of "line" happens to
+be currently in effect, and is also available as the special variable
+C<$.>.  See L<perlvar/"$/"> and L<perlvar/"$.">.
 
-Hint: sometimes appending C<", stopped"> to your message
-will cause it to make better sense when the string C<"at foo line 123"> is
-appended.  Suppose you are running script "canasta".
+Hint: sometimes appending C<", stopped"> to your message will cause it
+to make better sense when the string C<"at foo line 123"> is appended.
+Suppose you are running script "canasta".
 
     die "/etc/games is no good";
     die "/etc/games is no good, stopped";
@@ -1079,7 +1089,7 @@ This is useful for propagating exceptions:
 If LIST is empty and C<$@> contains an object reference that has a
 C<PROPAGATE> method, that method will be called with additional file
 and line number parameters.  The return value replaces the value in
-C<$@>.  ie. as if C<<$@ = eval { $@->PROPAGATE(__FILE__, __LINE__) };>> 
+C<$@>.  ie. as if C<<$@ = eval { $@->PROPAGATE(__FILE__, __LINE__) };>>
 were called.
 
 If C<$@> is empty then the string C<"Died"> is used.
@@ -1202,7 +1212,9 @@ resulting confusion on the part of Perl.
 This function is now largely obsolete, partly because it's very
 hard to convert a core file into an executable, and because the
 real compiler backends for generating portable bytecode and compilable
-C code have superseded it.
+C code have superseded it.  That's why you should now invoke it as
+C<CORE::dump()>, if you don't want to be warned against a possible
+typo.
 
 If you're looking to use L<dump> to speed up your program, consider
 generating bytecode or native C code as described in L<perlcc>.  If
@@ -1268,7 +1280,10 @@ formed from the files listed on the command line and accessed via the
 C<< <> >> operator.  Since C<< <> >> isn't explicitly opened,
 as a normal filehandle is, an C<eof()> before C<< <> >> has been
 used will cause C<@ARGV> to be examined to determine if input is
-available.
+available.   Similarly, an C<eof()> after C<< <> >> has returned
+end-of-file will assume you are processing another C<@ARGV> list,
+and if you haven't set C<@ARGV>, will read input from C<STDIN>;
+see L<perlop/"I/O Operators">.
 
 In a C<< while (<>) >> loop, C<eof> or C<eof(ARGV)> can be used to
 detect the end of each file, C<eof()> will only detect the end of the
@@ -1330,8 +1345,9 @@ executed, an undefined value is returned by C<eval>, and C<$@> is set to the
 error message.  If there was no error, C<$@> is guaranteed to be a null
 string.  Beware that using C<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>.
+To do either of those, you have to use the C<$SIG{__WARN__}> facility, or
+turn off warnings inside the BLOCK or EXPR using S<C<no warnings 'all'>>.
+See L</warn>, L<perlvar>, L<warnings> and L<perllexwarn>.
 
 Note that, because C<eval> traps otherwise-fatal errors, it is useful for
 determining whether a particular feature (such as C<socket> or C<symlink>)
@@ -1656,6 +1672,10 @@ are the semantics that lockf(3) implements.  Most if not all systems
 implement lockf(3) in terms of fcntl(2) locking, though, so the
 differing semantics shouldn't bite too many people.
 
+Note that the fcntl(2) emulation of flock(3) requires that FILEHANDLE
+be open with read intent to use LOCK_SH and requires that it be open
+with write intent to use LOCK_EX.
+
 Note also that some versions of C<flock> cannot lock things over the
 network; you would need to use the more system-specific C<fcntl> for
 that.  If you like you can force Perl to ignore your system's flock(2)
@@ -2083,6 +2103,9 @@ It can be used to go almost anywhere else within the dynamic scope,
 including out of subroutines, but it's usually better to use some other
 construct such as C<last> or C<die>.  The author of Perl has never felt the
 need to use this form of C<goto> (in Perl, that is--C is another matter).
+(The difference being that C does not offer named loops combined with
+loop control.  Perl does, and this replaces most structured uses of C<goto>
+in other languages.)
 
 The C<goto-EXPR> form expects a label name, whose scope will be resolved
 dynamically.  This allows for computed C<goto>s per FORTRAN, but isn't
@@ -2090,13 +2113,14 @@ necessarily recommended if you're optimizing for maintainability:
 
     goto ("FOO", "BAR", "GLARCH")[$i];
 
-The C<goto-&NAME> form is quite different from the other forms of C<goto>.
-In fact, it isn't a goto in the normal sense at all, and doesn't have
-the stigma associated with other gotos.  Instead, it
-substitutes a call to the named subroutine for the currently running
-subroutine.  This is used by C<AUTOLOAD> subroutines that wish to load
-another subroutine and then pretend that the other subroutine had been
-called in the first place (except that any modifications to C<@_>
+The C<goto-&NAME> form is quite different from the other forms of
+C<goto>.  In fact, it isn't a goto in the normal sense at all, and
+doesn't have the stigma associated with other gotos.  Instead, it
+exits the current subroutine (losing any changes set by local()) and
+immediately calls in its place the named subroutine using the current
+value of @_.  This is used by C<AUTOLOAD> subroutines that wish to
+load another subroutine and then pretend that the other subroutine had
+been called in the first place (except that any modifications to C<@_>
 in the current subroutine are propagated to the other subroutine.)
 After the C<goto>, not even C<caller> will be able to tell that this
 routine was called first.
@@ -2445,12 +2469,13 @@ and the month of the year, may not necessarily be three characters wide.
 
 =item lock THING
 
-This function places an advisory lock on a variable, subroutine,
-or referenced object contained in I<THING> until the lock goes out
-of scope.  This is a built-in function only if your version of Perl
-was built with threading enabled, and if you've said C<use Thread>.
-Otherwise a user-defined function by this name will be called.
-See L<Thread>.
+This function places an advisory lock on a shared variable, or referenced 
+object contained in I<THING> until the lock goes out of scope.
+
+lock() is a "weak keyword" : this means that if you've defined a function
+by this name (before any calls to it), that function will be called
+instead. (However, if you've said C<use threads>, lock() is always a
+keyword.) See L<threads>.
 
 =item log EXPR
 
@@ -2632,8 +2657,14 @@ that executes once.  Thus C<next> will exit such a block early.
 See also L</continue> for an illustration of how C<last>, C<next>, and
 C<redo> work.
 
+=item no Module VERSION LIST
+
+=item no Module VERSION
+
 =item no Module LIST
 
+=item no Module
+
 See the L</use> function, which C<no> is the opposite of.
 
 =item oct EXPR
@@ -2666,6 +2697,8 @@ conversion assumes base 10.)
 
 =item open FILEHANDLE,MODE,EXPR,LIST
 
+=item open FILEHANDLE,MODE,REFERENCE
+
 =item open FILEHANDLE
 
 Opens the file whose filename is given by EXPR, and associates it with
@@ -2683,7 +2716,7 @@ strict 'refs'> should I<not> be in effect.)
 If EXPR is omitted, the scalar variable of the same name as the
 FILEHANDLE contains the filename.  (Note that lexical variables--those
 declared with C<my>--will not work for this purpose; so if you're
-using C<my>, specify EXPR in your call to open.) 
+using C<my>, specify EXPR in your call to open.)
 
 If three or more arguments are specified then the mode of opening and
 the file name are separate. If MODE is C<< '<' >> or nothing, the file
@@ -2740,7 +2773,7 @@ and opening C<< '>-' >> opens STDOUT.
 You may use the three-argument form of open to specify
 I<I/O disciplines> that affect how the input and output
 are processed: see L</binmode> and L<open>.  For example
-  
+
   open(FH, "<:utf8", "file")
 
 will open the UTF-8 encoded file containing Unicode characters,
@@ -2754,7 +2787,7 @@ If you're running Perl on a system that distinguishes between text
 files and binary files, then you should check out L</binmode> for tips
 for dealing with this.  The key distinction between systems that need
 C<binmode> and those that don't is their text file formats.  Systems
-like Unix, MacOS, and Plan9, which delimit lines with a single
+like Unix, Mac OS, and Plan 9, which delimit lines with a single
 character, and which encode that character in C as C<"\n">, do not
 need C<binmode>.  The rest need it.
 
@@ -2778,6 +2811,16 @@ argument being C<undef>:
 
 opens a filehandle to an anonymous temporary file.
 
+File handles can be opened to "in memory" files held in Perl scalars via:
+
+    open($fh, '>', \$variable) || ..
+
+Though if you try to re-open C<STDOUT> or C<STDERR> as an "in memory"
+file, you have to close it first:
+
+    close STDOUT;
+    open STDOUT, '>', \$variable or die "Can't open STDOUT: $!";
+
 Examples:
 
     $ARTICLE = 100;
@@ -2802,6 +2845,11 @@ Examples:
     open(EXTRACT, "|sort >/tmp/Tmp$$")		# $$ is our process id
 	or die "Can't start sort: $!";
 
+    # in memory files
+    open(MEMORY,'>', \$var)
+	or die "Can't open memory file: $!";
+    print MEMORY "foo!\n";			# output will end up in $var
+
     # process argument list of files along with any includes
 
     foreach $file (@ARGV) {
@@ -2836,27 +2884,27 @@ mode you specify should match the mode of the original filehandle.
 IO buffers.) If you use the 3 arg form then you can pass either a number,
 the name of a filehandle or the normal "reference to a glob".
 
-Here is a script that saves, redirects, and restores STDOUT and
-STDERR:
+Here is a script that saves, redirects, and restores C<STDOUT> and
+C<STDERR> using various methods:
 
     #!/usr/bin/perl
-    open(my $oldout, ">&", \*STDOUT);
-    open(OLDERR, ">&STDERR");
+    open my $oldout, ">&STDOUT"     or die "Can't dup STDOUT: $!";
+    open OLDERR,     ">&", \*STDERR or die "Can't dup STDERR: $!";
 
-    open(STDOUT, '>', "foo.out") || die "Can't redirect stdout";
-    open(STDERR, ">&STDOUT")     || die "Can't dup stdout";
+    open STDOUT, '>', "foo.out" or die "Can't redirect STDOUT: $!";
+    open STDERR, ">&STDOUT"     or die "Can't dup STDOUT: $!";
 
-    select(STDERR); $| = 1;	# make unbuffered
-    select(STDOUT); $| = 1;	# make unbuffered
+    select STDERR; $| = 1;	# make unbuffered
+    select STDOUT; $| = 1;	# make unbuffered
 
     print STDOUT "stdout 1\n";	# this works for
     print STDERR "stderr 1\n"; 	# subprocesses too
 
-    close(STDOUT);
-    close(STDERR);
+    close STDOUT;
+    close STDERR;
 
-    open(STDOUT, ">&OLDOUT");
-    open(STDERR, ">&OLDERR");
+    open STDOUT, ">&", $oldout or die "Can't dup \$oldout: $!";
+    open STDERR, ">&OLDERR"    or die "Can't dup OLDERR: $!";
 
     print STDOUT "stdout 2\n";
     print STDERR "stderr 2\n";
@@ -3076,9 +3124,8 @@ the converted values.  Typically, each converted value looks
 like its machine-level representation.  For example, on 32-bit machines
 a converted integer may be represented by a sequence of 4 bytes.
 
-The TEMPLATE is a
-sequence of characters that give the order and type of values, as
-follows:
+The TEMPLATE is a 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	A text (ASCII) string, will be space padded.
@@ -3124,9 +3171,19 @@ follows:
 	   integer values _and_ if Perl has been compiled to support those.
            Causes a fatal error otherwise.)
 
+    j   A signed integer value (a Perl internal integer, IV).
+    J   An unsigned integer value (a Perl internal unsigned integer, UV).
+
     f	A single-precision float in the native format.
     d	A double-precision float in the native format.
 
+    F	A floating point value in the native native format
+           (a Perl internal floating point value, NV).
+    D	A long double-precision float in the native format.
+	  (Long doubles are available only if your system supports long
+	   double values _and_ if Perl has been compiled to support those.
+           Causes a fatal error otherwise.)
+
     p	A pointer to a null-terminated string.
     P	A pointer to a structure (fixed-length string).
 
@@ -3142,6 +3199,7 @@ follows:
     x	A null byte.
     X	Back up a byte.
     @	Null fill to absolute position.
+    (	Start of a ()-group.
 
 The following rules apply:
 
@@ -3151,11 +3209,20 @@ The following rules apply:
 
 Each letter may optionally be followed by a number giving a repeat
 count.  With all types except C<a>, C<A>, C<Z>, C<b>, C<B>, C<h>,
-C<H>, and C<P> the pack function will gobble up that many values from
-the LIST.  A C<*> for the repeat count means to use however many items are
-left, except for C<@>, C<x>, C<X>, where it is equivalent
-to C<0>, and C<u>, where it is equivalent to 1 (or 45, what is the
-same).
+C<H>, C<@>, C<x>, C<X> and C<P> the pack function will gobble up that
+many values from the LIST.  A C<*> for the repeat count means to use
+however many items are left, except for C<@>, C<x>, C<X>, where it is
+equivalent to C<0>, and C<u>, where it is equivalent to 1 (or 45, what
+is the same).  A numeric repeat count may optionally be enclosed in
+brackets, as in C<pack 'C[80]', @arr>.
+
+One can replace the numeric repeat count by a template enclosed in brackets;
+then the packed length of this template in bytes is used as a count.
+For example, C<x[L]> skips a long (it skips the number of bytes in a long);
+the template C<$t X[$t] $t> unpack()s twice what $t unpacks.
+If the template in brackets contains alignment commands (such as C<x![d]>),
+its packed length is calculated as if the start of the template has the maximal
+possible alignment.
 
 When used with C<Z>, C<*> results in the addition of a trailing null
 byte (so the packed result will be one longer than the byte C<length>
@@ -3244,11 +3311,10 @@ The C</> template character allows packing and unpacking of strings where
 the packed structure contains a byte count followed by the string itself.
 You write I<length-item>C</>I<string-item>.
 
-The I<length-item> can be any C<pack> template letter,
-and describes how the length value is packed.
-The ones likely to be of most use are integer-packing ones like
-C<n> (for Java strings), C<w> (for ASN.1 or SNMP)
-and C<N> (for Sun XDR).
+The I<length-item> can be any C<pack> template letter, and describes
+how the length value is packed.  The ones likely to be of most use are
+integer-packing ones like C<n> (for Java strings), C<w> (for ASN.1 or
+SNMP) and C<N> (for Sun XDR).
 
 The I<string-item> must, at present, be C<"A*">, C<"a*"> or C<"Z*">.
 For C<unpack> the length of the string is obtained from the I<length-item>,
@@ -3295,7 +3361,7 @@ not support long longs.)
 
 =item *
 
-The integer formats C<s>, C<S>, C<i>, C<I>, C<l>, and C<L>
+The integer formats C<s>, C<S>, C<i>, C<I>, C<l>, C<L>, C<j>, and C<J>
 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) would be ordered natively
@@ -3372,6 +3438,24 @@ sequences of bytes.
 
 =item *
 
+A ()-group is a sub-TEMPLATE enclosed in parentheses.  A group may
+take a repeat count, both as postfix, and via the C</> template
+character.
+
+=item *
+
+C<x> and C<X> accept C<!> modifier.  In this case they act as
+alignment commands: they jump forward/back to the closest position
+aligned at a multiple of C<count> bytes.  For example, to pack() or
+unpack() C's C<struct {char c; double d; char cc[2]}> one may need to
+use the template C<C x![d] d C[2]>; this assumes that doubles must be
+aligned on the double's size.
+
+For alignment commands C<count> of 0 is equivalent to C<count> of 1;
+both result in no-ops.
+
+=item *
+
 A comment in a TEMPLATE starts with C<#> and goes to the end of line.
 
 =item *
@@ -4168,6 +4252,9 @@ You can effect a sleep of 250 milliseconds this way:
 
     select(undef, undef, undef, 0.25);
 
+Note that whether C<select> gets restarted after signals (say, SIGALRM)
+is implementation-dependent.
+
 B<WARNING>: One should not attempt to mix buffered I/O (like C<read>
 or <FH>) with C<select>, except as permitted by POSIX, and even
 then only on POSIX systems.  You have to use C<sysread> instead.
@@ -4215,7 +4302,7 @@ documentation.
 
 =item send SOCKET,MSG,FLAGS
 
-Sends a message on a socket.  Attemps to send the scalar MSG to the
+Sends a message on a socket.  Attempts to send the scalar MSG to the
 SOCKET filehandle.  Takes the same flags as the system call of the
 same name.  On unconnected sockets you must specify a destination to
 send TO, in which case it does a C C<sendto>.  Returns the number of
@@ -4349,26 +4436,6 @@ help.
 
 See also the POSIX module's C<pause> function.
 
-=item sockatmark SOCKET
-
-Returns true if the socket is positioned at the out-of-band mark
-(also known as the urgent data mark), false otherwise.  Use right
-after reading from the socket.
-
-Not available directly, one has to import the function from
-the IO::Socket extension
-
-    use IO::Socket 'sockatmark';
-
-Even this doesn't guarantee that sockatmark() really is available,
-though, because sockatmark() is a relatively recent addition to
-the family of socket functions.  If it is unavailable, attempt to
-use it will fail
-
-	IO::Socket::atmark not implemented on this architecture ...
-
-See also L<IO::Socket>.
-
 =item socket SOCKET,DOMAIN,TYPE,PROTOCOL
 
 Opens a socket of the specified kind and attaches it to filehandle
@@ -4400,7 +4467,9 @@ to C<pipe(Rdr, Wtr)> is essentially:
     shutdown(Rdr, 1);        # no more writing for reader
     shutdown(Wtr, 0);        # no more reading for writer
 
-See L<perlipc> for an example of socketpair use.
+See L<perlipc> for an example of socketpair use.  Perl 5.8 and later will
+emulate socketpair using IP sockets to localhost if your system implements
+sockets but not socketpair.
 
 =item sort SUBNAME LIST
 
@@ -4436,11 +4505,19 @@ 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.
+Perl 5.6 and earlier used a quicksort algorithm to implement sort.
+That algorithm was not stable, and I<could> go quadratic.  (A I<stable> sort
+preserves the input order of elements that compare equal.  Although
+quicksort's run time is O(NlogN) when averaged over all arrays of
+length N, the time can be O(N**2), I<quadratic> behavior, for some
+inputs.)  In 5.7, the quicksort implementation was replaced with
+a stable mergesort algorithm whose worst case behavior is O(NlogN).
+But benchmarks indicated that for some inputs, on some platforms,
+the original quicksort was faster.  5.8 has a sort pragma for
+limited control of the sort.  Its rather blunt control of the
+underlying algorithm may not persist into future perls, but the
+ability to characterize the input or output in implementation
+independent ways quite probably will.  See L</use>.
 
 Examples:
 
@@ -4523,6 +4600,14 @@ Examples:
     package main;
     @new = sort other::backwards @old;
 
+    # guarantee stability, regardless of algorithm
+    use sort 'stable';
+    @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
+
+    # force use of mergesort (not portable outside Perl 5.8)
+    use sort '_mergesort';  # note discouraging _
+    @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
+
 If you're using strict, you I<must not> declare $a
 and $b as lexicals.  They are package globals.  That means
 if you're in the C<main> package and type
@@ -4554,8 +4639,11 @@ returns the last element removed, or C<undef> if no elements are
 removed.  The array grows or shrinks as necessary.
 If OFFSET is negative then it starts that far from the end of the array.
 If LENGTH is omitted, removes everything from OFFSET onward.
-If LENGTH is negative, leaves that many elements off the end of the array.
-If both OFFSET and LENGTH are omitted, removes everything.
+If LENGTH is negative, removes the elements from OFFSET onward
+except for -LENGTH elements at the end of the array.
+If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is
+past the end of the array, perl issues a warning, and splices at the
+end of the array.
 
 The following equivalences hold (assuming C<$[ == 0>):
 
@@ -4621,7 +4709,7 @@ 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
+Empty leading (or trailing) fields are produced when there are 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
 example:
@@ -4878,7 +4966,7 @@ Most programs won't even call srand() at all, except those that
 need a cryptographically-strong starting point rather than the
 generally acceptable default, which is based on time of day,
 process ID, and memory allocation, or the F</dev/urandom> device,
-if available. 
+if available.
 
 You can call srand($seed) with the same $seed to reproduce the
 I<same> sequence from rand(), but this is usually reserved for
@@ -5333,9 +5421,9 @@ supported on some platforms (see L<perlport>).  To be safe, you may need
 to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
 of C<IO::Handle> on any open handles.
 
-The return value is the exit status of the program as
-returned by the C<wait> call.  To get the actual exit value divide by
-256.  See also L</exec>.  This is I<not> what you want to use to capture
+The return value is the exit status of the program as returned by the
+C<wait> call.  To get the actual exit value shift right by eight (see below).
+See also L</exec>.  This is I<not> what you want to use to capture
 the output from a command, for that you should use merely backticks or
 C<qx//>, as described in L<perlop/"`STRING`">.  Return value of -1
 indicates a failure to start the program (inspect $! for the reason).
@@ -5343,8 +5431,9 @@ indicates a failure to start the program (inspect $! for the reason).
 Like C<exec>, C<system> allows you to lie to a program about its name if
 you use the C<system PROGRAM LIST> syntax.  Again, see L</exec>.
 
-Because C<system> and backticks block C<SIGINT> and C<SIGQUIT>, killing the
-program they're running doesn't actually interrupt your program.
+Because C<system> and backticks block C<SIGINT> and C<SIGQUIT>,
+killing the program they're running doesn't actually interrupt
+your program.
 
     @args = ("command", "arg1", "arg2");
     system(@args) == 0
@@ -5357,6 +5446,9 @@ C<$?> like this:
     $signal_num  = $? & 127;
     $dumped_core = $? & 128;
 
+or more portably by using the W*() calls of the POSIX extension;
+see L<perlport> for more information.
+
 When the arguments get executed via the system shell, results
 and return codes will be subject to its quirks and capabilities.
 See L<perlop/"`STRING`"> and L</exec> for details.
@@ -5521,7 +5613,7 @@ package.
 =item time
 
 Returns the number of non-leap seconds since whatever time the system
-considers to be the epoch (that's 00:00:00, January 1, 1904 for MacOS,
+considers to be the epoch (that's 00:00:00, January 1, 1904 for Mac OS,
 and 00:00:00 UTC, January 1, 1970 for most other systems).
 Suitable for feeding to C<gmtime> and C<localtime>.
 
@@ -5552,6 +5644,9 @@ specified length.  Produces a fatal error if truncate isn't implemented
 on your system.  Returns true if successful, the undefined value
 otherwise.
 
+The behavior is undefined if LENGTH is greater than the length of the
+file.
+
 =item uc EXPR
 
 =item uc
@@ -5804,6 +5899,7 @@ are also implemented this way.  Currently implemented pragmas are:
     use strict   qw(subs vars refs);
     use subs     qw(afunc blurfl);
     use warnings qw(all);
+    use sort     qw(stable _quicksort _mergesort);
 
 Some of these pseudo-modules import semantics into the current
 block scope (like C<strict> or C<integer>, unlike ordinary modules,
@@ -5817,8 +5913,6 @@ by C<use>, i.e., it calls C<unimport Module LIST> instead of C<import>.
     no strict 'refs';
     no warnings;
 
-If no C<unimport> method can be found the call fails with a fatal error.
-
 See L<perlmodlib> for a list of standard modules and pragmas.  See L<perlrun>
 for the C<-M> and C<-m> command-line options to perl that give C<use>
 functionality from the command-line.
@@ -6120,7 +6214,7 @@ The status is returned in C<$?>.  If you say
     #...
     do {
 	$kid = waitpid(-1, WNOHANG);
-    } until $kid == -1;
+    } until $kid > 0;
 
 then you can do a non-blocking wait for all pending zombie processes.
 Non-blocking wait is available on machines supporting either the