Rex Swain's HTMLified
Perl 5 Reference Guide

Jump to Contents or Index

This is an HTMLified version of the Perl 5 Desktop Reference , ISBN 1-56592-187-9, copyright © 1996 by Johan Vromans. HTML copyright © 1996-1997 by Rex Swain.

See Rex Swain's HTMLified Perl 4 Reference Guide for similar summary of Perl version 4.

See Perl 5 Desktop Reference for information about ordering a printed copy ($6.95) of the booklet from O'Reilly. See The Perl Reference Guide for pointers to a PostScript (free) version.

If you want to learn Perl, see the book Learning Perl by Randal L. Schwartz. If you want more detailed information about Perl, see the book Programming perl by Larry Wall and Randal L. Schwartz.

For more detail, see Perl Manual or Alphabetical Listing of Perl Functions.
For less detail, see The Perl Language Home Page.

Jump to Contents or Index

Contents

Jump to Contents or Index

Index

abs  accept  alarm  and  ARGV  ArithmeticFunctions  ArrayListFunctions  ArraysSpecial  atan2  BEGIN  bind  binmode  bless  caller  chdir  chmod  chomp  chop  chr  chroot  close  closedir  cmp  CommandLineOptions  connect  Contents  continue  Conventions  ConversionFunctions  ConversionStructure  cos  crypt  dbmclose  dbmopen  Debugger  defined  delete  die  DirectoryReadingRoutines  do  do  do  dump  each  else  elsif  END  ENV  EnvironmentVariables  eof  eq  eval  eval  exec  exists  exit  exp  EXPORT  EXPORT_OK  ExpressionsRegular  fcntl  fileno  FileOperations  FilesSystemInformationFrom  FileTestOperators  flock  for  foreach  fork  Formats  formline  FunctionsArithmetic  FunctionsArrayList  FunctionsConversion  FunctionsSearchReplace  FunctionsString  ge  getc  getlogin  getpeername  getpgrp  getppid  getpriority  getsockname  getsockopt  glob  gmtime  goto  goto  grep  gt  hex  HOME  if  import  INC  Index  index  InformationFromSystemFiles  InputOutput  int  InteractionSystem  ioctl  ISA  join  keys  kill  last  lc  lcfirst  le  length  link  ListArrayFunctions  listen  Literals  local  localtime  log  LOGDIR  lstat  lt  m  map  Miscellaeous  mkdir  Modules  my  ne  Networking  next  no  npt  ObjectOrientedProgramming  oct  open  opendir  OperationsFile  Operators  OperatorsFileTest  OptionsCommandLine  or  ord  OutputInput  OVERLOAD  pack  package  Packages  PATH  PERL5DB  PERL5LIB  PERLLIB  pipe  pop  pos  print  printf  push  quotemeta  rand  read  readdir  ReadingDirectoryRoutines  readlink  recv  redo  ref  RegularExpressions  rename  ReplaceSearchFunctions  require  reset  return  reverse  rewindir  rindex  rmdir  RoutinesDirectoryReading  s  scalar  scalar  SearchReplaceFunctions  seek  seekdir  select  send  setpgrp  setpriority  setsockopt  shift  shutdown  SIG  sin  sleep  socket  socketpair  sort  SpecialArrays  SpecialVariables  splice  split  sprintf  sqrt  srand  stat  Statements  StringFunctions  StructureConversion  study  sub  Subroutines  substr  symlink  syscall  sysread  system  SystemFilesInformationFrom  SystemInteraction  SystemVIPC  syswrite  tell  telldir  TestFileOperators  tie  time  times  tr  truncate  uc  ucfirst  umask  undef  unless  unlink  unpack  unshift  untie  until  until  use  utime  values  Variables  VariablesEnvironment  VariablesSpecial  vec  wait  waitpid  wantarray  warn  while  write  xor  y 

Back to Contents or Index

Conventions

Back to Contents or Index

Command-Line Options

-a

turns on autosplit mode when used with -n or -p . Splits to @F .

-c

checks syntax but does not execute.

-d

runs the script under the debugger. Use -de 0 to start the debugger without a script

-D NUMBER

sets debugging flags.

-e COMMANDLINE

may be used to enter a single line of script. Multiple -e commands may be given to build up a multiline script.

