Functions


CONTENTS


Perl has a large number of functions that come as standard with most implementations, and an even wider range of additional modules, each with its own additional functions. This chapter lists all the standard functions alphabetically for reference.

Each function is assigned a category. There are two main categories; list operators, which can take more than one argument, and named unary operators, which can only take one argument. A secondary category is noted in parentheses so you can see, at a glance, the type of operation the function performs. This is a very rough categorization, as many functions might overlap in any category scheme.

For each function the form of the arguments is listed. If there are multiple forms of calling the function, there will be multiple lines describing each form. The meanings of the arguments are described in the text.

The type of value returned by the function is listed. This is usually specified in more detail in the function description.

Two categories of functions, those dealing with sockets and those dealing with System V interprocess communications, are not dealt with in great detail. Both of these categories of function are direct counterparts of UNIX system functions.

The chapter includes


-A

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  integer (age of file in days since last access relative to $BASETIME)

Definition

The file test operator takes one file handle or filename as an argument. It returns age of file in days since last access relative to $BASETIME. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

print "-A ", -A "/etc/fstab", "\n";

-B

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition1

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is binary. It returns '' (false) if the file is not binary. The first characters of the file are checked to see if the high bit is set and if a suitable number do have the high bit set the file is assumed to be binary. If the file is empty it is returned as binary. Because this test involves reading the file itself, it is best to test to learn if the file exists as a plain file (-f), first. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-B "/etc/fstab") ? print("-B fstab is binary\n") : 
       print("-B fstab is not binary\n");

-b

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is a block special file (that is, a UNIX /dev device file). It returns '' (false) if the file is not a block special file. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-b "/dev/hda1") ? print("-b hda1 is block\n") : 
print("-b hda1 is not block\n");

-C

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  integer (age of file in days since last
inode change relative to $BASETIME)

Definition

The file test operator takes one file handle or filename as an argument. It returns age of file in days since last inode change relative to $BASETIME. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

print "-C ", -C "/etc/fstab", "\n";

-c

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is a character special file. It returns '' (false) if the file is not a character special file. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-c "/dev/tty0") ? print("-c tty0 is char\n") : 
       print("-c tty0 is not char\n");

-d

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is a directory. It returns '' (false) if the file is not a directory. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-d "/") ? print("-d / is dir\n") : print("-d / is not dir\n");

-e

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if file exists. It returns '' (false) if the file does not exist. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-e "/") ? print("-e / exists\n") : print("-e / exists\n");

-f

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is a plain file. It returns '' (false) if the file is not a plain file. A plain file is any file that is not a special block device (-b), a special character device (-c), a directory (-d), a symbolic link (-l), a pipe (-p), a named socket (-S), or a direct link to an I/O terminal (-t). All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-f "/") ? print("-f / is plain\n") : print("-f / 
    is not plain\n");

-g

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file has the setgid bit set. It returns '' (false) if the file does not have the setgid bit set. In UNIX, setgid allows an executable to run as if it was being run by the group, which owns the executable itself while executing (for example, if a binary is owned by the group wwwstat, and the binary has the getgid bit set, then that binary has access to all files that the wwwstat group can access while the binary is running, even when the binary is run by someone who is not actually a member of the wwwstat group). All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-g "/vmlinuz") ? print("-g /vmlinuz has setgid\n") :
        print("-g /vmlinuz has not setgid\n");

-k

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the sticky bit is set. It returns '' (false) if the sticky bit is not set. In UNIX, the sticky bit can mark an executable file to be held in memory when exited (for example, if the binary ls is marked as sticky, when the first person runs it, it is loaded from disk to memory and executed, but when the execution finishes, the binary stays in memory so that when the next person runs ls it does not need to be loaded into memory again because it is already there). This is normally set for frequently used commands to optimize execution speed. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-k "/vmlinuz") ? print("-k /vmlinuz is sticky\n") : 
       print("-k /vmlinuz is not sticky\n");

-l

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is a symbolic link. It returns '' (false) if the file is not a symbolic link. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-l "/vmlinuz") ? print("-l /vmlinuz is symlink\n") : 
        print("-l /vmlinuz is not symlink\n");

-M

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  integer (age of file in days relative to $BASETIME)

Definition

The file test operator takes one file handle or filename as an argument. It returns the age of the file in days relative to $BASETIME. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

print "-M ", -M "/etc/fstab", "\n";

