NAME
DESCRIPTION
- Perl Functions by Category
- Alphabetical Listing of Perl Functions

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 and 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 list argument.) For instance, splice() has three scalar arguments followed by a list.

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.

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 a 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///

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

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

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

Alphabetical Listing of Perl Functions

-X: run a file test
abs: absolute value function
accept: accept an incoming socket connect
alarm: schedule a SIGALRM
atan2: arctangent of Y/X
bind: binds an address to a socket
binmode: prepare binary files on old systems
bless: create an object
caller: get context of the current subroutine call
chdir: change your current working directory
chmod: changes the permissions on a list of files
chomp: remove a trailing record separator from a string
chop: remove the last character from a string
chown: change the owership on a list of files
chr: get character this number represents
chroot: make directory new root for path lookups
close: close file (or pipe or socket) handle
closedir: close directory handle
connect: connect to a remove socket
continue: optional trailing block in a while or foreach
cos: cosine function
crypt: one-way passwd-style encryption
dbmclose: breaks binding on a tied dbm file
dbmopen: create binding on a tied dbm file
defined: test whether a value, variable, or function is defined
delete: deletes a value from a hash
die: raise an exception or bail out
do: turn a BLOCK into a TERM
dump: create an immediate core dump
each: retrieve the next key/value pair from a hash
endgrent: be done using group file
endhostent: be done using hosts file
endnetent: be done using networks file
endprotoent: be done using protocols file
endpwent: be done using passwd file
endservent: be done using services file
eof: test a filehandle for its end
eval: catch exceptions or compile code
exec: abandon this program to run another
exists: test whether a hash key is present
exit: terminate this program
exp: raise e to a power
fcntl: file control system all
fileno: return file descriptor from filehandle
flock: lock an entire file with an advisory lock
fork: create a new process just like this one
format: declare a picture format with use by the write() function
formline: internal function used for formats
getc: get the next character from the filehandle
getgrent: get next group record
getgrgid: get group record given group user ID
getgrnam: get group record given group name
gethostbyaddr: get host record given its address
gethostbyname: get host record given name
gethostent: get next hosts record
getlogin: return who logged in at this tty
getnetbyaddr: get network record given its address
getnetbyname: get networks record given name
getnetent: get next networks record
getpeername: find the other hend of a socket connection
getpgrp: get process group
getppid: get parent process ID
getpriority: get current nice value
getprotobyname: get protocol record given name
getprotobynumber: get protocol record numeric protocol
getprotoent: get next protocols record
getpwent: get next passwd record
getpwnam: get passwd record given user login name
getpwuid: get passwd record given user ID
getservbyname: get services record given its name
getservbyport: get services record given numeric port
getservent: get next services record
getsockname: retrieve the sockaddr for a given socket
getsockopt: get socket options on a given socket
glob: expand filenames using wildcards
gmtime: convert UNIX time into record or string using Greenwich time
goto: create spaghetti code
grep: locate elements in a list test true against a given criterion
hex: convert a string to a hexadecimal number
import: patch a module's namespace into your own
int: get the integer portion of a number
ioctl: system-dependent device control system call
join: join a list into a string using a separator
keys: retrieve list of indices from a hash
kill: send a signal to a process or process group
last: exit a block prematurely
lc: return lower-case version of a string
lcfirst: return a string with just the next letter in lower case
length: return the number of bytes in a string
link: create a hard link in the filesytem
listen: register your socket as a server
local: create a temporary value for a global variable (dynamic scoping)
localtime: convert UNIX time into record or string using local time
log: retrieve the natural logarithm for a number
lstat: stat a symbolic link
m//: match a string with a regular expression pattern
map: apply a change to a list to get back a new list with the changes
mkdir: create a directory
msgctl: SysV IPC message control operations
msgget: get SysV IPC message queue
msgrcv: receive a SysV IPC message from a message queue
msgsnd: send a SysV IPC message to a message queue
my: declare and assign a local variable (lexical scoping)
next: iterate a block prematurely
no: unimport some module symbols or semantics at compile time
oct: convert a string to an octal number
open: open a file, pipe, or descriptor
opendir: open a directory
ord: find a character's numeric representation
pack: convert a list into a binary representation
package: declare a separate global namespace
pipe: open a pair of connected filehandles
pop: remove the last element from an array and return it
pos: find or set the offset for the last/next m//g search
print: output a list to a filehandle
printf: output a formatted list to a filehandle
prototype: get the prototype (if any) of a subroutine
push: append one or more elements to an array
q/STRING/: singly quote a string
qq/STRING/: doubly quote a string
quotemeta: quote regular expression magic characters
qw/STRING/: quote a list of words
qx/STRING/: backquote quote a string
rand: retrieve the next pseudorandom number
read: fixed-length buffered input from a filehandle
readdir: get a directory from a directory handle
readlink: determine where a symbolic link is pointing
recv: receive a message over a Socket
redo: start this loop iteration over again
ref: find out the type of thing being referenced
rename: change a filename
require: load in external functions from a library at runtime
reset: clear all variables of a given name
return: get out of a function early
reverse: flip a string or a list
rewinddir: reset directory handle
rindex: right-to-left substring search
rmdir: remove a directory
s///: replace a pattern with a string
scalar: force a scalar context
seek: reposition file pointer for random-access I/O
seekdir: reposition directory pointer
select: reset default output or do I/O multiplexing
semctl: SysV semaphore control operations
semget: get set of SysV semaphores
semop: SysV semaphore operations
send: send a message over a socket
setgrent: prepare group file for use
sethostent: prepare hosts file for use
setnetent: prepare networks file for use
setpgrp: set the process group of a process
setpriority: set a process's nice value
setprotoent: prepare protocols file for use
setpwent: prepare passwd file for use
setservent: prepare services file for use
setsockopt: set some socket options
shift: remove the first element of an array, and return it
shmctl: SysV shared memory operations
shmget: get SysV shared memory segment identifier
shmread: read SysV shared memory
shmwrite: write SysV shared memory
shutdown: close down just half of a socket connection
sin: return the sin of a number
sleep: block for some number of seconds
socket: create a socket
socketpair: create a pair of sockets
sort: sort a list of values
splice: add or remove elements anywhere in an array
split: split up a string using a regexp delimiter
sprintf: formatted print into a string
sqrt: square root function
srand: seed the random number generator
stat: get a file's status information
study: optimize input data for repeated searches
sub: declare a subroutine, possibly anonymously
substr: get or alter a portion of a stirng
symlink: create a symbolic link to a file
syscall: execute an arbitrary system call
sysread: fixed-length unbuffered input from a filehandle
system: run a separate program
syswrite: fixed-length unbuffered output to a filehandle
tell: get current seekpointer on a filehandle
telldir: get current seekpointer on a directory handle
tie: bind a variable to an object class
time: return number of seconds since 1970
times: return elapsed time for self and child processes
tr///: transliterate a string
truncate: shorten a file
uc: return upper-case version of a string
ucfirst: return a string with just the next letter in upper case
umask: set file creation mode mask
undef: remove a variable or function definition
unlink: remove one link to a file
unpack: convert binary structure into normal perl variables
unshift: prepend more elements to the beginning of a list
untie: break a tie binding to a variable
use: load in a module at compile time
utime: set a file's last access and modify times
values: return a list of the values in a hash
vec: test or set particular bits in a string
wait: wait for any child process to die
waitpid: wait for a particular child process to die
wantarray: get list vs array context of current subroutine call
warn: print debugging info
write: print a picture record
y///: transliterate a string

DISCLAIMER

We are painfully aware that these documents may contain incorrect links and misformatted HTML. Such bugs lie in the automatic translation process that automatically created the hundreds and hundreds of separate documents that you find here. Please do not report link or formatting bugs, because we cannot fix per-document problems. The only bug reports that will help us are those that supply working patches to the installhtml or pod2html programs, or to the Pod::HTML module itself, for which I and the entire Perl community will shower you with thanks and praises.

If rather than formatting bugs, you encounter substantive content errors in these documents, such as mistakes in the explanations or code, please use the perlbug utility included with the Perl distribution.

--Tom Christiansen, Perl Documentation Compiler and Editor

Return to the Perl Documentation Index.
Return to the Perl Home Page.