access setitimer(2) if your system supports it. The Time::HiRes module
from CPAN may also prove useful.
-It is usually a mistake to intermix C<alarm>
-and C<sleep> calls.
+It is usually a mistake to intermix C<alarm> and C<sleep> calls.
+(C<sleep> may be internally implemented in your system with C<alarm>)
If you want to use C<alarm> to time out a system call you need to use an
C<eval>/C<die> pair. You can't rely on the alarm causing the system call to
$rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
-See L</split>.
+Beware that unlike C<split>, C<join> doesn't take a pattern as its
+first argument. Compare L</split>.
=item keys HASH
$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, and the
-strftime(3) and mktime(3) function 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:
+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) function 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", localtime;
=item my EXPR
+=item my EXPR : ATTRIBUTES
+
A C<my> declares the listed variables to be local (lexically) to the
enclosing block, file, or C<eval>. If
more than one value is listed, the list must be placed in parentheses. See
automatically convert strings into numbers as needed, this automatic
conversion assumes base 10.)
+=item open FILEHANDLE,MODE,EXPR
+
=item open FILEHANDLE,EXPR
=item open FILEHANDLE
to open.) See L<perlopentut> for a kinder, gentler explanation of opening
files.
-If the filename begins with C<'E<lt>'> or nothing, the file is opened for input.
-If the filename begins with C<'E<gt>'>, the file is truncated and opened for
-output, being created if necessary. If the filename begins with C<'E<gt>E<gt>'>,
+If MODE is C<'E<lt>'> or nothing, the file is opened for input.
+If MODE is C<'E<gt>'>, the file is truncated and opened for
+output, being created if necessary. If MODE is C<'E<gt>E<gt>'>,
the file is opened for appending, again being created if necessary.
You can put a C<'+'> in front of the C<'E<gt>'> or C<'E<lt>'> to indicate that
you want both read and write access to the file; thus C<'+E<lt>'> is almost
switch in L<perlrun> for a better approach. The file is created with
permissions of C<0666> modified by the process' C<umask> value.
-The prefix and the filename may be separated with spaces.
These various prefixes correspond to the fopen(3) modes of C<'r'>, C<'r+'>, C<'w'>,
C<'w+'>, C<'a'>, and C<'a+'>.
+In the 2-arguments (and 1-argument) form of the call the mode and
+filename should be concatenated (in this order), possibly separated by
+spaces. It is possible to omit the mode if the mode is C<'E<lt>'>.
+
If the filename begins with C<'|'>, the filename is interpreted as a
command to which output is to be piped, and if the filename ends with a
C<'|'>, the filename is interpreted as a command which pipes output to
that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>,
and L<perlipc/"Bidirectional Communication"> for alternatives.)
-Opening C<'-'> opens STDIN and opening C<'E<gt>-'> opens STDOUT. Open returns
+If MODE is C<'|-'>, the filename is interpreted as a
+command to which output is to be piped, and if MODE is
+C<'-|'>, the filename is interpreted as a command which pipes output to
+us. In the 2-arguments (and 1-argument) form one should replace dash
+(C<'-'>) with the command. See L<perlipc/"Using open() for IPC">
+for more examples of this. (You are not allowed to C<open> to a command
+that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>,
+and L<perlipc/"Bidirectional Communication"> for alternatives.)
+
+In the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN
+and opening C<'E<gt>-'> opens STDOUT.
+
+Open returns
nonzero upon success, the undefined value otherwise. If the C<open>
involved a pipe, the return value happens to be the pid of the
subprocess.
open ARTICLE or die "Can't find article $ARTICLE: $!\n";
while (<ARTICLE>) {...
- open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
+ open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
# if the open fails, output is discarded
- open(DBASE, '+<dbase.mine') # open for update
+ open(DBASE, '+<', 'dbase.mine') # open for update
or die "Can't open 'dbase.mine' for update: $!";
- open(ARTICLE, "caesar <$article |") # decrypt article
+ open(DBASE, '+<dbase.mine') # ditto
+ or die "Can't open 'dbase.mine' for update: $!";
+
+ open(ARTICLE, '-|', "caesar <$article") # decrypt article
+ or die "Can't start caesar: $!";
+
+ open(ARTICLE, "caesar <$article |") # ditto
or die "Can't start caesar: $!";
- open(EXTRACT, "|sort >/tmp/Tmp$$") # $$ is our process id
+ open(EXTRACT, "|sort >/tmp/Tmp$$") # $$ is our process id
or die "Can't start sort: $!";
# process argument list of files along with any includes
You may also, in the Bourne shell tradition, specify an EXPR beginning
with C<'E<gt>&'>, 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<E<gt>>, C<E<gt>E<gt>>, C<E<lt>>, C<+E<gt>>,
-C<+E<gt>E<gt>>, and C<+E<lt>>. The
+duped and opened. You may use C<&> after C<E<gt>>, C<E<gt>E<gt>>,
+C<E<lt>>, C<+E<gt>>, C<+E<gt>E<gt>>, and C<+E<lt>>. The
mode you specify should match the mode of the original filehandle.
(Duping a filehandle does not take into account any existing contents of
-stdio buffers.)
+stdio buffers.) Duping file handles is not yet supported for 3-argument
+open().
+
Here is a script that saves, redirects, and restores STDOUT and
STDERR:
open(OLDOUT, ">&STDOUT");
open(OLDERR, ">&STDERR");
- open(STDOUT, ">foo.out") || die "Can't redirect stdout";
- open(STDERR, ">&STDOUT") || die "Can't dup stdout";
+ open(STDOUT, '>', "foo.out") || die "Can't redirect stdout";
+ open(STDERR, ">&STDOUT") || die "Can't dup stdout";
select(STDERR); $| = 1; # make unbuffered
select(STDOUT); $| = 1; # make unbuffered
open(FILEHANDLE, "<&=$fd")
-If you open a pipe on the command C<'-'>, i.e., either C<'|-'> or C<'-|'>, then
+If you open a pipe on the command C<'-'>, i.e., either C<'|-'> or C<'-|'>
+with 2-arguments (or 1-argument) form of open(), then
there is an implicit fork done, and the return value of open is the pid
of the child within the parent process, and C<0> within the child
process. (Use C<defined($pid)> to determine whether the open was successful.)
piped open when you want to exercise more control over just how the
pipe command gets executed, such as when you are running setuid, and
don't want to have to scan shell commands for metacharacters.
-The following pairs are more or less equivalent:
+The following triples are more or less equivalent:
open(FOO, "|tr '[a-z]' '[A-Z]'");
- open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]';
+ open(FOO, '|-', "tr '[a-z]' '[A-Z]'");
+ open(FOO, '|-') || exec 'tr', '[a-z]', '[A-Z]';
open(FOO, "cat -n '$file'|");
- open(FOO, "-|") || exec 'cat', '-n', $file;
+ open(FOO, '-|', "cat -n '$file'");
+ open(FOO, '-|') || exec 'cat', '-n', $file;
See L<perlipc/"Safe Pipe Opens"> for more examples of this.
Closing any piped filehandle causes the parent process to wait for the
child to finish, and returns the status value in C<$?>.
-The filename passed to open will have leading and trailing
+The filename passed to 2-argument (or 1-argument) form of open()
+will have leading and trailing
whitespace deleted, and the normal redirection characters
honored. This property, known as "magic open",
can often be used to good effect. A user could specify a filename of
$filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
open(FH, $filename) or die "Can't open $filename: $!";
-However, to open a file with arbitrary weird characters in it, it's
-necessary to protect any leading and trailing whitespace:
+Use 3-argument form to open a file with arbitrary weird characters in it,
+
+ open(FOO, '<', $file);
+
+otherwise it's necessary to protect any leading and trailing whitespace:
$file =~ s#^(\s)#./$1#;
open(FOO, "< $file\0");
+(this may not work on some bizzare filesystems). One should
+conscientiously choose between the the I<magic> and 3-arguments form
+of open():
+
+ open IN, $ARGV[0];
+
+will allow the user to specify an argument of the form C<"rsh cat file |">,
+but will not work on a filename which happens to have a trailing space, while
+
+ open IN, '<', $ARGV[0];
+
+will have exactly the opposite restrictions.
+
If you want a "real" C C<open> (see L<open(2)> on your system), then you
-should use the C<sysopen> function, which involves no such magic. This is
+should use the C<sysopen> function, which involves no such magic (but
+may use subtly different filemodes than Perl open(), which is mapped
+to C fopen()). This is
another way to protect your filenames from interpretation. For example:
use IO::Handle;
s A signed short value.
S An unsigned short value.
(This 'short' is _exactly_ 16 bits, which may differ from
- what a local C compiler calls 'short'.)
+ 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.
l A signed long value.
L An unsigned long value.
(This 'long' is _exactly_ 32 bits, which may differ from
- what a local C compiler calls 'long'.)
+ what a local C compiler calls 'long'. If you want
+ native-length longs, use the '!' suffix.)
n A short in "network" (big-endian) order.
N A long in "network" (big-endian) order.
q A signed quad (64-bit) value.
Q An unsigned quad value.
- (Available only if your system supports 64-bit integer values
- _and_ if Perl has been compiled to support those.
+ (Quads are available only if your system supports 64-bit
+ integer values _and_ if Perl has been compiled to support those.
Causes a fatal error otherwise.)
f A single-precision float in the native format.
=item *
-The C<"h"> and C<"H"> fields pack a string that many nybbles long.
+The C<"h"> and C<"H"> fields pack a string that many nybbles (4-bit groups,
+representable as hexadecimal digits, 0-9a-f) long.
=item *
=item *
The integer types C<"s">, C<"S">, C<"l">, and C<"L"> may be
-immediately followed by a C<"!"> 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 see
-whether using C<"!"> makes any difference by
+immediately followed by a C<"!"> suffix 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
+see whether using C<"!"> makes any difference by
print length(pack("s")), " ", length(pack("s!")), "\n";
print length(pack("l")), " ", length(pack("l!")), "\n";
C<"i!"> and C<"I!"> also work but only because of completeness;
they are identical to C<"i"> and C<"I">.
-The actual sizes (in bytes) of native shorts, ints, and longs on
-the platform where Perl was built are also available via L<Config>:
-
The actual sizes (in bytes) of native shorts, ints, longs, and long
longs on the platform where Perl was built are also available via
L<Config>:
print $Config{longsize}, "\n";
print $Config{longlongsize}, "\n";
+(The C<$Config{longlongsize}> will be empty if your system does
+not support long longs.)
+
=item *
The integer formats C<"s">, C<"S">, C<"i">, C<"I">, C<"l">, and C<"L">
If you want portable packed integers use the formats C<"n">, C<"N">,
C<"v">, and C<"V">, their byte endianness and size is known.
+See also L<perlport>.
=item *
made. This means that packed floating point data written on one machine
may not be readable on another - even if both use IEEE floating point
arithmetic (as the endian-ness of the memory representation is not part
-of the IEEE spec).
+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).
+=item *
+
+You must yourself do any alignment or padding by inserting for example
+enough C<'x'>es while packing. There is no way to pack() and unpack()
+could know where the bytes are going to or coming from. Therefore
+C<pack> (and C<unpack>) handle their output and input as flat
+sequences of bytes.
+
=back
Examples:
$foo = pack("ccxxcc",65,66,67,68);
# foo eq "AB\0\0CD"
+ # note: the above examples featuring "C" and "c" are true
+ # only on ASCII and ASCII-derived systems such as ISO Latin 1
+ # and UTF-8. In EBCDIC the first example would be
+ # $foo = pack("CCCC",193,194,195,196);
+
$foo = pack("s2",1,2);
# "\1\0\2\0" on little-endian
# "\0\1\0\2" on big-endian
unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
}
+ $foo = pack('sx2l', 12, 34);
+ # short 12, two zero bytes padding, long 34
+ $bar = pack('s@4l', 12, 34);
+ # short 12, zero fill to position 4, long 34
+ # $foo eq $bar
+
The same template may generally also be used in unpack().
=item package
Sets FILEHANDLE's position, just like the C<fseek> call of C<stdio>.
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 it to the current position plus POSITION, and C<2> to
-set it to EOF plus POSITION (typically negative). For WHENCE you may
-use the constants C<SEEK_SET>, C<SEEK_CUR>, and C<SEEK_END> from either the
-C<IO::Seekable> or the POSIX module. Returns C<1> upon success, C<0> otherwise.
+POSITION, C<1> to set it to the current position plus POSITION, and
+C<2> to set it to EOF plus POSITION (typically negative). For WHENCE
+you may use the constants C<SEEK_SET>, C<SEEK_CUR>, and C<SEEK_END>
+(start of the file, current position, end of the file) from any of the
+modules Fcntl, C<IO::Seekable>, or POSIX. Returns C<1> upon success,
+C<0> otherwise.
If you want to position file for C<sysread> or C<syswrite>, don't use
C<seek>--buffering makes its effect on the file's system position
busy multitasking system.
For delays of finer granularity than one second, you may use Perl's
-C<syscall> interface to access setitimer(2) if your system supports it,
-or else see L</select> above.
+C<syscall> interface to access setitimer(2) if your system supports
+it, or else see L</select> above. The Time::HiRes module from CPAN
+may also help.
See also the POSIX module's C<sigpause> function.
for integer
l interpret integer as C type "long" or "unsigned long"
h interpret integer as C type "short" or "unsigned short"
+ If no flags, interpret integer as C type "int" or "unsigned"
There is also one Perl-specific flag:
point in formatted real numbers is affected by the LC_NUMERIC locale.
See L<perllocale>.
+If Perl understands "quads" (64-bit integers) (this requires
+either that the platform natively supports quads or that Perl
+has been specifically compiled to support quads), the characters
+
+ d u o x X b i D U O
+
+print quads, and they may optionally be preceded by
+
+ ll L q
+
+For example
+
+ %lld %16LX %qo
+
+You can find out whether your Perl supports quads via L<Config>:
+
+ use Config;
+ ($Config{use64bits} eq 'define' || $Config{longsize} == 8) &&
+ print "quads\n";
+
+If Perl understands "long doubles" (this requires that the platform
+supports long doubles), the flags
+
+ e f g E F G
+
+may optionally be preceded by
+
+ ll L
+
+For example
+
+ %llf %Lg
+
+You can find out whether your Perl supports long doubles via L<Config>:
+
+ use Config;
+ $Config{d_longdbl} eq 'define' && print "long doubles\n";
+
=item sqrt EXPR
=item sqrt
=item sub NAME BLOCK
This is subroutine definition, not a real function I<per se>. With just a
-NAME (and possibly prototypes), it's just a forward declaration. Without
-a NAME, it's an anonymous function declaration, and does actually return a
-value: the CODE ref of the closure you just created. See L<perlsub> and
-L<perlref> for details.
+NAME (and possibly prototypes or attributes), it's just a forward declaration.
+Without a NAME, it's an anonymous function declaration, and does actually
+return a value: the CODE ref of the closure you just created. See L<perlsub>
+and L<perlref> for details.
=item substr EXPR,OFFSET,LENGTH,REPLACEMENT
The possible values and flag bits of the MODE parameter are
system-dependent; they are available via the standard module C<Fcntl>.
+See the documentation of your operating system's C<open> to see which
+values and flag bits are available. You may combine several flags
+using the C<|>-operator.
+
+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.
+
For historical reasons, some values work on almost every system
supported by perl: zero means read-only, one means write-only, and two
means read/write. We know that these values do I<not> work under
OS/390 & VM/ESA Unix and on the Macintosh; you probably don't want to
-use them in new code.
+se them in new code, use thhe constants discussed in the preceding
+paragraph.
If the file named by FILENAME does not exist and the C<open> call creates
it (typically because MODE includes the C<O_CREAT> flag), then the value of
These permission values need to be in octal, and are modified by your
process's current C<umask>.
+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>.
+
+Sometimes you may want to truncate an already-existing file: C<O_TRUNC>.
+
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.
Better to omit it. See the perlfunc(1) entry on C<umask> for more
Sets FILEHANDLE's system position using the system call lseek(2). It
bypasses stdio, so mixing this with reads (other than C<sysread>),
-C<print>, C<write>, C<seek>, C<tell>, or C<eof> may cause
-confusion. 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
-POSITION, and C<2> to set it to EOF plus POSITION (typically negative).
-For WHENCE, you may use the constants C<SEEK_SET>, C<SEEK_CUR>, and
-C<SEEK_END> from either the C<IO::Seekable> or the POSIX module.
+C<print>, C<write>, C<seek>, C<tell>, or C<eof> may cause confusion.
+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 POSITION,
+and C<2> to set it to EOF plus POSITION (typically negative). For
+WHENCE, you may also use the constants C<SEEK_SET>, C<SEEK_CUR>, and
+C<SEEK_END> (start of the file, current position, end of the file)
+from any of the modules Fcntl, C<IO::Seekable>, or POSIX.
Returns the new position, or the undefined value on failure. A position
of zero is returned as the string C<"0 but true">; thus C<sysseek> returns
and 00:00:00 UTC, January 1, 1970 for most other systems).
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.
+
=item times
Returns a four-element list giving the user and system times, in
corresponds to a valid memory location, passing a pointer value that's
not known to be valid is likely to have disastrous consequences.
-See L</pack> for more examples.
+See L</pack> for more examples and notes.
=item untie VARIABLE
use integer;
use diagnostics;
- use sigtrap qw(SEGV BUS);
- use strict qw(subs vars refs);
- use subs qw(afunc blurfl);
- use warning qw(all);
+ use sigtrap qw(SEGV BUS);
+ use strict qw(subs vars refs);
+ use subs qw(afunc blurfl);
+ use warnings qw(all);
Some of these pseudo-modules import semantics into the current
block scope (like C<strict> or C<integer>, unlike ordinary modules,
no integer;
no strict 'refs';
- no warning;
+ no warnings;
If no C<unimport> method can be found the call fails with a fatal error.
=item vec EXPR,OFFSET,BITS
Treats the string in EXPR as a vector of unsigned integers, and
-returns the value of the bit field specified by OFFSET. BITS specifies
-the number of bits that are reserved for each entry in the bit
-vector. This must be a power of two from 1 to 32. C<vec> may also be
-assigned to, in which case parentheses are needed to give the expression
-the correct precedence as in
+returns the value of the bit field specified by OFFSET. BITS
+specifies the number of bits that are reserved for each entry in the
+bit vector. This must be a power of two from 1 to 32 (or 64, if your
+platform supports that).
+
+C<vec> may also be assigned to, in which case parentheses are needed
+to give the expression the correct precedence as in
vec($image, $max_x * $x + $y, 8) = 3;
Vectors created with C<vec> can also be manipulated with the logical
-operators C<|>, C<&>, and C<^>, which will assume a bit vector operation is
-desired when both operands are strings. See L<perlop/"Bitwise String Operators">.
+operators C<|>, C<&>, and C<^>, which will assume a bit vector
+operation is desired when both operands are strings.
+See L<perlop/"Bitwise String Operators">.
The following code will build up an ASCII string saying C<'PerlPerlPerl'>.
The comments show the string after each step. Note that this code works