X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=c42257516b74e025a233d547b0d8de0a7cd9a347;hb=83272a45226e83bd136d713158e9b44ace2dbc8d;hp=b32cd9464c5694f0ed8ff42d0012d7d5ed2cee32;hpb=efdd02185294f5c1e6e467a2fe3ee05432b42a84;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index b32cd94..c422575 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>
@@ -445,37 +445,59 @@ does.  Returns true if it succeeded, false otherwise.  NAME should be a
 packed address of the appropriate type for the socket.  See the examples in
 L<perlipc/"Sockets: Client/Server Communication">.
 
-=item binmode FILEHANDLE, DISCIPLINE
+=item binmode FILEHANDLE, LAYER
 
 =item binmode FILEHANDLE
 
-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>.
-
-The C<open> pragma can be used to establish default I/O disciplines.
-See L<open>.
+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.  Returns true on success,
+C<undef> on failure.
+
+If LAYER is omitted or specified as C<:raw> the filehandle is made
+suitable for passing binary data. This includes turning off possible CRLF
+translation and marking it as bytes (as opposed to Unicode characters).
+Note that as desipite what may be implied in I<"Programming Perl">
+(the Camel) or elsewhere C<:raw> is I<not> the simply inverse of C<:crlf>
+-- other layers which would affect binary nature of the stream are
+I<also> disabled. See L<PerlIO>, L<perlrun> and the discussion about the
+PERLIO environment variable.
+
+I<The LAYER parameter of the binmode() function is described as "DISCIPLINE"
+in "Programming Perl, 3rd Edition".  However, since the publishing of this
+book, by many known as "Camel III", the consensus of the naming of this
+functionality has moved from "discipline" to "layer".  All documentation
+of this version of Perl therefore refers to "layers" rather than to
+"disciplines".  Now back to the regularly scheduled documentation...>
+
+On some systems (in general, DOS and Windows-based systems) binmode()
+is necessary when you're not working with a text file.  For the sake
+of portability it is a good idea to always use it when appropriate,
+and to never use it when it isn't appropriate.
+
+In other words: regardless of platform, use binmode() on binary files
+(like for example images).
+
+If LAYER is present it is a single string, but may contain
+multiple directives. The directives alter the behaviour of the
+file handle. When LAYER is present using binmode on text
+file makes sense.
+
+To mark FILEHANDLE as UTF-8, use C<:utf8>.
+
+The C<:bytes>, C<:crlf>, and C<:utf8>, and any other directives of the
+form C<:...>, are called I/O I<layers>.  The C<open> pragma can be used to
+establish default I/O layers.  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
-pending buffered input or output data on the handle.  The only
-exception to this is the C<:encoding> discipline that changes
-the default character encoding of the handle, see L<open>.
-The C<:encoding> discipline sometimes needs to be called in
+is done on the filehandle.  Calling binmode() will normally flush any
+pending buffered output data (and perhaps pending input data) on the
+handle.  An exception to this is the C<:encoding> layer that
+changes the default character encoding of the handle, see L<open>.
+The C<:encoding> layer sometimes needs to be called in
 mid-stream, and it doesn't flush the stream.
 
-On some systems binmode() is necessary when you're not working with a
-text file.  For the sake of portability it is a good idea to always use
-it when appropriate, and to never use it when it isn't appropriate.
-
-In other words:  Regardless of platform, use binmode() on binary
-files, and do not use binmode() on text files.
-
 The operating system, device drivers, C libraries, and Perl run-time
 system all work together to let the programmer treat a single
 character (C<\n>) as the line terminator, irrespective of the external
