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. To mark FILEHANDLE as
-UTF-8, use C<:utf8>, and to mark it as bytes, use C<:bytes>.
-
-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
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.
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 )
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
=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.
=item lock THING
-This function places an advisory lock on a shared variable, or referenced
+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
=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
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
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,
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.
=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
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.
+with it.
-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.) Examples:
+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 in the main interpreter after the first new interpreter
-has been cloned (for example, after the first new thread has been
-created).
+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
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
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
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
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.
=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
print $file, "\n";
}
-=item sub BLOCK
+=item sub NAME BLOCK
-=item sub NAME
+=item sub NAME (PROTO) BLOCK
-=item sub NAME BLOCK
+=item sub NAME : ATTRS 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
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
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).
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
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
=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
projects / p5sagit/p5-mst-13.2.git / blobdiff