-O

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is owned by the real UID/GID and it returns '' (false) otherwise. For the superuser it always returns true. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-o "/vmlinuz") ? print("-o /vmlinuz is owned by 
   real uid/gid\n") : 
	print("-o /vmlinuz is not owned by real uid/
      gid\n");

-o

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. This function returns 1 (true) if the file is owned by the effective UID/GID and it returns '' (false) otherwise. For the superuser it always returns true. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-O "/vmlinuz") ? print("-O /vmlinuz is owned by 
   effective uid/gid\n") : 
       print("-o /vmlinuz is not owned by effective 
       uid/gid\n");

-p

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is a named pipe. It returns '' (false) if the file is not a named pipe. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-p "/vmlinuz") ? print("-p /vmlinuz is named 
   pipe\n") : 
       print("-p /vmlinuz is not named pipe\n");

-R

Compliance15

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is readable by the effective UID/GID and it returns '' (false) otherwise. For the superuser it always returns true. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-R "/vmlinuz") ? print("-R /vmlinuz is readable by 
     effective uid/gid\n") : 
     print("-R /vmlinuz is not readable by effective 
      uid/gid\n");

-r

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is readable by the real UID/GID and it returns '' (false) otherwise. For the superuser it always returns true. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-r "/vmlinuz") ? print("-r /vmlinuz is readable by 
   real uid/gid\n") : 
       print("-r /vmlinuz is not readable by real uid/
       gid\n");

-S

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is a symbolic link. It returns '' (false) if the file is not a symbolic link. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-S "/vmlinuz") ? print("-S /vmlinuz is socket\n") : 
       print("-S /vmlinuz is not socket\n");

-s

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  integer (size) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns size in bytes as an integer if the file has a non-zero size. It returns '' (false) if the file has zero size. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-s "/vmlinuz") ? print("-s /vmlinuz has non-zero 
    size\n") : 
       print("-s /vmlinuz does not have non-zero 
       size\n");

-T

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is a text file. It returns '' (false) if the file is not a text file. The first characters of the file are checked to see if the high bit is set, and if a suitable number are not set the file is assumed to be text. If the file is empty, true is returned. Because this test involves reading the file itself, it is best to test to learn if the file exists as a plain file (-f) first. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-T "/vmlinuz") ? print("-T /vmlinuz is text 
     file\n") : 
       print("-T /vmlinuz is not text file\n");

-t

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is a terminal tty device. It returns '' (false) if the file is not. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, STDIN is used.

Example

(-t "/vmlinuz") ? print("-t /vmlinuz is tty\n") : 
       print("-t /vmlinuz is not tty\n");

-u

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file has the setuid bit set. It returns '' (false) if the files does not have the setuid bit set. In UNIX, setuid allows an executable to take on the UID of the user ownership of the executable itself while executing. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-u "/vmlinuz") ? print("-u /vmlinuz has suid 
    set\n") : 
    print("-u /vmlinuz does not have suid set\n");

-W

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is writable by the real UID/GID.It returns '' (false) otherwise. For the superuser it always returns true. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-W "/vmlinuz") ? print("-W /vmlinuz is writable by 
    real uid/gid\n") : 
print("-W /vmlinuz is not writable by real UID/
       GID\n");

-w

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is writable by the effective UID/GID. It returns '' (false) otherwise. For the superuser it always returns true. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-w "/vmlinuz") ? print("-w /vmlinuz is writable by 
     effective uid/gid\n") :
        print("-l /vmlinuz is not writable by 
        effective uid/gid\n");

-X

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is executable by the real UID/GID. It returns '' (false) otherwise. For the superuser it always returns true. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-X _) ? print("-X /bin/ls is executable by real 
    uid/gid\n") : 
       print("-X /bin/ls is not executable by real 
       uid/gid\n");

-x

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file is executable by the effective UID/GID. It returns '' (false) otherwise. For the superuser it always returns true. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call. If no argument is supplied, $_ is used.

Example

(-x "/bin/ls") ? print("-x /bin/ls is executable by 
     effective uid/gid\n") : 
       print("-x /bin/ls is not executable by 
       effective uid/gid\n");

-z

Compliance

Syntax

Category  named unary operator (file test)
Arguments  handle
Arguments  filename
Arguments  none
Return Value  1 (true) '' (false)

Definition

The file test operator takes one file handle or filename as an argument. It returns 1 (true) if the file has zero size. It returns '' (false) otherwise. All file test operators can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat() or lstat() call. If no argument is supplied, $_ is used.

Example

(-z "/vmlinuz") ? print("-z /vmlinuz has zero size\n") : 
print("-z /vmlinuz does not have zero size\n");

abs

Compliance

Syntax

Category  named unary operator (numeric)
Arguments  numeric value
Return Value  numeric

Definition

This function returns the absolute value of its argument (it ignores
any sign).

Example

print("abs(-10) = ",abs(-10),"\n");

accept

Compliance

Syntax

Category  list operator (socket)
Arguments  newsocket, genericsocket
Return Value  integer (address of socket), '' (false)

Definition

This function performs low-level UNIX socket call accept().


Alarm

Compliance29

Syntax

Category  named unary operator (process)
Arguments  integer (seconds)
Return Value  integer (seconds to previous alarm)

Definition

This function sets up a UNIX SIGALRM signal to be generated in the number of seconds specified. It is possible for Perl to trap such signals by calling specific signal handling subroutines, such as trap(). Subseqent calls reset the alarm() time, retaining the number of seconds which were needed before the previous SIGALRM would have been generated. A call with zero seconds as an argument cancels the current alarm().

Example

print("alarm(10) ",alarm(10),
" (to illustrate it needs to trapped c.f. trap)\n");

atan2

Compliance

Syntax

Category  list operator (numeric)
Arguments  numeric, numeric
Return Value  numeric

Definition

The atan2 function returns the arctangent of the arguments.

Example

print("atan2(60,2) = ",atan2(60,2),"\n");

bind

Compliance

Syntax

Category  list operator (socket)
Arguments  sockethandle, numeric (network address)
Return Value  1 (true) '' (false)

Definition

This function binds a network address to the socket handle, see the UNIX bind() call.


Binmode

Compliance

Syntax

Category  named unary operator (i/o)
Arguments  handle
Return Value  1 (success) or undefined (error)

Definition

On systems that distinguish between text and binary files, this function forces binary mode treatment of the given file handle. In systems which do make the distinction, text files have the end of line characters (Carriage Return, Linefeed) automatically translated to the UNIX end of line character (Linefeed) when reading from the file (and vice versa when writing to the file); binary mode files do not have this automatic transformation.

Example

open(FIL,"file.dat");
binmode(FIL);

bless

Compliance

Syntax

Category  list operator (class)
Arguments  variable
Arguments  variable, classname
Return Value  reference

Definition

This function assigns a class to the referenced object. This class is either explicitly stated in the call, or the name of the current package is used if a second argument is not used in the call. The reference is returned.

Tip
Explictly state the class (use the two argument version of the call) if the code can be inherited by other classes because the class in the single argument call would not return the required value.

Example

$tmp = {};
bless $tmp, ATMPCLASS;
print "bless() \$tmp is now in class ",ref($tmp),"\n";

caller

Compliance

Syntax

Category  named unary operator (scope)
Arguments  expression
Arguments  none
Return Value  1 (true) '' (false)
Return Value  (package, filename, line)

Definition

This function is used to test the current scope of a subroutine call. If evaluated in a scalar context, it returns 1 or '' depending on if the current code has been called as a subroutine (this includes code which is included using a require() or an eval() call). In an array context it supplies details of the calling context in a list comprising the package name, filename, and line of the call.

Example

sub testcaller {
    ($package, $file, $line) = caller;
}
&testcaller;
print "caller() Package=$package File=$file Line=$line \n";

chdir

Compliance

Syntax

Category  named unary operator (files)
Arguments  expression
Arguments  none
Return Value  1 (true) '' (false)

Definition

This function changes the current directory to the directory specified. If no argument is given this call changes the current directory to be the home directory of the current user. It returns 1 upon success and '' otherwise.

Example

chdir("/") ? print("It worked.\n") : print("It 
    didn't work.\n");

chmod

Compliance

Syntax

Category  list operator (files)
Arguments  list
Return Value  numeric

Definition

The first element in the list is the UNIX octal number representing the file permission. This function applies the mode specified by the octal number to all the files in the list that follows. It returns the number of files successfully modified.

Example

print "chmod() changed ",
chmod(0744,"/tmp/test1.txt","/tmp/test2.txt")," 
     files.\n";

chomp

Compliance

Syntax

Category  list operator (string)
Arguments  list
Arguments  variable
Arguments  none
Return Value  numeric

Definition

This is an alternative to the chop() function. It removes characters at the end of strings corresponding to the $INPUT_LINE_SEPARATOR ($/). It returns the number of characters removed. It can be given a list of strings upon which to perform this operation. When given no arguments, the operation is performed on $_.

Example

$tmp="Aaagh!\n";
$ret = chomp $tmp;
print("chomp() ", $tmp, " returned ", $ret, "\n");

chop

Compliance

Syntax

Category  list operator (string)
Arguments  list
Arguments  variable
Arguments  none
Return Value  character

Definition

This function removes the last character of a string and returns that character. If given a list of arguments, the operation is performed on each one and the last character chopped is returned.

Example

$tmp = "1234";
$ret = chop $tmp;
print("chop() ", $tmp, " returned ", $ret, "\n");

Tip
Use chomp() (with $/ set to "\n") rather than chop() if you are unsure that the string has a trailing newline because chop() will remove the last character regardless, but chomp() only removes it if it is a newline.


Chown

Compliance

Syntax

Category  list operator (files)
Arguments  list
Return Value  numeric

Definition

This function changes the ownership of the specified files. The first two elements of the list define the user ID and the group ID to set this ownership; the subsequent items in the list are the file names that are changed. The return value is the number of files successfully changed.

Example

print("chown() "); 
chown(1,1,"/tmp/test1.txt") ? print("Worked\n") : print("Didn't work\n");

chr

Compliance

Syntax

Category  named unary operator (string)
Arguments  numeric
Return Value  character

Definition

This function returns the character indicated by the numeric
argument.

Example

$E = chr(69);
print("chr() $E \n");

chroot

Compliance

Syntax

Category  named unary operator (files)
Arguments  directoryname
Arguments  none
Return Value  1 (true) '' (false)

Definition

This function is equivalent to the UNIX chroot() function. Given a directoryname, this directory is treated as the root directory by all subsequent file system references, thus effectively hiding the rest of the file system outside the specified directory. This restriction applies to all subprocesses of the current process as well.

Tip
Normal UNIX security limits this function to the superuser, and it is normally used to make processes safer by only allowing them access to the subdirectory tree relevant to their purpose.

Example

print("chroot() ");
chroot("/") ? print("Worked.\n") : print("Didn't 
      work.\n");

close

Compliance

Syntax

Category  named unary operator (files)
Arguments  handle
Return Value  1 (true) '' (false)

Definition

This function closes the file opened with the file handle. This operation flushes all buffered output. If the file handle refers to a pipe, the Perl program waits until the process being piped has finished.

Example

open(INF,"/tmp/test1.txt");
$ret = close(INF);
print("close() Returned ",$ret," on success\n");

closedir

Compliance

Syntax

Category  named unary operator (file)
Arguments  handle
Return Value  1 (true) '' (false)

Definition

This function closes the directory opened by opendir() by specifying the relevant directory handle.

Example

opendir(IND,"/tmp");
$ret = closedir(IND);
print("closedir() Returned ",$ret," on success\n");

connect

Compliance

Syntax

Category  list operator (socket)
Arguments  socket, name
Return Value  1 (true) '' (false)

Definition

This function is equivalent to the UNIX function call, which initiates a connection with a process, assuming that the process that is connected is waiting to accept.


Continue

Compliance

Syntax

Category  flow control
Arguments  block
Return Value  N/A

Definition45

A continue block is a syntax structure that allows a condition to be attached to another block (normally a while block). Any statements in the continue block are evaluated before the attached block is repeated.

Example

$i=0;
print "continue() ";
while ($i<10) {
      if ($i % 2)
         { print "${i}o "; next; }
      else
         {print "${i}e ";}
} continue {$i++}
print "\n";

cos

Compliance46

Syntax

Category  named unary operator (numeric)
Arguments  expression
Return Value  numeric

Definition

This function returns the cosine value of the numeric expression supplied as an argument.

Example

print "cos() ",cos(60),"\n";

crypt

Compliance

Syntax

Category  list operator
Arguments  string, string
Return Value  string

Definition

This function is equivalent to the crypt() UNIX call (where available). It encrypts a string (the first argument) using a key (usually the first two letters of the first string itself) and returns the encrypted string.

Example

print "crypt() Password PA: ",crypt("Password","PA"),"\n";

dbmclose

Compliance

Syntax

Category  named unary operator (i/o)
Arguments  arrayname
Return Value  1 (true) '' (false)

Definition

This function undoes the linking of an associative array to a DBM file (see dbmopen()).

Note
This is depreciated in Perl 5, use untie() instead.


Dbmopen

Compliance

Syntax

Category  list operator (i/o)
Arguments  arrayname, dbname, mode
Return Value  fatal error if dbm not supported 
(Perl 4)

Definition

This function links the associative array referred to by arrayname, to the DBM database (or equivalent) referred to by dbname (this name should not include the suffix). If the database does not exist, a new one with the specified mode will be opened (the mode being an octal chmod() style file protection).

Note
This is depreciated in Perl 5, use tie() instead.


Defined

Compliance

Syntax

Category  named unary operator (misc)
Arguments  expression
Return Value  1 (true) '' (false)

Definition

This function returns a Boolean value depending on whether the argument is defined or not. There is a subtle distinction between an undefined and a defined null value. Some functions return undefined null to indicate errors, while others return a defined null to indicate a particular result (use a comparison with the null string to test for this, rather than using defined())

Example

@iexist = (1,2,3);
print("defined() The array \@iexist ");
defined @iexist ? print("exists.\n") : print("does 
       not exist.\n");

delete

Compliance

Syntax

Category  named unary operator (hash)
Arguments  expression
Return Value  value

Definition51

Use this function to delete an element from a hash array, given the key for the element to delete, returning the value of the deleted element.

Example

%Hash = (1, One, 2, Two, 3, Three);
print("delete() Deleted ",delete($Hash{1}),"\n");

die

Compliance

Syntax

Category  list operator (i/o)
Arguments  list

Return Value  errorlevel

Definition

This function terminates execution of the Perl script when called printing the value of the list argument to STDERR (as if called with print(STDERR, list)). The exit value is the current value of $OS_ERROR ($!), which may have been set by a previous function. If this has a value of zero it returns $CHILD_ERROR ($?). If this is zero, it exits with errorlevel 255. If the error message string specified by the list does not end in a newline, the text "at $PROGRAM_NAME at line line, where line is the line number of the Perl script.

Example

die("die() Now we can give an example of 
 die()...exiting");

do

Compliance

Syntax

Category  (flow)
Arguments  block
Arguments  subroutine(list)
Arguments  expression
Return Value  special

Definition

This is a syntax structure that allows repeated execution of a block of statements. The value returned is the result of the last statement in the block. Normally an exit condition is supplied after the block. The second form where the argument is subroutine() is a depreciated form. The third form executes the contents of the file name specified by the expression (but it is better to use use() or require() instead, because this has better error checking).

Example

$i=1;
print("do ");
$return = do {
  print $i, " ";
  $i++;
} until $i==3;
print("Returned $return\n");

dump

Compliance

Syntax

Category  named unary operator (misc)
Arguments  label
Return Value  N/A

Definition

This function causes the program to create a binary image core dump. This then allows the dumped image to be reloaded using the undump() function (if supported) which can effectively allow the use of precompiled Perl images. When reloaded, the program begins execution from the label specified. It is possible to set up a program which initializes data structures to dump() after the initialization so that execution is faster when reloading the dumped image.


Each

Compliance

Syntax

Category  named unary operator (hash)
Arguments  variable
Return Value  key, value

Definition

This function allows iteration over the elements in an associative array. Each time it is evaluated, it returns another list of two elements (a key, value pair from the associative array). When all the elements have been returned, it returns a null list.

Example

%NumberWord = (1, One, 2, Two, 3, Three);
print("each() ");
while (($number,$wordform)=each(%NumberWord)) {
  print("$number:$wordform ");
}
print("\n");

endgrent

Compliance

Syntax

Category  (system files)
Arguments  none
Return Value  1 (true) '' (false)

Definition

This function closes the /etc/group file used by getgrent() and other group related functions. It is equivalent to the UNIX system call.

Example

($name,$pw,$gid,@members)=getgrent();
$returned = endgrent();
print("endgrent() Closes /etc/group [$name,$gid]",
       " file returning $returned.\n");

endhostent

Compliance

Syntax

Category  (system files)
Arguments  none
Return Value  1 (true) '' (false)

Definition

This function closes the TCP socket used by name server queries gethostbyname() and host related functions. It is equivalent to the UNIX system call.

Example

$host = gethostbyname("lynch");
$returned = endhostent();
print("endhostent() Closes /etc/hosts [$host]",
       " returning $returned.\n");

endnetent

Compliance

Syntax

Category  (system files)
Arguments  none
Return Value  1 (true) '' (false)

Definition

This function closes the /etc/networks file used by getnetent() and network related functions. This function is equivalent to the UNIX system call.

Example

($name,$alias,$net,$net) = getnetent();
$returned = endnetent();
print("endnetent() Closes /etc/networks [$name]",
       " returning $returned.\n");

endprotoent

Compliance

Syntax

Category  (system files)
Arguments  none
Return Value  1 (true) '' (false)

Definition

This function closes the /etc/protocols file used by getprotoent() and protocol related functions. It is equivalent
to the UNIX system call.

Example

($name, $alias, $protocol) = getprotoent();
$returned = endprotoent();
print("endprotoent() Closes /etc/protocols ",
"[$name,$alias,$protocol] file returning $returned.\n");

endpwent

Compliance

Syntax

Category  (system files)
Arguments  none
Return Value  1 (true) '' (false)

Definition

This function closes the /etc/passwd file used by getpwent() and password related functions. It is equivalent to the UNIX system call.

Example

($name,$pass,$uid,$gid,$quota,$name,$gcos,$logindir,$shell) 
      = getpwent();
$returned = endpwent();
print("endpwent() Closes /etc/passwd [$logindir,$shell] ",
"file returning $returned.\n");

endservent

Compliance

Syntax

Category  (system files)
Arguments  none
Return Value  1 (true) '' (false)

Definition

This function closes the /etc/servers file used by getservent() and related functions. It is equivalent to the UNIX system call.

Example

($name,$aliases,$port,$protocol) = getservent();
$returned = endservent();
print("endservent() Closes /etc/servers [$name]",
" file returning $returned.\n");

eof

Compliance

Syntax62

Category  named unary operator (i/o)
Arguments  handle
Arguments  ()
Arguments  none
Return Value  1 (true) '' (false)

Definition

This function tests if the file pointer to file specified by the file handle is at the and of the file. This is done by reading the next character and then undoing this operation (so is only suitable on files where this can be done safely). If no argument is supplied the file tested is the last file that was read. If the empty list is supplied then this tests if all the last file suppiled an argument to the Perl script are eof() (that is, it can be used as a termination condition in a while loop).

Example

open INF, "/tmp/test1.txt";
if (eof INF) 
  {print "eof() TRUE\n";}
else
  {print "eof() FALSE\n";}
close INF;

eval

Compliance

Syntax

Category  named unary operator (flow)
Arguments  expression
Arguments  block
Arguments  none
Return Value  special

Definition

This function treats the expression like a Perl program and executes it returning the return value of the last statement executed. As the context of this execution is the same as that of the script itself, variable definitions and subroutine definitions persist. Syntax errors and runtime errors (including die()) are trapped and an undefined result is returned. If such an error does occur, $EVAL_ERROR ($@) is set. If no errors are found, $@ is equal to a defined null string. If no expression is supplied, $_ is the default argument. If the block syntax is used, the expressions in the block are evaluated only once within the script, which may be more efficient for certain situations.

Tip
eval() traps possible error conditions that would otherwise crash a program. Therefore, it can be used to test if certain features are available that would cause runtime errors if used when not available.

Example

$ans = 3;
eval "$ans = ;";
if ($@ eq "")
  {print "eval() returned success.\n";}
else
  {print "eval() error: $@";}

exec

Compliance

Syntax

Category  list operator (process)
Arguments  list
Return Value  N/A

Definition

This function passes control from the script to an external system command. There is no retain from this call so there is no return value. Note that system() calls external commands and does return to the next line in the calling Perl program.

This is equivalent to the UNIX system call execvp().

Example

exec("cat /etc/motd");

exists

Compliance

Syntax

Category  named unary operator (hash)
Arguments  expression
Return Value  1 (true) '' (false)

Definition

This function tests if a given key value exists in an associative array, returning a Boolean value.

Example

%test = ( One, 1, Two, 2);
if (exists $test{One}) 
  {print "exists() returned success.\n";}
else
  {print "exists() returned an error.\n";}

exit

Compliance

Syntax

Category  named unary operator (flow)
Arguments  expression
Arguments  none
Return Value  value

Definition

This function evaluates the expression given as an argument and exits the program with that error. The default value for the error is 0 if no argument is supplied. Note that die() allows an error message.

Example

exit(16);

exp

Compliance

Syntax

Category  named unary operator (numeric)
Arguments  expression
Arguments  none
Return Value  numeric

Definition

This function returns the natural log base (e) to the power of expression (or of $_ if none specified).

Example

print "exp() e**1 is ",exp(1),"\n";

fcntl

Compliance

Syntax

Category  list operator (i/o)
Arguments  handle, function, packed_parameters

Definition

This function is equivalent to the UNIX fnctl() call. In Perl 5, use the fntcl module. In Perl 4, there should be some mechanism for linking the Perl functions to the system functions. This is usually executed when Perl is installed.


Fileno

Compliance

Syntax

Category  named unary operator (i/o)
Arguments  handle
Return Value  descriptor

Definition

This function returns the file descriptor given a file handle.

Example

print("fileno() ",fileno(INF),"\n");

flock

Compliance

Syntax

Category  list operator (i/o)
Arguments  handle, operation
Return Value  1 (true) '' (false)

Definition

This calls the UNIX flock() function to access file locks. The handle is a Perl file handle. The operation is any valid flock() operation: place exclusive lock, place shared lock, and unlock. These operations are represented by numeric values.


Fork

Compliance

Syntax

Category  (process)
Arguments  none
Return Value  pid

Definition

The fork function calls the UNIX fork() function or equivalent to fork a subprocess at this point. Returns the process ID (pid) of the child process to the calling process; returns 0 to the child process itself. The calling program should wait() on any child process it forks to avoid creating zombie processes.

Example

$pid = fork;
# Child only prints this
if ($pid != 0) { 
  print("fork() Forking a process duplicates o/p: $pid \n");
}
waitpid($pid,0);
# Child exits here
if ($$ != $origpid) { die; }

format

Compliance

Syntax

Category  list operator (i/o)
Arguments  format

Definition

This function declares an output format specification. These formats are used in conjunction with the write() function to control the output of variables and text to conform to a standard layout structure. Normally, the specification includes some variables, specifying how many characters to output and whether to justify these left, right or centered. When write() is called, the actual values of the variables are used. This is useful for printing simple text reports and tables. The format specification itself is terminated by a period on a line by itself. The specification itself is in pairs of lines, the first describing the layout, and the second describing the variables to use in this layout.

Example

format STDOUT =
format() @>>>>>>> @>>>>>>> @>>>>>>>
         $t1,     $t2,      $t3
.
$t1 = One;
$t2 = Two;
$t3 = 3;
write;

formline

Compliance

Syntax

Category  list operator (i/o)
Arguments  picture, list

Definition

This function is not usually called explictly (it is an implicit part of the format mechanism). It allows direct manipulation of the format process by adding values to the format accumulator ($^A).

Example

$tmp = formline <<'FINISH', Alpha, Beta, Gamma;
formline()  @>>>>>> @>>>>>> @>>>>>>
FINISH
print $^A;

getc

Compliance

Syntax

Category  named unary operator (i/o)
Arguments  handle
Arguments  none
Return Value  character

Definition

This function returns the next character in specified file handle. The file defaults to STDIN if none is specified. If there are no more characters, null is returned.

Example

open INF, "/etc/motd";
print "getc() ",getc(INF),"\n";
close INF;

getgrent

Compliance

Syntax

Category  list operator (system files)
Arguments  none
Return Value  name

Definition

This returns the next group name (or undefined) in the /etc/group system file. In a list context, it returns extra information taken from this file (or null list). This function is equivalent to the UNIX system call getgrent().

Example

($name,$pw,$gid,@members)=getgrent();
print("getgrent() Examines /etc/group [$name,$gid] file.\n");

getgrgid

Compliance

Syntax

Category  named unary operator (system files)
Arguments  gid
Return Value  name

Definition

This function returns the next group name (or undefined) in the /etc/group system file with the supplied group ID (gid). In a list context, it returns extra information taken from this file (or null list). Equivalent to the UNIX system call getgrgid().

Example

($grname,$grpw,$gid,@members) = getgrgid(0);
print("getgrgid() Returns group name given GID [$grname]\n");

getgrname

Compliance

Syntax

Category  named unary operator (system files)
Arguments  name
Return Value  gid

Definition

This function returns the next group ID, gid, (or undefined) in the /etc/group system file with the supplied group name. In a list context, it returns extra information taken from this file (or null list). It is equivalent to the UNIX system call getgrname().

Example

($grname,$grpw,$gid,@members) = getgrnam("root");
print("getgrnam() Returns group GID given name [$gid]\n");

gethostbyaddr

Compliance

Syntax

Category  named unary operator (system files)
Arguments  address
Return Value  name

Definition

It returns the host name, (or undefined) in the /etc/hosts system file (or via a Domain Name Server lookup) with the supplied host address. In a list context, The function returns extra information taken from this file (or null list). It is equivalent to the UNIX system call gethostbyaddr().

Example (Perl 5 only)

use Socket;
@a=(140,203,7,103);
$addr=pack('C4',@a);
($name,$alias,$adrtype,$length,@address)=gethostbyaddr($addr,AF_INET);
print("gethostbyaddr() [$alias].\n");

gethostbyname

Compliance

Syntax

Category  named unary operator (system files)
Arguments  name
Return Value  address

Definition

This function returns the host address, (or undefined) in the /etc/hosts system file (or via a Domain Name Server lookup) with the supplied host name. In a list context, it returns extra information taken from this file (or null list). This function is equivalent to the UNIX system call gethostbyname().

Example

($name,$alias,$adrtype,$length,@address)=gethostbyname("lynch");
print("gethostbyname() [$alias].\n");

gethostent

Compliance

Syntax

Category  (system files)
Arguments  none
Return Value  name

Definition

gethostent returns the next host name, (or undefined) in the /etc/hosts system file (or via a Domain Name Server lookup). In a list context, it returns extra information taken from this file (or null list). This function is equivalent to the UNIX system call gethostent().

Example

($name,$alias,$adrtype,$length,@address)=gethostbyname("lynch");
print("gethostent() [$alias].\n");

getlogin

Compliance

Syntax

Category  (system files)
Arguments  none
Return Value  name

Definition

This function returns the current login name from the /etc/utmp system file.

Example

print ("getlogin() ",getlogin(),"\n");

getnetbyaddr

Compliance

Syntax

Category  (system files)
Arguments  address
Return Value  name

Definition

getnetbyaddr returns the network name from the /etc/networks system file given a network address. In a list context, it returns extra information from this file. This function is equivalent to UNIX's getnetbyaddr() call.

Example

($name,$alias,$addrtype,$net) = getnetent();
($name,$alias,$addrtype,$net) = getnetbyaddr($net,$addrtype);
print("getnetbyaddr() Reads /etc/networks [$name]\n");

getnetbyname

Compliance

Syntax

Category  named unary operator (system files)
Arguments  name
Return Value  address

Definition

Returns the network address from the /etc/networks system file, given a network name. In a list context returns extra information from this file. Equivalent to the UNIX getnetbyname() call.

Example

($name,$alias,$addrtype,$net) = getnetbyname("localnet");
print("getnetbyname() Reads /etc/networks [$name]\n");

getnetent

Compliance

Syntax

Category  (system files)
Arguments  none
Return Value  name

Definition

This function returns the next network name from the /etc/networks system file. In a list context, it returns extra information from this file. getnetent is equivalent to the UNIX getnetent() call.

Example

($name,$alias,$addrtype,$net) = getnetent();
print("getnetent() Reads /etc/networks [$name,$addrtype]\n");

getpeername

Compliance

Syntax

Category  named unary operator (socket)
Arguments  socket
Return Value  name

Definition

getpeername is equivalent to the UNIX system getpeername() system call.


getpgrp

Compliance

Syntax

Category  named unary operator (process)
Arguments  pid
Return Value  gid

Definition

This function returns the group ID (gid) of the process with the process ID (pid).

Example

print("getpgrp() ",getpgrp(0),"\n");

getppid

Compliance

Syntax

Category  (process)
Arguments  none
Return Value  pid

Definition

getppid returns the process ID (pid) of the parent process of the current process.

Example

print("getppid() ",getppid(),"\n");

getpriority

Compliance

Syntax

Category  list operator (process)
Arguments  type, id
Return Value  priority

Definition

This function calls the UNIX getpriority() function. The type is one of PRIO_PROCESS, PRIO_PGGRP, and PRIO_USER. The id is the relevant ID for this (pid for PRIO_PROCESS, pid for PRIO_PGGRP, uid for PRIO_USER). If zero is used as the id, the current process, process group, or user is used.

Example

print("getpriority() ",getpriority(0,0),"\n");

getprotobyname

Compliance

Syntax

Category  named unary operator (system files)
Arguments  name
Return Value  protocol

Definition

This function returns the protocol number from the /etc/protocols system file, given the protocol name. In a list context, it returns extra information from this file. getprotobyname is equivalent to the UNIX getprotobyname() call.

Example

($name, $alias, $protocol) = getprotobyname("IP");
print("getprotobyname() /etc/protocols [$name,$alias,$protocol].\n");

getprotobynumber

Compliance

Syntax

Category  named unary operator (system files)
Arguments  protocol
Return Value  name

Definition

This function returns the protocol name from the /etc/protocols system file, given the protocol number. In a list context, it returns extra information from this file. getprotobynumber is equivalent to the UNIX getprotobynumber() call.

Example

($name, $alias, $protocol) = getprotobynumber(0);
print("getprotobynumber() /etc/protocols [$name,$alias,$protocol].\n");

getprotoent

Compliance

Syntax

Category  (system files)
Arguments  none
Return Value  name

Definition

This returns the next protocol name from the /etc/protocols system file. In a list context, it returns extra information from this file. This function is equivalent to UNIX's getprotoent() call.

Example

($name, $alias, $protocol) = getprotoent();
print("getprotoent() Closes /etc/protocols [$name,$alias,$protocol].\n");

getpwent

Compliance

Syntax

Category  (system files)
Arguments  none
Return Value  name

Definition

getpwent returns the user name from the next entry in the /etc/passwd system file. In a list context, it returns extra information from this file. This function is equivalent to the UNIX getpwent() call.

Example

($name,$pass,$uid,$gid,$quota,$name,$gcos,$logindir,$shell) = getpwent();
print("getpwent() /etc/passwd [$logindir,$shell].\n");

getpwnam

Compliance

Syntax

Category  named unary operator (system files)
Arguments  name
Return Value  uid

Definition

This function returns the user ID (uid) from the /etc/passwd system file given the user name. In a list context, it returns extra information from this file. It is equivalent to the UNIX getpwnam() call.

Example

($name,$pass,$uid,$gid,$quota,$name,$gcos,$logindir,$shell) 
= getpwnam("root");
print("getpwnam() /etc/passwd [$logindir,$shell].\n");

getpwuid

Compliance

Syntax

Category  named unary operator (system files)
Arguments  uid
Return Value  name

Definition

getpwiud returns the user name from the /etc/passwd system file given the user ID (uid). In a list context, getpwuid returns extra information from this file. This function is equivalent to the UNIX getpwnam() call.

Example

($name,$pass,$uid,$gid,$quota,$name,$gcos,$logindir,$shell) 
= getpwuid(0);
print("getpwuid() /etc/passwd [$logindir,$shell].\n");

getservbyname

Compliance

Syntax

Category  list operator (system files)
Arguments  name, protocol
Return Value  port

Definition

getservbyname returns the port number of the service from the /etc/services system file given the service name and the protocol name. In a list context, it returns extra information from this file. This function is equivalent to UNIX's getservbyname() call.

Example

($name,$aliases,$port,$protocol) = getservbyname("tcpmux","tcp");
print("getservbyname() /etc/servers [$name].\n");

getservbyport

Compliance

Syntax

Category  list operator (system files)
Arguments  port, protocol
Return Value  name

Definition

getservbyport returns the service name of the service from the /etc/services system file given the port number and the protocol name. In a list context, it returns extra information from this file. It is equivalent to the UNIX getservbyport() call.

Example

($name,$aliases,$port,$protocol) = getservbyport(512,"tcp");
print("getservbyport() Problem with this! [$name]\n");

getservent

Compliance

Syntax

Category  (system files)
Arguments  none
Return Value  name

Definition

This function returns the next service name of the service from the /etc/services system file. In a list context, it returns extra information from this file. It is equivalent to the UNIX getservet() call.

Example

($name,$aliases,$port,$protocol) = getservent();
print("getservent() /etc/servers [$name].\n");

getsockname

Compliance

Syntax

Category  named unary operator (socket)
Arguments  socket
Return Value  address

Definition

This function returns the address of the socket.


getsockopt

Compliance

Syntax

Category  list operator (socket)
Arguments  socket, level, optionname
Return Value  option

Definition

This function is equivalent to the UNIX getsockopt() system call and returns the socket option requested. However, if an error has happened, the function's return is undefined.


glob

Compliance

Syntax

Category  named unary operator (files)
Arguments  expression
Return Value  list

Definition

This function returns the list of files resulting from expanding the expression with any wildcards. This is equivalent to <*.*>.

Example

@files = glob("/tmp/*.txt");
print "glob() ",$files[1],"\n";

gmtime

Compliance

Syntax

Category  named unary operator (time)
Arguments  expression
Arguments  none
Return Value  list

Definition

Given a time as an argument (measured in seconds since 1 Jan. 1970), gmtime returns a list of nine elements with that time broken down into seconds, minutes, hours, day of month, month, year, day of week, day of year, daylight saving enabled (daylight saving enabled is either 1 for on or 0 for off). If no argument is used, the current time is reported. If the system supports POSIX time zones, the time returned is localized for the Greenwich Mean Time.

In a scalar context, the ctime() style output (a string describing the time in readable form) is returned.

Example

($sec,$min,$hour,$mday,$mon,$year,$wday,$ydat,$isdst) = gmtime();
print "gmtime() 19$year-$mon-$mday\n";

goto

Compliance

Syntax

Category  (flow)
Arguments  label
Arguments  expression
Arguments  &name
Return Value  N/A

Definition

The first form transfers control flow in the program to the specified label. The second allows the evaluation of an expression to supply the label name to transfer control to. The third form is a way of passing control from one subroutine to another subroutine so that, to the original caller, it appears that the second subroutine was called directly.

Example

print "goto ";
$count = 1;
TESTGOTO: {
   print $count, " ";
   $label = "TESTGOTO";
   if ($count < 2) {
          $count++;
       goto $label;
   }
   else {
       goto FINISH;}
}
FINISH: print "\n";

grep

Compliance

Syntax

Category  list operator (lists)
Arguments  expression, list
Arguments  block, list
Return Value  list

Definition

This function evaluates the expression or block for each of the elements in the supplied list, returning a list of the elements that were evaulated as true. The most common use for this is with a pattern match operation as the expression, and a list of strings to be processed.

Example

@a = ("One","Two","Three","Four","Five");
print("grep(), ",grep(/^T.*/,@a), "\n");

hex

Compliance

Syntax

Category  named unary operator (numeric)
Arguments  expression
Return Value  numeric

Definition

This function evaluates the expression as a hexadecimal string and returns the decimal equivalent.

Example

print("hex() ",hex("ff"), "\n");

import

Compliance

Syntax

Category  list operator (scope)
Arguments  list
Return Value  1 (true) '' (false)

Definition

In the Perl 5 module system, each module has a local import() method. This is called when use() includes modules.


index

Compliance

Syntax

Category  list operator (string)
Arguments  string substring
Arguments  string substring position
Return Value  position

Definition

index returns the position in the supplied string where the substring first occurs. If a position is supplied as an argument, the search begins at this element (thus repeated calls can find all occurrences if the found position is passed back as the argument to the subsequent calls). If the substring is not found, the return value is -1. All array element numbers are based on $[, which is normally set to zero. If this value is altered it will change the way index() works. This is because index will start its search from $[ if no position argument is supplied, and it will return $[-1 when there is no match found.

Example

$ans1 = index("abcdefghijiklmdef:-)","def");
$ans2 = index("abcdefghijiklmdef","def",$ans1+3);
print("index() def is at $ans1 and next at $ans2\n");

int

Compliance

Syntax

Category  named unary operator (numeric)
Arguments  expression
Arguments  none
Return Value  integer

Definition

This function returns the integer part of the expression. It uses $_ as the argument if none is specified.

Example

print("int() ",int(345.678), "\n");

ioctl

Compliance

Syntax

Category  list operator (files)
Arguments  handle, function, parameter
Return Value  numeric

Definition

This function calls the UNIX ioctl() function with the specified packed parameter. It returns undefined if the operating system returns -1. It returns the string 0 but true if the operating system returns 0. Otherwise, it returns the value returned by the operating system.


join

Compliance

Syntax

Category  list operator (lists)
Arguments  expression, list
Return Value  string

Definition

This function returns the string comprising each element in the list joined with the string expression.

Example

@listone = (0, 1, 2, 3);
print("join() ",join("-",@listone),"\n");

keys

Compliance

Syntax

Category  named unary operator (hash)
Arguments  array
Return Value  list

Definition

This function returns a list comprising each key in the associative array passed as a parameter. In a scalar context, the number of keys is returned. The returned list is ordered by the internal storage requirements, so it is often useful to sort this array before processing.

Example

%assocone = (
One, 1,
Two, 2,
Three, 3,
Four, 4
);
print("keys() ",join("-",keys(%assocone)),"\n");

kill

Compliance

Syntax

Category  list operator (process)
Arguments  signal, list
Return Value  1 (true) '' (false)

Definition

This function kills the processes with the PIDs in the supplied list by sending the signal level specified. If the signal level is negative, the process groups are killed.


last

Compliance

Syntax

Category  (flow)
Arguments  label
Arguments  none
Return Value  N/A

Definition

This causes control to exit the loop specified by label (or the innermost loop if none is specified).

Example

i=1;
print("last() ");
loop: while (I<10) {
last loop if i=3;
print(i);
}
print("\n");

lc

Compliance

Syntax

Category  named unary operator (string)
Arguments  expression
Return Value  string

Definition

This function returns the lowercase version of any supplied expression.

Example

print"lc() ",lc("ABCDef"), "\n";

lcfirst

Compliance

Syntax

Category  named unary operator (string)
Arguments  expression
Return Value  string

Definition

This function returns the string with the first character of the expression lowercased.

Example

print"lcfirst() ",lcfisrt("ABCDef"), "\n";

length

Compliance

Syntax

Category  named unary operator (string)
Arguments  expression
Arguments  none
Return Value  numeric

Definition

length returns the length of the string specified by expression. If no expression is supplied, $_ is evaluated.

Example

print("length() ",length("01234"),"\n");

link

Compliance

Syntax

Category  list operator (files)
Arguments  filename, linkname
Return Value  numeric

Definition

This function creates a new link named after the second argument linking to the filename specified in the first argument; returns 1 or 0 for success or failure.

Example

$result = link("/usr/local",:"/tmp/link");
print("link() $result\n");

listen

Compliance

Syntax

Category  list operator (socket)
Arguments  socket, queuesize
Return Value  1 (true) '' (false)

Definition

This is equivalent to the UNIX listen() system call. If you are using accepts on a socket, listen tells the system that it is available.


local

Compliance

Syntax

Category  named unary operator (scope)
Arguments  expression
Return Value  N/A

Definition

Modifies all the variables listed to be local to the current block. If there is more than one element, the list must be enclosed in parentheses. Any errors would be syntax errors. Although local() does prevent pollution of the global namespace with variables in subroutines, my() is safer than local() because it also creates new copies of the variables for each recursive call of a subroutine.


localtime

Compliance

Syntax

Category  named unary operator (time)
Arguments  expression
Arguments  none
Return Value  list

Definition

Given a time as an argument (measured in seconds since 1 Jan. 1970), this function returns a list of nine elements with that time broken down into seconds, minutes, hours, day of month, month, year, day of week, day of year, daylight saving enabled (daylight saving enabled is either 1 for on or 0 for off). If no argument is used, the current time is reported. If the system supports POSIX time zones, the time returned is localized for the current time zone.

In a scalar context, the ctime() style output is returned (a string describing the time in readable form).

Example

($sec,$min,$hour,$mday,$mon,$year,$wday,$ydat,$isdst) = localtime();
print "localtime() 19$year-$mon-$mday\n";

log

Compliance

Syntax

Category  named unary operator (numeric)
Arguments  expression
Arguments  none
Return Value  numeric

Definition

This returns the logarithm (using the natural logarithm base) of the expression (or of $_ if none specified).

Example

print("log() ",log(2.5),"\n");

lstat

Compliance

Syntax

Category  named unary operator (files)
Arguments  handle
Arguments  expression
Return Value  list

Definition

The lstat function returns the file statistics of the file pointed to by the file handle (or a file handle produced by evaluating the expression). This is equivalent to stat(), but if the file is a symbolic link, the statistics are generated for the symbolic link itself rather than the file being linked to. Note that, like the file test operators, lstat() can take a special argument underscore, which means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call.

Example

($device,$inode,$mode,$nlink,$uid,$gid,$rdev,$size,
$atime,$mtime,$ctime,$blksize,$blocks) = lstat("/tmp/link");
print("lstat() $device, $inode, $ctime \n");

m//

Compliance

Syntax

Category  named unary operator (pattern)
Arguments  m/<pattern>/<optionlist>
Arguments  /<pattern>/<optionlist>
Return Value  1 (true) '' (false)

Definition

This function searches the default string for the pattern using regular expression pattern matching. It returns 1 if a match is found. Otherwise, '' is returned. The default string can be assigned to the match using either the =~ or !~ operators; otherwise, it is $_.

Example

$_ = "Happy MaN";
print "m// ",/n$/i,"\n";

map

Compliance

Syntax

Category  list operator (list)
Arguments  block list
Arguments  expression, list
Return Value  list

Definition

This function evaluates the specified expression (or block) for each individual member of the specified list. This is done by assigning $_ to each member of the list and evaluating the expression (or block). The value returned is the list of all these results (not necessarily one Perl element of the list).

Example

@result = map($_+1,(0,1,2));
print("map() ",@result,."\n");

mkdir

Compliance

Syntax

Category  list operator (files)
Arguments  filename, mode
Return Value  1 or 0

Definition

The mkdir function creates a directory with a name specified by the filename, with the mode specified by the octal mode. If it fails, $OS_ERROR ($!) is set to operating system error.

Example

print("mkdir() ",mkdir("/tmp/testdir",0777), "\n");

msgctl

Compliance

Syntax

Category  list operator (System V)
Arguments  id, cmd, arg
Return Value  special

Definition

This function is equivalent to the UNIX system call msgctl(), if supported, and provides a variety of message control operations as specified by CMD.


msgget

Compliance

Syntax

Category  list operator (System V)
Arguments  key, flags
Return Value  special

Definition

This function is equivalent to the UNIX system call msgget(), if supported, and returns the message queue identifier associated with key.


msgrcv

Compliance

Syntax

Category  list operator (System V)
Arguments  id, var.size, type, flags
Return Value  special

Definition

This is equivalent to the UNIX system call msgrcv(), if supported. This function reads a message from the queue associated with the message queue identifier, specified by msqid, and places it in the structure pointed to by msgp.


msgsnd

Compliance

Syntax

Category  list operator (System V)
Arguments  id, msg, flags
Return Value  special

Definition

The msgsnd function is equivalent to the UNIX system call msgsnd(), if supported, and sends a message to the queue associated with the message queue identifier.


my

Compliance

Syntax

Category  named unary operator (scope)
Arguments  expression
Return Value  N/A

Definition

This function declares each of the variables listed to be local() to the block. If more than one variable is specified, parentheses are required. The my() specification is stronger than the the local() specification because it not only stops pollution of the global namespace but also creates a stack frame for subroutine calls so that recursive calls will behave as one would expect with local variables.


next

Compliance

Syntax

Category  named unary operator (flow)
Arguments  label
Arguments  none
Return Value  N/A

Definition

This operator allows branching within a loop so that the execution skips onto the next instance of the loop.

Example

print("next ");
@array = ("a","b","c");
loop: foreach $elem (@array) {
next if $elem =~ /^a/;
print $elem;
}
print "\n";

no

Compliance

Syntax

Category  list operator (module)
Arguments  module, list
Return Value  N/A

Definition

Using this function, particularly useful when using pragmas, is the reverse of use().

Example

use integer;
# code using integer arithmetic here
no integer;
# back to floating point arithmetic

oct

Compliance

Syntax

Category  named unary operator (numeric)
Arguments  expression
Return Value  numeric

Definition

This function evaluates the expression as an octal string and returns the decimal value.

Example

print("oct() ",oct("88"), "\n");

open

Compliance

Syntax

Category  list operator (files)
Arguments  handle, filename
Arguments  handle
Return Value  TRUE (non zero) or FALSE (undefined)

Definition

This function opens a file using the specified file handle. The file handle may be an expression; the resulting value is used as the handle. If no filename is specified, a variable with the same name as the file handle is used (this should be a scalar variable with a string value referring to the filename).

The filename string may be prefixed with the following values to indicate the mode:

The special file name - can refer to either STDIN (-) when reading) or STDOUT (>-), when writing.

Example

open(FIL,"/tmp/notexist") || 
       print("open() failed as file did not exist.\n");

opendir

Compliance

Syntax

Category  list operator (files)
Arguments  handle, dirname
Return Value  1 (true) '' (false)

Definition

Opens a directory handle for the directory name specified. If the dirname is an expression this can be evaluated to return a name.

Example

opendir (DIR, "/tmp/notexist") || 
print("opendir() diled as directory dod not exist.\n");

ord

Compliance

Syntax

Category  named unary operator (string)
Arguments  expression
Arguments  none
Return Value  numeric

Definition

This function returns the numeric ASCII code of the first character in the expression (or $_ if none specified).

Example

print("ord() ",ord("A"), "\n");

pack

Compliance

Syntax

Category  list operator (records)
Arguments  template, list
Return Value  string

Definition

This function returns a packed version of the data in the list using the template to determine how it is coded. The template comprises a sequence of characters, each specifying the data type of the matching data item in the list.

Character Description
@ Null fill to absolute position
A ASCII string with spaces to pad
a ASCII string with nulls to pad
b Bit string (ascending bit order)
B Bit string (descending bit order)
c Signed char value
C Unsigned char value
d Double-precision float in the native format
f Single-precision float in the native format
h Hex string (low nybble first)
H Hex string (high nybble first)
i Signed integer value
I Unsigned integer value
l Signed long integer value
L Unsigned long integer value
n Short integer "network" order
N Long integer "network" order
p Pointer to a null-terminated string
P Pointer to a structure (fixed-length string)
s Signed short integer value
S Unsigned short integer value
u UUencoded string
v Short integer "VAX" (little-endian) order
V Long integer "VAX" (little-endian) order
x Null byte
X Back up a byte

A concise form of template can be used by appending a number after any letter to repeat that format specifier. For aA, the number uses one value and pads the rest. For bB, the number indicates the number of bits. For hH, the number indicates the number of nybbles. For P, the number indicates the size of the pointer structure. Using an asterisk in place of a number means to repeat the format specifier as necessary to use up all list values. Note that some packed structures may not be portable across machines (in particular, network and floating point formats). It should be possible to unpack the data using the same format specification with an unpack() call.

Example

Use Socketl
@a=(140,203,7,103);
$addr=pack('C4',@a);
($name,$alias,$adrtype,$length,@address)=gethostbyaddr
($addr,AF_INET);print("pack() ",@a, "packed as: $addr".\n");

package

Compliance

Syntax

Category  named unary operator (class)
Arguments  name
Return Value  N/A

Definition

Calling this function declares that all unqualified dynamic variables in the current block are in the scope of the specified package name. This is normally done in the header of a file to be included as a package or a module in other programs that require() or use(). Note that this does apply to variables declared as local() but not to variables declared as my().


pipe

Compliance

Syntax

Category  list operator (process)
Arguments  readhandle, writehandle
Return Value  1 (true) '' (false)

Definition

Links named pipes like the UNIX function pipe().


pop

Compliance

Syntax

Category  name unary operator (array)
Arguments  variable
Return Value  value

Definition

This function removes the top item from the array specified and returns that element.

Example

@a = (1,2,3,4);
print("pop() ",pop(@a), "leaves ",@a,"\n");

pos

Compliance

Syntax

Category  named unary operator (pattern)
Arguments  variable
Return Value  numeric

Definition

Returns the offset that the last pattern match (m//g) reached when searching the scalar variable specified as an argument. It can be assigned to alter the bahavior of the next match.

Example

$name = "alpha1 alpha2 alpha3 alpha4";
$name =~ m/alpha/g;
print("pos() ", pos($name), "\n");

pos

Compliance

Syntax

Category  list operator (i/o)
Arguments  handle, list
Arguments  list
Arguments  none
Return Value  1 (true) '' (false)

Definition

Prints the list to the file represented by the file handle. If no file handle is specified the default file handle is STDOUT. This default file handle may be altered using the select() operator. If no list argument is specified, $_ is printed.

Example

$return = print "print() ";
print "returns $return on success.\n");

printf

Compliance

Syntax

Category  list operator (i/o)
Arguments  filehandle list
Arguments  list
Return Value  1 (true) '' (false)

Definition

This function uses the C printf format specifiers to control the printed output. It is equivalent to

print filehandle, sprintf(list);

As with print() the default file handle is STDOUT.

Example

printf("printf() An integer printed with leading zeroes %05d.\n",9);

push

Compliance

Syntax

Category  list operator (array)
Arguments  array, list
Return Value  numeric

Definition

This appends the elements in the specified list on the end of the specified array and returns the new number of elements in the list.

Example

@a = (1);
$num = push(@a,2,3,4,5);
print("push() Added ",$num-1," elements to array:",
@a,"\n");

q/STRING/

Compliance

Syntax

Category  (string)
Arguments  q/string/
Return Value  value

Definition

This is a standard quote used to surpress special interpretation of characters giving a literal string. You can use single quotes 'string' or the letter q with delimiters. Any delimiter will do as long as it is not used in the string. The backslash character can be used to escape any reference to the delimiting character itself in the string.

Example

print(q!q// The only special character is the delimiter itself \!!, "\n");

qq/STRING/

Compliance

Syntax

Category  (string)
Arguments  qq/string/
Return Value  value

Definition

This is a double quote, used to allow interpolation of special characters within the string as required. You can use double quote "string" or the double qq with delimiters. The backslash character can be used to disable the special meaning of interpolated characters, including the delimiter itself.

Example

$newline = "\n";
print(qq!qq// double quoted with interpolation! $newline!);

quotemeta

Compliance

Syntax

Category  named unary operator (pattern)
Arguments  expression
Return Value  string

Definition

quotemeta returns the value of the expression with all the metacharacters backslashed.

Example

print(quotemeta("quotameta() I can use any metcharacter $ \ "),"\n");

qw/STRING/

Compliance

Syntax

Category  (list)
Arguments  qw/string/
Return Value  list

Definition

This function returns a list of words in string. Spaces are used as delimiters in the string to produce this list.

Example

print("qw// ",qw("1 2 3 4 5"),"\n");

qx/STRING/

Compliance

Syntax

Category  (process)
Arguments  qx/string/
Return Value  special

Definition

This is a back quote, used to allow interpolation of special characters within the string as required and then execute the resulting command as a system command. You can use back quotes 'string' or the letters qx with delimiters. The backslash character can be used to disable the special meaning of interpolated characters, including the delimiter itself. The return value is the return value of the system() call.

Example

print("qx// ",qx!du -s /tmp!);

rand

Compliance

Syntax

Category  named unary operator (numeric)
Arguments  expression
Arguments  none
Return Value  numeric

Definition

This function returns a real number between 0 and the number evaluated as expression (the upper limit is 1 if no expression is specified). The upper limit must be positive. As the function calls a pseudorandom generator, it should be possible to generate the same sequence of numbers repeatedly unless the initial seed value is altered with srand().

Example

print("rand(), ",rand,"\n");

read

Compliance

Syntax

Category  list operator (i/o)
Arguments  handle, variable, length, offset
Arguments  handle, variable, length
Return Value  1 (true) '' (false)

Definition

Reads length bytes from file handle into variable (starting at offset if specified). It returns the number of bytes actually read.

Example

open(INF,"/etc/services") || die "Error reading file, stopped";
read(INF,$result,10);
print("read() $result \n");
close(INF)

readdir

Compliance

Syntax

Category  list operator (i/o)
Arguments  dirhandle
Return Value  lname

Definition

In a list context, this function returns a list of the files in the directory specified by the directory handle. In a scalar context, it returns the next file name in the directory.

Example

opendir(DIR,"/tmp");
@file = readdir(DIR);
print("readdir() ",@files, "\n");

readlink

Compliance

Syntax

Category  named unary operator (files)
Arguments  expression
Arguments  none
Return Value  value

Definition

This function returns the value of the symbolic link specified by expression (or $_ if none specified). If symbolic links are not implemented, it gives a fatal error. If symbolic links are supported, but there is some system error, the error is returned in $OS_ERROR ($!).


recv

Compliance

Syntax

Category  list operator (socket)
Arguments  socket, variable, length, flags
Return Value  address

Definition

The recv function is equivalent to UNIX system call recv() and receives a message on a socket.


redo

Compliance

Syntax

Category  (flow)
Arguments  label
Arguments  none
Return Value  N/A

Definition

This function passes control directly to the label without executing any continue block. If no label is specified, the innermost loop is used.


ref

Compliance

Syntax

Category  named unary operator (class)
Arguments  expression
Return Value  package

Definition

This function returns the package of a bless()ed variable, TRUE if the variable is a reference, or FALSE. The return value for TRUE is actually the type of the variable (for example ARRAY, HASH, REF, SCALAR).

Example

$tmp = {};
bless $tmp, ATMPCLASS;
print "ref() \$tmp is now in class ",ref($tmp),"\n";

rename

Compliance

Syntax

Category  list operator (files)
Arguments  oldname, newname
Return Value  1 (true) 0 (fail)

Definition

This function renames files on the same file system from oldname to newname.

Example

$returned = rename("/tmp/test","/tmp/test2");
print("rename() returned $returned \n");

require

Compliance

Syntax

Category  named unary operator (module)
Arguments  expression
Arguments  none
Return Value  1 (true) '' (false)

Definition

If the expression is a scalar, the library specified by the filename is included (if it has not already been).

In Perl 5, if the expression is numeric this requires that the version of Perl being used (in $PERL_VERSION or $[) is greater than or equal to the version specified.

Note that Perl 5 also has the use() mechanism for including modules; use() is more robust than require.

Example

require "cgilib.pl";

reset

Compliance

Syntax

Category  named unary operator (misc)
Arguments  expression
Arguments  none
Return Value  1

Definition

This function provides a way of resetting variables in the current package (especially pattern match variables). The expression is interpreted as a list of single characters. All variables starting with those characters are reset. The letters are case sensitive (as Perl variables are). Hyphens may be used to specify ranges of variables to reset. If called without any argument, reset simply resets all search matches.

Caution
Use of this operator can reset system variables you may not want to alter. For example, be very careful with the following:

reset A-Z;

return

Compliance

Syntax

Category  list operator (flow)
Arguments  list
Return Value  list

Definition

This function returns from a subroutine (or an eval()) with the value specified.

Example

sub test {
return 1;
}
$test = &test;
print("return() Returned $test \n");

reverse

Compliance

Syntax

Category  list operator (list)
Arguments  list
Return Value  list

Definition

The reverse function returns the list given as an argument in reverse order. In a scalar context, it reverses the letters of its first argument.

Example

@a = (1,2,3);
print("reverse() ",reverse(@a),"\n");

rewinddir

Compliance

Syntax

Category  named unary operator (i/o)
Arguments  dirhandle
Return Value  1 (true) '' (false)

Definition

When reading a directory using readdir(), it is possible to reset the directory to the first file name.

Example

opendir(DIR,"/tmp");
print("rewinddir() (a): "
file: while ($file=readdir(DIR) {
print $file, " ";
}
rewinddir();
print(" (b): "
file: while ($file=readdir(DIR) {
print $file, " ";
}
print("\n");
closedir(DIR);

rindex

Compliance

Syntax

Category  list operator (string)
Arguments  string, substring, position
Arguments  string, substring
Return Value  position

Definition

This function is very similar to index() except that, instead of scanning for the substring from the first character in the string, it scans backwards from the last character. So it returns the starting position of the last occurrence of substring in string (scanning backwards from the specified position or from the end if no position is specified).

Example

$ans1 = rindex("abcdefghijiklmdef:-)","def");
$ans2 = rindex("abcdefghijiklmdef","def",$ans1+3);
print("rindex() def is at $ans1 and next at $ans2\n");

rmdir

Compliance

Syntax

Category  named unary operator (files)
Arguments  filename
Return Value  1 or 0

Definition

This function deletes the directory specified (or $_) if it is empty and sets $OS_ERROR ($!) to the error value if there is a system error.


s///

Compliance

Syntax

Category  (pattern)
Arguments  s/pattern/replacement/options
Return Value  numeric

Definition

This function searches the default string for pattern (a regular expression) and replaces this with the replacement string (the actual replacemnt behavior depends on the options). It returns the number of replacements made. The default string is set using either of the pattern binding operators (=~ or ¬~ ) or $_ is used if none have been bound. The valid options are

Option Description
e Evaluate the right side as an expression
g Global (replace all occurrences)
i Case-insensitive pattern matching
m Ignore \n in string (multiple lines)
o Optimize (compile pattern once)
s Treat string as single line
x Extended regular expressions

Example

$oldstr = "abcdefABCDEFabcdefABCDEF";
$newstr= $oldstr;
$str =~ s/abc/zzz/ig;
print("s/// $oldstr became $newstr \n");

scalar

Compliance

Syntax

Category  named unary operator (misc)
Arguments  expression
Return Value  value

Definition

This operator forces the argument to be interpreted in a scalar context, rather than as a list so that it can override the default context if
necessary.


seek

Compliance

Syntax

Category  list operator (i/o)
Arguments  handle, position, start
Return Value  1 (true) '' (false)

Definition

This function sets the file pointer to a specified offset position in a file. The offset is relative to the start that can have three values: 0 (start of file), 1 (current position), 2 (end of file). This allows the use of random access files, and the implementation of fast read algorithms (for example binary search techniques) on file handles, especially with fixed-length data where the offsets are easier to calculate.


seekdir

Compliance

Syntax

Category  list operator (i/o)
Arguments  dirhandle, position
Return Value  1 (true) '' (false)

Definition

This function allows the position in a directory to be reset to a position saved with telldir(). This is useful when processing directories with readdir().


select

Compliance

Syntax

Category  named unary operator (i/o)
Arguments  handle
Arguments  rbits, wbits, ebits, timeout
Return Value  handle

Definition

This operator selects the default file handle used for I/O operations such as print() and write(). By default STDOUT is selected, but this function can select any other file handle to be the default instead. The return value is the currently selected file handle (before any change) so it is useful to assign this to a variable in order to be able to restore the original handle as the default at a later stage.

The second form calls the UNIX system select() function.

Example

open(OUT,"/tmp/t.out");
$return = select(OUT);
print("This goues in /tmp/t.out.\n");
select($return);
print("select() restored to STDOUT.\n");

semctl

Compliance

Syntax

Category  list operator (System V)
Arguments  id, semnum, command, arg
Return Value  value

Definition

This function is equivalent to the UNIX semctl() function. This is a semaphore control operation with several variables.


semget

Compliance

Syntax

Category  list operator (System V)
Arguments  key, nsems, flags
Return Value  value

Definition

This function is equivalent to the UNIX semget() function and returns the semaphore ID.


semop

Compliance

Syntax

Category  list operator (System V)
Arguments  key, opstring
Return Value  1 (true) '' (false)

Definition

The semop function is equivalent to the UNIX semop() function call and performs semaphore signalling and waiting functions.


send

Compliance

Syntax

Category  list operator (socket)
Arguments  socket, message, flags, to
Arguments  socket, message, flags
Return Value  numeric

Definition

This function is equivalent to the UNIX system send() function and sends a message socket.


setgrent

Compliance

Syntax

Category  (system files)
Arguments  none
Return Value  n/a

Definition

This function rewinds the /etc/group file to the start of the file for subsequent accesses using getgrent().

Example

print("setgrent() ",setgrent(), "\n");

sethostent

Compliance

Syntax

Category  named unary operator (system files)
Arguments  flag
Return Value  N/A

Definition

If called with an argument of 1, this function tells the system to keep a TCP socket open for name server queries such as gethostbyname(). If this is not, then the name server queries use UDP datagrams.

Example

print("sethostent() ",sethostent(1), "\n");

setnetent

Compliance

Syntax

Category  named unary operator (system files)
Arguments  flag
Return Value  N/A

Definition

This function rewinds the /etc/networks file used by getnetent() and other network related functions. If the flag has a value of 1, then the file is kept open between calls to getnetbyname() and getnetbyaddr().

print("setnetent() ",setnetent(1), "\n");

setpgrp

Compliance

Syntax

Category  list operator (process)
Arguments  pid, pgrp
Return Value  1 (true) '' (false)

Definition

This function sets the current process group for the specified process (pid); if this is zero, the current process is set.


setpriority

Compliance

Syntax

Category  list operator (proxess)
Arguments  type, id, priority
Return Value  1 (true) '' (false)

Definition

This function calls the UNIX setprority() function. The type is one of PRIO_PROCESS, PRIO_PGGRP, or PRIO_USER. The id is the relevent ID for this (pid, a pid for a group of processes, or uid). If 0 is used as the id, the current process, process group, or user is used. The priority is a number representing the level of priority (normally in the range 120 to 20) where the lower the priority, the more favorable the scheduling of the process by the operating system.

Example

print("setpriority() ",setpriority(0,0,-20),"\n");

setprotoent

Compliance

Category  named unary operator (system files)
Arguments  flag
Return Value  1 (true) '' (false)

Definition

This function rewinds the /etc/protocols file used by getprotoent() and other protocol related functions. If the flag has a value of 1, then the file is kept open between calls to getprotobyname() and getnetbynumber().

Example

print("setprotoent() ",setprotoent(1), "\n");

setpwent

Compliance

Syntax

Category  (system files)
Arguments  none
Return Value  1 (true) '' (false)

Definition

This function rewinds the /etc/passwd file used by getpwent() and other password related functions.

Example

print("setpwent() ",setpwent(), "\n");

setservent

Compliance

Syntax

Category  named unary operator (system files)
Arguments  flag
Return Value  1 (true) '' (false)

Definition

This function rewinds the /etc/services file used by getservent() and other service-related functions. If the flag has a value of 1, then the file is kept open between calls to getservbyname() and getnetbyport().

Example

print("setservent() ",setservent(1), "\n");

setsockopt

Compliance

Syntax

Category  list operator (socket)
Arguments  socket, level, optname, optval
Return Value  1 (true) '' (false)

Definition

This function is equivalent to UNIX system call setsockopt() and sets the socket options.


shift

Compliance

Syntax

Category  named unary operator (array)
Arguments  array
Arguments  none
Return Value  value

Definition

This function takes the leftmost element from the array specified and returns that, reducing the array by one element. When no array is specified, the array of arguments passed to the Perl script, $ARGV, is used if the context is not in a subroutine; otherwise, the array of arguments passed to the subroutine, @_, is used.

The return value is undefined if the array is empty.

Example

print("shift() ");
while ($arg = shift) {
print($arg,' ');
}
print("\n");

shmctl

Compliance

Syntax

Category  list operator (System V)
Arguments  id, cmd, arg
Return Value  value

Definition

This function is equivalent to the UNIX shmctl() function and performs shared memory control operations.


shmget

Compliance

Syntax

Category  list operator (System V)
Arguments  key.size, flags
Return Value  value

Definition

This function is equivalent to the UNIX shmget() function and returns shared memory segment ID.


shmread

Compliance

Syntax

Category  list operator (System V)
Arguments  id, var. pos, size
Return Value  value

Definition

This function is equivalent to the UNIX shmread() function and reads from the shared memory segment ID.


shmwrite

Compliance

Syntax

Category  list operator (System V)
Arguments  id, string, pos, size
Return Value  value

Definition

This function is equivalent to the UNIX shmwrite() function and writes to the shared memory segment ID.


shutdown

Compliance

Syntax

Category  list operator (socket)
Arguments  socket, how
Return Value  1 (true) '' (false)

Definition

This function is equivalent to the UNIX shutdown() function and shuts down a socket.


sin

Compliance

Syntax

Category  named unary operator (numeric)
Arguments  expression
Arguments  none
Return Value  numeric

Definition

This function returns the sine of the expression in radians. If there is no explicit argument, $_ is used.

Example

print("sin() ",sin(4), "\n");

sleep

Compliance

Syntax

Category  named unary operator (process)
Arguments  expression
Arguments  none
Return Value  numeric

Definition

This function causes the current process to sleep for the number of seconds specified in expression (if none is specified, it sleeps forever but may be woken up by a signal if this has been programmed).

Example

print("sleep() ",sleep(5),"\n");

socket

Compliance

Syntax

Category  list operator (socket)
Arguments  socket, domain, type, protocol
Return Value  value

Definition

This function is equivalent to the UNIX socket() system call and opens a specified type of socket and attaches it to a file handle.


socketpair

Compliance

Syntax

Category  list operator (socket)
Arguments  socket1, socket2, domain, type, protocol
Return Value  value

Definition

This function is equivalent to the UNIX socketpair() system call and creates a pair of sockets, which are unnamed, in the specified domain.


sort

Compliance

Syntax

Category  list operator (list)
Arguments  subname list
Arguments  block list
Arguments  list
Return Value  list

Definition

This function sorts the list specified and returns the sorted list. The sort method can be specified with the optional subroutine or block argument. A subroutine may be specified that takes two arguments (passed as global package variables, $a $b) and returns TRUE if the first is less than or equal to the second by any criteria used. Similarly, a block can be specified (effectively an anonymous subroutine) to perform this function. The default sort order is based on the standard string comparison order.

Example

@a = ("z","w","r","i","b","a");
print("sort() ",sort(@a),"\n");

splice

Compliance

Syntax

Category  list operator (array)
Arguments  array, offset, length, list
Arguments  array, offset, length
Arguments  array, offset
Return Value  list

Definition

This function removes the elements specified by offset and length from the array and replaces them with the elements in the list supplied as the last argument. A list of those elements removed is returned. If no length is specified, all the items from offset to the end of the array are removed.

Example

@a = ("a","e","i","o","u");
print("splice() ",splice(@a,0,3,"A","E","I"),"\n");

split

Compliance

Syntax

Category  list operator (pattern)
Arguments  /pattern/,expression,limit
Arguments  /pattern/,expression
Arguments  /pattern/
Arguments  none
Return Value  list

Definition

This function manipulates a string, splitting the string denoted by the expression (or the $_ if none is specified) into an array of strings based on some separator string specified by the pattern (if the pattern has no specified whitespace as the default). An optional limit restricts the number of elements returned. A negative limit has no effect.

If not in a list context, the number of elements found is returned. In an scalar context, it returns the number of elements and puts the resulting array into the @_ array (the use of the @_ as the result is depreciated).

Examples

print("spilt() ",split(/:/,"1:2:3:4:5"),"\n");

sprintf

Compliance

Syntax

Category  list operator (string)
Arguments  format, list
Return Value  string

Definition

This is equivalent to the C sprintf() call. The format is a string with special metacharacters to specify how may values/variables follow and how to represent each of these in the resulting string. This enables the explicit formatting of floating point and integer numbers (also enabling binary, hexidecimal, and octal formats).

Example

print("strintf() ",sprintf("%0d \n",9),"\n");

sqrt

Compliance

Syntax

Category  named unary operator (numeric)
Arguments  expression
Return Value  numeric

Definition

This function returns the result of evaluating the expression and finding its square root.

Example

print("sqrt() ",sqrt(4),"\n");

srand

Compliance

Syntax

Category  named unary operator (numeric)
Arguments  expression
Arguments  none
Return Value  1 (true) '' (false)

Definition

This function sets the seed used by the pseudorandom number generation algorithm when generating rand() numbers. In order to randomize the possible sequences, the seed should be set to a different value each time the script is called. The default behavior, when no expression is supplied, is to use the result of a call to time(). This is not a secure method of randomizing for scripts that need to be secure because it is possible to predict what sequence the script will return.

Note that, when using a set of pseudorandom data generated using rand(), it is possible to generate exactly the same data repeatedly (without having to save the entire sequence) simply by stetting and saving the seed. Restoring the seed and calling rand() will then produce the same sequence again.

Example

srand(26);
print("rand() ",rand(),", ");
srand(26);
print(rand()," (should produce the same \"random\" number twice) \n");

stat

Compliance

Syntax

Category  list operator (files)
Arguments  handle
Arguments  expression
Arguments  none
Return Value  list

Definition

This function returns the file statistics of the file pointed to by the file handle (or a file handle produced by evaluating the expression). Note that, like the file test operators, stat() can take a special argument underscore; this means that the test is carried out on the same file handle as the last file test, stat(), or lstat() call.

Example

($device,$inode,$mode,$nlink,$uid,$gid,$rdev,$size,$atime,
$mtime,$ctime,$blksize,$blocks) = stat("/etc/ passwd");
print("stat() $device, $inode, $ctime \n");

study

Compliance

Syntax

Category  named unary operator (pattern)
Arguments  scalar
Arguments  none
Return Value  1 (true) '' (false)

Definition

When many pattern match operations are being performed on the same string, the efficiency of these patterns can be improved with the study() function. If no string is specified, the $_ is studied by default. The call sets up internal lookup tables based on the string studied so that pattern matching operations can use this information to process the pattern match more quickly. Only one string at a time can be studied (subsequent calls effectively "unstudy" any previous study() removing the lookup tables). The function study() is often used in a loop processing lines of a text file where each line is studied before being processed with various pattern matches.


sub

Compliance

Syntax

Category  (flow)
Arguments  name block
Arguments  name
Arguments  name
Return Value  value

Definition

This is the syntax for a subroutine declaration. The full form defines a subroutine with the name and associates this with the statements in block. When evoked, it will return the result of the last statement executed in the block (often a return() statement). If no name is supplied, it is an anonymous subroutine (certain functions such as sort() allow anonymous subroutines as arguments). With only a name as an argument, the statement is a forward reference to a subroutine, which is fully declared later in the script.


substr

Compliance

Syntax

Category  list operator (string)
Arguments  expression, offset, length
Arguments  expression, offset
Return Value  string

Definition

This function returns a substring of a string specified by expression. The substring starts at the specified offset and has the specified length. If the offset is negative, it starts from the right side of the string instead of the left side. If the length is negative, it means to trim the string by that number of characters.

Example

print("substr() ",substring("okay",0,2),"\n");

symlink

Compliance

Syntax

Category  list operator ((files)
Arguments  oldfile, newfile
Return Value  1 or 0

Definition

This function creates a symbolic link from the existing file specified by oldfile to the specified newfile and returns 1 on success and 0 on failure. If symbolic links are not supported by the operating system, this will return a fatal error.

Example

print("symlink() ",symlink("/usr/local","/tmp/symlinktousrlocal"),"\n");

syscall

Compliance

Syntax

Category  list operator (i/o)
Arguments  list
Return Value  varies

Definition

This mechanism allows Perl to call corresponding UNIX C system calls directly. It relies on the existence of the set of Perl header files Syscall.ph which declares all of these calls. The script h2ph that is normally executed when Perl is installed, sets up the Syscall.ph files. Each call has the same name as the equivalent UNIX system call with the SYS_ prefix. As these calls actually pass control to the relevant C system function. Care must be taken with passing parameters.

The fisrt element in the list used as an argument to syscall() itself, is the name corresponding to the UNIX system call (that is, with the SYS_ prefix). The next elements in the list are interpreted as parameters to this call. Numeric values are passed as the C type int. String values are passed as pointers to arrays. The length of these strings must be able to cope with any value assigned to that parameter in the call.

Example

require "syscall.ph";
print("syscall() ",syscall(&SYS_getpid)," equivalent to $PID\n");

sysopen

Compliance

Syntax

Category  list operator (i/o)
Arguments  handle, name, mode, permissions
Arguments  handle, name, mode
Return Value  1 (true) '' (false)

Definition

This function calls the UNIX C open() function directly from the Perl script, which opens a file for reading or writing.


sysread

Compliance

Syntax

Category  list operator (i/o)
Arguments  handle, scalar, length, offset
Arguments  handle, scalar, length
Return Value  1 (true) '' (false)

Definition

This function calls the UNIX C read() function directly from the Perl script, which reads a line from the standard input source.


system

Compliance

Syntax

Category  list operator (process)
Arguments  list
Return Value  status

Definition

This call executes the specified list as an operating system call. The process to execute this command is forked and the script waits for the child process to return. The return value is the exit status of the child process.

Note
To capture the output from a system call, use the qx// (back quote mechanism) rather than system().

Example

print("system() ",system("ls -F /var > /tmp/t.tmp"),"\n");

syswrite

Compliance

Syntax

Category  list operator (i/o)
Arguments  handle, scalar, length, offset
Arguments  handle, scalar, length
Return Value  1 (true) '' (false)

Definition

This function calls the UNIX C write() function directly from the Perl script, which is an interactive write to another user process.


tell

Compliance

Syntax

Category  named unary operator (i/o)
Arguments  expression
Arguments  none
Return Value  position

Definition

This function returns the current position in the file specified by the expression (which should evaluate to a file handle). If no handle is specified, the last file accessed is used. This value can be used by seek() to return to this position if appropriate.

Example

print("tell() ",tell(STDOUT),"\n");

telldir

Compliance

Syntax

Category  named unary operator (i/o)
Arguments  dirhandle
Return Value  position

Definition

This function returns the current position in the directory handle specified. This value can be used by seekdir() to return to this position if appropriate.

Example

opendir(DIR,"/tmp");
readdir(DIR);
print("telldir() ",telldir(DIR),"\n");

tie

Compliance

Syntax

Category  list operator (class)
Arguments  variable, classname, list
Return Value  object

Definition

This function binds a variable to a package class. It creates an instance of this class by running the new() method associated with that class. Any parameters for the new() method may be specified in the list.

The behavior depends on the way the package class is written and on the type of variable. Most common are package classes written to support associative arrays. In particular, package classes exist to bind associative arrays to various databases.

The tie() mechanism hides all the complexities of implemention behind a simple interface so that, for example, the records in a database can be accessed by looking at the associative array bound to the database though an appropriate package class.

The example here uses the Configure.pm module. This module gives access to information about the machine on which Perl was installed. It is possible to bind an associative array to this class and examine this to find out the value of any of the configuration parameters.

Example

use Configure;
$return = tie %c, Configure;
print("tie() returned \"$return\" and ",
 "a sample value is $c{installbin}\n");

tied

Compliance

Syntax

Category  named unary operator
Arguments  variable
Return Value  object

Definition

This function was first implemented in Perl 5.002 and returns a reference to the object that the variable is an instance of. This is the same as is returned by the original call to tie() when it is bound.


time

Compliance

Syntax

Category  (time)
Arguments  none
Return Value  time

Definition

This function returns the time, in seconds, since 1 January 1970. The format can be converted into more useful parts using gmtime() or localtime().


times

Compliance

Syntax

Category  (process)
Arguments  none
Return Value  list

Definition

This function returns a list of four elements representing the time, in seconds, used. The four elements represent the system time and the user time used by the current process and child processes.

Example

($usertime,$systemtime,$childsystem,$childuser) = times();
print("times() $usertime $systemtime $childsystem $childuser\n");

tr///

Compliance

Syntax

Category  (string)
Arguments  tr/searchlist/replacelist/<options>
Return Value  numeric

Definition

This function translates all occurrences of items in the search list with the equivalent items in the replacement list. The string searched is the default search string bound by =~ or !=, or if no string is bound to the pattern match, the $_ string is used. The return value is the number of characters translated or deleted.

The valid options are

Option Description
c Complement (non-matching characters in search list are used)
d Delete (delete any characters not in search list as well as translating)
s Squash (if the translation results in a sequence of repeated characters from the replace list ,then reduce this to one occurance of the character)

The searchlist and the replacelist may contain the character to indicate a range of characters.

Examples

tr/AEIOU/aeiou/ # Make all vowels lowercase
tr/[A-M]/[a-m]/ # Make first half of alphabet lowercase
tr/aeiou/ /c # Replace all non-vowels with space
tr/aeiou/AEIOU/d # Make all vowels uppercase and # remove all
other characters
tr/aeiou/-/s # Replace all vowels with -, # but only one -
for adjacent vowels


truncate

Compliance

Syntax

Category  list operator (i/o)
Arguments  handle, length
Arguments  expression, length
Return Value  1 (true) '' (false)

Definition

This function truncates the file referenced by the file handle to length. An expression can be used that evaluates to the file handle if the operating system does not implement this feature.


uc

Compliance

Syntax

Category  named unary operator (string)
Arguments  expression
Return Value  string

Definition

This function returns an uppercase version of the specified
expression.

Example

print("uc() ",uc("This is All Caps"), "\n");

ucfirst

Compliance

Syntax

Category  named unary operator (string)
Arguments  expression
Return Value  string

Definition

This function returns a string with the first character of the
expression in uppercase.

Example

print("ucfirst() ",ucfirst("this is Capitalized"), "\n");

umask

Compliance

Syntax

Category  named unary operator (files)
Arguments  newumask
Arguments  none
Return Value  oldumask

Definition

This function sets the file mask using the specified newumask. It returns the oldumask so that it can be stored and restored later if required. If called without any arguments, it returns the current umask. This is the mechanism UNIX uses to modify the permissions of any files created.

Example

print("umask() The current umask is: ",umask,"\n");

undef

Compliance

Syntax

Category  named unary operator (misc)
Arguments  expression
Arguments  none
Return Value  value

Definition

This function undefines the value of the expression. The expression may be a scalar value, and array, or a subroutine (specified with an & prefix). When called without an expression, this function returns an undefined value.


unlink

Compliance

Syntax

Category  list operator (files)
Arguments  list
Return Value  numeric

Definition

This function deletes the files in the list and returns the number of files deleted.

Example

system("touch /tmp/t.tst");
print("unlink() ",unlink("/tmp/t.tst"),"\n");

unpack

Compliance

Syntax

Category  list operator (data)
Arguments  template, expression
Return Value  list

Definition

This function unpacks data that are packed with pack(). It uses the same template mechanism to specify the format of the data in the packed string. In a scalar context, the first value in the list is returned.


unshift

Compliance

Syntax

Category  list operator (array)
Arguments  array, list
Return Value  numeric

Definition

This function prepends the list to the front of the specified array and returns the new number of elements in array.

Example

@a = (a, b, c);
$ret = unshift(@a, 1, 2, 3);
print("unshift() Array has $ret elements:",@a,"\n");

untie

Compliance

Syntax

Category  named unary operator (class)
Arguments  variable
Return Value  1 (true) '' (false)

Definition

This function undoes the binding between a variable and a package class that was created using tie().


use

Compliance

Syntax

Category  list operator (module)
Arguments  module, list
Return Value  N/A

Definition

This function imports the specified module into the current block. The import() method defined for the package class represented by the module is evaluated. The specified list is passed as optional arguments to this import() method. If you do not specify a list argument, then the default methods for that module will be those imported. You can specify the empty list() in order to avoid adding any items to the local namespace.

Example

use English;

Note that this is the mechanism for implementing compiler directives known as pragmas. You can, for example, force all aritmateic to be interger based by

use integer; 

And then this can be turned off again with

no integer;

utime

Compliance

Syntax

Category  list operator (files)
Arguments  list
Return Value  numeric

Definition

This function sets the access and modification time of all the files in the list to the time specified in the first two items in the list. The time must be in the numeric format (that is, seconds since 1 January 1970) as returned by the time() function.

Example

$time = now;
print("utime() ",utime($time,$time,"/tmp/t.tst"),"\n");

values

Compliance

Syntax

Category  named unary operator (hash)
Arguments  variable
Return Value  list

Definition

This function returns the array comprising all the values in the associate array specified. In a scalar context, it returns the number of values in the array.

Example

%a = (1, "one", 2, "two", 3, "three");
print("values() ",values(%a),"\n);

vec

Compliance

Syntax

Category  list operator (fixed)
Arguments  expression, offset, bits
Return Value  value

Definition

This function uses the string specified by expression as a vector of unsigned integers. The return value is the value of the bitfield specified by offset. The specified bits is the number of bits that are reserved for each entry in the bit vector. This must be a power of 2 from 1 to 32. Note that the offset is the marker for the end of the vector, and it counts back the number of bits specified to find the start.

Vectors can be manipulated with the logical bitwise operators |, &,
and ^.

Example

$vec = '';
vec($vec,3,4) = 1;       # bits 0 to 3
vec($vec,7,4) = 10;       # bits 4 to 7
vec($vec,11,4) = 3;       # bits 8 to 11
vec($vec,15,4) = 15;       # bits 12 to 15
# As there are 4 bits per number this can be 
decoded by 
# unpack() as a hex number
print("vec() Has a created a string of nybbles, in hex: ",
unpack("h*",$vec),"\n");

wait

Compliance

Syntax

Category  (process)
Arguments  none
Return Value  pid

Definition

This function waits for a child process to exit. It returns the process ID (pid) of the terminated process and -1 if there are no child processes.


waitpid

Compliance

Syntax

Category  list operator (process)
Arguments  pid, flags
Return Value  pid

Definition

This function waits for a specified child process to exit and returns pid of the terminated process and -1 if there is no child process matching the pid specified. The flags can be set to various values that are equivalent to the waitpid() UNIX system call (if the operating system supports this), a flags value of 0 should work on all operating systems supporting processes.


wantarray

Compliance

Syntax

Category  (flow)
Arguments  none
Return Value  1 (true) '' (false)

Definition

This function returns 1 if the current context is an array context; otherwise, it returns ''. This construct is most often used to return two alternatives from a subroutine, depending on the calling context.

Example

return wantarray ? (8, 4, 33) : 3;

warn

Compliance

Syntax

Category  list operator (i/o)
Arguments  list
Return Value  1 (true) '' (false)

Definition

This function prints the supplied list to STDERR, like die(). If there is no newline in the list, warn() appends the text at line <line number>\n to the message. However, the script will continue after a warn().


write

Compliance

Syntax

Category  list operator (i/o)
Arguments  expression
Arguments  handle
Arguments  none

Definition

This function writes a formatted record to the file handle (or the file handle that the expression evaluates to). If no file handle is specified, the default is STDOUT; this can be altered using select() if necessary.

A format for use by that file handle must have been declared using the format() function. This defaults to the name of the file handle being used, but other format names can be associated with the current write() operation using the $FORMAT_NAME ($~) special variable.


y///

Compliance

Syntax

Category  (string)
Arguments  y/searchlist/replacelist/<options>
Return Value  numeric

Definition

The y/// operator is a synonym for the translation operator tr///.