appendix A

Perl 5 Function and Variable Reference

This appendix presents a brief alphabetic synopsis of all available Perl functions to enable you to quickly look up the functions' syntax. This appendix is not intended to provide a complete, exhaustive reference. For a complete documentation set on Perl 5, you can visit the CPAN site described in the following note.

Here are a few points to note when using this appendix:

• Parameters to functions can be specified either with or without parentheses. For example, the following two statements are equivalent:
  alarm 3;
  alarm (3);
  The placeholders for variables are shown in italics or all uppercase. A placeholder is a generic term for which you are to substitute specific information. Where all uppercase characters are used, the placeholder implies a handle to a system resource such as a file, directory, pipe, or socket. For example, when the context is relevant, the word SOCKET implies a handle to a socket.
• All optional parameters (and related semicolons) are listed in square brackets. Do not include the square brackets in your code for this syntax. For example, the bless function can take one or two parameters, so it's listed as follows:
  bless REFEREncE[,CLASS]
  which means that you can make these two calls:
  bless $this,
  bless $this,myClass
  but not this call:
  bless $this,[myClass]
• When there is more than one type of parameter as an argument or a list of arguments to a function, all such types of syntax are listed.
• A code block refers to a set of Perl statements within a pair of curly braces. The code block includes the surrounding curly braces if there is more than one statement in it. For example, the do command is really written as follows:
  
  do {
  something here
  something there
  more code
  statement...
  }
• The code block above is shown in italics for the do loop.

-X [FILEHANDLE or Expression]

The -X command is a unary file test operator. X can take one of the following values:

The -X operator takes one argument: a filename or a file handle. Then it applies a test with the associated file for what's requested. It uses $_ if no argument is given. The exception to this rule is the -t test, which defaults to using STDIN. The function returns 1 if the tested condition is true; otherwise, it returns false. The precedence for this operator is the same as any other named unary operator. The arguments into this function may be parenthesized like any other unary operator.

The permission operators (-r, -R, -w , -W, -x, and -X ) test the umask file permissions and those of the calling program's uids and gids. Other reasons why you can't actually read, write, or execute the file are ignored. When tested while a program is running as root, the read/write flags will always return 1 as the test. The values from the -x and -X return 1 only if any execute bit is set. It's probably better to use the stat() function instead to figure out the mode of the file.

The -T and -B switches determine the type of file by looking at the first few blocks of the file. If there are non-ASCII characters in there, the file is assumed to be binary. Control codes generally have the highest bit set, which is what Perl looks for. Also, any file containing null in the first block is considered a binary file.

If -T or -B is used on a file handle, the current input buffer is examined rather than the first block. Both -T and -B return TRUE on a null file or from a file pointer at EOF when testing a file handle. To be able to perform a -T or -B test on a file, you have to be able to read it. To test for readability, use the -f option along with the -T or -B flag: -f $file && -T $file. Like the stat() operator, the special handle referred by the underscore (_) is the last file handle used. This shortcut does not work with -t.

abs value

The absolute value of its argument. Non-numeric arguments return a value of 0.

accept newSocket, oldSocket

This call is used to accept an incoming packet. The return value is the packed address if successful, or FALSE if not successful. The underlying call is the same as the accept() system call in UNIX. See Chapter 12, "Using Sockets."

alarm seconds

Sets up a timer to send the SIGALRM signal to a process after the approximate number of seconds in the argument have passed. Each call to alarm resets any previous timer. A value of 0 for the timer disables any previous timer. The returned value is the number of seconds on the previous timer. Don't use the sleep() call with the alarm call in the same code block because they share the same internal Perl variables in two different ways.

atan2 Y,X

Returns the arctangent of Y/X. The returned value is guaranteed to be in the range [-PI , PI].

bind socket,name

Used to bind a network address to a socket. Returns TRUE on success or FALSE on any failure. The name must be a packed address of the appropriate type for the socket. See Chapter 12.

binmode FILEHANDLE

Forces binary mode on the file specified by the FILEHANDLE handle. Those files not in binary mode will have the CR, LF line termination translated to LF on input, and LF to CR,LF on output, in non-UNIX systems. The FILEHANDLE may be the value of an expression.

bless REFEREncE[,CLASS]

