taken as the name of the filehandle. Returns true on success,
otherwise it returns C<undef> and sets C<$!> (errno).
+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. Also, people can
+set their I/O to be by default UTF-8 encoded Unicode, not bytes.
+
+In other words: regardless of platform, use binmode() on binary data,
+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.
+
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).
I<also> disabled. See L<PerlIO>, L<perlrun> and the discussion about the
PERLIO environment variable.
+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>.
+
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
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 normally flush any
pending buffered output data (and perhaps pending input data) on the
to 255 (inclusive) are by default not encoded in Unicode for backward
compatibility reasons (but see L<encoding>).
+If NUMBER is omitted, uses C<$_>.
+
For the reverse, use L</ord>.
-See L<perlunicode> and L<encoding> for more about Unicode.
-If NUMBER is omitted, uses C<$_>.
+Note that under the C<bytes> pragma the NUMBER is masked to
+the low eight bits.
+
+See L<perlunicode> and L<encoding> for more about Unicode.
=item chroot FILENAME
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.
element in the hash.
Entries are returned in an apparently random order. The actual random
-order is subject to change in future versions of perl, but it is guaranteed
-to be in the same order as either the C<keys> or C<values> function
-would produce on the same (unmodified) hash.
+order is subject to change in future versions of perl, but it is
+guaranteed to be in the same order as either the C<keys> or C<values>
+function would produce on the same (unmodified) hash.
When the hash is entirely read, a null array is returned in list context
(which when assigned produces a false (C<0>) value), and C<undef> in
=item keys HASH
-Returns a list consisting of all the keys of the named hash. (In
-scalar context, returns the number of keys.) The keys are returned in
-an apparently random order. The actual random order is subject to
-change in future versions of perl, but it is guaranteed to be the same
-order as either the C<values> or C<each> function produces (given
-that the hash has not been modified). As a side effect, it resets
-HASH's iterator.
+Returns a list consisting of all the keys of the named hash.
+(In scalar context, returns the number of keys.)
+
+The keys are returned in an apparently random order. The actual
+random order is subject to change in future versions of perl, but it
+is guaranteed to be the same order as either the C<values> or C<each>
+function produces (given that the hash has not been modified).
+Attacks">).
+
+As a side effect, calling keys() resets the HASH's internal iterator,
+see L</each>.
Here is yet another way to print your environment:
=item length
-Returns the length in characters of the value of EXPR. If EXPR is
+Returns the length in I<characters> of the value of EXPR. If EXPR is
omitted, returns length of C<$_>. Note that this cannot be used on
an entire array or hash to find out how many elements these have.
For that, use C<scalar @array> and C<scalar keys %hash> respectively.
+Note the I<characters>: if the EXPR is in Unicode, you will get the
+number of characters, not the number of bytes. To get the length
+in bytes, use C<do { use bytes; length(EXPR) }>, see L<bytes>.
+
=item link OLDFILE,NEWFILE
Creates a new filename linked to the old filename. Returns true for
open(TMP, "+>", undef) or die ...
-opens a filehandle to an anonymous temporary file.
+opens a filehandle to an anonymous temporary file. Also using "+<"
+works for symmetry, but you really should consider writing something
+to the temporary file first. You will need to seek() to do the
+reading.
File handles can be opened to "in memory" files held in Perl scalars via:
Attempts to read LENGTH I<characters> of data into variable SCALAR
from the specified FILEHANDLE. Returns the number of characters
actually read, C<0> at end of file, or undef if there was an error (in
-the latter case C<$!> is also set). SCALAR will be grown or shrunk to
-the length actually read. If SCALAR needs growing, the new bytes will
-be zero bytes. An OFFSET may be specified to place the read data into
-some other place in SCALAR than the beginning. The call is actually
-implemented in terms of either Perl's or system's fread() call. To
-get a true read(2) system call, see C<sysread>.
+the latter case C<$!> is also set). SCALAR will be grown or shrunk
+so that the last character actually read is the last character of the
+scalar after the read.
+
+An OFFSET may be specified to place the read data at some place in the
+string other than the beginning. A negative OFFSET specifies
+placement at that many characters counting backwards from the end of
+the string. A positive OFFSET greater than the length of SCALAR
+results in the string being padded to the required size with C<"\0">
+bytes before the result of the read is appended.
+
+The call is actually implemented in terms of either Perl's or system's
+fread() call. To get a true read(2) system call, 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> I/O layer (see L</open>, and the C<open>
-pragma, L<open>), the I/O will operate on characters, not bytes.
+pragma, L<open>), the I/O will operate on UTF-8 encoded Unicode
+characters, not bytes. Similarly for the C<:encoding> pragma:
+in that case pretty much any characters can be read.
=item readdir DIRHANDLE
(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> I/O layer (see the C<open>
-pragma, L<open>), the I/O will operate on characters, not bytes.
+pragma, L<open>), the I/O will operate on UTF-8 encoded Unicode
+characters, not bytes. Similarly for the C<:encoding> pragma:
+in that case pretty much any characters can be read.
=item redo LABEL
=item rmdir
-Deletes the directory specified by FILENAME if that directory is empty. If it
-succeeds it returns true, otherwise it returns false and sets C<$!> (errno). If
-FILENAME is omitted, uses C<$_>.
+Deletes the directory specified by FILENAME if that directory is
+empty. If it succeeds it returns true, otherwise it returns false and
+sets C<$!> (errno). If FILENAME is omitted, uses C<$_>.
=item s///
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> I/O layer (see L</open>, or
-the C<open> pragma, L<open>), the I/O will operate on characters, not
-bytes.
+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 UTF-8 encoded
+Unicode characters, not bytes. Similarly for the C<:encoding> pragma:
+in that case pretty much any characters can be sent.
=item setpgrp PID,PGRP
sometimes saying the opposite, for example) the results are not
well-defined.
+Because C<< <=> >> returns C<undef> when either operand is C<NaN>
+(not-a-number), and because C<sort> will trigger a fatal error unless the
+result of a comparison is defined, when sorting with a comparison function
+like C<< $a <=> $b >>, be careful about lists that might contain a C<NaN>.
+The following example takes advantage of the fact that C<NaN != NaN> to
+eliminate any C<NaN>s from the input.
+
+ @result = sort { $a <=> $b } grep { $_ == $_ } @input;
+
=item splice ARRAY,OFFSET,LENGTH,LIST
=item splice ARRAY,OFFSET,LENGTH
($login, $passwd, $remainder) = split(/:/, $_, 3);
-When assigning to a list, if LIMIT is omitted, Perl supplies a LIMIT
-one larger than the number of variables in the list, to avoid
+When assigning to a list, if LIMIT is omitted, or zero, Perl supplies
+a LIMIT one larger than the number of variables in the list, to avoid
unnecessary work. For the list above LIMIT would have been 4 by
default. In time critical applications it behooves you not to split
into more fields than you really need.
that many characters counting backwards from the end of the string.
In the case the SCALAR is empty you can use OFFSET but only zero offset.
-Note that if the filehandle has been marked as C<:utf8>,
-Unicode characters are written instead of bytes (the LENGTH, OFFSET,
-and the return value of syswrite() are in Unicode characters).
+Note that if the filehandle has been marked as C<:utf8>, Unicode
+characters are written instead of bytes (the LENGTH, OFFSET, and the
+return value of syswrite() are in UTF-8 encoded Unicode characters).
The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
See L</binmode>, L</open>, and the C<open> pragma, L<open>.
=item values HASH
-Returns a list consisting of all the values of the named hash. (In a
-scalar context, returns the number of values.) The values are
-returned in an apparently random order. The actual random order is
-subject to change in future versions of perl, but it is guaranteed to
-be the same order as either the C<keys> or C<each> function would
-produce on the same (unmodified) hash.
+Returns a list consisting of all the values of the named hash.
+(In a scalar context, returns the number of values.)
+
+The values are returned in an apparently random order. The actual
+random order is subject to change in future versions of perl, but it
+is guaranteed to be the same order as either the C<keys> or C<each>
+function would produce on the same (unmodified) hash.
+
+As a side effect, calling values() resets the HASH's internal iterator,
+see L</each>.
Note that the values are not copied, which means modifying them will
modify the contents of the hash:
for (values %hash) { s/foo/bar/g } # modifies %hash values
for (@hash{keys %hash}) { s/foo/bar/g } # same
-As a side effect, calling values() resets the HASH's internal iterator.
See also C<keys>, C<each>, and C<sort>.
=item vec EXPR,OFFSET,BITS
https://perl5.git.perl.org / perl5.git / blobdiff