=head1 NAME
+X<function>
perlfunc - Perl builtin functions
last value in the list. Some operators return a count of successful
operations. In general, they do what you want, unless you want
consistency.
+X<context>
A 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
variable on failure. Other functions do not, except accidentally.
=head2 Perl Functions by Category
+X<function>
Here are Perl's functions (including things that look like
functions, like some keywords and named operators)
=over 4
=item Functions for SCALARs or strings
+X<scalar> X<string> X<character>
C<chomp>, C<chop>, C<chr>, C<crypt>, C<hex>, C<index>, C<lc>, C<lcfirst>,
C<length>, C<oct>, C<ord>, C<pack>, C<q/STRING/>, C<qq/STRING/>, C<reverse>,
C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y///>
=item Regular expressions and pattern matching
+X<regular expression> X<regex> X<regexp>
C<m//>, C<pos>, C<quotemeta>, C<s///>, C<split>, C<study>, C<qr//>
=item Numeric functions
+X<numeric> X<number> X<trigonometric> X<trigonometry>
C<abs>, C<atan2>, C<cos>, C<exp>, C<hex>, C<int>, C<log>, C<oct>, C<rand>,
C<sin>, C<sqrt>, C<srand>
=item Functions for real @ARRAYs
+X<array>
C<pop>, C<push>, C<shift>, C<splice>, C<unshift>
=item Functions for list data
+X<list>
C<grep>, C<join>, C<map>, C<qw/STRING/>, C<reverse>, C<sort>, C<unpack>
=item Functions for real %HASHes
+X<hash>
C<delete>, C<each>, C<exists>, C<keys>, C<values>
=item Input and output functions
+X<I/O> X<input> X<output> X<dbm>
C<binmode>, C<close>, C<closedir>, C<dbmclose>, C<dbmopen>, C<die>, C<eof>,
C<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>,
C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec>
=item Functions for filehandles, files, or directories
+X<file> X<filehandle> X<directory> X<pipe> X<link> X<symlink>
C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
C<umask>, C<unlink>, C<utime>
=item Keywords related to the control flow of your Perl program
+X<control flow>
C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>,
C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>
C<scalar>, C<undef>, C<wantarray>
=item Functions for processes and process groups
+X<process> X<pid> X<process id>
C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>,
C<pipe>, C<qx/STRING/>, C<setpgrp>, C<setpriority>, C<sleep>, C<system>,
C<times>, C<wait>, C<waitpid>
=item Keywords related to perl modules
+X<module>
C<do>, C<import>, C<no>, C<package>, C<require>, C<use>
=item Keywords related to classes and object-orientedness
+X<object> X<class> X<package>
C<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>,
C<untie>, C<use>
=item Low-level socket functions
+X<socket> X<sock>
C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
C<socket>, C<socketpair>
=item System V interprocess communication functions
+X<IPC> X<System V> X<semaphore> X<shared memory> X<memory> X<message>
C<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<semctl>, C<semget>, C<semop>,
C<shmctl>, C<shmget>, C<shmread>, C<shmwrite>
=item Fetching user and group info
+X<user> X<group> X<password> X<uid> X<gid> X<passwd> X</etc/passwd>
C<endgrent>, C<endhostent>, C<endnetent>, C<endpwent>, C<getgrent>,
C<getgrgid>, C<getgrnam>, C<getlogin>, C<getpwent>, C<getpwnam>,
C<getpwuid>, C<setgrent>, C<setpwent>
=item Fetching network info
+X<network> X<protocol> X<host> X<hostname> X<IP> X<address> X<service>
C<endprotoent>, C<endservent>, C<gethostbyaddr>, C<gethostbyname>,
C<gethostent>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
C<setnetent>, C<setprotoent>, C<setservent>
=item Time-related functions
+X<time> X<date>
C<gmtime>, C<localtime>, C<time>, C<times>
=item Functions new in perl5
+X<perl5>
C<abs>, C<bless>, C<chomp>, C<chr>, C<exists>, C<formline>, C<glob>,
C<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<our>, C<prototype>,
=back
=head2 Portability
+X<portability> X<Unix> X<portable>
Perl was born in Unix and can therefore access all common Unix
system calls. In non-Unix environments, the functionality of some
=over 8
=item -X FILEHANDLE
+X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p>
+X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
=item -X EXPR
names, precedence is the same as any other named unary operator, and
the argument may be parenthesized like any other unary operator. The
operator may be any of:
-X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p>
-X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
-r File is readable by effective uid/gid.
-w File is writable by effective uid/gid.
operator, no special magic will happen.)
=item abs VALUE
+X<abs> X<absolute>
=item abs
If VALUE is omitted, uses C<$_>.
=item accept NEWSOCKET,GENERICSOCKET
+X<accept>
Accepts an incoming socket connect, just as the accept(2) system call
does. Returns the packed address if it succeeded, false otherwise.
value of $^F. See L<perlvar/$^F>.
=item alarm SECONDS
+X<alarm>
+X<SIGALRM>
+X<timer>
=item alarm
For more information see L<perlipc>.
=item atan2 Y,X
+X<atan2> X<arctangent> X<tan> X<tangent>
Returns the arctangent of Y/X in the range -PI to PI.
sub tan { sin($_[0]) / cos($_[0]) }
+Note that atan2(0, 0) is not well-defined.
+
=item bind SOCKET,NAME
+X<bind>
Binds a network address to a socket, just as the bind system call
does. Returns true if it succeeded, false otherwise. NAME should be a
L<perlipc/"Sockets: Client/Server Communication">.
=item binmode FILEHANDLE, LAYER
+X<binmode> X<binary> X<text> X<DOS> X<Windows>
=item binmode FILEHANDLE
line-termination sequences.
=item bless REF,CLASSNAME
+X<bless>
=item bless REF
See L<perlmod/"Perl Modules">.
=item caller EXPR
+X<caller> X<call stack> X<stack> X<stack trace>
=item caller
previous time C<caller> was called.
=item chdir EXPR
+X<chdir>
+X<cd>
=item chdir FILEHANDLE
passing handles produces a fatal error at run time.
=item chmod LIST
+X<chmod> X<permission> X<mode>
Changes the permissions of a list of files. The first element of the
list must be the numerical mode, which should probably be an octal
# This is identical to the chmod 0755 of the above example.
=item chomp VARIABLE
+X<chomp> X<INPUT_RECORD_SEPARATOR> X<$/> X<newline> X<eol>
=item chomp( LIST )
as C<chomp($a, $b)>.
=item chop VARIABLE
+X<chop>
=item chop( LIST )
See also L</chomp>.
=item chown LIST
+X<chown> X<owner> X<user> X<group>
Changes the owner (and group) of a list of files. The first two
elements of the list must be the I<numeric> uid and gid, in that
$can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
=item chr NUMBER
+X<chr> X<character> X<ASCII> X<Unicode>
=item chr
backward compatibility reasons (but see L<encoding>).
Negative values give the Unicode replacement character (chr(0xfffd)),
-except under the L</bytes> pragma, where low eight bits of the value
+except under the L<bytes> pragma, where low eight bits of the value
(truncated to an integer) are used.
If NUMBER is omitted, uses C<$_>.
See L<perlunicode> and L<encoding> for more about Unicode.
=item chroot FILENAME
+X<chroot> X<root>
=item chroot
omitted, does a C<chroot> to C<$_>.
=item close FILEHANDLE
+X<close>
=item close
filehandle, usually the real filehandle name.
=item closedir DIRHANDLE
+X<closedir>
Closes a directory opened by C<opendir> and returns the success of that
system call.
=item connect SOCKET,NAME
+X<connect>
Attempts to connect to a remote socket, just as the connect system call
does. Returns true if it succeeded, false otherwise. NAME should be a
L<perlipc/"Sockets: Client/Server Communication">.
=item continue BLOCK
+X<continue>
C<continue> is actually a flow control statement rather than a function. If
there is a C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
to check the condition at the top of the loop.
=item cos EXPR
+X<cos> X<cosine> X<acos> X<arccosine>
=item cos
sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
=item crypt PLAINTEXT,SALT
+X<crypt> X<digest> X<hash> X<salt> X<plaintext> X<password>
+X<decrypt> X<cryptography> X<passwd>
Creates a digest string exactly like the crypt(3) function in the C
library (assuming that you actually have a version there that has not
C<Wide character in crypt>.
=item dbmclose HASH
+X<dbmclose>
[This function has been largely superseded by the C<untie> function.]
Breaks the binding between a DBM file and a hash.
=item dbmopen HASH,DBNAME,MASK
+X<dbmopen> X<dbm> X<ndbm> X<sdbm> X<gdbm>
[This function has been largely superseded by the C<tie> function.]
or die "Can't open netscape history file: $!";
=item defined EXPR
+X<defined> X<undef> X<undefined>
=item defined
See also L</undef>, L</exists>, L</ref>.
=item delete EXPR
+X<delete>
Given an expression that specifies a hash element, array element, hash slice,
or array slice, deletes the specified element(s) from the hash or array.
delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
=item die LIST
+X<die> X<throw> X<exception> X<raise> X<$@> X<abort>
Outside an C<eval>, prints the value of LIST to C<STDERR> and
exits with the current value of C<$!> (errno). If C<$!> is C<0>,
behavior may be fixed in a future release.
=item do BLOCK
+X<do> X<block>
Not really a function. Returns the value of the last command in the
sequence of commands indicated by BLOCK. When modified by the C<while> or
See L<perlsyn> for alternative strategies.
=item do SUBROUTINE(LIST)
+X<do>
This form of subroutine call is deprecated. See L<perlsub>.
=item do EXPR
+X<do>
Uses the value of EXPR as a filename and executes the contents of the
file as a Perl script.
}
=item dump LABEL
+X<dump> X<core> X<undump>
=item dump
make your program I<appear> to run faster.
=item each HASH
+X<each> X<hash, iterator>
When called in list context, returns a 2-element list consisting of the
key and value for the next element of a hash, so that you can iterate over
See also C<keys>, C<values> and C<sort>.
=item eof FILEHANDLE
+X<eof>
+X<end of file>
+X<end-of-file>
=item eof ()
there was an error.
=item eval EXPR
+X<eval> X<try> X<catch> X<evaluate> X<parse> X<execute>
=item eval BLOCK
need to worry about this unless you are writing a Perl debugger.
=item exec LIST
+X<exec> X<execute>
=item exec PROGRAM LIST
any C<DESTROY> methods in your objects.
=item exists EXPR
+X<exists> X<autovivification>
Given an expression that specifies a hash element or array element,
returns true if the specified element in the hash or array has ever
exists &sub(); # Error
=item exit EXPR
+X<exit> X<terminate> X<abort>
=item exit
See L<perlmod> for details.
=item exp EXPR
+X<exp> X<exponential> X<antilog> X<antilogarithm> X<e>
=item exp
If EXPR is omitted, gives C<exp($_)>.
=item fcntl FILEHANDLE,FUNCTION,SCALAR
+X<fcntl>
Implements the fcntl(2) function. You'll probably have to say
or die "Can't set flags for the socket: $!\n";
=item fileno FILEHANDLE
+X<fileno>
Returns the file descriptor for a filehandle, or undefined if the
filehandle is not open. This is mainly useful for constructing
=item flock FILEHANDLE,OPERATION
+X<flock> X<lock> X<locking>
Calls flock(2), or an emulation of it, on FILEHANDLE. Returns true
for success, false on failure. Produces a fatal error if used on a
See also L<DB_File> for other flock() examples.
=item fork
+X<fork> X<child> X<parent>
Does a fork(2) system call to create a new process running the
same program at the same point. It returns the child pid to the
You should reopen those to F</dev/null> if it's any issue.
=item format
+X<format>
Declare a picture format for use by the C<write> function. For
example:
See L<perlform> for many details and examples.
=item formline PICTURE,LIST
+X<formline>
This is an internal function used by C<format>s, though you may call it,
too. It formats (see L<perlform>) a list of values according to the
C<formline> always returns true. See L<perlform> for other examples.
=item getc FILEHANDLE
+X<getc> X<getchar>
=item getc
L<perlmodlib/CPAN>.
=item getlogin
+X<getlogin> X<login>
This implements the C library function of the same name, which on most
systems returns the current login from F</etc/utmp>, if any. If null,
secure as C<getpwuid>.
=item getpeername SOCKET
+X<getpeername> X<peer>
Returns the packed sockaddr address of other end of the SOCKET connection.
$herstraddr = inet_ntoa($iaddr);
=item getpgrp PID
+X<getpgrp> X<group>
Returns the current process group for the specified PID. Use
a PID of C<0> to get the current process group for the
does not accept a PID argument, so only C<PID==0> is truly portable.
=item getppid
+X<getppid> X<parent> X<pid>
Returns the process id of the parent process.
C<Linux::Pid>.
=item getpriority WHICH,WHO
+X<getpriority> X<priority> X<nice>
Returns the current priority for a process, a process group, or a user.
(See L<getpriority(2)>.) Will raise a fatal exception if used on a
machine that doesn't implement getpriority(2).
=item getpwnam NAME
+X<getpwnam> X<getgrnam> X<gethostbyname> X<getnetbyname> X<getprotobyname>
+X<getpwuid> X<getgrgid> X<getservbyname> X<gethostbyaddr> X<getnetbyaddr>
+X<getprotobynumber> X<getservbyport> X<getpwent> X<getgrent> X<gethostent>
+X<getnetent> X<getprotoent> X<getservent> X<setpwent> X<setgrent> X<sethostent>
+X<setnetent> X<setprotoent> X<setservent> X<endpwent> X<endgrent> X<endhostent>
+X<endnetent> X<endprotoent> X<endservent>
=item getgrnam NAME
a C<User::pwent> object.
=item getsockname SOCKET
+X<getsockname>
Returns the packed sockaddr address of this end of the SOCKET connection,
in case you don't know the address because you have several different
inet_ntoa($myaddr);
=item getsockopt SOCKET,LEVEL,OPTNAME
+X<getsockopt>
Queries the option named OPTNAME associated with SOCKET at a given LEVEL.
Options may exist at multiple protocol levels depending on the socket
=item glob EXPR
+X<glob> X<wildcard> X<filename, expansion> X<expand>
=item glob
C<File::Glob> extension. See L<File::Glob> for details.
=item gmtime EXPR
+X<gmtime> X<UTC> X<Greenwich>
=item gmtime
See L<perlport/gmtime> for portability concerns.
=item goto LABEL
+X<goto> X<jump> X<jmp>
=item goto EXPR
reference.
=item grep BLOCK LIST
+X<grep>
=item grep EXPR,LIST
See also L</map> for a list composed of the results of the BLOCK or EXPR.
=item hex EXPR
+X<hex> X<hexadecimal>
=item hex
L</sprintf>, or L</unpack>.
=item import LIST
+X<import>
There is no builtin C<import> function. It is just an ordinary
method (subroutine) defined (or inherited) by modules that wish to export
for the package used. See also L</use>, L<perlmod>, and L<Exporter>.
=item index STR,SUBSTR,POSITION
+X<index> X<indexOf> X<InStr>
=item index STR,SUBSTR
the wildcard-like behavior of a full regular-expression pattern match.
It returns the position of the first occurrence of SUBSTR in STR at
or after POSITION. If POSITION is omitted, starts searching from the
-beginning of the string. The return value is based at C<0> (or whatever
+beginning of the string. POSITION before the beginning of the string
+or after its end is treated as if it were the beginning or the end,
+respectively. POSITION and the return value are based at C<0> (or whatever
you've set the C<$[> variable to--but don't do that). If the substring
is not found, C<index> returns one less than the base, ordinarily C<-1>.
=item int EXPR
+X<int> X<integer> X<truncate> X<trunc>
=item int
functions will serve you better than will int().
=item ioctl FILEHANDLE,FUNCTION,SCALAR
+X<ioctl>
Implements the ioctl(2) function. You'll probably first have to say
- require "sys/ioctl.ph"; # probably in $Config{archlib}/ioctl.ph
+ require "sys/ioctl.ph"; # probably in $Config{archlib}/sys/ioctl.ph
to get the correct function definitions. If F<sys/ioctl.ph> doesn't
exist or doesn't have the correct definitions you'll have to roll your
about improper numeric conversions.
=item join EXPR,LIST
+X<join>
Joins the separate strings of LIST into a single string with fields
separated by the value of EXPR, and returns that new string. Example:
first argument. Compare L</split>.
=item keys HASH
+X<keys> X<key>
Returns a list consisting of all the keys of the named hash.
(In scalar context, returns the number of keys.)
See also C<each>, C<values> and C<sort>.
=item kill SIGNAL, LIST
+X<kill> X<signal>
Sends a signal to a list of processes. Returns the number of
processes successfully signaled (which is not necessarily the
See L<perlipc/"Signals"> for more details.
=item last LABEL
+X<last> X<break>
=item last
C<redo> work.
=item lc EXPR
+X<lc> X<lowercase>
=item lc
If EXPR is omitted, uses C<$_>.
=item lcfirst EXPR
+X<lcfirst> X<lowercase>
=item lcfirst
If EXPR is omitted, uses C<$_>.
=item length EXPR
+X<length> X<size>
=item length
in bytes, use C<do { use bytes; length(EXPR) }>, see L<bytes>.
=item link OLDFILE,NEWFILE
+X<link>
Creates a new filename linked to the old filename. Returns true for
success, false otherwise.
=item listen SOCKET,QUEUESIZE
+X<listen>
Does the same thing that the listen system call does. Returns true if
it succeeded, false otherwise. See the example in
L<perlipc/"Sockets: Client/Server Communication">.
=item local EXPR
+X<local>
You really probably want to be using C<my> instead, because C<local> isn't
what most people think of as "local". See
for details, including issues with tied arrays and hashes.
=item localtime EXPR
+X<localtime>
=item localtime
See L<perlport/localtime> for portability concerns.
=item lock THING
+X<lock>
This function places an advisory lock on a shared variable, or referenced
object contained in I<THING> until the lock goes out of scope.
keyword.) See L<threads>.
=item log EXPR
+X<log> X<logarithm> X<e> X<ln> X<base>
=item log
See also L</exp> for the inverse operation.
=item lstat EXPR
+X<lstat>
=item lstat
The match operator. See L<perlop>.
=item map BLOCK LIST
+X<map>
=item map EXPR,LIST
and you get list of anonymous hashes each with only 1 entry.
=item mkdir FILENAME,MASK
+X<mkdir> X<md> X<directory, create>
=item mkdir FILENAME
everyone happy.
=item msgctl ID,CMD,ARG
+X<msgctl>
Calls the System V IPC function msgctl(2). You'll probably have to say
L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::Semaphore> documentation.
=item msgget KEY,FLAGS
+X<msgget>
Calls the System V IPC function msgget(2). Returns the message queue
id, or the undefined value if there is an error. See also
L<perlipc/"SysV IPC"> and C<IPC::SysV> and C<IPC::Msg> documentation.
=item msgrcv ID,VAR,SIZE,TYPE,FLAGS
+X<msgrcv>
Calls the System V IPC function msgrcv to receive a message from
message queue ID into variable VAR with a maximum message size of
C<IPC::SysV::Msg> documentation.
=item msgsnd ID,MSG,FLAGS
+X<msgsnd>
Calls the System V IPC function msgsnd to send the message MSG to the
message queue ID. MSG must begin with the native long integer message
and C<IPC::SysV::Msg> documentation.
=item my EXPR
+X<my>
=item my TYPE EXPR
L<attributes>, and L<Attribute::Handlers>.
=item next LABEL
+X<next> X<continue>
=item next
C<redo> work.
=item no Module VERSION LIST
+X<no>
=item no Module VERSION
See the C<use> function, of which C<no> is the opposite.
=item oct EXPR
+X<oct> X<octal> X<hex> X<hexadecimal> X<binary> X<bin>
=item oct
conversion assumes base 10.)
=item open FILEHANDLE,EXPR
+X<open> X<pipe> X<file, open> X<fopen>
=item open FILEHANDLE,MODE,EXPR
See L</seek> for some details about mixing reading and writing.
=item opendir DIRHANDLE,EXPR
+X<opendir>
Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
C<seekdir>, C<rewinddir>, and C<closedir>. Returns true if successful.
DIRHANDLEs have their own namespace separate from FILEHANDLEs.
=item ord EXPR
+X<ord> X<encoding>
=item ord
See L<perlunicode> and L<encoding> for more about Unicode.
=item our EXPR
+X<our> X<global>
=item our EXPR TYPE
subject to change.
=item pack TEMPLATE,LIST
+X<pack>
Takes a LIST of values and converts it into a string using the rules
given by the TEMPLATE. The resulting string is the concatenation of
The same template may generally also be used in unpack().
=item package NAMESPACE
+X<package> X<module> X<namespace>
=item package
and classes. See L<perlsub> for other scoping issues.
=item pipe READHANDLE,WRITEHANDLE
+X<pipe>
Opens a pair of connected pipes like the corresponding system call.
Note that if you set up a loop of piped processes, deadlock can occur
See L<perlvar/$^F>.
=item pop ARRAY
+X<pop> X<stack>
=item pop
array in subroutines, just like C<shift>.
=item pos SCALAR
+X<pos> X<match, position>
=item pos
L<perlop>.
=item print FILEHANDLE LIST
+X<print>
=item print LIST
print { $OK ? STDOUT : STDERR } "stuff\n";
=item printf FILEHANDLE FORMAT, LIST
+X<printf>
=item printf FORMAT, LIST
error prone.
=item prototype FUNCTION
+X<prototype>
Returns the prototype of a function as a string (or C<undef> if the
function has no prototype). FUNCTION is a reference to, or the name of,
prototype is returned.
=item push ARRAY,LIST
+X<push>, X<stack>
Treats ARRAY as a stack, and pushes the values of LIST
onto the end of ARRAY. The length of ARRAY increases by the length of
$ARRAY[++$#ARRAY] = $value;
}
-but is more efficient. Returns the new number of elements in the array.
+but is more efficient. Returns the number of elements in the array following
+the completed C<push>.
=item q/STRING/
Generalized quotes. See L<perlop/"Regexp Quote-Like Operators">.
=item quotemeta EXPR
+X<quotemeta> X<metacharacter>
=item quotemeta
If EXPR is omitted, uses C<$_>.
=item rand EXPR
+X<rand> X<random>
=item rand
with the wrong number of RANDBITS.)
=item read FILEHANDLE,SCALAR,LENGTH,OFFSET
+X<read>
=item read FILEHANDLE,SCALAR,LENGTH
in that case pretty much any characters can be read.
=item readdir DIRHANDLE
+X<readdir>
Returns the next directory entry for a directory opened by C<opendir>.
If used in list context, returns all the rest of the entries in the
closedir DIR;
=item readline EXPR
+X<readline> X<gets> X<fgets>
Reads from the filehandle whose typeglob is contained in EXPR. In scalar
context, each call reads and returns the next line, until end-of-file is
}
=item readlink EXPR
+X<readlink>
=item readlink
omitted, uses C<$_>.
=item readpipe EXPR
+X<readpipe>
EXPR is executed as a system command.
The collected standard output of the command is returned.
operator is discussed in more detail in L<perlop/"I/O Operators">.
=item recv SOCKET,SCALAR,LENGTH,FLAGS
+X<recv>
Receives a message on a socket. Attempts to receive LENGTH characters
of data into variable SCALAR from the specified SOCKET filehandle.
in that case pretty much any characters can be read.
=item redo LABEL
+X<redo>
=item redo
C<redo> work.
=item ref EXPR
+X<ref> X<reference>
=item ref
See also L<perlref>.
=item rename OLDNAME,NEWNAME
+X<rename> X<move> X<mv> X<ren>
Changes the name of a file; an existing file NEWNAME will be
clobbered. Returns true for success, false otherwise.
rename(2) manpage or equivalent system documentation for details.
=item require VERSION
+X<require>
=item require EXPR
require 5.6.1; # ditto
require 5.006_001; # ditto; preferred for backwards compatibility
-Otherwise, C<ref> demands that a library file be included if it hasn't already
-been included. The file is included via the do-FILE mechanism, which is
-essentially just a variety of C<eval>. Has semantics similar to the
-following subroutine:
+Otherwise, C<require> demands that a library file be included if it
+hasn't already been included. The file is included via the do-FILE
+mechanism, which is essentially just a variety of C<eval>. Has
+semantics similar to the following subroutine:
sub require {
my ($filename) = @_;
For a yet-more-powerful import facility, see L</use> and L<perlmod>.
=item reset EXPR
+X<reset>
=item reset
See L</my>.
=item return EXPR
+X<return>
=item return
evaluated.)
=item reverse LIST
+X<reverse> X<rev> X<invert>
In list context, returns a list value consisting of the elements
of LIST in the opposite order. In scalar context, concatenates the
%by_name = reverse %by_address; # Invert the hash
=item rewinddir DIRHANDLE
+X<rewinddir>
Sets the current position to the beginning of the directory for the
C<readdir> routine on DIRHANDLE.
=item rindex STR,SUBSTR,POSITION
+X<rindex>
=item rindex STR,SUBSTR
last occurrence at or before that position.
=item rmdir FILENAME
+X<rmdir> X<rd> X<directory, remove>
=item rmdir
The substitution operator. See L<perlop>.
=item scalar EXPR
+X<scalar> X<context>
Forces EXPR to be interpreted in scalar context and returns the value
of EXPR.
See L<perlop> for more details on unary operators and the comma operator.
=item seek FILEHANDLE,POSITION,WHENCE
+X<seek> X<fseek> X<filehandle, position>
Sets FILEHANDLE's position, just like the C<fseek> call of C<stdio>.
FILEHANDLE may be an expression whose value gives the name of the
}
=item seekdir DIRHANDLE,POS
+X<seekdir>
Sets the current position for the C<readdir> routine on DIRHANDLE. POS
must be a value returned by C<telldir>. C<seekdir> also has the same caveats
routine.
=item select FILEHANDLE
+X<select> X<filehandle, default>
=item select
STDERR->autoflush(1);
=item select RBITS,WBITS,EBITS,TIMEOUT
+X<select>
This calls the select(2) system call with the bit masks specified, which
can be constructed using C<fileno> and C<vec>, along these lines:
is implementation-dependent. See also L<perlport> for notes on the
portability of C<select>.
-On error, C<select> returns C<undef> and sets C<$!>.
+On error, C<select> behaves like the select(2) system call : it returns
+-1 and sets C<$!>.
Note: on some Unixes, the select(2) system call may report a socket file
descriptor as "ready for reading", when actually no data is available,
then only on POSIX systems. You have to use C<sysread> instead.
=item semctl ID,SEMNUM,CMD,ARG
+X<semctl>
Calls the System V IPC function C<semctl>. You'll probably have to say
documentation.
=item semget KEY,NSEMS,FLAGS
+X<semget>
Calls the System V IPC function semget. Returns the semaphore id, or
the undefined value if there is an error. See also
documentation.
=item semop KEY,OPSTRING
+X<semop>
Calls the System V IPC function semop to perform semaphore operations
such as signalling and waiting. OPSTRING must be a packed array of
documentation.
=item send SOCKET,MSG,FLAGS,TO
+X<send>
=item send SOCKET,MSG,FLAGS
in that case pretty much any characters can be sent.
=item setpgrp PID,PGRP
+X<setpgrp> X<group>
Sets the current process group for the specified PID, C<0> for the current
process. Will produce a fatal error if used on a machine that doesn't
C<POSIX::setsid()>.
=item setpriority WHICH,WHO,PRIORITY
+X<setpriority> X<priority> X<nice> X<renice>
Sets the current priority for a process, a process group, or a user.
(See setpriority(2).) Will produce a fatal error if used on a machine
that doesn't implement setpriority(2).
=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
+X<setsockopt>
Sets the socket option requested. Returns undefined if there is an
error. OPTVAL may be specified as C<undef> if you don't want to pass an
argument.
=item shift ARRAY
+X<shift>
=item shift
right end.
=item shmctl ID,CMD,ARG
+X<shmctl>
Calls the System V IPC function shmctl. You'll probably have to say
See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
=item shmget KEY,SIZE,FLAGS
+X<shmget>
Calls the System V IPC function shmget. Returns the shared memory
segment id, or the undefined value if there is an error.
See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
=item shmread ID,VAR,POS,SIZE
+X<shmread>
+X<shmwrite>
=item shmwrite ID,STRING,POS,SIZE
C<IPC::SysV> documentation, and the C<IPC::Shareable> module from CPAN.
=item shutdown SOCKET,HOW
+X<shutdown>
Shuts down a socket connection in the manner indicated by HOW, which
has the same interpretation as in the system call of the same name.
processes.
=item sin EXPR
+X<sin> X<sine> X<asin> X<arcsine>
=item sin
sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
=item sleep EXPR
+X<sleep> X<pause>
=item sleep
See also the POSIX module's C<pause> function.
=item socket SOCKET,DOMAIN,TYPE,PROTOCOL
+X<socket>
Opens a socket of the specified kind and attaches it to filehandle
SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for
value of $^F. See L<perlvar/$^F>.
=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
+X<socketpair>
Creates an unnamed pair of sockets in the specified domain, of the
specified type. DOMAIN, TYPE, and PROTOCOL are specified the same as
sockets but not socketpair.
=item sort SUBNAME LIST
+X<sort> X<qsort> X<quicksort> X<mergesort>
=item sort BLOCK LIST
@result = sort { $a <=> $b } grep { $_ == $_ } @input;
=item splice ARRAY,OFFSET,LENGTH,LIST
+X<splice>
=item splice ARRAY,OFFSET,LENGTH
if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
=item split /PATTERN/,EXPR,LIMIT
+X<split>
=item split /PATTERN/,EXPR
# @fields is (1, 'A', 2, undef, 3)
=item sprintf FORMAT, LIST
+X<sprintf>
Returns a string formatted by the usual C<printf> conventions of the C
library function C<sprintf>. See below for more details
effect as the C<-> flag: left-justification.
=item precision, or maximum width
+X<precision>
You can specify a precision (for numeric conversions) or a maximum
width (for string conversions) by specifying a C<.> followed by a number.
See L<perllocale>.
=item sqrt EXPR
+X<sqrt> X<root> X<square root>
=item sqrt
print sqrt(-2); # prints 1.4142135623731i
=item srand EXPR
+X<srand> X<seed> X<randseed>
=item srand
one-third of the time. So don't do that.
=item stat FILEHANDLE
+X<stat> X<file, status>
=item stat EXPR
instead of the target file behind the link, use the C<lstat> function.
=item study SCALAR
+X<study>
=item study
}
=item sub NAME BLOCK
+X<sub>
=item sub NAME (PROTO) BLOCK
information about attributes.
=item substr EXPR,OFFSET,LENGTH,REPLACEMENT
+X<substr> X<substring> X<mid> X<left> X<right>
=item substr EXPR,OFFSET,LENGTH
unspecified.
=item symlink OLDFILE,NEWFILE
+X<symlink> X<link> X<symbolic link> X<link, symbolic>
Creates a new filename symbolically linked to the old filename.
Returns C<1> for success, C<0> otherwise. On systems that don't support
$symlink_exists = eval { symlink("",""); 1 };
=item syscall NUMBER, LIST
+X<syscall> X<system call>
Calls the system call specified as the first element of the list,
passing the remaining elements as arguments to the system call. If
problem by using C<pipe> instead.
=item sysopen FILEHANDLE,FILENAME,MODE
+X<sysopen>
=item sysopen FILEHANDLE,FILENAME,MODE,PERMS
Some of the most common values are C<O_RDONLY> for opening the file in
read-only mode, C<O_WRONLY> for opening the file in write-only mode,
and C<O_RDWR> for opening the file in read-write mode.
+X<O_RDONLY> X<O_RDWR> X<O_WRONLY>
For historical reasons, some values work on almost every system
supported by perl: zero means read-only, one means write-only, and two
the PERMS argument to C<sysopen>, Perl uses the octal value C<0666>.
These permission values need to be in octal, and are modified by your
process's current C<umask>.
+X<O_CREAT>
In many systems the C<O_EXCL> flag is available for opening files in
exclusive mode. This is B<not> locking: exclusiveness means here that
is set as well. Setting C<O_CREAT|O_EXCL> prevents the file from
being opened if it is a symbolic link. It does not protect against
symbolic links in the file's path.
+X<O_EXCL>
Sometimes you may want to truncate an already-existing file. This
can be done using the C<O_TRUNC> flag. The behavior of
C<O_TRUNC> with C<O_RDONLY> is undefined.
+X<O_TRUNC>
You should seldom if ever use C<0644> as argument to C<sysopen>, because
that takes away the user's option to have a more permissive umask.
See L<perlopentut> for a kinder, gentler explanation of opening files.
=item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
+X<sysread>
=item sysread FILEHANDLE,SCALAR,LENGTH
See L</binmode>, L</open>, and the C<open> pragma, L<open>.
=item sysseek FILEHANDLE,POSITION,WHENCE
+X<sysseek> X<lseek>
Sets FILEHANDLE's system position in bytes using the system call
lseek(2). FILEHANDLE may be an expression whose value gives the name
the new position.
=item system LIST
+X<system> X<shell>
=item system PROGRAM LIST
of C<IO::Handle> on any open handles.
The return value is the exit status of the program as returned by the
-C<wait> call. To get the actual exit value, shift right by eight (see below).
-See also L</exec>. This is I<not> what you want to use to capture
+C<wait> call. To get the actual exit value, shift right by eight (see
+below). See also L</exec>. This is I<not> what you want to use to capture
the output from a command, for that you should use merely backticks or
C<qx//>, as described in L<perlop/"`STRING`">. Return value of -1
-indicates a failure to start the program (inspect $! for the reason).
+indicates a failure to start the program or an error of the wait(2) system
+call (inspect $! for the reason).
Like C<exec>, C<system> allows you to lie to a program about its name if
you use the C<system PROGRAM LIST> syntax. Again, see L</exec>.
See L<perlop/"`STRING`"> and L</exec> for details.
=item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
+X<syswrite>
=item syswrite FILEHANDLE,SCALAR,LENGTH
See L</binmode>, L</open>, and the C<open> pragma, L<open>.
=item tell FILEHANDLE
+X<tell>
=item tell
Those functions ignore the buffering, while tell() does not.
=item telldir DIRHANDLE
+X<telldir>
Returns the current position of the C<readdir> routines on DIRHANDLE.
Value may be given to C<seekdir> to access a particular location in a
compaction as the corresponding system library routine.
=item tie VARIABLE,CLASSNAME,LIST
+X<tie>
This function binds a variable to a package class that will provide the
implementation for the variable. VARIABLE is the name of the variable
For further details see L<perltie>, L<"tied VARIABLE">.
=item tied VARIABLE
+X<tied>
Returns a reference to the object underlying VARIABLE (the same value
that was originally returned by the C<tie> call that bound the variable
package.
=item time
+X<time> X<epoch>
Returns the number of non-leap seconds since whatever time the system
considers to be the epoch, suitable for feeding to C<gmtime> and
See L<perlfaq8> for details.
=item times
+X<times>
Returns a four-element list giving the user and system times, in
seconds, for this process and the children of this process.
The transliteration operator. Same as C<y///>. See L<perlop>.
=item truncate FILEHANDLE,LENGTH
+X<truncate>
=item truncate EXPR,LENGTH
file.
=item uc EXPR
+X<uc> X<uppercase> X<toupper>
=item uc
If EXPR is omitted, uses C<$_>.
=item ucfirst EXPR
+X<ucfirst> X<uppercase>
=item ucfirst
If EXPR is omitted, uses C<$_>.
=item umask EXPR
+X<umask>
=item umask
string of octal digits. See also L</oct>, if all you have is a string.
=item undef EXPR
+X<undef> X<undefine>
=item undef
Note that this is a unary operator, not a list operator.
=item unlink LIST
+X<unlink> X<delete> X<remove> X<rm>
=item unlink
If LIST is omitted, uses C<$_>.
=item unpack TEMPLATE,EXPR
+X<unpack>
=item unpack TEMPLATE
See L</pack> for more examples and notes.
=item untie VARIABLE
+X<untie>
Breaks the binding between a variable and a package. (See C<tie>.)
Has no effect if the variable is not tied.
=item unshift ARRAY,LIST
+X<unshift>
Does the opposite of a C<shift>. Or the opposite of a C<push>,
depending on how you look at it. Prepends list to the front of the
reverse.
=item use Module VERSION LIST
+X<use> X<module> X<import>
=item use Module VERSION
functionality from the command-line.
=item utime LIST
+X<utime>
Changes the access and modification times on each file of a list of
files. The first two elements of the list must be the NUMERICAL access
described when they are both C<undef>. This case will also trigger an
uninitialized warning.
+On systems that support futimes, you might pass file handles among the
+files. On systems that don't support futimes, passing file handles
+produces a fatal error at run time.
+
=item values HASH
+X<values>
Returns a list consisting of all the values of the named hash.
(In a scalar context, returns the number of values.)
See also C<keys>, C<each>, and C<sort>.
=item vec EXPR,OFFSET,BITS
+X<vec> X<bit> X<bit vector>
Treats the string in EXPR as a bit vector made up of elements of
width BITS, and returns the value of the element specified by OFFSET
vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
=item wait
+X<wait>
Behaves like the wait(2) system call on your system: it waits for a child
process to terminate and returns the pid of the deceased process, or
being automatically reaped, as described in L<perlipc>.
=item waitpid PID,FLAGS
+X<waitpid>
Waits for a particular child process to terminate and returns the pid of
the deceased process, or C<-1> if there is no such child process. On some
and for other examples.
=item wantarray
+X<wantarray> X<context>
Returns true if the context of the currently executing subroutine or
C<eval> is looking for a list value. Returns false if the context is
This function should have been named wantlist() instead.
=item warn LIST
+X<warn> X<warning> X<STDERR>
Produces a message on STDERR just like C<die>, but doesn't exit or throw
an exception.
carp() and cluck() functions.
=item write FILEHANDLE
+X<write>
=item write EXPR