The bless function forces the REFEREncE referenced object to be an object of the type ClassName. If no ClassName is specified, the current class name is used. The REFEREncE value is returned by this function. The bless function is usually the last item called in a constructor for an object.

Note that the two-argument version is the preferred way of calling the bless function. The one-argument function might cause the wrong class to be bless-ed if the class is inherited by a derived class.

chdir newDir

Sets the current working directory to the value in newDir. The function returns TRUE if the change was okay, FALSE if not.

chmod mode listOfFileNames

Works like the chmod command in UNIX. The first argument is an octal number of the bits or the UNIX mode (for example +w) to set in the list of filenames that follow. Returns the number of files whose mode was successfully changed.

chomp variable
chomp list
chomp

The chomp function removes the ending part of a line if the terminating characters are of the same value as the $/ variable. The function returns the number of characters removed. If variable is omitted, the $_ variable is chomp-ed. If you set $/ to "", all blank lines are removed. If you chomp a list, each element is chomp-ed, and the total number of characters removed is returned. Like chop, the chomp function can be used on the results of expressions:

chomp($users = `who`);
             chomp($answer = <STDIN>);

chop variable
chop list
chop

Removes the last character from a string. If no variable or list is specified, chop uses the $_ variable. If the input to chop is a list, it removes the last item in the list. If the input to chop is a string, it removes the last character in the string. The last item chop-ed is the return value.

chown uid gid listOfiles

Change the owner with uid and group with gid of a list of files. The function returns the number of files successfully changed. Caller must have permissions to write on the files you are modifying. Both uid and gid must be numbers or evaluate to numbers.

chr number

Returns the character for the underlying operating system given its index in a character set.

chroot rootDir

Makes the value in rootDir the root directory for all relative pathnames used in the application. The current working directory is not changed. chroot uses $_ if no argument is specified. This only works if you are running this script as superuser.

close

Closes the file, socket, or pipe associated with the file handle. Returns TRUE if all the buffers are flushed and the system call to close the file, pipe, or socket succeeds. Re-opening a file with the open() file closes the file automatically. The $. variable for line counts is reset to zero when a file is closed, but not when the file is re-opened. Closing a pipe causes the calling process to wait for the process executing on the pipe to complete. Closing a pipe explicitly also puts the status value of the current command in a pipe into $?.

closedir

This function closes a directory opened by opendir().

connect SOCKET,name

Connects using sockets to a remote socket. Returns TRUE if it succeeded, FALSE otherwise. The name should be a packed address of the appropriate type for the socket. See Chapter 12.

continue code block continue

Processes the next item in a loop. Execute the code block before proceeding to the top of the loop.

cos Expression

Returns the cosine of Expression whose value must be expressed in radians. Use the $_ if no variable is specified.

crypt

Uses a function similar to the UNIX crypt() function to encrypt the passed text using the value in salt.

dbmclose hash

Breaks the binding between a DBM file and an associative array.

dbmopen hashName,DBname,mode

This call binds a Perl supported DB file to an associative array. DBname is the name of the database without any extensions. The mode is the permissions with which to open the database. The default database is sdbm. If you don't have write access to the DB file, all your assignments will not be written to disk and instead will trigger a trap instruction.

defined Expression

Returns true if the Expression is assigned a value and returns false if the value of Expression is not defined (undef). If applied to a hash array element, it tells you whether the key exists for the hash.

delete Expression

Deletes the specified Expression from a hash. The deleted value is returned. Note that any deletions on the %ENV array modify the environment variables for a program. Deleting a hash entry that's mapped to a disk file with tie() will delete the entry from the disk file. Deleting from a tied hash always returns undef.

die Message

The die() function is the de facto bailout function for a Perl script. The most common use is to include the $! variable to provide some error message of why it died. In a script, die() prints the Message to the standard error and exits with the value in $!. If $! is zero, the value of ($?>>8) is returned. If the value of $? is zero, a value of 255 is returned. Inside an eval() block, the Message is placed into the $@ variable and the eval() block is terminated with 'undef'.

If the message does not end in a newline, the line number of the script and the line number of the input is also printed along with a newline.

do code block

Returns the value of the last command in the sequence of commands in the code block. The do command executes the code block at least once.

do Expression

Uses the value of Expression as a filename and executes the contents of the file as a Perl script. Its use is the same as eval `cat filename.pl`;.

dump Label

