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
print "Text\n" if -T _;
print "Binary\n" if -B _;
+As of Perl 5.9.1, as a form of purely syntactic sugar, you can stack file
+test operators, in a way that C<-f -w -x $file> is equivalent to
+C<-x $file && -w _ && -f _>. (This is only syntax fancy : if you use
+the return value of C<-f $file> as an argument to another filetest
+operator, no special magic will happen.)
+
=item abs VALUE
=item abs
# 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">
-(the Camel) or elsewhere C<:raw> is I<not> the simply inverse of C<:crlf>
+Note that, 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
Changes the permissions of a list of files. The first element of the
list must be the numerical mode, which should probably be an octal
-number, and which definitely should I<not> a string of octal digits:
+number, and which definitely should I<not> be a string of octal digits:
C<0644> is okay, C<'0644'> is not. Returns the number of files
successfully changed. See also L</oct>, if all you have is a string.
If you chomp a list, each element is chomped, and the total number of
characters removed is returned.
+If the C<encoding> pragma is in scope then the lengths returned are
+calculated from the length of C<$/> in Unicode characters, which is not
+always the same as the length of C<$/> in the native encoding.
+
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
Returns the character represented by that NUMBER in the character set.
For example, C<chr(65)> is C<"A"> in either ASCII or Unicode, and
-chr(0x263a) is a Unicode smiley face. Note that characters from 127
-to 255 (inclusive) are by default not encoded in Unicode for backward
-compatibility reasons (but see L<encoding>).
+chr(0x263a) is a Unicode smiley face. Note that characters from 128
+to 255 (inclusive) are by default not encoded in UTF-8 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
C<open>.) However, an explicit C<close> on an input file resets the line
counter (C<$.>), while the implicit close done by C<open> does not.
-If the file handle came from a piped open C<close> will additionally
-return false if one of the other system calls involved fails or if the
+If the file handle came from a piped open, C<close> will additionally
+return false if one of the other system calls involved fails, or if the
program exits with non-zero status. (If the only problem was that the
-program exited non-zero C<$!> will be set to C<0>.) Closing a pipe
+program exited non-zero, C<$!> will be set to C<0>.) Closing a pipe
also waits for the process executing on the pipe to complete, in case you
want to look at the output of the pipe afterwards, and
implicitly puts the exit status value of that command into C<$?>.
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>.
the size of the array will shrink to the highest element that tests
true for exists() (or 0 if no such element exists).
-Returns each element so deleted or the undefined value if there was no such
-element. Deleting from C<$ENV{}> modifies the environment. Deleting from
+Returns a list with the same number of elements as the number of elements
+for which deletion was attempted. Each element of that list consists of
+either the value of the element deleted, or the undefined value. In scalar
+context, this means that you get the value of the last element deleted (or
+the undefined value if that element did not exist).
+
+ %hash = (foo => 11, bar => 22, baz => 33);
+ $scalar = delete $hash{foo}; # $scalar is 11
+ $scalar = delete @hash{qw(foo bar)}; # $scalar is 22
+ @array = delete @hash{qw(foo bar baz)}; # @array is (undef,undef,33)
+
+Deleting from C<%ENV> modifies the environment. Deleting from
a hash tied to a DBM file deletes the entry from the DBM file. Deleting
from a C<tie>d hash or array may not necessarily return anything.
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
fcntl($filehandle, F_GETFL, $packed_return_buffer)
or die "can't fcntl F_GETFL: $!";
-You don't have to check for C<defined> on the return from C<fnctl>.
+You don't have to check for C<defined> on the return from C<fcntl>.
Like C<ioctl>, it maps a C<0> return from the system call into
C<"0 but true"> in Perl. This string is true in boolean context and C<0>
in numeric context. It is also exempt from the normal B<-w> warnings
doesn't implement fcntl(2). See the Fcntl module or your fcntl(2)
manpage to learn what functions are available on your system.
+Here's an example of setting a filehandle named C<REMOTE> to be
+non-blocking at the system level. You'll have to negotiate C<$|>
+on your own, though.
+
+ use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
+
+ $flags = fcntl(REMOTE, F_GETFL, 0)
+ or die "Can't get flags for the socket: $!\n";
+
+ $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK)
+ or die "Can't set flags for the socket: $!\n";
+
=item fileno FILEHANDLE
Returns the file descriptor for a filehandle, or undefined if the
=item getsockopt SOCKET,LEVEL,OPTNAME
-Returns the socket option requested, or undef if there is an error.
+Queries the option named OPTNAME associated with SOCKET at a given LEVEL.
+Options may exist at multiple protocol levels depending on the socket
+type, but at least the uppermost socket level SOL_SOCKET (defined in the
+C<Socket> module) will exist. To query options at another level the
+protocol number of the appropriate protocol controlling the option
+should be supplied. For example, to indicate that an option is to be
+interpreted by the TCP protocol, LEVEL should be set to the protocol
+number of TCP, which you can get using getprotobyname.
+
+The call returns a packed string representing the requested socket option,
+or C<undef> if there is an error (the error reason will be in $!). What
+exactly is in the packed string depends in the LEVEL and OPTNAME, consult
+your system documentation for details. A very common case however is that
+the option is an integer, in which case the result will be an packed
+integer which you can decode using unpack with the C<i> (or C<I>) format.
+
+An example testing if Nagle's algorithm is turned on on a socket:
+
+ use Socket;
+
+ defined(my $tcp = getprotobyname("tcp"))
+ or die "Could not determine the protocol number for tcp";
+ # my $tcp = Socket::IPPROTO_TCP; # Alternative
+ my $packed = getsockopt($socket, $tcp, Socket::TCP_NODELAY)
+ or die "Could not query TCP_NODELAY SOCKEt option: $!";
+ my $nodelay = unpack("I", $packed);
+ print "Nagle's algorithm is turned ", $nodelay ? "off\n" : "on\n";
+
=item glob EXPR
$now_string = gmtime; # e.g., "Thu Oct 13 04:54:34 1994"
-Also see the C<timegm> function provided by the C<Time::Local> module,
-and the strftime(3) function available via the POSIX module.
+If you need local time instead of GMT use the L</localtime> builtin.
+See also the C<timegm> function provided by the C<Time::Local> module,
+and the strftime(3) and mktime(3) functions available via the L<POSIX> module.
-This scalar value is B<not> locale dependent (see L<perllocale>), but
-is instead a Perl builtin. Also see the C<Time::Local> module, and the
-strftime(3) and mktime(3) functions available via the POSIX module. To
-get somewhat similar but locale dependent date strings, set up your
-locale environment variables appropriately (please see L<perllocale>)
-and try for example:
-
- use POSIX qw(strftime);
- $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
-
-Note that the C<%a> and C<%b> escapes, which represent the short forms
-of the day of the week and the month of the year, may not necessarily
-be three characters wide in all locales.
+This scalar value is B<not> locale dependent (see L<perllocale>), but is
+instead a Perl builtin. To get somewhat similar but locale dependent date
+strings, see the example in L</localtime>.
=item goto LABEL
or another C<grep>) actually modifies the element in the original list.
This is usually something to be avoided when writing clear code.
+If C<$_> is lexical in the scope where the C<grep> appears (because it has
+been declared with C<my $_>) then, in addition the be locally aliased to
+the list elements, C<$_> keeps being lexical inside the block; i.e. it
+can't be seen from the outside, avoiding any potential side-effects.
+
See also L</map> for a list composed of the results of the BLOCK or EXPR.
=item hex EXPR
$retval = ioctl(...) || -1;
printf "System returned %d\n", $retval;
-The special string "C<0> but true" is exempt from B<-w> complaints
+The special string C<"0 but true"> is exempt from B<-w> complaints
about improper numeric conversions.
-Here's an example of setting a filehandle named C<REMOTE> to be
-non-blocking at the system level. You'll have to negotiate C<$|>
-on your own, though.
-
- use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
-
- $flags = fcntl(REMOTE, F_GETFL, 0)
- or die "Can't get flags for the socket: $!\n";
-
- $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK)
- or die "Can't set flags for the socket: $!\n";
-
=item join EXPR,LIST
Joins the separate strings of LIST into a single string with fields
=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>. (In particular, calling keys() in void context resets
+the iterator with no other overhead.)
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
$now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
-This scalar value is B<not> locale dependent, see L<perllocale>, but
-instead a Perl builtin. Also see the C<Time::Local> module
-(to convert the second, minutes, hours, ... back to seconds since the
-stroke of midnight the 1st of January 1970, the value returned by
-time()), and the strftime(3) and mktime(3) functions available via the
-POSIX module. To get somewhat similar but locale dependent date
-strings, set up your locale environment variables appropriately
-(please see L<perllocale>) and try for example:
+This scalar value is B<not> locale dependent but is a Perl builtin. For GMT
+instead of local time use the L</gmtime> builtin. See also the
+C<Time::Local> module (to convert the second, minutes, hours, ... back to
+the integer value returned by time()), and the L<POSIX> module's strftime(3)
+and mktime(3) functions.
+
+To get somewhat similar but locale dependent date strings, set up your
+locale environment variables appropriately (please see L<perllocale>) and
+try for example:
use POSIX qw(strftime);
$now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
+ # or for GMT formatted appropriately for your locale:
+ $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
Note that the C<%a> and C<%b>, the short forms of the day of the week
and the month of the year, may not necessarily be three characters wide.
most cases. See also L</grep> for an array composed of those items of
the original list for which the BLOCK or EXPR evaluates to true.
+If C<$_> is lexical in the scope where the C<map> appears (because it has
+been declared with C<my $_>) then, in addition the be locally aliased to
+the list elements, C<$_> keeps being lexical inside the block; i.e. it
+can't be seen from the outside, avoiding any potential side-effects.
+
C<{> starts both hash references and blocks, so C<map { ...> could be either
the start of map BLOCK LIST or map EXPR, LIST. Because perl doesn't look
ahead for the closing C<}> it has to take a guess at which its dealing with
=item no Module
-See the L</use> function, which C<no> is the opposite of.
+See the C<use> function, of which C<no> is the opposite.
=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:
+Since v5.8.0, perl has built using PerlIO by default. Unless you've
+changed this (ie Configure -Uuseperlio), you can open file handles to
+"in memory" files held in Perl scalars via:
open($fh, '>', \$variable) || ..
open(ARTICLE, "caesar <$article |") # ditto
or die "Can't start caesar: $!";
- open(EXTRACT, "|sort >/tmp/Tmp$$") # $$ is our process id
+ open(EXTRACT, "|sort >Tmp$$") # $$ is our process id
or die "Can't start sort: $!";
# in memory files
}
}
+See L<perliol/> for detailed info on PerlIO.
+
You may also, in the Bourne shell tradition, specify an EXPR beginning
-with C<< '>&' >>, in which case the rest of the string is interpreted as the
-name of a filehandle (or file descriptor, if numeric) to be
-duped and opened. You may use C<&> after C<< > >>, C<<< >> >>>,
-C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>. The
-mode you specify should match the mode of the original filehandle.
-(Duping a filehandle does not take into account any existing contents of
-IO buffers.) If you use the 3 arg form then you can pass either a number,
-the name of a filehandle or the normal "reference to a glob".
+with C<< '>&' >>, in which case the rest of the string is interpreted
+as the name of a filehandle (or file descriptor, if numeric) to be
+duped (as L<dup(2)>) and opened. You may use C<&> after C<< > >>,
+C<<< >> >>>, C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>.
+The mode you specify should match the mode of the original filehandle.
+(Duping a filehandle does not take into account any existing contents
+of IO buffers.) If you use the 3 arg form then you can pass either a
+number, the name of a filehandle or the normal "reference to a glob".
Here is a script that saves, redirects, and restores C<STDOUT> and
C<STDERR> using various methods:
print STDOUT "stdout 1\n"; # this works for
print STDERR "stderr 1\n"; # subprocesses too
- close STDOUT;
- close STDERR;
-
open STDOUT, ">&", $oldout or die "Can't dup \$oldout: $!";
open STDERR, ">&OLDERR" or die "Can't dup OLDERR: $!";
print STDOUT "stdout 2\n";
print STDERR "stderr 2\n";
-If you specify C<< '<&=N' >>, where C<N> is a number, then Perl will
-do an equivalent of C's C<fdopen> of that file descriptor; this is
-more parsimonious of file descriptors. For example:
+If you specify C<< '<&=X' >>, where C<X> is a file descriptor number
+or a filehandle, then Perl will do an equivalent of C's C<fdopen> of
+that file descriptor (and not call L<dup(2)>); this is more
+parsimonious of file descriptors. For example:
+ # open for input, reusing the fileno of $fd
open(FILEHANDLE, "<&=$fd")
or
open(FILEHANDLE, "<&=", $fd)
-Note that if Perl is using the standard C libraries' fdopen() then on
-many UNIX systems, fdopen() is known to fail when file descriptors
-exceed a certain value, typically 255. If you need more file
-descriptors than that, consider rebuilding Perl to use the C<PerlIO>.
+or
+
+ # open for append, using the fileno of OLDFH
+ open(FH, ">>&=", OLDFH)
+
+or
+
+ open(FH, ">>&=OLDFH")
+
+Being parsimonious on filehandles is also useful (besides being
+parsimonious) for example when something is dependent on file
+descriptors, like for example locking using flock(). If you do just
+C<< open(A, '>>&B') >>, the filehandle A will not have the same file
+descriptor as B, and therefore flock(A) will not flock(B), and vice
+versa. But with C<< open(A, '>>&=B') >> the filehandles will share
+the same file descriptor.
+
+Note that if you are using Perls older than 5.8.0, Perl will be using
+the standard C libraries' fdopen() to implement the "=" functionality.
+On many UNIX systems fdopen() fails when file descriptors exceed a
+certain value, typically 255. For Perls 5.8.0 and later, PerlIO is
+most often the default.
You can see whether Perl has been compiled with PerlIO or not by
running C<perl -V> and looking for C<useperlio=> line. If C<useperlio>
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
multi-threaded application. The C<unique> attribute does nothing in
all other environments.
+Warning: the current implementation of this attribute operates on the
+typeglob associated with the variable; this means that C<our $x : unique>
+also has the effect of C<our @x : unique; our %x : unique>. This may be
+subject to change.
+
=item pack TEMPLATE,LIST
Takes a LIST of values and converts it into a string using the rules
h A hex string (low nybble first).
H A hex string (high nybble first).
- c A signed char value.
+ c A signed char (8-bit) value.
C An unsigned char value. Only does bytes. See U for Unicode.
- s A signed short value.
+ s A signed short (16-bit) value.
S An unsigned short value.
- (This 'short' is _exactly_ 16 bits, which may differ from
- what a local C compiler calls 'short'. If you want
- native-length shorts, use the '!' suffix.)
- i A signed integer value.
- I An unsigned integer value.
- (This 'integer' is _at_least_ 32 bits wide. Its exact
- size depends on what a local C compiler calls 'int',
- and may even be larger than the 'long' described in
- the next item.)
-
- l A signed long value.
+ l A signed long (32-bit) value.
L An unsigned long value.
- (This 'long' is _exactly_ 32 bits, which may differ from
- what a local C compiler calls 'long'. If you want
- native-length longs, use the '!' suffix.)
-
- n An unsigned short in "network" (big-endian) order.
- N An unsigned long in "network" (big-endian) order.
- v An unsigned short in "VAX" (little-endian) order.
- V An unsigned long in "VAX" (little-endian) order.
- (These 'shorts' and 'longs' are _exactly_ 16 bits and
- _exactly_ 32 bits, respectively.)
q A signed quad (64-bit) value.
Q An unsigned quad value.
integer values _and_ if Perl has been compiled to support those.
Causes a fatal error otherwise.)
- j A signed integer value (a Perl internal integer, IV).
- J An unsigned integer value (a Perl internal unsigned integer, UV).
+ i A signed integer value.
+ I A unsigned integer value.
+ (This 'integer' is _at_least_ 32 bits wide. Its exact
+ size depends on what a local C compiler calls 'int'.)
+
+ n An unsigned short (16-bit) in "network" (big-endian) order.
+ N An unsigned long (32-bit) in "network" (big-endian) order.
+ v An unsigned short (16-bit) in "VAX" (little-endian) order.
+ V An unsigned long (32-bit) in "VAX" (little-endian) order.
+
+ j A Perl internal signed integer value (IV).
+ J A Perl internal unsigned integer value (UV).
f A single-precision float in the native format.
d A double-precision float in the native format.
- F A floating point value in the native native format
- (a Perl internal floating point value, NV).
+ F A Perl internal floating point value (NV) in the native format
D A long double-precision float in the native format.
(Long doubles are available only if your system supports long
double values _and_ if Perl has been compiled to support those.
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.
+Some letters in the TEMPLATE may optionally be followed by one or
+more of these modifiers (the second column lists the letters for
+which the modifier is valid):
+
+ ! sSlLiI Forces native (short, long, int) sizes instead
+ of fixed (16-/32-bit) sizes.
+
+ xX Make x and X act as alignment commands.
+
+ nNvV Treat integers as signed instead of unsigned.
+
+ > sSiIlLqQ Force big-endian byte-order on the type.
+ jJfFdDpP (The "big end" touches the construct.)
+
+ < sSiIlLqQ Force little-endian byte-order on the type.
+ jJfFdDpP (The "little end" touches the construct.)
+
+The C<E<gt>> and C<E<lt>> modifiers can also be used on C<()>-groups,
+in which case they force a certain byte-order on all components of
+that group, including subgroups.
+
The following rules apply:
=over 8
length. A NULL pointer is created if the corresponding value for C<p> or
C<P> is C<undef>, similarly for unpack().
+If your system has a strange pointer size (i.e. a pointer is neither as
+big as an int nor as big as a long), it may not be possible to pack or
+unpack pointers in big- or little-endian byte order. Attempting to do
+so will result in a fatal error.
+
=item *
The C</> template character allows packing and unpacking of strings where
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')
=item *
The integer types C<s>, C<S>, C<l>, and C<L> may be
-immediately followed by a C<!> suffix to signify native shorts or
+followed by a C<!> modifier to signify native shorts or
longs--as you can see from above for example a bare C<l> does mean
exactly 32 bits, the native C<long> (as seen by the local C compiler)
may be larger. This is an issue mainly in 64-bit platforms. You can
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 *
Byteorders C<'1234'> and C<'12345678'> are little-endian, C<'4321'>
and C<'87654321'> are big-endian.
-If you want portable packed integers use the formats C<n>, C<N>,
-C<v>, and C<V>, their byte endianness and size are known.
+If you want portable packed integers you can either use the formats
+C<n>, C<N>, C<v>, and C<V>, or you can use the C<E<gt>> and C<E<lt>>
+modifiers. These modifiers are only available as of perl 5.9.2.
See also L<perlport>.
=item *
+All integer and floating point formats as well as C<p> and C<P> and
+C<()>-groups may be followed by the C<E<gt>> or C<E<lt>> modifiers
+to force big- or little- endian byte-order, respectively.
+This is especially useful, since C<n>, C<N>, C<v> and C<V> don't cover
+signed integers, 64-bit integers and floating point values. However,
+there are some things to keep in mind.
+
+Exchanging signed integers between different platforms only works
+if all platforms store them in the same format. Most platforms store
+signed integers in two's complement, so usually this is not an issue.
+
+The C<E<gt>> or C<E<lt>> modifiers can only be used on floating point
+formats on big- or little-endian machines. Otherwise, attempting to
+do so will result in a fatal error.
+
+Forcing big- or little-endian byte-order on floating point values for
+data exchange can only work if all platforms are using the same
+binary representation (e.g. IEEE floating point format). Even if all
+platforms are using IEEE, there may be subtle differences. Being able
+to use C<E<gt>> or C<E<lt>> on floating point values can be very useful,
+but also very dangerous if you don't know exactly what you're doing.
+It is definetely not a general way to portably store floating point
+values.
+
+When using C<E<gt>> or C<E<lt>> on an C<()>-group, this will affect
+all types inside the group that accept the byte-order modifiers,
+including all subgroups. It will silently be ignored for all other
+types. You are not allowed to override the byte-order within a group
+that already has a byte-order modifier suffix.
+
+=item *
+
Real numbers (floats and doubles) are in the native machine format only;
due to the multiplicity of floating formats around, and the lack of a
standard "network" representation, no facility for interchange has been
arithmetic (as the endian-ness of the memory representation is not part
of the IEEE spec). See also L<perlport>.
-Note that Perl uses doubles internally for all numeric calculation, and
-converting from double into float and thence back to double again will
-lose precision (i.e., C<unpack("f", pack("f", $foo)>) will not in general
-equal $foo).
+If you know exactly what you're doing, you can use the C<E<gt>> or C<E<lt>>
+modifiers to force big- or little-endian byte-order on floating point values.
+
+Note that Perl uses doubles (or long doubles, if configured) internally for
+all numeric calculation, and converting from double into float and thence back
+to double again will lose precision (i.e., C<unpack("f", pack("f", $foo)>)
+will not in general equal $foo).
=item *
-If the pattern begins with a C<U>, the resulting string will be treated
-as Unicode-encoded. You can force UTF8 encoding on in a string with an
-initial C<U0>, and the bytes that follow will be interpreted as Unicode
-characters. If you don't want this to happen, you can begin your pattern
-with C<C0> (or anything else) to force Perl not to UTF8 encode your
-string, and then follow this with a C<U*> somewhere in your pattern.
+If the pattern begins with a C<U>, the resulting string will be
+treated as UTF-8-encoded Unicode. You can force UTF-8 encoding on in a
+string with an initial C<U0>, and the bytes that follow will be
+interpreted as Unicode characters. If you don't want this to happen,
+you can begin your pattern with C<C0> (or anything else) to force Perl
+not to UTF-8 encode your string, and then follow this with a C<U*>
+somewhere in your pattern.
=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 *
+C<n>, C<N>, C<v> and C<V> accept the C<!> modifier. In this case they
+will represent signed 16-/32-bit integers in big-/little-endian order.
+This is only portable if all platforms sharing the packed data use the
+same binary representation for signed integers (e.g. all platforms are
+using two's complement representation).
+
+=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
+modifiers and a repeat count must follow immediately.
=item *
# short 12, zero fill to position 4, long 34
# $foo eq $bar
+ $foo = pack('nN', 42, 4711);
+ # pack big-endian 16- and 32-bit unsigned integers
+ $foo = pack('S>L>', 42, 4711);
+ # exactly the same
+ $foo = pack('s<l<', -42, 4711);
+ # pack little-endian 16- and 32-bit signed integers
+ $foo = pack('(sl)<', -42, 4711);
+ # exactly the same
+
The same template may generally also be used in unpack().
=item package NAMESPACE
=item pos
Returns the offset of where the last C<m//g> search left off for the variable
-in question (C<$_> is used when the variable is not specified). May be
-modified to change that offset. Such modification will also influence
-the C<\G> zero-width assertion in regular expressions. See L<perlre> and
+in question (C<$_> is used when the variable is not specified). Note that
+0 is a valid match offset, while C<undef> indicates that the search position
+is reset (usually due to match failure, but can also be because no match has
+yet been performed on the scalar). C<pos> directly accesses the location used
+by the regexp engine to store the offset, so assigning to C<pos> will change
+that offset, and so will also influence the C<\G> zero-width assertion in
+regular expressions. Because a failed C<m//gc> match doesn't reset the offset,
+the return from C<pos> won't change either in this case. See L<perlre> and
L<perlop>.
=item print FILEHANDLE LIST
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
=item ref
-Returns a true value if EXPR is a reference, false otherwise. If EXPR
+Returns a non-empty string if EXPR is a reference, the empty
+string otherwise. If EXPR
is not specified, C<$_> will be used. The value returned depends on the
type of thing the reference is a reference to.
Builtin types include:
Otherwise, demands that a library file be included if it hasn't already
been included. The file is included via the do-FILE mechanism, which is
-essentially just a variety of C<eval>. Has semantics similar to the following
-subroutine:
+essentially just a variety of C<eval>. Has semantics similar to the
+following subroutine:
sub require {
- my($filename) = @_;
- return 1 if $INC{$filename};
- my($realfilename,$result);
- ITER: {
- foreach $prefix (@INC) {
- $realfilename = "$prefix/$filename";
- if (-f $realfilename) {
- $INC{$filename} = $realfilename;
- $result = do $realfilename;
- last ITER;
- }
- }
- die "Can't find $filename in \@INC";
- }
- delete $INC{$filename} if $@ || !$result;
- die $@ if $@;
- die "$filename did not return true value" unless $result;
- return $result;
+ my ($filename) = @_;
+ if (exists $INC{$filename}) {
+ return 1 if $INC{$filename};
+ die "Compilation failed in require";
+ }
+ my ($realfilename,$result);
+ ITER: {
+ foreach $prefix (@INC) {
+ $realfilename = "$prefix/$filename";
+ if (-f $realfilename) {
+ $INC{$filename} = $realfilename;
+ $result = do $realfilename;
+ last ITER;
+ }
+ }
+ die "Can't find $filename in \@INC";
+ }
+ if ($@) {
+ $INC{$filename} = undef;
+ die $@;
+ } elsif (!$result) {
+ delete $INC{$filename};
+ die "$filename did not return true value";
+ } else {
+ return $result;
+ }
}
Note that the file will not be included twice under the same specified
-name. The file must return true as the last statement to indicate
+name.
+
+The file must return true as the last statement to indicate
successful execution of any initialization code, so it's customary to
end such a file with C<1;> unless you're sure it'll return true
otherwise. But it's better just to put the C<1;>, in case you add more
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.
undef $/; # for efficiency of <>
print scalar reverse <>; # character tac, last line tsrif
+Used without arguments in scalar context, reverse() reverses C<$_>.
+
This operator is also handy for inverting a hash, although there are some
caveats. If a value is duplicated in the original hash, only one of those
can be represented as a key in the inverted hash. Also, this has to
=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///
select(undef, undef, undef, 0.25);
Note that whether C<select> gets restarted after signals (say, SIGALRM)
-is implementation-dependent.
+is implementation-dependent. See also L<perlport> for notes on the
+portability of C<select>.
B<WARNING>: One should not attempt to mix buffered I/O (like C<read>
or <FH>) with C<select>, except as permitted by POSIX, and even
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:
=item split
-Splits a string into a list of strings and returns that list. By default,
-empty leading fields are preserved, and empty trailing ones are deleted.
+Splits the string EXPR into a list of strings and returns that list. By
+default, empty leading fields are preserved, and empty trailing ones are
+deleted. (If all fields are empty, they are considered to be trailing.)
In scalar context, returns the number of fields found and splits into
the C<@_> array. Use of split in scalar context is deprecated, however,
($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.
= stat($filename);
Not all fields are supported on all filesystem types. Here are the
-meaning of the fields:
+meanings of the fields:
0 dev device number of filesystem
1 ino inode number
(The epoch was at 00:00 January 1, 1970 GMT.)
-(*) The ctime field is non-portable, in particular you cannot expect
-it to be a "creation time", see L<perlport/"Files and Filesystems">
-for details.
+(*) Not all fields are supported on all filesystem types. Notably, the
+ctime field is non-portable. In particular, you cannot expect it to be a
+"creation time", see L<perlport/"Files and Filesystems"> for details.
-If stat is passed the special filehandle consisting of an underline, no
+If C<stat> is passed the special filehandle consisting of an underline, no
stat is done, but the current contents of the stat structure from the
-last stat or filetest are returned. Example:
+last C<stat>, C<lstat>, or filetest are returned. Example:
if (-x $file && (($d) = stat(_)) && $d < 0) {
print "$file is executable NFS file\n";
$is_setgid = S_ISDIR($mode);
You could write the last two using the C<-u> and C<-d> operators.
-The commonly available S_IF* constants are
+The commonly available C<S_IF*> constants are
# Permissions: read, write, execute, for user, group, others.
S_IREAD S_IWRITE S_IEXEC
-and the S_IF* functions are
+and the C<S_IF*> functions are
S_IMODE($mode) the part of $mode containing the permission bits
and the setuid/setgid/sticky bits
which can be bit-anded with e.g. S_IFREG
or with the following functions
- # The operators -f, -d, -l, -b, -c, -p, and -s.
+ # The operators -f, -d, -l, -b, -c, -p, and -S.
S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)
S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)
S_ISENFMT($mode) S_ISWHT($mode)
See your native chmod(2) and stat(2) documentation for more details
-about the S_* constants. To get status info for a symbolic link
+about the C<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().
+Note that the lvalue returned by by the 3-arg version of substr() acts as
+a 'magic bullet'; each time it is assigned to, it remembers which part
+of the original string is being modified; for example:
+
+ $x = '1234';
+ for (substr($x,1,2)) {
+ $_ = 'a'; print $x,"\n"; # prints 1a4
+ $_ = 'xyz'; print $x,"\n"; # prints 1xyz4
+ $x = '56789';
+ $_ = 'pq'; print $x,"\n"; # prints 5pq9
+ }
+
+
+Prior to Perl version 5.9.1, the result of using an lvalue multiple times was
+unspecified.
+
=item symlink OLDFILE,NEWFILE
Creates a new filename symbolically linked to the old filename.
$symlink_exists = eval { symlink("",""); 1 };
-=item syscall LIST
+=item syscall NUMBER, LIST
Calls the system call specified as the first element of the list,
passing the remaining elements as arguments to the system call. If
Some of the most common values are C<O_RDONLY> for opening the file in
read-only mode, C<O_WRONLY> for opening the file in write-only mode,
-and C<O_RDWR> for opening the file in read-write mode, and.
+and C<O_RDWR> for opening the file in read-write mode.
For historical reasons, some values work on almost every system
supported by perl: zero means read-only, one means write-only, and two
In many systems the C<O_EXCL> flag is available for opening files in
exclusive mode. This is B<not> locking: exclusiveness means here that
-if the file already exists, sysopen() fails. The C<O_EXCL> wins
-C<O_TRUNC>.
+if the file already exists, sysopen() fails. C<O_EXCL> may not work
+on network filesystems, and has no effect unless the C<O_CREAT> flag
+is set as well. Setting C<O_CREAT|O_EXCL> prevents the file from
+being opened if it is a symbolic link. It does not protect against
+symbolic links in the file's path.
-Sometimes you may want to truncate an already-existing file: C<O_TRUNC>.
+Sometimes you may want to truncate an already-existing file. This
+can be done using the C<O_TRUNC> flag. The behavior of
+C<O_TRUNC> with C<O_RDONLY> is undefined.
You should seldom if ever use C<0644> as argument to C<sysopen>, because
that takes away the user's option to have a more permissive umask.
=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.
from the Fcntl module. Use of the constants is also more portable
than relying on 0, 1, and 2. For example to define a "systell" function:
- use Fnctl 'SEEK_CUR';
+ use Fcntl 'SEEK_CUR';
sub systell { sysseek($_[0], 0, SEEK_CUR) }
Returns the new position, or the undefined value on failure. A position
Like C<exec>, C<system> allows you to lie to a program about its name if
you use the C<system PROGRAM LIST> syntax. Again, see L</exec>.
-Because C<system> and backticks block C<SIGINT> and C<SIGQUIT>,
-killing the program they're running doesn't actually interrupt
-your program.
+Since C<SIGINT> and C<SIGQUIT> are ignored during the execution of
+C<system>, if you expect your program to terminate on receipt of these
+signals you will need to arrange to do so yourself based on the return
+value.
@args = ("command", "arg1", "arg2");
system(@args) == 0
You can check all the failure possibilities by inspecting
C<$?> like this:
- $exit_value = $? >> 8;
- $signal_num = $? & 127;
- $dumped_core = $? & 128;
+ if ($? == -1) {
+ print "failed to execute: $!\n";
+ }
+ elsif ($? & 127) {
+ printf "child died with signal %d, %s coredump\n",
+ ($? & 127), ($? & 128) ? 'with' : 'without';
+ }
+ else {
+ printf "child exited with value %d\n", $? >> 8;
+ }
or more portably by using the W*() calls of the POSIX extension;
see L<perlport> for more information.
=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
There is no C<systell> function. Use C<sysseek(FH, 0, 1)> for that.
-Do not use tell() on a filehandle that has been opened using
-sysopen(), use sysseek() for that as described above. Why? Because
-sysopen() creates unbuffered, "raw", filehandles, while open() creates
-buffered filehandles. sysseek() make sense only on the first kind,
-tell() only makes sense on the second kind.
+Do not use tell() (or other buffered I/O operations) on a file handle
+that has been manipulated by sysread(), syswrite() or sysseek().
+Those functions ignore the buffering, while tell() does not.
=item telldir DIRHANDLE
EXISTS this, key
FIRSTKEY this
NEXTKEY this, lastkey
+ SCALAR this
DESTROY this
UNTIE this
=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 Mac OS,
-and 00:00:00 UTC, January 1, 1970 for most other systems).
-Suitable for feeding to C<gmtime> and C<localtime>.
+considers to be the epoch, suitable for feeding to C<gmtime> and
+C<localtime>. On most systems the epoch is 00:00:00 UTC, January 1, 1970;
+a prominent exception being Mac OS Classic which uses 00:00:00, January 1,
+1904 in the current local time zone for its epoch.
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.
C<import> method any way it likes, though most modules just choose to
derive their C<import> method via inheritance from the C<Exporter> class that
is defined in the C<Exporter> module. See L<Exporter>. If no C<import>
-method can be found then the call is skipped.
+method can be found then the call is skipped, even if there is an AUTOLOAD
+method.
If you do not want to call the package's C<import> method (for instance,
to stop your namespace from being altered), explicitly supply the empty list:
There's a corresponding C<no> command that unimports meanings imported
by C<use>, i.e., it calls C<unimport Module LIST> instead of C<import>.
+It behaves exactly as C<import> does with respect to VERSION, an
+omitted LIST, empty LIST, or no unimport method being found.
no integer;
no strict 'refs';
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> and belong to
+the user running the program:
#!/usr/bin/perl
- $now = time;
- utime $now, $now, @ARGV;
+ $atime = $mtime = time;
+ utime $atime, $mtime, @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.)
+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) and will even work on other users' files where you have write
+permission:
utime undef, undef, @ARGV;
+Under NFS this will use 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. The Unix
+touch(1) command will in fact normally use this form instead of the
+one shown in the first example.
+
+Note that only passing one of the first two elements as C<undef> will
+be equivalent of passing it as 0 and will not have the same effect as
+described when they are both C<undef>. This case will also trigger an
+uninitialized warning.
+
=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>. (In particular, calling values() in void context resets
+the iterator with no other overhead.)
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
to try to write off the beginning of the string (i.e. negative OFFSET).
The string should not contain any character with the value > 255 (which
-can only happen if you're using UTF8 encoding). If it does, it will be
-treated as something which is not UTF8 encoded. When the C<vec> was
+can only happen if you're using UTF-8 encoding). If it does, it will be
+treated as something which is not UTF-8 encoded. When the C<vec> was
assigned to, other parts of your program will also no longer consider the
-string to be UTF8 encoded. In other words, if you do have such characters
+string to be UTF-8 encoded. In other words, if you do have such characters
in your string, vec() will operate on the actual byte string, and not the
conceptual character string.
=item wantarray
-Returns true if the context of the currently executing subroutine is
-looking for a list value. Returns false if the context is looking
-for a scalar. Returns the undefined value if the context is looking
-for no value (void context).
+Returns true if the context of the currently executing subroutine or
+eval() block is looking for a list value. Returns false if the context is
+looking for a scalar. Returns the undefined value if the context is
+looking for no value (void context).
return unless defined wantarray; # don't bother doing more
my @a = complex_calculation();
https://perl5.git.perl.org / perl5.git / blobdiff