C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
-C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<umask>,
-C<unlink>, C<utime>
+C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<sysopen>,
+C<umask>, C<unlink>, C<utime>
=item Keywords related to the control flow of your perl program
C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
-C<sockatmark>, C<socket>, C<socketpair>
+C<socket>, C<socketpair>
=item System V interprocess communication functions
C<semget>, C<semop>, C<setgrent>, C<sethostent>, C<setnetent>,
C<setpgrp>, C<setpriority>, C<setprotoent>, C<setpwent>,
C<setservent>, C<setsockopt>, C<shmctl>, C<shmget>, C<shmread>,
-C<shmwrite>, C<sockatmark>, C<socket>, C<socketpair>,
+C<shmwrite>, C<socket>, C<socketpair>,
C<stat>, C<symlink>, C<syscall>, C<sysopen>, C<system>,
C<times>, C<truncate>, C<umask>, C<unlink>,
C<utime>, C<wait>, C<waitpid>
-T File is an ASCII text file (heuristic guess).
-B File is a "binary" file (opposite of -T).
- -M Age of file in days when script started.
+ -M Script start time minus file modification time, in days.
-A Same for access time.
- -C Same for inode change time.
+ -C Same for inode change time (Unix, may differ for other platforms)
Example:
Arranges for FILEHANDLE to be read or written in "binary" or "text" mode
on systems where the run-time libraries distinguish between binary and
text files. If FILEHANDLE is an expression, the value is taken as the
-name of the filehandle. DISCIPLINE can be either of C<:raw> for
-binary mode or C<:crlf> for "text" mode. If the DISCIPLINE is
-omitted, it defaults to C<:raw>. Returns true on success, C<undef> on
-failure. The C<:raw> are C<:clrf>, and any other directives of the
-form C<:...>, are called I/O I<disciplines>.
+name of the filehandle.
-The C<open> pragma can be used to establish default I/O disciplines.
-See L<open>.
+DISCIPLINE can be either of C<:raw> for binary mode or C<:crlf> for
+"text" mode. If the DISCIPLINE is omitted, it defaults to C<:raw>.
+Returns true on success, C<undef> on failure. To mark FILEHANDLE as
+UTF-8, use C<:utf8>, and to mark it as bytes, use C<:bytes>.
+
+The C<:raw> are C<:clrf>, and any other directives of the form
+C<:...>, are called I/O I<disciplines>. The C<open> pragma can be
+used to establish default I/O disciplines. See L<open>.
In general, binmode() should be called after open() but before any I/O
is done on the filehandle. Calling binmode() will flush any possibly
C<require> or C<use> statement, $evaltext contains the text of the
C<eval EXPR> statement. In particular, for an C<eval BLOCK> statement,
$filename is C<(eval)>, but $evaltext is undefined. (Note also that
-each C<use> statement creates a C<require> frame inside an C<eval EXPR>)
-frame. C<$hasargs> is true if a new instance of C<@_> was set up for the
-frame. C<$hints> and C<$bitmask> contain pragmatic hints that the caller
-was compiled with. The C<$hints> and C<$bitmask> values are subject to
-change between versions of Perl, and are not meant for external use.
+each C<use> statement creates a C<require> frame inside an C<eval EXPR>
+frame.) $subroutine may also be C<(unknown)> if this particular
+subroutine happens to have been deleted from the symbol table.
+C<$hasargs> is true if a new instance of C<@_> was set up for the frame.
+C<$hints> and C<$bitmask> contain pragmatic hints that the caller was
+compiled with. The C<$hints> and C<$bitmask> values are subject to change
+between versions of Perl, and are not meant for external use.
Furthermore, when called from within the DB package, caller returns more
detailed information: it sets the list variable C<@DB::args> to be the
die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
-If the value of EXPR does not end in a newline, the current script line
-number and input line number (if any) are also printed, and a newline
-is supplied. Note that the "input line number" (also known as "chunk")
-is subject to whatever notion of "line" happens to be currently in
-effect, and is also available as the special variable C<$.>.
-See L<perlvar/"$/"> and L<perlvar/"$.">.
+If the last element of LIST does not end in a newline, the current
+script line number and input line number (if any) are also printed,
+and a newline is supplied. Note that the "input line number" (also
+known as "chunk") is subject to whatever notion of "line" happens to
+be currently in effect, and is also available as the special variable
+C<$.>. See L<perlvar/"$/"> and L<perlvar/"$.">.
-Hint: sometimes appending C<", stopped"> to your message
-will cause it to make better sense when the string C<"at foo line 123"> is
-appended. Suppose you are running script "canasta".
+Hint: sometimes appending C<", stopped"> to your message will cause it
+to make better sense when the string C<"at foo line 123"> is appended.
+Suppose you are running script "canasta".
die "/etc/games is no good";
die "/etc/games is no good, stopped";
C<< <> >> operator. Since C<< <> >> isn't explicitly opened,
as a normal filehandle is, an C<eof()> before C<< <> >> has been
used will cause C<@ARGV> to be examined to determine if input is
-available.
+available. Similarly, an C<eof()> after C<< <> >> has returned
+end-of-file will assume you are processing another C<@ARGV> list,
+and if you haven't set C<@ARGV>, will read input from C<STDIN>;
+see L<perlop/"I/O Operators">.
In a C<< while (<>) >> loop, C<eof> or C<eof(ARGV)> can be used to
detect the end of each file, C<eof()> will only detect the end of the
See also L</continue> for an illustration of how C<last>, C<next>, and
C<redo> work.
+=item no Module VERSION LIST
+
+=item no Module VERSION
+
=item no Module LIST
+=item no Module
+
See the L</use> function, which C<no> is the opposite of.
=item oct EXPR
File handles can be opened to "in memory" files held in Perl scalars via:
- open($fh,'>', \$variable) || ..
+ open($fh, '>', \$variable) || ..
+
+Though if you try to re-open C<STDOUT> or C<STDERR> as an "in memory"
+file, you have to close it first:
+
+ close STDOUT;
+ open STDOUT, '>', \$variable or die "Can't open STDOUT: $!";
Examples:
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 STDOUT and
-STDERR:
+Here is a script that saves, redirects, and restores C<STDOUT> and
+C<STDERR> using various methods:
#!/usr/bin/perl
- open(my $oldout, ">&", \*STDOUT);
- open(OLDERR, ">&STDERR");
-
- open(STDOUT, '>', "foo.out") || die "Can't redirect stdout";
- open(STDERR, ">&STDOUT") || die "Can't dup stdout";
+ open my $oldout, ">&STDOUT" or die "Can't dup STDOUT: $!";
+ open OLDERR, ">&", \*STDERR or die "Can't dup STDERR: $!";
+
+ open STDOUT, '>', "foo.out" or die "Can't redirect STDOUT: $!";
+ open STDERR, ">&STDOUT" or die "Can't dup STDOUT: $!";
- select(STDERR); $| = 1; # make unbuffered
- select(STDOUT); $| = 1; # make unbuffered
+ select STDERR; $| = 1; # make unbuffered
+ select STDOUT; $| = 1; # make unbuffered
print STDOUT "stdout 1\n"; # this works for
print STDERR "stderr 1\n"; # subprocesses too
- close(STDOUT);
- close(STDERR);
+ close STDOUT;
+ close STDERR;
- open(STDOUT, ">&OLDOUT");
- open(STDERR, ">&OLDERR");
+ 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";
like its machine-level representation. For example, on 32-bit machines
a converted integer may be represented by a sequence of 4 bytes.
-The TEMPLATE is a
-sequence of characters that give the order and type of values, as
-follows:
+The TEMPLATE is a sequence of characters that give the order and type
+of values, as follows:
a A string with arbitrary binary data, will be null padded.
A A text (ASCII) string, will be space padded.
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).
+
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).
+ 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.
+ Causes a fatal error otherwise.)
+
p A pointer to a null-terminated string.
P A pointer to a structure (fixed-length string).
x A null byte.
X Back up a byte.
@ Null fill to absolute position.
+ ( Start of a ()-group.
The following rules apply:
Each letter may optionally be followed by a number giving a repeat
count. With all types except C<a>, C<A>, C<Z>, C<b>, C<B>, C<h>,
-C<H>, and C<P> the pack function will gobble up that many values from
-the LIST. A C<*> for the repeat count means to use however many items are
-left, except for C<@>, C<x>, C<X>, where it is equivalent
-to C<0>, and C<u>, where it is equivalent to 1 (or 45, what is the
-same).
+C<H>, C<@>, C<x>, C<X> and C<P> the pack function will gobble up that
+many values from the LIST. A C<*> for the repeat count means to use
+however many items are left, except for C<@>, C<x>, C<X>, where it is
+equivalent to C<0>, and C<u>, where it is equivalent to 1 (or 45, what
+is the same). A numeric repeat count may optionally be enclosed in
+brackets, as in C<pack 'C[80]', @arr>.
+
+One can replace the numeric repeat count by a template enclosed in brackets;
+then the packed length of this template in bytes is used as a count.
+For example, C<x[L]> skips a long (it skips the number of bytes in a long);
+the template C<$t X[$t] $t> unpack()s twice what $t unpacks.
+If the template in brackets contains alignment commands (such as C<x![d]>),
+its packed length is calculated as if the start of the template has the maximal
+possible alignment.
When used with C<Z>, C<*> results in the addition of a trailing null
byte (so the packed result will be one longer than the byte C<length>
the packed structure contains a byte count followed by the string itself.
You write I<length-item>C</>I<string-item>.
-The I<length-item> can be any C<pack> template letter,
-and describes how the length value is packed.
-The ones likely to be of most use are integer-packing ones like
-C<n> (for Java strings), C<w> (for ASN.1 or SNMP)
-and C<N> (for Sun XDR).
+The I<length-item> can be any C<pack> template letter, and describes
+how the length value is packed. The ones likely to be of most use are
+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>,
=item *
-The integer formats C<s>, C<S>, C<i>, C<I>, C<l>, and C<L>
+The integer formats C<s>, C<S>, C<i>, C<I>, C<l>, C<L>, C<j>, and C<J>
are inherently non-portable between processors and operating systems
because they obey the native byteorder and endianness. For example a
4-byte integer 0x12345678 (305419896 decimal) would be ordered natively
=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.
+
+=item *
+
+C<x> and C<X> accept C<!> modifier. In this case they act as
+alignment commands: they jump forward/back to the closest position
+aligned at a multiple of C<count> bytes. For example, to pack() or
+unpack() C's C<struct {char c; double d; char cc[2]}> one may need to
+use the template C<C x![d] d C[2]>; this assumes that doubles must be
+aligned on the double's size.
+
+For alignment commands C<count> of 0 is equivalent to C<count> of 1;
+both result in no-ops.
+
+=item *
+
A comment in a TEMPLATE starts with C<#> and goes to the end of line.
=item *
See also the POSIX module's C<pause> function.
-=item sockatmark SOCKET
-
-Returns true if the socket is positioned at the out-of-band mark
-(also known as the urgent data mark), false otherwise. Use right
-after reading from the socket.
-
-Not available directly, one has to import the function from
-the IO::Socket extension
-
- use IO::Socket 'sockatmark';
-
-Even this doesn't guarantee that sockatmark() really is available,
-though, because sockatmark() is a relatively recent addition to
-the family of socket functions. If it is unavailable, attempt to
-use it will fail
-
- IO::Socket::atmark not implemented on this architecture ...
-
-See also L<IO::Socket>.
-
=item socket SOCKET,DOMAIN,TYPE,PROTOCOL
Opens a socket of the specified kind and attaches it to filehandle
use sort 'stable';
@new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
- # force use of quicksort (not portable outside Perl 5.8)
- use sort '_quicksort'; # note discouraging _
- @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
-
- # similar to the previous example, but demand stability as well
- use sort qw( _mergesort stable );
+ # force use of mergesort (not portable outside Perl 5.8)
+ use sort '_mergesort'; # note discouraging _
@new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
If you're using strict, you I<must not> declare $a
removed. The array grows or shrinks as necessary.
If OFFSET is negative then it starts that far from the end of the array.
If LENGTH is omitted, removes everything from OFFSET onward.
-If LENGTH is negative, leaves that many elements off the end of the array.
-If both OFFSET and LENGTH are omitted, removes everything.
+If LENGTH is negative, removes the elements from OFFSET onward
+except for -LENGTH elements at the end of the array.
+If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is
+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>):
on your system. Returns true if successful, the undefined value
otherwise.
+The behavior is undefined if LENGTH is greater than the length of the
+file.
+
=item uc EXPR
=item uc