Forces a core dump for later use with the undump command. When the core is undump-ed, the new code jumps to the location at Label with the environment restored as much as possible.

each HASH

This function returns a two-item list-the first item is the key and the second is the value at the key in a hash. The each function can be used in an iterative loop because it returns null at the end of the array. Calling each() after getting a null value causes it to start over from the first {key, value} pair in the hash. Do not add elements to an array while you're iterating over it. There is a single iterator for each associative array that is shared by all each(), keys(), and values() function calls in a program.

endpwent
endgrent
endhostent
endnetent
endprotoent
endservent

These functions perform the same function as the underlying system call.

eof FILEHANDLE
eof ()
eof

This function returns true if the next read on FILEHANDLE returns end of file or if FILEHANDLE is not open. If no FILEHANDLE is specified, the last file handle used in a statement is assumed. The FILEHANDLE may be an expression whose value gives the real file handle. This function should not be used for reading from the console. If used in a while (<>) loop, the eof() call is valid for each file being read.

eval
eval Expression
eval code block

Evaluates the expression passed to it just like a Perl program and returns the value of the last expression evaluated. A return statement may be used in an eval() statement. The call returns an undefined value if there is a runtime error or if the die() call is made. The $@ variable is set to the error message. If there was no error, $@ is set to null. The eval() call uses $_ if no expression is given. The final semicolon in a code block is not necessary.

exec command [args ... ]

The exec() function executes a system command and does not return. This call is generally made after a fork() call. The arguments to the exec command include the command to execute in the first argument, followed by any arguments to that command.

exists Expression

Checks if a key exists in a hash. Returns true if the key does exist, and null if it does not.

exit Expression

Exits with the value from the Expression evaluation. If no Expression is given, it exits with a value of 0.

exp Expression

Returns the natural logarithm base to the power of Expression. Uses $_ if no Expression is given.

fcntl FILEHANDLE,function,scalar

Implements the fcntl(2) function and requires the Fcntl module.

fileno FILEHANDLE

Returns the file descriptor id for a file handle and is used with the select() call. The FILEHANDLE may be an expression whose value would be used as the name of the file handle.

flock FILEHANDLE,operation

Calls the system function flock(2) on FILEHANDLE. Returns true on success and false on failure. The flock function locks files, not records within files-but it's portable across platforms, especially if the locked files exist across the network.

fork

This is a fork(2) system call. Upon return, the parent process gets the child pid, and the child process gets a 0. The parent process gets undef in case of errors. It's a good idea to set $| to 1 before a fork or to call the autoflush(FILEHANDLE) function to flush any pending output before the fork call because buffers are not automatically flushed by fork().

format

The format command. See Chapter 19, "Generating Reports."

getc
getc FILEHANDLE

Does a getc() I/O call to get the next character from the input file specified in FILEHANDLE. It returns null if at end of file. If no FILEHANDLE is specified, getc uses STDIN for input.

getgrgid GID
getpwuid UID

Gets the password or group file entry from the user or group ID. Each function performs the same function as the underlying system call.

gethostbyname name
getnetbyname name
getprotobyname name
getservbyname name,protocol
gethostbyaddr addr,addressType
getnetbyaddr addr,addressType

These functions perform the same function as the underlying system call to return the net structure. See networks(5) in the UNIX manuals.

getlogin

Gets the current login name from /etc/utmp, if any. It's better to use getpwuid($<).

getpeernam socket

Gets the packed sockaddr structure with the socket address of the remote computer at the end of a socket connection.

getpgrp pid

Gets the current process group for the specified pid. You can use 0 or null for specifying the current process.

This function may raise a fatal exception if the underlying system call is not supported.

getppid

Gets the process ID of the parent process.

getpriority processID
getpriority UID

Gets the current priority for a process, a process group, or a user using the getpriority(2) system call. This function may raise a fatal exception if the underlying system call is not supported.

getprotobynumber number

Returns the protocol by number.

getpwent
getgrent
gethostent
getnetent
getprotoent
getservent

These functions perform the same function as the underlying system call.

getpwnam name
getgrnam name

Gets the password or group file entry given a name. This function performs the same function as the underlying system call.

getservbyport port, proto

This function performs the same function as the underlying system call. The port is the port number to use for the given protocol in proto. Check out the file /usr/include/net.h for these values.

getsockname SOCKETHANDLE

