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; many functions might overlap in any category scheme.
For each function, the form of its arguments are listed. If there are multiple forms of calling the function, there will be multiple lines describing each one. The meaning of the arguments is 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 function-those dealing with sockets, and those dealing with System V inter process communications-are not dealt with in great detail. These are nearly all direct counterparts of UNIX system calls.
The appendix includes
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: integer (age of file in days since last access relative to $BASETIME)
File test operator takes one file handle or file name as an argument. Returns the 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";
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if file is binary. Returns '' (false) if 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 are, the file is assumed to be binary. If the file is empty, it is returned as being binary. Because this test involves reading the file itself, it is best to test 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");
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if file is a block special file (i.e. a UNIX /dev device file). Returns '' (false) if 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");
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if file is a character special file. Returns '' (false) if 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");
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: integer (age of file in days since last inode change relative to $BASETIME)
File test operator takes one file handle or file name as an argument. 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";
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if file is a directory. Returns '' (false) if 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");
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if file exists. Returns '' (false) if 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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Category: named unary operator (file test)
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if file is a plain file. Returns '' (false) if 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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if file has the setgid bit set. Returns '' (false) if file does not have the setgid bit set. In UNIX, setgid allows an executable to take on the group of the group 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:
(-g "/vmlinuz") ? print("-g /vmlinuz has setgid\n") : print("-g /vmlinuz has not setgid\n")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if the sticky bit is set. 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. 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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if the file is a symbolic link. 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 filetest, 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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: integer (age of file in days relative to $BASETIME)
File test operator takes one file handle or file name as an argument. 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"
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if the file is owned by the effective uid/gid and '' (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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if the file is owned by the real uid/gid and '' (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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if file is a named pipe. Returns '' (false) if 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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if file is readable by the effective uid/gid and '' (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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if file is readable by the real uid/gid and '' (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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: integer (size) '' (false)
File test operator takes one file handle or file name as an argument. Returns size in bytes as an integer if file has a non-zero size. Returns '' (false) if 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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if file is a symbolic link. Returns '' (false) if 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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if file is a text file. Returns '' (false) if file is not a text file. The first characters of the file are checked to see if the high bit is set; 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 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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if the file is a terminal tty device. 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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if the file has the setuid bit set. 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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if the file is writable by the effective uid/gid. 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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if the file is writable by the real uid/gid. 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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if the file is executable by the effective uid/gid. 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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if the file is executable by the real uid/gid. Returns '' (false) otherwise. For the superuser, it always returns true. All filetest 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")
Category: named unary operator (file test)
Arguments: handle
Arguments: file name
Arguments: none
Return value: 1 (true) '' (false)
File test operator takes one file handle or file name as an argument. Returns 1 (true) if the file has zero size. 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")
Category: named unary operator (numeric)
Arguments: numeric value
Return value: numeric
Returns absolute value of its argument (ignoring any sign).
Example:
print("abs(-10) = ",abs(-10),"\n")
Category: list operator (socket)
Arguments: newsocket, genericsocket
Return value: integer (address of socket), '' (false)
Performs low-level UNIX socket calls as accept().
Category: named unary operator (process)
Arguments: integer (seconds)
Return value: integer (seconds to previous alarm)
Sets up a UNIX SIGALRM signal to be generated in the number of seconds specified. It is possible for Perl to trap such signals to call specific signal-handling subroutines, such as trap(). Subseqent calls reset the alarm() time, retaining the number of seconds 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")
Category: list operator (numeric)
Arguments: numeric, numeric
Return value: numeric
Returns the arctangent of the arguments.
Example:
print("atan2(60,2) = ",atan2(60,2),"\n")
Category: list operator (socket)
Arguments: sockethandle, numeric (network address)
Return value: 1 (true) '' (false)
Binds a network address to the socket handle. As UNIX bind() call.
Category: named unary operator (I/O)
Arguments: handle
Return value: 1 (success) or undefined (error)
On systems that distinguish between text and binary files, this function forces binary mode treatment of the given file handle. In systems that 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 have this automatic transformation.
Example:
open(FIL,"file.dat")
binmode(FIL)
Category: list operator (class)
Arguments: variable
Arguments: variable, classname
Return value: reference
Assigns a class to the referenced object. This class is 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 could 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"
Category: named unary operator (scope)
Arguments: expression
Arguments: none
Return value: TRUE FALSE
Return value: (package, filename, line)
This function is used to test the current scope of a subroutine call. If evaluated in a scalar context, returns TRUE or FALSE, depending on whether the current code has been called as a subroutine (this includes code that is included using a require() or an eval() call). In a list context, it supplies details of the calling context in a list comprising the package name, file name, and line of the call.
Example:
sub testcaller {
($package, $file, $line) = caller
}
&testcaller
print "caller() Package=$package File=$file Line=$line \n"
Category: named unary operator (files)
Arguments: expression
Arguments: none
Return value: TRUE/FALSE
Changes the current directory to the directory specified. If no argument is given, changes to the home directory of the current user. Returns TRUE on success and FALSE otherwise.
Example:
chdir("/") ? print("It worked.\n") : print("It didn't work.\n")
Category: list operator (files)
Arguments: list
Return value: numeric
The first element in the list is the UNIX octal number representing the file permission. This function applies this to all the files in the following list. It returns the number of files successfully modified.
Example:
print "chmod() changed ", chmod(0744,"/tmp/test1.txt","/tmp/test2.txt")," files.\n"
Category: list operator (string)
Arguments: list
Arguments: variable
Arguments: none
Return value: numeric
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")
Category: list operator (string)
Arguments: list
Arguments: variable
Arguments: none
Return value: character
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 not sure whether the string has a trailing newline, because chop() will remove the last character regardless, but chomp() will only remove it if it is a new line. |
Category: list operator (files)
Arguments: list
Return value: numeric
This function changes the ownership of the specified files. The first two elements of the list defined the user ID and the group ID to set this ownership to, and 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")
Category: named unary operator (string)
Arguments: numeric
Return value: character
Returns the character indicated by the numeric argument.
Example:
$E = chr(69)
print("chr() $E \n")
Category: named unary operator (files)
Arguments: directory name
Arguments: none
Return value: TRUE/FALSE
This is equivalent to the UNIX chroot()
function. Given a directory name, this directory is treated as
the root directory by all subseqent file system references (effectively
hiding the rest of the file system outside the specified directory).
This restriction will apply 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")
Category: named unary operator (files)
Arguments: handle
Return value: TRUE/FALSE
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 to has finished.
Example:
open(INF,"/tmp/test1.txt")
$ret = close(INF)
print("close() Returned ",$ret," on success\n")
Category: named unary operator (file)
Arguments: handle
Return value: TRUE/FALSE
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")
Category: list operator (socket)
Arguments: socket, name
Return value: TRUE/FALSE
This is equivalent to the UNIX function call.
Category: flow control
Arguments: block
Return value: n/a
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"
Category: named unary operator (numeric)
Arguments: expression
Return value: numeric
Returns the cosine value of the numeric expression supplied as an argument.
Example:
print "cos() ",cos(60),"\n"
Category: list operator
Arguments: string, string
Return value: string
This 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"
Category: named unary operator (I/O)
Arguments: array name
Return value: TRUE/FALSE
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. |
Category: list operator (I/O)
Arguments: array name, dbname, mode
Return value: fatal error if dbm not supported (Perl 4)
Links the associative array referred to by array name 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 is an octal chmod()
style file protection).
| New to version x |
This is depreciated in Perl 5. Use tie() instead. |
Category: named unary operator (misc)
Arguments: expression
Return value: TRUE/FALSE
This function returns a Boolean value, depending on whether the argument is defined. 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")
Category: named unary operator (hash)
Arguments: expression
Return value: value
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")
Category: list operator (I/O)
Arguments: list
Return value: errorlevel
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>" is used, where <line> is the line number of the Perl script.
Example:
die("die() Now we can give an example of die()...exiting")
Category: (flow)
Arguments: block
Arguments: subroutine(list)
Arguments: expression
Return value: special
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")
Category: named unary operator (misc)
Arguments: label
Return value: n/a
This 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. So it is possible to set up a program that initializes data structures to dump() after the initialization so that execution is faster when reloading the dumped image.
Category: named unary operator (hash)
Arguments: variable
Return value: key, value
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). After 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")
Category: (system files)
Arguments: none
Return value: TRUE/FALSE
Closes the /etc/group file used by getgrent() and other group-related functions. 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")
Category: (system files)
Arguments: none
Return value: TRUE/FALSE
Closes the TCP socket used by name server queries gethostbyname() and host-related functions. Equivalent to the UNIX system call.
Example:
$host = gethostbyname("lynch")
$returned = endhostent()
print("endhostent() Closes /etc/hosts [$host] returning $returned.\n")
Category: (system files)
Arguments: none
Return value: TRUE/FALSE
Closes the /etc/networks file used by getnetent() and network-related functions. Equivalent to the UNIX system call.
Example:
($name,$alias,$net,$net) = getnetent()
$returned = endnetent()
print("endnetent() Closes /etc/networks [$name] returning $returned.\n")
Category: (system files)
Arguments: none
Return value: TRUE/FALSE
Closes the /etc/protocols file used by getprotoent() and protocol-related functions. 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")
Category: (system files)
Arguments: none
Return value: TRUE/FALSE
Closes the /etc/passwd file used by getpwent() and password-related functions. 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")
Category: (system files)
Arguments: none
Return value: TRUE/FALSE
Closes the /etc/servers file used by getservent() and related functions. Equivalent to the UNIX system call.
Example:
($name,$aliases,$port,$protocol) = getservent()
$returned = endservent()
print("endservent() Closes /etc/servers [$name] file returning $returned.\n")
Category: named unary operator (I/O)
Arguments: handle
Arguments: ( )
Arguments: none
Return value: TRUE/FALSE
Tests if the file specified by the file handle is at the end of file. This is done by reading the next character and then undoing this operation (so it is only suitable on files when 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, this tests if the last file suppiled an argument to the Perl script is eof() (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
Category: named unary operator (flow)
Arguments: expression
Arguments: block
Arguments: none
Return value: special
This function treats the expression like a Perl program and executes
it returning the return value of the last statement executed.
Because 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. $@ will be equal
to a defined null string if no errors are found. 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 in certain situations).
| Tip |
eval() traps possible error conditions that would otherwise crash a program and so can be used to test whether 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: $@";}
Category: list operator (process)
Arguments: list
Return value: n/a
This function passes control from the script to an external system
command. There is no
return from this call, so there is no return value. Note that
system() calls external commands
and does return.
This is equivalent to the UNIX system call execvp().
Example:
exec("cat /etc/motd")
Category: named unary operator (hash)
Arguments: expression
Return value: TRUE/FALSE
Tests whether 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";}
Category: named unary operator (flow)
Arguments: expression
Arguments: none
Return value: value
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)
Category: named unary operator (numeric)
Arguments: expression
Arguments: none
Return value: numeric
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"
Category: list operator (I/O)
Arguments: handle, function, packed_parameters
Return value:
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 function to the system function that is usually executed when Perl is installed.
Category: named unary operator (I/O)
Arguments: handle
Return value: descriptor
Returns the file descriptor given a file handle.
Example:
print("fileno() ",fileno(INF),"\n")
Category: list operator (I/O)
Arguments: handle, operation
Return value: TRUE/FALSE
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, unlock. These operations are represented by numeric values.
Category: (process)
Arguments: none
Return value: pid
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
# Chlid 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; }
Category: list operator (I/O)
Arguments: format
This function declares an output format specification. These formats are used 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 describes the layout, and the second describes the variables to use in this layout.
Example:
format STDOUT =
format() @>>>>>>> @>>>>>>> @>>>>>>>
$t1, $t2, $t3
$t1 = One
$t2 = Two
$t3 = 3
write
Category: list operator (I/O)
Arguments: picture, list
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
Category: named unary operator (I/O)
Arguments: handle
Arguments: none
Return value: character
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
Category: list operator (system files)
Arguments: none
Return value: name
Returns the next group name (or undefined) in the /etc/group system file. In a list context, returns extra information taken from this file (or null list). Equivalent to the UNIX system call getgrent().
Example:
($name,$pw,$gid,@members)=getgrent()
print("getgrent() Examines /etc/group [$name,$gid] file.\n")
Category: named unary operator (system files)
Arguments: gid
Return value: name
Returns the next group name (or undefined) in the /etc/group system file with the supplied group ID (gid). In a list context, 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")
Category: named unary operator (system files)
Arguments: name
Return value: gid
Returns the next group ID, gid, (or undefined) in the /etc/group system file with the supplied group name. In a list context, returns extra information taken from this file (or null list). Equivalent to the UNIX system call getgrname().
Example:
($grname,$grpw,$gid,@members) = getgrnam("root")
print("getgrnam() Returns group GID given name [$gid]\n")
Category: named unary operator (system files)
Arguments: address
Return value: name
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, returns extra information taken from this file (or null list). 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")
Category: named unary operator (system files)
Arguments: name
Return value: address
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, returns extra information taken from this file (or null list). Equivalent to the UNIX system call gethostbyname().
Example:
($name,$alias,$adrtype,$length,@address)=gethostbyname("lynch")
print("gethostbyname() [$alias].\n")
Category: (system files)
Arguments: none
Return value: name
Returns the next host name (or undefined) in the /etc/hosts system file (or via a domain name server lookup). In a list context, returns extra information taken from this file (or null list). Equivalent to the UNIX system call gethostent().
Example:
($name,$alias,$adrtype,$length,@address)=gethostbyname("lynch")
print("gethostent() [$alias].\n")
Category: (system files)
Arguments: none
Return value: name
Gets the current login name from the /etc/utmp system file. It is better to use the getpwuid() function for more information on the login, because the information stored in /etc/utmp is limited.
Example:
print ("getlogin() ",getlogin(),"\n")
Category: (system files)
Arguments: address
Return value: name
Returns the network name from the /etc/networks system file given a network address. In a list context, returns extra information from this file. Equivalent to the UNIX getnetbyaddr() call.
Example:
($name,$alias,$addrtype,$net) = getnetent()
($name,$alias,$addrtype,$net) = getnetbyaddr($net,$addrtype)
print("getnetbyaddr() Reads /etc/networks [$name]\n")
Category: named unary operator (system files)
Arguments: name
Return value: address
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")
Category: (system files)
Arguments: none
Return value: name
Returns the next network name from the /etc/networks system file. In a list context, returns extra information from this file. Equivalent to the UNIX getnetent() call.
Example:
($name,$alias,$addrtype,$net) = getnetent()
print("getnetent() Reads /etc/networks [$name,$addrtype]\n")
Category: named unary operator (socket)
Arguments: socket
Return value: name
Equivalent to the UNIX system getpeername() system call.
Category: named unary operator (process)
Arguments: pid
Return value: gid
Returns the group ID (gid) of the process with the process ID (pid).
Example:
print("getpgrp() ",getpgrp(0),"\n")
Category: (process)
Arguments: none
Return value: pid
Returns the process ID (pid) if it is the parent process of the current process.
Example:
print("getppid() ",getppid(),"\n")
Category: list operator (process)
Arguments: type, id
Return value: priority
Calls the UNIX getpriority() function. The type is PRIO_PROCESS, PRIO_PGGRP, or PRIO_USER. The id is the relevent id for this (pid, a pid for a group of processes, uid). If zero is used as the id, the current process/process group/user is used.
Example:
print("getpriority() ",getpriority(0,0),"\n")
Category: named unary operator (system files)
Arguments: name
Return value: protocol
Returns the protocol number from the /etc/protocols system file given the protocol name. In a list context, returns extra information from this file. Equivalent to the UNIX getprotobyname() call.
Example:
($name, $alias, $protocol) = getprotobyname("IP")
print("getprotobyname() /etc/protocols [$name,$alias,$protocol].\n")
Category: named unary operator (system files)
Arguments: protocol
Return value: name
Returns the protocol name from the /etc/protocols system file given the protocol number. In a list context, returns extra information from this file. Equivalent to UNIX getprotobynumber() call.
Example:
($name, $alias, $protocol) = getprotobynumber(0)
print("getprotobynumber() /etc/protocols [$name,$alias,$protocol].\n")
Category: (system files)
Arguments: none
Return value: name
Returns the next protocol name from the /etc/protocols system file. In a list context, returns extra information from this file. Equivalent to the UNIX getprotoent() call.
Example:
($name, $alias, $protocol) = getprotoent()
print("getprotoent() Closes /etc/protocols [$name,$alias,$protocol].\n")
Category: (system files)
Arguments: none
Return value: name
Returns the user name from the next entry in the /etc/passwd system file. In a list context, returns extra information from this file. Equivalent to the UNIX getpwent() call.
Example:
($name,$pass,$uid,$gid,$quota,$name,$gcos,$logindir,$shell) = getpwent()
print("getpwent() /etc/passwd [$logindir,$shell].\n")
Category: named unary operator (system files)
Arguments: name
Return value: uid
Returns the user ID (uid) from the /etc/passwd system file given the user name. In a list context, returns extra information from this file. 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")
Category: named unary operator (system files)
Arguments: uid
Return value: name
Returns the user name from the /etc/passwd system file given the user ID (uid). In a list context, returns extra information from this file. 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")
Category: list operator (system files)
Arguments: name, protocol
Return value: port
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, returns extra information from this file. Equivalent to the UNIX getservbyname() call.
Example:
($name,$aliases,$port,$protocol) = getservbyname("tcpmux","tcp")
print("getservbyname() /etc/servers [$name].\n")
Category: list operator (system files)
Arguments: port, protocol
Return value: name
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, returns extra information from this file. Equivalent to the UNIX getservbyport() call.
Example:
($name,$aliases,$port,$protocol) = getservbyport(512,"tcp")
print("getservbyport() Problem with this! [$name]\n")
Category: (system files)
Arguments: none
Return value: name
Returns the next service name of the service from the /etc/services system file. In a list context, returns extra information from this file. Equivalent to the UNIX getservet() call.
Example:
($name,$aliases,$port,$protocol) = getservent()
print("getservent() /etc/servers [$name].\n")
Category: named unary operator (socket)
Arguments: socket
Return value: address
Equivalent to the UNIX getsockname() system call.
Category: list operator (socket)
Arguments: socket, level, option name
Return value: option
Equivalent to the UNIX getsockopt() system call.
Category: named unary operator (files)
Arguments: expression
Return value: list
Returns the list of files resulting from expanding the expression with any wild cards. This is equivalent to <*.*>.
Example:
@files = glob("/tmp/*.txt")
print "glob() ",$files[1],"\n"
Category: named unary operator (time)
Arguments: expression
Arguments: none
Return value: list
Given a time as an argument (measured in seconds since 1st Jan 1970), returns a list of nine elements with that time broken down. If no argument is used, the current time is reported. If the system supports POSIX timezones, the time returned is localized for the Greenwich Mean Time 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) = gmtime()
print "gmtime() 19$year-$mon-$mday\n"
Category: (flow)
Arguments: label
Arguments: expression
Arguments: &name
Return value: n/a
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 to a subroutine from another subroutine, so that the appearance to the original caller is 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"
Category: list operator (lists)
Arguments: expression, list
Arguments: block, list
Return value: list
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")
Category: named unary operator (numeric)
Arguments: expression
Return value: numeric
Evaluates the expression as a hexadecimal string and returns the decimal equivalent.
Example:
print("hex() ",hex("ff"), "\n")
Category: list operator (scope)
Arguments: list
Return value: TRUE/FALSE
In the Perl 5 module system, each module has a local import() method. This is called when use() includes modules.
Category: list operator (string)
Arguments: string substring
Arguments: string substring position
Return value: position
Returns the position in the supplied string where the substring fisrt 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, because it will start its search from $[ if no position argument is supplied, and it will return $[-1 if no match is found.
Example:
$ans1 = index("abcdefghijiklmdef:-)","def")
$ans2 = index("abcdefghijiklmdef","def",$ans1+3)
print("index() def is at $ans1 and next at $ans2\n")
Category: named unary operator (numeric)
Arguments: expression
Arguments: none
Return value: integer
Returns the integer part of the expression. Uses $_ as the argument if none is specified.
Example:
print("int() ",int(345.678), "\n")
Category: list operator (files)
Arguments: handle, function, parameter
Return value: numeric
Calls the UNIX ioctl() function with the specified packed parameter. Returns undefined if the operating system returns -1. Returns the string "0 but true" if the operating system returns 0. Otherwise, returns the value returned by the operating system.
Category: list operator (lists)
Arguments: expression, list
Return value: string
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")
Category: named unary operator (hash)
Arguments: array
Return value: list
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")
Category: list operator (process)
Arguments: signal, list
Return value: TRUE/FALSE
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.
Category: (flow)
Arguments: label
Arguments: none
Return value: n/a
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")
Category: named unary operator (string)
Arguments: expression
Return value: string
Returns the lowercase version of any supplied expression.
Example:
print"lc() ",lc("ABCDef"), "\n"
Category: named unary operator (string)
Arguments: expression
Return value: string
Returns the string with the first character of the expression lowercased.
Example:
print"lcfirst() ",lcfisrt("ABCDef"), "\n"
Category: named unary operator (string)
Arguments: expression
Arguments: none
Return value: numeric
Returns the length of the string specified by expression. If no expression is supplied, $_ is evaluated.
Example:
print("length() ",length("01234"),"\n")
Category: list operator (files)
Arguments: file name, link name
Return value: numeric
Creates a new link named after the second argument linking to the file name specified in the fisrt argument. Returns 1 or 0 for success or failure.
Example:
$result = link("/usr/local",:"/tmp/link")
print("link() $result\n")
Category: list operator (socket)
Arguments: socket, queuesize
Return value: TRUE/FALSE
Equivalant to the UNIX listen() system call.
Category: named unary operator (scope)
Arguments: expression
Return value: n/a
Modifies all the variables listed to be local to the current block. The list must be enclosed in parentheses if there is more than one element. Any errors will 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.
Category: named unary operator (time)
Arguments: expression
Arguments: none
Return value: list
Given a time as an argument (measured in seconds since January 1st, 1970) and returns a list of nine elements with that time broken down. 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"
Category: named unary operator (numeric)
Arguments: expression
Arguments: none
Return value: numeric
Returns the logarithm (using the natural logarithm base e) of the expression (or of $_ if none specified).
Example:
print("log() ",log(2.5),"\n")
Category: named unary operator (files)
Arguments: handle
Arguments: expression
Return value: list
Returns the file statstics of the file pointed to by the file handle (or a file handle produced by evaluating 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 filetest 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")
Category: named unary operator (pattern)
Arguments: m/<pattern>/<optionlist>
Arguments: /<pattern>/<optionlist>
Return value: TRUE/FALSE
Searches the default string for the pattern using regular expression pattern matching. Returns 1 (TRUE) if a match is found and '' (FALSE) otherwise. The default string can be assigned to the match using the =~ or !~ operators; otherwise, it is $_.
Example:
$_ = "Happy MaN"
print "m// ",/n$/i,"\n"
Category: list operator (list)
Arguments: block list
Arguments: expression, list
Return value: list
Evaluates the specified expression (or block) for each indivual member of the specified list. This is done by assigning $_ to each member of the list and evaluting 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")
Category: list operator (files)
Arguments: file name, mode
Return value: 1 or 0
Creates a directory with a name specified by the file name, 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")
Category: list operator (System V)
Arguments: id, cmd, arg
Return value: special
Equivalent to the UNIX system call msgctl() if supported.
Category: list operator (System V)
Arguments: key, flags
Return value: special
Equivalent to the UNIX system call msgget() if supported.
Category: list operator (System V)
Arguments: id, var.size, type, flags
Return value: special
Equivalent to the UNIX system call msgrcv() if supported.
Category: list operator (System V)
Arguments: id, msg, flags
Return value: special
Equivalent to the UNIX system call msgsnd() if supported.
Category: named unary operator (scope)
Arguments: expression
Return value: n/a
Declares each of the variables listed to be local() to the block. If more than one variable is specified, parentheses are required. The may() specification is stronger than the the local() specification, because it not only stops pollution of the global namespace, but creates a stack frame for subroutine calls so that recursive calls will behave as one would expect with local variables.
Category: named unary operator (flow)
Arguments: label
Arguments: none
Return value: n/a
Example:
print("next ")
@array = ("a","b","c")
loop: foreach $elem (@array) {
next if $elem =~ /^a/
print $elem
}
print "\n"
Category: list operator (module)
Arguments: module, list
Return value: n/a
Unimports values imported by use().
Example:
use integer
# code using integer arithmetic here
no integer
# back to floating point arithmetic
Category: named unary operator (numeric)
Arguments: expression
Return value: numeric
This function evaluates the expression as an octal string and returns the decimal value.
Example:
print("oct() ",oct("88"), "\n")
Category: list operator (files)
Arguments: handle, file name
Arguments: handle
Return value: TRUE (nonzero) or FALSE (undefined)
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 file name 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 file name).
The file name string may be prefixed with the following values to indicate the mode: "<" (this is the default), ">" (write), "+>" (read/write-starting with new file), "+<" (read/write using existing file) , ">>" (append), "<command> |" (input pipe-the file name is actually a subshell command from which the file handle is piped), "| <command>"(output pipe-the file name is actually a subshell command to which the output of the file handle is piped). The special file name '-' refers to STDIN '-' or STDOUT '>-'.
Example:
open(FIL,"/tmp/notexist") || print("open() failed as file did not exist.\n")
Category: list operator (files)
Arguments: handle, dirname
Return value: TRUE/FALSE
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")
Category: named unary operator (string)
Arguments: expression
Arguments: none
Return value: numeric
Returns the numeric ASCII code of the first character in the expression (or $_ if none specified).
Example:
print("ord() ",ord("A"), "\n")
Category: list operator (records)
Arguments: template, list
Return value: string
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, with each specifying the data type of the matching data item in the list:
|
| Null fill to absolute position |
|
| ASCII string with spaces to pad |
|
| ASCII string with nulls to pad |
|
| Bit string (ascending bit order) |
|
| Bit string (descending bit order) |
|
| Signed char value |
|
| Unsigned char value |
|
| Double-precision float in the native format |
|
| Single-precision float in the native format |
|
| Hex string (low nybble first) |
|
| Hex string (high nybble first) |
|
| Signed integer value |
|
| Unsigned integer value |
|
| Signed long integer value |
|
| Unsigned long integer value |
|
| Short integer "network" order |
|
| Long integer "network" order |
|
| Pointer to a null-terminated string |
|
| Pointer to a structure (fixed-length string) |
|
| Signed short integer value |
|
| Unsigned short integer value |
|
| UUencoded string |
|
| Short integer "VAX" (little-endian) order |
|
| Long integer "VAX" (little-endian) order |
|
| Null byte |
|
| 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 a * 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")
Category: named unary operator (class)
Arguments: name
Return value: n/a
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 with require() or use(). Note that this applies to variables declared as local() but not to variables declared as my().
Category: list operator (process)
Arguments: readhandle, writehandle
Return value: TRUE/FALSE
Links named pipes like the UNIX function pipe().
Category: name unary operator (array)
Arguments: variable
Return value: value
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")
Category: named unary operator (pattern)
Arguments: variable
Return value: numeric
Returns the offset where the last pattern match (m//g) reached when searching the scalar variable specified as an argument. It can be assigned to in order to alter the behaviour of the next match.
Example:
$name = "alpha1 alpha2 alpha3 alpha4"
$name =~ m/alpha/g
print("pos() ", pos($name), "\n")
Category: list operator (i/o)
Arguments: handle, list
Arguments: list
Arguments: none
Return value: TRUE/FALSE
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")
Category: list operator (I/O)
Arguments: file handle list
Arguments: list
Return value: TRUE/FALSE
This function uses the C printf format specifiers to control the printed output. It is equivalent to the following:
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)
Category: list operator (array)
Arguments: array, list
Return value: numeric
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")
Category: (string)
Arguments: q/string/
Return value: value
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")
Category: (string)
Arguments: qq/string/
Return value: value
This is a double quote used to allow interpolation of special characters within the string as required. You can use a double quoted string ("string") or the double letter 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// This is a normal double quoted string with interpolation! $newline!)
Category: named unary operator (pattern)
Arguments: expression
Return value: string
Returns the value of the expression with all the metacharacters backslashed.
Example:
print(quotemeta("quotameta() I can use any metcharacter $ \ "),"\n")
Category: (list)
Arguments: qw/string/
Return value: list
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")
Category: (process)
Arguments: qx/string/
Return value: special
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!)
Category: named unary operator (numeric)
Arguments: expression
Arguments: none
Return value: numeric
This function returns a real number between 0 and the number evaluated as the expression (the upper limit is 1 if no expression is specified). The upper limit must be positive. Because the function calls a pseudo random 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")
Category: list operator (I/O)
Arguments: handle, variable, length, offset
Arguments: handle, variable, length
Return value: TRUE/FALSE
Reads length bytes from file handle into variable (starting at offset if specified). Returns 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)
Category: list operator (I/O)
Arguments: dirhandle
Return value: lname
In a list context, returns a list of the files in the directory specified by the directory handle. In a scalar context, returns the next file name in the directory.
Example:
opendir(DIR,"/tmp")
@file = readdir(DIR)
print("readdir() ",@files, "\n")
Category: named unary operator (files)
Arguments: expression
Arguments: none
Return value: value
Returns the value of the symbolic link specified by expression (or $_ if none specified). If symbolic links are not implemented, gives a fatal error. If symbolic links are supported, but there is some system error, this is returned in $OS_ERROR ($!).
Category: list operator (socket)
Arguments: socket, variable, length, flags
Return value: address
Equivalent to the UNIX system call recv().
Category: (flow)
Arguments: label
Arguments: none
Return value: n/a
Passes control directly to the label without executing any continue block. If no label is specified, the innermost loop is used.
Category: named unary operator (class)
Arguments: expression
Return value: package
Returns the package of a bless()ed variable. Otherwise, returns TRUE if the variable is a reference and FALSE otherwise. The return value for TRUE is actually the type of the variable (for example, ARRAY, HASH, REF, and SCALAR).
Example:
$tmp = {}
bless $tmp, ATMPCLASS
print "ref() \$tmp is now in class ",ref($tmp),"\n"
Category: list operator (files)
Arguments: oldname, newname
Return value: 1 (true) 0 (fail)
Renames files on the same file system from their old name to their new name.
Example:
$returned = rename("/tmp/test","/tmp/test2")
print("rename() returned $returned \n")
Category: named unary operator (module)
Arguments: expression
Arguments: none
Return value: TRUE/FALSE
If the expression is a scalar, the library specified by the file name 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, $[) is greater than or equal to the version specified.
Note that Perl 5 also has the use() mechanism for including modules, which is more robust.
Example:
require "cgilib.pl"
Category: named unary operator (misc)
Arguments: expression
Arguments: none
Return value: 1
This 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, it simply resets all search matches.
| Caution |
Use of this operator can reset system variables you might not want to alter. Be very careful with the following, for example: reset A-Z; |
Category: list operator (flow)
Arguments: list
Return value: list
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")
Category: list operator (list)
Arguments: list
Return value: list
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")
Category: named unary operator (I/O)
Arguments: dirhandle
Return value: TRUE/FALSE
When reading a directory using readdir(), it is possible to reset the directory to the first file name using rewindddir().
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)
Category: list operator (string)
Arguments: string, substring, position
Arguments: string, substring
Return value: position
This function is very similar to index() except that, instead of scanning for the substring from the first character in the string, it scans backward from the last character. So it returns the starting position of the last occurance of substring in string (starting at position if specified but scanning backward from there).
Example:
$ans1 = rindex("abcdefghijiklmdef:-)","def")
$ans2 = rindex("abcdefghijiklmdef","def",$ans1+3)
print("rindex() def is at $ans1 and next at $ans2\n")
Category: named unary operator (files)
Arguments: file name
Return value: 1 or 0
Deletes the directory specified (or $_ if it is empty). Sets $OS_ERROR ($!) on system error.
Category: (pattern)
Arguments: s/pattern/replacement/options
Return value: numeric
Searches the default string for pattern (a regular expression)
and replaces this with the replacement string (the actual replacement
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 follow:
| Evaluate the right side as an expression | |
| Global (replace all occurrences) | |
| Case-insensitive pattern matching | |
| Ignore \n in string (multiple lines) | |
| Optimize (compile pattern once) | |
| Treat string as single line | |
| Extended regular expressions |
Example:
$oldstr = "abcdefABCDEFabcdefABCDEF"
$newstr= $oldstr
$str =~ s/abc/zzz/ig
print("s/// $oldstr became $newstr \n")
Category: named unary operator (misc)
Arguments: expression
Return value: value
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.
Category: list operator (I/O)
Arguments: handle, position, start
Return value: TRUE/FALSE
This function sets the file pointer to a specified offset position in a file. The offset is relative to the start, which can have three values: 0 (start of file), 1 (current position), or 2 (end of file). This allows the use of random-access files and the implentation of fast read algorithms (for example, binary search techniques) on file handles, especially with fixed-length data where the offsets are easier to calculate.
Category: list operator (I/O)
Arguments: dirhandle. position
Return value: TRUE/FALSE
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().
Caamed unary operator (I/O)
Arguments: handle
Aruments: rbits, wbits, ebits, timeout
Return value: handle
This operator selects the default file handle used for input/ouput 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")
Category: list operator (System V)
Arguments: id, semnum, command, arg
Return value: value
Equivalent to the UNIX semctl() function.
Category: list operator (System V)
Arguments: key, nsems, flags
Return value: value
Equivalent to the UNIX semget() function.
Category: list operator (System V)
Arguments: key, opstring
Return value: TRUE/FALSE
Equivalent to the UNIX semop() function call.
Category: list operator (socket)
Arguments: socket, message, flags, to
Arguments: socket, message, flags
Return value: numeric
Equivalent to the UNIX system send() function.
Category: (system files)
Arguments: none
Return value: n/a
Rewinds the /etc/group file to the start of the file for subsequent accesses using getgrent().
Example:
print("setgrent() ",setgrent(), "\n")
Category: named unary operator (system files)
Arguments: flag
Return value: n/a
If called with an argument of 1, tells the system to keep a TCP socket open for name server queries such as gethostbyname(). If this is not, then then name server queries use UDP datagrams.
Example:
print("sethostent() ",sethostent(1), "\n")
Category: named unary operator (system files)
Arguments: flag
Return value: n/a
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")
Category: list operator (process)
Arguments: pid, pgrp
Return value: TRUE/FALSE
This function sets the current process group for the specified process (pid); if this is zero, the current process is set.
Category: list operator (proxess)
Arguments: type, id, priority
Return value: TRUE/FALSE
Calls the UNIX setpriority() function. The type is PRIO_PROCESS, PRIO_PGGRP, or PRIO_USER. The id is the relevent id for this (pid, a pid for a group of processes, uid). If zero is used as the id, the current process/process group/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")
Category: named unary operator (system files)
Arguments: flag
Return value: TRUE/FALSE
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")
Category: (system files)
Arguments: none
Return value: TRUE/FALSE
Rewinds the /etc/passwd file used by getpwent() and other password-related functions.
Example:
print("setpwent() ",setpwent(), "\n")
Category: named uanry operator (system files)
Arguments: flag
Return value: TRUE/FALSE
Rewinds the /etc/services file used by getservent() and other service-related functions. If the flag has a value of 1, the file is kept open between calls to getservbyname() and getnetbyport().
Example:
print("setservent() ",setservent(1), "\n")
Category: list operator (socket)
Arguments: socket, level, optname, optval
Return value: TRUE/FALSE
Equivalent to UNIX system call setsockopt().
Category: named unary operator (array)
Arguments: array
Arguments: none
Return value: value
This functions takes the leftmost element from the array specified and returns that, reducing the array by one element. If 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")
Category: list operator (System V)
Arguments: id, cmd, arg
Return value: value
Equivalent to the UNIX shmctl() function.
Category: list operator (System V)
Arguments: key. size, flags
Return value: value
Equivalent to the UNIX shmget() function.
Category: list operator (System V)
Arguments: id, var. pos, size
Return value: value
Equivalent to the UNIX shmread() function.
Category: list operator (System V)
Arguments: id, string, pos, size
Return value: value
Equivalent to the UNIX shmwrite() function.
Category: list operator (socket)
Arguments: socket, how
Return value: TRUE/FALSE
Equivalent to the UNIX shutdown() function.
Category: named unary operator (numeric)
Arguments: expression
Arguments: none
Return value: numeric
Returns the sine of the expression in radians. If there is no explicit argument, $_ is used.
Example:
print("sin() ",sin(4), "\n")
Category: named unary operator (process)
Arguments: expression
Arguments: none
Return value: numeric
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")
Category: list operator (socket)
Arguments: socket, domain, type, protocol
Return value: value
Equivalent to the UNIX socket() system call.
Category: list operator (socket)
Arguments: socket1, socket2, domain, type, protocol
Return value: value
Equivalent to the UNIX socketpair() system call.
Category: list operator (list)
Arguments: subname list
Arguments: block list
Arguments: list
Return value: list
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 sort 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")
Category: list operator (array)
Arguments: array, offset, length, list
Arguments: array, offset, length
Arguments: array, offset
Return value: list
Removes the elements specified by offset and length from the array, replacing 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")
Category: list operator (pattern)
Arguments: /pattern/,expression,limit
Arguments: /pattern/,expression
Arguments: /pattern/
Arguments: none
Return value: list
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 is not specified, white space is the default). An optional limit restricts the number of elements returned. A negative limit has no effect; no limit is imposed.
If not in a list context, the number of elements found is returned. In an scalar context, returns the number of elements and puts the resulting array into the @_ array (the use of the @_ as the result is depreciated).
Example:
print("spilt() ",split(/:/,"1:2:3:4:5"),"\n")
Category: list operator (string)
Arguments: format, list
Return value: string
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 allows for the explicit formatting of floating point and integer numbers (also allowing binary, hexadecimal, and octal formats).
Example:
print("strintf() ",sprintf("%0d \n",9),"\n")
Category: named unary operator (numeric)
Arguments: expression
Return value: numeric
Returns the result of evaluating the expression and finding its square root.
Example:
print("sqrt() ",sqrt(4),"\n")
Category: named unary operator (numeric)
Arguments: expression
Arguments: none
Return value: TRUE/FALSE
This functions sets the seed used by the pseudo random 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 pseudo random data generated using rand(), it is possible to generate exactly the same data repeatedly (without having to save the entire sequence) simply by setting and saving the seed. Restoring the seed and calling rand() then produces the same sequence again.
Example:
srand(26)
print("rand() ",rand(),", ")
srand(26)
print(rand()," (should produce the same \"random\" number twice) \n")
Category: list operator (files)
Arguments: handle
Arguments: expression
Arguments: none
Return value: list
Returns the file statistics of the file pointed to by the file handle (or a file handle produced by the evaluating expression). Note that, like the filetest operators, stat() can take a special argument underscore (_), which means that the test is carried out on the same filehandle as the last filetest, 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")
Category: named unary operator (pattern)
Arguments: scalar
Arguments: none
Return value: TRUE/FALSE
When many pattern match operations are being performed on the same string, the efficiency of these patterns can be improved by the use of 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 processs the pattern match more quickly. Only one string at a time can be studied (subsequent calls effectively "unstudy" any previous study()). 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.
Category: (flow)
Arguments: name block
Arguments: name
Arguments: name
Return value: value
This is the syntax for a subroutine declaration. The full form defines a subroutine with the name and associates this with the statements in the block. When envoked, it returns 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 that is declared fully later in the script.
Category: list operator (string)
Arguments: expression, offset, length
Arguments: expression, offset
Return value: string
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-hand side of the string instead of the left-hand 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")
Category: list operator (files)
Arguments: oldfile, newfile
Return value: 1 or 0
This functions creates a symbolic link from the existing file specified by the old file to the specified new file. Returns 1 on success and 0 on failure. If symbolic links are not supported by the operating system, this returns a fatal error.
Example:
print("symlink() ",symlink("/usr/local","/tmp/symlinktousrlocal"),"\n")
Category: list operator (I/O)
Arguments: list
Return value: varies
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 declare all these calls. The script h2ph, which 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. Because these calls actually pass control to the relevant C system function, care must be taken with passing parameters.
The first element in the list used as an argument to syscall() itself is the name corresponding to the UNIX system call (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")
Category: list operator (I/O)
Arguments: handle, name, mode, permissions
Arguments: handle, name, mode
Return value: TRUE/FALSE
This function calls the UNIX C open() function directly from the Perl script.
Category: list operator (I/O)
Arguments: handle, scalar, length, offset
Arguments: handle, scalar, length
Return value: TRUE/FALSE
This function calls the UNIX C read() function directly from the Perl script.
Category: list operator (process)
Arguments: list
Return value: status
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")
Category: list operator (I/O)
Arguments: handle, scalar, length, offset
Arguments: handle, scalar, length
Return value: TRUE/FALSE
This function calls the UNIX C write() function directly from the Perl script.
Category: named unary operator (I/O)
Arguments: expression
Arguments: none
Return value: position
This function returns the current position in the file specified by the expression (which should evaluate to a filehandle). 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")
Category: named unary operator (I/O)
Arguments: dirhandle
Return value: position
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")
Category: list operator (class)
Arguments: variable, classname, list
Return value: object
This functions 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 has the effect of hiding 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 stores the information about the machine on which Perl has been installed. It is possible to bind an associateive 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")
Category: named unary operator
Arguments: variable
Return value: object
| New to version x |
This was first implemented in Perl 5.002 |
This function returns a reference to the object of which the variable is an instance. This is same as that returned by the original call to tie() when it was bound.
Category: (time)
Arguments: none
Return value: time
Returns the time in seconds since January 1st, 1970. The format can be converted into more useful parts using gmtime() or localtime().
Category: (process)
Arguments: none
Return value: list
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")
Category: (string)
Arguments: tr/searchlist/replacelist/<options>
Return value: numeric
This function translates all occurrances 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 follow:
| Complement (non-matching characters in search list are used) | |
| Delete (delete any characters not in search list as well as translating) | |
| Squash (if the translation results in a sequence of repeated characters from the replace list, reduce this to one occurance of the character) |
The search list and the replace list may contain the-character to indicate a range of characters.
Example:
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
Category: list operator (I/O)
Arguments: handle, length
Arguments: expression, length
Return value: TRUE/FALSE
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.
Category: named unary operator (string)
Arguments: expression
Return value: string
Returns an uppercase version of the specified expression.
Example:
print("uc() ",uc("This is All Caps"), "\n")
ucfirst
Category: named unary operator (string)
Arguments: expression
Return value: string
Returns a string with the first character of the expression in uppercase.
Example:
print("ucfirst() ",ucfirst("this is Capitalized"), "\n")
Category: named unary operator (files)
Arguments: newumask
Arguments: none
Return value: oldumask
Sets the file mask using the specified newumask. Returns the oldumask so that it can be stored and restored later if required. If called without any arguments, 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")
Category: named unary operator (misc)
Arguments: expression
Arguments: none
Return value: value
Undefines the value of the expression. The expression may be a scalar value and array or a subroutine (specified with a & prefix). When called without an expression, it returns an undefined value.
Category: list operator (files)
Arguments: list
Return value: numeric
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")
Category: list operator (data)
Arguments: template, expression
Return value: list
This function unpacks data 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.
Category: list operator (array)
Arguments: array, list
Return value: numeric
Prepends the list to the front of the specified array. 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")
Category: named unary operator (class)
Arguments: variable
Return value: TRUE/FALSE
Undoes the binding between a variable and a package class that was created using tie().
Category: list operator (module)
Arguments: module, list
Return value: n/a
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, 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 arithmetic to be integer based by using this:
use integer;
And then this can be turned off again with this:
no integer
Category: list operator (files)
Arguments: list
Return value: numeric
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 (seconds since January 1st, 1970, for example) as returned by the time() function.
Example:
$time = now
print("utime() ",utime($time,$time,"/tmp/t.tst"),"\n")
Category: named unary operator (hash)
Arguments: variable
Return value: list
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("vaules() ",values(%a),"\n)
Category: list operator (fixed)
Arguments: expression, offset, bits
Return value: value
This function uses the string specified by expression as a vector of unsigned integers. The return value is the value of the bit field specified by offset. The specified bits is the number of bits 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")
Category: (process)
Arguments: none
Return value: pid
Waits for a child process to exit. Returns the process ID (pid) of the terminated process, and ¥1 if there are no child processes.
Category: list operator (process)
Arguments: pid, flags
Return value: pid
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 flag's value of 0 should work on all operating systems supporting processes.
Category: (flow)
Arguments: none
Return value: TRUE/FALSE
This function returns TRUE if the current context is an array context; otherwise it returns FALSE. 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
Category: list operator (I/O)
Arguments: list
Return value: TRUE/FALSE
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().
Category: list operator (I/O)
Arguments: expression
Arguments: handle
Arguments: none
Writes a formatted record to the file handle (or the file handle to which the expression evaluates). If no file handle is specified, the default is STDOUT, but 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 by using the $FORMAT_NAME ($~) special variable.
Category: (string)
Arguments: y/searchlist/replacelist/<options>
Return value: numeric
The operator y/// is a synonym for the translation operator tr///.