Chapter 29. Functions

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.

[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.

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:

push ARRAY, 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. (LISTs 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."

29.1. Perl Functions by Category

Here are Perl's functions and function-like keywords, arranged by category. Some functions appear under more than one heading.

Scalar manipulation: chomp, chop, chr, crypt, hex, index, lc, lcfirst, length, oct, ord, pack, q//, qq//, reverse, rindex, sprintf, substr, tr///, uc, ucfirst, y///
Regular expressions and pattern matching: m//, pos, qr//, quotemeta, s///, split, study
Numeric functions: abs, atan2, cos, exp, hex, int, log, oct, rand, sin, sqrt, srand
Array processing: pop, push, shift, splice, unshift
List processing: grep, join, map, qw//, reverse, sort, unpack
Hash processing: delete, each, exists, keys, values
Input and output: 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
Fixed-length data and records: pack, read, syscall, sysread, sysseek, syswrite, unpack, vec
Filehandles, files, and directories: 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
Flow of program control: caller, continue, die, do, dump, eval, exit, goto, last, next, redo, return, sub, wantarray
Scoping: caller, import, local, my, no, our, package, use
Miscellaneous: defined, dump, eval, formline, lock, prototype, reset, scalar, undef, wantarray
Processes and process groups: alarm, exec, fork, getpgrp, getppid, getpriority, kill, pipe, qx//, setpgrp, setpriority, sleep, system, times, wait, waitpid
Library modules: do, import, no, package, require, use
Classes and objects: bless, dbmclose, dbmopen, package, ref, tie, tied, untie, use
Low-level socket access: accept, bind, connect, getpeername, getsockname, getsockopt, listen, recv, send, setsockopt, shutdown, socket, socketpair
System V interprocess communication: msgctl, msgget, msgrcv, msgsnd, semctl, semget, semop, shmctl, shmget, shmread, shmwrite
Fetching user and group information: endgrent, endhostent, endnetent, endpwent, getgrent, getgrgid, getgrnam, getlogin, getpwent, getpwnam, getpwuid, setgrent, setpwent
Fetching network information: endprotoent, endservent, gethostbyaddr, gethostbyname, gethostent, getnetbyaddr, getnetbyname, getnetent, getprotobyname, getprotobynumber, getprotoent, getservbyname, getservbyport, getservent, sethostent, setnetent, setprotoent, setservent
Time: gmtime, localtime, time, times

Chapter 29. Functions

Contents:

29.1. Perl Functions by Category