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
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.
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
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
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.
Here are Perl's functions and function-like keywords, arranged by category. Some functions appear under more than one heading.
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
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
endprotoent, endservent, gethostbyaddr, gethostbyname, gethostent, getnetbyaddr, getnetbyname, getnetent, getprotobyname, getprotobynumber, getprotoent, getservbyname, getservbyport, getservent, sethostent, setnetent, setprotoent, setservent