[Chapter 3] Functions
Author: Larry Wall, Tom Christiansen, and Randal Schwartz
Date: Fri Aug 29 18:34:31 1997

#

| Chapter 3 |

# 3. Functions

Contents:
Perl Functions by Category
Perl Functions in Alphabetical Order

This chapter describes each of the Perl functions. They're presented one by one in alphabetical order. (Well, actually, some related functions are presented in pairs, or even threes or fours. This is usually the case when the Perl functions simply make UNIX system calls or C library calls. In such cases, the presentation of the Perl function matches up with the corresponding UNIX manpage organization.)

Each function description begins with a brief presentation of the syntax for that function. Parameters in `ALL_CAPS` represent placeholders for actual expressions, as described in the body of the function description. Some parameters are optional; the text describes the default values used when the parameter is not included.

The functions described in this chapter can serve as terms in an expression, along with literals and variables. (Or you can think of them as prefix operators. We call them operators half the time anyway.) Some of these operators, er, functions take a `LIST` as an argument. Such a list can consist of any combination of scalar and list values, but any list values are interpolated as a sequence of scalar values; that is, the overall argument `LIST` remains 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.) Elements of the `LIST` should be separated by commas (or by `=>`, which is just a funny kind of comma). Each element of the `LIST` is evaluated in a list context.

The functions described in this chapter may be used either with or without parentheses around their arguments. (The syntax descriptions omit the parentheses.) If you use the parentheses, the simple (but occasionally surprising) rule is this: if it looks like a function, 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 its left parenthesis doesn't count--so you need to be careful sometimes:

    print 1+2+3;       # Prints 6.
    print(1+2) + 3;    # Prints 3.
    print (1+2)+3;     # Also prints 3!
    print +(1+2)+3;    # Prints 6.
    print ((1+2)+3);   # Prints 6.

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 3.
    Useless use of integer addition in void context at - line 3.

Some of the `LIST` operators impose special semantic significance on the first element or two of the list. For example, the chmod function requires that the first element of the list be the new permission to apply to the files listed in the remaining elements. Syntactically, however, the argument to chmod is really just a `LIST`, and you could say:

    unshift @array,0644;
    chmod @array;

which is the same as:

    chmod 0644, @array;

In these cases, the syntax summary at the top of the section mentions only the bare `LIST`, and any special initial arguments are documented in the description.

On the other hand, if the syntax summary lists any arguments before the `LIST`, those arguments are syntactically distinguished (not just semantically distinguished), and may impose syntactic constraints on the actual arguments you pass to the function when you call it. For instance, the first argument to the push function must be an array name. (You may also put such syntactic constraints on your own subroutine declarations by the use of prototypes. See "Prototypes" in Chapter 2, The Gory Details.)

Many of these operations are based directly on the C library's functions. If so, we do not attempt to duplicate the UNIX system documentation for that function, but refer you directly to the manual page. Such references look like this: "See getlogin (3)." The number in parentheses tells you which section of the UNIX manual normally contains the given entry. If you can't find a manual page (manpage for short) for a particular C function on your system, it's likely that the corresponding Perl function is unimplemented. For example, not all systems implement socket (2) calls. If you're running in the MS-DOS world, you may have socket calls, but you won't have fork (2). (You probably won't have manpages either, come to think of it.)

Occasionally you'll find that the documented C function has more arguments than the corresponding Perl function. The missing arguments are almost always things that Perl already knows, such as the length of the previous argument, so you needn't supply them in Perl. Any remaining disparities are due to different ways Perl and C specify their filehandles and their success/failure values.

For functions that can be used in either scalar or list context, non-abortive failure is generally indicated in a scalar context by returning the undefined value, and in a 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 general rule for converting a list into a scalar!

Many operators can return a list in list context. Each such operator knows whether it is being called in scalar or list context, and in scalar context returns whichever sort of value it would be most appropriate to return. 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 the "other" value, when something can be looked up either by number or by name. Some operators return a count of successful operations. In general, Perl operators do exactly what you want, unless you want consistency.

## 3.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, 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, rewinddir, seek, seekdir, select (ready file descriptors), syscall, sysread, syswrite, tell, telldir, truncate, warn, write

Fixed-length data and records

  pack, read, syscall, sysread, syswrite, unpack, vec

Filehandles, files, and directories

  chdir, chmod, chown, chroot, fcntl, glob, ioctl, link, lstat, mkdir, open, opendir, readlink, rename, rmdir, 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, package, use

Miscellaneous

  defined, dump, eval, formline, local, my, 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

Special Variables |  | Perl Functions in Alphabetical Order