This chapter describes the built-in Perl functions in
alphabetical order[1] for convenient reference. Each function description begins
with a brief summary of the syntax for that function. Parameter names
like THIS
represent placeholders for actual
expressions, and the text following the syntax summary will describe the
semantics of supplying (or omitting) the actual arguments.
You can think of functions as terms in an expression, along with literals and variables. Or you can think of them as prefix operators that process the arguments after them. We call them operators half the time anyway.
Some of these operators, er, functions take a
LIST
as an argument. Elements of the
LIST
should be separated by commas (or by
=>
, which is just a funny kind of comma). The
elements of the LIST
are evaluated in a list
context, so each element will return either a scalar or a list value,
depending on its sensitivity to list context. Each returned value,
whether scalar or list, will be interpolated as part of the overall
sequence of scalar values. That is, all the lists get flattened into one
list. From the viewpoint of the function receiving the arguments, the
overall argument LIST
is always a
single-dimensional list value. (To interpolate an array as a single
element, you must explicitly create and interpolate a reference to the
array instead.)
Predefined Perl functions may be used either with or without parentheses around their arguments; the syntax summaries in this chapter omit the parentheses. If you do use parentheses, the simple but occasionally surprising rule is this: if it looks like a function, then it is a function, so precedence doesn't matter. Otherwise, it's a list operator or unary operator, and precedence does matter. Be careful, because even if you put whitespace between the keyword and its left parenthesis, that doesn't keep it from being a function:
print 1+2*4; # Prints 9. print(1+2) * 4; # Prints 3! print (1+2)*4; # Also prints 3! print +(1+2)*4; # Prints 12. print ((1+2)*4); # Prints 12.
If you run Perl with the -w
switch, it will warn you about this. For example, the second and third
lines above produce messages like this:
print (…) interpreted as function at - line 2. Useless use of integer multiplication in void context at - line 2.
Given the simple definition of some functions, you have
considerable latitude in how you pass arguments. For instance, the most
common way to use chmod
is to pass the file
permissions (the mode) as an initial argument:
chmod 0644, @array;
but the definition of chmod
just says:
chmod LIST
so you could just as well say:
unshift @array, 0644; chmod @array;
If the first argument of the list is not a valid mode,
chmod
will fail, but that's a run-time semantic
problem unrelated to the syntax of the call. If the semantics require
any special arguments to be passed first, the text will describe these
restrictions.
In contrast to the simple LIST
functions, other functions impose additional syntactic constraints. For
instance, push
has a syntax summary that looks like
this:
pushARRAY
,LIST
This means that push
requires a proper array as
its first argument, but doesn't care about its subsequent arguments.
That's what the LIST
at the end means.
(LIST
s always come at the end, since they
gobble up all remaining values.) Whenever a syntax summary contains any
arguments before the LIST
, those arguments
are syntactically distinguished by the compiler, not just semantically
distinguished by the interpreter when it runs later. Such arguments are
never evaluated in list context. They may be evaluated in scalar
context, or they may be special referential arguments such as the array
in push
. (The description will tell you which is
which.)
For those operations that are based
directly on the C library's functions, we do not attempt to duplicate
your system's documentation. When a function
description says to see function (2), that
means that you should look up the corresponding C version of that
function to learn more about its semantics. The number in parentheses
indicates the section of the system programmer's manual in which you
will find the manpage, if you have the manpages installed. (And in which
you won't, if you don't.)
These manpages may document system-dependent behavior like shadow password files, access control lists, and so forth. Many Perl functions that derive from C library functions in Unix are emulated even on non-Unix platforms. For example, although your operating system might not support the flock (2) or fork (2) syscalls, Perl will do its best to emulate them anyway by using whatever native facilities your platform provides.
Occasionally, you'll find that the documented C function has more arguments than the corresponding Perl function. Generally, the missing arguments are things that Perl knows already, such as the length of the previous argument, so you needn't supply them in Perl. Any remaining disparities are caused by the different ways Perl and C specify filehandles and success/failure values.
In general, functions in Perl that serve as wrappers for syscalls
of the same name (like chown (2),
fork (2), closedir
(2), etc.) all return true when they succeed and
undef
otherwise, as mentioned in the descriptions
that follow. This is different from the C library's interfaces to these
operations, which all return -1
on failure.
Exceptions to this rule are wait
,
waitpid
, and syscall
. Syscalls
also set the special $!
($OS_ERROR
) variable on failure. Other functions do
not, except accidentally.
For functions that can be used in either scalar or list
context, failure is generally indicated in scalar context by returning a
false value (usually undef
) and in list context by
returning the null list. Successful execution is generally indicated by
returning a value that will evaluate to true (in context).
Remember the following rule: there is no rule that relates the behavior of a function in list context to its behavior in scalar context, or vice versa. It might do two totally different things.
Each function knows the context in which it was called. The same function that returns a list when called in list context will, when called in scalar context, return whichever kind of value would be most appropriate. Some functions return the length of the list that would have been returned in list context. Some operators return the first value in the list. Some functions return the last value in the list. Some functions return the "other" value, when something can be looked up either by number or by name. Some functions return a count of successful operations. In general, Perl functions do exactly what you want, unless you want consistency.
One final note: we've tried to be very consistent in our use of the terms "byte" and "character". Historically, these terms have been confused with each other (and with themselves). But when we say "byte" we always mean an octet, 8 bits. When we say "character", we mean an abstract character, usually a Unicode character, which may be represented by one or more bytes within your strings.
But notice that we said "usually". Perl purposefully confuses
bytes with characters in the scope of a use bytes
declaration, so whenever we say "character", you should take it to mean
a byte in a use bytes
context, and a Unicode
character otherwise. In other words, use bytes
just
warps the definition of character back to what it was in older versions
of Perl. So, for instance, when we say that a scalar
reverse
reverses a string character by character,
don't ask us whether that really means characters
or bytes, because the answer is, "Yes, it does."
Here are Perl's functions and function-like keywords, arranged by category. Some functions appear under more than one heading.
chomp
,
chop
, chr
,
crypt
, hex
,
index
, lc
,
lcfirst
, length
,
oct
, ord
,
pack
, q//
,
qq//
, reverse
,
rindex
, sprintf
,
substr
, tr///
,
uc
, ucfirst
,
y///
abs
, atan2
,
cos
, exp
,
hex
, int
,
log
, oct
,
rand
, sin
,
sqrt
, srand
binmode
,
close
, closedir
,
dbmclose
, dbmopen
,
die
, eof
,
fileno
, flock
,
format
, getc
,
print
, printf
,
read
, readdir
,
readpipe
, rewinddir
,
seek
, seekdir
,
select
(ready file descriptors),
syscall
, sysread
,
sysseek
, syswrite
,
tell
, telldir
,
truncate
, warn
,
write
pack
, read
,
syscall
, sysread
,
sysseek
, syswrite
,
unpack
, vec
chdir
,
chmod
, chown
,
chroot
, fcntl
,
glob
, ioctl
,
link
, lstat
,
mkdir
, open
,
opendir
, readlink
,
rename
, rmdir
,
select
(ready file descriptors),
select
(output filehandle),
stat
, symlink
,
sysopen
, umask
,
unlink
, utime
caller
,
continue
, die
,
do
, dump
,
eval
, exit
,
goto
, last
,
next
, redo
,
return
, sub
,
wantarray
defined
, dump
,
eval
, formline
,
lock
, prototype
,
reset
, scalar
,
undef
, wantarray
alarm
,
exec
, fork
,
getpgrp
, getppid
,
getpriority
, kill
,
pipe
, qx//
,
setpgrp
, setpriority
,
sleep
, system
,
times
, wait
,
waitpid
bless
,
dbmclose
, dbmopen
,
package
, ref
,
tie
, tied
,
untie
, use
accept
,
bind
, connect
,
getpeername
, getsockname
,
getsockopt
, listen
,
recv
, send
,
setsockopt
, shutdown
,
socket
, socketpair
msgctl
,
msgget
, msgrcv
,
msgsnd
, semctl
,
semget
, semop
,
shmctl
, shmget
,
shmread
, shmwrite
endgrent
,
endhostent
, endnetent
,
endpwent
, getgrent
,
getgrgid
, getgrnam
,
getlogin
, getpwent
,
getpwnam
, getpwuid
,
setgrent
, setpwent
endprotoent
,
endservent
, gethostbyaddr
,
gethostbyname
, gethostent
,
getnetbyaddr
,
getnetbyname
, getnetent
,
getprotobyname
,
getprotobynumber
,
getprotoent
,
getservbyname
,
getservbyport
, getservent
,
sethostent
, setnetent
,
setprotoent
,
setservent
[1] Sometimes tightly related functions are grouped together in
the system manpages, so we respect that grouping here. To find the
description of endpwent
, for instance, you'll
have to look under getpwent
.