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

Keywords related to the control flow of your perl program
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.