@@ -487,14 +509,13 @@ one character.
 Mac OS, all variants of Unix, and Stream_LF files on VMS use a single
 character to end each line in the external representation of text (even
 though that single character is CARRIAGE RETURN on Mac OS and LINE FEED
-on Unix and most VMS files).  Consequently binmode() has no effect on
-these operating systems.  In other systems like OS/2, DOS and the various
-flavors of MS-Windows your program sees a C<\n> as a simple C<\cJ>, but
-what's stored in text files are the two characters C<\cM\cJ>.  That means
-that, if you don't use binmode() on these systems, C<\cM\cJ> sequences on
-disk will be converted to C<\n> on input, and any C<\n> in your program
-will be converted back to C<\cM\cJ> on output.  This is what you want for
-text files, but it can be disastrous for binary files.
+on Unix and most VMS files). In other systems like OS/2, DOS and the
+various flavors of MS-Windows your program sees a C<\n> as a simple C<\cJ>,
+but what's stored in text files are the two characters C<\cM\cJ>.  That
+means that, if you don't use binmode() on these systems, C<\cM\cJ>
+sequences on disk will be converted to C<\n> on input, and any C<\n> in
+your program will be converted back to C<\cM\cJ> on output.  This is what
+you want for text files, but it can be disastrous for binary files.
 
 Another consequence of using binmode() (on some systems) is that
 special end-of-file markers will be seen as part of the data stream.
@@ -552,11 +573,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
@@ -634,6 +657,13 @@ You can actually chomp anything that's an lvalue, including an assignment:
 If you chomp a list, each element is chomped, and the total number of
 characters removed is returned.
 
+Note that parentheses are necessary when you're chomping anything
+that is not a simple variable.  This is because C<chomp $cwd = `pwd`;>
+is interpreted as C<(chomp $cwd) = `pwd`;>, rather than as
+C<chomp( $cwd = `pwd` )> which you might expect.  Similarly,
+C<chomp $a, $b> is interpreted as C<chomp($a), $b> rather than
+as C<chomp($a, $b)>.
+
 =item chop VARIABLE
 
 =item chop( LIST )
@@ -653,6 +683,8 @@ last C<chop> is returned.
 Note that C<chop> returns the last character.  To return all but the last
 character, use C<substr($string, 0, -1)>.
 
+See also L</chomp>.
+
 =item chown LIST
 
 Changes the owner (and group) of a list of files.  The first two
@@ -1054,16 +1086,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";
@@ -1085,7 +1117,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.
@@ -1276,7 +1308,7 @@ 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.   Similarly, an C<eof()> after C<< <> >> has returned 
+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">.
@@ -2021,11 +2053,13 @@ Returns the socket option requested, or undef if there is an error.
 
 =item glob
 
-Returns the value of EXPR with filename expansions such as the
-standard Unix shell F</bin/csh> would do.  This is the internal function
-implementing the C<< <*.c> >> operator, but you can use it directly.
-If EXPR is omitted, C<$_> is used.  The C<< <*.c> >> operator is
-discussed in more detail in L<perlop/"I/O Operators">.
+In list context, returns a (possibly empty) list of filename expansions on
+the value of EXPR such as the standard Unix shell F</bin/csh> would do. In
+scalar context, glob iterates through such filename expansions, returning
+undef when the list is exhausted. This is the internal function
+implementing the C<< <*.c> >> operator, but you can use it directly. If
+EXPR is omitted, C<$_> is used.  The C<< <*.c> >> operator is discussed in
+more detail in L<perlop/"I/O Operators">.
 
 Beginning with v5.6.0, this operator is implemented using the standard
 C<File::Glob> extension.  See L<File::Glob> for details.
@@ -2465,12 +2499,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
 
@@ -2619,12 +2654,22 @@ and C<IPC::SysV::Msg> documentation.
 
 =item my EXPR
 
-=item my EXPR : ATTRIBUTES
+=item my TYPE EXPR
+
+=item my EXPR : ATTRS
+
+=item my TYPE EXPR : ATTRS
 
 A C<my> declares the listed variables to be local (lexically) to the
