Perl Cd Bookshelf [Electronic resources] نسخه متنی

29.2. Perl Functions in Alphabetical Order

Many of the following function names are annotated with, um, annotations.
Here are their meanings:

Uses $_ ($ARG) as a default variable.

Sets $! ($OS_ERROR) on syscall errors.

Raises exceptions; use eval to trap $@ ($EVAL_ERROR).

Sets $? ($CHILD_ERROR) when child process exits.

Taints returned data.

Taints returned data under some system, locale, or handle settings.

Raises an exception if given an argument of inappropriate type.

Raises an exception if modifying a read-only target.

Raises an exception if fed tainted data.

Raises an exception if unimplemented on current platform.

Functions that return tainted data when fed tainted data are not
marked, since that''s most of them. In particular, if you use any
function on %ENV or @ARGV, you''ll get tainted data.

Functions marked with raise an exception when they require, but do not receive,
an argument of a particular type (such as filehandles for I/O
operations, references for blessing, etc.).

Functions marked with sometimes need to alter their arguments.
If they can''t modify the argument because it''s marked read-only,
they''ll raise an exception. Examples of read-only variables are
the special variables containing data captured during a pattern
match and variables that are really aliases to constants.

Functions marked with may not be implemented on all platforms.
Although many of these are named after functions in the Unix C
library, don''t assume that just because you aren''t running Unix,
you can''t call any of them. Many are emulated, even
those you might never expect to see--such as fork on Win32
systems, which works as of the 5.6 release of Perl. For more
information about the portability and behavior of system-specific
functions, see the perlport manpage, plus any platform-specific documentation that came with
your Perl port.

Functions that raise other miscellaneous exceptions are marked with ,
including math functions that throw range errors, such as sqrt(-1).

29.2.1. abs

abs VALUE
abs

$diff = abs($first - $second);

my $diff = abs($first - $second);

29.2.2. accept

accept SOCKET, PROTOSOCKET

unless ($peer = accept(SOCK, PROTOSOCK)) {
die "Can''t accept a connection: $!\n";
}

See accept(2).
See also the example in the section "Sockets" in
Chapter 16, "Interprocess Communication".

29.2.3. alarm

alarm EXPR
alarm

Only one timer may be active at once. Each call disables the previous
timer, and an EXPR of 0 may be supplied to
cancel the previous timer without starting a new one. The return
value is the amount of time remaining on the previous timer.

print "Answer me within one minute, or die: ";
alarm(60);             # kill program in one minute
$answer = <STDIN>;
$timeleft = alarm(0);  # clear alarm
print "You had $timeleft seconds remaining\n";

For alarms of finer granularity than one second, you might be able
to use the syscall function to access setitimer(2) if your
system supports it. The CPAN module, Timer::HiRes, also provides
functions for this purpose.

29.2.4. atan2

atan2 Y, X

$pi = atan2(1,1) * 4;

sub tan { sin($_[0]) / cos($_[0]) }

29.2.5. bind

bind SOCKET, NAME

use Socket;
$port_number = 80;      # pretend we want to be a web server
$sockaddr = sockaddr_in($port_number, INADDR_ANY);
bind SOCK, $sockaddr or die "Can''t bind $port_number: $!\n";

29.2.6. binmode

binmode FILEHANDLE, DISCIPLINES
binmode FILEHANDLE

The binmode function should be called after the open but before
any I/O is done on the filehandle. The only way to reset the mode on a
filehandle is to reopen the file, since the various disciplines may
have treasured up various bits and pieces of data in various buffers.
This restriction may be relaxed in the future.

In the olden days, binmode was used primarily on
operating systems whose run-time libraries distinguished text
from binary files. On those systems, the purpose of
binmode was to turn off the default text semantics.
However, with the advent of Unicode, all programs on all systems must
take some cognizance of the distinction, even on Unix and Mac systems.
These days there is only one kind of binary file (as far as Perl is
concerned), but there are many kinds of text files, which Perl would
also like to treat in a single way. So Perl has a single internal
format for Unicode text, UTF-8. Since there are many kinds of text
files, text files often need to be translated upon input into UTF-8,
and upon output back into some legacy character set, or some other
representation of Unicode. You can use disciplines to tell Perl how
exactly (or inexactly) to do these translations.[2]

[2]More
precisely, you will be able to use disciplines
for this, but we''re still implementing them as of this
writing.

For example, a discipline of ":text" will tell Perl to do generic
text processing without telling Perl which kind of text processing to
do. But disciplines like ":utf8" and ":latin1" tell Perl which
text format to read and write. On the other hand, the ":raw"
discipline tells Perl to keep its cotton-pickin'' hands off the data.
For more on how disciplines work (or will work), see the open function. The rest of this discussion describes what binmode does
without the DISCIPLINES argument, that is, the historical meaning of
binmode, which is equivalent to:

binmode FILEHANDLE, ":raw";

In the absence of a DISCIPLINES argument, binmode has no effect
under Unix or Mac OS, both of which use \n to end each line and
represent that as a single character. (It may, however, be a different
character: Unix uses \cJ and older Macs use \cM. Doesn''t matter.)

The following example shows how a Perl script might read a GIF image
from a file and print it to the standard output. On systems that
would otherwise alter the literal data into something other than its
exact physical representation, you must prepare both handles.
While you could use a ":raw" discipline directly in the GIF open,
you can''t do that so easily with pre-opened filehandles like STDOUT:

binmode STDOUT;
open(GIF, "vim-power.gif") or die "Can''t open vim-power.gif: $!\n";
binmode GIF;
while (read(GIF, $buf, 1024)) {
print STDOUT $buf;
}

29.2.7. bless

bless REF, CLASSNAME
bless REF

$pet = Beast->new(TYPE => "cougar", NAME => "Clyde");
# then in Beast.pm:
sub new {
my $class  = shift;
my %attrs = @_;
my $self   = { %attrs };
return bless($self, $class);
}

Make sure that CLASSNAME is not false; blessing into false
packages is not supported and may result in unpredictable behavior.

It is not a bug that there is no corresponding curse operator. (But
there is a sin operator.) See also Chapter 12, "Objects", for more
about the blessing (and blessings) of objects.

29.2.8. caller

caller EXPR
caller

($package, $filename, $line) = caller;

sub careful {
my ($package, $filename) = caller;
unless ($package  eq __PACKAGE__ && $filename eq __FILE__) {
die "You weren''t supposed to call me, $package!\n";
}
print "called me safely\n";
}
sub safecall {
careful();
}

$i = 0;
while (($package, $filename, $line, $subroutine,
$hasargs, $wantarray, $evaltext, $is_require,
$hints, $bitmask) = caller($i++) )
{
...
}

In a fit of even deeper magic, caller also sets the
array @DB::args to the arguments passed in the
given stack frame--but only when called from within the
DB package. See
Chapter 20, "The Perl Debugger".

29.2.9. chdir

chdir EXPR
chdir

chdir "$prefix/lib" or die "Can''t cd to $prefix/lib: $!\n";

29.2.10. chmod

chmod LIST

$cnt = chmod 0755, ''file1'', ''file2'';

Here''s a more typical usage:

chmod(0755, @executables) == @executables
or die "couldn''t chmod some of @executables: $!";

@cannot = grep {not chmod 0755, $_} ''file1'', ''file2'', ''file3'';
die "$0: could not chmod @cannot\n" if @cannot;

When using nonliteral mode data, you may need to convert an octal
string to a number using the oct function. That''s because
Perl doesn''t automatically assume a string contains an octal number
just because it happens to have a leading "0".

$DEF_MODE = 0644;   # Can''t use quotes here!
PROMPT: {
print "New mode? ";
$strmode = <STDIN>;
exit unless defined $strmode;   # test for eof
if ($strmode =~ /^\s*$/) {          # test for blank line
$mode = $DEF_MODE;
}
elsif ($strmode !~ /^\d+$/) {
print "Want numeric mode, not $strmode\n";
redo PROMPT;
}
else {
$mode = oct($strmode);          # converts "755" to 0755
}
chmod $mode, @files;
}

You can also import the symbolic S_I* constants from the Fcntl
module:

use Fcntl '':mode'';
chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;

29.2.11. chomp

chomp VARIABLE
chomp LIST
chomp

Unlike chop, chomp returns the number of characters deleted.
If $/ is " (in paragraph mode), chomp removes all trailing
newlines from the selected string (or strings, if chomping a LIST).
You cannot chomp a literal, only a variable.

For example:

while (<PASSWD>) {
chomp;   # avoid \n on last field
@array = split /:/;
...
}

29.2.12. chop

chop VARIABLE
chop LIST
chop

You cannot chop a literal, only a variable.

If you chop a LIST of variables, each string in the list is
chopped:

@lines = `cat myfile`;
chop @lines;

chop($cwd = `pwd`);
chop($answer = <STDIN>);

$answer = chop($tmp = <STDIN>);  # WRONG

$answer = substr <STDIN>, 0, -1;

chop($answer = <STDIN>);

