perlfunc
Hurricane Electric Internet Services
NAME
perlfunc - Perl builtin functions
DESCRIPTION
The functions in this section can serve as terms in an
expression. They fall into two major categories: list
operators and named unary operators. These differ in
their precedence relationship with a following comma.
(See the precedence table in the perlop manpage.) List
operators take more than one argument, while unary
operators can never take more than one argument. Thus, a
comma terminates the argument of a unary operator, but
merely separates the arguments of a list operator. A
unary operator generally provides a scalar context to its
argument, while a list operator may provide either scalar
and list contexts for its arguments. If it does both, the
scalar arguments will be first, and the list argument will
follow. (Note that there can ever be only one list
argument.) For instance, splice() has three scalar
arguments followed by a list.
In the syntax descriptions that follow, list operators
that expect a list (and provide list context for the
elements of the list) are shown with LIST as an argument.
Such a list may consist of any combination of scalar
arguments or list values; the list values will be included
in the list as if each individual element were
interpolated at that point in the list, forming a longer
single-dimensional list value. Elements of the LIST
should be separated by commas.
Any function in the list below may be used either with or
without parentheses around its arguments. (The syntax
descriptions omit the parentheses.) If you use the
parentheses, the simple (but occasionally surprising) rule
is this: It LOOKS like a function, therefore it IS a
function, and precedence doesn't matter. Otherwise it's a
list operator or unary operator, and precedence does
matter. And whitespace between the function and left
parenthesis doesn't count--so you need to be careful
sometimes:
print 1+2+4; # Prints 7.
print(1+2) + 4; # Prints 3.
print (1+2)+4; # Also prints 3!
print +(1+2)+4; # Prints 7.
print ((1+2)+4); # Prints 7.
If you run Perl with the -w switch it can warn you about
this. For example, the third line above produces:
print (...) interpreted as function at - line 1.
Useless use of integer addition in void context at - line 1.
For functions that can be used in either a scalar or list
context, nonabortive failure is generally indicated in a
scalar context by returning the undefined value, and in a
list context by returning the null list.
Remember the following rule:
THERE IS NO GENERAL RULE FOR CONVERTING A LIST INTO A
SCALAR!
Each operator and function decides which sort of value it
would be most appropriate to return in a scalar context.
Some operators return the length of the list that would
have been returned in a list context. Some operators
return the first value in the list. Some operators return
the last value in the list. Some operators return a count
of successful operations. In general, they do what you
want, unless you want consistency.
Perl Functions by Category
Here are Perl's functions (including things that look like
functions, like some of the keywords and named operators)
arranged by category. Some functions appear in more than
one place.
Functions for SCALARs or strings
chomp, chop, chr, crypt, hex, index, lc, lcfirst,
length, oct, ord, pack, q/STRING/, qq/STRING/,
reverse, rindex, sprintf, substr, tr///, uc, ucfirst,
y///
Regular expressions and pattern matching
m//, pos, quotemeta, s///, split, study
Numeric functions
abs, atan2, cos, exp, hex, int, log, oct, rand, sin,
sqrt, srand
Functions for real @ARRAYs
pop, push, shift, splice, unshift
Functions for list data
grep, join, map, qw/STRING/, reverse, sort, unpack
Functions for real %HASHes
delete, each, exists, keys, values
Input and output functions
binmode, close, closedir, dbmclose, dbmopen, die,
eof, fileno, flock, format, getc, print, printf,
read, readdir, rewinddir, seek, seekdir, select,
syscall, sysread, sysseek, syswrite, tell, telldir,
truncate, warn, write
Functions for fixed length data or records
pack, read, syscall, sysread, syswrite, unpack, vec
Functions for filehandles, files, or directories
-X, chdir, chmod, chown, chroot, fcntl, glob, ioctl,
link, lstat, mkdir, open, opendir, readlink, rename,
rmdir, stat, symlink, umask, unlink, utime
Keywords related to the control flow of your perl program
caller, continue, die, do, dump, eval, exit, goto,
last, next, redo, return, sub, wantarray
Keywords related to scoping
caller, import, local, my, package, use
Miscellaneous functions
defined, dump, eval, formline, local, my, reset,
scalar, undef, wantarray
Functions for processes and process groups
alarm, exec, fork, getpgrp, getppid, getpriority,
kill, pipe, qx/STRING/, setpgrp, setpriority, sleep,
system, times, wait, waitpid
Keywords related to perl modules
do, import, no, package, require, use
Keywords related to classes and object-orientedness
bless, dbmclose, dbmopen, package, ref, tie, tied,
untie, use
Low-level socket functions
accept, bind, connect, getpeername, getsockname,
getsockopt, listen, recv, send, setsockopt, shutdown,
socket, socketpair
System V interprocess communication functions
msgctl, msgget, msgrcv, msgsnd, semctl, semget,
semop, shmctl, shmget, shmread, shmwrite
Fetching user and group info
endgrent, endhostent, endnetent, endpwent, getgrent,
getgrgid, getgrnam, getlogin, getpwent, getpwnam,
getpwuid, setgrent, setpwent
Fetching network info
endprotoent, endservent, gethostbyaddr,
gethostbyname, gethostent, getnetbyaddr,
getnetbyname, getnetent, getprotobyname,
getprotobynumber, getprotoent, getservbyname,
getservbyport, getservent, sethostent, setnetent,
setprotoent, setservent
Time-related functions
gmtime, localtime, time, times
Functions new in perl5
abs, bless, chomp, chr, exists, formline, glob,
import, lc, lcfirst, map, my, no, prototype, qx, qw,
readline, readpipe, ref, sub*, sysopen, tie, tied,
uc, ucfirst, untie, use
* - sub was a keyword in perl4, but in perl5 it is an
operator which can be used in expressions.
Functions obsoleted in perl5
dbmclose, dbmopen
Alphabetical Listing of Perl Functions
-X FILEHANDLE
-X EXPR
-X A file test, where X is one of the letters listed
below. This unary operator takes one argument,
either a filename or a filehandle, and tests the
associated file to see if something is true about
it. If the argument is omitted, tests $_, except
for -t, which tests STDIN. Unless otherwise
documented, it returns 1 for TRUE and '' for
FALSE, or the undefined value if the file doesn't
exist. Despite the funny names, precedence is the
same as any other named unary operator, and the
argument may be parenthesized like any other unary
operator. The operator may be any of:
-r File is readable by effective uid/gid.
-w File is writable by effective uid/gid.
-x File is executable by effective uid/gid.
-o File is owned by effective uid.
-R File is readable by real uid/gid.
-W File is writable by real uid/gid.
-X File is executable by real uid/gid.
-O File is owned by real uid.
-e File exists.
-z File has zero size.
-s File has nonzero size (returns size).
-f File is a plain file.
-d File is a directory.
-l File is a symbolic link.
-p File is a named pipe (FIFO).
-S File is a socket.
-b File is a block special file.
-c File is a character special file.
-t Filehandle is opened to a tty.
-u File has setuid bit set.
-g File has setgid bit set.
-k File has sticky bit set.
-T File is a text file.
-B File is a binary file (opposite of -T).
-M Age of file in days when script started.
-A Same for access time.
-C Same for inode change time.
The interpretation of the file permission
operators -r, -R, -w, -W, -x, and -X is based
solely on the mode of the file and the uids and
gids of the user. There may be other reasons you
can't actually read, write or execute the file.
Also note that, for the superuser, -r, -R, -w, and
-W always return 1, and -x and -X return 1 if any
execute bit is set in the mode. Scripts run by
the superuser may thus need to do a stat() to
determine the actual mode of the file, or
temporarily set the uid to something else.
Example:
while (<>) {
chop;
next unless -f $_; # ignore specials
...
}
Note that -s/a/b/ does not do a negated
substitution. Saying -exp($foo) still works as
expected, however--only single letters following a
minus are interpreted as file tests.
The -T and -B switches work as follows. The first
block or so of the file is examined for odd
characters such as strange control codes or
characters with the high bit set. If too many odd
characters (>30%) are found, it's a -B file,
otherwise it's a -T file. Also, any file
containing null in the first block is considered a
binary file. If -T or -B is used on a filehandle,
the current stdio buffer is examined rather than
the first block. Both -T and -B return TRUE on a
null file, or a file at EOF when testing a
filehandle. Because you have to read a file to do
the -T test, on most occasions you want to use a
-f against the file first, as in next unless -f
$file && -T $file.
If any of the file tests (or either the stat() or
lstat() operators) are given the special
filehandle consisting of a solitary underline,
then the stat structure of the previous file test
(or stat operator) is used, saving a system call.
(This doesn't work with -t, and you need to
remember that lstat() and -l will leave values in
the stat structure for the symbolic link, not the
real file.) Example:
print "Can do.\n" if -r $a || -w _ || -x _;
stat($filename);
print "Readable\n" if -r _;
print "Writable\n" if -w _;
print "Executable\n" if -x _;
print "Setuid\n" if -u _;
print "Setgid\n" if -g _;
print "Sticky\n" if -k _;
print "Text\n" if -T _;
print "Binary\n" if -B _;
abs VALUE
abs Returns the absolute value of its argument. If
VALUE is omitted, uses $_.
accept NEWSOCKET,GENERICSOCKET
Accepts an incoming socket connect, just as the
accept(2) system call does. Returns the packed
address if it succeeded, FALSE otherwise. See
example in the section on Sockets: Client/Server
Communication in the perlipc manpage.
alarm SECONDS
alarm Arranges to have a SIGALRM delivered to this
process after the specified number of seconds have
elapsed. If SECONDS is not specified, the value
stored in $_ is used. (On some machines,
unfortunately, the elapsed time may be up to one
second less than you specified because of how
seconds are counted.) Only one timer may be
counting at once. Each call disables the previous
timer, and an argument of 0 may be supplied to
cancel the previous timer without starting a new
one. The returned value is the amount of time
remaining on the previous timer.
For delays of finer granularity than one second,
you may use Perl's syscall() interface to access
setitimer(2) if your system supports it, or else
see the select() entry elsewhere in this document
. It is usually a mistake to intermix alarm() and
sleep() calls.
If you want to use alarm() to time out a system
call you need to use an eval/die pair. You can't
rely on the alarm causing the system call to fail
with $! set to EINTR because Perl sets up signal
handlers to restart system calls on some systems.
Using eval/die always works.
eval {
local $SIG{ALRM} = sub { die "alarm\n" }; # NB \n required
alarm $timeout;
$nread = sysread SOCKET, $buffer, $size;
alarm 0;
};
die if $@ && $@ ne "alarm\n"; # propagate errors
if ($@) {
# timed out
}
else {
# didn't
}
atan2 Y,X
Returns the arctangent of Y/X in the range -pi to
pi.
For the tangent operation, you may use the
POSIX::tan() function, or use the familiar
relation:
sub tan { sin($_[0]) / cos($_[0]) }
bind SOCKET,NAME
Binds a network address to a socket, just as the
bind system call does. Returns TRUE if it
succeeded, FALSE otherwise. NAME should be a
packed address of the appropriate type for the
socket. See the examples in the section on
Sockets: Client/Server Communication in the
perlipc manpage.
binmode FILEHANDLE
Arranges for the file to be read or written in
"binary" mode in operating systems that
distinguish between binary and text files. Files
that are not in binary mode have CR LF sequences
translated to LF on input and LF translated to CR
LF on output. Binmode has no effect under Unix;
in MS-DOS and similarly archaic systems, it may be
imperative--otherwise your MS-DOS-damaged C
library may mangle your file. The key distinction
between systems that need binmode and those that
don't is their text file formats. Systems like
Unix and Plan9 that delimit lines with a single
character, and that encode that character in C as
'\n', do not need binmode. The rest need it. If
FILEHANDLE is an expression, the value is taken as
the name of the filehandle.
bless REF,CLASSNAME
bless REF
This function tells the thingy referenced by REF
that it is now an object in the CLASSNAME
package--or the current package if no CLASSNAME is
specified, which is often the case. It returns
the reference for convenience, because a bless()
is often the last thing in a constructor. Always
use the two-argument version if the function doing
the blessing might be inherited by a derived
class. See the perlobj manpage for more about the
blessing (and blessings) of objects.
caller EXPR
caller Returns the context of the current subroutine
call. In a scalar context, returns the caller's
package name if there is a caller, that is, if
we're in a subroutine or eval() or require(), and
the undefined value otherwise. In a list context,
returns
($package, $filename, $line) = caller;
With EXPR, it returns some extra information that
the debugger uses to print a stack trace. The
value of EXPR indicates how many call frames to go
back before the current one.
($package, $filename, $line, $subroutine,
$hasargs, $wantarray, $evaltext, $is_require) = caller($i);
Here $subroutine may be "(eval)" if the frame is
not a subroutine call, but an eval. In such a
case additional elements $evaltext and $is_require
are set: $is_require is true if the frame is
created by a require or use statement, $evaltext
contains the text of the eval EXPR statement. In
particular, for a eval BLOCK statement, $filename
is "(eval)", but $evaltext is undefined. (Note
also that each use statement creates a require
frame inside an eval EXPR) frame.
Furthermore, when called from within the DB
package, caller returns more detailed information:
it sets the list variable @DB::args to be the
arguments with which the subroutine was invoked.
chdir EXPR
Changes the working directory to EXPR, if
possible. If EXPR is omitted, changes to home
directory. Returns TRUE upon success, FALSE
otherwise. See example under die().
chmod LIST
Changes the permissions of a list of files. The
first element of the list must be the numerical
mode, which should probably be an octal number,
and which definitely should not a string of octal
digits: 0644 is okay, '0644' is not. Returns the
number of files successfully changed. See also
the oct entry elsewhere in this document if all
you have is a string.
$cnt = chmod 0755, 'foo', 'bar';
chmod 0755, @executables;
$mode = '0644'; chmod $mode, 'foo'; # !!! sets mode to --w----r-T
$mode = '0644'; chmod oct($mode), 'foo'; # this is better
$mode = 0644; chmod $mode, 'foo'; # this is best
chomp VARIABLE
chomp LIST
chomp This is a slightly safer version of the chop entry
elsewhere in this document . It removes any line
ending that corresponds to the current value of $/
(also known as $INPUT_RECORD_SEPARATOR in the
English module). It returns the total number of
characters removed from all its arguments. It's
often used to remove the newline from the end of
an input record when you're worried that the final
record may be missing its newline. When in
paragraph mode ($/ = ""), it removes all trailing
newlines from the string. If VARIABLE is omitted,
it chomps $_. Example:
while (<>) {
chomp; # avoid \n on last field
@array = split(/:/);
...
}
You can actually chomp anything that's an lvalue,
including an assignment:
chomp($cwd = `pwd`);
chomp($answer = <STDIN>);
If you chomp a list, each element is chomped, and
the total number of characters removed is
returned.
chop VARIABLE
chop LIST
chop Chops off the last character of a string and
returns the character chopped. It's used
primarily to remove the newline from the end of an
input record, but is much more efficient than
s/\n// because it neither scans nor copies the
string. If VARIABLE is omitted, chops $_.
Example:
while (<>) {
chop; # avoid \n on last field
@array = split(/:/);
...
}
You can actually chop anything that's an lvalue,
including an assignment:
chop($cwd = `pwd`);
chop($answer = <STDIN>);
If you chop a list, each element is chopped. Only
the value of the last chop is returned.
Note that chop returns the last character. To
return all but the last character, use
substr($string, 0, -1).
chown LIST
Changes the owner (and group) of a list of files.
The first two elements of the list must be the
NUMERICAL uid and gid, in that order. Returns the
number of files successfully changed.
$cnt = chown $uid, $gid, 'foo', 'bar';
chown $uid, $gid, @filenames;
Here's an example that looks up nonnumeric uids in
the passwd file:
print "User: ";
chop($user = <STDIN>);
print "Files: "
chop($pattern = <STDIN>);
($login,$pass,$uid,$gid) = getpwnam($user)
or die "$user not in passwd file";
@ary = <${pattern}>; # expand filenames
chown $uid, $gid, @ary;
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.
chr NUMBER
chr Returns the character represented by that NUMBER
in the character set. For example, chr(65) is "A"
in ASCII. For the reverse, use the ord entry
elsewhere in this document .
If NUMBER is omitted, uses $_.
chroot FILENAME
chroot This function works as the system call by the same
name: it makes the named directory the new root
directory for all further pathnames that begin
with a "/" by your process and all of its
children. (It doesn't change your current working
directory, which is unaffected.) For security
reasons, this call is restricted to the superuser.
If FILENAME is omitted, does chroot to $_.
close FILEHANDLE
Closes the file or pipe associated with the file
handle, returning TRUE only if stdio successfully
flushes buffers and closes the system file
descriptor. If the file handle came from a piped
open close will additionally return FALSE if one
of the other system calls involved fails or if the
program exits with non-zero status. (If the
problem was that the program exited non-zero $!
will be set to 0.) You don't have to close
FILEHANDLE if you are immediately going to do
another open() on it, because open() will close it
for you. (See open().) However, an explicit
close on an input file resets the line counter
($.), while the implicit close done by open() does
not. Also, closing a pipe will wait for the
process executing on the pipe to complete, in case
you want to look at the output of the pipe
afterwards. Closing a pipe explicitly also puts
the status value of the command into $?. Example:
open(OUTPUT, '|sort >foo'); # pipe to sort
... # print stuff to output
close OUTPUT; # wait for sort to finish
open(INPUT, 'foo'); # get sort's results
FILEHANDLE may be an expression whose value gives
the real filehandle name.
closedir DIRHANDLE
Closes a directory opened by opendir().
connect SOCKET,NAME
Attempts to connect to a remote socket, just as
the connect system call does. Returns TRUE if it
succeeded, FALSE otherwise. NAME should be a
packed address of the appropriate type for the
socket. See the examples in the section on
Sockets: Client/Server Communication in the
perlipc manpage.
continue BLOCK
Actually a flow control statement rather than a
function. If there is a continue BLOCK attached
to a BLOCK (typically in a while or foreach), it
is always executed just before the conditional is
about to be evaluated again, just like the third
part of a for loop in C. Thus it can be used to
increment a loop variable, even when the loop has
been continued via the next statement (which is
similar to the C continue statement).
cos EXPR
Returns the cosine of EXPR (expressed in radians).
If EXPR is omitted takes cosine of $_.
For the inverse cosine operation, you may use the
POSIX::acos() function, or use this relation:
sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
crypt PLAINTEXT,SALT
Encrypts a string exactly like the crypt(3)
function in the C library (assuming that you
actually have a version there that has not been
extirpated as a potential munition). This can
prove useful for checking the password file for
lousy passwords, amongst other things. Only the
guys wearing white hats should do this.
Note that crypt is intended to be a one-way
function, much like breaking eggs to make an
omelette. There is no (known) corresponding
decrypt function. As a result, this function
isn't all that useful for cryptography. (For
that, see your nearby CPAN mirror.)
Here's an example that makes sure that whoever
runs this program knows their own password:
$pwd = (getpwuid($<))[1];
$salt = substr($pwd, 0, 2);
system "stty -echo";
print "Password: ";
chop($word = <STDIN>);
print "\n";
system "stty echo";
if (crypt($word, $salt) ne $pwd) {
die "Sorry...\n";
} else {
print "ok\n";
}
Of course, typing in your own password to whomever
asks you for it is unwise.
dbmclose HASH
[This function has been superseded by the untie()
function.]
Breaks the binding between a DBM file and a hash.
dbmopen HASH,DBNAME,MODE
[This function has been superseded by the tie()
function.]
This binds a dbm(3), ndbm(3), sdbm(3), gdbm(), or
Berkeley DB file to a hash. HASH is the name of
the hash. (Unlike normal open, the first argument
is NOT a filehandle, even though it looks like
one). DBNAME is the name of the database (without
the .dir or .pag extension if any). If the
database does not exist, it is created with
protection specified by MODE (as modified by the
umask()). If your system supports only the older
DBM functions, you may perform only one dbmopen()
in your program. In older versions of Perl, if
your system had neither DBM nor ndbm, calling
dbmopen() produced a fatal error; it now falls
back to sdbm(3).
If you don't have write access to the DBM file,
you can only read hash variables, not set them.
If you want to test whether you can write, either
use file tests or try setting a dummy hash entry
inside an eval(), which will trap the error.
Note that functions such as keys() and values()
may return huge array values when used on large
DBM files. You may prefer to use the each()
function to iterate over large DBM files.
Example:
# print out history file offsets
dbmopen(%HIST,'/usr/lib/news/history',0666);
while (($key,$val) = each %HIST) {
print $key, ' = ', unpack('L',$val), "\n";
}
dbmclose(%HIST);
See also the AnyDBM_File manpage for a more
general description of the pros and cons of the
various dbm approaches, as well as the DB_File
manpage for a particularly rich implementation.
defined EXPR
defined Returns a Boolean value telling whether EXPR has a
value other than the undefined value undef. If
EXPR is not present, $_ will be checked.
Many operations return undef to indicate failure,
end of file, system error, uninitialized variable,
and other exceptional conditions. This function
allows you to distinguish undef from other values.
(A simple Boolean test will not distinguish among
undef, zero, the empty string, and "0", which are
all equally false.) Note that since undef is a
valid scalar, its presence doesn't necessarily
indicate an exceptional condition: pop() returns
undef when its argument is an empty array, or when
the element to return happens to be undef.
You may also use defined() to check whether a
subroutine exists. On the other hand, use of
defined() upon aggregates (hashes and arrays) is
not guaranteed to produce intuitive results, and
should probably be avoided.
When used on a hash element, it tells you whether
the value is defined, not whether the key exists
in the hash. Use the exists entry elsewhere in
this document for the latter purpose.
Examples:
print if defined $switch{'D'};
print "$val\n" while defined($val = pop(@ary));
die "Can't readlink $sym: $!"
unless defined($value = readlink $sym);
sub foo { defined &$bar ? &$bar(@_) : die "No bar"; }
$debugging = 0 unless defined $debugging;
Note: Many folks tend to overuse defined(), and
then are surprised to discover that the number 0
and "" (the zero-length string) are, in fact,
defined values. For example, if you say
"ab" =~ /a(.*)b/;
the pattern match succeeds, and $1 is defined,
despite the fact that it matched "nothing". But
it didn't really match nothing--rather, it matched
something that happened to be 0 characters long.
This is all very above-board and honest. When a
function returns an undefined value, it's an
admission that it couldn't give you an honest
answer. So you should use defined() only when
you're questioning the integrity of what you're
trying to do. At other times, a simple comparison
to 0 or "" is what you want.
Currently, using defined() on an entire array or
hash reports whether memory for that aggregate has
ever been allocated. So an array you set to the
empty list appears undefined initially, and one
that once was full and that you then set to the
empty list still appears defined. You should
instead use a simple test for size:
if (@an_array) { print "has array elements\n" }
if (%a_hash) { print "has hash members\n" }
Using undef() on these, however, does clear their
memory and then report them as not defined
anymore, but you shoudln't do that unless you
don't plan to use them again, because it saves
time when you load them up again to have memory
already ready to be filled.
This counterintuitive behaviour of defined() on
aggregates may be changed, fixed, or broken in a
future release of Perl.
See also the undef, exists, and ref entries
elsewhere in this document .
delete EXPR
Deletes the specified key(s) and their associated
values from a hash. For each key, returns the
deleted value associated with that key, or the
undefined value if there was no such key.
Deleting from $ENV{} modifies the environment.
Deleting from a hash tied to a DBM file deletes
the entry from the DBM file. (But deleting from a
tie()d hash doesn't necessarily return anything.)
The following deletes all the values of a hash:
foreach $key (keys %HASH) {
delete $HASH{$key};
}
And so does this:
delete @HASH{keys %HASH}
(But both of these are slower than the undef()
command.) Note that the EXPR can be arbitrarily
complicated as long as the final operation is a
hash element lookup or hash slice:
delete $ref->[$x][$y]{$key};
delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};
die LIST
Outside of an eval(), prints the value of LIST to
STDERR and exits with the current value of $!
(errno). If $! is 0, exits with the value of ($?
>> 8) (backtick `command` status). If ($? >> 8)
is 0, exits with 255. Inside an eval(), the error
message is stuffed into $@, and the eval() is
terminated with the undefined value; this makes
die() the way to raise an exception.
Equivalent examples:
die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
If the value of EXPR does not end in a newline,
the current script line number and input line
number (if any) are also printed, and a newline is
supplied. Hint: sometimes appending ", stopped"
to your message will cause it to make better sense
when the string "at foo line 123" is appended.
Suppose you are running script "canasta".
die "/etc/games is no good";
die "/etc/games is no good, stopped";
produce, respectively
/etc/games is no good at canasta line 123.
/etc/games is no good, stopped at canasta line 123.
See also exit() and warn().
You can arrange for a callback to be called just
before the die() does its deed, by setting the
$SIG{__DIE__} hook. The associated handler will
be called with the error text and can change the
error message, if it sees fit, by calling die()
again. See the perlvar manpage for details on
setting %SIG entries, and eval() for some
examples.
do BLOCK
Not really a function. Returns the value of the
last command in the sequence of commands indicated
by BLOCK. When modified by a loop modifier,
executes the BLOCK once before testing the loop
condition. (On other statements the loop
modifiers test the conditional first.)
do SUBROUTINE(LIST)
A deprecated form of subroutine call. See the
perlsub manpage.
do EXPR Uses the value of EXPR as a filename and executes
the contents of the file as a Perl script. Its
primary use is to include subroutines from a Perl
subroutine library.
do 'stat.pl';
is just like
eval `cat stat.pl`;
except that it's more efficient, more concise,
keeps track of the current filename for error
messages, and searches all the -I libraries if the
file isn't in the current directory (see also the
@INC array in the section on Predefined Names in
the perlvar manpage). It's the same, however, in
that it does reparse the file every time you call
it, so you probably don't want to do this inside a
loop.
Note that inclusion of library modules is better
done with the use() and require() operators, which
also do error checking and raise an exception if
there's a problem.
dump LABEL
This causes an immediate core dump. Primarily
this is so that you can use the undump program to
turn your core dump into an executable binary
after having initialized all your variables at the
beginning of the program. When the new binary is
executed it will begin by executing a goto LABEL
(with all the restrictions that goto suffers).
Think of it as a goto with an intervening core
dump and reincarnation. If LABEL is omitted,
restarts the program from the top. WARNING: any
files opened at the time of the dump will NOT be
open any more when the program is reincarnated,
with possible resulting confusion on the part of
Perl. See also -u option in the perlrun manpage.
Example:
#!/usr/bin/perl
require 'getopt.pl';
require 'stat.pl';
%days = (
'Sun' => 1,
'Mon' => 2,
'Tue' => 3,
'Wed' => 4,
'Thu' => 5,
'Fri' => 6,
'Sat' => 7,
);
dump QUICKSTART if $ARGV[0] eq '-d';
QUICKSTART:
Getopt('f');
each HASH
When called in a list context, returns a 2-element
array consisting of the key and value for the next
element of a hash, so that you can iterate over
it. When called in a scalar context, returns the
key for only the next element in the hash. (Note:
Keys may be "0" or "", which are logically false;
you may wish to avoid constructs like while ($k =
each %foo) {} for this reason.)
Entries are returned in an apparently random
order. When the hash is entirely read, a null
array is returned in list context (which when
assigned produces a FALSE (0) value), and undef is
returned in a scalar context. The next call to
each() after that will start iterating again.
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, you may get
entries skipped or duplicated, so don't.
The following prints out your environment like the
printenv(1) program, only in a different order:
while (($key,$value) = each %ENV) {
print "$key=$value\n";
}
See also keys() and values().
eof FILEHANDLE
eof ()
eof Returns 1 if the next read on FILEHANDLE will
return end of file, or if FILEHANDLE is not open.
FILEHANDLE may be an expression whose value gives
the real filehandle name. (Note that this
function actually reads a character and then
ungetc()s it, so it is not very useful in an
interactive context.) Do not read from a terminal
file (or call eof(FILEHANDLE) on it) after end-of-
file is reached. Filetypes such as terminals may
lose the end-of-file condition if you do.
An eof without an argument uses the last file read
as argument. Empty parentheses () may be used to
indicate the pseudo file formed of the files
listed on the command line, i.e., eof() is
reasonable to use inside a while (<>) loop to
detect the end of only the last file. Use
eof(ARGV) or eof without the parentheses to test
EACH file in a while (<>) loop. Examples:
# reset line numbering on each input file
while (<>) {
print "$.\t$_";
close(ARGV) if (eof); # Not eof().
}
# insert dashes just before last line of last file
while (<>) {
if (eof()) {
print "--------------\n";
close(ARGV); # close or break; is needed if we
# are reading from the terminal
}
print;
}
Practical hint: you almost never need to use eof
in Perl, because the input operators return undef
when they run out of data.
eval EXPR
eval BLOCK
EXPR is parsed and executed as if it were a little
Perl program. It is executed in the context of
the current Perl program, so that any variable
settings or subroutine and format definitions
remain afterwards. The value returned is the
value of the last expression evaluated, or a
return statement may be used, just as with
subroutines. The last expression is evaluated in
scalar or array context, depending on the context
of the eval.
If there is a syntax error or runtime error, or a
die() statement is executed, an undefined value is
returned by eval(), and $@ is set to the error
message. If there was no error, $@ is guaranteed
to be a null string. If EXPR is omitted,
evaluates $_. The final semicolon, if any, may be
omitted from the expression. Beware that using
eval() neither silences perl from printing
warnings to STDERR, nor does it stuff the text of
warning messages into $@. To do either of those,
you have to use the $SIG{__WARN__} facility. See
warn() and the perlvar manpage.
Note that, because eval() traps otherwise-fatal
errors, it is useful for determining whether a
particular feature (such as socket() or symlink())
is implemented. It is also Perl's exception
trapping mechanism, where the die operator is used
to raise exceptions.
If the code to be executed doesn't vary, you may
use the eval-BLOCK form to trap run-time errors
without incurring the penalty of recompiling each
time. The error, if any, is still returned in $@.
Examples:
# make divide-by-zero nonfatal
eval { $answer = $a / $b; }; warn $@ if $@;
# same thing, but less efficient
eval '$answer = $a / $b'; warn $@ if $@;
# a compile-time error
eval { $answer = };
# a run-time error
eval '$answer ='; # sets $@
When using the eval{} form as an exception trap in
libraries, you may wish not to trigger any __DIE__
hooks that user code may have installed. You can
use the local $SIG{__DIE__} construct for this
purpose, as shown in this example:
# a very private exception trap for divide-by-zero
eval { local $SIG{'__DIE__'}; $answer = $a / $b; }; warn $@ if $@;
This is especially significant, given that __DIE__
hooks can call die() again, which has the effect
of changing their error messages:
# __DIE__ hooks may modify error messages
{
local $SIG{'__DIE__'} = sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
eval { die "foo foofs here" };
print $@ if $@; # prints "bar barfs here"
}
With an eval(), you should be especially careful
to remember what's being looked at when:
eval $x; # CASE 1
eval "$x"; # CASE 2
eval '$x'; # CASE 3
eval { $x }; # CASE 4
eval "\$$x++" # CASE 5
$$x++; # CASE 6
Cases 1 and 2 above behave identically: they run
the code contained in the variable $x. (Although
case 2 has misleading double quotes making the
reader wonder what else might be happening
(nothing is).) Cases 3 and 4 likewise behave in
the same way: they run the code '$x', which does
nothing but return the value of $x. (Case 4 is
preferred for purely visual reasons, but it also
has the advantage of compiling at compile-time
instead of at run-time.) Case 5 is a place where
normally you WOULD like to use double quotes,
except that in this particular situation, you can
just use symbolic references instead, as in case
6.
exec LIST
The exec() function executes a system command AND
NEVER RETURNS, unless the command does not exist
and is executed directly instead of via /bin/sh -c
(see below). Use system() instead of exec() if
you want it to return.
If there is more than one argument in LIST, or if
LIST is an array with more than one value, calls
execvp(3) with the arguments in LIST. If there is
only one scalar argument, the argument is checked
for shell metacharacters. If there are any, the
entire argument is passed to /bin/sh -c for
parsing. If there are none, the argument is split
into words and passed directly to execvp(), which
is more efficient. Note: exec() and system() do
not flush your output buffer, so you may need to
set $| to avoid lost output. Examples:
exec '/bin/echo', 'Your arguments are: ', @ARGV;
exec "sort $outfile | uniq";
If you don't really want to execute the first
argument, but want to lie to the program you are
executing about its own name, you can specify the
program you actually want to run as an "indirect
object" (without a comma) in front of the LIST.
(This always forces interpretation of the LIST as
a multivalued list, even if there is only a single
scalar in the list.) Example:
$shell = '/bin/csh';
exec $shell '-sh'; # pretend it's a login shell
or, more directly,
exec {'/bin/csh'} '-sh'; # pretend it's a login shell
exists EXPR
Returns TRUE if the specified hash key exists in
its hash array, even if the corresponding value is
undefined.
print "Exists\n" if exists $array{$key};
print "Defined\n" if defined $array{$key};
print "True\n" if $array{$key};
A hash element can be TRUE only if it's defined,
and defined if it exists, but the reverse doesn't
necessarily hold true.
Note that the EXPR can be arbitrarily complicated
as long as the final operation is a hash key
lookup:
if (exists $ref->[$x][$y]{$key}) { ... }
exit EXPR
Evaluates EXPR and exits immediately with that
value. (Actually, it calls any defined END
routines first, but the END routines may not abort
the exit. Likewise any object destructors that
need to be called are called before exit.)
Example:
$ans = <STDIN>;
exit 0 if $ans =~ /^[Xx]/;
See also die(). If EXPR is omitted, exits with 0
status. The only universally portable values for
EXPR are 0 for success and 1 for error; all other
values are subject to unpredictable interpretation
depending on the environment in which the Perl
program is running.
You shouldn't use exit() to abort a subroutine if
there's any chance that someone might want to trap
whatever error happened. Use die() instead, which
can be trapped by an eval().
exp EXPR
exp Returns e (the natural logarithm base) to the
power of EXPR. If EXPR is omitted, gives exp($_).
fcntl FILEHANDLE,FUNCTION,SCALAR
Implements the fcntl(2) function. You'll probably
have to say
use Fcntl;
first to get the correct function definitions.
Argument processing and value return works just
like ioctl() below. Note that fcntl() will
produce a fatal error if used on a machine that
doesn't implement fcntl(2). For example:
use Fcntl;
fcntl($filehandle, F_GETLK, $packed_return_buffer);
fileno FILEHANDLE
Returns the file descriptor for a filehandle.
This is useful for constructing bitmaps for
select(). If FILEHANDLE is an expression, the
value is taken as the name of the filehandle.
flock FILEHANDLE,OPERATION
Calls flock(2), or an emulation of it, on
FILEHANDLE. Returns TRUE for success, FALSE on
failure. Produces a fatal error if used on a
machine that doesn't implement flock(2), fcntl(2)
locking, or lockf(3). flock() is Perl's portable
file locking interface, although it locks only
entire files, not records.
OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN,
possibly combined with LOCK_NB. These constants
are traditionally valued 1, 2, 8 and 4, but you
can use the symbolic names if import them from the
Fcntl module, either individually, or as a group
using the ':flock' tag. LOCK_SH requests a shared
lock, LOCK_EX requests an exclusive lock, and
LOCK_UN releases a previously requested lock. If
LOCK_NB is added to LOCK_SH or LOCK_EX then
flock() will return immediately rather than
blocking waiting for the lock (check the return
status to see if you got it).
To avoid the possibility of mis-coordination, Perl
flushes FILEHANDLE before (un)locking it.
Note that the emulation built with lockf(3)
doesn't provide shared locks, and it requires that
FILEHANDLE be open with write intent. These are
the semantics that lockf(3) implements. Most
(all?) systems implement lockf(3) in terms of
fcntl(2) locking, though, so the differing
semantics shouldn't bite too many people.
Note also that some versions of flock() cannot
lock things over the network; you would need to
use the more system-specific fcntl() for that. If
you like you can force Perl to ignore your
system's flock(2) function, and so provide its own
fcntl(2)-based emulation, by passing the switch
-Ud_flock to the Configure program when you
configure perl.
Here's a mailbox appender for BSD systems.
use Fcntl ':flock'; # import LOCK_* constants
sub lock {
flock(MBOX,LOCK_EX);
# and, in case someone appended
# while we were waiting...
seek(MBOX, 0, 2);
}
sub unlock {
flock(MBOX,LOCK_UN);
}
open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
or die "Can't open mailbox: $!";
lock();
print MBOX $msg,"\n\n";
unlock();
See also the DB_File manpage for other flock()
examples.
fork Does a fork(2) system call. Returns the child pid
to the parent process and 0 to the child process,
or undef if the fork is unsuccessful. Note:
unflushed buffers remain unflushed in both
processes, which means you may need to set $|
($AUTOFLUSH in English) or call the autoflush()
method of IO::Handle to avoid duplicate output.
If you fork() without ever waiting on your
children, you will accumulate zombies:
$SIG{CHLD} = sub { wait };
There's also the double-fork trick (error checking
on fork() returns omitted);
unless ($pid = fork) {
unless (fork) {
exec "what you really wanna do";
die "no exec";
# ... or ...
## (some_perl_code_here)
exit 0;
}
exit 0;
}
waitpid($pid,0);
See also the perlipc manpage for more examples of
forking and reaping moribund children.
Note that if your forked child inherits system
file descriptors like STDIN and STDOUT that are
actually connected by a pipe or socket, even if
you exit, the remote server (such as, say, httpd
or rsh) won't think you're done. You should
reopen those to /dev/null if it's any issue.
format Declare a picture format with use by the write()
function. For example:
format Something =
Test: @<<<<<<<< @||||| @>>>>>
$str, $%, '$' . int($num)
.
$str = "widget";
$num = $cost/$quantity;
$~ = 'Something';
write;
See the perlform manpage for many details and
examples.
formline PICTURE,LIST
This is an internal function used by formats,
though you may call it too. It formats (see the
perlform manpage) a list of values according to
the contents of PICTURE, placing the output into
the format output accumulator, $^A (or
$ACCUMULATOR in English). Eventually, when a
write() is done, the contents of $^A are written
to some filehandle, but you could also read $^A
yourself and then set $^A back to "". Note that a
format typically does one formline() per line of
form, but the formline() function itself doesn't
care how many newlines are embedded in the
PICTURE. This means that the ~ and ~~ tokens will
treat the entire PICTURE as a single line. You
may therefore need to use multiple formlines to
implement a single record format, just like the
format compiler.
Be careful if you put double quotes around the
picture, because an "@" character may be taken to
mean the beginning of an array name. formline()
always returns TRUE. See the perlform manpage for
other examples.
getc FILEHANDLE
getc Returns the next character from the input file
attached to FILEHANDLE, or a null string at end of
file. If FILEHANDLE is omitted, reads from STDIN.
This is not particularly efficient. It cannot be
used to get unbuffered single-characters, however.
For that, try something more like:
if ($BSD_STYLE) {
system "stty cbreak </dev/tty >/dev/tty 2>&1";
}
else {
system "stty", '-icanon', 'eol', "\001";
}
$key = getc(STDIN);
if ($BSD_STYLE) {
system "stty -cbreak </dev/tty >/dev/tty 2>&1";
}
else {
system "stty", 'icanon', 'eol', '^@'; # ASCII null
}
print "\n";
Determination of whether $BSD_STYLE should be set
is left as an exercise to the reader.
The POSIX::getattr() function can do this more
portably on systems alleging POSIX compliance.
See also the Term::ReadKey module from your
nearest CPAN site; details on CPAN can be found on
the CPAN entry in the perlmod manpage.
getlogin
Returns the current login from /etc/utmp, if any.
If null, use getpwuid().
$login = getlogin || getpwuid($<) || "Kilroy";
Do not consider getlogin() for authentication: it
is not as secure as getpwuid().
getpeername SOCKET
Returns the packed sockaddr address of other end
of the SOCKET connection.
use Socket;
$hersockaddr = getpeername(SOCK);
($port, $iaddr) = unpack_sockaddr_in($hersockaddr);
$herhostname = gethostbyaddr($iaddr, AF_INET);
$herstraddr = inet_ntoa($iaddr);
getpgrp PID
Returns the current process group for the
specified PID. Use a PID of 0 to get the current
process group for the current process. Will raise
an exception if used on a machine that doesn't
implement getpgrp(2). If PID is omitted, returns
process group of current process. Note that the
POSIX version of getpgrp() does not accept a PID
argument, so only PID==0 is truly portable.
getppid Returns the process id of the parent process.
getpriority WHICH,WHO
Returns the current priority for a process, a
process group, or a user. (See the getpriority(2)
manpage.) Will raise a fatal exception if used on
a machine that doesn't implement getpriority(2).
getpwnam NAME
getgrnam NAME
gethostbyname NAME
getnetbyname NAME
getprotobyname NAME
getpwuid UID
getgrgid GID
getservbyname NAME,PROTO
gethostbyaddr ADDR,ADDRTYPE
getnetbyaddr ADDR,ADDRTYPE
getprotobynumber NUMBER
getservbyport PORT,PROTO
getpwent
getgrent
gethostent
getnetent
getprotoent
getservent
setpwent
setgrent
sethostent STAYOPEN
setnetent STAYOPEN
setprotoent STAYOPEN
setservent STAYOPEN
endpwent
endgrent
endhostent
endnetent
endprotoent
endservent
These routines perform the same functions as their
counterparts in the system library. Within a list
context, the return values from the various get
routines are as follows:
($name,$passwd,$uid,$gid,
$quota,$comment,$gcos,$dir,$shell) = getpw*
($name,$passwd,$gid,$members) = getgr*
($name,$aliases,$addrtype,$length,@addrs) = gethost*
($name,$aliases,$addrtype,$net) = getnet*
($name,$aliases,$proto) = getproto*
($name,$aliases,$port,$proto) = getserv*
(If the entry doesn't exist you get a null list.)
Within a scalar context, you get the name, unless
the function was a lookup by name, in which case
you get the other thing, whatever it is. (If the
entry doesn't exist you get the undefined value.)
For example:
$uid = getpwnam
$name = getpwuid
$name = getpwent
$gid = getgrnam
$name = getgrgid
$name = getgrent
etc.
The $members value returned by getgr*() is a space
separated list of the login names of the members
of the group.
For the gethost*() functions, if the h_errno
variable is supported in C, it will be returned to
you via $? if the function call fails. The @addrs
value returned by a successful call is a list of
the raw addresses returned by the corresponding
system library call. In the Internet domain, each
address is four bytes long and you can unpack it
by saying something like:
($a,$b,$c,$d) = unpack('C4',$addr[0]);
getsockname SOCKET
Returns the packed sockaddr address of this end of
the SOCKET connection.
use Socket;
$mysockaddr = getsockname(SOCK);
($port, $myaddr) = unpack_sockaddr_in($mysockaddr);
getsockopt SOCKET,LEVEL,OPTNAME
Returns the socket option requested, or undefined
if there is an error.
glob EXPR
glob Returns the value of EXPR with filename expansions
such as a shell would do. This is the internal
function implementing the <*.c> operator, but you
can use it directly. If EXPR is omitted, $_ is
used. The <*.c> operator is discussed in more
detail in the section on I/O Operators in the
perlop manpage.
gmtime EXPR
Converts a time as returned by the time function
to a 9-element array with the time localized for
the standard Greenwich time zone. Typically used
as follows:
# 0 1 2 3 4 5 6 7 8
($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
gmtime(time);
All array elements are numeric, and come straight
out of a struct tm. In particular this means that
$mon has the range 0..11 and $wday has the range
0..6 with sunday as day 0. Also, $year is the
number of years since 1900, not simply the last
two digits of the year.
If EXPR is omitted, does gmtime(time()).
In a scalar context, returns the ctime(3) value:
$now_string = gmtime; # e.g., "Thu Oct 13 04:54:34 1994"
Also see the timegm() function provided by the
Time::Local module, and the strftime(3) function
available via the POSIX module.
goto LABEL
goto EXPR
goto &NAME
The goto-LABEL form finds the statement labeled
with LABEL and resumes execution there. It may
not be used to go into any construct that requires
initialization, such as a subroutine or a foreach
loop. It also can't be used to go into a
construct that is optimized away, or to get out of
a block or subroutine given to sort(). It can be
used to go almost anywhere else within the dynamic
scope, including out of subroutines, but it's
usually better to use some other construct such as
last or die. The author of Perl has never felt
the need to use this form of goto (in Perl, that
is--C is another matter).
The goto-EXPR form expects a label name, whose
scope will be resolved dynamically. This allows
for computed gotos per FORTRAN, but isn't
necessarily recommended if you're optimizing for
maintainability:
goto ("FOO", "BAR", "GLARCH")[$i];
The goto-&NAME form is highly magical, and
substitutes a call to the named subroutine for the
currently running subroutine. This is used by
AUTOLOAD subroutines that wish to load another
subroutine and then pretend that the other
subroutine had been called in the first place
(except that any modifications to @_ in the
current subroutine are propagated to the other
subroutine.) After the goto, not even caller()
will be able to tell that this routine was called
first.
grep BLOCK LIST
grep EXPR,LIST
This is similar in spirit to, but not the same as,
grep(1) and its relatives. In particular, it is
not limited to using regular expressions.
Evaluates the BLOCK or EXPR for each element of
LIST (locally setting $_ to each element) and
returns the list value consisting of those
elements for which the expression evaluated to
TRUE. In a scalar context, returns the number of
times the expression was TRUE.
@foo = grep(!/^#/, @bar); # weed out comments
or equivalently,
@foo = grep {!/^#/} @bar; # weed out comments
Note that, because $_ is a reference into the list
value, it can be used to modify the elements of
the array. While this is useful and supported, it
can cause bizarre results if the LIST is not a
named array. Similarly, grep returns aliases into
the original list, much like the way that the
section on Foreach Loops's index variable aliases
the list elements. That is, modifying an element
of a list returned by grep actually modifies the
element in the original list.
hex EXPR
hex Interprets EXPR as a hex string and returns the
corresponding value. (To convert strings that
might start with either 0 or 0x see the oct entry
elsewhere in this document .) If EXPR is omitted,
uses $_.
print hex '0xAf'; # prints '175'
print hex 'aF'; # same
import There is no builtin import() function. It is
merely an ordinary method (subroutine) defined (or
inherited) by modules that wish to export names to
another module. The use() function calls the
import() method for the package used. See also
the use() entry elsewhere in this document the
perlmod manpage, and the Exporter manpage.
index STR,SUBSTR,POSITION
index STR,SUBSTR
Returns the position of the first occurrence of
SUBSTR in STR at or after POSITION. If POSITION
is omitted, starts searching from the beginning of
the string. The return value is based at 0 (or
whatever you've set the $[ variable to--but don't
do that). If the substring is not found, returns
one less than the base, ordinarily -1.
int EXPR
int Returns the integer portion of EXPR. If EXPR is
omitted, uses $_.
ioctl FILEHANDLE,FUNCTION,SCALAR
Implements the ioctl(2) function. You'll probably
have to say
require "ioctl.ph"; # probably in /usr/local/lib/perl/ioctl.ph
first to get the correct function definitions. If
ioctl.ph doesn't exist or doesn't have the correct
definitions you'll have to roll your own, based on
your C header files such as <sys/ioctl.h>. (There
is a Perl script called h2ph that comes with the
Perl kit which may help you in this, but it's
nontrivial.) SCALAR will be read and/or written
depending on the FUNCTION--a pointer to the string
value of SCALAR will be passed as the third
argument of the actual ioctl call. (If SCALAR has
no string value but does have a numeric value,
that value will be passed rather than a pointer to
the string value. To guarantee this to be TRUE,
add a 0 to the scalar before using it.) The
pack() and unpack() functions are useful for
manipulating the values of structures used by
ioctl(). The following example sets the erase
character to DEL.
require 'ioctl.ph';
$getp = &TIOCGETP;
die "NO TIOCGETP" if $@ || !$getp;
$sgttyb_t = "ccccs"; # 4 chars and a short
if (ioctl(STDIN,$getp,$sgttyb)) {
@ary = unpack($sgttyb_t,$sgttyb);
$ary[2] = 127;
$sgttyb = pack($sgttyb_t,@ary);
ioctl(STDIN,&TIOCSETP,$sgttyb)
|| die "Can't ioctl: $!";
}
The return value of ioctl (and fcntl) is as
follows:
if OS returns: then Perl returns:
-1 undefined value
0 string "0 but true"
anything else that number
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(...)) || ($retval = -1);
printf "System returned %d\n", $retval;
join EXPR,LIST
Joins the separate strings of LIST into a single
string with fields separated by the value of EXPR,
and returns the string. Example:
$_ = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
See the split entry in the perlfunc manpage.
keys HASH
Returns a normal array consisting of all the keys
of the named hash. (In a scalar context, returns
the number of keys.) The keys are returned in an
apparently random order, but it is the same order
as either the values() or each() function produces
(given that the hash has not been modified). As a
side effect, it resets HASH's iterator.
Here is yet another way to print your environment:
@keys = keys %ENV;
@values = values %ENV;
while ($#keys >= 0) {
print pop(@keys), '=', pop(@values), "\n";
}
or how about sorted by key:
foreach $key (sort(keys %ENV)) {
print $key, '=', $ENV{$key}, "\n";
}
To sort an array by value, you'll need to use a
sort function. Here's a descending numeric sort
of a hash by its values:
foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash)) {
printf "%4d %s\n", $hash{$key}, $key;
}
As an lvalue keys allows you to increase the
number of hash buckets allocated for the given
hash. This can gain you a measure of efficiency
if you know the hash is going to get big. (This
is similar to pre-extending an array by assigning
a larger number to $#array.) If you say
keys %hash = 200;
then %hash will have at least 200 buckets
allocated for it. These buckets will be retained
even if you do %hash = (), use undef %hash if you
want to free the storage while %hash is still in
scope. You can't shrink the number of buckets
allocated for the hash using keys in this way (but
you needn't worry about doing this by accident, as
trying has no effect).
kill LIST
Sends a signal to a list of processes. The first
element of the list must be the signal to send.
Returns the number of processes successfully
signaled.
$cnt = kill 1, $child1, $child2;
kill 9, @goners;
Unlike in the shell, in Perl if the SIGNAL is
negative, it kills process groups instead of
processes. (On System V, a negative PROCESS
number will also kill process groups, but that's
not portable.) That means you usually want to use
positive not negative signals. You may also use a
signal name in quotes. See the section on Signals
in the perlipc manpage for details.
last LABEL
last The last command is like the break statement in C
(as used in loops); it immediately exits the loop
in question. If the LABEL is omitted, the command
refers to the innermost enclosing loop. The
continue block, if any, is not executed:
LINE: while (<STDIN>) {
last LINE if /^$/; # exit when done with header
...
}
lc EXPR
lc Returns an lowercased version of EXPR. This is
the internal function implementing the \L escape
in double-quoted strings. Respects current
LC_CTYPE locale if use locale in force. See the
perllocale manpage.
If EXPR is omitted, uses $_.
lcfirst EXPR
lcfirst Returns the value of EXPR with the first character
lowercased. This is the internal function
implementing the \l escape in double-quoted
strings. Respects current LC_CTYPE locale if use
locale in force. See the perllocale manpage.
If EXPR is omitted, uses $_.
length EXPR
length Returns the length in characters of the value of
EXPR. If EXPR is omitted, returns length of $_.
link OLDFILE,NEWFILE
Creates a new filename linked to the old filename.
Returns 1 for success, 0 otherwise.
listen SOCKET,QUEUESIZE
Does the same thing that the listen system call
does. Returns TRUE if it succeeded, FALSE
otherwise. See example in the section on Sockets:
Client/Server Communication in the perlipc
manpage.
local EXPR
A local modifies the listed variables to be local
to the enclosing block, subroutine, eval{}, or do.
If more than one value is listed, the list must be
placed in parentheses. See the section on
Temporary Values via local() in the perlsub
manpage for details, including issues with tied
arrays and hashes.
But you really probably want to be using my()
instead, because local() isn't what most people
think of as "local"). See the section on Private
Variables via my() in the perlsub manpage for
details.
localtime EXPR
Converts a time as returned by the time function
to a 9-element array with the time analyzed for
the local time zone. Typically used as follows:
# 0 1 2 3 4 5 6 7 8
($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
localtime(time);
All array elements are numeric, and come straight
out of a struct tm. In particular this means that
$mon has the range 0..11 and $wday has the range
0..6 with sunday as day 0. Also, $year is the
number of years since 1900, that is, $year is 123
in year 2023.
If EXPR is omitted, uses the current time
(localtime(time)).
In a scalar context, returns the ctime(3) value:
$now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
Also see the Time::Local module, and the
strftime(3) and mktime(3) function available via
the POSIX module.
log EXPR
log Returns logarithm (base e) of EXPR. If EXPR is
omitted, returns log of $_.
lstat FILEHANDLE
lstat EXPR
lstat Does the same thing as the stat() function, but
stats a symbolic link instead of the file the
symbolic link points to. If symbolic links are
unimplemented on your system, a normal stat() is
done.
If EXPR is omitted, stats $_.
m// The match operator. See the perlop manpage.
map BLOCK LIST
map EXPR,LIST
Evaluates the BLOCK or EXPR for each element of
LIST (locally setting $_ to each element) and
returns the list value composed of the results of
each such evaluation. Evaluates BLOCK or EXPR in
a list context, so each element of LIST may
produce zero, one, or more elements in the
returned value.
@chars = map(chr, @nums);
translates a list of numbers to the corresponding
characters. And
%hash = map { getkey($_) => $_ } @array;
is just a funny way to write
%hash = ();
foreach $_ (@array) {
$hash{getkey($_)} = $_;
}
mkdir FILENAME,MODE
Creates the directory specified by FILENAME, with
permissions specified by MODE (as modified by
umask). If it succeeds it returns 1, otherwise it
returns 0 and sets $! (errno).
msgctl ID,CMD,ARG
Calls the System V IPC function msgctl(2). If CMD
is &IPC_STAT, then ARG must be a variable which
will hold the returned msqid_ds structure.
Returns like ioctl: the undefined value for error,
"0 but true" for zero, or the actual return value
otherwise.
msgget KEY,FLAGS
Calls the System V IPC function msgget(2).
Returns the message queue id, or the undefined
value if there is an error.
msgsnd ID,MSG,FLAGS
Calls the System V IPC function msgsnd to send the
message MSG to the message queue ID. MSG must
begin with the long integer message type, which
may be created with pack("l", $type). Returns
TRUE if successful, or FALSE if there is an error.
msgrcv ID,VAR,SIZE,TYPE,FLAGS
Calls the System V IPC function msgrcv to receive
a message from message queue ID into variable VAR
with a maximum message size of SIZE. Note that if
a message is received, the message type will be
the first thing in VAR, and the maximum length of
VAR is SIZE plus the size of the message type.
Returns TRUE if successful, or FALSE if there is
an error.
my EXPR A "my" declares the listed variables to be local
(lexically) to the enclosing block, subroutine,
eval, or do/require/use'd file. If more than one
value is listed, the list must be placed in
parentheses. See the section on Private Variables
via my() in the perlsub manpage for details.
next LABEL
next The next command is like the continue statement in
C; it starts the next iteration of the loop:
LINE: while (<STDIN>) {
next LINE if /^#/; # discard comments
...
}
Note that if there were a continue block on the
above, it would get executed even on discarded
lines. If the LABEL is omitted, the command
refers to the innermost enclosing loop.
no Module LIST
See the "use" function, which "no" is the opposite
of.
oct EXPR
oct Interprets EXPR as an octal string and returns the
corresponding value. (If EXPR happens to start
off with 0x, interprets it as a hex string
instead.) The following will handle decimal,
octal, and hex in the standard Perl or C notation:
$val = oct($val) if $val =~ /^0/;
If EXPR is omitted, uses $_. This function is
commonly used when a string such as "644" needs to
be converted into a file mode, for example.
(Although perl will automatically convert strings
into numbers as needed, this automatic conversion
assumes base 10.)
open FILEHANDLE,EXPR
open FILEHANDLE
Opens the file whose filename is given by EXPR,
and associates it with FILEHANDLE. If FILEHANDLE
is an expression, its value is used as the name of
the real filehandle wanted. If EXPR is omitted,
the scalar variable of the same name as the
FILEHANDLE contains the filename. (Note that
lexical variables--those declared with my--will
not work for this purpose; so if you're using my,
specify EXPR in your call to open.)
If the filename begins with '<' or nothing, the
file is opened for input. If the filename begins
with '>', the file is truncated and opened for
output. If the filename begins with '>>', the
file is opened for appending. You can put a '+'
in front of the '>' or '<' to indicate that you
want both read and write access to the file; thus
'+<' is almost always preferred for read/write
updates--the '+>' mode would clobber the file
first. The prefix and the filename may be
separated with spaces. These various prefixes
correspond to the fopen(3) modes of 'r', 'r+',
'w', 'w+', 'a', and 'a+'.
If the filename begins with "|", the filename is
interpreted as a command to which output is to be
piped, and if the filename ends with a "|", the
filename is interpreted See the section on Using
open() for IPC in the perlipc manpage for more
examples of this. as command which pipes input to
us. (You may not have a raw open() to a command
that pipes both in and out, but see the IPC::Open2
manpage, the IPC::Open3 manpage, and the section
on Bidirectional Communication in the perlipc
manpage for alternatives.)
Opening '-' opens STDIN and opening '>-' opens
STDOUT. Open returns nonzero upon success, the
undefined value otherwise. If the open involved a
pipe, the return value happens to be the pid of
the subprocess.
If you're unfortunate enough to be running Perl on
a system that distinguishes between text files and
binary files (modern operating systems don't
care), then you should check out the binmode entry
elsewhere in this document for tips for dealing
with this. The key distinction between systems
that need binmode and those that don't is their
text file formats. Systems like Unix and Plan9
that delimit lines with a single character, and
that encode that character in C as '\n', do not
need binmode. The rest need it.
Examples:
$ARTICLE = 100;
open ARTICLE or die "Can't find article $ARTICLE: $!\n";
while (<ARTICLE>) {...
open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
open(DBASE, '+<dbase.mine'); # open for update
open(ARTICLE, "caesar <$article |"); # decrypt article
open(EXTRACT, "|sort >/tmp/Tmp$$"); # $$ is our process id
# process argument list of files along with any includes
foreach $file (@ARGV) {
process($file, 'fh00');
}
sub process {
local($filename, $input) = @_;
$input++; # this is a string increment
unless (open($input, $filename)) {
print STDERR "Can't open $filename: $!\n";
return;
}
while (<$input>) { # note use of indirection
if (/^#include "(.*)"/) {
process($1, $input);
next;
}
... # whatever
}
}
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)
which is to be duped and opened. You may use &
after >, >>, <, +>, +>>, and +<. 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.) Here is a script that saves, redirects,
and restores STDOUT and STDERR:
#!/usr/bin/perl
open(SAVEOUT, ">&STDOUT");
open(SAVEERR, ">&STDERR");
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
print STDOUT "stdout 1\n"; # this works for
print STDERR "stderr 1\n"; # subprocesses too
close(STDOUT);
close(STDERR);
open(STDOUT, ">&SAVEOUT");
open(STDERR, ">&SAVEERR");
print STDOUT "stdout 2\n";
print STDERR "stderr 2\n";
If you specify "<&=N", where N is a number, then
Perl will do an equivalent of C's fdopen() of that
file descriptor; this is more parsimonious of file
descriptors. For example:
open(FILEHANDLE, "<&=$fd")
If you open a pipe on the command "-", i.e.,
either "|-" or "-|", then there is an implicit
fork done, and the return value of open is the pid
of the child within the parent process, and 0
within the child process. (Use defined($pid) to
determine whether the open was successful.) The
filehandle behaves normally for the parent, but
i/o to that filehandle is piped from/to the
STDOUT/STDIN of the child process. In the child
process the filehandle isn't opened--i/o happens
from/to the new STDOUT or STDIN. Typically this
is used like the normal 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:
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;
See the section on Safe Pipe Opens in the perlipc
manpage for more examples of this.
NOTE: On any operation which may do a fork,
unflushed buffers remain unflushed in both
processes, which means you may need to set $| to
avoid duplicate output.
Closing any piped filehandle causes the parent
process to wait for the child to finish, and
returns the status value in $?.
Using the constructor from the IO::Handle package
(or one of its subclasses, such as IO::File or
IO::Socket), you can generate anonymous
filehandles which have the scope of whatever
variables hold references to them, and
automatically close whenever and however you leave
that scope:
use IO::File;
...
sub read_myfile_munged {
my $ALL = shift;
my $handle = new IO::File;
open($handle, "myfile") or die "myfile: $!";
$first = <$handle>
or return (); # Automatically closed here.
mung $first or die "mung failed"; # Or here.
return $first, <$handle> if $ALL; # Or here.
$first; # Or here.
}
The filename that is passed to open will have
leading and trailing whitespace deleted. To open
a file with arbitrary weird characters in it, it's
necessary to protect any leading and trailing
whitespace thusly:
$file =~ s#^(\s)#./$1#;
open(FOO, "< $file\0");
If you want a "real" C open() (see the open(2)
manpage on your system), then you should use the
sysopen() function. This is another way to
protect your filenames from interpretation. For
example:
use IO::Handle;
sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL, 0700)
or die "sysopen $path: $!";
HANDLE->autoflush(1);
HANDLE->print("stuff $$\n");
seek(HANDLE, 0, 0);
print "File contains: ", <HANDLE>;
See the seek() entry elsewhere in this document
for some details about mixing reading and writing.
opendir DIRHANDLE,EXPR
Opens a directory named EXPR for processing by
readdir(), telldir(), seekdir(), rewinddir(), and
closedir(). Returns TRUE if successful.
DIRHANDLEs have their own namespace separate from
FILEHANDLEs.
ord EXPR
ord Returns the numeric ascii value of the first
character of EXPR. If EXPR is omitted, uses $_.
For the reverse, see the chr entry elsewhere in
this document .
pack TEMPLATE,LIST
Takes an array or list of values and packs it into
a binary structure, returning the string
containing the structure. The TEMPLATE is a
sequence of characters that give the order and
type of values, as follows:
A An ascii string, will be space padded.
a An ascii string, will be null padded.
b A bit string (ascending bit order, like vec()).
B A bit string (descending bit order).
h A hex string (low nybble first).
H A hex string (high nybble first).
c A signed char value.
C An unsigned char value.
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'.)
i A signed integer value.
I An unsigned integer value.
(This 'integer' is _at_least_ 32 bits wide. Its exact size
depends on what a local C compiler calls 'int', and may
even be larger than the 'long' described in the next item.)
l A signed long value.
L An unsigned long value.
(This 'long' is _exactly_ 32 bits, which may differ from
what a local C compiler calls 'long'.)
n A short in "network" (big-endian) order.
N A long in "network" (big-endian) order.
v A short in "VAX" (little-endian) order.
V A long in "VAX" (little-endian) order.
(These 'shorts' and 'longs' are _exactly_ 16 bits and
_exactly_ 32 bits, respectively.)
f A single-precision float in the native format.
d A double-precision float in the native format.
p A pointer to a null-terminated string.
P A pointer to a structure (fixed-length string).
u A uuencoded string.
w A BER compressed integer. Its bytes represent an unsigned
integer in base 128, most significant digit first, with as few
digits as possible. Bit eight (the high bit) is set on each
byte except the last.
x A null byte.
X Back up a byte.
@ Null fill to absolute position.
Each letter may optionally be followed by a number
which gives a repeat count. With all types except
"a", "A", "b", "B", "h", "H", and "P" the pack
function will gobble up that many values from the
LIST. A * for the repeat count means to use
however many items are left. The "a" and "A"
types gobble just one value, but pack it as a
string of length count, padding with nulls or
spaces as necessary. (When unpacking, "A" strips
trailing spaces and nulls, but "a" does not.)
Likewise, the "b" and "B" fields pack a string
that many bits long. The "h" and "H" fields pack
a string that many nybbles long. The "P" packs a
pointer to a structure of the size indicated by
the length. Real numbers (floats and doubles) are
in the native machine format only; due to the
multiplicity of floating formats around, and the
lack of a standard "network" representation, no
facility for interchange has been 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). 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.,
unpack("f", pack("f", $foo)) will not in general
equal $foo).
Examples:
$foo = pack("cccc",65,66,67,68);
# foo eq "ABCD"
$foo = pack("c4",65,66,67,68);
# same thing
$foo = pack("ccxxcc",65,66,67,68);
# foo eq "AB\0\0CD"
$foo = pack("s2",1,2);
# "\1\0\2\0" on little-endian
# "\0\1\0\2" on big-endian
$foo = pack("a4","abcd","x","y","z");
# "abcd"
$foo = pack("aaaa","abcd","x","y","z");
# "axyz"
$foo = pack("a14","abcdefg");
# "abcdefg\0\0\0\0\0\0\0"
$foo = pack("i9pl", gmtime);
# a real struct tm (on my system anyway)
sub bintodec {
unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
}
The same template may generally also be used in
the unpack function.
package NAMESPACE
Declares the compilation unit as being in the
given namespace. The scope of the package
declaration is from the declaration itself through
the end of the enclosing block (the same scope as
the local() operator). All further unqualified
dynamic identifiers will be in this namespace. A
package statement affects only dynamic
variables--including those you've used local()
on--but not lexical variables created with my().
Typically it would be the first declaration in a
file to be included by the require or use
operator. You can switch into a package in more
than one place; it influences merely which symbol
table is used by the compiler for the rest of that
block. You can refer to variables and filehandles
in other packages by prefixing the identifier with
the package name and a double colon:
$Package::Variable. If the package name is null,
the main package as assumed. That is, $::sail is
equivalent to $main::sail.
See the section on Packages in the perlmod manpage
for more information about packages, modules, and
classes. See the perlsub manpage for other
scoping issues.
pipe READHANDLE,WRITEHANDLE
Opens a pair of connected pipes like the
corresponding system call. Note that if you set
up a loop of piped processes, deadlock can occur
unless you are very careful. In addition, note
that Perl's pipes use stdio buffering, so you may
need to set $| to flush your WRITEHANDLE after
each command, depending on the application.
See the IPC::Open2 manpage, the IPC::Open3
manpage, and the section on Bidirectional
Communication in the perlipc manpage for examples
of such things.
pop ARRAY
pop Pops and returns the last value of the array,
shortening the array by 1. Has a similar effect
to
$tmp = $ARRAY[$#ARRAY--];
If there are no elements in the array, returns the
undefined value. If ARRAY is omitted, pops the
@ARGV array in the main program, and the @_ array
in subroutines, just like shift().
pos SCALAR
pos Returns the offset of where the last m//g search
left off for the variable is in question ($_ is
used when the variable is not specified). May be
modified to change that offset. Such modification
will also influence the \G zero-width assertion in
regular expressions. See the perlre manpage and
the perlop manpage.
print FILEHANDLE LIST
print LIST
print Prints a string or a comma-separated list of
strings. Returns TRUE if successful. FILEHANDLE
may be a scalar variable name, in which case the
variable contains the name of or a reference to
the filehandle, thus introducing one level of
indirection. (NOTE: If FILEHANDLE is a variable
and the next token is a term, it may be
misinterpreted as an operator unless you interpose
a + or put parentheses around the arguments.) If
FILEHANDLE is omitted, prints by default to
standard output (or to the last selected output
channel--see the select entry elsewhere in this
document ). If LIST is also omitted, prints $_ to
STDOUT. To set the default output channel to
something other than STDOUT use the select
operation. Note that, because print takes a LIST,
anything in the LIST is evaluated in a list
context, and any subroutine that you call will
have one or more of its expressions evaluated in a
list context. Also be careful not to follow the
print keyword with a left parenthesis unless you
want the corresponding right parenthesis to
terminate the arguments to the print--interpose a
+ or put parentheses around all the arguments.
Note that if you're storing FILEHANDLES in an
array or other expression, you will have to use a
block returning its value instead:
print { $files[$i] } "stuff\n";
print { $OK ? STDOUT : STDERR } "stuff\n";
printf FILEHANDLE FORMAT, LIST
printf FORMAT, LIST
Equivalent to print FILEHANDLE sprintf(FORMAT,
LIST). The first argument of the list will be
interpreted as the printf format. If use locale
is in effect, the character used for the decimal
point in formatted real numbers is affected by the
LC_NUMERIC locale. See the perllocale manpage.
Don't fall into the trap of using a printf() when
a simple print() would do. The print() is more
efficient, and less error prone.
prototype FUNCTION
Returns the prototype of a function as a string
(or undef if the function has no prototype).
FUNCTION is a reference to, or the name of, the
function whose prototype you want to retrieve.
push ARRAY,LIST
Treats ARRAY as a stack, and pushes the values of
LIST onto the end of ARRAY. The length of ARRAY
increases by the length of LIST. Has the same
effect as
for $value (LIST) {
$ARRAY[++$#ARRAY] = $value;
}
but is more efficient. Returns the new number of
elements in the array.
q/STRING/
qq/STRING/
qx/STRING/
qw/STRING/
Generalized quotes. See the perlop manpage.
quotemeta EXPR
quotemeta
Returns the value of EXPR with all non-
alphanumeric characters backslashed. (That is,
all characters not matching /[A-Za-z_0-9]/ will be
preceded by a backslash in the returned string,
regardless of any locale settings.) This is the
internal function implementing the \Q escape in
double-quoted strings.
If EXPR is omitted, uses $_.
rand EXPR
rand Returns a random fractional number greater than or
equal to 0 and less than the value of EXPR. (EXPR
should be positive.) If EXPR is omitted, the
value 1 is used. Automatically calls srand()
unless srand() has already been called. See also
srand().
(Note: If your rand function consistently returns
numbers that are too large or too small, then your
version of Perl was probably compiled with the
wrong number of RANDBITS.)
read FILEHANDLE,SCALAR,LENGTH,OFFSET
read FILEHANDLE,SCALAR,LENGTH
Attempts to read LENGTH bytes of data into
variable SCALAR from the specified FILEHANDLE.
Returns the number of bytes actually read, or
undef if there was an error. SCALAR will be grown
or shrunk to the length actually read. An OFFSET
may be specified to place the read data at some
other place than the beginning of the string.
This call is actually implemented in terms of
stdio's fread call. To get a true read system
call, see sysread().
readdir DIRHANDLE
Returns the next directory entry for a directory
opened by opendir(). If used in a list context,
returns all the rest of the entries in the
directory. If there are no more entries, returns
an undefined value in a scalar context or a null
list in a list context.
If you're planning to filetest the return values
out of a readdir(), you'd better prepend the
directory in question. Otherwise, because we
didn't chdir() there, it would have been testing
the wrong file.
opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!";
@dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
closedir DIR;
readlink EXPR
readlink
Returns the value of a symbolic link, if symbolic
links are implemented. If not, gives a fatal
error. If there is some system error, returns the
undefined value and sets $! (errno). If EXPR is
omitted, uses $_.
recv SOCKET,SCALAR,LEN,FLAGS
Receives a message on a socket. Attempts to
receive LENGTH bytes of data into variable SCALAR
from the specified SOCKET filehandle. Actually
does a C recvfrom(), so that it can returns the
address of the sender. Returns the undefined
value if there's an error. SCALAR will be grown
or shrunk to the length actually read. Takes the
same flags as the system call of the same name.
See the section on UDP: Message Passing in the
perlipc manpage for examples.
redo LABEL
redo The redo command restarts the loop block without
evaluating the conditional again. The continue
block, if any, is not executed. If the LABEL is
omitted, the command refers to the innermost
enclosing loop. This command is normally used by
programs that want to lie to themselves about what
was just input:
# a simpleminded Pascal comment stripper
# (warning: assumes no { or } in strings)
LINE: while (<STDIN>) {
while (s|({.*}.*){.*}|$1 |) {}
s|{.*}| |;
if (s|{.*| |) {
$front = $_;
while (<STDIN>) {
if (/}/) { # end of comment?
s|^|$front{|;
redo LINE;
}
}
}
print;
}
ref EXPR
ref Returns a TRUE value if EXPR is a reference, FALSE
otherwise. If EXPR is not specified, $_ will be
used. The value returned depends on the type of
thing the reference is a reference to. Builtin
types include:
REF
SCALAR
ARRAY
HASH
CODE
GLOB
If the referenced object has been blessed into a
package, then that package name is returned
instead. You can think of ref() as a typeof()
operator.
if (ref($r) eq "HASH") {
print "r is a reference to a hash.\n";
}
if (!ref ($r) {
print "r is not a reference at all.\n";
}
See also the perlref manpage.
rename OLDNAME,NEWNAME
Changes the name of a file. Returns 1 for
success, 0 otherwise. Will not work across file
system boundaries.
require EXPR
require Demands some semantics specified by EXPR, or by $_
if EXPR is not supplied. If EXPR is numeric,
demands that the current version of Perl ($] or
$PERL_VERSION) be equal or greater than EXPR.
Otherwise, demands that a library file be included
if it hasn't already been included. The file is
included via the do-FILE mechanism, which is
essentially just a variety of eval(). Has
semantics similar to the following subroutine:
sub require {
local($filename) = @_;
return 1 if $INC{$filename};
local($realfilename,$result);
ITER: {
foreach $prefix (@INC) {
$realfilename = "$prefix/$filename";
if (-f $realfilename) {
$result = do $realfilename;
last ITER;
}
}
die "Can't find $filename in \@INC";
}
die $@ if $@;
die "$filename did not return true value" unless $result;
$INC{$filename} = $realfilename;
$result;
}
Note that the file will not be included twice
under the same specified name. The file must
return TRUE as the last statement to indicate
successful execution of any initialization code,
so it's customary to end such a file with "1;"
unless you're sure it'll return TRUE otherwise.
But it's better just to put the "1;", in case you
add more statements.
If EXPR is a bareword, the require assumes a ".pm"
extension and replaces "::" with "/" in the
filename for you, to make it easy to load standard
modules. This form of loading of modules does not
risk altering your namespace.
For a yet-more-powerful import facility, see the
use entry elsewhere in this document the perlmod
manpage.
reset EXPR
reset Generally used in a continue block at the end of a
loop to clear variables and reset ?? searches so
that they work again. The expression is
interpreted as a list of single characters
(hyphens allowed for ranges). All variables and
arrays beginning with one of those letters are
reset to their pristine state. If the expression
is omitted, one-match searches (?pattern?) are
reset to match again. Resets only variables or
searches in the current package. Always returns
1. Examples:
reset 'X'; # reset all X variables
reset 'a-z'; # reset lower case variables
reset; # just reset ?? searches
Resetting "A-Z" is not recommended because you'll
wipe out your ARGV and ENV arrays. Resets only
package variables--lexical variables are
unaffected, but they clean themselves up on scope
exit anyway, so you'll probably want to use them
instead. See the my entry elsewhere in this
document .
return EXPR
return Returns from a subroutine, eval(), or do FILE with
the value of the given EXPR. Evaluation of EXPR
may be in a list, scalar, or void context,
depending on how the return value will be used,
and the context may vary from one execution to the
next (see wantarray()). If no EXPR is given,
returns an empty list in a list context, an
undefined value in a scalar context, or nothing in
a void context.
(Note that in the absence of a return, a
subroutine, eval, or do FILE will automatically
return the value of the last expression
evaluated.)
reverse LIST
In a list context, returns a list value consisting
of the elements of LIST in the opposite order. In
a scalar context, concatenates the elements of
LIST, and returns a string value consisting of
those bytes, but in the opposite order.
print reverse <>; # line tac, last line first
undef $/; # for efficiency of <>
print scalar reverse <>; # byte tac, last line tsrif
This operator is also handy for inverting a hash,
although there are some caveats. If a value is
duplicated in the original hash, only one of those
can be represented as a key in the inverted hash.
Also, this has to unwind one hash and build a
whole new one, which may take some time on a large
hash.
%by_name = reverse %by_address; # Invert the hash
rewinddir DIRHANDLE
Sets the current position to the beginning of the
directory for the readdir() routine on DIRHANDLE.
rindex STR,SUBSTR,POSITION
rindex STR,SUBSTR
Works just like index except that it returns the
position of the LAST occurrence of SUBSTR in STR.
If POSITION is specified, returns the last
occurrence at or before that position.
rmdir FILENAME
rmdir Deletes the directory specified by FILENAME if it
is empty. If it succeeds it returns 1, otherwise
it returns 0 and sets $! (errno). If FILENAME is
omitted, uses $_.
s/// The substitution operator. See the perlop
manpage.
scalar EXPR
Forces EXPR to be interpreted in a scalar context
and returns the value of EXPR.
@counts = ( scalar @a, scalar @b, scalar @c );
There is no equivalent operator to force an
expression to be interpolated in a list context
because it's in practice never needed. If you
really wanted to do so, however, you could use the
construction @{[ (some expression) ]}, but usually
a simple (some expression) suffices.
seek FILEHANDLE,POSITION,WHENCE
Sets FILEHANDLE's position, just like the fseek()
call of stdio. FILEHANDLE may be an expression
whose value gives the name of the filehandle. The
values for WHENCE are 0 to set the new position to
POSITION, 1 to set it to the current position plus
POSITION, and 2 to set it to EOF plus POSITION
(typically negative). For WHENCE you may use the
constants SEEK_SET, SEEK_CUR, and SEEK_END from
either the IO::Seekable or the POSIX module.
Returns 1 upon success, 0 otherwise.
If you want to position file for sysread() or
syswrite(), don't use seek() -- buffering makes
its effect on the file's system position
unpredictable and non-portable. Use sysseek()
instead.
On some systems you have to do a seek whenever you
switch between reading and writing. Amongst other
things, this may have the effect of calling
stdio's clearerr(3). A WHENCE of 1 (SEEK_CUR) is
useful for not moving the file position:
seek(TEST,0,1);
This is also useful for applications emulating
tail -f. Once you hit EOF on your read, and then
sleep for a while, you might have to stick in a
seek() to reset things. The seek() doesn't change
the current position, but it does clear the end-
of-file condition on the handle, so that the next
<FILE> makes Perl try again to read something. We
hope.
If that doesn't work (some stdios are particularly
cantankerous), then you may need something more
like this:
for (;;) {
for ($curpos = tell(FILE); $_ = <FILE>; $curpos = tell(FILE)) {
# search for some stuff and put it into files
}
sleep($for_a_while);
seek(FILE, $curpos, 0);
}
seekdir DIRHANDLE,POS
Sets the current position for the readdir()
routine on DIRHANDLE. POS must be a value
returned by telldir(). Has the same caveats about
possible directory compaction as the corresponding
system library routine.
select FILEHANDLE
select Returns the currently selected filehandle. Sets
the current default filehandle for output, if
FILEHANDLE is supplied. This has two effects:
first, a write or a print without a filehandle
will default to this FILEHANDLE. Second,
references to variables related to output will
refer to this output channel. For example, if you
have to set the top of form format for more than
one output channel, you might do the following:
select(REPORT1);
$^ = 'report1_top';
select(REPORT2);
$^ = 'report2_top';
FILEHANDLE may be an expression whose value gives
the name of the actual filehandle. Thus:
$oldfh = select(STDERR); $| = 1; select($oldfh);
Some programmers may prefer to think of
filehandles as objects with methods, preferring to
write the last example as:
use IO::Handle;
STDERR->autoflush(1);
select RBITS,WBITS,EBITS,TIMEOUT
This calls the select(2) system call with the bit
masks specified, which can be constructed using
fileno() and vec(), along these lines:
$rin = $win = $ein = '';
vec($rin,fileno(STDIN),1) = 1;
vec($win,fileno(STDOUT),1) = 1;
$ein = $rin | $win;
If you want to select on many filehandles you
might wish to write a subroutine:
sub fhbits {
local(@fhlist) = split(' ',$_[0]);
local($bits);
for (@fhlist) {
vec($bits,fileno($_),1) = 1;
}
$bits;
}
$rin = fhbits('STDIN TTY SOCK');
The usual idiom is:
($nfound,$timeleft) =
select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
or to block until something becomes ready just do
this
$nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
Most systems do not bother to return anything
useful in $timeleft, so calling select() in a
scalar context just returns $nfound.
Any of the bit masks can also be undef. The
timeout, if specified, is in seconds, which may be
fractional. Note: not all implementations are
capable of returning the $timeleft. If not, they
always return $timeleft equal to the supplied
$timeout.
You can effect a sleep of 250 milliseconds this
way:
select(undef, undef, undef, 0.25);
WARNING: Do not attempt to mix buffered I/O (like
read() or <FH>) with select(). You have to use
sysread() instead.
semctl ID,SEMNUM,CMD,ARG
Calls the System V IPC function semctl. If CMD is
&IPC_STAT or &GETALL, then ARG must be a variable
which will hold the returned semid_ds structure or
semaphore value array. Returns like ioctl: the
undefined value for error, "0 but true" for zero,
or the actual return value otherwise.
semget KEY,NSEMS,FLAGS
Calls the System V IPC function semget. Returns
the semaphore id, or the undefined value if there
is an error.
semop KEY,OPSTRING
Calls the System V IPC function semop to perform
semaphore operations such as signaling and
waiting. OPSTRING must be a packed array of semop
structures. Each semop structure can be generated
with pack("sss", $semnum, $semop, $semflag). The
number of semaphore operations is implied by the
length of OPSTRING. Returns TRUE if successful,
or FALSE if there is an error. As an example, the
following code waits on semaphore $semnum of
semaphore id $semid:
$semop = pack("sss", $semnum, -1, 0);
die "Semaphore trouble: $!\n" unless semop($semid, $semop);
To signal the semaphore, replace "-1" with "1".
send SOCKET,MSG,FLAGS,TO
send SOCKET,MSG,FLAGS
Sends a message on a socket. Takes the same flags
as the system call of the same name. On
unconnected sockets you must specify a destination
to send TO, in which case it does a C sendto().
Returns the number of characters sent, or the
undefined value if there is an error. See the
section on UDP: Message Passing in the perlipc
manpage for examples.
setpgrp PID,PGRP
Sets the current process group for the specified
PID, 0 for the current process. Will produce a
fatal error if used on a machine that doesn't
implement setpgrp(2). If the arguments are
omitted, it defaults to 0,0. Note that the POSIX
version of setpgrp() does not accept any
arguments, so only setpgrp 0,0 is portable.
setpriority WHICH,WHO,PRIORITY
Sets the current priority for a process, a process
group, or a user. (See setpriority(2).) Will
produce a fatal error if used on a machine that
doesn't implement setpriority(2).
setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
Sets the socket option requested. Returns
undefined if there is an error. OPTVAL may be
specified as undef if you don't want to pass an
argument.
shift ARRAY
shift Shifts the first value of the array off and
returns it, shortening the array by 1 and moving
everything down. If there are no elements in the
array, returns the undefined value. If ARRAY is
omitted, shifts the @ARGV array in the main
program, and the @_ array in subroutines. (This
is determined lexically.) See also unshift(),
push(), and pop(). Shift() and unshift() do the
same thing to the left end of an array that pop()
and push() do to the right end.
shmctl ID,CMD,ARG
Calls the System V IPC function shmctl. If CMD is
&IPC_STAT, then ARG must be a variable which will
hold the returned shmid_ds structure. Returns
like ioctl: the undefined value for error, "0 but
true" for zero, or the actual return value
otherwise.
shmget KEY,SIZE,FLAGS
Calls the System V IPC function shmget. Returns
the shared memory segment id, or the undefined
value if there is an error.
shmread ID,VAR,POS,SIZE
shmwrite ID,STRING,POS,SIZE
Reads or writes the System V shared memory segment
ID starting at position POS for size SIZE by
attaching to it, copying in/out, and detaching
from it. When reading, VAR must be a variable
which will hold the data read. When writing, if
STRING is too long, only SIZE bytes are used; if
STRING is too short, nulls are written to fill out
SIZE bytes. Return TRUE if successful, or FALSE
if there is an error.
shutdown SOCKET,HOW
Shuts down a socket connection in the manner
indicated by HOW, which has the same
interpretation as in the system call of the same
name.
sin EXPR
sin Returns the sine of EXPR (expressed in radians).
If EXPR is omitted, returns sine of $_.
For the inverse sine operation, you may use the
POSIX::asin() function, or use this relation:
sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
sleep EXPR
sleep Causes the script to sleep for EXPR seconds, or
forever if no EXPR. May be interrupted by sending
the process a SIGALRM. Returns the number of
seconds actually slept. You probably cannot mix
alarm() and sleep() calls, because sleep() is
often implemented using alarm().
On some older systems, it may sleep up to a full
second less than what you requested, depending on
how it counts seconds. Most modern systems always
sleep the full amount.
For delays of finer granularity than one second,
you may use Perl's syscall() interface to access
setitimer(2) if your system supports it, or else
see the select() entry elsewhere in this document
below.
See also the POSIX module's sigpause() function.
socket SOCKET,DOMAIN,TYPE,PROTOCOL
Opens a socket of the specified kind and attaches
it to filehandle SOCKET. DOMAIN, TYPE, and
PROTOCOL are specified the same as for the system
call of the same name. You should "use Socket;"
first to get the proper definitions imported. See
the example in the section on Sockets:
Client/Server Communication in the perlipc
manpage.
socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
Creates an unnamed pair of sockets in the
specified domain, of the specified type. DOMAIN,
TYPE, and PROTOCOL are specified the same as for
the system call of the same name. If
unimplemented, yields a fatal error. Returns TRUE
if successful.
sort SUBNAME LIST
sort BLOCK LIST
sort LIST
Sorts the LIST and returns the sorted list value.
If SUBNAME or BLOCK is omitted, sorts in standard
string comparison order. If SUBNAME is specified,
it gives the name of a subroutine that returns an
integer less than, equal to, or greater than 0,
depending on how the elements of the array are to
be ordered. (The <=> and cmp operators are
extremely useful in such routines.) SUBNAME may
be a scalar variable name, in which case the value
provides the name of the subroutine to use. In
place of a SUBNAME, you can provide a BLOCK as an
anonymous, in-line sort subroutine.
In the interests of efficiency the normal calling
code for subroutines is bypassed, with the
following effects: the subroutine may not be a
recursive subroutine, and the two elements to be
compared are passed into the subroutine not via @_
but as the package global variables $a and $b (see
example below). They are passed by reference, so
don't modify $a and $b. And don't try to declare
them as lexicals either.
You also cannot exit out of the sort block or
subroutine using any of the loop control operators
described in the perlsyn manpage or with goto().
When use locale is in effect, sort LIST sorts LIST
according to the current collation locale. See
the perllocale manpage.
Examples:
# sort lexically
@articles = sort @files;
# same thing, but with explicit sort routine
@articles = sort {$a cmp $b} @files;
# now case-insensitively
@articles = sort {uc($a) cmp uc($b)} @files;
# same thing in reversed order
@articles = sort {$b cmp $a} @files;
# sort numerically ascending
@articles = sort {$a <=> $b} @files;
# sort numerically descending
@articles = sort {$b <=> $a} @files;
# sort using explicit subroutine name
sub byage {
$age{$a} <=> $age{$b}; # presuming numeric
}
@sortedclass = sort byage @class;
# this sorts the %age hash by value instead of key
# using an in-line function
@eldest = sort { $age{$b} <=> $age{$a} } keys %age;
sub backwards { $b cmp $a; }
@harry = ('dog','cat','x','Cain','Abel');
@george = ('gone','chased','yz','Punished','Axed');
print sort @harry;
# prints AbelCaincatdogx
print sort backwards @harry;
# prints xdogcatCainAbel
print sort @george, 'to', @harry;
# prints AbelAxedCainPunishedcatchaseddoggonetoxyz
# inefficiently sort by descending numeric compare using
# the first integer after the first = sign, or the
# whole record case-insensitively otherwise
@new = sort {
($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
||
uc($a) cmp uc($b)
} @old;
# same thing, but much more efficiently;
# we'll build auxiliary indices instead
# for speed
@nums = @caps = ();
for (@old) {
push @nums, /=(\d+)/;
push @caps, uc($_);
}
@new = @old[ sort {
$nums[$b] <=> $nums[$a]
||
$caps[$a] cmp $caps[$b]
} 0..$#old
];
# same thing using a Schwartzian Transform (no temps)
@new = map { $_->[0] }
sort { $b->[1] <=> $a->[1]
||
$a->[2] cmp $b->[2]
} map { [$_, /=(\d+)/, uc($_)] } @old;
If you're using strict, you MUST NOT declare $a
and $b as lexicals. They are package globals.
That means if you're in the main package, it's
@articles = sort {$main::b <=> $main::a} @files;
or just
@articles = sort {$::b <=> $::a} @files;
but if you're in the FooPack package, it's
@articles = sort {$FooPack::b <=> $FooPack::a} @files;
The comparison function is required to behave. If
it returns inconsistent results (sometimes saying
$x[1] is less than $x[2] and sometimes saying the
opposite, for example) the Perl interpreter will
probably crash and dump core. This is entirely
due to and dependent upon your system's qsort(3)
library routine; this routine often avoids sanity
checks in the interest of speed.
splice ARRAY,OFFSET,LENGTH,LIST
splice ARRAY,OFFSET,LENGTH
splice ARRAY,OFFSET
Removes the elements designated by OFFSET and
LENGTH from an array, and replaces them with the
elements of LIST, if any. Returns the elements
removed from the array. The array grows or
shrinks as necessary. If LENGTH is omitted,
removes everything from OFFSET onward. The
following equivalences hold (assuming $[ == 0):
push(@a,$x,$y) splice(@a,$#a+1,0,$x,$y)
pop(@a) splice(@a,-1)
shift(@a) splice(@a,0,1)
unshift(@a,$x,$y) splice(@a,0,0,$x,$y)
$a[$x] = $y splice(@a,$x,1,$y);
Example, assuming array lengths are passed before
arrays:
sub aeq { # compare two list values
local(@a) = splice(@_,0,shift);
local(@b) = splice(@_,0,shift);
return 0 unless @a == @b; # same len?
while (@a) {
return 0 if pop(@a) ne pop(@b);
}
return 1;
}
if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
split /PATTERN/,EXPR,LIMIT
split /PATTERN/,EXPR
split /PATTERN/
split Splits a string into an array of strings, and
returns it.
If not in a list context, returns the number of
fields found and splits into the @_ array. (In a
list context, you can force the split into @_ by
using ?? as the pattern delimiters, but it still
returns the array value.) The use of implicit
split to @_ is deprecated, however.
If EXPR is omitted, splits the $_ string. If
PATTERN is also omitted, splits on whitespace
(after skipping any leading whitespace). Anything
matching PATTERN is taken to be a delimiter
separating the fields. (Note that the delimiter
may be longer than one character.) If LIMIT is
specified and is not negative, splits into no more
than that many fields (though it may split into
fewer). If LIMIT is unspecified, trailing null
fields are stripped (which potential users of
pop() would do well to remember). If LIMIT is
negative, it is treated as if an arbitrarily large
LIMIT had been specified.
A pattern matching the null string (not to be
confused with a null pattern //, which is just one
member of the set of patterns matching a null
string) will split the value of EXPR into separate
characters at each point it matches that way. For
example:
print join(':', split(/ */, 'hi there'));
produces the output 'h:i:t:h:e:r:e'.
The LIMIT parameter can be used to split a line
partially
($login, $passwd, $remainder) = split(/:/, $_, 3);
When assigning to a list, if LIMIT is omitted,
Perl supplies a LIMIT one larger than the number
of variables in the list, to avoid unnecessary
work. For the list above LIMIT would have been 4
by default. In time critical applications it
behooves you not to split into more fields than
you really need.
If the PATTERN contains parentheses, additional
array elements are created from each matching
substring in the delimiter.
split(/([,-])/, "1-10,20", 3);
produces the list value
(1, '-', 10, ',', 20)
If you had the entire header of a normal Unix
email message in $header, you could split it up
into fields and their values this way:
$header =~ s/\n\s+/ /g; # fix continuation lines
%hdrs = (UNIX_FROM => split /^(.*?):\s*/m, $header);
The pattern /PATTERN/ may be replaced with an
expression to specify patterns that vary at
runtime. (To do runtime compilation only once,
use /$variable/o.)
As a special case, specifying a PATTERN of space
(' ') will split on white space just as split with
no arguments does. Thus, split(' ') can be used
to emulate awk's default behavior, whereas split(/
/) will give you as many null initial fields as
there are leading spaces. A split on /\s+/ is
like a split(' ') except that any leading
whitespace produces a null first field. A split
with no arguments really does a split(' ', $_)
internally.
Example:
open(passwd, '/etc/passwd');
while (<passwd>) {
($login, $passwd, $uid, $gid, $gcos,
$home, $shell) = split(/:/);
...
}
(Note that $shell above will still have a newline
on it. See the chop, chomp, and join entries
elsewhere in this document .)
sprintf FORMAT, LIST
Returns a string formatted by the usual printf
conventions of the C library function sprintf().
See the sprintf(3) manpage or the printf(3)
manpage on your system for an explanation of the
general principles.
Perl does all of its own sprintf() formatting --
it emulates the C function sprintf(), but it
doesn't use it (except for floating-point numbers,
and even then only the standard modifiers are
allowed). As a result, any non-standard
extensions in your local sprintf() are not
available from Perl.
Perl's sprintf() permits the following
universally-known conversions:
%% a percent sign
%c a character with the given number
%s a string
%d a signed integer, in decimal
%u an unsigned integer, in decimal
%o an unsigned integer, in octal
%x an unsigned integer, in hexadecimal
%e a floating-point number, in scientific notation
%f a floating-point number, in fixed decimal notation
%g a floating-point number, in %e or %f notation
In addition, Perl permits the following widely-
supported conversions:
%X like %x, but using upper-case letters
%E like %e, but using an upper-case "E"
%G like %g, but with an upper-case "E" (if applicable)
%p a pointer (outputs the Perl value's address in hexadecimal)
%n special: *stores* the number of characters output so far
into the next variable in the parameter list
Finally, for backward (and we do mean "backward")
compatibility, Perl permits these unnecessary but
widely-supported conversions:
%i a synonym for %d
%D a synonym for %ld
%U a synonym for %lu
%O a synonym for %lo
%F a synonym for %f
Perl permits the following universally-known flags
between the % and the conversion letter:
space prefix positive number with a space
+ prefix positive number with a plus sign
- left-justify within the field
0 use zeros, not spaces, to right-justify
# prefix octal with "0", hex with "0x"
number minimum field width
.number "precision": digits after decimal point for floating-point,
max length for string, minimum length for integer
l interpret integer as C type "long" or "unsigned long"
h interpret integer as C type "short" or "unsigned short"
There is also one Perl-specific flag:
V interpret integer as Perl's standard integer type
Where a number would appear in the flags, an
asterisk ("*") may be used instead, in which case
Perl uses the next item in the parameter list as
the given number (that is, as the field width or
precision). If a field width obtained through "*"
is negative, it has the same effect as the '-'
flag: left-justification.
If use locale is in effect, the character used for
the decimal point in formatted real numbers is
affected by the LC_NUMERIC locale. See the
perllocale manpage.
sqrt EXPR
sqrt Return the square root of EXPR. If EXPR is
omitted, returns square root of $_.
srand EXPR
srand Sets the random number seed for the rand operator.
If EXPR is omitted, uses a semi-random value based
on the current time and process ID, among other
things. In versions of Perl prior to 5.004 the
default seed was just the current time(). This
isn't a particularly good seed, so many old
programs supply their own seed value (often time ^
$$ or C<time ^ ($$ + ($$ << 15))>), but that isn't
necessary any more.
In fact, it's usually not necessary to call
srand() at all, because if it is not called
explicitly, it is called implicitly at the first
use of the rand operator. However, this was not
the case in version of Perl before 5.004, so if
your script will run under older Perl versions, it
should call srand().
Note that you need something much more random than
the default seed for cryptographic purposes.
Checksumming the compressed output of one or more
rapidly changing operating system status programs
is the usual method. For example:
srand (time ^ $$ ^ unpack "%L*", `ps axww | gzip`);
If you're particularly concerned with this, see
the Math::TrulyRandom module in CPAN.
Do not call srand() multiple times in your program
unless you know exactly what you're doing and why
you're doing it. The point of the function is to
"seed" the rand() function so that rand() can
produce a different sequence each time you run
your program. Just do it once at the top of your
program, or you won't get random numbers out of
rand()!
Frequently called programs (like CGI scripts) that
simply use
time ^ $$
for a seed can fall prey to the mathematical
property that
a^b == (a+1)^(b+1)
one-third of the time. So don't do that.
stat FILEHANDLE
stat EXPR
stat Returns a 13-element array giving the status info
for a file, either the file opened via FILEHANDLE,
or named by EXPR. If EXPR is omitted, it stats
$_. Returns a null list if the stat fails.
Typically used as follows:
($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
$atime,$mtime,$ctime,$blksize,$blocks)
= stat($filename);
Not all fields are supported on all filesystem
types. Here are the meaning of the fields:
0 dev device number of filesystem
1 ino inode number
2 mode file mode (type and permissions)
3 nlink number of (hard) links to the file
4 uid numeric user ID of file's owner
5 gid numeric group ID of file's owner
6 rdev the device identifier (special files only)
7 size total size of file, in bytes
8 atime last access time since the epoch
9 mtime last modify time since the epoch
10 ctime inode change time (NOT creation time!) since the epoch
11 blksize preferred block size for file system I/O
12 blocks actual number of blocks allocated
(The epoch was at 00:00 January 1, 1970 GMT.)
If stat is passed the special filehandle
consisting of an underline, no stat is done, but
the current contents of the stat structure from
the last stat or filetest are returned. Example:
if (-x $file && (($d) = stat(_)) && $d < 0) {
print "$file is executable NFS file\n";
}
(This works on machines only for which the device
number is negative under NFS.)
study SCALAR
study Takes extra time to study SCALAR ($_ if
unspecified) in anticipation of doing many pattern
matches on the string before it is next modified.
This may or may not save time, depending on the
nature and number of patterns you are searching
on, and on the distribution of character
frequencies in the string to be searched -- you
probably want to compare run times with and
without it to see which runs faster. Those loops
which scan for many short constant strings
(including the constant parts of more complex
patterns) will benefit most. You may have only
one study active at a time -- if you study a
different scalar the first is "unstudied". (The
way study works is this: a linked list of every
character in the string to be searched is made, so
we know, for example, where all the 'k' characters
are. From each search string, the rarest
character is selected, based on some static
frequency tables constructed from some C programs
and English text. Only those places that contain
this "rarest" character are examined.)
For example, here is a loop which inserts index
producing entries before any line containing a
certain pattern:
while (<>) {
study;
print ".IX foo\n" if /\bfoo\b/;
print ".IX bar\n" if /\bbar\b/;
print ".IX blurfl\n" if /\bblurfl\b/;
...
print;
}
In searching for /\bfoo\b/, only those locations
in $_ that contain "f" will be looked at, because
"f" is rarer than "o". In general, this is a big
win except in pathological cases. The only
question is whether it saves you more time than it
took to build the linked list in the first place.
Note that if you have to look for strings that you
don't know till runtime, you can build an entire
loop as a string and eval that to avoid
recompiling all your patterns all the time.
Together with undefining $/ to input entire files
as one record, this can be very fast, often faster
than specialized programs like fgrep(1). The
following scans a list of files (@files) for a
list of words (@words), and prints out the names
of those files that contain a match:
$search = 'while (<>) { study;';
foreach $word (@words) {
$search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n";
}
$search .= "}";
@ARGV = @files;
undef $/;
eval $search; # this screams
$/ = "\n"; # put back to normal input delimiter
foreach $file (sort keys(%seen)) {
print $file, "\n";
}
sub BLOCK
sub NAME
sub NAME BLOCK
This is subroutine definition, not a real function
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 the
perlsub manpage and the perlref manpage for
details.
substr EXPR,OFFSET,LEN
substr EXPR,OFFSET
Extracts a substring out of EXPR and returns it.
First character is at offset 0, or whatever you've
set $[ to (but don't do that). If OFFSET is
negative, starts that far from the end of the
string. If LEN is omitted, returns everything to
the end of the string. If LEN is negative, leaves
that many characters off the end of the string.
You can use the substr() function as an lvalue, in
which case EXPR must be an lvalue. If you assign
something shorter than LEN, the string will
shrink, and if you assign something longer than
LEN, the string will grow to accommodate it. To
keep the string the same length you may need to
pad or chop your value using sprintf().
symlink OLDFILE,NEWFILE
Creates a new filename symbolically linked to the
old filename. Returns 1 for success, 0 otherwise.
On systems that don't support symbolic links,
produces a fatal error at run time. To check for
that, use eval:
$symlink_exists = (eval {symlink("","")};, $@ eq '');
syscall LIST
Calls the system call specified as the first
element of the list, passing the remaining
elements as arguments to the system call. If
unimplemented, produces a fatal error. The
arguments are interpreted as follows: if a given
argument is numeric, the argument is passed as an
int. If not, the pointer to the string value is
passed. You are responsible to make sure a string
is pre-extended long enough to receive any result
that might be written into a string. If your
integer arguments are not literals and have never
been interpreted in a numeric context, you may
need to add 0 to them to force them to look like
numbers.
require 'syscall.ph'; # may need to run h2ph
syscall(&SYS_write, fileno(STDOUT), "hi there\n", 9);
Note that Perl supports passing of up to only 14
arguments to your system call, which in practice
should usually suffice.
sysopen FILEHANDLE,FILENAME,MODE
sysopen FILEHANDLE,FILENAME,MODE,PERMS
Opens the file whose filename is given by
FILENAME, and associates it with FILEHANDLE. If
FILEHANDLE is an expression, its value is used as
the name of the real filehandle wanted. This
function calls the underlying operating system's
open function with the parameters FILENAME, MODE,
PERMS.
The possible values and flag bits of the MODE
parameter are system-dependent; they are available
via the standard module Fcntl. However, for
historical reasons, some values are universal:
zero means read-only, one means write-only, and
two means read/write.
If the file named by FILENAME does not exist and
the open call creates it (typically because MODE
includes the O_CREAT flag), then the value of
PERMS specifies the permissions of the newly
created file. If PERMS is omitted, the default
value is 0666, which allows read and write for
all. This default is reasonable: see umask.
The IO::File module provides a more object-
oriented approach, if you're into that kind of
thing.
sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
sysread FILEHANDLE,SCALAR,LENGTH
Attempts to read LENGTH bytes of data into
variable SCALAR from the specified FILEHANDLE,
using the system call read(2). It bypasses stdio,
so mixing this with other kinds of reads, print(),
write(), seek(), or tell() can cause confusion.
Returns the number of bytes actually read, or
undef if there was an error. SCALAR will be grown
or shrunk so that the last byte actually read is
the last byte of the scalar after the read.
An OFFSET may be specified to place the read data
at some place in the string other than the
beginning. A negative OFFSET specifies placement
at that many bytes counting backwards from the end
of the string. A positive OFFSET greater than the
length of SCALAR results in the string being
padded to the required size with "\0" bytes before
the result of the read is appended.
sysseek FILEHANDLE,POSITION,WHENCE
Sets FILEHANDLE's system position using the system
call lseek(2). It bypasses stdio, so mixing this
with reads (other than sysread()), print(),
write(), seek(), or tell() may cause confusion.
FILEHANDLE may be an expression whose value gives
the name of the filehandle. The values for WHENCE
are 0 to set the new position to POSITION, 1 to
set the it to the current position plus POSITION,
and 2 to set it to EOF plus POSITION (typically
negative). For WHENCE, you may use the constants
SEEK_SET, SEEK_CUR, and SEEK_END from either the
IO::Seekable or the POSIX module.
Returns the new position, or the undefined value
on failure. A position of zero is returned as the
string "0 but true"; thus sysseek() returns TRUE
on success and FALSE on failure, yet you can still
easily determine the new position.
system LIST
Does exactly the same thing as "exec LIST" except
that a fork is done first, and the parent process
waits for the child process to complete. Note
that argument processing varies depending on the
number of arguments. The return value is the exit
status of the program as returned by the wait()
call. To get the actual exit value divide by 256.
See also the exec entry elsewhere in this document
. This is NOT what you want to use to capture the
output from a command, for that you should use
merely backticks or qx//, as described in the
section on `STRING` in the perlop manpage.
Because system() and backticks block SIGINT and
SIGQUIT, killing the program they're running
doesn't actually interrupt your program.
@args = ("command", "arg1", "arg2");
system(@args) == 0
or die "system @args failed: $?"
Here's a more elaborate example of analysing the
return value from system() on a Unix system to
check for all possibilities, including for signals
and core dumps.
$rc = 0xffff & system @args;
printf "system(%s) returned %#04x: ", "@args", $rc;
if ($rc == 0) {
print "ran with normal exit\n";
}
elsif ($rc == 0xff00) {
print "command failed: $!\n";
}
elsif ($rc > 0x80) {
$rc >>= 8;
print "ran with non-zero exit status $rc\n";
}
else {
print "ran with ";
if ($rc & 0x80) {
$rc &= ~0x80;
print "core dump from ";
}
print "signal $rc\n"
}
$ok = ($rc != 0);
syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
syswrite FILEHANDLE,SCALAR,LENGTH
Attempts to write LENGTH bytes of data from
variable SCALAR to the specified FILEHANDLE, using
the system call write(2). It bypasses stdio, so
mixing this with reads (other than sysread()),
print(), write(), seek(), or tell() may cause
confusion. Returns the number of bytes actually
written, or undef if there was an error. If the
length is greater than the available data, only as
much data as is available will be written.
An OFFSET may be specified to write the data from
some part of the string other than the beginning.
A negative OFFSET specifies writing that many
bytes counting backwards from the end of the
string.
tell FILEHANDLE
tell Returns the current position for FILEHANDLE.
FILEHANDLE may be an expression whose value gives
the name of the actual filehandle. If FILEHANDLE
is omitted, assumes the file last read.
telldir DIRHANDLE
Returns the current position of the readdir()
routines on DIRHANDLE. Value may be given to
seekdir() to access a particular location in a
directory. Has the same caveats about possible
directory compaction as the corresponding system
library routine.
tie VARIABLE,CLASSNAME,LIST
This function binds a variable to a package class
that will provide the implementation for the
variable. VARIABLE is the name of the variable to
be enchanted. CLASSNAME is the name of a class
implementing objects of correct type. Any
additional arguments are passed to the "new"
method of the class (meaning TIESCALAR, TIEARRAY,
or TIEHASH). Typically these are arguments such
as might be passed to the dbm_open() function of
C. The object returned by the "new" method is
also returned by the tie() function, which would
be useful if you want to access other methods in
CLASSNAME.
Note that functions such as keys() and values()
may return huge array values when used on large
objects, like DBM files. You may prefer to use
the each() function to iterate over such.
Example:
# print out history file offsets
use NDBM_File;
tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
while (($key,$val) = each %HIST) {
print $key, ' = ', unpack('L',$val), "\n";
}
untie(%HIST);
A class implementing a hash should have the
following methods:
TIEHASH classname, LIST
DESTROY this
FETCH this, key
STORE this, key, value
DELETE this, key
EXISTS this, key
FIRSTKEY this
NEXTKEY this, lastkey
A class implementing an ordinary array should have
the following methods:
TIEARRAY classname, LIST
DESTROY this
FETCH this, key
STORE this, key, value
[others TBD]
A class implementing a scalar should have the
following methods:
TIESCALAR classname, LIST
DESTROY this
FETCH this,
STORE this, value
Unlike dbmopen(), the tie() function will not use
or require a module for you--you need to do that
explicitly yourself. See the DB_File manpage or
the Config module for interesting tie()
implementations.
tied VARIABLE
Returns a reference to the object underlying
VARIABLE (the same value that was originally
returned by the tie() call which bound the
variable to a package.) Returns the undefined
value if VARIABLE isn't tied to a package.
time Returns the number of non-leap seconds since
whatever time the system considers to be the epoch
(that's 00:00:00, January 1, 1904 for MacOS, and
00:00:00 UTC, January 1, 1970 for most other
systems). Suitable for feeding to gmtime() and
localtime().
times Returns a four-element array giving the user and
system times, in seconds, for this process and the
children of this process.
($user,$system,$cuser,$csystem) = times;
tr/// The translation operator. Same as y///. See the
perlop manpage.
truncate FILEHANDLE,LENGTH
truncate EXPR,LENGTH
Truncates the file opened on FILEHANDLE, or named
by EXPR, to the specified length. Produces a
fatal error if truncate isn't implemented on your
system.
uc EXPR
uc Returns an uppercased version of EXPR. This is
the internal function implementing the \U escape
in double-quoted strings. Respects current
LC_CTYPE locale if use locale in force. See the
perllocale manpage.
If EXPR is omitted, uses $_.
ucfirst EXPR
ucfirst Returns the value of EXPR with the first character
uppercased. This is the internal function
implementing the \u escape in double-quoted
strings. Respects current LC_CTYPE locale if use
locale in force. See the perllocale manpage.
If EXPR is omitted, uses $_.
umask EXPR
umask Sets the umask for the process to EXPR and returns
the previous value. If EXPR is omitted, merely
returns the current umask. Remember that a umask
is a number, usually given in octal; it is not a
string of octal digits. See also the oct entry
elsewhere in this document if all you have is a
string.
undef EXPR
undef Undefines the value of EXPR, which must be an
lvalue. Use only on a scalar value, an entire
array, an entire hash, or a subroutine name (using
"&"). (Using undef() will probably not do what
you expect on most predefined variables or DBM
list values, so don't do that.) Always returns
the undefined value. You can omit the EXPR, in
which case nothing is undefined, but you still get
an undefined value that you could, for instance,
return from a subroutine, assign to a variable or
pass as a parameter. Examples:
undef $foo;
undef $bar{'blurfl'}; # Compare to: delete $bar{'blurfl'};
undef @ary;
undef %hash;
undef &mysub;
return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
select undef, undef, undef, 0.25;
($a, $b, undef, $c) = &foo; # Ignore third value returned
unlink LIST
unlink Deletes a list of files. Returns the number of
files successfully deleted.
$cnt = unlink 'a', 'b', 'c';
unlink @goners;
unlink <*.bak>;
Note: unlink will not delete directories unless
you are superuser and the -U flag is supplied to
Perl. Even if these conditions are met, be warned
that unlinking a directory can inflict damage on
your filesystem. Use rmdir instead.
If LIST is omitted, uses $_.
unpack TEMPLATE,EXPR
Unpack does the reverse of pack: it takes a string
representing a structure and expands it out into a
list value, returning the array value. (In a
scalar context, it returns merely the first value
produced.) The TEMPLATE has the same format as in
the pack function. Here's a subroutine that does
substring:
sub substr {
local($what,$where,$howmuch) = @_;
unpack("x$where a$howmuch", $what);
}
and then there's
sub ordinal { unpack("c",$_[0]); } # same as ord()
In addition, you may prefix a field with a
%<number> to indicate that you want a <number>-bit
checksum of the items instead of the items
themselves. Default is a 16-bit checksum. For
example, the following computes the same number as
the System V sum program:
while (<>) {
$checksum += unpack("%16C*", $_);
}
$checksum %= 65536;
The following efficiently counts the number of set
bits in a bit vector:
$setbits = unpack("%32b*", $selectmask);
untie VARIABLE
Breaks the binding between a variable and a
package. (See tie().)
unshift ARRAY,LIST
Does the opposite of a shift. Or the opposite of
a push, depending on how you look at it. Prepends
list to the front of the array, and returns the
new number of elements in the array.
unshift(ARGV, '-e') unless $ARGV[0] =~ /^-/;
Note the LIST is prepended whole, not one element
at a time, so the prepended elements stay in the
same order. Use reverse to do the reverse.
use Module LIST
use Module
use Module VERSION LIST
use VERSION
Imports some semantics into the current package
from the named module, generally by aliasing
certain subroutine or variable names into your
package. It is exactly equivalent to
BEGIN { require Module; import Module LIST; }
except that Module must be a bareword.
If the first argument to use is a number, it is
treated as a version number instead of a module
name. If the version of the Perl interpreter is
less than VERSION, then an error message is
printed and Perl exits immediately. This is often
useful if you need to check the current Perl
version before useing library modules which have
changed in incompatible ways from older versions
of Perl. (We try not to do this more than we have
to.)
The BEGIN forces the require and import to happen
at compile time. The require makes sure the
module is loaded into memory if it hasn't been
yet. The import is not a builtin--it's just an
ordinary static method call into the "Module"
package to tell the module to import the list of
features back into the current package. The
module can implement its import method any way it
likes, though most modules just choose to derive
their import method via inheritance from the
Exporter class that is defined in the Exporter
module. See the Exporter manpage. If no import
method can be found then the error is currently
silently ignored. This may change to a fatal
error in a future version.
If you don't want your namespace altered,
explicitly supply an empty list:
use Module ();
That is exactly equivalent to
BEGIN { require Module; }
If the VERSION argument is present between Module
and LIST, then the use will call the VERSION
method in class Module with the given version as
an argument. The default VERSION method,
inherited from the Universal class, croaks if the
given version is larger than the value of the
variable $Module::VERSION. (Note that there is
not a comma after VERSION!)
Because this is a wide-open interface, pragmas
(compiler directives) are also implemented this
way. Currently implemented pragmas are:
use integer;
use diagnostics;
use sigtrap qw(SEGV BUS);
use strict qw(subs vars refs);
use subs qw(afunc blurfl);
These pseudo-modules import semantics into the
current block scope, unlike ordinary modules,
which import symbols into the current package
(which are effective through the end of the file).
There's a corresponding "no" command that
unimports meanings imported by use, i.e., it calls
unimport Module LIST instead of import.
no integer;
no strict 'refs';
If no unimport method can be found the call fails
with a fatal error.
See the perlmod manpage for a list of standard
modules and pragmas.
utime LIST
Changes the access and modification times on each
file of a list of files. The first two elements
of the list must be the NUMERICAL access and
modification times, in that order. Returns the
number of files successfully changed. The inode
modification time of each file is set to the
current time. Example of a "touch" command:
#!/usr/bin/perl
$now = time;
utime $now, $now, @ARGV;
values HASH
Returns a normal array consisting of all the
values of the named hash. (In a scalar context,
returns the number of values.) The values are
returned in an apparently random order, but it is
the same order as either the keys() or each()
function would produce on the same hash. As a
side effect, it resets HASH's iterator. See also
keys(), each(), and sort().
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.
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 vec() can also be manipulated
with the logical operators |, &, and ^, which will
assume a bit vector operation is desired when both
operands are strings.
To transform a bit vector into a string or array
of 0's and 1's, use these:
$bits = unpack("b*", $vector);
@bits = split(//, unpack("b*", $vector));
If you know the exact length in bits, it can be
used in place of the *.
wait Waits for a child process to terminate and returns
the pid of the deceased process, or -1 if there
are no child processes. The status is returned in
$?.
waitpid PID,FLAGS
Waits for a particular child process to terminate
and returns the pid of the deceased process, or -1
if there is no such child process. The status is
returned in $?. If you say
use POSIX ":sys_wait_h";
...
waitpid(-1,&WNOHANG);
then you can do a non-blocking wait for any
process. Non-blocking wait is available on
machines supporting either the waitpid(2) or
wait4(2) system calls. However, waiting for a
particular pid with FLAGS of 0 is implemented
everywhere. (Perl emulates the system call by
remembering the status values of processes that
have exited but have not been harvested by the
Perl script yet.)
wantarray
Returns TRUE if the context of the currently
executing subroutine is looking for a list value.
Returns FALSE if the context is looking for a
scalar. Returns the undefined value if the
context is looking for no value (void context).
return unless defined wantarray; # don't bother doing more
my @a = complex_calculation();
return wantarray ? @a : "@a";
warn LIST
Produces a message on STDERR just like die(), but
doesn't exit or throw an exception.
No message is printed if there is a $SIG{__WARN__}
handler installed. It is the handler's
responsibility to deal with the message as it sees
fit (like, for instance, converting it into a
die()). Most handlers must therefore make
arrangements to actually display the warnings that
they are not prepared to deal with, by calling
warn() again in the handler. Note that this is
quite safe and will not produce an endless loop,
since __WARN__ hooks are not called from inside
one.
You will find this behavior is slightly different
from that of $SIG{__DIE__} handlers (which don't
suppress the error text, but can instead call
die() again to change it).
Using a __WARN__ handler provides a powerful way
to silence all warnings (even the so-called
mandatory ones). An example:
# wipe out *all* compile-time warnings
BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } }
my $foo = 10;
my $foo = 20; # no warning about duplicate my $foo,
# but hey, you asked for it!
# no compile-time or run-time warnings before here
$DOWARN = 1;
# run-time warnings enabled after here
warn "\$foo is alive and $foo!"; # does show up
See the perlvar manpage for details on setting
%SIG entries, and for more examples.
write FILEHANDLE
write EXPR
write Writes a formatted record (possibly multi-line) to
the specified file, using the format associated
with that file. By default the format for a file
is the one having the same name as the filehandle,
but the format for the current output channel (see
the select() function) may be set explicitly by
assigning the name of the format to the $~
variable.
Top of form processing is handled automatically:
if there is insufficient room on the current page
for the formatted record, the page is advanced by
writing a form feed, a special top-of-page format
is used to format the new page header, and then
the record is written. By default the top-of-page
format is the name of the filehandle with "_TOP"
appended, but it may be dynamically set to the
format of your choice by assigning the name to the
$^ variable while the filehandle is selected. The
number of lines remaining on the current page is
in variable $-, which can be set to 0 to force a
new page.
If FILEHANDLE is unspecified, output goes to the
current default output channel, which starts out
as STDOUT but may be changed by the select
operator. If the FILEHANDLE is an EXPR, then the
expression is evaluated and the resulting string
is used to look up the name of the FILEHANDLE at
run time. For more on formats, see the perlform
manpage.
Note that write is NOT the opposite of read.
Unfortunately.
y/// The translation operator. Same as tr///. See the
perlop manpage.
Hurricane Electric Internet Services
Copyright (C) 1998
Hurricane Electric.
All Rights Reserved.