-enclosing block, file, or C<eval>.  If
-more than one value is listed, the list must be placed in parentheses.  See
-L<perlsub/"Private Variables via my()"> for details.
+enclosing block, file, or C<eval>.  If more than one value is listed,
+the list must be placed in parentheses.
+
+The exact semantics and interface of TYPE and ATTRS are still
+evolving.  TYPE is currently bound to the use of C<fields> pragma,
+and attributes are handled using the C<attributes> pragma, or starting
+from Perl 5.8.0 also via the C<Attribute::Handlers> module.  See
+L<perlsub/"Private Variables via my()"> for details, and L<fields>,
+L<attributes>, and L<Attribute::Handlers>.
 
 =item next LABEL
 
@@ -2652,8 +2697,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
@@ -2705,7 +2756,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
@@ -2759,14 +2810,17 @@ meaning.
 In the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN
 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
+You may use the three-argument form of open to specify IO "layers"
+(sometimes also referred to as "disciplines") to be applied to the handle
+that affect how the input and output are processed (see L<open> and
+L<PerlIO> for more details). For example
 
   open(FH, "<:utf8", "file")
 
 will open the UTF-8 encoded file containing Unicode characters,
-see L<perluniintro>.
+see L<perluniintro>. (Note that if layers are specified in the
+three-arg form then default layers set by the C<open> pragma are
+ignored.)
 
 Open returns nonzero upon success, the undefined value otherwise.  If
 the C<open> involved a pipe, the return value happens to be the pid of
@@ -2776,15 +2830,10 @@ 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.
 
-In the three argument form MODE may also contain a list of IO "layers"
-(see L<open> and L<PerlIO> for more details) to be applied to the
-handle. This can be used to achieve the effect of C<binmode> as well
-as more complex behaviours.
-
 When opening a file, it's usually a bad idea to continue normal execution
 if the request failed, so C<open> is frequently used in connection with
 C<die>.  Even if C<die> won't do what you want (say, in a CGI script,
@@ -2802,7 +2851,13 @@ 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) || ..
+    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:
 
@@ -2867,27 +2922,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";
@@ -2936,7 +2991,9 @@ The following triples are more or less equivalent:
     open(FOO, '-|', "cat", '-n', $file);
 
 The last example in each block shows the pipe as "list form", which is
-not yet supported on all platforms.
+not yet supported on all platforms.  A good rule of thumb is that if
+your platform has true C<fork()> (in other words, if your platform is
+UNIX) you can use the list form.
 
 See L<perlipc/"Safe Pipe Opens"> for more examples of this.
 
@@ -3037,7 +3094,11 @@ See L<perlunicode> and L<encoding> for more about Unicode.
 
 =item our EXPR
 
-=item our EXPR : ATTRIBUTES
+=item our EXPR TYPE
+
+=item our EXPR : ATTRS
+
+=item our TYPE EXPR : ATTRS
 
 An C<our> declares the listed variables to be valid globals within
 the enclosing block, file, or C<eval>.  That is, it has the same
@@ -3078,22 +3139,29 @@ package, Perl will emit warnings if you have asked for them.
     our $bar;		# emits warning
 
 An C<our> declaration may also have a list of attributes associated
-with it.  B<WARNING>: This is an experimental feature that may be
-changed or removed in future releases of Perl.  It should not be
-relied upon.
-
-The only currently recognized attribute is C<unique> which indicates
-that a single copy of the global is to be used by all interpreters
-should the program happen to be running in a multi-interpreter
-environment. (The default behaviour would be for each interpreter to
-have its own copy of the global.)  In such an environment, this
-attribute also has the effect of making the global readonly.
-Examples:
+with it.
+
+The exact semantics and interface of TYPE and ATTRS are still
+evolving.  TYPE is currently bound to the use of C<fields> pragma,
+and attributes are handled using the C<attributes> pragma, or starting
+from Perl 5.8.0 also via the C<Attribute::Handlers> module.  See
+L<perlsub/"Private Variables via my()"> for details, and L<fields>,
+L<attributes>, and L<Attribute::Handlers>.
+
+The only currently recognized C<our()> attribute is C<unique> which
+indicates that a single copy of the global is to be used by all
+interpreters should the program happen to be running in a
+multi-interpreter environment. (The default behaviour would be for
+each interpreter to have its own copy of the global.)  Examples:
 
     our @EXPORT : unique = qw(foo);
     our %EXPORT_TAGS : unique = (bar => [qw(aa bb cc)]);
     our $VERSION : unique = "1.00";
 