$last_char = chop($var);
$last_char = substr($var, -1, 1, ");   # same thing

substr($caravan, -5) = ";

$tail = substr($caravan, -5, 5, ");

29.2.13. chown

chown LIST

chown($uidnum, $gidnum, ''file1'', ''file2'') == 2
or die "can''t chown file1 or file2: $!";

chown($uidnum, $gidnum, @filenames) == @filenames
or die "can''t chown @filenames: $!";

sub chown_by_name {
my($user, @files) = @_;
chown((getpwnam($user))[2,3], @files) == @files
or die "can''t chown @files: $!";
}
chown_by_name("fred", glob("*.c"));

On most systems, you are not allowed to change the ownership of the
file unless you''re the superuser, although you should be able to
change the group to any of your secondary groups. On insecure
systems, these restrictions may be relaxed, but this is not a
portable assumption. On POSIX systems, you can detect which rule
applies like this:

use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
# only try if we''re the superuser or on a permissive system
if ($> == 0 || !sysconf(_PC_CHOWN_RESTRICTED) ) {
chown($uidnum, -1, $filename)
or die "can''t chown $filename to $uidnum: $!";
}

29.2.14. chr

chr NUMBER
chr

This function returns the character represented by that NUMBER in
the character set. For example, chr(65) is "A" in either ASCII
or Unicode, and chr(0x263a) is a Unicode smiley face. For the
reverse of chr, use ord.

If you''d rather specify your characters by name than by number (for
example, "\N{WHITE SMILING FACE}" for a Unicode smiley), see
charnames in Chapter 31, "Pragmatic Modules".

29.2.15. chroot

chroot FILENAME
chroot

chroot((getpwnam(''ftp''))[7])
or die "Can''t do anonymous ftp: $!\n";

29.2.16. close

close FILEHANDLE
close

FILEHANDLE may be an expression whose value can be used as an
indirect filehandle (either the real filehandle name or a reference
to anything that can be interpreted as a filehandle object).

If the filehandle came from a piped open, close will return false if
any underlying syscall fails or if the program at the other end of
the pipe exited with nonzero status. In the latter case, the close
forces $! ($OS_ERROR) to zero. So if a close on a pipe
returns a nonzero status, check $! to determine whether the problem
was with the pipe itself (nonzero value) or with the program at
the other end (zero value). In either event, $? ($CHILD_ERROR)
contains the wait status value (see its interpretation under system)
of the command associated with the other end of the pipe. For example:

open(OUTPUT, ''| sort -rn | lpr -p'') # pipe to sort and lpr
or die "Can''t start sortlpr pipe: $!";
print OUTPUT @lines;                # print stuff to output
close OUTPUT                        # wait for sort to finish
or warn $! ? "Syserr closing sortlpr pipe: $!"
: "Wait status $? from sortlpr pipe";

open(NETSTAT, "netstat -rn |")
or die "can''t run netstat: $!";
open(STDIN, "<&NETSTAT")
or die "can''t dup to stdin: $!";

If you somehow manage to reap an exited pipe child on your own, the
close will fail. This could happen if you had a $SIG{CHLD}
handler of your own that got triggered when the pipe child exited, or if
you intentionally called waitpid on the process ID returned from the
open call.

29.2.17. closedir

closedir DIRHANDLE

29.2.18. connect

connect SOCKET, NAME

use Socket;
my ($remote, $port) = ("www.perl.com", 80);
my $destaddr = sockaddr_in($port, inet_aton($remote));
connect SOCK, $destaddr
or die "Can''t connect to $remote at port $port: $!";

29.2.19. cos

cos EXPR
cos

# Here''s the lazy way of getting degrees-to-radians.
$pi = atan2(1,1) * 4;
$piover180 = $pi/180;
# Print table.
for ($deg = 0; $deg <= 90; $deg++) {
printf "%3d %7.5f\n", $deg, cos($deg * $piover180);
}

sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }

29.2.20. crypt

crypt PLAINTEXT, SALT

[3] Only people with honorable intentions are
allowed to do this.

crypt is intended to be a one-way function, much
like breaking eggs to make an omelette. There is no (known) way to
decrypt an encrypted password apart from exhaustive, brute-force
guessing.

When verifying an existing encrypted string, you should use the
encrypted text as the SALT (like crypt($plain, $crypted) eq $crypted). This allows your code to work with the standard
crypt, and with more exotic implementations, too.

When choosing a new SALT, you minimally need to create a random two character string whose
characters come from the set [./0-9A-Za-z]
(like join '', (''.'', ''/'', 0..9, ''A''..''Z'', ''a''..''z'')[rand 64, rand 64]).
Older implementations of crypt only needed the first two characters
of the SALT, but code that only gives the first two characters
is now considered nonportable. See your local crypt(3) manpage
for interesting details.

Here''s an example that makes sure that whoever runs this program knows
their own password:

$pwd = (getpwuid ($<))[1];    # Assumes we''re on Unix.
system "stty -echo";   # or look into Term::ReadKey on CPAN
print "Password: ";
chomp($word = <STDIN>);
print "\n";
system "stty echo";
if (crypt($word, $pwd) ne $pwd) {
die "Sorry...\n";
} else {
print "ok\n";
}

Shadow password files are slightly more secure than traditional
password files, and you might have to be a superuser to access them.
Because few programs should run under such powerful privileges, you
might have the program maintain its own independent authentication
system by storing the crypt strings in a different
file than /etc/passwd or
/etc/shadow.

The 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 by-module/Crypt and by-module/PGP directories
on your favorite CPAN mirror for a slew of potentially useful
modules.

29.2.21. dbmclose

dbmclose HASH

29.2.22. dbmopen

dbmopen HASH, DBNAME, MODE

The dbmopen function is really just a call to
tie with the proper arguments, but is provided for
backward compatibility with ancient versions of Perl. You can control
which DBM library you use by using the tie
interface directly or by loading the appropriate module before you
call dbmopen. Here''s an example that works on some
systems for versions of DB_File similar to the
version in your Netscape browser:

use DB_File;
dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.dat", undef)
or die "Can''t open netscape history file: $!";
while (($url, $when) = each %NS_Hist) {
next unless defined($when);
chop ($url, $when);        # kill trailing null bytes
printf "Visited %s at %s.\n", $url,
scalar(localtime(unpack("V",$when)));
}

Functions such as keys and values may return huge list values
when used on large DBM files. You may prefer to use the each
function to iterate over large DBM files so that you don''t load the
whole thing in memory at once.

Hashes bound to DBM files have the same limitations as the type of DBM
package you''re using, including restrictions on how much data you can
put into a bucket. If you stick to short keys and values, it''s rarely
a problem. See also the DB_File module in Chapter 32, "Standard Modules".

Another thing you should bear in mind is that many existing DBM
databases contain null-terminated keys and values because they were
set up with C programs in mind. The Netscape history file and the
old sendmail aliases file are examples. Just use "$key\0"
when pulling out a value, and remove the null from the value.

$alias = $aliases{"postmaster\0"};
chop $alias;   # kill the null

29.2.23. defined

defined EXPR
defined

Many operations return undef under exceptional
conditions, such as at end-of-file, when using an uninitialized
variable''s value, an operating system error, etc. Since undef is
just one kind of false value, a simple Boolean test does not
distinguish between undef, numeric zero, the null string, and the
one-character string, "0"--all of which are equally false. The
defined function allows you to distinguish between an undefined null
string and a defined null string when you''re using operators that might
return a real null string.

Here is a fragment that tests a scalar value from a hash:

print if defined $switch{D};

In the next example we exploit the convention that some operations return the
undefined value when you run out of data:

print "$val\n" while defined($val = pop(@ary));

setpwent();
while (defined($name = getpwent())) {
print "<<$name>>\n";
}
endpwent();

die "Can''t readlink $sym: $!"
unless defined($value = readlink $sym);

indir("funcname", @arglist);
sub indir {
my $subname = shift;
no strict ''refs'';  # so we can use subname indirectly
if (defined &$subname) {
&$subname(@_);    # or $subname->(@_);
}
else {
warn "Ignoring call to invalid function $subname";
}
}

if (@an_array) { print "has array elements\n" }
if (%a_hash)   { print "has hash members\n"   }

29.2.24. delete

delete EXPR

Deleting from the %ENV hash modifies the
environment. Deleting from a hash that is bound to a (writable)
DBM file deletes the entry from that DBM file.

Historically, you could only delete from a hash, but with Perl version 5.6
you may also delete from an array. Deleting from an array causes the
element at the specified position to revert to a completely
uninitialized state, but it doesn''t close up the gap, since that would
change the positions of all the subsequent entries. Use a splice
for that. (However, if you delete the final element in an array, the
array size will shrink by one (or more, depending on the position of the
next largest existing element (if any))).

EXPR can be arbitrarily complicated, provided that the final
operation is a hash or array lookup:

# set up array of array of hash
$dungeon[$x][$y] = \%properties;
# delete one property from hash
delete $dungeon[$x][$y]{"OCCUPIED"};
# delete three properties all at once from hash
delete @{ $dungeon[$x][$y] }{ "OCCUPIED", "DAMP", "LIGHTED" };
# delete reference to %properties from array
delete $dungeon[$x][$y];

foreach $key (keys %hash) {
delete $hash{$key};
}

delete @hash{keys %hash};

%hash = ();         # completely empty %hash
undef %hash;        # forget %hash ever existed

foreach $index (0 .. $#array) {
delete $array[$index];
}

delete @array[0 .. $#array];

@array = ();         # completely empty @array
undef @array;        # forget @array ever existed

29.2.25. die

die LIST
die

Within an eval, the function sets the $@ variable to the
error message that would have otherwise been produced, then aborts the
eval, which returns undef. The die function
can thus be used to raise named exceptions that can be caught at a
higher level in the program. See eval
later in this chapter.

If LIST is a single object reference, that object is assumed to be
an exception object and is returned unmodified as the exception in $@.

If LIST is empty and $@ already contains a string value (typically from
a previous eval) that value is reused after appending
"\t...propagated". This is useful for propagating (reraising) exceptions:

eval { ... };
die unless $@ =~ /Expected exception/;

If LIST is empty and $@
is empty, then the string "Died" is used.

If the final value of LIST does not end in
a newline (and you''re not passing an exception object), the current
script filename, line number, and input line number (if any) are
appended to the message, as well as a newline. Hint: sometimes
appending ", stopped" to your message will
cause it to make better sense when the string "at scriptname
line 123" is appended. Suppose you are running script
canasta; consider the difference between the
following two ways of dying:

die "/usr/games is no good";
die "/usr/games is no good, stopped";

/usr/games is no good at canasta line 123.
/usr/games is no good, stopped at canasta line 123.

die ''"'', __FILE__, ''", line '', __LINE__, ", phooey on you!\n";

"canasta", line 38, phooey on you!

die "Can''t cd to spool: $!\n"   unless chdir ''/usr/spool/news'';
chdir ''/usr/spool/news''         or die "Can''t cd to spool: $!\n"

See also exit, warn, %SIG, and the Carp module.

29.2.26. do (block)

do BLOCK

29.2.27. do (file)

do FILE

do ''stat.pl'';

scalar eval `cat stat.pl`;   # `type stat.pl` on Windows

If do can''t read the file, it returns
undef and sets $! to the error.
If do can read the file but can''t compile it, it
returns undef and sets an error message in
$@. If the file is successfully compiled,
do returns the value of the last expression
evaluated.

Inclusion of library modules (which have a mandatory
.pm suffix) is better done with the
use and require operators, which
also do error checking and raise an exception if there''s a problem.
They also offer other benefits: they avoid duplicate loading, help
with object-oriented programming, and provide hints to the compiler on
function prototypes.

But doFILE is still
useful for such things as reading program configuration files. Manual
error checking can be done this way:

# read in config files: system first, then user
for $file ("/usr/share/proggie/defaults.rc",
"$ENV{HOME}/.someprogrc")
{
unless ($return = do $file) {
warn "couldn''t parse $file: $@" if $@;
warn "couldn''t do $file: $!"    unless defined $return;
warn "couldn''t run $file"       unless $return;
}
}

29.2.28. do (subroutine)

do SUBROUTINE(LIST)

29.2.29. dump

dump LABEL
dump

This function is now largely obsolete, partly because it''s difficult in
the extreme to convert a core file into an executable in the general
case, and because various compiler backends for generating portable
bytecode and compilable C code have superseded it.

If you''re looking to use dump to speed up your
program, check out the discussion of efficiency matters in Chapter 24, "Common Practices", as well the Perl native-code
generator in Chapter 18, "Compiling". You might also
consider autoloading or selfloading, which at least make your program
appear to run faster.

29.2.30. each

each HASH

while (($key,$value) = each %ENV) {
print "$key=$value\n";
}

There is a single iterator for each hash, shared by all each,
keys, and values function calls in the program; it can be
reset by reading all the elements from the hash, or by evaluating
keys %hash or values %hash. If you add or delete elements
of a hash while you''re iterating over it, the resulting behavior
is not well-defined: entries might get skipped or duplicated.

See also keys, values, and sort.

29.2.31. eof

eof FILEHANDLE
eof()
eof

while (<>) {
if (eof()) {
print "-" x 30, "\n";
}
print;
}

# reset line numbering on each input file
while (<>) {
next if /^\s*#/;        # skip comments
print "$.\t$_";
} continue {
close ARGV if eof;      # Not eof()!
}

while (<>) {
print if /pattern/ .. eof;
}

Warning: The eof function reads a byte and then pushes it
back on the input stream with ungetc(3), so it is not useful in
an interactive context. In fact, experienced Perl programmers rarely use
eof, since the various input operators already behave politely in
while-loop conditionals. See the example in the description of
foreach in Chapter 4, "Statements and Declarations".

29.2.32. eval

eval BLOCK
eval EXPR
eval

For either form of eval,
the value returned from an eval is the value of the last expression
evaluated, just as with subroutines. Similarly, you may use the
return operator to return a value from the middle of the eval.
The expression providing the return value is evaluated in void,
scalar, or list context, depending on the context of the eval itself.
See wantarray for more on how the evaluation context can be
determined.

If there is a trappable error (including any produced by the die
operator), eval returns undef and puts the error
message (or object) in $@. If there is no error, $@ is guaranteed
to be set to the null string, so you can test it reliably afterward for
errors. A simple Boolean test suffices:

eval { ... };    # trap run-time errors
if ($@) { ... }    # handle error

The evalEXPR form can
trap syntax errors because it parses the code at run time. (If the
parse is unsuccessful, it places the parse error in
$@, as usual.) Otherwise, it executes the value of
EXPR as though it were a little Perl
program. The code is executed in the context of the current Perl
program, which means that it can see any enclosing lexicals from a
surrounding scope, and that any non-local variable settings remain in
effect after the eval is complete, as do any
subroutine or format definitions. The code of the
eval is treated as a block, so any locally scoped
variables declared within the eval last only until
the eval is done. (See my and
local.) As with any code in a block, a final
semicolon is not required.

Here is a simple Perl shell. It prompts the user to enter
a string of arbitrary Perl code, compiles and executes that string,
and prints whatever error occurred:

print "\nEnter some Perl code: ";
while (<STDIN>) {
eval;
print $@;
print "\nEnter some more Perl code: ";
}

#!/usr/bin/perl
# rename - change filenames
$op = shift;
for (@ARGV) {
$was = $_;
eval $op;
die if $@;
# next line calls the built-in function, not the script by the same name
rename($was,$_) unless $was eq $_;
}

$ rename ''s/\.orig$//''                *.orig
$ rename ''y/A-Z/a-z/ unless /^Make/''  *
$ rename ''$_ .= ".bad"''               *.f

Because evalBLOCK is syntax-checked at compile time, any syntax
error is reported earlier. Therefore, if your code is invariant and
both evalEXPR and evalBLOCK will suit your purposes
equally well, the BLOCK form is preferred. For example:

# make divide-by-zero nonfatal
eval { $answer = $a / $b; };    warn $@ if $@;
# same thing, but less efficient if run multiple times
eval ''$answer = $a / $b'';       warn $@ if $@;
# a compile-time syntax error (not trapped)
eval { $answer = };             # WRONG
# a run-time syntax error
eval ''$answer ='';               # sets $@

The block of evalBLOCK does not count as a loop, so the loop
control statements next, last, or redo cannot be used to leave
or restart the block.

29.2.33. exec

exec PATHNAME LIST
exec LIST

If there is only one scalar argument, the argument is checked for shell
metacharacters. If metacharacters are found, the entire argument is
passed to the system''s standard command interpreter (/bin/sh
under
Unix). If there are no metacharacters, the argument is split into
words and executed directly, since in the interests of efficiency this
bypasses all the overhead of shell processing. It also gives you more
control of error recovery should the program not exist.

If there is more than one argument in LIST, or if LIST is an
array with more than one value, the system shell will never be used.
This also bypasses any shell processing of the command. The presence
or absence of metacharacters in the arguments doesn''t affect this
list-triggered behavior, which makes it the preferred form in
security-conscious programs that do not wish to expose themselves to
potential shell escapes.

This example causes the currently running Perl program to replace
itself with the echo program, which then prints out the current
argument list:

exec ''echo'', ''Your arguments are: '', @ARGV;

exec "sort $outfile | uniq"
or die "Can''t do sort/uniq: $!\n";

When you ask the operating system to execute a new program within an
existing process (as Perl''s exec function does),
you tell the system the location of the program to execute, but you
also tell the new program (through its first argument) the name under
which the program was invoked. Customarily, the name you tell it is
just a copy of the location of the program, but it doesn''t necessarily
have to be, since there are two separate arguments at the level of the
C language. When it is not a copy, you have the odd result that the
new program thinks it''s running under a name that may be totally
different from the actual pathname where the program resides. Often
this doesn''t matter to the program in question, but some programs do
care and adopt a different persona depending on what they think their
name is. For example, the vi editor looks to see
whether it was called as "vi" or as
"view". If invoked as "view",
it automatically enables read-only mode, just as though it was called
with the -R command-line option.

This is where exec''s optional
PATHNAME parameter comes into play.
Syntactically, it goes in the indirect-object slot like the filehandle
for print or printf. Therefore,
it doesn''t take a comma after it, because it''s not exactly part of the
argument list. (In a sense, Perl takes the opposite approach from the
operating system in that it assumes the first argument is the
important one, and lets you modify the pathname if it differs.) For
example:

$editor = "/usr/bin/vi";
exec $editor "view", @files      # trigger read-only mode
or die "Couldn''t execute $editor: $!\n";

exec { "/usr/bin/vi" } "view" @files      # trigger read-only mode
or die "Couldn''t execute $editor: $!\n";

@args = ("echo surprise");  # just one element in list
exec @args                  # still subject to shell escapes
or die "exec: $!";     #   because @args == 1

exec { $args[0] } @args   # safe even with one-argument list
or die "can''t exec @args: $!";

Because the exec function is most often used
shortly after a fork, it is assumed that anything
that normally happens when a Perl process terminates should be
skipped. Upon an exec, Perl will not call your
END blocks, nor will it call any
DESTROY methods associated with any objects.
Otherwise, your child process would end up doing the cleanup you
expected the parent process to do. (We wish that were the case in
real life.)

Because it''s such a common mistake to use exec
instead of system, Perl warns you if there is a
following statement that isn''t die,
warn, or exit when run with the
popular -w command-line option, or if you''ve
used the use warnings qw(exec syntax) pragma. If
you really want to follow an exec with some other
statement, you can use either of these styles to avoid the warning:

exec (''foo'')   or print STDERR "couldn''t exec foo: $!";
{ exec (''foo'') }; print STDERR "couldn''t exec foo: $!";

See also system.

29.2.34. exists

exists EXPR

print "True\n"      if         $hash{$key};
print "Defined\n"   if defined $hash{$key};
print "Exists\n"    if exists  $hash{$key};
print "True\n"      if         $array[$index];
print "Defined\n"   if defined $array[$index];
print "Exists\n"    if exists  $array[$index];

EXPR can be arbitrarily complicated,
provided that the final operation is a hash key or array index lookup:

if (exists $hash{A}{B}{$key}) { ... }

undef $ref;
if (exists $ref->{"Some key"}) { }
print $ref;   # prints HASH(0x80d3d5c)

if ($ref                        and
exists $ref->[$x]           and
exists $ref->[$x][$y]       and
exists $ref->[$x][$y]{$key} and
exists $ref->[$x][$y]{$key}[2] ) { ... }

sub flub;
print "Exists\n"     if exists  &flub;
print "Defined\n"    if defined &flub;

29.2.35. exit

exit EXPR
exit

$ans = <STDIN>;
exit if $ans =~ /^[Xx]/;

We said that the exit function exits immediately, but that was a
bald-faced lie. It exits as soon as possible, but first it calls any
defined END routines for at-exit handling. These routines cannot
abort the exit, although they can change the eventual exit value by
setting the $? variable. Likewise, any class that defines
a DESTROY method will invoke that method on behalf of all its
objects before the real program exits. If you really need to bypass
exit processing, you can call the POSIX module''s _exit function
to avoid all END and destructor processing. And if POSIX isn''t
available, you can exec "/bin/false" or some such.

29.2.36. exp

exp EXPR
exp

use Math::Complex;
print -exp(1) ** (i * pi);   # prints 1

29.2.37. fcntl

fcntl FILEHANDLE, FUNCTION, SCALAR

use Fcntl;

SCALAR will be read or written (or both) depending on the
FUNCTION. A pointer to the string value of SCALAR will be
passed as the third argument of the actual fcntl call. (If
SCALAR has no string value but does have a numeric value, that
value will be passed directly rather than passing a pointer to the string
value.) See the Fcntl module for a description of the more common
permissible values for FUNCTION.

The fcntl function will raise an exception if used
on a system that doesn''t implement
fcntl(2). On systems that do implement
it, you can do such things as modify the close-on-exec flags (if you
don''t want to play with the $^F
($SYSTEM_FD_MAX) variable), modify the nonblocking
I/O flags, emulate the lockf(3) function,
and arrange to receive the SIGIO signal when I/O is
pending.

Here''s an example of setting a filehandle named
REMOTE to be nonblocking at the system level. This
makes any input operation return immediately if nothing is available
when reading from a pipe, socket, or serial line that would otherwise
block. It also works to cause output operations that normally would
block to return a failure status instead. (For those, you''ll likely
have to negotiate $| as well.)

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";

Thus Perl returns true on success and false on failure, yet you can
still easily determine the actual value returned by the operating
system:

$retval = fcntl(...) || -1;
printf "fcntl actually returned %d\n", $retval;

29.2.38. fileno

fileno FILEHANDLE

So, for example, the fileno function is useful for
constructing bitmaps for select and for passing to certain
obscure system calls if syscall(2) is implemented. It''s also
useful for double-checking that the open function gave you the
file descriptor you wanted and for determining whether two filehandles
use the same system file descriptor.

if (fileno(THIS) == fileno(THAT)) {
print "THIS and THAT are dups\n";
}

One caution: don''t count on the association of a Perl filehandle and a
numeric file descriptor throughout the life of the program. If a file
has been closed and reopened, the file descriptor may change. Perl
takes a bit of trouble to try to ensure that certain file descriptors
won''t be lost if an open on them fails, but it only does this for
file descriptors that don''t exceed the current value of the special $^F ($SYSTEM_FD_MAX) variable (by default, 2). Although
filehandles STDIN, STDOUT, and STDERR start out with file
descriptors of 0, 1, and 2 (the Unix standard convention), even they
can change if you start closing and opening them with wild abandon.
You can''t get into trouble with 0, 1, and 2 as long as you always
reopen immediately after closing. The basic rule on Unix systems
is to pick the lowest available descriptor, and that''ll be the one you
just closed.

29.2.39. flock

flock FILEHANDLE, OPERATION

OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN,
possibly ORed with LOCK_NB. These constants are traditionally
valued 1, 2, 8, and 4, but you can use the symbolic names if you
import them from the Fcntl module, either individually or as a
group using the :flock tag.

LOCK_SH requests a shared lock, so it''s typically used for reading.
LOCK_EX requests an exclusive lock, so it''s typically used for
writing. LOCK_UN releases a previously requested lock; closing the
file also releases any locks. If the LOCK_NB bit is used with
LOCK_SH or LOCK_EX, flock returns immediately rather than
waiting for an unavailable lock. Check the return status to see
whether you got the lock you asked for. If you don''t use LOCK_NB,
you might wait indefinitely for the lock to be granted.

Another nonobvious but traditional aspect of flock is
that its locks are merely advisory. Discretionary locks are more flexible
but offer fewer guarantees than mandatory ones. This means that
files locked with flock may be modified by programs that do not
also use flock. Cars that stop for red lights get on well with
each other, but not with cars that don''t stop for red lights. Drive
defensively.

Some implementations of flock cannot lock things over the network.
While you could in theory use the more system-specific fcntl for
that, the jury (having sequestered itself on the case for a decade or
so) is still out on whether this is (or even can be) reliable.

Here''s a mailbox appender for Unix systems that use flock(2)
to lock mailboxes:

use Fcntl qw/:flock/;       # import LOCK_* constants
sub mylock {
flock(MBOX, LOCK_EX)
or die "can''t lock mailbox: $!";
# in case someone appended while we were waiting
# and our stdio buffer is out of sync
seek(MBOX, 0, 2)
or die "can''t seek to the end of mailbox: $!";
}
open(MBOX, ">>/usr/spool/mail/$ENV{''USER''}")
or die "can''t open mailbox: $!";
mylock();
print MBOX $msg, "\n\n";
close MBOX
or die "can''t close mailbox: $!";

29.2.40. fork

fork

In versions of Perl prior to 5.6, unflushed buffers remain unflushed in
both processes, which means you may need to set $| on one or more
filehandles earlier in the program to avoid duplicate output.

A nearly bulletproof way to launch a child process while checking for
"cannot fork" errors would be:

use Errno qw(EAGAIN);
FORK: {
if ($pid = fork) {
# parent here
# child process pid is available in $pid
}
elsif (defined $pid) { # $pid is zero here if defined
# child here
# parent process pid is available with getppid
}
elsif ($! == EAGAIN) {
# EAGAIN is the supposedly recoverable fork error
sleep 5;
redo FORK;
}
else {
# weird fork error
die "Can''t fork: $!\n";
}
}

If you fork without ever waiting on your children,
you will accumulate zombies (exited processes whose parents haven''t
waited on them yet). On some systems, you can avoid this by setting
$SIG{CHLD} to "IGNORE"; on most,
you must wait for your moribund children. See the
wait function for examples of doing this, or see
the "Signals" section of Chapter 16, "Interprocess Communication" for more on
SIGCHLD.

If a forked child inherits system file descriptors like
STDIN and STDOUT that are
connected to a remote pipe or socket, you may have to reopen these in
the child to /dev/null. That''s because even when
the parent process exits, the child will live on with its copies of
those filehandles. The remote server (such as, say, a CGI script or a
background job launched from a remote shell) will appear to hang
because it''s still waiting for all copies to be closed. Reopening the
system filehandles to something else fixes this.

On most systems supporting fork(2), great
care has gone into making it extremely efficient (for example, using
copy-on-write technology on data pages), making it the dominant
paradigm for multitasking over the last few decades. The
fork function is unlikely to be implemented
efficiently, or perhaps at all, on systems that don''t resemble Unix.
For example, Perl 5.6 emulates a proper fork even
on Microsoft systems, but no assurances can be made on performance at
this point. You might have more luck there with the
Win32::Process module.

29.2.41. format

format NAME =
picture line
value list
...
.

my $str = "widget";               # Lexically scoped variable.
format Nice_Output =
Test: @<<<<<<<< @||||| @>>>>>
$str,     $%,    ''$'' . int($num)
.
local $~ = "Nice_Output";         # Select our format.
local $num = $cost * $quantity;   # Dynamically scoped variable.
write;

The "Format Variables" section in Chapter 7, "Formats"
contains numerous details and examples of their use. Chapter 28, "Special Names" describes the internal
format-specific variables, and the English and
IO::Handle modules provide easier access to them.

29.2.42. formline

formline PICTURE, LIST

Be careful if you put double quotes around the picture, since an
@ character may be taken to mean the beginning of
an array name. See "Formats" in Chapter 6, "Subroutines" for example uses.

29.2.43. getc

getc FILEHANDLE
getc

This function is somewhat slow, but occasionally useful for
single-character (byte, really) input from the keyboard--provided you
manage to get your keyboard input unbuffered. This function requests
unbuffered input from the standard I/O library. Unfortunately, the
standard I/O library is not so standard as to provide a portable way
to tell the underlying operating system to supply unbuffered keyboard
input to the standard I/O system. To do that, you have to be slightly
more clever, and in an operating-system-dependent fashion. Under Unix
you might say this:

if ($BSD_STYLE) {
system "stty cbreak </dev/tty >/dev/tty 2>&1";
} else {
system "stty", "-icanon", "eol", "\001";
}
$key = getc;
if ($BSD_STYLE) {
system "stty -cbreak </dev/tty >/dev/tty 2>&1";
} else {
system "stty", "icanon", "eol", "^@"; # ASCII NUL
}
print "\n";

The POSIX module provides a more portable version
of this using the POSIX::getattr function. See
also the Term::ReadKey module from your nearest
CPAN site for a more portable and flexible approach.

29.2.44. getgrent

getgrent
setgrent
endgrent

($name, $passwd, $gid, $members)

while (($name, $passwd, $gid) = getgrent) {
$gid{$name} = $gid;
}

29.2.45. getgrgid

getgrgid GID

($name, $passwd, $gid, $members)

In scalar context, getgrgid returns only the group name.
The User::grent module supports a by-name interface
to this function. See getgrgid(3).

29.2.46. getgrnam

getgrnam NAME

($name, $passwd, $gid, $members)

In scalar context, getgrnam returns only the
numeric group ID. The User::grent module supports
a by-name interface to this function. See
getgrnam(3).

29.2.47. gethostbyaddr

gethostbyaddr ADDR, ADDRTYPE

($name, $aliases, $addrtype, $length, @addrs) =
gethostbyaddr($packed_binary_address, $addrtype);

($a, $b, $c, $d) = unpack(''C4'', $addrs[0]);

$dots = sprintf "%vd", $addrs[0];

use Socket;
$printable_address = inet_ntoa($addrs[0]);

To produce an ADDR from a dot vector,
say this:

use Socket;
$ipaddr = inet_aton("127.0.0.1");       # localhost
$claimed_hostname = gethostbyaddr($ipaddr, AF_INET);

$ipaddr = v127.0.0.1;

29.2.48. gethostbyname

gethostbyname NAME

($name, $aliases, $addrtype, $length, @addrs) =
gethostbyname($remote_hostname);

($a, $b, $c, $d) = unpack(''C4'', $addrs[0]);

$dots = sprintf "%vd", $addrs[0];

use Socket;
$ipaddr = gethostbyname($remote_host);
printf "%s has address %s\n",
$remote_host, inet_ntoa($ipaddr);

29.2.49. gethostent

gethostent
sethostent STAYOPEN
endhostent

($name, $aliases, $addrtype, $length, @addrs)

($a, $b, $c, $d) = unpack(''C4'', $addrs[0]);

The Net::hostent module supports a by-name interface to
this function.

29.2.50. getlogin

getlogin

$login = getlogin() || (getpwuid($<))[0] || "Intruder!!";

29.2.51. getnetbyaddr

getnetbyaddr ADDR, ADDRTYPE

use Socket;
($name, $aliases, $addrtype, $net) = getnetbyaddr(127, AF_INET);

29.2.52. getnetbyname

getnetbyname NAME

($name, $aliases, $addrtype, $net) = getnetbyname("loopback");

29.2.53. getnetent

getnetent
setnetent STAYOPEN
endnetent

($name, $aliases, $addrtype, $net) = getnetent();

The concept of network
names seems rather quaint these days; most IP addresses are on unnamed
(and unnameable) subnets.

29.2.54. getpeername

getpeername SOCKET

use Socket;
$hersockaddr      = getpeername SOCK;
($port, $heraddr) = sockaddr_in($hersockaddr);
$herhostname      = gethostbyaddr($heraddr, AF_INET);
$herstraddr       = inet_ntoa($heraddr);

29.2.55. getpgrp

getpgrp PID

29.2.56. getppid

getppid

29.2.57. getpriority

getpriority WHICH, WHO

The BSD::Resource module from CPAN provides a more
convenient interface, including the PRIO_PROCESS,
PRIO_PGRP, and PRIO_USER
symbolic constants to supply for the WHICH
argument. Although these are traditionally set to
0, 1, and 2
respectively, you really never know what may happen within the dark
confines of C''s #include files.

A value of 0 for WHO means the current process, process group,
or user, so to get the priority of the current process, use:

$curprio = getpriority(0, 0);

29.2.58. getprotobyname

getprotobyname NAME

($name, $aliases, $protocol_number) = getprotobyname("tcp");

29.2.59. getprotobynumber

getprotobynumber NUMBER

($name, $aliases, $protocol_number) = getprotobynumber(6);

29.2.60. getprotoent

getprotoent
setprotoent STAYOPEN
endprotoent

($name, $aliases, $protocol_number) = getprotoent();

29.2.61. getpwent

getpwent
setpwent
endpwent

($name,$passwd,$uid,$gid,$quota,$comment,$gcos,$dir,$shell) = getpwent();

while (($name, $passwd, $uid) = getpwent()) {
$uid{$name} = $uid;
}

29.2.62. getpwnam

getpwnam NAME

($name,$passwd,$uid,$gid,$quota,$comment,$gcos,$dir,$shell) = getpwnam("daemon");

For repeated lookups, consider caching the data in a hash
using getpwent.

In scalar context, getpwnam returns only the numeric user ID.
The User::pwent module supports a by-name interface
to this function. See getpwnam(3) and passwd(5).

29.2.63. getpwuid

getpwuid UID

($name,$passwd,$uid,$gid,$quota,$comment,$gcos,$dir,$shell) = getpwuid(2);

In scalar context, getpwuid returns the username.
The User::pwent module supports a by-name interface
to this function. See getpwnam(3) and passwd(5).

29.2.64. getservbyname

getservbyname NAME, PROTO

($name, $aliases, $port_number, $protocol_name) = getservbyname("www", "tcp");

29.2.65. getservbyport

getservbyport PORT, PROTO

($name, $aliases, $port_number, $protocol_name) = getservbyport(80, "tcp");

29.2.66. getservent

getservent
setservent STAYOPEN
endservent

($name, $aliases, $port_number, $protocol_name) = getservent();

29.2.67. getsockname

getsockname SOCKET

use Socket;
$mysockaddr = getsockname(SOCK);
($port, $myaddr) = sockaddr_in($mysockaddr);
$myname = gethostbyaddr($myaddr,AF_INET);
printf "I am %s [%vd]\n", $myname, $myaddr;

29.2.68. getsockopt

getsockopt SOCKET, LEVEL, OPTNAME

29.2.69. glob

glob EXPR
glob

For historical reasons, the algorithm matches the
csh(1)''s style of expansion, not the
Bourne shell''s. Versions of Perl before the 5.6 release used an
external process, but 5.6 and later perform globs internally. Files
whose first character is a dot (".") are ignored
unless this character is explicitly matched. An asterisk
("*") matches any sequence of any character
(including none). A question mark ("?") matches
any one character. A square bracket sequence
("[...]") specifies a simple
character class, like "[chy0-9]". Character
classes may be negated with a circumflex, as in
"*.[^oa]", which matches any non-dot files whose
names contain a period followed by one character which is neither an
"a" nor an "o" at the end of the name. A tilde
("~") expands to a home directory, as in
"~/.*rc" for all the current user''s "rc" files, or
"~jane/Mail/*" for all of Jane''s mail files.
Braces may be used for alternation, as in
"~/.{mail,ex,csh,twm,}rc" to get those particular
rc files.

If you want to glob filenames that might contain whitespace, you''ll
need to use the File::Glob module directly, since
glob grandfathers the use of whitespace to separate
multiple patterns such as <*.c *.h>. For
details, see File::Glob in Chapter 32, "Standard Modules". Calling
glob (or the <*> operator)
automatically uses that module, so if the module
mysteriously vaporizes from your library, an exception is raised.

When you call open, Perl does not expand wildcards,
including tildes. You need to glob the result
first.

open(MAILRC, "~/.mailrc")                # WRONG: tilde is a shell thing
or die "can''t open ~/.mailrc: $!";
open(MAILRC, (glob("~/.mailrc"))[0])     # expand tilde first
or die "can''t open ~/.mailrc: $!";

See also the "Filename globbing operator" section of Chapter 2, "Bits and Pieces".

29.2.70. gmtime

gmtime EXPR
gmtime

#  0    1    2     3     4    5     6     7     8
($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = gmtime;

All list elements are numeric and come straight out of a struct tm
(that''s a C programming structure--don''t sweat it). In particular this
means that $mon has the range 0..11 with January as month 0, and $wday has the range
0..6 with Sunday as day 0. You can remember which ones are
zero-based because those are the ones you''re always using as subscripts
into zero-based arrays containing month and day names.

For example, to get the current month in London, you might say:

$london_month = (qw(Jan Feb Mar Apr May Jun
Jul Aug Sep Oct Nov Dec))[(gmtime)[4]];

In scalar context, gmtime returns a ctime(3)-like string based
on the GMT time value. The Time::gmtime module supports
a by-name interface to this function. See also POSIX::strftime()
for a more fine-grained approach to formatting times.

This scalar value is not locale dependent but is
instead a Perl built-in. Also see the 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 the perllocale
manpage), and try:

use POSIX qw(strftime);
$now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;

29.2.71. goto

goto LABEL
goto EXPR
goto &NAME

[4]This means that if it doesn''t find the label in the
current routine, it looks back through the routines that called the
current routine for the label, thus making it nearly impossible to
maintain your program.

Going to even greater heights of orthogonality (and depths of idiocy),
Perl allows gotoEXPR,
which expects EXPR to evaluate to a label
name, whose location is guaranteed to be
unresolvable until run time since the label is unknown when the
statement is compiled. This allows for computed
gotos per FORTRAN, but isn''t necessarily
recommended[5] if you''re optimizing
for maintainability:

goto +("FOO", "BAR", "GLARCH")[$i];

[5] Understatement is reputed to be funny, so
we thought we''d try one here.

29.2.72. grep

grep EXPR, LIST
grep BLOCK LIST

If @all_lines contains lines of code, this example weeds out
comment lines:

@code_lines = grep !/^\s*#/, @all_lines;

@list = qw(barney fred dino wilma);
@greplist = grep { s/^[bfd]// } @list;

See also map. The following two statements are functionally
equivalent:

@out = grep { EXPR } @in;
@out = map { EXPR ? $_ : () } @in

29.2.73. hex

hex EXPR
hex

$number = hex("ffff12c0");

sprintf "%lx", $number;         # (That''s an ell, not a one.)

29.2.74. import

import CLASSNAME LIST
import CLASSNAME

29.2.75. index

index STR, SUBSTR, OFFSET
index STR, SUBSTR

$pos = -1;
while (($pos = index($string, $lookfor, $pos)) > -1) {
print "Found at $pos\n";
$pos++;
}

29.2.76. int

int EXPR
int

$average_age = 939/16;      # yields 58.6875 (58 in C)
$average_age = int 939/16;  # yields 58

$n = sprintf("%.0f", $f);   # round (not trunc) to nearest integer

29.2.77. ioctl

ioctl FILEHANDLE, FUNCTION, SCALAR

require "sys/ioctl.ph";     # perhaps /usr/local/lib/perl/sys/ioctl.ph

require ''sys/ioctl.ph'';
$size = pack("L", 0);
ioctl(FH, FIONREAD(), $size)
or die "Couldn''t call ioctl: $!\n";
$size = unpack("L", $size);

The return value of ioctl (and fcntl) is as follows:

Thus Perl returns true on success and false on failure, yet you can
still easily determine the actual value returned by the operating
system:

$retval = ioctl(...) || -1;
printf "ioctl actually returned %d\n", $retval;

Calls to ioctl should not be considered portable. If, say, you''re
merely turning off echo once for the whole script, it''s more
portable to say:

system "stty -echo";   # Works on most Unix boxen.

For still better portability, you might look at the Term::ReadKey
module from CPAN.

29.2.78. join

join EXPR, LIST

$rec = join '':'', $login,$passwd,$uid,$gid,$gcos,$home,$shell;

$string = join ", @array;

29.2.79. keys

keys HASH

@keys   = keys   %ENV;    # keys are in the same order as
@values = values %ENV;    # values, as this demonstrates
while (@keys) {
print pop(@keys), ''='', pop(@values), "\n";
}

foreach $key (sort keys %ENV) {
print $key, ''='', $ENV{$key}, "\n";
}

foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
printf "%4d %s\n", $hash{$key}, $key;
}

In scalar context, keys returns the number of elements of the hash
(and resets the each iterator). However, to get this information for
tied hashes, including DBM files, Perl must walk the entire hash,
so it''s not efficient then. Calling keys in a void context helps with that.

Used as an lvalue, keys increases the number of hash buckets
allocated for the given hash. (This is similar to pre-extending an
array by assigning a larger number to $#array.) Pre-extending your
hash can gain a measure of efficiency if you happen to know the hash is
going to get big, and how big it''s going to get. If you say:

keys %hash = 1000;

See also each, values, and sort.

29.2.80. kill

kill SIGNAL, LIST

$cnt = kill 1, $child1, $child2;
kill 9, @goners;
kill ''STOP'', getppid       # Can *so* suspend my login shell...
unless getppid == 1;    # (But don''t taunt init(8).)

use Errno qw(ESRCH EPERM);
if (kill 0 => $minion) {
print "$minion is alive!\n";
} elsif ($! == EPERM) {             # changed UID
print "$minion has escaped my control!\n";
} elsif ($! == ESRCH) {
print "$minion is deceased.\n";  # or zombied
} else {
warn "Odd; I couldn''t check on the status of $minion: $!\n";
}

See the section "Signals" in
Chapter 16, "Interprocess Communication".

29.2.81. last

last LABEL
last

LINE: while (<MAILMSG>) {
last LINE if /^$/; # exit when done with header
# rest of loop here
}

A block by itself is semantically identical to a loop that executes
once. Thus last can be used to effect an early
exit out of such a block.

See also Chapter 4, "Statements and Declarations" for
illustrations of how last, next,
redo, and continue work.

29.2.82. lc

lc EXPR
lc

29.2.83. lcfirst

lcfirst EXPR
lcfirst

29.2.84. length

length EXPR
length

Do not try to use length to find the size of an
array or hash. Use scalar @array for the size of
an array, and scalar keys %hash for the number of
key/value pairs in a hash. (The scalar is
typically omitted when redundant.)

To find the length of a string in bytes rather than characters, say:

$blen = do { use bytes; length $string; };

$blen = bytes::length($string);    # must use bytes first

29.2.85. link

link OLDFILE, NEWFILE

29.2.86. listen

listen SOCKET, QUEUESIZE

use Socket;
listen(PROTOSOCK, SOMAXCONN)
or die "cannot set listen queue on PROTOSOCK: $!";

29.2.87. local

local EXPR

This operator works by saving the
current values of the specified variables on a hidden stack and restoring
them upon exiting the block, subroutine, eval, or file. After
the local is executed, but before the scope is exited, any
subroutines and executed formats will see the local, inner value,
instead of the previous, outer value because the variable is still a
global variable, despite having a localized value. The technical
term for this is "dynamic scoping". See the section "Scoped Declarations" in Chapter 4, "Statements and Declarations".

The EXPR may be assigned to if desired, which allows you to
initialize your variables as you localize them. If no initializer is
given, all scalars are initialized to undef, and all
arrays and hashes to (). As with ordinary assignment, if
you use parentheses around the variables on the left (or if the
variable is an array or hash), the expression on the right is evaluated
in list context. Otherwise, the expression on the right is evaluated in
scalar context.

In any event, the expression on the right is evaluated before the
localization, but the initialization happens after localization, so you
can initialize a localized variable with its nonlocalized value. For
instance, this code demonstrates how to make a temporary modification
to a global array:

if ($sw eq ''-v'') {
# init local array with global array
local @ARGV = @ARGV;
unshift @ARGV, ''echo'';
system @ARGV;
}
# @ARGV restored

# temporarily add a couple of entries to the %digits hash
if ($base12) {
# (NOTE: We''re not claiming this is efficient!)
local(%digits) = (%digits, T => 10, E => 11);
parse_num();
}

if ($protected) {
local $SIG{INT} = ''IGNORE'';
precious();     # no interrupts during this function
}                   # previous handler (if any) restored

local *MOTD;                # protect any global MOTD handle
my $fh = do { local *FH };  # create new indirect filehandle

But in general, you usually want to use my instead
of local, because local isn''t
really what most people think of as "local", or even "lo-cal". See
my.

29.2.88. localtime

localtime EXPR
localtime

#  0    1    2     3     4    5     6     7     8
($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime;

All list elements are numeric and come straight out of a
struct tm. (That''s a bit of C programming
lingo--don''t worry about it.) In particular, this means that
$mon has the range 0..11 with
January as month 0, and $wday has the range
0..6 with Sunday as day 0. You
can remember which ones are zero-based because those are the ones
you''re always using as subscripts into zero-based arrays containing
month and day names.

For example, to get the name of the current day of the week:

$thisday = (Sun,Mon,Tue,Wed,Thu,Fri,Sat)[(localtime)[6]];

The Perl library module Time::Local contains a subroutine,
timelocal, that can convert in the opposite direction.

In scalar context, localtime returns a
ctime(3)-like string. For example, the
date(1) command can be
(almost)[6] emulated with:

perl -le ''print scalar localtime''

[6]date(1) prints the
timezone, whereas scalar localtime does
not.

29.2.89. lock

lock THING

29.2.90. log

log EXPR
log

sub log10 {
my $n = shift;
return log($n)/log(10);
}

29.2.91. lstat

lstat EXPR
lstat

29.2.92. m//

/PATTERN/
m/PATTERN/

29.2.93. map

map BLOCK LIST
map EXPR, LIST

@words = map { split '' '' } @lines;

@chars = map chr, @nums;

%hash = map { genkey($_) => $_ } @array;

%hash = ();
foreach $_ (@array) {
$hash{genkey($_)} = $_;
}

29.2.94. mkdir

mkdir FILENAME, MASK
mkdir FILENAME

If MASK is omitted, a mask of 0777 is assumed, which is almost
always what you want anyway. In general, creating
directories with permissive MASKs (like 0777) and letting the user
modify that with their umask is better than supplying a restrictive
MASK and giving the user no way to be more permissive. The exception
to this rule is when the file or directory should be kept private (mail
files, for instance). See umask.

If the mkdir(2) syscall is not built into your C library, Perl emulates it by
calling the mkdir(1) program for each directory. If you are
creating a long list of directories on such a system, it''ll be more
efficient to call the mkdir program yourself with the list of
directories than it is to start zillions of subprocesses.

29.2.95. msgctl

msgctl ID, CMD, ARG

This function is available only on machines supporting System V IPC,
which turns out to be far fewer than those supporting sockets.

29.2.96. msgget

msgget KEY, FLAGS

This function is available only on machines supporting System V IPC.

29.2.97. msgrcv

msgrcv ID, VAR, SIZE, TYPE, FLAGS

This function is available only on machines supporting System V IPC.

29.2.98. msgsnd

msgsnd ID, MSG, FLAGS

$msg = pack "L a*", $type, $text_of_message;

This function is available only on machines supporting System V IPC.

29.2.99. my

my TYPE EXPR : ATTRIBUTES
my EXPR : ATTRIBUTES
my TYPE EXPR
my EXPR

The variable name cannot be package qualified, because package
variables are all globally accessible through their corresponding
symbol table, and lexical variables are unrelated to any symbol table.
Unlike local, then, this operator has nothing to do with global
variables, other than hiding any other variable of the same name from
view within its scope (that is, where the private variable exists). A
global variable can always be accessed through its package-qualified
form, however, or through a symbolic reference.

A private variable''s scope does not start until the statement after its
declaration. The variable''s scope extends into any enclosed blocks
thereafter, up to the end of the scope of the variable itself.

However, this means that any subroutines you call from within
the scope of a private variable cannot see the private variable unless
the block that defines the subroutine itself is also textually enclosed
within the scope of that variable. That sounds complicated, but it''s
not once you get the hang of it. The technical term for this is
lexical scoping, so we often call these lexical variables. In C
culture, they''re sometimes called "auto" variables, since they''re automatically
allocated and deallocated at scope entry and exit.

The EXPR may be assigned to if desired, which allows you to
initialize your lexical variables. (If no initializer is given, all
scalars are initialized to the undefined value and all arrays and
hashes to the empty list.) As with ordinary assignment, if you use
parentheses around the variables on the left (or if the variable is an
array or hash), the expression on the right is evaluated in list
context. Otherwise, the expression on the right is evaluated in scalar
context. For example, you can name your formal subroutine parameters
with a list assignment, like this:

my ($friends, $romans, $countrymen) = @_;

my $country = @_;  # right or wrong?

sub simple_as {
my $self = shift;   # scalar assignment
my ($a,$b,$c) = @_; # list assignment
...
}

The TYPE and
ATTRIBUTES are optional, which is just as
well, since they''re both considered experimental. Here''s what a
declaration that uses them might look like:

my Dog $spot :ears(short) :tail(long);

my Dog $lassie = new Collie;

Interestingly, up through version 5.6.0, the only time Perl pays
attention to the TYPE declaration is when
the corresponding class
has declared fields with the use fields
pragma. Together, these
declarations allow the pseudohash implementation of a class to "show
through" to code outside the class, so that hash lookups can be
optimized by the compiler into array lookups. In a sense, the
pseudohash is the interface to such a class, so
our theory remains
intact, if a bit battered. For more on pseudohashes, see the section
"Pseudohashes" in Chapter 8, "References".

In the future, other types of classes may interpret the
TYPE differently. The
TYPE declaration should be considered a
generic type interface that might someday be instantiated in various
ways depending on the class. In fact, the
TYPE might not even be an official class
name. We''re reserving the lowercase type names for Perl, because one
of the ways we''d like to extend the type interface is to allow
optional low-level type declarations such as int,
num, str, and
ref. These declarations will not be for the
purpose of strong typing; rather, they''ll be hints to the compiler
telling it to optimize the storage of the variable with the assumption
that the variable will be used mostly as declared. The semantics of
scalars will stay pretty much the same--you''ll still be able to
add two str scalars, or print an
int scalar, just as though they were the ordinary
polymorphic scalars you''re familiar with. But with an
int declaration Perl might decide to store only the
integer value and forget about caching the resulting string as it
currently does. Loops with int loop variables
might run faster, particularly in code compiled down to C. In
particular, arrays of numbers could be stored much more compactly. As
a limiting case, the built-in vec function might
even become obsolete when we can write declarations such as:

my bit @bitstring;

The ATTRIBUTES declaration is even more
experimental. We haven''t
done much more than reserve the syntax and prototype the internal
interface; see the use attributes pragma in
Chapter 31, "Pragmatic Modules" for more on
that. The first attribute we''ll implement is likely to be
constant:

my num $PI : constant = atan2(1,1) * 4;

See also local, our, and the
section "Scoped Declarations" in
Chapter 4, "Statements and Declarations".

29.2.100. new

new CLASSNAME LIST
new CLASSNAME

29.2.101. next

next LABEL
next

LINE: while (<STDIN>) {
next LINE if /^#/;     # discard comments
...
}

A block by itself is semantically identical to a loop
that executes once. Thus, next will exit such a block early
(via the continue block, if there is one).

next cannot be used to exit a block that returns a
value, such as eval {}, sub {},
or do {}, and should not be used to exit a
grep or map operation. With
warnings enabled, Perl will warn you if you next
out of a loop not in your current lexical scope, such as a loop in a
calling subroutine. See the section "Loop Statements" in
Chapter 4, "Statements and Declarations".

29.2.102. no

no MODULE LIST

29.2.103. oct

oct EXPR
oct

$val = oct $val if $val =~ /^0/;

$perms = (stat("filename"))[2] & 07777;
$oct_perms = sprintf "%lo", $perms;

29.2.104. open

open FILEHANDLE, MODE, LIST
open FILEHANDLE, EXPR
open FILEHANDLE

If only two arguments are present, the mode and filename/command are
assumed to be combined in the second argument. (And if you don''t
specify a mode in the second argument, just a filename, then the file
is opened read-only to be on the safe side.)

With only one argument, the package scalar variable of the same name as
the FILEHANDLE must contain the filename and optional mode:

$LOG = ">logfile";        # $LOG must not be declared my!
open LOG or die "Can''t open logfile: $!";

The open function returns true when it succeeds and undef
otherwise. If the open starts up a pipe to a child process, the
return value will be the process ID of that new process. As with
any syscall, always check the return value of open to make sure it
worked. But this isn''t C or Java, so don''t use an if statement when
the or operator will do. You can also use ||, but if you do, use
parentheses on the open. If you choose to omit parentheses on the
function call to turn it into a list operator, be careful to use "or die" after the list rather than "|| die", because the precedence of
|| is higher than list operators like open, and the || will
bind to your last argument, not the whole open:

open LOG, ">logfile" || die "Can''t create logfile: $!";  # WRONG
open LOG, ">logfile" or die "Can''t create logfile: $!";  # ok

open LOG, ">logfile"
or die "Can''t create logfile: $!";

{
my $fh;                   # (uninitialized)
open($fh, ">logfile")     # $fh is autovivified
or die "Can''t create logfile: $!";
...                       # do stuff with $fh
}                                 # $fh closed here

open my $fh, ">logfile" or die ...

open(LOG, ">", "logfile")  or die "Can''t create logfile: $!";

The modes that indicate how to open a file are shell-like redirection
symbols. A list of these symbols is provided in Table 29-1.
(To access a file with combinations of open modes not covered by
this table, see the low-level sysopen function.)

Table 29.1. Modes for open

If the mode is "<" or nothing, an existing file
is opened for input. If the mode is ">", the
file is opened for output, which truncates existing files and creates
nonexistent ones. If the mode is ">>",
the file is created if needed and opened for appending, and all output
is automatically placed at the end of the file. If a new file is created
because you used a mode of ">" or ">>" and the
file did not previously exist, access permissions will depend on the
process''s current umask under the rules described for that
function.

Here are common examples:

open(INFO,      "datafile")  || die("can''t open datafile: $!");
open(INFO,    "< datafile")  || die("can''t open datafile: $!");
open(RESULTS, "> runstats")  || die("can''t open runstats: $!");
open(LOG,    ">> logfile ")  || die("can''t open logfile:  $!");

open INFO,      "datafile"   or die "can''t open datafile: $!";
open INFO,    "< datafile"   or die "can''t open datafile: $!";
open RESULTS, "> runstats"   or die "can''t open runstats: $!";
open LOG,    ">> logfile "   or die "can''t open logfile:  $!";

open(INPUT,  "-" ) or die;     # re-open standard input for reading
open(INPUT,  "<-") or die;     # same thing, but explicit
open(OUTPUT, ">-") or die;     # re-open standard output for writing

You may also place a "+" in front of any of these three modes
to request simultaneous read and write. However, whether the file
is clobbered or created and whether it must already exist is still
governed by your choice of less-than or greater-than signs. This
means that "+<" is almost always preferred for read/write
updates, as the dubious "+>" mode would first clobber the
file before you could ever read anything from it. (Use that mode
only if you want to reread only what you just wrote.)

open(DBASE, "+< database")
or die "can''t open existing database in update mode: $!";

If the leading character in EXPR is a pipe symbol, open fires
up a new process and connects a write-only filehandle to the
command. This way you can write into that handle and what you
write will show up on that command''s standard input. For example:

open(PRINTER, "| lpr -Plp1")    or die "can''t fork: $!";
print PRINTER "stuff\n";
close(PRINTER)                  or die "lpr/close failed: $?/$!";

open(NET, "netstat -i -n |")    or die "can''t fork: $!";
while (<NET>) { ... }
close(NET)                      or die "can''t close netstat: $!/$?";

Any pipe command containing shell metacharacters such as wildcards
or I/O redirections is passed to your system''s canonical shell
(/bin/sh on Unix), so those shell-specific constructs can be
processed first. If no metacharacters are found, Perl launches the
new process itself without calling the shell.

You may also use the three-argument form to start up pipes.
Using that style, the equivalent of the previous pipe opens would be:

open(PRINTER, "|-", "lpr -Plp1")    or die "can''t fork: $!";
open(NET, "-|", "netstat -i -n")    or die "can''t fork: $!";

open(PRINTER, "|-", "lpr", "-Plp1")    or die "can''t fork: $!";
open(NET, "-|", "netstat", "-i", "-n") or die "can''t fork: $!";

defined($pid = open(FROM_CHILD, "-|"))
or die "can''t fork: $!";
if ($pid) {
@parent_lines = <FROM_CHILD>;  # parent code
}
else {
print STDOUT @child_lines;     # child code
}

open FH,            "| tr   ''a-z''  ''A-Z''";        # pipe to shell command
open FH, "|-",        ''tr'', ''a-z'', ''A-Z'';         # pipe to bare command
open FH, "|-" or exec ''tr'', ''a-z'', ''A-Z'' or die;  # pipe to child

open FH,              "cat    -n   ''file'' |";     # pipe from shell command
open FH, "-|",        ''cat'', ''-n'', ''file'';        # pipe from bare command
open FH, "-|" or exec ''cat'', ''-n'', ''file'' or die; # pipe from child

[7]Or you can think of it as
leaving the command off of the three-argument forms above.

When starting a command with open, you must choose
either input or output: "cmd|" for reading or
"|cmd" for writing. You may not use
open to start a command that pipes both in and out,
as the (currently) illegal notation, "|cmd|", might
appear to indicate. However, the standard
IPC::Open2 and IPC::Open3
library routines give you a close equivalent. For details on
double-ended pipes, see the section "Bidirectional Communication" in
Chapter 16, "Interprocess Communication".

You may also, in the Bourne shell tradition, specify an
EXPR beginning with
>&, in which case the rest of the string is
interpreted as the name of a filehandle (or file descriptor, if
numeric) to be duplicated using the
dup2(2) syscall.[8] You may use & after
>, >>,
<, +>,
+>>, and +<. (The
specified mode should match the mode of the original filehandle.)

[8]This
doesn''t (currently) work with I/O objects on typeglob references by
filehandle autovivification, but you can always use
fileno to fetch the file descriptor and dup
that.

One reason you might want to do this would be if you already had a
filehandle open and wanted to make another handle that''s really a
duplicate of the first one.

open(SAVEOUT, ">&SAVEERR") or die "couldn''t dup SAVEERR: $!";
open(MHCONTEXT, "<&4")     or die "couldn''t dup fd4: $!";

somefunction("&main::LOGFILE");

#!/usr/bin/perl
open SAVEOUT, ">&STDOUT";
open SAVEERR, ">&STDERR";
open STDOUT, ">foo.out" or die "Can''t redirect stdout";
open STDERR, ">&STDOUT" or die "Can''t dup stdout";
select STDERR; $| = 1;         # enable autoflush
select STDOUT; $| = 1;         # enable autoflush
print STDOUT "stdout 1\n";     # these I/O streams propagate to
print STDERR "stderr 1\n";     # subprocesses too
system("some command");        # uses new stdout/stderr
close STDOUT;
close STDERR;
open STDOUT, ">&SAVEOUT";
open STDERR, ">&SAVEERR";
print STDOUT "stdout 2\n";
print STDERR "stderr 2\n";

$fd = $ENV{"MHCONTEXTFD"};
open(MHCONTEXT, "<&=$fdnum")
or die "couldn''t fdopen descriptor $fdnum: $!";

use Fcntl qw(F_GETFD F_SETFD);
$flags = fcntl(FH, F_SETFD, 0)
or die "Can''t clear close-on-exec flag on FH: $!\n";

With the one- or two-argument form of open, you
have to be careful when you use a string variable as a filename, since
the variable may contain arbitrarily weird characters (particularly
when the filename has been supplied by arbitrarily weird characters on
the Internet). If you''re not careful, parts of the filename might get
interpreted as a MODE string, ignorable
whitespace, a dup specification, or a minus. Here''s one historically
interesting way to insulate yourself:

$path =~ s#^(\s)#./$1#;
open (FH, "< $path\0") or die "can''t open $path: $!";

open(FH, "<", $path) or die "can''t open $path: $!";

use Fcntl;
sysopen(FH, $path, O_RDONLY) or die "can''t open $path: $!";

Systems that need the binmode
function are distinguished from those that don''t by the format used
for text files. Those that don''t need it terminate each line with a
single character that corresponds to what C thinks is a newline,
\n. Unix and Mac OS fall into this category. VMS,
MVS, MS-whatever, and S&M operating systems of other varieties
treat I/O on text files and binary files differently, so they need
binmode.

Or its equivalent. As of the 5.6 release of Perl, you can specify
binary mode in the open function without a separate
call to binmode. As part of the
MODE argument (but only in the
three-argument form), you may specify various input and output
disciplines. To do the equivalent of a binmode,
use the three argument form of open and stuff a
discipline of :raw in after the other
MODE characters:

open(FH, "<:raw", $path) or die "can''t open $path: $!";

Table 29.2. I/O Disciplines

You''ll be able to stack disciplines that make sense to stack, so, for
instance, you could say:

open(FH, "<:para:crlf:uni", $path) or die "can''t open $path: $!";
while ($para = <FH>) { ... }

• 
  

  read in some form of Unicode and translate to Perl''s internal UTF-8 format
  if the file isn''t already in UTF-8,



• 
  

  look for variants of line-ending sequences, translating them all to \n, and



• 
  

  process the file into paragraph-sized chunks, much as $/ = " does.

If you want to set the default open mode (:def) to something other
than :text, you can declare that at the top of your file with the open pragma:

use open IN => ":any", OUT => ":utf8";

29.2.105. opendir

opendir DIRHANDLE, EXPR

29.2.106. ord

ord EXPR
ord

29.2.107. our

our TYPE EXPR : ATTRIBUTES
our EXPR : ATTRIBUTES
our TYPE EXPR
our EXPR

The primary use of an our declaration is to hide the variable from
the effects of a use strict "vars" declaration; since the variable
is masquerading as a my variable, you are permitted to use the
declared global variable without qualifying it with its package.
However, just like the my variable, this only works within the
lexical scope of the our declaration. In this respect, it differs
from use vars, which affects the entire package and is not lexically
scoped.

our is also like my in that you are allowed to declare variables
with a TYPE and with ATTRIBUTES. Here is the syntax:

our Dog $spot :ears(short) :tail(long);

Another way in which our is like my is in its visibility.
An our declaration declares a global variable that will be visible
across its entire lexical scope, even across package boundaries. The
package in which the variable is located is determined at the point
of the declaration, not at the point of use. This means the following
behavior holds and is deemed to be a feature:

package Foo;
our $bar;      # $bar is $Foo::bar for rest of lexical scope
$bar = 582;
package Bar;
print $bar;    # prints 582, just as if "our" had been "my"

($x, $y) = ("one", "two");
print "before block, x is $x, y is $y\n";
{
our $x = 10;
local our $y = 20;
print "in block, x is $x, y is $y\n";
}
print "past block, x is $x, y is $y\n";

before block, x is one, y is two
in block, x is 10, y is 20
past block, x is 10, y is two

use warnings;
package Foo;
our $bar;          # declares $Foo::bar for rest of lexical scope
$bar = 20;
package Bar;
our $bar = 30;     # declares $Bar::bar for rest of lexical scope
print $bar;        # prints 30
our $bar;          # emits warning

29.2.108. pack

pack TEMPLATE, LIST

The template describes the structure of the string as a sequence of
fields. Each field is represented by a single character that
describes the type of the value and its encoding. For instance, a
format character of N specifies an unsigned
four-byte integer in big-endian byte order.

Fields are packed in the order given in the template.
For example, to pack an unsigned one-byte integer and a
single-precision floating-point value into a string, you''d say:

$string = pack("Cf", 244, 3.14);

Some important things to consider when packing are:

• 
  

  the type of data (such as integer or float or string),



• 
  

  the range of values (such as whether your integers will fit into one,
  two, four, or maybe even eight bytes; or whether you''re packing 8-bit
  or Unicode characters),



• 
  

  whether your integers are signed or unsigned, and



• 
  

  the encoding to use (such as native, little-endian, or big-endian packing of
  bits and bytes).

Table 29-3 lists the format characters and their meanings. (Other characters
can occur in formats as well; these are described later.)

Table 29.3. Template Characters for pack/unpack