X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=c42257516b74e025a233d547b0d8de0a7cd9a347;hb=83272a45226e83bd136d713158e9b44ace2dbc8d;hp=048ecfb4bab33e7f39618c155ed1111dc2752a1b;hpb=80a5d8e74b5512d4ab704d0e83466ae41247ce55;p=p5sagit%2Fp5-mst-13.2.git
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 048ecfb..c422575 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -136,8 +136,8 @@ C, C, C, C, C, C, C
C<-I>, C, C, C, C, C, C,
C, C, C, C, C, C,
-C, C, C, C, C, C,
-C, C
+C, C, C, C, C, C,
+C, C, C
=item Keywords related to the control flow of your perl program
@@ -172,7 +172,7 @@ C, C.
-
=item readline EXPR
Reads from the filehandle whose typeglob is contained in EXPR. In scalar
@@ -3792,7 +3844,7 @@ See L for examples.
Note the I: 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
+binmode() to operate with the C<:utf8> I/O layer (see the C
pragma, L), the I/O will operate on characters, not bytes.
=item redo LABEL
@@ -4140,7 +4192,7 @@ otherwise.
Note the I: 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 or C, don't use
@@ -4251,6 +4303,9 @@ You can effect a sleep of 250 milliseconds this way:
select(undef, undef, undef, 0.25);
+Note that whether C, or
+binmode() to operate with the C<:utf8> I/O layer (see L, or
the C pragma, L), the I/O will operate on characters, not
bytes.
@@ -4432,26 +4487,6 @@ help.
See also the POSIX module's C 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.
-
=item socket SOCKET,DOMAIN,TYPE,PROTOCOL
Opens a socket of the specified kind and attaches it to filehandle
@@ -4493,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, Cs 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
-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 is undefined.
+
+If SUBNAME or BLOCK is omitted, Cs 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 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
@@ -4624,12 +4661,6 @@ Examples:
use sort '_mergesort'; # note discouraging _
@new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
- # Similar to the previous example, but demand stability as well
- # Because of the way quicksort is "stabilized", this combination
- # is not threadsafe
- use sort qw( _quicksort stable );
- @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
-
If you're using strict, you I declare $a
and $b as lexicals. They are package globals. That means
if you're in the C package and type
@@ -4988,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 device,
-if available.
+if available.
You can call srand($seed) with the same $seed to reproduce the
I sequence from rand(), but this is usually reserved for
@@ -5213,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.
+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. 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
-and L for details.
+See L and L for details about subroutines and
+references, and L and L for more
+information about attributes.
=item substr EXPR,OFFSET,LENGTH,REPLACEMENT
@@ -5374,7 +5410,7 @@ last byte of the scalar after the read.
Note the I: 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, and the C
+been opened with the C<:utf8> I/O layer (see L, and the C
pragma, L), the I/O will operate on characters, not bytes.
An OFFSET may be specified to place the read data at some place in the
@@ -5398,7 +5434,7 @@ POSITION, and C<2> to set it to EOF plus POSITION (typically
negative).
Note the I: 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).
@@ -5499,7 +5535,7 @@ In the case the SCALAR is empty you can use OFFSET but only zero offset.
Note the I: 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, and the open
+been opened with the C<:utf8> I/O layer (see L, and the open
pragma, L), the I/O will operate on characters, not bytes.
=item tell FILEHANDLE
@@ -5513,7 +5549,7 @@ last read.
Note the I: 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
@@ -5635,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 and C.
@@ -5666,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
@@ -5828,6 +5867,7 @@ See L for more examples and notes.
=item untie VARIABLE
Breaks the binding between a variable and a package. (See C.)
+Has no effect if the variable is not tied.
=item unshift ARRAY,LIST
@@ -5932,8 +5972,6 @@ by C