+Note that this attribute also has the effect of making the global
+readonly when the first new interpreter is cloned (for example,
+when the first new thread is created).
+
 Multi-interpreter environments can come to being either through the
 fork() emulation on Windows platforms, or by embedding perl in a
 multi-threaded application.  The C<unique> attribute does nothing in
@@ -3433,10 +3501,10 @@ 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.
@@ -3704,7 +3772,7 @@ see C<sysread>.
 Note the I<characters>: depending on the status of the filehandle,
 either (8-bit) bytes or characters are read.  By default all
 filehandles operate on bytes, but for example if the filehandle has
-been opened with the C<:utf8> discipline (see L</open>, and the C<open>
+been opened with the C<:utf8> I/O layer (see L</open>, and the C<open>
 pragma, L<open>), the I/O will operate on characters, not bytes.
 
 =item readdir DIRHANDLE
@@ -3776,7 +3844,7 @@ See L<perlipc/"UDP: Message Passing"> for examples.
 Note the I<characters>: depending on the status of the socket, either
 (8-bit) bytes or characters are received.  By default all sockets
 operate on bytes, but for example if the socket has been changed using
-binmode() to operate with the C<:utf8> discipline (see the C<open>
+binmode() to operate with the C<:utf8> I/O layer (see the C<open>
 pragma, L<open>), the I/O will operate on characters, not bytes.
 
 =item redo LABEL
@@ -4124,7 +4192,7 @@ otherwise.
 
 Note the I<in bytes>: even if the filehandle has been set to
 operate on characters (for example by using the C<:utf8> open
-discipline), tell() will return byte offsets, not character offsets
+layer), tell() will return byte offsets, not character offsets
 (because implementing that would render seek() and tell() rather slow).
 
 If you want to position file for C<sysread> or C<syswrite>, don't use
@@ -4235,6 +4303,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.
@@ -4293,7 +4364,7 @@ L<perlipc/"UDP: Message Passing"> for examples.
 Note the I<characters>: depending on the status of the socket, either
 (8-bit) bytes or characters are sent.  By default all sockets operate
 on bytes, but for example if the socket has been changed using
-binmode() to operate with the C<:utf8> discipline (see L</open>, or
+binmode() to operate with the C<:utf8> I/O layer (see L</open>, or
 the C<open> pragma, L<open>), the I/O will operate on characters, not
 bytes.
 
@@ -4416,26 +4487,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
@@ -4477,16 +4528,18 @@ sockets but not socketpair.
 
 =item sort LIST
 
-Sorts the LIST and returns the sorted list value.  If SUBNAME or BLOCK
-is omitted, C<sort>s in standard string comparison order.  If SUBNAME is
-specified, it gives the name of a subroutine that returns an integer
-less than, equal to, or greater than C<0>, depending on how the elements
-of the list are to be ordered.  (The C<< <=> >> and C<cmp>
-operators are extremely useful in such routines.)  SUBNAME may be a
-scalar variable name (unsubscripted), in which case the value provides
-the name of (or a reference to) the actual subroutine to use.  In place
-of a SUBNAME, you can provide a BLOCK as an anonymous, in-line sort
-subroutine.
+In list context, this sorts the LIST and returns the sorted list value.
+In scalar context, the behaviour of C<sort()> is undefined.
+
+If SUBNAME or BLOCK is omitted, C<sort>s in standard string comparison
+order.  If SUBNAME is specified, it gives the name of a subroutine
+that returns an integer less than, equal to, or greater than C<0>,
+depending on how the elements of the list are to be ordered.  (The C<<
+<=> >> and C<cmp> operators are extremely useful in such routines.)
+SUBNAME may be a scalar variable name (unsubscripted), in which case
+the value provides the name of (or a reference to) the actual
+subroutine to use.  In place of a SUBNAME, you can provide a BLOCK as
+an anonymous, in-line sort subroutine.
 
 If the subroutine's prototype is C<($$)>, the elements to be compared
 are passed by reference in C<@_>, as for a normal subroutine.  This is
@@ -4604,12 +4657,8 @@ Examples:
     use sort 'stable';
     @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
 
-    # force use of quicksort (not portable outside Perl 5.8)
-    use sort '_quicksort';  # note discouraging _
-    @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
-
-    # similar to the previous example, but demand stability as well
-    use sort qw( _mergesort stable );
+    # 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
@@ -4643,7 +4692,8 @@ 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 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.
@@ -4969,7 +5019,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
@@ -5194,17 +5244,22 @@ out the names of those files that contain a match:
 	print $file, "\n";
     }
 
-=item sub BLOCK
+=item sub NAME BLOCK
+
+=item sub NAME (PROTO) BLOCK
 
-=item sub NAME
+=item sub NAME : ATTRS BLOCK
 
-=item sub NAME BLOCK
+=item sub NAME (PROTO) : ATTRS BLOCK
+
+This is subroutine definition, not a real function I<per se>.
+Without a BLOCK it's just a forward declaration.  Without a NAME,
+it's an anonymous function declaration, and does actually return
+a value: the CODE ref of the closure you just created.
 
-This is subroutine definition, not a real function I<per se>.  With just a
-NAME (and possibly prototypes or attributes), it's just a forward declaration.
-Without 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.
+See L<perlsub> and L<perlref> for details about subroutines and
+references, and L<attributes> and L<Attribute::Handlers> for more
+information about attributes.
 
 =item substr EXPR,OFFSET,LENGTH,REPLACEMENT
 
@@ -5355,7 +5410,7 @@ last byte of the scalar after the read.
 Note the I<characters>: depending on the status of the filehandle,
 either (8-bit) bytes or characters are read.  By default all
 filehandles operate on bytes, but for example if the filehandle has
-been opened with the C<:utf8> discipline (see L</open>, and the C<open>
+been opened with the C<:utf8> I/O layer (see L</open>, and the C<open>
 pragma, L<open>), the I/O will operate on characters, not bytes.
 
 An OFFSET may be specified to place the read data at some place in the
@@ -5379,7 +5434,7 @@ POSITION, and C<2> to set it to EOF plus POSITION (typically
 negative).
 
 Note the I<in bytes>: even if the filehandle has been set to operate
-on characters (for example by using the C<:utf8> discipline), tell()
+on characters (for example by using the C<:utf8> I/O layer), tell()
 will return byte offsets, not character offsets (because implementing
 that would render sysseek() very slow).
 
@@ -5480,7 +5535,7 @@ In the case the SCALAR is empty you can use OFFSET but only zero offset.
 Note the I<characters>: depending on the status of the filehandle,
 either (8-bit) bytes or characters are written.  By default all
 filehandles operate on bytes, but for example if the filehandle has
-been opened with the C<:utf8> discipline (see L</open>, and the open
+been opened with the C<:utf8> I/O layer (see L</open>, and the open
 pragma, L<open>), the I/O will operate on characters, not bytes.
 
 =item tell FILEHANDLE
@@ -5494,7 +5549,7 @@ last read.
 
 Note the I<in bytes>: even if the filehandle has been set to
 operate on characters (for example by using the C<:utf8> open
-discipline), tell() will return byte offsets, not character offsets
+layer), tell() will return byte offsets, not character offsets
 (because that would render seek() and tell() rather slow).
 
 The return value of tell() for the standard streams like the STDIN
@@ -5616,7 +5671,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>.
 
@@ -5647,6 +5702,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
@@ -5809,6 +5867,7 @@ See L</pack> for more examples and notes.
 =item untie VARIABLE
 
 Breaks the binding between a variable and a package.  (See C<tie>.)
+Has no effect if the variable is not tied.
 
 =item unshift ARRAY,LIST
 
@@ -5913,8 +5972,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.