X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=c42257516b74e025a233d547b0d8de0a7cd9a347;hb=83272a45226e83bd136d713158e9b44ace2dbc8d;hp=858f23f5ad6cea0905c348c27790d3c7fc9ca51a;hpb=d5563ed7fd46e9485baaa3b43c79a6a71c7b4740;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 858f23f..c422575 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -445,7 +445,7 @@ 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. -=item binmode FILEHANDLE, DISCIPLINE +=item binmode FILEHANDLE, LAYER =item binmode FILEHANDLE @@ -455,27 +455,21 @@ binary and text files. If FILEHANDLE is an expression, the value is taken as the name of the filehandle. Returns true on success, C on failure. -DISCIPLINE can be either of C<:bytes> for "binary" mode or C<:crlf> -for "text" mode. If the DISCIPLINE is omitted, it defaults to -C<:bytes>. To mark FILEHANDLE as UTF-8, use C<:utf8>. For backward -compatibility C also implicitly marks the -filehandle as bytes. - -The C<:bytes>, C<:crlf>, and C<:utf8>, and any other directives of the -form C<:...>, are called I/O I. The C pragma can -be used to establish default I/O disciplines. See L. - -The C<:raw> discipline is deprecated. (As opposed to what Camel III -said, it is not the inverse of C<:crlf>.) See L and the -discussion about the PERLIO environment variable. - -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. -The C<:encoding> discipline sometimes needs to be called in -mid-stream, and it doesn't flush the stream. +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 the simply inverse of C<:crlf> +-- other layers which would affect binary nature of the stream are +I disabled. See L, L and the discussion about the +PERLIO environment variable. + +I 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 @@ -483,7 +477,26 @@ 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), and do not use binmode() on text 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. The C pragma can be used to +establish default I/O layers. See L. + +In general, binmode() should be called after open() but before any I/O +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. +The C<:encoding> layer sometimes needs to be called in +mid-stream, and it doesn't flush the stream. The operating system, device drivers, C libraries, and Perl run-time system all work together to let the programmer treat a single @@ -496,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. @@ -645,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 +is interpreted as C<(chomp $cwd) = `pwd`;>, rather than as +C which you might expect. Similarly, +C is interpreted as C rather than +as C. + =item chop VARIABLE =item chop( LIST ) @@ -664,6 +683,8 @@ last C is returned. Note that C returns the last character. To return all but the last character, use C. +See also L. + =item chown LIST Changes the owner (and group) of a list of files. The first two @@ -2032,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 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. +In list context, returns a (possibly empty) list of filename expansions on +the value of EXPR such as the standard Unix shell F 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. Beginning with v5.6.0, this operator is implemented using the standard C extension. See L for details. @@ -2476,7 +2499,7 @@ and the month of the year, may not necessarily be three characters wide. =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 until the lock goes out of scope. lock() is a "weak keyword" : this means that if you've defined a function @@ -2787,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 that affect how the input and output -are processed: see L and L. 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 and +L for more details). For example open(FH, "<:utf8", "file") will open the UTF-8 encoded file containing Unicode characters, -see L. +see L. (Note that if layers are specified in the +three-arg form then default layers set by the C pragma are +ignored.) Open returns nonzero upon success, the undefined value otherwise. If the C involved a pipe, the return value happens to be the pid of @@ -2808,11 +2834,6 @@ 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. The rest need it. -In the three argument form MODE may also contain a list of IO "layers" -(see L and L for more details) to be applied to the -handle. This can be used to achieve the effect of C 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 is frequently used in connection with C. Even if C won't do what you want (say, in a CGI script, @@ -3751,7 +3772,7 @@ see C. 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. =item readdir DIRHANDLE @@ -3823,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 @@ -4171,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 @@ -4343,7 +4364,7 @@ L for examples. Note the I: 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, 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. @@ -5389,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 @@ -5413,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). @@ -5514,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 @@ -5528,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 @@ -5846,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