Gets the packed sockaddr structure with the address of the local end of a socket connection.

getsockopt SOCKETHANDLE,level,optname

Gets the socket option requested, or is undefined if there is an error. This function performs the same function as the underlying system call.

glob Expression

Expands the value of Expression to filenames just like a shell operation.

gmtime Expression

Converts the time value returned by the time() function to a nine-element array adjusted for the standard Greenwich time zone. All returned array elements are numeric and come straight out of a struct tm defined in /usr/include/time.h.

goto LABEL
goto Expression
goto &name

The goto LABEL form jumps to the statement labeled with LABEL. You cannot jump into a subroutine or within a loop. The Expression is used for computed GOTOs. GOTO &name substitutes a call to the named subroutine for the currently running subroutine. The code returns back from the newly referenced subroutine.

grep Codeblock @list
grep Expression, @list

Runs grep on the Codeblock or Expression for each element of @list by setting $_ to each element in the @list. The return value is a list of all the elements that matched the grep expression. For example, @freds = grep(/fred/, @users); gets all the strings with the word fred in @users.

hex Expression

Evaluates Expression as a hex string and returns the corresponding decimal number.

import moduleName

Used to import other modules into a program.

index string,substr,[position]

Gets the position of the first occurrence of substr in str at or after the optional parameter, position. If position is omitted, a search is started from the beginning of the string. The return value is indexed from 0 or h, the value in the $[ variable. Returns -1 or ($[ - 1) if no substr was found.

int Expression

Parses the Expression to return the integer portion. If Expression is omitted, $_ is used to parse for integer.

ioctl FILEHANDLE,function,scalar

Implements the ioctl(2) function. See Chapter 15, "Direct Access to System Facilities."

join Expression,list
join Expression,@array

Creates a string from elements of a list or array. Uses the value of Expression as the separator of items in the string.

keys %hash

Returns an array whose members are all the keys of the named hash. For example, you can get the environment variables with @keys = keys %ENV;.

kill Signal @List-of-PIDs

Sends a signal to the list of processes whose process IDs (PID) are listed in the @List-of-PIDs. The first element is the signal to send. The function returns the number of processes successfully signaled.

last [LABEL]

This function breaks out of a loop in which it's used. Usually, it only breaks out of the inner-most loop. If a LABEL is specified, the code jumps to the statement after the end of the current loop.

lc String

Returns a lowercase version of String.

lcfirst String

Returns the value of String with the first character lowercased.

length [String]

Returns the length in characters of the String. If String is not provided, $_ is used.

link Oldfile,Newfile

Creates a link from old file to a new filename; returns true on success and false on failure.

listen Socket,Queuesize

Works like the listen system call. Returns true on success, false otherwise.

local variable[,variable[,variable ... ]]

Creates local variables in a subroutine or other code block. A local variable is visible to other code blocks nested within the scope of where a local variable is declared. More than one variable may be declared local on one line. See the my() function. Use parentheses when specifying more than one variable.

localtime Expression

Converts a time value returned by the time() function to a nine-element array with values for the local time zone. The values returned correspond to the tm structure in the file /usr/include/time.h.

log Expression

Returns natural log of Expression. If the Expression is not provided, it returns natural log of $_.

lstat FILEHANDLE
lstat Expression

Works just like the stat() system call. Works on links instead of on a linked file.

map CodeBlock, @list
map Expression, @list

Evaluates the code block or Expression for each element of @ilist by setting $_ to each element in @list. Returns a list of element $_ to each element and returns the list value composed of the results of applying the code block or Expression to @list. For example, the following function returns a list of @names with all lowercase strings:

@allLower = map(lc, @names);

mkdir dirName,permissions

Makes a directory specified by dirName with the permissions specified in the argument. Upon success, it returns 1; otherwise it returns 0.

msgctl QueueID,Action,Arguement

The System V Ipc function msgctl(2) is called here. See Chapter 13, "Message Facilities: The System V Ipc Functions."

msgget KEY,flags

The System V Ipc function msgget(2) is called here. See Chapter 13.

msgrcv QueueID,Var,Sz,Type,flags

The System V Ipc function msgrcv is called here.

msgsnd QueueID,Message,flags

Calls the System V Ipc function msgsnd(2) to send the Message to the message QueueID. The Message must begin with a long integer message type. Returns true if successful and false on error.

my Expression

The my function declares the listed variables to be local to the enclosing block, subroutine, eval, or do/require/use file. Use parentheses when specifying more than one variable. Variables declared as my are not seen by code blocks within the scope of the current block.

next LABEL
next

The next command starts the next iteration of a loop or jump to LABEL. For nested loops, it jumps to the innermost enclosing loop.

no Module[,Module[,Module...]]

The opposite of the use function.

oct Expression

Returns an octal number after parsing Expression. Returns a hex number if the Expression begins with 0x.

open FILEHANDLE[,filename]

Opens the file whose filename is given by filename and associates it with FILEHANDLE. If filename is not specified, the scalar variable of the same name as the FILEHANDLE contains the filename. If the filename begins with >, the file is opened for writing. If the filename begins with >>, the file is opened for appending. If the filename begins with nothing or <, the file is opened for reading. Put + in front of > or < to indicate that you want both read and write access to the file. The +< is for read/write updates, whereas the +> mode overwrites files. If the filename begins with |, the filename is used as a command to which all output to the FILEHANDLE will be piped. If the filename ends with |, the filename is used as a command from which to read input. The - is a synonym for STDIN, and >- is a synonym for STDOUT. Prepending a filename with >& duplicates and opens a new file handle.

Open returns non-zero upon success or the undefined value on error. To do an implicit fork(), use |- or -|. The return value is 0 in the child and the pid of the child in the parent. The STDIN and STDOUT of the child is initially tied to the file handle in the parent.

When working on a pipe, the return value happens to be the pid of the subprocess. Closing any piped file handle causes the parent process to wait for the child to finish and returns the status value in $?.

opendir DIRHANDLE,dirname

Opens a directory named dirname for processing by readdir(), telldir(), seekdir(), rewinddir(), and closedir(). Returns TRUE if successful. DIRHANDLEs have their own name space separate from FILEHANDLEs.

ord [String]

Gets the numeric ASCII value of the first character in String. Uses value of $_ no string is specified.

pack template,@list

Packs a list into a binary structure and returns a string with the structure. The template is a sequence of characters that give the order and type of values.

Each letter may optionally be prepended by a number to allow it to be repeated. Use a * for the repeat count to all remaining items in a list. The pack function will use as many values as needed but requires specifications for a, A, b, B, h H, and `P.

package nameSPACE

Used for declaring packages. See Chapter 4, "Introduction to Perl Modules."

pipe readhandle,writehandle

Creates a pair of connected pipes, like the corresponding system call. See Chapter 14, "Signals, Pipes, FIFOs, and Perl."

pop @array

Removes and returns the last value of an array. The array is shortened by one element. Returns undef if @array is empty. Uses the @ARGV array in the main program or the @_ array in subroutines if the @array is not specified.

pos ScalarVariable

Returns the offset of where the last matched search left off for the scalarVariable.

print [FILEHANDLE] LIST

Prints a string or a comma-separated list of strings. Returns true if successful. Writes to FILEHANDLE when specified or uses STDOUT as the default if no other output has been selected.

printf [FILEHANDLE] LIST

Just like the C call to printf.

push @array,@list

Stacks the items in @list onto the end of @array.

q/STRING/
qq/STRING/
qx/STRING/
qw/STRING/

Generalized quotes for strings.

quotemeta String

Returns a copy of String with all the regular expression metacharacters backslashed. See Chapter 7, "Strings and Patterns."

rand [Number]

Returns a random fractional number between 0 and the value of Number. Number must be positive. If Number is not provided, a value between 0 and 1 is returned. Use srand() to seed this function.

read FILEHANDLE,scalar,length[,offset]

Reads length bytes of data into variable scalar from the FILEHANDLE. Returns the number of bytes actually read, or undef in the case of an error. The scalar will be grown or shrunk to the length actually read. The offset to write input in the string to is defaulted to 0 if no offset is explicitly passed as the fourth parameter.

readdir DIRHANDLE

Returns the next directory entry for a directory opened by opendir(). If used in a list context, it returns all the rest of the entries in the directory. For no more entries, it returns an undef value or an empty list if used in list context.

readlink [Expression]

Returns the value of a symbolic link. Crashes the program if symbolic links are not implemented. Upon error, it returns the undefined value and sets $!. Uses $_ for input if Expression is not provided.

recv SOCKET,scalar,len,flags

Receives a message on a socket. See Chapter 12. The data is read into the scalar variable from the specified SOCKET file handle up to len bytes. The flags are as defined in the recvfrom(2) system call.

redo [LABEL]

The redo command restarts a loop block without evaluating the conditional again. The continue block, if any, is not executed. If the LABEL is omitted, the command refers to the innermost enclosing loop.

ref Expression

Returns true if Expression is a reference, or false if it is not. The function returns the name of the package if Expression is a pointer to an object.

rename oldName,newName

Changes the name of the file oldName to newName. Returns 1 for success, 0 otherwise. This function does not work across file system boundaries.

require [Expression]

Uses either Expression or, if no Expression is provided, $_ to determine if some semantics are present. If Expression evaluates to a number, it demands that the current version of Perl ($]) be at least that number. If Expression evaluates to a string, the string is used as the name of the library file to load. Prevents a file from being loaded in twice if the file being loaded in has a 1; statement terminating it. (1; indicates that the file loaded and initialized itself correctly.)

If Expression is a bare word, require assumes a .pm extension for you, to make it easy to load standard modules. This form of loading of modules does not risk altering your name space.

reset [Expression]

Clears values of variables whose names begin with letters in the Expression. More than one letter can be specified using ranges. Uses the ?? special variable if Expression is not specified. The reset function always returns a true value. Here are some examples:

reset 'M';   # reset all M* named variables
reset 'a-z'; # reset lower case variables
reset;       # just reset those listed in ?? searches

Do not use reset 'A-Z'; because this will blow away your environment variables ENV and ARGV!

return arguments

Used to return the list of arguments at the end of a subroutine. A subroutine always returns the result of the last expression in it if no return statement is found.

reverse @list
reverse String

Reverses the order of items in @list. Reverses the order of characters in String.

rewinddir DIRHANDLE

Resets the current position to the start of the directory for use with the readdir() routine on DIRHANDLE.

rindex str,substr[,position]

Gets the position of the last occurrence of substr in str. Starts the search from the end of string unless a position has been specified. If a position is specified, starts the search at the position from the end of the string.

rmdir [DirName]

Removes the directory specified by DirName, but only if the directory is empty. Uses $_ if no DirName is given. Returns 1 on success and 0 otherwise with the error code in $!.

scalar Expression

This operator forces the Expression to be interpreted in a scalar context and returns the value of Expression.

seek FILEHANDLE,position,startingPoint

Set the file pointer for FILEHANDLE just like seek() or fseek() calls in UNIX. The values for startingPoint are 0 to set position from the start of file, 1 to set position relative to the current location in the file, and 2 to set it relative to the end of file. Returns 1 upon success; 0 otherwise.

seekdir DIRHANDLE,position

Moves the current position for the readdir() routine on DIRHANDLE to position, which must be a value returned by telldir().

select [FILEHANDLE]

Sets the default file handle to FILEHANDLE, the currently selected file handle. Returns the current default file handle. All writes and references to output that do not specify a file handle will refer to the FILEHANDLE.

select rbit,wbit,ebit,timeout

The interface to the UNIX select(2) system call. rbit, wbit, and ebit are bitmasks for the select call. The timeout may be 0 if the program wants to wait forever; otherwise, it should be a numeric value in milliseconds. See Chapter 15.

semctl semaphoreID,number,command,argument-list

Works just like the System V Ipc function semctl(2). See Chapter 13 for a complete description.

semget key,nsems,flags

Works just like the System V Ipc function semget(2). See Chapter 13 for a complete description.

semop key,opstring

Works just like the System V Ipc function semop(2). See Chapter 13 for a complete description. The opstring must be a packed array of semop structures. Each semop structure is generated with the instruction pack("sss", $semnum, $semop, $semflag). The number of semaphore operations is implied by the length of opstring. Returns true on success or false otherwise.

send socket,msg,flags[,to]

Sends a message on a socket using the socket(2) system call. See Chapter 12.

sethostent stayopen
setnetent stayopen
setprotoent stayopen
setservent stayopen

These functions perform the same function as the underlying system call. The stayopen value is set to TRUE if the file being read should be kept open, and FALSE otherwise.

setpgrp PID,PGRPID

Sets the current process group for the specified PID. Use a PID of 0 to imply the current process. Works only if the underlying system supports it.

setpriority process,group,user

Sets the current priority for a process, a process group, or a user like the system call to setpriority(2). Works only if the underlying system supports it.

setpwent
setgrent

These functions perform the same function as the underlying system call.

setsockopt socket,level,optionName,optionValue

Sets the socket option named to the value in optionValue. Like the system call to setsocketopt(2). Works only if the underlying system supports it.

shift [@array]shift

Shifts the first value of the @array off and returns it. The size of the @array is reduced by 1. If the @array is empty, it returns undef. Uses @_ in subroutines if @array is not specified.

shmctl shmID,command,argument

Works like the System V Ipc function shmctl(2). If CMD is &Ipc_STAT, the argument must be a variable big enough to hold the returned shmid_ds structure.

shmget shmKey,size,flags

Works just like the System V Ipc function shmget(2). Returns the shared memory segment ID or undef if there is an error.

shmread shmID,VAR,POS,SIZE
shmwrite shmID,STRING,POS,SIZE

Reads or writes the System V shared memory segment shmID by operating at the position POS for SIZE bytes by attaching to the segment, reading or writing to it, and then detaching from the segment. When reading, VAR holds the data read. When writing, up to SIZE bytes in STRING are written. If the length of the string is too short (that is, less than the value in SIZE), null bytes are written to make up the difference. Returns true on success or false otherwise.

shutdown SOCKETHANDLE,how

Shuts down a socket connection by making a system call to shutdown(2).

sin Radians

Returns a double with the sine of the value of Radians. If Radians is omitted, returns sine of $_.

sleep [Seconds]

Makes the program sleep for passed number of seconds. If no arguments are given or if Seconds evaluates to null, the program sleeps forever. Do not mix alarm() and sleep calls in the same program.

socket SOCKETHANDLE,DOMAIN,TYPE,PROTOCOL

Makes a call to open a socket of the specified TYPE in the DOMAIN and uses PROTOCOL. Works like the socket(2) system call.

socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL

Creates two unnamed sockets in the specified DOMAIN of the specified type. Otherwise, works like the socket(2) system call.

sort subroutine @list
sort Code Block @list
sort @list

Sorts the @list and returns the sorted list value. Empty values in arrays are removed. The subroutine or code block are pointers to user-defined functions that take two arguments and return an integer value of 1, 0, or -1. A 1 indicates that the first argument is greater than the second. A 0 indicates that the arguments are equal, and a -1 indicates that the second argument is greater than the first.

splice @array,Offset[,Length[,@list]]

Removes the elements at the Offset and of Length items from the @array and replaces them with the contents of @list. Returns the list of items removed from @array. The @array grows or shrinks as needed. If @list is not provided, nothing is inserted. If Length is not provided, all elements from Offset onward are removed.

split [/Pattern/[,String[,Limit]]]

Returns an array derived from splitting a String into an array of strings of items equal to a number of elements in Limit. If String is not provided, the $_ string is used. The Pattern may be more than one character long. If Pattern is not specified, the function splits on white spaces after removing any leading white spaces. It returns the number of items up to the limit specified and leaves the remainder as one long list. By default, Perl assumes Limit to be one larger than the number of items in the list. A call to split() with no arguments is equivalent to a split(' ', $_ ) call. The Pattern to a split command can be a regular expression or a variable with a regular expression.

sprintf FORMAT,LIST

Returns a string formatted using the printf() syntax.

sqrt Expression

Returns the square root of Expression. Uses $_ if Expression is left out.

srand Expression

Seeds the random number generator for rand() using the Expression as a number.

stat FILEHANDLE
stat FileName

Returns a 13-element array that gives the status information for a file using either the handle FILEHANDLE or the name in FileName. The items in the array are listed in this order: ($device, $inode, $protection, $numberOfhardLinks,$uidOwner, $gidOwner, $deviceType, $totalSize, $blockSize, $blocksUsed, $lastAccessTime, $lastModificationTime, $lastChangeTime). Returns a null list if stat fails. Use stat(_) to return the value from the last stat(FILEHANDLE) call.

sub name

Defines a subroutine for forward referencing.

substr String,Offset,Length
substr String,Offset

Gets a substring from String of up to Length characters and returns it. The first character to extract from is 0. If Length is not provided, everything up to the end of string is returned. If the Offset is negative, the offset starts from the end of the string. If the Length is negative, it leaves that many characters off from the end of the string. The substr() function can be used as an lvalue to patch substrings into String. See Chapter 7 for examples.

symlink oldFile,newFile

Creates a new filename symbolically linked to the old filename. Returns 1 for success or 0 otherwise.

syscall systemCallNumber Arguments

Makes the system call, passing the remaining elements as arguments. Unimplemented system calls, if referenced, produce a fatal error. Strings are passed by reference and numbers as integers.

sysread FILEHANDLE,scalar,length,offset
sysread FILEHANDLE,scalar,length

Reads length bytes of data into variable scalar from the specified FILEHANDLE using the read(2) system call. Returns the number of bytes actually read, or undef in case of an error. The scalar is grown or shrunk to the length actually read. The offset is used to the read data at some other place than at the first byte in scalar.

system program arguments...

Does a fork() to do exactly the same thing as exec but returns to the parent when it's finished. The return value is the exit status of the wait call. To get the actual exit value of the program specified in the system call, divide it by 256.

syswrite FILEHANDLE,scalar,length,offset
syswrite FILEHANDLE,scalar,length

Attempts to write length bytes of data from variable scalar to the specified FILEHANDLE using the system call write(2). Returns the number of bytes actually written, or undef in case of an error. An offset is used to place the read data at the number of offset bytes at the beginning of the string in the scalar.

tell FILEHANDLE
tell

Gets the current file position for FILEHANDLE. If no FILEHANDLE is specified, it uses the file last read.

telldir DIRHANDLE

Returns the current position of the readdir() routines on DIRHANDLE. A value can be used with seekdir() to access a particular location in a directory.

tie variable,classname,LIST

Binds a variable to a class. See the section titled "Using the tie() Operator" in Chapter 6, "Binding Variables to Objects."

time

Returns the number of non-leap seconds since 00:00:00 UTC, January 1, 1970. Used with gmtime() and localtime().

times

Returns a four-item array with the user and system times, in seconds, for this process and the children (if any) of this process.

tr///

The translation operator. See Chapter 7.

truncate FILEHANDLE,LENGTH

Truncates the file opened on FILEHANDLE to the specified length.

uc String

Returns an uppercased copy of String.

ucfirst String

Returns the value of String with the first character uppercased.

umask Expression
umask

Sets the umask for the process and returns the old one. If Expression is not provided, the current umask is returned.

undef Scalar
undef Array
undef Hash
undef Subroutine

Removes any definition of the value of Scalar, hash, array or subroutine by name. This function always returns the undef value.

unlink namedFiles

Deletes the named files. Returns the number of files successfully deleted. The unlink() will not delete directories unless you are superuser and the -U flag is supplied to Perl. Use rmdir instead.

unpack TEMPLATE,Expression

Unpack does the reverse of pack. It takes a structure and expands it into a list of items. TEMPLATE has the same format as in the pack function.

unshift @array,@list

Works the opposite way of shift(). Attaches @list to the front of @array. Returns the new number of elements in the @array.

untie variable

Breaks binding between a variable and a package.

use Module[,Module[,Module ... ]]

Imports all named modules into a program. See Chapter 4 for more information on Perl modules.

utime accessTime Modification Filenames

Modifies the access and modification times on each file in a list of files. Returns the number of files successfully changed.

values %Hash

Returns an array with just the values in random of the named hash. Works like the keys() function except that it returns values.

vec string,offset,bitsToSet

Sets the bits from the values of 0s and 1s in a string. Starts setting bits at the offset. Returns the value of the bitfield specified. The bitsToSet to set must be a power of 2 from 1 to 32. It's an easier way of setting bits than using logical operators.

Wait

Waits for a child process to terminate and returns the pid of the deceased process, or -1 if there are no child processes. The status is returned in $?.

waitpid PID,flags

Waits for a particular child process to die and returns the PID of the dead process. It returns -1 if there is no such child process. The status is returned in $?.

wantarray

Returns true if the currently executing subroutine is looking for list value. Returns false if the subroutine is looking for a scalar.

warn Message

Prints an error message on STDERR just like die() but doesn't exit.

write FILEHANDLE
write Expression
write

Writes a formatted record to the specified file using the format associated with that file. See Chapter 19.

y///

The translation operator (just like the tr operator).