C<-X>, C<binmode>, C<chmod>, C<chown>, C<chroot>, C<crypt>,
C<dbmclose>, C<dbmopen>, C<dump>, C<endgrent>, C<endhostent>,
C<endnetent>, C<endprotoent>, C<endpwent>, C<endservent>, C<exec>,
-C<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostent>,
-C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
+C<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostbyname>,
+C<gethostent>, C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
C<getppid>, C<getprgp>, C<getpriority>, C<getprotobynumber>,
C<getprotoent>, C<getpwent>, C<getpwnam>, C<getpwuid>,
C<getservbyport>, C<getservent>, C<getsockopt>, C<glob>, C<ioctl>,
=over 8
-=item I<-X> FILEHANDLE
+=item -X FILEHANDLE
-=item I<-X> EXPR
+=item -X EXPR
-=item I<-X>
+=item -X
A file test, where X is one of the letters listed below. This unary
operator takes one argument, either a filename or a filehandle, and
# didn't
}
+For more information see L<perlipc>.
+
=item atan2 Y,X
Returns the arctangent of Y/X in the range -PI to PI.
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).
-Note that as desipite what may be implied in I<"Programming Perl">
+Note that as despite 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.
+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
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.
+mid-stream, and it doesn't flush the stream. The C<:encoding>
+also implicitly pushes on top of itself the C<:utf8> layer because
+internally Perl will operate on UTF-8 encoded Unicode characters.
The operating system, device drivers, C libraries, and Perl run-time
system all work together to let the programmer treat a single
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
Closes a directory opened by C<opendir> and returns the success of that
system call.
-DIRHANDLE may be an expression whose value can be used as an indirect
-dirhandle, usually the real dirhandle name.
-
=item connect SOCKET,NAME
Attempts to connect to a remote socket, just as the connect system call
the password file for lousy passwords, amongst other things. Only the
guys wearing white hats should do this.
-Note that C<crypt> is intended to be a one-way function, much like
+Note that L<crypt|/crypt> is intended to be a one-way function, much like
breaking eggs to make an omelette. There is no (known) corresponding
decrypt function (in other words, the crypt() is a one-way hash
function). As a result, this function isn't all that useful for
When verifying an existing encrypted string you should use the
encrypted text as the salt (like C<crypt($plain, $crypted) eq
-$crypted>). This allows your code to work with the standard C<crypt>
+$crypted>). This allows your code to work with the standard L<crypt|/crypt>
and with more exotic implementations. In other words, do not assume
anything about the returned string itself, or how many bytes in
the encrypted string matter.
When choosing a new salt create a random two character string whose
characters come from the set C<[./0-9A-Za-z]> (like C<join '', ('.',
-'/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>).
+'/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>). This set of
+characters is just a recommendation; the characters allowed in
+the salt depend solely on your system's crypt library, and Perl can't
+restrict what salts C<crypt()> accepts.
Here's an example that makes sure that whoever runs this program knows
their own password:
Of course, typing in your own password to whoever asks you
for it is unwise.
-The L<crypt> function is unsuitable for encrypting large quantities
+The L<crypt|/crypt> function is unsuitable for encrypting large quantities
of data, not least of all because you can't get the information
back. Look at the F<by-module/Crypt> and F<by-module/PGP> directories
on your favorite CPAN mirror for a slew of potentially useful
You may also use C<defined(&func)> to check whether subroutine C<&func>
has ever been defined. The return value is unaffected by any forward
-declarations of C<&foo>. Note that a subroutine which is not defined
+declarations of C<&func>. Note that a subroutine which is not defined
may still be callable: its package may have an C<AUTOLOAD> method that
makes it spring into existence the first time that it is called -- see
L<perlsub>.
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. Since Perl
+5.8.1 the ordering is different even between different runs of Perl
+for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
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
# insert dashes just before last line of last file
while (<>) {
- if (eof()) { # check for end of current file
+ if (eof()) { # check for end of last file
print "--------------\n";
- close(ARGV); # close or last; is needed if we
- # are reading from the terminal
}
print;
+ last if eof(); # needed if we're reading from a terminal
}
Practical hint: you almost never need to use C<eof> in Perl, because the
=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). Since
+Perl 5.8.1 the ordering is different even between different runs of
+Perl for security reasons (see L<perlsec/"Algorithmic Complexity
+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:
kill 9, @goners;
If SIGNAL is zero, no signal is sent to the process. This is a
-useful way to check that the process is alive and hasn't changed
+useful way to check that a child process is alive and hasn't changed
its UID. See L<perlport> for notes on the portability of this
construct.
process groups instead of processes. (On System V, a negative I<PROCESS>
number will also kill process groups, but that's not portable.) That
means you usually want to use positive not negative signals. You may also
-use a signal name in quotes. See L<perlipc/"Signals"> for details.
+use a signal name in quotes.
+
+See L<perlipc/"Signals"> for more details.
=item last LABEL
=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
Does the same thing as the C<stat> function (including setting the
special C<_> filehandle) but stats a symbolic link instead of the file
the symbolic link points to. If symbolic links are unimplemented on
-your system, a normal C<stat> is done.
+your system, a normal C<stat> is done. For much more detailed
+information, please see the documentation for C<stat>.
If EXPR is omitted, stats C<$_>.
=item no Module
-See the L</use> function, which C<no> is the opposite of.
+See the C<use> function, which C<no> is the opposite of.
=item oct EXPR
(The following is a comprehensive reference to open(): for a gentler
introduction you may consider L<perlopentut>.)
-If FILEHANDLE is an undefined lexical (C<my>) variable the variable is
-assigned a reference to a new anonymous filehandle, otherwise if
-FILEHANDLE is an expression, its value is used as the name of the real
-filehandle wanted. (This is considered a symbolic reference, so C<use
-strict 'refs'> should I<not> be in effect.)
+If FILEHANDLE is an undefined scalar variable (or array or hash element)
+the variable is assigned a reference to a new anonymous filehandle,
+otherwise if FILEHANDLE is an expression, its value is used as the name of
+the real filehandle wanted. (This is considered a symbolic reference, so
+C<use 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
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:
Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
C<seekdir>, C<rewinddir>, and C<closedir>. Returns true if successful.
+DIRHANDLE may be an expression whose value can be used as an indirect
+dirhandle, usually the real dirhandle name. If DIRHANDLE is an undefined
+scalar variable (or array or hash element), the variable is assigned a
+reference to a new anonymous dirhandle.
DIRHANDLEs have their own namespace separate from FILEHANDLEs.
=item ord EXPR
x A null byte.
X Back up a byte.
- @ Null fill to absolute position.
+ @ Null fill to absolute position, counted from the start of
+ the innermost ()-group.
( Start of a ()-group.
The following rules apply:
integer-packing ones like C<n> (for Java strings), C<w> (for ASN.1 or
SNMP) and C<N> (for Sun XDR).
-The I<string-item> must, at present, be C<"A*">, C<"a*"> or C<"Z*">.
-For C<unpack> the length of the string is obtained from the I<length-item>,
-but if you put in the '*' it will be ignored.
+For C<pack>, the I<string-item> must, at present, be C<"A*">, C<"a*"> or
+C<"Z*">. For C<unpack> the length of the string is obtained from the
+I<length-item>, but if you put in the '*' it will be ignored. For all other
+codes, C<unpack> applies the length value to the next item, which must not
+have a repeat count.
unpack 'C/a', "\04Gurusamy"; gives 'Guru'
unpack 'a3/A* A*', '007 Bond J '; gives (' Bond','J')
print $Config{longsize}, "\n";
print $Config{longlongsize}, "\n";
-(The C<$Config{longlongsize}> will be undefine if your system does
+(The C<$Config{longlongsize}> will be undefined if your system does
not support long longs.)
=item *
=item *
A ()-group is a sub-TEMPLATE enclosed in parentheses. A group may
-take a repeat count, both as postfix, and via the C</> template
-character.
+take a repeat count, both as postfix, and for unpack() also via the C</>
+template character. Within each repetition of a group, positioning with
+C<@> starts again at 0. Therefore, the result of
+
+ pack( '@1A((@2A)@3A)', 'a', 'b', 'c' )
+
+is the string "\0a\0\0bc".
+
=item *
=item *
A comment in a TEMPLATE starts with C<#> and goes to the end of line.
+White space may be used to separate pack codes from each other, but
+a C<!> modifier and a repeat count must follow immediately.
=item *
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
$line = <STDIN>;
$line = readline(*STDIN); # same thing
+If readline encounters an operating system error, C<$!> will be set with the
+corresponding error message. It can be helpful to check C<$!> when you are
+reading from filehandles you don't trust, such as a tty or a socket. The
+following example uses the operator form of C<readline>, and takes the necessary
+steps to ensure that C<readline> was successful.
+
+ for (;;) {
+ undef $!;
+ unless (defined( $line = <> )) {
+ die $! if $!;
+ last; # reached EOF
+ }
+ # ...
+ }
+
=item readlink EXPR
=item readlink
(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
eval "require $class";
+Now that you understand how C<require> looks for files in the case of
+a bareword argument, there is a little extra functionality going on
+behind the scenes. Before C<require> looks for a "F<.pm>" extension,
+it will first look for a filename with a "F<.pmc>" extension. A file
+with this extension is assumed to be Perl bytecode generated by
+L<B::Bytecode|B::Bytecode>. If this file is found, and it's modification
+time is newer than a coinciding "F<.pm>" non-compiled file, it will be
+loaded in place of that non-compiled file ending in a "F<.pm>" extension.
+
You can also insert hooks into the import facility, by putting directly
Perl code into the @INC array. There are three forms of hooks: subroutine
references, array references and blessed objects.
=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
past the end of the array, perl issues a warning, and splices at the
end of the array.
-The following equivalences hold (assuming C<$[ == 0>):
+The following equivalences hold (assuming C<< $[ == 0 and $#a >= $i >> )
push(@a,$x,$y) splice(@a,@a,0,$x,$y)
pop(@a) splice(@a,-1)
shift(@a) splice(@a,0,1)
unshift(@a,$x,$y) splice(@a,0,0,$x,$y)
- $a[$x] = $y splice(@a,$x,1,$y)
+ $a[$i] = $y splice(@a,$i,1,$y)
Example, assuming array lengths are passed before arrays:
($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.
patterns that vary at runtime. (To do runtime compilation only once,
use C</$variable/o>.)
-As a special case, specifying a PATTERN of space (C<' '>) will split on
-white space just as C<split> with no arguments does. Thus, C<split(' ')> can
-be used to emulate B<awk>'s default behavior, whereas C<split(/ /)>
+As a special case, specifying a PATTERN of space (S<C<' '>>) will split on
+white space just as C<split> with no arguments does. Thus, S<C<split(' ')>> can
+be used to emulate B<awk>'s default behavior, whereas S<C<split(/ /)>>
will give you as many null initial fields as there are leading spaces.
-A C<split> on C</\s+/> is like a C<split(' ')> except that any leading
+A C<split> on C</\s+/> is like a S<C<split(' ')>> except that any leading
whitespace produces a null first field. A C<split> with no arguments
-really does a C<split(' ', $_)> internally.
+really does a S<C<split(' ', $_)>> internally.
A PATTERN of C</^/> is treated as if it were C</^/m>, since it isn't
much use otherwise.
S_IRWXG S_IRGRP S_IWGRP S_IXGRP
S_IRWXO S_IROTH S_IWOTH S_IXOTH
- # Setuid/Setgid/Stickiness.
+ # Setuid/Setgid/Stickiness/SaveText.
+ # Note that the exact meaning of these is system dependent.
S_ISUID S_ISGID S_ISVTX S_ISTXT
S_ISENFMT($mode) S_ISWHT($mode)
See your native chmod(2) and stat(2) documentation for more details
-about the S_* constants.
+about the S_* constants. To get status info for a symbolic link
+instead of the target file behind the link, use the C<lstat> function.
=item study SCALAR
parts of the EXPR and return what was there before in one operation,
just as you can with splice().
+If the lvalue returned by substr is used after the EXPR is changed in
+any way, the behaviour may not be as expected and is subject to change.
+This caveat includes code such as C<print(substr($foo,$a,$b)=$bar)> or
+C<(substr($foo,$a,$b)=$bar)=$fud> (where $foo is changed via the
+substring assignment, and then the substr is used again), or where a
+substr() is aliased via a C<foreach> loop or passed as a parameter or
+a reference to it is taken and then the alias, parameter, or deref'd
+reference either is used after the original EXPR has been changed or
+is assigned to and then used a second time.
+
=item symlink OLDFILE,NEWFILE
Creates a new filename symbolically linked to the old filename.
=item sysread FILEHANDLE,SCALAR,LENGTH
-Attempts to read LENGTH I<characters> of data into variable SCALAR
-from the specified FILEHANDLE, using the system call read(2). It
-bypasses buffered IO, so mixing this with other kinds of reads,
-C<print>, C<write>, C<seek>, C<tell>, or C<eof> can cause confusion
-because stdio usually buffers data. 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 so
-that the last byte actually read is the 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> I/O layer (see L</open>, and the C<open>
-pragma, L<open>), the I/O will operate on characters, not bytes.
+Attempts to read LENGTH bytes of data into variable SCALAR from the
+specified FILEHANDLE, using the system call read(2). It bypasses
+buffered IO, so mixing this with other kinds of reads, C<print>,
+C<write>, C<seek>, C<tell>, or C<eof> can cause confusion because the
+perlio or stdio layers usually buffers data. Returns the number of
+bytes 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 so that the last byte actually read is the last byte 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
very well on device files (like ttys) anyway. Use sysread() and check
for a return value for 0 to decide whether you're done.
+Note that if the filehandle has been marked as C<:utf8> Unicode
+characters are read instead of bytes (the LENGTH, OFFSET, and the
+return value of sysread() are in 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 sysseek FILEHANDLE,POSITION,WHENCE
-Sets FILEHANDLE's system position I<in bytes> using the system call
+Sets FILEHANDLE's system position in bytes using the system call
lseek(2). FILEHANDLE may be an expression whose value gives the name
of the filehandle. The values for WHENCE are C<0> to set the new
position to POSITION, C<1> to set the it to the current position plus
will return byte offsets, not character offsets (because implementing
that would render sysseek() very slow).
-sysseek() bypasses normal buffered io, so mixing this with reads (other
+sysseek() bypasses normal buffered IO, so mixing this with reads (other
than C<sysread>, for example >< or read()) C<print>, C<write>,
C<seek>, C<tell>, or C<eof> may cause confusion.
=item syswrite FILEHANDLE,SCALAR
-Attempts to write LENGTH characters of data from variable SCALAR to
-the specified FILEHANDLE, using the system call write(2). If LENGTH
-is not specified, writes whole SCALAR. It bypasses buffered IO, so
+Attempts to write LENGTH bytes of data from variable SCALAR to the
+specified FILEHANDLE, using the system call write(2). If LENGTH is
+not specified, writes whole SCALAR. It bypasses buffered IO, so
mixing this with reads (other than C<sysread())>, C<print>, C<write>,
-C<seek>, C<tell>, or C<eof> may cause confusion because stdio usually
-buffers data. Returns the number of characters actually written, or
-C<undef> if there was an error (in this case the errno variable C<$!>
-is also set). If the LENGTH is greater than the available data in the
-SCALAR after the OFFSET, only as much data as is available will be
-written.
+C<seek>, C<tell>, or C<eof> may cause confusion because the perlio and
+stdio layers usually buffers data. Returns the number of bytes
+actually written, or C<undef> if there was an error (in this case the
+errno variable C<$!> is also set). If the LENGTH is greater than the
+available data in the SCALAR after the OFFSET, only as much data as is
+available will be written.
An OFFSET may be specified to write the data from some part of the
string other than the beginning. A negative OFFSET specifies writing
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 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> I/O layer (see L</open>, and the open
-pragma, L<open>), the I/O will operate on characters, not bytes.
+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 tell FILEHANDLE
Suitable for feeding to C<gmtime> and C<localtime>.
For measuring time in better granularity than one second,
-you may use either the Time::HiRes module from CPAN, or
-if you have gettimeofday(2), you may be able to use the
-C<syscall> interface of Perl, see L<perlfaq8> for details.
+you may use either the Time::HiRes module (from CPAN, and starting from
+Perl 5.8 part of the standard distribution), or if you have
+gettimeofday(2), you may be able to use the C<syscall> interface of Perl.
+See L<perlfaq8> for details.
=item times
Undefines the value of EXPR, which must be an lvalue. Use only on a
scalar value, an array (using C<@>), a hash (using C<%>), a subroutine
-(using C<&>), or a typeglob (using <*>). (Saying C<undef $hash{$key}>
+(using C<&>), or a typeglob (using C<*>). (Saying C<undef $hash{$key}>
will probably not do what you expect on most predefined variables or
DBM list values, so don't do that; see L<delete>.) Always returns the
undefined value. You can omit the EXPR, in which case nothing is
=item unpack TEMPLATE,EXPR
+=item unpack TEMPLATE
+
C<unpack> does the reverse of C<pack>: it takes a string
and expands it out into a list of values.
(In scalar context, it returns merely the first value produced.)
+If EXPR is omitted, unpacks the C<$_> string.
+
The string is broken into chunks described by the TEMPLATE. Each chunk
is converted separately to a value. Typically, either the string is a result
of C<pack>, or the bytes of the string represent a C structure of some
corresponds to a valid memory location, passing a pointer value that's
not known to be valid is likely to have disastrous consequences.
-If the repeat count of a field is larger than what the remainder of
-the input string allows, repeat count is decreased. If the input string
-is longer than one described by the TEMPLATE, the rest is ignored.
+If there are more pack codes or if the repeat count of a field or a group
+is larger than what the remainder of the input string allows, the result
+is not well defined: in some cases, the repeat count is decreased, or
+C<unpack()> will produce null strings or zeroes, or terminate with an
+error. If the input string is longer than one described by the TEMPLATE,
+the rest is ignored.
See L</pack> for more examples and notes.
files. The first two elements of the list must be the NUMERICAL access
and modification times, in that order. Returns the number of files
successfully changed. The inode change time of each file is set
-to the current time. This code has the same effect as the C<touch>
-command if the files already exist:
+to the current time. For example, this code has the same effect as the
+Unix touch(1) command when the files I<already exist>.
#!/usr/bin/perl
$now = time;
utime $now, $now, @ARGV;
-If the first two elements of the list are C<undef>, then the utime(2)
-function in the C library will be called with a null second argument.
-On most systems, this will set the file's access and modification
-times to the current time. (i.e. equivalent to the example above.)
+B<Note:> Under NFS, touch(1) uses the time of the NFS server, not
+the time of the local machine. If there is a time synchronization
+problem, the NFS server and local machine will have different times.
+
+Since perl 5.7.2, if the first two elements of the list are C<undef>, then
+the utime(2) function in the C library will be called with a null second
+argument. On most systems, this will set the file's access and
+modification times to the current time (i.e. equivalent to the example
+above.)
utime undef, undef, @ARGV;
=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. Since Perl
+5.8.1 the ordering is different even between different runs of Perl
+for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
+
+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