PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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
or 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 such list
argument.) For instance, splice() has three scalar
arguments followed by a list, whereas gethostbyname() has
four scalar arguments.
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.
29/Apr/1999 perl 5.005, patch 03 1
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
A few functions take no arguments at all, and therefore
work as neither unary nor list operators. These include
such functions as time and endpwent. For example,
time+86_400 always means time() + 86_400.
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 important rule: There is no rule
that relates the behavior of an expression in list context
to its behavior in scalar context, or vice versa. It
might do two totally different things. Each operator and
function decides which sort of value it would be most
appropriate to return in scalar context. Some operators
return the length of the list that would have been
returned in 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.
An named array in scalar context is quite different from
what would at first glance appear to be a list in scalar
context. You can't get a list like (1,2,3) into being in
scalar context, because the compiler knows the context at
compile time. It would generate the scalar comma operator
there, not the list construction version of the comma.
That means it was never a list to start with.
In general, functions in Perl that serve as wrappers for
system calls of the same name (like chown(2), fork(2),
closedir(2), etc.) all return true when they succeed and
undef otherwise, as is usually mentioned in the
descriptions below. This is different from the C
interfaces, which return -1 on failure. Exceptions to
this rule are wait(), waitpid(), and syscall(). System
calls also set the special $! variable on failure. Other
functions do not, except accidentally.
Perl Functions by Category
Here are Perl's functions (including things that look like
functions, like some 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///
29/Apr/1999 perl 5.005, patch 03 2
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
Regular expressions and pattern matching
m//, pos, quotemeta, s///, split, study, qr//
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
29/Apr/1999 perl 5.005, patch 03 3
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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
Portability
Perl was born in Unix and can therefore access all common
Unix system calls. In non-Unix environments, the
functionality of some Unix system calls may not be
available, or details of the available functionality may
differ slightly. The Perl functions affected by this are:
-X, binmode, chmod, chown, chroot, crypt, dbmclose,
dbmopen, dump, endgrent, endhostent, endnetent,
endprotoent, endpwent, endservent, exec, fcntl, flock,
fork, getgrent, getgrgid, gethostent, getlogin,
getnetbyaddr, getnetbyname, getnetent, getppid, getprgp,
getpriority, getprotobynumber, getprotoent, getpwent,
getpwnam, getpwuid, getservbyport, getservent, getsockopt,
glob, ioctl, kill, link, lstat, msgctl, msgget, msgrcv,
msgsnd, open, pipe, readlink, rename, select, semctl,
29/Apr/1999 perl 5.005, patch 03 4
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
semget, semop, setgrent, sethostent, setnetent, setpgrp,
setpriority, setprotoent, setpwent, setservent,
setsockopt, shmctl, shmget, shmread, shmwrite, socket,
socketpair, stat, symlink, syscall, sysopen, system,
times, truncate, umask, unlink, utime, wait, waitpid
For more information about the portability of these
functions, see the perlport manpage and other available
platform-specific documentation.
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), or Filehandle is a pipe.
-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.
29/Apr/1999 perl 5.005, patch 03 5
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
-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.
Example:
while (<>) {
chop;
next unless -f $_; # ignore specials
#...
}
The interpretation of the file permission
operators -r, -R, -w, -W, -x, and -X is by default
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. Such reasons may be for example network
filesystem access controls, ACLs (access control
lists), read-only filesystems, and unrecognized
executable formats.
Also note that, for the superuser on the local
filesystems, the -r, -R, -w, and -W tests 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 their effective uid to something
else.
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
strange 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
29/Apr/1999 perl 5.005, patch 03 6
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 the
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.
29/Apr/1999 perl 5.005, patch 03 7
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
For delays of finer granularity than one second,
you may use Perl's four-arugment version of
select() leaving the first three arguments
undefined, or you might be able to use the
syscall() interface to access setitimer(2) if your
system supports it. The Time::HiRes module from
CPAN may also prove useful.
It is usually a mistake to intermix 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, modulo
the caveats given in the section on Signals in the
perlipc manpage.
eval {
local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
alarm $timeout;
$nread = sysread SOCKET, $buffer, $size;
alarm 0;
};
if ($@) {
die unless $@ eq "alarm\n"; # propagate unexpected errors
# 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.
29/Apr/1999 perl 5.005, patch 03 8
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 many
sytems, but 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, MacOS, and Plan9 that
delimit lines with a single character, and that
encode that character in C as "\n", do not need
binmode(). The rest may need it. If FILEHANDLE
is an expression, the value is taken as the name
of the filehandle.
If the system does care about it, using it when
you shouldn't is just as perilous as failing to
use it when you should. Fortunately for most of
us, you can't go wrong using binmode() on systems
that don't care about it, though.
bless REF,CLASSNAME
bless REF
This function tells the thingy referenced by REF
that it is now an object in the CLASSNAME package.
If CLASSNAME is omitted, the current package is
used. Because a bless() is often the last thing
in a constructor. it returns the reference for
convenience. Always use the two-argument version
if the function doing the blessing might be
inherited by a derived class. See the perltoot
manpage and the perlobj manpage for more about the
blessing (and blessings) of objects.
Consider always blessing objects in CLASSNAMEs
that are mixed case. Namespaces with all
lowercase names are considered reserved for Perl
pragmata. Builtin types have all uppercase names,
so to prevent confusion, you may wish to avoid
such package names as well. Make sure that
CLASSNAME is a true value.
See the section on Perl Modules in the perlmod
manpage.
caller EXPR
caller Returns the context of the current subroutine
call. In scalar context, returns the caller's
29/Apr/1999 perl 5.005, patch 03 9
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 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.
Be aware that the optimizer might have optimized
call frames away before caller() had a chance to
get the information. That means that caller(N)
might not return information about the call frame
you expect it do, for N > 1. In particular,
@DB::args might have information from the previous
time caller() was called.
chdir EXPR
Changes the working directory to EXPR, if
possible. If EXPR is omitted, changes to the
user's home directory. Returns TRUE upon success,
FALSE otherwise. See the 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 documentif all you
have is a string.
29/Apr/1999 perl 5.005, patch 03 10
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
$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 safer version of the chop entry elsewhere in
this documentremoves any trailing string 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:
29/Apr/1999 perl 5.005, patch 03 11
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 = glob($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
29/Apr/1999 perl 5.005, patch 03 12
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
elsewhere in this document.
If NUMBER is omitted, uses $_.
chroot FILENAME
chroot This function works like 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 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 a chroot() to $_.
close FILEHANDLE
close Closes the file or pipe associated with the file
handle, returning TRUE only if stdio successfully
flushes buffers and closes the system file
descriptor. Closes the currently selected
filehandle if the argument is omitted.
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.
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 only problem
was that the program exited non-zero $! will be
set to 0.) Closing a pipe also waits for the
process executing on the pipe to complete, in case
you want to look at the output of the pipe
afterwards, and implicitly puts the exit status
value of that command into $?.
Example:
open(OUTPUT, '|sort >foo') # pipe to sort
or die "Can't start sort: $!";
#... # print stuff to output
close OUTPUT # wait for sort to finish
or warn $! ? "Error closing sort pipe: $!"
: "Exit status $? from sort";
open(INPUT, 'foo') # get sort's results
or die "Can't open 'foo' for input: $!";
FILEHANDLE may be an expression whose value can be
used as an indirect filehandle, usually the real
29/Apr/1999 perl 5.005, patch 03 13
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
filehandle name.
closedir DIRHANDLE
Closes a directory opened by opendir() and returns
the success of that system call.
DIRHANDLE may be an expression whose value can be
used as an indirect dirhandle, usually the real
dirhandle name.
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).
last, next, or redo may appear within a continue
block. last and redo will behave as if they had
been executed within the main block. So will next,
but since it will execute a continue block, it may
be more entertaining.
while (EXPR) {
### redo always comes here
do_something;
} continue {
### next always comes here
do_something_else;
# then back the top to re-check EXPR
}
### last always comes here
Omitting the continue section is semantically
equivalent to using an empty one, logically
enough. In that case, next goes directly back to
check the condition at the top of the loop.
cos EXPR
Returns the cosine of EXPR (expressed in radians).
If EXPR is omitted, takes cosine of $_.
29/Apr/1999 perl 5.005, patch 03 14
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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.)
When verifying an existing encrypted string you
should use the encrypted text as the salt (like
crypt($plain, $crypted) eq $crypted). This allows
your code to work with the standard crypt() and
with more exotic implementations. When choosing a
new salt create a random two character string
whose characters come from the set [./0-9A-Za-z]
(like join '', ('.', '/', 0..9, 'A'..'Z',
'a'..'z')[rand 64, rand 64]).
Here's an example that makes sure that whoever
runs this program knows their own password:
$pwd = (getpwuid($<))[1];
system "stty -echo";
print "Password: ";
chomp($word = <STDIN>);
print "\n";
system "stty echo";
if (crypt($word, $pwd) ne $pwd) {
die "Sorry...\n";
} else {
print "ok\n";
}
Of course, typing in your own password to whoever
asks you for it is unwise.
dbmclose HASH
[This function has been largely superseded by the
29/Apr/1999 perl 5.005, patch 03 15
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
untie() function.]
Breaks the binding between a DBM file and a hash.
dbmopen HASH,DBNAME,MODE
[This function has been largely superseded by the
tie() function.]
This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), 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 lists 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.
You can control which DBM library you use by
loading that library before you call dbmopen():
use DB_File;
dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db")
or die "Can't open netscape history file: $!";
29/Apr/1999 perl 5.005, patch 03 16
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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, by saying defined &func without
parentheses. 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 documentfor 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 zero 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
29/Apr/1999 perl 5.005, patch 03 17
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 shouldn'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. The normal way to
free up space used by an aggregate is to assign
the empty list.
This counterintuitive behavior 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 just assigning
the empty list or undefining it:
29/Apr/1999 perl 5.005, patch 03 18
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
%hash = (); # completely empty %hash
undef %hash; # forget %hash every existed
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 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. Note that the "input line number" (also
known as "chunk") is subject to whatever notion of
"line" happens to be currently in effect, and is
also available as the special variable $.. See
the section on $/ in the perlvar manpage and the
section on $. in the perlvar manpage.
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(), warn(), and the Carp module.
If LIST is empty and $@ already contains a value
(typically from a previous eval) that value is
reused after appending "\t...propagated". This is
29/Apr/1999 perl 5.005, patch 03 19
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
useful for propagating exceptions:
eval { ... };
die unless $@ =~ /Expected exception/;
If $@ is empty then the string "Died" is used.
die() can also be called with a reference
argument. If this happens to be trapped within an
eval(), $@ contains the reference. This behavior
permits a more elaborate exception handling
implementation using objects that maintain
arbitary state about the nature of the exception.
Such a scheme is sometimes preferable to matching
particular string values of $@ using regular
expressions. Here's an example:
eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
if ($@) {
if (ref($@) && UNIVERSAL::isa($@,"Some::Module::Exception")) {
# handle Some::Module::Exception
}
else {
# handle all other possible exceptions
}
}
Since perl will stringify uncaught exception
messages before displaying them, you may want to
overload stringification operations on such custom
exception objects. See the overload manpage for
details about that.
You can arrange for a callback to be run 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 section on $SIG{expr} in the
perlvar manpage for details on setting %SIG
entries, and the section on eval BLOCK for some
examples.
Note that the $SIG{__DIE__} hook is currently
called even inside eval()ed blocks/strings! If
one wants the hook to do nothing in such
situations, put
die @_ if $^S;
as the first line of the handler (see the section
on $^S in the perlvar manpage). Because this
promotes action at a distance, this
counterintuitive behavior may be fixed in a future
29/Apr/1999 perl 5.005, patch 03 20
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
release.
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 BLOCK does not count as a loop, so the loop
control statements next, last, or redo cannot be
used to leave or restart the block. See the
perlsyn manpage for alternative strategies.
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
scalar eval `cat stat.pl`;
except that it's more efficient and concise, keeps
track of the current filename for error messages,
searches the @INC libraries, and updates %INC if
the file is found. See the section on Predefined
Names in the perlvar manpage for these variables.
It also differs in that code evaluated with do
FILENAME cannot see lexicals in the enclosing
scope; eval STRING does. 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.
If do cannot read the file, it returns undef and
sets $! to the error. If do can read the file but
cannot compile it, it returns undef and sets an
error message in $@. If the file is successfully
compiled, do returns the value of the last
expression evaluated.
Note that inclusion of library modules is better
done with the use() and require() operators, which
also do automatic error checking and raise an
exception if there's a problem.
29/Apr/1999 perl 5.005, patch 03 21
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
You might like to use do to read in a program
configuration file. Manual error checking can be
done this way:
# read in config files: system first, then user
for $file ("/share/prog/defaults.rc",
"$ENV{HOME}/.someprogrc")
{
unless ($return = do $file) {
warn "couldn't parse $file: $@" if $@;
warn "couldn't do $file: $!" unless defined $return;
warn "couldn't run $file" unless $return;
}
}
dump LABEL
dump 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');
This operator is largely obsolete, partly because
29/Apr/1999 perl 5.005, patch 03 22
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
it's very hard to convert a core file into an
executable, and because the real perl-to-C
compiler has superseded it.
each HASH
When called in list context, returns a 2-element
list consisting of the key and value for the next
element of a hash, so that you can iterate over
it. When called in 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. The actual random order is subject to
change in future versions of perl, but it is
guaranteed to be in the same order as either the
keys() or values() function would produce on the
same (unmodified) hash.
When the hash is entirely read, a null array is
returned in list context (which when assigned
produces a FALSE (0) value), and undef in 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(), values() and sort().
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. (Note that this function
actually reads a character and then ungetc()s it,
so isn't very useful in an interactive context.)
Do not read from a terminal file (or call
29/Apr/1999 perl 5.005, patch 03 23
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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. Using eof() with empty parentheses
is very different. It indicates 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 (<>) {
next if /^\s*#/; # skip comments
print "$.\t$_";
} continue {
close ARGV if eof; # Not eof()!
}
# insert dashes just before last line of last file
while (<>) {
if (eof()) { # check for end of current file
print "--------------\n";
close(ARGV); # close or last; 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 false
values when they run out of data, or if there was
an error.
eval EXPR
eval BLOCK
In the first form, the return value of EXPR is
parsed and executed as if it were a little Perl
program. The value of the expression (which is
itself determined within scalar context) is first
parsed, and if there weren't any errors, executed
in the context of the current Perl program, so
that any variable settings or subroutine and
format definitions remain afterwards. Note that
the value is parsed every time the eval executes.
If EXPR is omitted, evaluates $_. This form is
typically used to delay parsing and subsequent
execution of the text of EXPR until run time.
In the second form, the code within the BLOCK is
parsed only once--at the same time the code
29/Apr/1999 perl 5.005, patch 03 24
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
surrounding the eval itself was parsed--and
executed within the context of the current Perl
program. This form is typically used to trap
exceptions more efficiently than the first (see
below), while also providing the benefit of
checking the code within BLOCK at compile time.
The final semicolon, if any, may be omitted from
the value of EXPR or within the BLOCK.
In both forms, the value returned is the value of
the last expression evaluated inside the mini-
program; a return statement may be also used, just
as with subroutines. The expression providing the
return value is evaluated in void, scalar, or list
context, depending on the context of the eval
itself. See the wantarray entry elsewhere in this
documentfor more on how the evaluation context can
be determined.
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. 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 the warn
entry elsewhere in this document 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 = }; # WRONG
29/Apr/1999 perl 5.005, patch 03 25
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
# a run-time error
eval '$answer ='; # sets $@
Due to the current arguably broken state of
__DIE__ hooks, 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 lives here" };
print $@ if $@; # prints "bar lives here"
}
Because this promotes action at a distance, this
counterintuive behavior may be fixed in a future
release.
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,
29/Apr/1999 perl 5.005, patch 03 26
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
except that in this particular situation, you can
just use symbolic references instead, as in case
6.
eval BLOCK does not count as a loop, so the loop
control statements next, last, or redo cannot be
used to leave or restart the block.
exec LIST
exec PROGRAM LIST
The exec() function executes a system command AND
NEVER RETURNS - use system() instead of exec() if
you want it to return. It fails and returns FALSE
only if the command does not exist and it is
executed directly instead of via your system's
command shell (see below).
Since it's a common mistake to use exec() instead
of system(), Perl warns you if there is a
following statement which isn't die(), warn(), or
exit() (if -w is set - but you always do that).
If you really want to follow an exec() with some
other statement, you can use one of these styles
to avoid the warning:
exec ('foo') or print STDERR "couldn't exec foo: $!";
{ exec ('foo') }; print STDERR "couldn't exec foo: $!";
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 or an array with one
element in it, the argument is checked for shell
metacharacters, and if there are any, the entire
argument is passed to the system's command shell
for parsing (this is /bin/sh -c on Unix platforms,
but varies on other platforms). If there are no
shell metacharacters in the argument, it 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
29/Apr/1999 perl 5.005, patch 03 27
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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
When the arguments get executed via the system
shell, results will be subject to its quirks and
capabilities. See the section on `STRING` in the
perlop manpage for details.
Using an indirect object with exec() or system()
is also more secure. This usage forces
interpretation of the arguments as a multivalued
list, even if the list had just one argument.
That way you're safe from the shell expanding
wildcards or splitting up words with whitespace in
them.
@args = ( "echo surprise" );
exec @args; # subject to shell escapes
# if @args == 1
exec { $args[0] } @args; # safe even with one-arg list
The first version, the one without the indirect
object, ran the echo program, passing it
"surprise" an argument. The second version
didn't--it tried to run a program literally called
"echo surprise", didn't find it, and set $? to a
non-zero value indicating failure.
Note that exec() will not call your END blocks,
nor will it call any DESTROY methods in your
objects.
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
29/Apr/1999 perl 5.005, patch 03 28
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
lookup:
if (exists $ref->{A}->{B}->{$key}) { }
if (exists $hash{A}{B}{$key}) { }
Although the last element will not spring into
existence just because its existence was tested,
intervening ones will. Thus $ref->{"A"} and
$ref->{"A"}->{"B"} will spring into existence due
to the existence test for a $key element. This
happens anywhere the arrow operator is used,
including even
undef $ref;
if (exists $ref->{"Some key"}) { }
print $ref; # prints HASH(0x80d3d5c)
This surprising autovivification in what does not
at first--or even second--glance appear to be an
lvalue context may be fixed in a future release.
exit EXPR
Evaluates EXPR and exits immediately with that
value. Example:
$ans = <STDIN>;
exit 0 if $ans =~ /^[Xx]/;
See also die(). If EXPR is omitted, exits with 0
status. The only universally recognized values
for EXPR are 0 for success and 1 for error; other
values are subject to interpretation depending on
the environment in which the Perl program is
running. For example, exiting 69 (EX_UNAVAILABLE)
from a sendmail incoming-mail filter will cause
the mailer to return the item undelivered, but
that's not true everywhere.
Don'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().
The exit() function does not always exit
immediately. It calls any defined END routines
first, but these END routines may not themselves
abort the exit. Likewise any object destructors
that need to be called are called before the real
exit. If this is a problem, you can call
POSIX:_exit($status) to avoid END and destructor
processing. See the perlsub manpage for details.
exp EXPR
29/Apr/1999 perl 5.005, patch 03 29
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 constant definitions.
Argument processing and value return works just
like ioctl() below. For example:
use Fcntl;
fcntl($filehandle, F_GETFL, $packed_return_buffer)
or die "can't fcntl F_GETFL: $!";
You don't have to check for defined() on the
return from fnctl(). Like ioctl(), it maps a 0
return from the system call into "0 but true" in
Perl. This string is true in boolean context and
0 in numeric context. It is also exempt from the
normal -w warnings on improper numeric
conversions.
Note that fcntl() will produce a fatal error if
used on a machine that doesn't implement fcntl(2).
See the Fcntl module or your fcntl(2) manpage to
learn what functions are available on your system.
fileno FILEHANDLE
Returns the file descriptor for a filehandle, or
undefined if the filehandle is not open. This is
mainly useful for constructing bitmaps for
select() and low-level POSIX tty-handling
operations. If FILEHANDLE is an expression, the
value is taken as an indirect filehandle,
generally its name.
You can use this to find out whether two handles
refer to the same underlying descriptor:
if (fileno(THIS) == fileno(THAT)) {
print "THIS and THAT are dups\n";
}
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
29/Apr/1999 perl 5.005, patch 03 30
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
entire files, not records.
Two potentially non-obvious but traditional flock
semantics are that it waits indefinitely until the
lock is granted, and that its locks merely
advisory. Such discretionary locks are more
flexible, but offer fewer guarantees. This means
that files locked with flock() may be modified by
programs that do not also use flock(). See the
perlport manpage, your port's specific
documentation, or your system-specific local
manpages for details. It's best to assume
traditional behavior if you're writing portable
programs. (But if you're not, you should as
always feel perfectly free to write for your own
system's idiosyncrasies (sometimes called
"features"). Slavish adherence to portability
concerns shouldn't get in the way of your getting
your job done.)
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 miscoordination, Perl
now flushes FILEHANDLE before locking or unlocking
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 if
not 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.
29/Apr/1999 perl 5.005, patch 03 31
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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();
On systems that support a real flock(), locks are
inherited across fork() calls, whereas those that
must resort to the more capricious fcntl()
function lose the locks, making it harder to write
servers.
See also the DB_File manpage for other flock()
examples.
fork Does a fork(2) system call to create a new process
running the same program at the same point. It
returns the child pid to the parent process, 0 to
the child process, or undef if the fork is
unsuccessful. File descriptors (and sometimes
locks on those descriptors) are shared, while
everything else is copied. On most systems
supporting fork(), great care has gone into making
it extremely efficient (for example, using copy-
on-write technology on data pages), making it the
dominant paradigm for multitasking over the last
few decades.
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. On some
systems, you can avoid this by setting $SIG{CHLD}
to "IGNORE". See also the perlipc manpage for
more examples of forking and reaping moribund
29/Apr/1999 perl 5.005, patch 03 32
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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, then the remote server (such as, say, a
CGI script or a backgrounded job launced from a
remote shell) won't think you're done. You should
reopen those to /dev/null if it's any issue.
format Declare a picture format for 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
29/Apr/1999 perl 5.005, patch 03 33
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
getc Returns the next character from the input file
attached to FILEHANDLE, or the undefined value at
end of file, or if there was an error. If
FILEHANDLE is omitted, reads from STDIN. This is
not particularly efficient. However, it cannot be
used by itself to fetch single characters without
waiting for the user to hit enter. 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 purporting 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 perlmodlib manpage.
getlogin
Implements the C library function of the same
name, which on most systems 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.
29/Apr/1999 perl 5.005, patch 03 34
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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
29/Apr/1999 perl 5.005, patch 03 35
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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. In list
context, the return values from the various get
routines are as follows:
($name,$passwd,$uid,$gid,
$quota,$comment,$gcos,$dir,$shell,$expire) = 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.)
In 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:
29/Apr/1999 perl 5.005, patch 03 36
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
$uid = getpwnam($name);
$name = getpwuid($num);
$name = getpwent();
$gid = getgrnam($name);
$name = getgrgid($num;
$name = getgrent();
#etc.
In getpw*() the fields $quota, $comment, and
$expire are special cases in the sense that in
many systems they are unsupported. If the $quota
is unsupported, it is an empty scalar. If it is
supported, it usually encodes the disk quota. If
the $comment field is unsupported, it is an empty
scalar. If it is supported it usually encodes
some administrative comment about the user. In
some systems the $quota field may be $change or
$age, fields that have to do with password aging.
In some systems the $comment field may be $class.
The $expire field, if present, encodes the
expiration period of the account or the password.
For the availability and the exact meaning of
these fields in your system, please consult your
getpwnam(3) documentation and your pwd.h file.
You can also find out from within Perl what your
$quota and $comment fields mean and whether you
have the $expire field by using the Config module
and the values d_pwquota, d_pwage, d_pwchange,
d_pwcomment, and d_pwexpire. Shadow password
files are only supported if your vendor has
implemented them in the intuitive fashion that
calling the regular C library routines gets the
shadow versions if you're running under privilege.
Those that incorrectly implement a separate
library call are not supported.
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]);
The Socket library makes this slightly easier:
29/Apr/1999 perl 5.005, patch 03 37
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
use Socket;
$iaddr = inet_aton("127.1"); # or whatever address
$name = gethostbyaddr($iaddr, AF_INET);
# or going the other way
$straddr = inet_ntoa($iaddr");
If you get tired of remembering which element of
the return list contains which return value, by-
name interfaces are also provided in modules:
File::stat, Net::hostent, Net::netent,
Net::protoent, Net::servent, Time::gmtime,
Time::localtime, and User::grent. These override
the normal built-in, replacing them with versions
that return objects with the appropriate names for
each field. For example:
use File::stat;
use User::pwent;
$is_his = (stat($filename)->uid == pwent($whoever)->uid);
Even though it looks like they're the same method
calls (uid), they aren't, because a File::stat
object is different from a User::pwent object.
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 undef if
there is an error.
glob EXPR
glob Returns the value of EXPR with filename expansions
such as the standard Unix shell /bin/csh 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:
29/Apr/1999 perl 5.005, patch 03 38
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
# 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, that is, $year is 123
in year 2023, not simply the last two digits of
the year. If you assume it is, then you create
non-Y2K-compliant programs--and you wouldn't want
to do that, would you?
If EXPR is omitted, does gmtime(time()).
In 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.
This scalar value is not locale dependent (see the
perllocale manpage), but is instead a Perl
builtin. Also see the Time::Local module, and the
strftime(3) and mktime(3) functions available via
the POSIX module. To get somewhat similar but
locale dependent date strings, set up your locale
environment variables appropriately (please see
the perllocale manpage) and try for example:
use POSIX qw(strftime);
$now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
Note that the %a and %b escapes, which represent
the short forms of the day of the week and the
month of the year, may not necessarily be three
characters wide in all locales.
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
29/Apr/1999 perl 5.005, patch 03 39
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 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 as a for loop's index
variable aliases the list elements. That is,
modifying an element of a list returned by grep
29/Apr/1999 perl 5.005, patch 03 40
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
(for example, in a foreach, map() or another
grep()) actually modifies the element in the
original list. This is usually something to be
avoided when writing clear code.
See also the map entry elsewhere in this
documentfor an array composed of the results of
the BLOCK or EXPR.
hex EXPR
hex Interprets EXPR as a hex string and returns the
corresponding value. (To convert strings that
might start with either 0, 0x, or 0b, 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 just
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 documentthe
perlmod manpage, and the Exporter manpage.
index STR,SUBSTR,POSITION
index STR,SUBSTR
The index function searches for one string within
another, but without the wildcard-like behavior of
a full regular-expression pattern match. It
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 $_. You should not use this
function for rounding: one because it truncates
towards 0, and two because machine representations
of floating point numbers can sometimes produce
counterintuitive results. For example,
int(-6.725/0.025) produces -268 rather than the
correct -269; that's because it's really more like
-268.99999999999994315658 instead. Usually, the
29/Apr/1999 perl 5.005, patch 03 41
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
sprintf(), printf(), or the POSIX::floor and
POSIX::ceil functions will serve you better than
will int().
ioctl FILEHANDLE,FUNCTION,SCALAR
Implements the ioctl(2) function. You'll probably
first have to say
require "ioctl.ph"; # probably in /usr/local/lib/perl/ioctl.ph
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 that 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:
29/Apr/1999 perl 5.005, patch 03 42
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
$retval = ioctl(...) || -1;
printf "System returned %d\n", $retval;
The special string "0 but true" is exempt from -w
complaints about improper numeric conversions.
join EXPR,LIST
Joins the separate strings of LIST into a single
string with fields separated by the value of EXPR,
and returns that new string. Example:
$rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
See the split entry elsewhere in this document.
keys HASH
Returns a list 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. The actual random order
is subject to change in future versions of perl,
but it is guaranteed to be the same order as
either the 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 a hash 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
29/Apr/1999 perl 5.005, patch 03 43
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
keys %hash = 200;
then %hash will have at least 200 buckets
allocated for it--256 of them, in fact, since it
rounds up to the next power of two. 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).
See also each(), values() and sort().
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
#...
}
last cannot be used to exit a block which returns
a value such as eval {}, sub {} or do {}, and
should not be used to exit a grep() or map()
operation.
See also the continue entry elsewhere in this
documentfor an illustration of how last, next, and
redo work.
29/Apr/1999 perl 5.005, patch 03 44
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 $_.
Note that this cannot be used on an entire array
or hash to find out how many elements these have.
For that, use scalar @array and scalar keys %hash
respectively.
link OLDFILE,NEWFILE
Creates a new filename linked to the old filename.
Returns TRUE for success, FALSE otherwise.
listen SOCKET,QUEUESIZE
Does the same thing that the listen system call
does. Returns TRUE if it succeeded, FALSE
otherwise. See the example in the section on
Sockets: Client/Server Communication in the
perlipc manpage.
local EXPR
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.
A local modifies the listed variables to be local
to the enclosing block, file, or eval. 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.
29/Apr/1999 perl 5.005, patch 03 45
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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, and not simply the last two digits
of the year. If you assume it is, then you create
non-Y2K-compliant programs--and you wouldn't want
to do that, would you?
If EXPR is omitted, uses the current time
(localtime(time)).
In scalar context, returns the ctime(3) value:
$now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
This scalar value is not locale dependent, see the
perllocale manpage, but instead a Perl builtin.
Also see the Time::Local module, and the
strftime(3) and mktime(3) function available via
the POSIX module. To get somewhat similar but
locale dependent date strings, set up your locale
environment variables appropriately (please see
the perllocale manpage) and try for example:
use POSIX qw(strftime);
$now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
Note that the %a and %b, the short forms of the
day of the week and the month of the year, may not
necessarily be three characters wide.
log EXPR
log Returns the natural logarithm (base e) of EXPR.
If EXPR is omitted, returns log of $_. To get the
log of another base, use basic algebra: The base-N
log of a number is is equal to the natural log of
that number divided by the natural log of N. For
example:
29/Apr/1999 perl 5.005, patch 03 46
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
sub log10 {
my $n = shift;
return log($n)/log(10);
}
See also the exp entry elsewhere in this
documentfor the inverse operation.
lstat FILEHANDLE
lstat EXPR
lstat Does the same thing as the stat() function
(including setting the special _ filehandle) 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.
In scalar context, returns the total number of
elements so generated.
@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($_)} = $_;
}
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
29/Apr/1999 perl 5.005, patch 03 47
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
can cause bizarre results if the LIST is not a
named array. Using a regular foreach loop for
this purpose would be clearer in most cases. See
also the grep entry elsewhere in this documentfor
an array composed of those items of the original
list for which the BLOCK or EXPR evaluates to
true.
mkdir FILENAME,MODE
Creates the directory specified by FILENAME, with
permissions specified by MODE (as modified by
umask). If it succeeds it returns TRUE, otherwise
it returns FALSE and sets $! (errno).
In general, it is better to create directories
with permissive MODEs, and let the user modify
that with their umask, than it is to supply a
restrictive MODE and give the user no way to be
more permissive. The exceptions to this rule are
when the file or directory should be kept private
(mail files, for instance). The perlfunc(1) entry
on umask discusses the choice of MODE in more
detail.
msgctl ID,CMD,ARG
Calls the System V IPC function msgctl(2). You'll
probably have to say
use IPC::SysV;
first to get the correct constant definitions. 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. See also IPC::SysV and
IPC::Semaphore::Msg documentation.
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. See also IPC::SysV
and IPC::SysV::Msg documentation.
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.
See also IPC::SysV and IPC::SysV::Msg
documentation.
29/Apr/1999 perl 5.005, patch 03 48
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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. See also IPC::SysV and IPC::SysV::Msg
documentation.
my EXPR A my() declares the listed variables to be local
(lexically) to the enclosing block, file, or
eval(). 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.
next cannot be used to exit a block which returns
a value such as eval {}, sub {} or do {}, and
should not be used to exit a grep() or map()
operation.
See also the continue entry elsewhere in this
documentfor an illustration of how last, next, and
redo work.
no Module LIST
See the the use entry elsewhere in this
documentfunction, 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. If
EXPR starts off with 0b, it is interpreted as a
binary string.) The following will handle
decimal, binary, octal, and hex in the standard
29/Apr/1999 perl 5.005, patch 03 49
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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.) See the
perlopentut manpage for a kinder, gentler
explanation of opening files.
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, being created if necessary. If the
filename begins with '>>', the file is opened for
appending, again being created if necessary. 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. You can't usually use
either read-write mode for updating textfiles,
since they have variable length records. See the
-i switch in the perlrun manpage for a better
approach. The file is created with permissions of
0666 modified by the process' umask value.
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 as a command which pipes
output to us. See the section on Using open() for
IPC in the perlipc manpage for more examples of
29/Apr/1999 perl 5.005, patch 03 50
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
this. (You are not allowed to 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 documentfor 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, MacOS, and
Plan9, which delimit lines with a single
character, and which encode that character in C as
"\n", do not need binmode(). The rest need it.
When opening a file, it's usually a bad idea to
continue normal execution if the request failed,
so open() is frequently used in connection with
die(). Even if die() won't do what you want (say,
in a CGI script, where you want to make a nicely
formatted error message (but there are modules
that can help with that problem)) you should
always check the return value from opening a file.
The infrequent exception is when working with an
unopened filehandle is actually what you want to
do.
Examples:
$ARTICLE = 100;
open ARTICLE or die "Can't find article $ARTICLE: $!\n";
while (<ARTICLE>) {...
open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
# if the open fails, output is discarded
open(DBASE, '+<dbase.mine') # open for update
or die "Can't open 'dbase.mine' for update: $!";
open(ARTICLE, "caesar <$article |") # decrypt article
or die "Can't start caesar: $!";
open(EXTRACT, "|sort >/tmp/Tmp$$") # $$ is our process id
or die "Can't start sort: $!";
29/Apr/1999 perl 5.005, patch 03 51
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
# process argument list of files along with any includes
foreach $file (@ARGV) {
process($file, 'fh00');
}
sub process {
my($filename, $input) = @_;
$input++; # this is a string increment
unless (open($input, $filename)) {
print STDERR "Can't open $filename: $!\n";
return;
}
local $_;
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)
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(OLDOUT, ">&STDOUT");
open(OLDERR, ">&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, ">&OLDOUT");
open(STDERR, ">&OLDERR");
29/Apr/1999 perl 5.005, patch 03 52
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 that may do a fork, any
unflushed buffers remain unflushed in both
processes, which means you may need to set $| to
avoid duplicate output. On systems that support a
close-on-exec flag on files, the flag will be set
for the newly opened file descriptor as determined
by the value of $^F. See the section on $^F in
the perlvar manpage.
Closing any piped filehandle causes the parent
process to wait for the child to finish, and
returns the status value in $?.
The filename passed to open will have leading and
trailing whitespace deleted, and the normal
redirection characters honored. This property,
known as "magic open", can often be used to good
29/Apr/1999 perl 5.005, patch 03 53
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
effect. A user could specify a filename of "rsh
cat file |", or you could change certain filenames
as needed:
$filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
open(FH, $filename) or die "Can't open $filename: $!";
However, to open a file with arbitrary weird
characters in it, it's necessary to protect any
leading and trailing whitespace:
$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, which involves no such magic.
This is another way to protect your filenames from
interpretation. For example:
use IO::Handle;
sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL)
or die "sysopen $path: $!";
$oldfh = select(HANDLE); $| = 1; select($oldfh);
print HANDLE "stuff $$\n");
seek(HANDLE, 0, 0);
print "File contains: ", <HANDLE>;
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 that 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.
}
See the seek entry elsewhere in this documentfor
some details about mixing reading and writing.
opendir DIRHANDLE,EXPR
Opens a directory named EXPR for processing by
29/Apr/1999 perl 5.005, patch 03 54
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 A string with arbitrary binary data, will be null padded.
A An ascii string, will be space padded.
Z A null terminated (asciz) 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.)
29/Apr/1999 perl 5.005, patch 03 55
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
q A signed quad (64-bit) value.
Q An unsigned quad value.
(Available only if your system supports 64-bit integer values
_and_ if Perl has been compiled to support those.
Causes a fatal error otherwise.)
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.
The following rules apply:
- Each letter may optionally be followed by
a number giving a repeat count. With all
types except "a", "A", "Z", "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", "A", and "Z" 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, "Z" strips
everything after the first null, and "a"
returns data verbatim.
- 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" type packs a pointer to a null-
terminated string. You are responsible
for ensuring the string is not a temporary
value (which can potentially get
deallocated before you get around to using
the packed result). The "P" type packs a
pointer to a structure of the size
29/Apr/1999 perl 5.005, patch 03 56
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
indicated by the length. A NULL pointer is
created if the corresponding value for "p"
or "P" is undef.
- The integer formats "s", "S", "i", "I",
"l", and "L" are inherently non-portable
between processors and operating systems
because they obey the native byteorder and
endianness. For example a 4-byte integer
0x87654321 (2271560481 decimal) be ordered
natively (arranged in and handled by the
CPU registers) into bytes as
0x12 0x34 0x56 0x78 # little-endian
0x78 0x56 0x34 0x12 # big-endian
Basically, the Intel, Alpha, and VAX CPUs
and little-endian, while everybody else,
for example Motorola m68k/88k, PPC, Sparc,
HP PA, Power, and Cray are big-endian.
MIPS can be either: Digital used it in
little-endian mode, SGI uses it in big-
endian mode.
The names `big-endian' and `little-endian'
are joking references to the classic
"Gulliver's Travels" (via the paper "On
Holy Wars and a Plea for Peace" by Danny
Cohen, USC/ISI IEN 137, April 1, 1980) and
the egg-eating habits of the lilliputs.
Some systems may even have weird byte
orders such as
0x56 0x78 0x12 0x34
0x34 0x12 0x78 0x56
You can see your system's preference with
print join(" ", map { sprintf "%#02x", $_ }
unpack("C*",pack("L",0x12345678))), "\n";
The byteorder on the platform where Perl
was built is also available via the Config
manpage:
use Config;
print $Config{byteorder}, "\n";
Byteorders '1234' and '12345678' are
little-endian, '4321' and '87654321' are
big-endian.
If you want portable packed integers use
29/Apr/1999 perl 5.005, patch 03 57
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
the formats "n", "N", "v", and "V", their
byte endianness and size is known.
- 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)
$utmp_template = "Z8 Z8 Z16 L";
$utmp = pack($utmp_template, @utmp1);
# a struct utmp (BSDish)
29/Apr/1999 perl 5.005, patch 03 58
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
@utmp2 = unpack($utmp_template, $utmp);
# "@utmp1" eq "@utmp2"
sub bintodec {
unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
}
The same template may generally also be
used in unpack().
package
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, file, or eval (the
same as the my() 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, which are
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 merely
influences 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 (as well as to
$main'sail, still seen in older code).
If NAMESPACE is omitted, then there is no current
package, and all identifiers must be fully
qualified or lexicals. This is stricter than use
strict, since it also extends to function names.
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.
29/Apr/1999 perl 5.005, patch 03 59
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
See the IPC::Open2 manpage, the IPC::Open3
manpage, and the section on Bidirectional
Communication in the perlipc manpage for examples
of such things.
On systems that support a close-on-exec flag on
files, the flag will be set for the newly opened
file descriptors as determined by the value of
$^F. See the section on $^F in the perlvar
manpage.
pop ARRAY
pop Pops and returns the last value of the array,
shortening the array by one element. 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
the currently selected output channel. To set the
default output channel to something other than
STDOUT use the select operation. Note that,
29/Apr/1999 perl 5.005, patch 03 60
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
because print takes a LIST, anything in the LIST
is evaluated in list context, and any subroutine
that you call will have one or more of its
expressions evaluated in 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), except that $\ (the output record
separator) is not appended. 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.
If FUNCTION is a string starting with CORE::, the
rest is taken as a name for Perl builtin. If the
builtin is not overridable (such as qw//) or its
arguments cannot be expressed by a prototype (such
as system()) returns undef because the builtin
does not really behave like a Perl function.
Otherwise, the string describing the equivalent
prototype is returned.
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
29/Apr/1999 perl 5.005, patch 03 61
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
for $value (LIST) {
$ARRAY[++$#ARRAY] = $value;
}
but is more efficient. Returns the new number of
elements in the array.
q/STRING/
qq/STRING/
qr/STRING/
qx/STRING/
qw/STRING/
Generalized quotes. See the section on Regexp
Quote-Like Operators in 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, 0 at
end of file, or undef if there was an error.
SCALAR will be grown or shrunk to the length
29/Apr/1999 perl 5.005, patch 03 62
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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(3) call. To
get a true read(2) system call, see sysread().
readdir DIRHANDLE
Returns the next directory entry for a directory
opened by opendir(). If used in list context,
returns all the rest of the entries in the
directory. If there are no more entries, returns
an undefined value in scalar context or a null
list in 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;
readline EXPR
Reads from the filehandle whose typeglob is
contained in EXPR. In scalar context, each call
reads and returns the next line, until end-of-file
is reached, whereupon the subsequent call returns
undef. In list context, reads until end-of-file
is reached and returns a list of lines. Note that
the notion of "line" used here is however you may
have defined it with $/ or
$INPUT_RECORD_SEPARATOR). See the section on $/
in the perlvar manpage.
When $/ is set to undef, when readline() is in
scalar context (i.e. file slurp mode), and when an
empty file is read, it returns '' the first time,
followed by undef subsequently.
This is the internal function implementing the
<EXPR> operator, but you can use it directly. The
<EXPR> operator is discussed in more detail in the
section on I/O Operators in the perlop manpage.
$line = <STDIN>;
$line = readline(*STDIN); # same thing
readlink EXPR
29/Apr/1999 perl 5.005, patch 03 63
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 $_.
readpipe EXPR
EXPR is executed as a system command. The
collected standard output of the command is
returned. In scalar context, it comes back as a
single (potentially multi-line) string. In list
context, returns a list of lines (however you've
defined lines with $/ or $INPUT_RECORD_SEPARATOR).
This is the internal function implementing the
qx/EXPR/ operator, but you can use it directly.
The qx/EXPR/ operator is discussed in more detail
in the section on I/O Operators in the perlop
manpage.
recv SOCKET,SCALAR,LENGTH,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 return 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:
29/Apr/1999 perl 5.005, patch 03 64
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
# 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;
}
redo cannot be used to retry a block which returns
a value such as eval {}, sub {} or do {}, and
should not be used to exit a grep() or map()
operation.
See also the continue entry elsewhere in this
documentfor an illustration of how last, next, and
redo work.
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.
29/Apr/1999 perl 5.005, patch 03 65
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
if (ref($r) eq "HASH") {
print "r is a reference to a hash.\n";
}
unless (ref($r)) {
print "r is not a reference at all.\n";
}
if (UNIVERSAL::isa($r, "HASH")) { # for subclassing
print "r is a reference to something that isa hash.\n";
}
See also the perlref manpage.
rename OLDNAME,NEWNAME
Changes the name of a file. Returns 1 for
success, 0 otherwise. Behavior of this function
varies wildly depending on your system
implementation. For example, it will usually not
work across file system boundaries, even though
the system mv command sometimes compensates for
this. Other restrictions include whether it works
on directories, open files, or pre-existing files.
Check the perlport manpage and either the
rename(2) manpage or equivalent system
documentation for details.
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:
29/Apr/1999 perl 5.005, patch 03 66
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
sub require {
my($filename) = @_;
return 1 if $INC{$filename};
my($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;
return $result;
}
Note that the file will not be included twice
under the same specified name. The file must
return TRUE as the last statement to indicate
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.
In other words, if you try this:
require Foo::Bar; # a splendid bareword
The require function will actually look for the
"Foo/Bar.pm" file in the directories specified in
the @INC array.
But if you try this:
$class = 'Foo::Bar';
require $class; # $class is not a bareword
#or
require "Foo::Bar"; # not a bareword because of the ""
The require function will look for the "Foo::Bar"
file in the @INC array and will complain about not
finding "Foo::Bar" there. In this case you can do:
29/Apr/1999 perl 5.005, patch 03 67
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
eval "require $class";
For a yet-more-powerful import facility, see the
use entry elsewhere in this document and 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 ?one-time? searches
Resetting "A-Z" is not recommended because you'll
wipe out your @ARGV and @INC arrays and your %ENV
hash. 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 given in EXPR. Evaluation of EXPR may
be in 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 list context, the undefined value in
scalar context, and (of course) nothing at all in
a void context.
(Note that in the absence of a explicit return, a
subroutine, eval, or do FILE will automatically
return the value of the last expression
evaluated.)
reverse LIST
In list context, returns a list value consisting
of the elements of LIST in the opposite order. In
scalar context, concatenates the elements of LIST
and returns a string value with all characters in
29/Apr/1999 perl 5.005, patch 03 68
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
the opposite order.
print reverse <>; # line tac, last line first
undef $/; # for efficiency of <>
print scalar reverse <>; # character 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, such as from a DBM file.
%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
that directory is empty. If it succeeds it
returns TRUE, otherwise it returns FALSE and sets
$! (errno). If FILENAME is omitted, uses $_.
s/// The substitution operator. See the perlop
manpage.
scalar EXPR
Forces EXPR to be interpreted in 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 list context
because in practice, this is never needed. If you
really wanted to do so, however, you could use the
construction @{[ (some expression) ]}, but usually
a simple (some expression) suffices.
Since scalar is a unary operator, if you
29/Apr/1999 perl 5.005, patch 03 69
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
accidentally use for EXPR a parenthesized list,
this behaves as a scalar comma expression,
evaluating all but the last element in void
context and returning the final element evaluated
in scalar context. This is seldom what you want.
The following single statement:
print uc(scalar(&foo,$bar)),$baz;
is the moral equivalent of these two:
&foo;
print(uc($bar),$baz);
See the perlop manpage for more details on unary
operators and the comma operator.
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.
Due to the rules and rigors of ANSI C, 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.
29/Apr/1999 perl 5.005, patch 03 70
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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
29/Apr/1999 perl 5.005, patch 03 71
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 {
my(@fhlist) = split(' ',$_[0]);
my($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 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: One should not attempt to mix buffered
I/O (like read() or <FH>) with select(), except as
permitted by POSIX, and even then only on POSIX
systems. You have to use sysread() instead.
semctl ID,SEMNUM,CMD,ARG
Calls the System V IPC function semctl(). You'll
probably have to say
29/Apr/1999 perl 5.005, patch 03 72
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
use IPC::SysV;
first to get the correct constant definitions. 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. See also IPC::SysV and IPC::Semaphore
documentation.
semget KEY,NSEMS,FLAGS
Calls the System V IPC function semget. Returns
the semaphore id, or the undefined value if there
is an error. See also IPC::SysV and
IPC::SysV::Semaphore documentation.
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. See
also IPC::SysV and IPC::SysV::Semaphore
documentation.
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. The C
system call sendmsg(2) is currently unimplemented.
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
29/Apr/1999 perl 5.005, patch 03 73
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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. See
also POSIX::setsid().
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 @_ array within the lexical
scope of subroutines and formats, and the @ARGV
array at file scopes or within the lexical scopes
established by the eval '', BEGIN {}, END {}, and
INIT {} constructs. 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. You'll
probably have to say
use IPC::SysV;
first to get the correct constant definitions. 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. See also IPC::SysV documentation.
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. See also IPC::SysV
documentation.
shmread ID,VAR,POS,SIZE
29/Apr/1999 perl 5.005, patch 03 74
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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
that 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. See also IPC::SysV
documentation and the IPC::Shareable module from
CPAN.
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.
shutdown(SOCKET, 0); # I/we have stopped reading data
shutdown(SOCKET, 1); # I/we have stopped writing data
shutdown(SOCKET, 2); # I/we have stopped using this socket
This is useful with sockets when you want to tell
the other side you're done writing but not done
reading, or vice versa. It's also a more
insistent form of close because it also disables
the filedescriptor in any forked copies in other
processes.
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 if the
process receives a signal such as 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
29/Apr/1999 perl 5.005, patch 03 75
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
sleep the full amount. They may appear to sleep
longer than that, however, because your process
might not be scheduled right away in a busy
multitasking system.
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
documentabove.
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 examples 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.
Some systems defined pipe() in terms of
socketpair(), in which a call to pipe(Rdr, Wtr) is
essentially:
use Socket;
socketpair(Rdr, Wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC);
shutdown(Rdr, 1); # no more writing for reader
shutdown(Wtr, 0); # no more reading for writer
See the perlipc manpage for an example of
socketpair use.
sort SUBNAME LIST
sort BLOCK LIST
sort LIST
Sorts the LIST and returns the sorted list value.
If SUBNAME or BLOCK is omitted, sort()s 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
29/Apr/1999 perl 5.005, patch 03 76
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
are to be ordered. (The <=> and cmp operators are
extremely useful in such routines.) SUBNAME may
be a scalar variable name (unsubscripted), in
which case the value provides the name of (or a
reference to) the actual 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;
29/Apr/1999 perl 5.005, patch 03 77
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
# 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
29/Apr/1999 perl 5.005, patch 03 78
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
@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 results are not well-
defined.
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. In list context,
returns the elements removed from the array. In
scalar context, returns the last element removed,
or undef if no elements are removed. The array
grows or shrinks as necessary. If OFFSET is
negative then it start that far from the end of
the array. If LENGTH is omitted, removes
everything from OFFSET onward. If LENGTH is
negative, leave that many elements off the end of
the array. The following equivalences hold
(assuming $[ == 0):
push(@a,$x,$y) splice(@a,@a,0,$x,$y)
pop(@a) splice(@a,-1)
shift(@a) splice(@a,0,1)
unshift(@a,$x,$y) splice(@a,0,0,$x,$y)
$a[$x] = $y splice(@a,$x,1,$y)
Example, assuming array lengths are passed before
arrays:
sub aeq { # compare two list values
my(@a) = splice(@_,0,shift);
my(@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
29/Apr/1999 perl 5.005, patch 03 79
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
split /PATTERN/,EXPR
split /PATTERN/
split Splits a string into an array of strings, and
returns it. By default, empty leading fields are
preserved, and empty trailing ones are deleted.
If not in list context, returns the number of
fields found and splits into the @_ array. (In
list context, you can force the split into @_ by
using ?? as the pattern delimiters, but it still
returns the list value.) The use of implicit
split to @_ is deprecated, however, because it
clobbers your subroutine arguments.
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 positive, splits into no
more than that many fields (though it may split
into fewer). If LIMIT is unspecified or zero,
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.
29/Apr/1999 perl 5.005, patch 03 80
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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*?):\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 its own sprintf() formatting -- it
29/Apr/1999 perl 5.005, patch 03 81
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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:
29/Apr/1999 perl 5.005, patch 03 82
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 non-zero octal with "0", non-zero 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 $_. Only works on
non-negative operands, unless you've loaded the
standard Math::Complex module.
use Math::Complex;
print sqrt(-2); # prints 1.4142135623731i
srand EXPR
srand Sets the random number seed for the rand()
operator. If EXPR is omitted, uses a semi-random
value supplied by the kernel (if it supports the
/dev/urandom device) or 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 time ^ ($$ + ($$ <<
15))), but that isn't necessary any more.
In fact, it's usually not necessary to call
29/Apr/1999 perl 5.005, patch 03 83
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 list 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
29/Apr/1999 perl 5.005, patch 03 84
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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.)
Because the mode contains both the file type and
its permissions, you should mask off the file type
portion and (s)printf using a "%o" if you want to
see the real permissions.
$mode = (stat($filename))[2];
printf "Permissions are %04o\n", $mode & 07777;
In scalar context, stat() returns a boolean value
indicating success or failure, and, if successful,
sets the information associated with the special
filehandle _.
The File::stat module provides a convenient, by-
name access mechanism:
use File::stat;
$sb = stat($filename);
printf "File is %s, size is %s, perm %04o, mtime %s\n",
$filename, $sb->size, $sb->mode & 07777,
scalar localtime $sb->mtime;
29/Apr/1999 perl 5.005, patch 03 85
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 that 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
29/Apr/1999 perl 5.005, patch 03 86
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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,REPLACEMENT
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 (or more precisely, less than $[), 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.
If you specify a substring that is partly outside
the string, the part within the string is
returned. If the substring is totally outside
the string a warning is produced.
You can use the substr() function as an lvalue, in
which case EXPR must itself 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
29/Apr/1999 perl 5.005, patch 03 87
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
keep the string the same length you may need to
pad or chop your value using sprintf().
An alternative to using substr() as an lvalue is
to specify the replacement string as the 4th
argument. This allows you to replace parts of the
EXPR and return what was there before in one
operation, just as you can with splice().
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("",""); 1 };
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. You can't
use a string literal (or other read-only string)
as an argument to syscall() because Perl has to
assume that any string pointer might be written
through. 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. This emulates
the syswrite() function (or vice versa):
require 'syscall.ph'; # may need to run h2ph
$s = "hi there\n";
syscall(&SYS_write, fileno(STDOUT), $s, length $s);
Note that Perl supports passing of up to only 14
arguments to your system call, which in practice
should usually suffice.
Syscall returns whatever value returned by the
system call it calls. If the system call fails,
syscall() returns -1 and sets $! (errno). Note
that some system calls can legitimately return -1.
The proper way to handle such calls is to assign
$!=0; before the call and check the value of $! if
syscall returns -1.
29/Apr/1999 perl 5.005, patch 03 88
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
There's a problem with syscall(&SYS_pipe): it
returns the file number of the read end of the
pipe it creates. There is no way to retrieve the
file number of the other end. You can avoid this
problem by using pipe() instead.
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. For historical
reasons, some values work on almost every system
supported by perl: zero means read-only, one means
write-only, and two means read/write. We know
that these values do not work under OS/390 &
VM/ESA Unix and on the Macintosh; you probably
don't want to use them in new code.
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 you omit the PERMS argument to
sysopen(), Perl uses the octal value 0666. These
permission values need to be in octal, and are
modified by your process's current umask.
You should seldom if ever use 0644 as argument to
sysopen(), because that takes away the user's
option to have a more permissive umask. Better to
omit it. See the perlfunc(1) entry on umask for
more on this.
See the perlopentut manpage for a kinder, gentler
explanation of opening files.
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(), tell(), or eof() can cause
confusion because stdio usually buffers data.
29/Apr/1999 perl 5.005, patch 03 89
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
Returns the number of bytes actually read, 0 at
end of file, 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.
There is no syseof() function, which is ok, since
eof() doesn't work very well on device files (like
ttys) anyway. Use sysread() and check for a
return value for 0 to decide whether you're done.
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(), tell(), or eof() 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
system PROGRAM 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. If there is more than one
argument in LIST, or if LIST is an array with more
than one value, starts the program given by the
first element of the list with arguments given by
the rest of the list. If there is only one scalar
argument, the argument is checked for shell
29/Apr/1999 perl 5.005, patch 03 90
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
metacharacters, and if there are any, the entire
argument is passed to the system's command shell
for parsing (this is /bin/sh -c on Unix platforms,
but varies on other platforms). If there are no
shell metacharacters in the argument, it is split
into words and passed directly to execvp(), which
is more efficient.
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.
Like exec(), system() allows you to lie to a
program about its name if you use the "system
PROGRAM LIST" syntax. Again, see the exec entry
elsewhere in this document.
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: $?"
You can check all the failure possibilities by
inspecting $? like this:
$exit_value = $? >> 8;
$signal_num = $? & 127;
$dumped_core = $? & 128;
When the arguments get executed via the system
shell, results and return codes will be subject to
its quirks and capabilities. See the section on
`STRING` in the perlop manpage and the exec entry
elsewhere in this documentfor details.
syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
syswrite FILEHANDLE,SCALAR,LENGTH
syswrite FILEHANDLE,SCALAR
Attempts to write LENGTH bytes of data from
variable SCALAR to the specified FILEHANDLE, using
the system call write(2). If LENGTH is not
specified, writes whole SCALAR. It bypasses stdio,
so mixing this with reads (other than sysread()),
print(), write(), seek(), tell(), or eof() may
29/Apr/1999 perl 5.005, patch 03 91
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
cause confusion because stdio usually buffers
data. Returns the number of bytes actually
written, or undef if there was an error. If the
LENGTH is greater than the available data in the
SCALAR after the OFFSET, only as much data as is
available will be written.
An OFFSET may be specified to write the data from
some part of the string other than the beginning.
A negative OFFSET specifies writing that many
bytes counting backwards from the end of the
string. In the case the SCALAR is empty you can
use OFFSET but only zero offset.
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.
There is no systell() function. Use sysseek(FH,
0, 1) for that.
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, TIEHANDLE,
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 lists when used on large objects,
like DBM files. You may prefer to use the each()
function to iterate over such. Example:
29/Apr/1999 perl 5.005, patch 03 92
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
# 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
FETCH this, key
STORE this, key, value
DELETE this, key
CLEAR this
EXISTS this, key
FIRSTKEY this
NEXTKEY this, lastkey
DESTROY this
A class implementing an ordinary array should have
the following methods:
TIEARRAY classname, LIST
FETCH this, key
STORE this, key, value
FETCHSIZE this
STORESIZE this, count
CLEAR this
PUSH this, LIST
POP this
SHIFT this
UNSHIFT this, LIST
SPLICE this, offset, length, LIST
EXTEND this, count
DESTROY this
A class implementing a file handle should have the
following methods:
TIEHANDLE classname, LIST
READ this, scalar, length, offset
READLINE this
GETC this
WRITE this, scalar, length, offset
PRINT this, LIST
PRINTF this, format, LIST
CLOSE this
DESTROY this
A class implementing a scalar should have the
following methods:
29/Apr/1999 perl 5.005, patch 03 93
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
TIESCALAR classname, LIST
FETCH this,
STORE this, value
DESTROY this
Not all methods indicated above need be
implemented. See the perltie manpage, the
Tie::Hash manpage, the Tie::Array manpage, the
Tie::Scalar manpage, and the Tie::Handle manpage.
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.
For further details see the perltie manpage, the
section on tied VARIABLE.
tied VARIABLE
Returns a reference to the object underlying
VARIABLE (the same value that was originally
returned by the tie() call that 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 list giving the user and
system times, in seconds, for this process and the
children of this process.
($user,$system,$cuser,$csystem) = times;
tr/// The transliteration 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. Returns TRUE if successful, the undefined
value otherwise.
uc EXPR
29/Apr/1999 perl 5.005, patch 03 94
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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. (It does not attempt to do
titlecase mapping on initial letters. See
ucfirst() for that.)
If EXPR is omitted, uses $_.
ucfirst EXPR
ucfirst Returns the value of EXPR with the first character
in uppercase. 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.
The Unix permission rwxr-x--- is represented as
three sets of three bits, or three octal digits:
0750 (the leading 0 indicates octal and isn't one
of the digits). The umask value is such a number
representing disabled permissions bits. The
permission (or "mode") values you pass mkdir or
sysopen are modified by your umask, so even if you
tell sysopen to create a file with permissions
0777, if your umask is 0022 then the file will
actually be created with permissions 0755. If
your umask were 0027 (group can't write; others
can't read, write, or execute), then passing
sysopen() 0666 would create a file with mode 0640
(0666 &~ 027 is 0640).
Here's some advice: supply a creation mode of 0666
for regular files (in sysopen()) and one of 0777
for directories (in mkdir()) and executable files.
This gives users the freedom of choice: if they
want protected files, they might choose process
umasks of 022, 027, or even the particularly
antisocial mask of 077. Programs should rarely if
ever make policy decisions better left to the
user. The exception to this is when writing files
that should be kept private: mail files, web
browser cookies, .rhosts files, and so on.
If umask(2) is not implemented on your system and
29/Apr/1999 perl 5.005, patch 03 95
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
you are trying to restrict access for yourself
(i.e., (EXPR & 0700) > 0), produces a fatal error
at run time. If umask(2) is not implemented and
you are not trying to restrict access for
yourself, returns undef.
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 documentif
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 array
(using "@"), a hash (using "%"), a subroutine
(using "&"), or a typeglob (using "<*>"). (Saying
undef $hash{$key} will probably not do what you
expect on most predefined variables or DBM list
values, so don't do that; see the delete manpage.)
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;
undef *xyz; # destroys $xyz, @xyz, %xyz, &xyz, etc.
return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
select undef, undef, undef, 0.25;
($a, $b, undef, $c) = &foo; # Ignore third value returned
Note that this is a unary operator, not a list
operator.
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.
29/Apr/1999 perl 5.005, patch 03 96
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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
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 {
my($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("%32C*", $_);
}
$checksum %= 65535;
The following efficiently counts the number of set
bits in a bit vector:
$setbits = unpack("%32b*", $selectmask);
See the pack entry elsewhere in this documentfor
more examples.
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
29/Apr/1999 perl 5.005, patch 03 97
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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 that 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 }
29/Apr/1999 perl 5.005, patch 03 98
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
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);
Some of these these pseudo-modules import
semantics into the current block scope (like
strict or integer, 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. This code has the same effect as
the "touch" command if the files already exist:
#!/usr/bin/perl
$now = time;
utime $now, $now, @ARGV;
29/Apr/1999 perl 5.005, patch 03 99
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
values HASH
Returns a list consisting of all the values of the
named hash. (In a scalar context, returns the
number of values.) The values are returned in an
apparently random order. The actual random order
is subject to change in future versions of perl,
but it is guaranteed to be the same order as
either the keys() or each() function would produce
on the same (unmodified) hash.
Note that you cannot modify the values of a hash
this way, because the returned list is just a
copy. You need to use a hash slice for that,
since it's lvaluable in a way that values() is
not.
for (values %hash) { s/foo/bar/g } # FAILS!
for (@hash{keys %hash}) { s/foo/bar/g } # ok
As a side effect, calling values() resets the
HASH's internal 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. See the section on Bitwise
String Operators in the perlop manpage.
The following code will build up an ASCII string
saying 'PerlPerlPerl'. The comments show the
string after each step. Note that this code works
in the same way on big-endian or little-endian
machines.
29/Apr/1999 perl 5.005, patch 03 100
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
my $foo = '';
vec($foo, 0, 32) = 0x5065726C; # 'Perl'
vec($foo, 2, 16) = 0x5065; # 'PerlPe'
vec($foo, 3, 16) = 0x726C; # 'PerlPerl'
vec($foo, 8, 8) = 0x50; # 'PerlPerlP'
vec($foo, 9, 8) = 0x65; # 'PerlPerlPe'
vec($foo, 20, 4) = 2; # 'PerlPerlPe' . "\x02"
vec($foo, 21, 4) = 7; # 'PerlPerlPer'
# 'r' is "\x72"
vec($foo, 45, 2) = 3; # 'PerlPerlPer' . "\x0c"
vec($foo, 93, 1) = 1; # 'PerlPerlPer' . "\x2c"
vec($foo, 94, 1) = 1; # 'PerlPerlPerl'
# 'l' is "\x6c"
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 Behaves like the wait(2) system call on your
system: it 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
rketurned in $?. Note that a return value of -1
could mean that child processes are being
automatically reaped, as described in the perlipc
manpage.
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. On some
systems, a value of 0 indicates that there are
processes still running. The status is returned
in $?. If you say
use POSIX ":sys_wait_h";
#...
do {
$kid = waitpid(-1,&WNOHANG);
} until $kid == -1;
then you can do a non-blocking wait for all
pending zombie processes. 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
29/Apr/1999 perl 5.005, patch 03 101
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
the Perl script yet.)
Note that on some systems, a return value of -1
could mean that child processes are being
automatically reaped. See the perlipc manpage for
details, and for other examples.
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.
If LIST is empty and $@ already contains a value
(typically from a previous eval) that value is
used after appending "\t...caught" to $@. This is
useful for staying almost, but not entirely
similar to die().
If $@ is empty then the string "Warning:
Something's wrong" is used.
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:
29/Apr/1999 perl 5.005, patch 03 102
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
# 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. See the Carp
module for other kinds of warnings using its
carp() and cluck() functions.
write FILEHANDLE
write EXPR
write Writes a formatted record (possibly multi-line) to
the specified FILEHANDLE, 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.
29/Apr/1999 perl 5.005, patch 03 103
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
y/// The transliteration operator. Same as tr///. See
the perlop manpage.
29/Apr/1999 perl 5.005, patch 03 104
PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1)
29/Apr/1999 perl 5.005, patch 03 105
Source: OpenBSD 2.6 man pages. Copyright: Portions are copyrighted by BERKELEY
SOFTWARE DESIGN, INC., The Regents of the University of California, Massachusetts
Institute of Technology, Free Software Foundation, FreeBSD Inc., and others. |
![[Detailed Topics]](/inbndsm.gif)
![[Overview Topics]](/outbndsm.gif)