-F REGEXP

specifies a regular expression to split on if -a is in effect.

-i EXT

files processed by the < > construct are to be edited in place.

-I DIR

with -P , tells the C preprocessor where to look for include files. The directory is prepended to @INC .

-l [ OCTNUM ]

enables automatic line-end processing, e.g., -l013 .

-n

assumes an input loop around your script. Lines are not printed.

-p

assumes an input loop around your script. Lines are printed.

-P

runs the C preprocessor on the script before compilation by Perl.

-s

interprets -xxx on the command line as a switch and sets the corresponding variable $xxx in the script.

-S

uses the PATH environment variable to search for the script.

-T

forces taint checking.

-u

dumps core after compiling the script. To be used with the undump (1) program (where available).

-U

allows perl to perform unsafe operations.

-v

prints the version and patchlevel of your Perl executable.

-w

prints warnings about possible spelling errors and other error-prone constructs in the script.

-x [ DIR ]

extracts Perl program from input stream. If DIR is specified, switches to this directory before running the program.

-0 VAL

(that's the number zero.) Designates an initial value for the record separator $/ . See also -l

Back to Contents or Index

Literals

Numeric:

123

1_234

123.4

5E-10

0xff (hex)

0377 (octal)

String:

'abc'

literal string, no variable interpolation or escape characters, except \' and \\ . Also: q/abc/ . Almost any pair of delimiters can be used instead of / ... / .

"abc"

Variables are interpolated and escape sequences are processed. Also: qq/abc/ .
Escape sequences: \t (Tab), \n (Newline), \r (Return), \f (Formfeed), \b (Backspace), \a (Alarm), \e (Escape), \033 (octal), \x1b (hex), \c[ (control)
\l and \u lowercase/uppercase the following character. \L and \U lowercase/uppercase until a \E is encountered. \Q quote regular expression characters until a \E is encountered.

` COMMAND `

evaluates to the output of the COMMAND . Also: qx/ COMMAND / .

Array:

(1, 2, 3) . () is an empty array.
(1..4) is the same as (1,2,3,4) ,
likewise ('a'..'z') .
qw/foo bar ... / is the same as ('foo','bar', ... ) .

Array reference:

[1,2,3]

Hash (associative array):

( KEY1 , VAL1 , KEY2 , VAL2 , ... )
Also ( KEY1 => VAL1 , KEY2 => VAL2 , ... )

Hash reference:

{ KEY1 , VAL1 , KEY2 , VAL2 , ... }

Code reference:

sub { STATEMENTS }

Filehandles:

<STDIN> , <STDOUT> , <STDERR> , <ARGV> , <DATA> .
User-specified: HANDLE , $ VAR .

Globs:

< PATTERN > evaluates to all filenames according to the pattern. Use <${ VAR }> or glob   $ VAR to glob from a variable.

Here-Is:

<< IDENTIFIER
Shell-style "here document."

Special tokens:

__FILE__ : filename; __LINE__ : line number; __END__ : end of program; remaining lines can be read using the filehandle DATA .

Back to Contents or Index

Variables

You can always use a { BLOCK } returning the right type of reference instead of the variable identifier, e.g., ${ ... } , &{ ... } . $$p is just a shorthand for ${$p} .

Back to Contents or Index

Operators

All Perl functions can be used as list operators, in which case they have very high or very low precedence, depending on whether you look at the left or the right side of the operator. Only the operators not , and , or and xor have lower precedence.

A "list" is a list of expressions, variables, or lists. An array variable or an array slice may always be used instead of a list.

Parentheses can be added around the parameter lists to avoid precedence problems.

Back to Contents or Index

Statements

Every statement is an expression, optionally followed by a modifier, and terminated by a semicolon. The semicolon may be omitted if the statement is the final one in a BLOCK .

Execution of expressions can depend on other expressions using one of the modifiers if , unless , while or until , for example:

• EXPR1 if EXPR2 ;
  EXPR1 until EXPR2 ;

The logical operators || , && or ?: also allow conditional execution:

• EXPR1 || EXPR2 ;
  EXPR1 ? EXPR2 : EXPR3 ;

Statements can be combined to form a BLOCK when enclosed in {} . Blocks may be used to control flow:

• if ( EXPR ) BLOCK [ [ elsif ( EXPR ) BLOCK ... ] else BLOCK ]
  unless ( EXPR ) BLOCK [ else BLOCK ]
  [ LABEL : ] while ( EXPR ) BLOCK [ continue BLOCK ]
  [ LABEL : ] until ( EXPR ) BLOCK [ continue BLOCK ]
  [ LABEL : ] for ( EXPR ; EXPR ; EXPR ) BLOCK
  [ LABEL : ] foreach VAR† ( LIST ) BLOCK
  [ LABEL : ] BLOCK [ continue BLOCK ]

Program flow can be controlled with:

Special forms are:

• do BLOCK while EXPR ;
  do BLOCK until EXPR ;

which are guaranteed to perform BLOCK once before testing EXPR , and

• do BLOCK

which effectively turns BLOCK into an expression.

Back to Contents or Index

Subroutines, Packages and Modules

& SUBROUTINE LIST

Executes a SUBROUTINE declared by a sub declaration, and returns the value of the last expression evaluated in SUBROUTINE . SUBROUTINE can be an expression yielding a reference to a code object. The & may be omitted if the subroutine has been declared before being used.

bless REF [ , PACKAGE ]

Turns the object REF into an object in PACKAGE . Returns the reference.

caller [ EXPR ]

Returns an array ( $ package, $ file, $ line,...) for a specific subroutine call. caller returns this info for the current subroutine, caller(1) for the caller of this subroutine, etc. Returns false if no caller.

do SUBROUTINE LIST

Depreciated form of & SUBROUTINE .

goto & SUBROUTINE

Substitutes a call to SUBROUTINE for the current subroutine.

import MODULE [ [ VERSION ] LIST ]

Imports the named subroutines from MODULE .

no MODULE [ LIST ]

Cancels imported semantics. See use .

package NAME

Designates the remainder of the current block as a package.

require EXPR†

If EXPR is numeric, requires Perl to be at least that version. Otherwise EXPR must be the name of a file that is included from the Perl library. Does not include more than once, and yields a fatal error if the file does not evaluate to a true value. If EXPR is a bare word, assumes extension .pm for the name of the file.

return EXPR

Returns from a subroutine with the value specified.

sub NAME { EXPR ; ... }

Designates NAME as a subroutine. Parameters are passed by reference as array @_ . Returns the value of the last expression evaluated.

[ sub ] BEGIN { EXPR ; ... }

Defines a setup BLOCK to be called before execution.

[ sub ] END { EXPR ; ... }

Defines a cleanup BLOCK to be called upon termination.

tie VAR , PACKAGE , [ LIST ]

Ties a variable to a package that will handle it. Can be used to bind a dbm or ndbm file to a hash.

untie VAR

Breaks the binding between the variable and the package.

use MODULE [ [ VERSION ] LIST ]

Imports semantics from the named module into the current package.

Back to Contents or Index

Object-Oriented Programming

Perl rules of object oriented programming:

• An object is simply a reference that happens to know which class it belongs to. Objects are blessed, references are not.
• A class is simply a package that happens to provide methods to deal with object references. If a package fails to provide a method, the base classes as listed in @ISA are searched.
• A method is simply a subroutine that expects an object reference (or a package name, for static methods) as the first argument.

Methods can be applied with:

• METHOD OBJREF PARAMETERS           or
  OBJREF -> METHOD PARAMETERS

Back to Contents or Index

Arithmetic Functions

Back to Contents or Index

Conversion Functions

chr EXPR†

Returns the character represented by the decimal value EXPR .

gmtime EXPR†

Converts a time as returned by the time function to a 9-element array (0:  $ sec, 1:  $ min, 2:  $ hour, 3:  $ mday, 4:  $ mon, 5:  $ year, 6:  $ wday, 7:  $ yday, 8:  $ isdst) with the time analyzed for the Greenwich time zone. $ mon has the range 0..11 and $ wday has the range 0..6.

hex EXPR†

Returns the decimal value of EXPR interpreted as a hex string.

localtime EXPR†

Converts a time as returned by the time function to ctime (3) string. In array context, returns a 9-element array with the time analyzed for the local time zone.

oct EXPR†

Returns the decimal value of EXPR interpreted as an octal string. If EXPR starts off with 0x , interprets it as a hex string instead.

ord EXPR†

Returns the ASCII value of the first character of EXPR .

vec EXPR , OFFSET , BITS

Treats string EXPR as a vector of unsigned integers, and yields the bit at OFFSET . BITS must be between 1 and 32. May be assigned to.

Back to Contents or Index

Structure Conversion

pack TEMPLATE , LIST

Packs the values into a binary structure using TEMPLATE .

unpack TEMPLATE , EXPR

Unpacks the structure EXPR into an array, using TEMPLATE .

TEMPLATE is a sequence of characters as follows:

Each character may be followed by a decimal number that will be used as a repeat count; an asterisk ( * ) specifies all remaining arguments. If the format is preceded with % N , unpack returns an N -bit checksum instead. Spaces may be included in the template for readability purposes.

Back to Contents or Index

String Functions

chomp LIST†

Removes line endings from all elements of the list; returns the (total) number of characters removed.

chop LIST†

Chops off the last character on all elements of the list; returns the last chopped character.

crypt PLAINTEXT , SALT

Encrypts a string.

eval EXPR†

EXPR is parsed and executed as if it were a Perl program. The value returned is the value of the last expression evaluated. If there is a syntax error or runtime error, an undefined string is returned by eval , and $@ is set to the error message. See also eval in section Miscellaneous.

index STR , SUBSTR [ , OFFSET ]

Returns the position of SUBSTR in STR at or after OFFSET . If the substring is not found, returns -1 (but see $[ in section Special Variables).

length EXPR†

Returns the length in characters of the value of EXPR .

lc EXPR

Returns a lowercase version of EXPR .

lcfirst EXPR

Returns EXPR with the first character lowercase.

quotemeta EXPR

Returns EXPR with all regular expression metacharacters quoted.

rindex STR , SUBSTR [ , OFFSET ]

Returns the position of the last SUBSTR in STR at or before OFFSET .

substr EXPR , OFFSET [ , LEN ]

Extracts a substring of length LEN out of EXPR and returns it. If OFFSET is negative, counts from the end of the string. May be assigned to.

uc EXPR

Returns an uppercased version of EXPR .

ucfirst EXPR

Returns EXPR with the first character uppercased.

Back to Contents or Index

Array and List Functions

delete $ HASH { KEY }

Deletes the specified value from the specified hash. Returns the deleted value unless HASH is tie d to a package that does not support this.

each % HASH

Returns a 2-element array consisting of the key and value for the next value of the hash. Entries are returned in an apparently random order. After all values of the hash have been returned, a null array is returned. The next call to each after that will start iterating again.

exists EXPR†

Checks if the specified hash key exists in its hash array.

grep EXPR , LIST
grep BLOCK LIST

Evaluates EXPR or BLOCK for each element of the LIST , locally setting $_ to refer to the element. Modifying $_ will modify the corresponding element from LIST . Returns the array of elements from LIST for which EXPR returned true .

join EXPR , LIST

Joins the separate strings of LIST into a single string with fields separated by the value of EXPR , and returns the string.

keys % HASH

Returns an array with of all the keys of the named hash.

map EXPR , LIST
map BLOCK LIST

Evaluates EXPR or BLOCK for each element of the LIST , locally setting $_ to refer to the element. Modifying $_ will modify the corresponding element from LIST . Returns the list of results.

pop @ ARRAY

Pops off and returns the last value of the array.

push @ ARRAY , LIST

Pushes the values of LIST onto the end of the array.

reverse LIST

In array context, returns the LIST in reverse order. In scalar context: returns the first element of LIST with bytes reversed.

scalar @ ARRAY

Returns the number of elements in the array.

scalar % HASH

Returns a true value if the hash has elements defined.

shift [ @ ARRAY ]

Shifts the first value of the array off and returns it, shortening the array by 1 and moving everything down. If @ ARRAY is omitted, shifts @ARGV in main and @_ in subroutines.

sort [ SUBROUTINE ] LIST

Sorts the LIST and returns the sorted array value. SUBROUTINE , if specified, must return less than zero, zero, or greater than zero, depending on how the elements of the array (available to the routine as $a and $b ) are to be ordered. SUBROUTINE may be the name of a user-defined routine, or a BLOCK .

splice @ ARRAY , OFFSET [ , LENGTH [ , LIST ] ]

Removes the elements of @ ARRAY designated by OFFSET and LENGTH , and replaces them with LIST (if specified). Returns the elements removed.

split [ PATTERN [ , EXPR† [ , LIMIT ] ] ]

Splits a string into an array of strings, and returns it. If LIMIT is specified, splits into at most that number of fields. If PATTERN is also omitted, splits at the whitespace. If not in array context, returns number of fields and splits to @_ . See also Search and Replace Functions.

unshift @ ARRAY , LIST

Prepends list to the front of the array, and returns the number of elements in the new array.

values % HASH

Returns a normal array consisting of all the values of the named hash.

Back to Contents or Index

Regular Expressions

Each character matches itself, unless it is one of the special characters + ? . * ^ $ ( ) [ ] { } | \ . The special meaning of these characters can be escaped using a \ .

See also $1 ... $9 , $+ , $& , $` , and $' in section Special Variables.

With modifier x , whitespace can be used in the patterns for readability purposes.

Back to Contents or Index

Search and Replace Functions

[ EXPR =~ ] [ m ] / PATTERN / [ g ] [ i ] [ m ] [ o ] [ v ] [ x ]

Searches EXPR (default: $_ ) for a pattern. If you prepend an m you can use almost any pair of delimiters instead of the slashes. If used in array context, an array is returned consisting of the subexpressions matched by the parentheses in the pattern, i.e., ($1,$2,$3, ... ) .
Optional modifiers: g matches as many times as possible; i searches in a case-insensitive manner; o interpolates variables only once. m treats the string as multiple lines; s treats the string as a single line; x allows for regular expression extensions.
If PATTERN is empty, the most recent pattern from a previous match or replacement is used.
With g the match can be used as an iterator in scalar context.

? PATTERN ?

This is just like the / PATTERN / search, except that it matches only once between calls to the reset operator.

[ $ VAR =~ ] s / PATTERN / REPLACEMENT / [ e ] [ g ] [ i ] [ m ] [ o ] [ s ] [ x ]

Searches a string for a pattern, and if found, replaces that pattern with the replacement text. It returns the number of substitutions made, if any; if no substitutions are made, it returns false .
Optional modifiers: g replaces all occurrences of the pattern; e evaluates the replacement string as a Perl expression; for any other modifiers, see / PATTERN / matching. Almost any delimiter may replace the slashes; if single quotes are used, no interpretation is done on the strings between the delimiters, otherwise the strings are interpolated as if inside double quotes.
If bracketing delimiters are used, PATTERN and REPLACEMENT may have their own delimiters, e.g., s(foo)[bar] . If PATTERN is empty, the most recent pattern from a previous match or replacement is used.

[ $ VAR =~ ] tr / SEARCHLIST / REPLACEMENTLIST / [ c ] [ d ] [ s ]

Translates all occurrences of the characters found in the search list with the corresponding character in the replacement list. It returns the number of characters replaced. y may be used instead of tr .
Optional modifiers: c complements the SEARCHLIST ; d deletes all characters found in SEARCHLIST that do not have a corresponding character in REPLACEMENTLIST ; s squeezes all sequences of characters that are translated into the same target character into one occurrence of this character.

pos SCALAR

Returns the position where the last m//g search left off for SCALAR . May be assigned to.

study [ $ VAR† ]

Study the scalar variable $ VAR in anticipation of performing many pattern matches on its contents before the variable is next modified.

Back to Contents or Index

File Test Operators

These unary operators takes one argument, either a filename or a filehandle, and test the associated file to see if something is true about it. If the argument is omitted, they test $_ (except for -t , which tests STDIN ). If the special argument _ (underscore) is passed, they use the information from the preceding test or stat call.

Back to Contents or Index

File Operations

Functions operating on a list of files return the number of files successfully operated upon.

chmod LIST

Changes the permissions of a list of files. The first element of the list must be the numerical mode.

chown LIST

Changes the owner and group of a list of files. The first two elements of the list must be the numerical uid and gid.

truncate FILE , SIZE

Truncates FILE to SIZE . FILE may be a filename or a filehandle.

link OLDFILE , NEWFILE

Creates a new filename linked to the old filename.

lstat FILE

Like stat , but does not traverse a final symbolic link.

mkdir DIR , MODE

Creates a directory with given permissions. Sets $! on failure.

readlink EXPR†

Returns the value of a symbolic link.

rename OLDNAME , NEWNAME

Changes the name of a file.

rmdir FILENAME†

Deletes the directory if it is empty. Sets $! on failure.

stat FILE

Returns a 13-element array (0:  $ dev, 1:  $ ino, 2:  $ mode, 3:  $ nlink, 4:  $ uid, 5:  $ gid, 6:  $ rdev, 7:  $ size, 8:  $ atime, 9:  $ mtime, 10:  $ ctime, 11:  $ blksize, 12:  $ blocks). FILE can be a filehandle, an expression evaluating to a filename, or _ to refer to the last file test operation or stat call. Returns a null list if the stat fails.

symlink OLDFILE , NEWFILE

Creates a new filename symbolically linked to the old filename.

unlink LIST

Deletes a list of files.

utime LIST

Changes the access and modification times. The first two elements of the list must be the numerical access and modification times.

Back to Contents or Index

Input / Output

In input/output operations, FILEHANDLE may be a filehandle as opened by the open operator, a predefined filehandle (e.g., STDOUT ) or a scalar variable that evaluates to the name of a filehandle to be used.

< FILEHANDLE >

In scalar context, reads a single line from the file opened on FILEHANDLE . In array context, reads the whole file.

< >

Reads from the input stream formed by the files specified in @ARGV , or standard input if no arguments were supplied.

binmode FILEHANDLE

Arranges for the file opened on FILEHANDLE to be read or written in binary mode as opposed to text mode (null operation on UNIX).

close FILEHANDLE

Closes the file or pipe associated with the filehandle.

dbmclose % HASH

Depreciated, use untie instead.

dbmopen % HASH , DBMNAME , MODE

Depreciated, use tie instead.

eof FILEHANDLE

Returns true if the next read will return end of file, or if the file is not open.

eof

Returns the EOF status for the last file read.

eof ()

Indicates EOF on the pseudo file formed of the files listed on the command line.

fcntl FILEHANDLE , FUNCTION , $ VAR

Implements the fcntl (2) function. This function has non-standard return values.

fileno FILEHANDLE

Returns the file descriptor for a given (open) file.

flock FILEHANDLE , OPERATION

Calls flock (2) on the file. OPERATION formed by adding 1 (shared), 2 (exclusive), 4 (non-blocking), or 8 (unlock).

getc [ FILEHANDLE ]

Yields the next character from the file, or an empty string on end of file. If FILEHANDLE is omitted, reads from STDIN .

ioctl FILEHANDLE , FUNCTION , $ VAR

Performs ioctl (2) on the file. This function has non-standard return values.

open FILEHANDLE [ , FILENAME ]

Opens a file and associates it with FILEHANDLE . If FILENAME is omitted, the scalar variable of the same name as the FILEHANDLE must contain the filename.
The following filename conventions apply when opening a file.

" FILE "	open FILE for input. Also "< FILE " .
"> FILE "	open FILE for output, creating it if necessary.
">> FILE "	open FILE in append mode.
"+> FILE "	open FILE with read/write access.
"| CMD "	opens a pipe to command CMD ; forks if CMD is - .
" CMD |"	opens a pipe from command CMD ; forks if CMD is - .

FILE may be & FILEHND in which case the new filehandle is connected to the (previously opened) filehandle FILEHND . If it is &= N , FILE will be connected to the given file descriptor. open returns undef upon failure, true otherwise.

pipe READHANDLE , WRITEHANDLE )

Returns a pair of connected pipes.

print [ FILEHANDLE ] [ LIST† ]

Equivalent to print FILEHANDLE sprintf LIST .

printf [ ( [ FILEHANDLE ] LIST† ) *]

Equivalent to print FILEHANDLE sprintf ( LIST ) .

read FILEHANDLE , $ VAR , LENGTH [ , OFFSET ]

Reads LENGTH binary bytes from the file into the variable at OFFSET . Returns number of bytes actually read.

seek FILEHANDLE , POSITION , WHENCE

Arbitarily positions the file. Returns true if successful.

select [ FILEHANDLE ]

Returns the currently selected filehandle. Sets the current default filehandle for output operations if FILEHANDLE is supplied.

select RBITS , WBITS , NBITS , TIMEOUT

Performs a select (2) system call with the same parameters.

sprintf FORMAT , LIST

Returns a string formatted by (almost all of) the usual printf (3) conventions.

sysread FILEHANDLE , $ VAR , LENGTH [ , OFFSET ]

Reads LENGTH bytes into $ VAR at OFFSET .

syswrite FILEHANDLE , SCALAR , LENGTH [ , OFFSET ]

Writes LENGTH bytes from SCALAR at OFFSET .

tell [ FILEHANDLE ]

Returns the current file position for the file. If FILENAME is omitted, assumes the file last read.

write [ FILEHANDLE ]

Writes a formatted record to the specified file, using the format associated with that file.

Back to Contents or Index

Formats

formline PICTURE , LIST

Formats LIST according to PICTURE and accumulates the result into $^A .

write [ FILEHANDLE ]

Writes a formatted record to the specified file, using the format associated with that file.

Formats are defined as follows:

• format [ NAME ] =
  FORMLIST
  .

FORMLIST pictures the lines, and contains the arguments which will give values to the fields in the lines. NAME defaults to STDOUT if omitted.

Picture fields are:

Use ^ instead of @ for multiline block filling.
Use ~ at the beginning of a line to suppress unwanted empty lines.
Use ~~ at the beginning of a line to have this format line repeated until all fields are exhausted.
Use $- to zero to force a page break on the next write .
See also $^ , $~ , $^A , $^F , $- and $= in section Special Variables.

Back to Contents or Index

Directory Reading Routines

closedir DIRHANDLE

Closes a directory opened by opendir .

opendir DIRHANDLE , DIRNAME

Opens a directory on the handle specified.

readdir DIRHANDLE

Returns the next entry (or an array of entries) from the directory.

rewinddir DIRHANDLE

Positions the directory to the beginning.

seekdir DIRHANDLE , POS

Sets position for readdir on the directory.

telldir DIRHANDLE

Returns the position in the directory.

Back to Contents or Index

System Interaction

alarm EXPR

Schedules a SIGALRM to be delivered after EXPR seconds.

chdir [ EXPR ]

Changes the working directory. Uses $ENV{"HOME"} or $ENV{"LOGNAME"} if EXPR is omitted.

chroot FILENAME†

Changes the root directory for the process and its children.

die [ LIST ]

Prints the value of LIST to STDERR and exits with the current value of $! (errno). If $! is 0, exits with the value of ($? >> 8) . If ($? >> 8) is 0, exits with 255. LIST defaults to " Died ".

exec LIST

Executes the system command in LIST ; does not return.

exit EXPR

Exits immediately with the value of EXPR , which defaults to 0 (zero). Calls END routines and object destructors before exiting.

fork

Does a fork (2) system call. Returns the process ID of the child to the parent process and zero to the child process.

getlogin

Returns the current login name as known by the system.

getpgrp [ PID ]

Returns the process group for process PID (0, or omitted, means the current process).

getppid

Returns the process ID of the parent process.

getpriority WHICH , WHO

Returns the current priority for a process, process group, or user.

glob PAT

Returns a list of filenames that match the shell pattern PAT .

kill LIST

Sends a signal to a list of processes. The first element of the list must be the signal to send (either numeric, or its name as a string).

setpgrp PID , PGRP

Sets the process group for the PID (0 means the current process).

setpriority WHICH , WHO , PRIORITY

Sets the current priority for a process, process group, or a user.

sleep [ EXPR ]

Causes the program to sleep for EXPR seconds, or forever if no EXPR . Returns the number of seconds actually slept.

syscall LIST

Calls the system call specified in the first element of the list, passing the rest of the list as arguments to the call.

system LIST

Does exactly the same thing as exec LIST except that a fork is performed first, and the parent process waits for the child process to complete.

times

Returns a 4-element array (0:  $ user, 1:  $ system, 2:  $ cursor, 3:  $ csystem) giving the user and system times, in seconds, for this process and the children of this process.

umask [ EXPR ]

Sets the umask for the process and returns the old one. If EXPR is omitted, returns current umask value.

wait

Waits for a child process to terminate and returns the process ID of the deceased process (-1 if none). The status is returned in $? .

waitpid PID , FLAGS

Performs the same function as the corresponding system call.

warn [ LIST ]

Prints the message on STDERR like die , but doesn't exit. LIST defaults to " Warning: something's wrong ".

Back to Contents or Index

Networking

accept NEWSOCKET , GENERICSOCKET

Accepts a new socket.

bind SOCKET , NAME

Binds the NAME to the SOCKET .

connect SOCKET , NAME

Connects the NAME to the SOCKET .

getpeername SOCKET

Returns the socket address of the other end of the SOCKET .

getsockname SOCKET

Returns the name of the SOCKET .

getsockopt SOCKET , LEVEL , OPTNAME

Returns the socket options.

listen SOCKET , QUEUESIZE

Starts listening on the specified SOCKET .

recv SOCKET , SCALAR , LENGTH , FLAGS

Receives a message on SOCKET .

send SOCKET , MSG , FLAGS [ , TO ]

Sends a message on the SOCKET .

setsockopt SOCKET , LEVEL , OPTNAME , OPTVAL

Sets the requested socket option.

shutdown SOCKET , HOW

Shuts down a SOCKET .

socket SOCKET , DOMAIN , TYPE , PROTOCOL

Creates a SOCKET in DOMAIN with TYPE and PROTOCOL .

socketpair SOCKET1 , SOCKET2 , DOMAIN , TYPE , PROTOCOL

Works the same as socket , but creates a pair of bidirectional sockets.

Back to Contents or Index

System V IPC

You need to require "sys/ipc.ph" before you can use the symbolic names of the operations.

msgctl ID , CMD , ARGS

Calls msgctl (2). If CMD is &IPC_STAT then ARGS must be a variable.

msgget KEY , FLAGS

Creates a message queue for KEY . Returns the message queue identifier.

msgsnd ID , MSG , FLAGS

Sends MSG to queue ID .

msgrcv ID , $ VAR , SIZE , TYPE , FLAGS

Receives a message from queue ID into VAR .

semctl ID , SEMNUM , CMD , ARG

Calls semctl (2). If CMD is &IPC_STAT of &GETALL then ARG must be a variable.

semget KEY , NSEMS , SIZE , FLAGS

Creates a set of semaphores for KEY . Returns the message semaphore identifier.

semop KEY , ...

Performs semaphore operations.

shmctl ID , CMD , ARG

Calls shmctl (2). If CMD is &IPC_STAT then ARG must be a variable.

shmget KEY , SIZE , FLAGS

Creates shared memory. Returns the shared memory segment identifier.

shmread ID , $ VAR , POS , SIZE

Reads at most SIZE bytes of the contents of shared memory segment ID starting at offset POS into VAR .

shmwrite ID , STRING , POS , SIZE

Writes at most SIZE bytes of STRING into the contents of shared memory segment ID at offset POS .

Back to Contents or Index

Miscellaneous

defined EXPR

Tests whether the lvalue EXPR has an actual value.

do FILENAME

Executes FILENAME as a Perl script. See also require in the section Subroutines, Packages and Modules.

dump [ LABEL ]

Immediate core dump. When reincarnated, starts at LABEL .

eval { EXPR ; ... }

Executes the code between { and } . Traps runtime errors as described with eval ( EXPR ) , in the section String Functions.

local VARIABLE

local ( LIST )

Creates a scope for the listed variables local to the enclosing block, subroutine or eval .

my VARIABLE

my ( LIST )

Creates a scope for the listed variables lexically local to the enclosing block, subroutine or eval .

ref EXPR†

Returns a true value if EXPR is a reference. Returns the package name if EXPR has been blessed into a package.

reset [ EXPR ]

Resets ?? searches so that they work again. EXPR is a list of single letters. All variables and arrays beginning with one of those letters are reset to their pristine state. Only affects the current package.

scalar EXPR

Forces evaluation of EXPR in scalar context.

undef [ LVALUE ]

Undefines the LVALUE . Always returns the undefined value.

wantarray

Returns true if the current context expects an array value.

Back to Contents or Index

Information from System Files

Back to Contents or Index

Special Variables

Back to Contents or Index

Special Arrays

Back to Contents or Index

Environment Variables

Perl uses the following environment variables.

Back to Contents or Index

The Perl Debugger

The Perl symbolic debugger is invoked with perl -d .