\def\revision{1}
\documentclass[epsf]{pr}

\begin{document}

\begin{titlepage}
\hbox{ }
\end{titlepage}

\unnumbered{Contents}

\tableofcontents

\unnumbered{Conventions}

\begin{enum}{2cm}
\Xi{|fixed|} denotes text that you enter literally.

\Xi{<this>} means variable text, i.e. things you must fill in.

\Xi{<this>\dag} means that <this> will default to |$_| if omitted.

\Xi{\kwd{word}} is a keyword, i.e. a word with a special meaning.

\Xi{\fbox{<ret>}} denotes pressing a keyboard key.

\Xi{[\ldots]} denotes an optional part.

\end{enum}

\clearpage


\section{Command line options} 

\begin{enum}{1.4cm}

\Xi{|-a|} turns on autosplit mode when used with |-n| or
|-p|. Splits to |@F|.

\Xi{|-c|} checks syntax but does not execute.
It does run |BEGIN| and |END| blocks.

\Xi{|-d| [ |:|<debugger> ]} runs the script under the debugger.
Use `|-de 0|' to start the debugger without a script.

\Xi{|-D| <number>} sets debugging flags. 

\Xi{|-e| <commandline>} may be used to enter a single line of
script. Multiple |-e| commands may be given to build up a
multi-line script.

\Xi{|-F| <regexp>} specifies a regular expression to split on 
if |-a| is in effect.

\Xi{|-h|} prints the Perl usage summary. Does not execute.

\Xi{|-i| <ext>} files processed by the |<|\,|>| construct are
to be edited in-place.

\Xi{|-I| <dir>} with |-P|: tells the C preprocessor where
to look for include files. The directory is prepended to |@INC|.

\Xi{|-l| [ <octnum> ] } enables automatic line ending processing, 
e.g. |-l013|.

\Xi{|-m| <module>} imports the <module> before executing 
the script. <module> may be followed by a `|=|' and a comma-separated
list of items.

\Xi{|-M| <module>} Same as |-m|, but with more trickery.

\Xi{|-n|} assumes an input loop around the script. Lines are not
printed.

\Xi{|-p|} assumes an input loop around the script. Lines are
printed.

\Xi{|-P|} runs the C preprocessor on the script before
compilation by Perl.

\Xi{|-s|} interprets `|-xxx|' on the command line as a
switch and sets the corresponding variable \$|xxx| in the script.

\Xi{|-S|} uses the |PATH| environment variable to search for
the script.

\Xi{|-T|} turns on \textit{taint} checking.

\Xi{|-u|} dumps core after compiling the script. To be used with
the \textit{undump} program (where available).

\Xi{|-U|} allows Perl to perform unsafe operations.

\Xi{|-v|} prints the version and patchlevel of your Perl
executable.

\Xi{|-V| [ |:|<var> ]} prints Perl configuration information.

\Xi{|-w|} prints warnings about possible spelling errors and
other error-prone constructs in the script.

\Xi{|-x| [ <dir> ]} extracts Perl program from the input stream.
If <dir> is specified, switches to this directory before running 
the program.

\Xi{|-0| [ <val> ]} (that's the number zero) designates an
initial value for the record separator \$|/|.
See also |-l|.

\end{enum}

Command line options may be specified on the `|#!|' line of the perl
script, except for |-M|, |-m| and |-T|.


\section{Syntax} 

Perl is a free-format programming language. This means that in general
it does not matter how the Perl program is written with regard to
indentation and lines.

An exception to this rule is when the Perl compiler encounters a
`sharp' symbol (|#|) in the input: it then discards this symbol and
everything it follows up to the end of the current input line. This
can be used to put comments in Perl programs. Real programmers put
lots of useful comments in their programs.

There are places where whitespace does matter: within literal texts,
patterns and formats.

If the Perl compiler encounters the special token \_\,\_|END|\_\,\_ it
discards this symbol and stops reading input. Anything following this
token is ignored by the Perl compiler, but can be read by the program
when it is run.


\section{Variables} 

\begin{enum}{3.2cm}

\Xi{|\$var|} a simple scalar variable.

\Xi{|\$var[28]|} 29th element of array |@var|.

\Xi{|\$p = \char`\\@var|} now |$p| is a reference to array |@var|.

\Xi{|\$\$p[28]|} 29th element of array referenced by |$p|. 
Also: |$p->[28]|.

\Xi{|\$var[-1]|} last element of array |@var|.

\Xi{|\$var[\$i][\$j]|} |$j|-th element of |$i|-th element of array |@var|.

\Xi{|\$var\{'Feb'\}|} a value from `hash' (associative array) |%var|.

\Xi{|\$p = \char`\\\%var|} now |$p| is a reference to hash |%var|.

\Xi{|\$\$p\{'Feb'\}|} a value from hash referenced by |$p|. 
Also: |$p->{'Feb'}|.

\Xi{|\$\#var|} last index of array |@var|.

\Xi{|@var|} the entire array;
\\
in a scalar context, the number of elements in the array.

\Xi{|@var[3,4,5]|} a slice of array |@var|.

\Xi{|@var\{'a','b'\}|} a slice of |%var|; same as
|($var{'a'},$var{'b'})|.

\Xi{|\%var|} the entire hash;
\\
in a scalar context, \true{} if the hash has elements.

\Xj{|\$var\{'a',1,...\}|} emulates a multi-dimensional array.

\Xj{|('a'..'z')[4,7,9]|} a slice of an array literal.

\Xi{<pkg>|::|<var>} a variable from a package, e.g. |$pkg::var|, |@pkg::ary|.

\Xi{|\char`\\|<thingie>} reference to a thingie, e.g. |\$var|, |\%hash|.

\Xi{|*|<name>} refers to all thingies represented by <name>.
\\
`|*n1|~|=|~|*n2|' makes |n1| an alias for |n2|.
\\
`|*n1|~|=|~|\$n2|' makes |$n1| an alias for |$n2|.

\end{enum}

You can always use a |{| <block> |}| returning the right type of reference
instead of the variable identifier, e.g. |${|\ldots|}|, |&{|\ldots|}|.
|$$p| is just a shorthand for |${$p}|.

\clearpage

\section{Literals} 

Numeric: |123  1_234  123.4  5E-10  0xff| (hex)|  0377| (octal).

\hangindent=2cm\hangafter=1
String: |'abc'| literal string, no variable interpolation nor
escape characters, except |\'| and |\\|. Also: |q/abc/|.
Almost any pair of delimiters can be used instead of |/|\ldots|/|.

\hangindent=2cm\hangafter=1
\makebox[1cm]{}|"abc"|
Variables are interpolated and escape sequences are processed. 
\newline Also: |qq/abc/|.
\newline Escape sequences: |\t| (Tab), |\n| (Newline), |\r| (Return),
|\f| (Formfeed), |\b| (Backspace), |\a| (Alarm), |\e|
(Escape), |\033|(octal), |\x1b|(hex), |\c[| (control).
\newline |\l| and |\u| lowcase/upcase the following character; 
\newline |\L| and |\U| lowcase/upcase until a |\E| is encountered.
\newline |\Q| quote regexp characters until a |\E| is encountered.

\hangindent=2cm\hangafter=1
\makebox[1cm]{}|`|<command>|`|
evaluates to the output of the <command>. 
\newline Also: |qx/|<command>|/|.

\hangindent=1cm\hangafter=1
Boolean: Perl has no boolean data type. Anything that evaluates to the
null string, the number zero or the string |"0"| is considered
\false{}, everything else is \true{} (including strings like |"00"|!).


\hangindent=1cm\hangafter=1
Array: |(1,2,3)| a three member array. |()| is an empty array.  
\newline |(1..4)| is the same as |(1,2,3,4)|. Likewise |('abc'..'ade')|.
\newline |qw/foo bar| \ldots|/| is the same as |('foo','bar',|\ldots|)|.

\hangindent=1cm\hangafter=1
Array reference: |[1,2,3]|.

\hangindent=1cm\hangafter=1
Hash (associative array):
|(|<key1>|, |<val1>|, |<key2>|, |<val2>|, |\ldots|)|.
\newline Also: 
|(|<key1>| => |<val1>|, |<key2>| => |<val2>|, |\ldots|)|.

\hangindent=1cm\hangafter=1
Hash reference:
|{|<key1>|, |<val1>|, |<key2>|, |<val2>|, |\ldots|}|.

\hangindent=1cm\hangafter=1
Code reference:
\kwd{sub} |{| <statements> |}|

\hangindent=1cm\hangafter=1
Filehandles: |STDIN|, |STDOUT|, |STDERR|, |ARGV|, |DATA|.
\newline User-specified: <handle>, |$|<var>.

\hangindent=1cm\hangafter=1
Globs: |<|<pattern>|>| evaluates to all filenames according
to the pattern.
\newline Use `|<${|<var>|}>|' or `\kwd{glob} \$<var>' to glob from a variable.

\hangindent=1cm\hangafter=1
Here-Is: |<<|<identifier>
\quad Shell-style `here document'. 

\hangindent=1cm\hangafter=1
Special tokens:
\newline 
\_\,\_|FILE|\_\,\_: filename; 
\_\,\_|PACKAGE|\_\,\_: package;
\_\,\_|LINE|\_\,\_: line number.
\newline \_\,\_|END|\_\,\_: end of program; remaining lines can be read using
filehandle \<<data>\>.

\clearpage

\section{Operators and precedence} 

Perl operators have the following associativity and precedence,
listed from highest precedence to lowest. 

\vspace{1mm}

~\begin{tabular}{@{\vline~}c@{~\vline~}l@{~\vline~}l@{~\vline}}
\hline
Assoc & Operators & Description\hspace{40mm} \\ \hline
left & terms and list operators & See below. \\ \hline
left & |->| & Infix dereference operator. \\ \hline
 & |++| & Auto-increment (magical on strings). \\ 
 & |--| & Auto-decrement. \\ \hline
right & |**| & Exponentiation. \\ \hline
right & |\| & Reference to an object (unary). \\ 
right & |!  ~| & Unary negation, bitwise complement. \\ 
right & |+  -| & Unary plus, minus.\\ \hline
left & |=~|  & Binds a scalar expression to a pattern match. \\ 
left & |!~|  & Same, but negates the result. \\ \hline
left & |*  /  %  x| & Multiplication, division, modulo, repetition. \\ \hline
left & |+  -  .| & Addition, subtraction, concatenation. \\ \hline
left & |>>  <<| & Bitwise shift right, bitwise shift left. \\ \hline
 & named unary operators & E.g. \kwd{sin}, \kwd{chdir}, |-f|, |-M|.\\ \hline
 & |<  >  <=  >=| & Numerical relational operators.\\ 
 & \kwd{lt}~~\kwd{gt}~~\kwd{le}~~\kwd{ge} & String relational operators. \\ \hline
 & |==  !=  <=>| & Numerical equal, not equal, compare. \\ 
 & \kwd{eq}~~\kwd{ne}~~\kwd{cmp} & Stringwise equal, not equal, compare.\\
 & & Compare operators return -1 (less), 0 (equal) \\
 & & or 1 (greater).\\ \hline
left & \& & Bitwise AND. \\ \hline
left & \||  ^| & Bitwise OR, exclusive OR. \\ \hline
left & \&\& & Logical AND. \\ \hline
left & \|\| & Logical OR. \\ \hline
 & |..| & In scalar context, range operator. \\
 & & In array context, enumeration. \\ \hline
right & |?:| & Conditional (\textit{if} |?| \textit{then} |:| \textit{else}) operator. \\ \hline
right & |=  +=  -=  *= |etc. & Assignment operators. \\ \hline
left & |,| & Comma operator, also list element separator. \\ 
left & |=>| & Same, enforces the left operand to be a string. \\ \hline
 & list operators (rightward) & See below. \\ \hline
right & \kwd{not} & Low precedence logical NOT. \\ \hline
left & \kwd{and} & Low precedence logical AND. \\ \hline
left & \kwd{or}~~\kwd{xor} & Low precedence logical OR, exclusive OR.\\ \hline
\end{tabular}

\vspace{2mm}

Parentheses can be used to group an expression into a term.

A `list' is a list of expressions, variables or lists, separated by
commas. An array variable or an array slice may always be used instead
of a list.

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
side of the operator or at the right side of the operator.
\newline Parentheses can be added around the parameter lists 
to avoid precedence problems.

The logical operators do not evaluate the right operand if the
result is already known after evaluation of the left operand.


\section{Statements} 

Every statement is an expression, optionally followed by a modifier,
and terminated with 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 \kwd{if}, \kwd{unless}, \kwd{while} or \kwd{until},
e.g.:

\quad	<expr1> \kwd{if} <expr2> |;| \\
\quad	<expr1> \kwd{until} <expr2> |;|

The logical operators \|\|, |&&|, or |?:| also allow conditional execution,
e.g.:

\quad	<expr1> \|\| <expr2> |;| \\
\quad	<expr1> |?| <expr2> |:| <expr3> |;| 

Statements can be combined to form a <block> when enclosed in |{}|.
<block>s may be used to control flow:

\quad	\kwd{if} |(|<expr>|)| <block> [ [ \kwd{elsif}
	|(|<expr>|)| <BLOCK ...> ] \kwd{else}
	<block> ]
\\
\quad	\kwd{unless} |(|<expr>|)| <block> [ \kwd{else}
	<block> ]
\\
\quad	[ <label>\kwd{:} ] \kwd{while} |(|<expr>|)|
	<block> [ \kwd{continue} <block> ]
\\
\quad	[ <label>\kwd{:} ] \kwd{until} |(|<expr>|)|
	<block> [ \kwd{continue} <block> ]
\\
\quad	[ <label>\kwd{:} ] \kwd{for} |(| [ <expr> ] |;|
	[ <expr> ] |;| [ <expr> ] |)| <block>
\\
\quad	[ <label>\kwd{:} ] \kwd{foreach} <var>\dag
	|(|<list>|)| <block> [ \kwd{continue} < block> ]
\\
\quad	[ <label>\kwd{:} ] <block> [ \kwd{continue} < block> ]

Program flow can be controlled with:

\begin{enum}{1cm}

\Xi{\kwd{goto} <label>}
Finds the statement labeled with <label> and resumes execution there. 
<label> may be an expression that evaluates to the name of a label.

\Xi{\kwd{last} [ <label> ]}
Immediately exits the loop in question. Skips continue block.

\Xi{\kwd{next} [ <label> ]}
Starts the next iteration of the loop.

\Xi{\kwd{redo} [ <label> ]}
Restarts the loop block without evaluating the conditional again.

\end{enum}

Special forms are:

\quad	\kwd{do} <block> \kwd{while} <expr> |;| \\
\quad	\kwd{do} <block> \kwd{until} <expr> |;| \\

which are guaranteed to perform <block> once before testing <expr>, and

\quad	\kwd{do} <block>

which effectively turns <block> into an expression.


\section{Subroutines, packages and modules} 

\begin{enum}{1cm}

\Xi{<subroutine> [ <list> ]}
Executes a <subroutine> declared by a preceding \kwd{sub} declaration, and
returns the value of the last expression evaluated in <subroutine> .
\\
<subroutine> can be an expression yielding a reference to code.
In this case you can use |&${|<expr>|}(|[<list>]|)| or 
|${|<expr>|}->(|[<list>]|)|.

\Xi{|\char`\&|<subroutine> \kwd{(} [ <list> ] \kwd{)}}
Executes a <subroutine> not neccesarily declared 
before being used.

\Xi{\kwd{bless} <ref> [ \kwd{,} <classname> ]}
Turns the object <ref> into an object in <classname>.
Returns the reference.

\Xi{\kwd{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.

\Xi{\kwd{do} <subroutine> <list>} 
Deprecated form of |&|<subroutine> .

\Xi{\kwd{goto} |\char`\&|<subroutine>}
Substitutes a call to <subroutine> for the current subroutine.

\Xi{\kwd{import} <module> [ <version> ] [ <list> ]}
Imports the named items from <module>.
Checks the module for the required <version>.

\Xi{\kwd{no} <module> [ <list> ]}
Cancels imported semantics. See \kwd{use}.

\Xi{\kwd{package} <name>}
Designates the remainder of the current block as a package.

\Xi{\kwd{prototype} <name>}
Returns the prototype for this function.

\Xi{\kwd{require} \oEXPR}
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.
\newline If <expr> is a bare word, assumes extension `|.pm|'
for the name of the file. This form of loading of 
modules does not risk altering your namespace.

\Xi{\kwd{return} <expr>}
Returns from a subroutine with the value specified.

\Xi{\kwd{sub} <name> [ |(| <proto> |)| ] \{ <expr> |;| \ldots \}}
Designates <name> as a subroutine. Parameters are passed by reference
as array |@_|. Returns the value of the last expression evaluated. 
\newline <proto> can be used to define the required parameters.
\newline Without a <block> it is a forward declaration, 
without the <name> it is an anonymous subroutine.
Functions that have an empty prototype and do nothing but return a
fixed value are inlined.

\Xi{[ \kwd{sub} ] |BEGIN| \{ <expr> |;| \ldots \}}
Defines a setup <block> to be called before execution.

\Xi{[ \kwd{sub} ] |END| \{ <expr> |;| \dots \}}
Defines a cleanup <block> to be called upon termination.

\Xi{\kwd{tie} <var>\kwd{,} <classname>\kwd{,} [ <list> ]}
Ties a variable to a package class that will handle it.
Can be used to bind a dbm or ndbm file to a hash. 

\Xi{\kwd{tied} <var>}
Returns a reference to the object underlying <var>, or the undefined value
if <var> is not tied to a package class.

\Xi{\kwd{untie} <var>}
Breaks the binding between the variable and the package class.

\Xi{\kwd{use} <version>}
Requires perl version.

\Xi{\kwd{use} <module> [ <version> ] [ <list> ]}
Imports semantics from the named module into the current package.

\end{enum}

\subsection*{Standard methods}

The \kwd{UNIVERSAL} package contains the following methods that are
inherited by all other classes:

\begin{enum}{1cm}

\Xi{\kwd{isa} <class>}
Returns \true{} if its object is blessed into a subclass of <class>.

\Xi{\kwd{can} <method>}
Returns a reference to the method if its object has it, \undef{}
otherwise.

\Xi{\kwd{VERSION} [ <need> ]}
Returns the version of the class. Checks the version if <need> is
supplied.

\end{enum}


\section{Pragmatic modules} 

Pragmatic modules affect the compilation of your program. Pragmatic
modules can be activated (imported) with \kwd{use}, and deactivated
with \kwd{no}. These are locally scoped.

\begin{enum}{1.3cm}

\Xi{\kwd{autouse} <module> |=>| <subs>}
Defers \kwd{require} until one of the subs is called.

\Xi{\kwd{blib} [<dir>]}
Used for testing of uninstalled packages.

\Xi{\kwd{constant} <name> |=| <value>}
Defines <name> to have a constant (compile-time) value.

\Xi{\kwd{diagnostics}}
Force verbose warning diagnostics.

\Xi{\kwd{integer}}
Compute arithmetic in integer instead of double precision.

\Xi{\kwd{less}}
Request less of something from the compiler. 

\Xi{\kwd{lib}}
Manipulate |@INC| at compile time.

\Xi{\kwd{locale}}
Enable POSIX locales.

\Xi{\kwd{ops}}
Restrict unsafe operations when compiling.

\Xi{\kwd{overload}}
Package for overloading Perl operators.
\newline Example: |use overload "+" => \&my_add;|
 
\Xi{\kwd{sigtrap}}
Enable simple signal handling.
\newline Example: |use sigtrap qw(SEGV TRAP);|

\Xi{\kwd{strict}}
Restrict unsafe constructs.
\newline |use strict "refs"| restricts the use of symbolic references.
\newline |use strict "vars"| requires all variables to be either local or
fully qualified.
\newline |use strict "subs"| restricts the use of bareword identifiers
that are not subroutines.

\Xi{\kwd{subs}}
Predeclare subroutine names, allowing you to use them 
without parentheses even before they are declared.
\newline Example: |use subs qw(ding dong);|

\Xi{\kwd{vars}}
Predeclare variable names, allowing you to use them 
under ``use strict''.
\newline Example: |use vars qw($foo @bar);|

\Xi{\kwd{vmsish}}
Emulate some VMS behaviour.

\end{enum}


\section{Object oriented programming} 

Perl rules of object oriented programming:

\begin{enum}{3mm}

\Xj{$\bullet$}
An object is simply a reference that happens to know which class it
belongs to.
\newline Objects are blessed, references are not.

\Xj{$\bullet$}
A class is simply a package that happens to provide methods to deal
with object references.
\newline If a package fails to provide a method, the base classes as
listed in |@ISA| are searched.

\Xj{$\bullet$}
A method is simply a subroutine that expects an object reference (or a
package name, for static methods) as the first argument.
\newline Methods can be applied with:\\
\hspace*{1cm}<method> <objref> <parameters>\quad\quad\quad\quad or\\
\hspace*{1cm}<objref>|->|<method> <parameters>

\end{enum}


\section{Arithmetic functions} 

\begin{enum}{1cm}

\Xi{\kwd{abs} \oEXPR}
Returns the absolute value of its operand.

\Xi{\kwd{atan2} <y>\kwd{,} <x>}
Returns the arctangent of <Y>/<X> in the range -$\pi$ to $\pi$.

\Xi{\kwd{cos} \oEXPR}
Returns the cosine of <expr> (expressed in radians).

\Xi{\kwd{exp} \oEXPR}
Returns \textit{e} to the power of <expr>.

\Xi{\kwd{int} \oEXPR}
Returns the integer portion of <expr>.

\Xi{\kwd{log} \oEXPR}
Returns natural logarithm (base \textit{e}) of <expr>.

\Xi{\kwd{rand} [ <expr> ]}
Returns a random fractional number between 0 and the value of <expr>.
If <expr> is omitted, returns a value between 0 and 1. 

\Xi{\kwd{sin} \oEXPR}
Returns the sine of <expr> (expressed in radians).

\Xi{\kwd{sqrt} \oEXPR}
Returns the square root of <expr>.

\Xi{\kwd{srand} [ <expr> ]}
Sets the random number seed for the \kwd{rand} operator.

\Xi{\kwd{time}}
Returns the number of seconds since January 1, 1970. Suitable for
feeding to \kwd{gmtime} and \kwd{localtime}. 

\end{enum}

\clearpage

\section{Conversion functions} 

\begin{enum}{1cm}

\Xi{\kwd{chr} \oEXPR}
Returns the character represented by the decimal value <expr>.

\Xi{\kwd{gmtime} \oEXPR}
Converts a time as returned by the \kwd{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 localized for the
standard Greenwich time zone.
\$mon has the range 0..11 and \$wday has the range 0..6.

\Xi{\kwd{hex} \oEXPR}
Returns the decimal value of <expr> interpreted as an hex string.

\Xi{\kwd{localtime} \oEXPR}
Converts a time as returned by the \kwd{time} function to
\tool{ctime}(3) string. In array context, returns a 9-element array
(see \kwd{gmtime}) with the time localized for the local time zone.

\Xi{\kwd{oct} \oEXPR}
Returns the decimal value of <expr> interpreted as an octal string. If
<expr> starts off with |0x|, interprets it as a hex string instead.

\Xi{\kwd{ord} \oEXPR}
Returns the ASCII value of the first character of <expr>.

\Xi{\kwd{vec} <expr>\kwd{,} <offset>\kwd{,} <bits>}
Treats string <expr> as a vector of unsigned integers of <bits> bits
each, and yields the decimal value of the element at <offset>. <bits>
must be a power of 2 between 1 and 32. May be assigned to.

\end{enum}


\section{Structure conversion} 

\begin{enum}{1cm}

\Xi{\kwd{pack} <template>\kwd{,} <list>}
Packs the values into a binary structure using <template>.

\Xi{\kwd{unpack} <template>\kwd{,} <expr>}
Unpacks the structure <expr> into an array, using <template>.

\end{enum}

<template> is a sequence of characters as follows:

\begin{tabbing}
|  |\=|a |\=|/ |\=|A  |\= \kill
  \> |a| \> / \> |A| \> ASCII string, null / space padded \\
  \> |b| \> / \> |B| \> Bit string in ascending / descending order \\
  \> |c| \> / \> |C| \> Native / unsigned char value \\
  \> |f| \> / \> |d| \> Single / double float in native format \\
  \> |h| \> / \> |H| \> Hex string, low / high nybble first. \\
  \> |i| \> / \> |I| \> Signed / unsigned integer value \\
  \> |l| \> / \> |L| \> Signed / unsigned long value \\
  \> |n| \> / \> |N| \> Short / long in network (big endian) byte order \\
  \> |s| \> / \> |S| \> Signed / unsigned short value \\
  \> |u| \> / \> |p| \> Uuencoded string / pointer to a string \\
  \> |P| \>   \>     \> A pointer to a structure (fixed-length string) \\
  \> |v| \> / \> |V| \> Short / long in VAX (little endian) byte order \\
  \> |w| \> / \> |x| \> BER compressed integer / null byte \\
  \> |X| \> / \> |@| \> Backup a byte / null fill until position
\end{tabbing}

Each character may be followed by a decimal number which will be used
as a repeat count, `|*|' specifies all remaining arguments. \\
If the format is preceded with |%|<n>, \kwd{unpack} returns an
<n>-bit checksum instead. \\
Spaces may be included in the template for readability purposes.


\section{String functions} 

\begin{enum}{1cm}

\Xi{\kwd{chomp} <list>\dag}
Removes line endings from all elements of the list; 
returns the (total) number of characters removed.

\Xi{\kwd{chop} <list>\dag}
Chops off the last character on all elements of the list; returns the
last chopped character. 

\Xi{\kwd{crypt} <plaintext>\kwd{,} <salt>}
Encrypts a string.

\Xi{\kwd{eval} \oEXPR}
<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, \undef is returned by
\kwd{eval}, and |$@| is set to the error message. 
See also \kwd{eval} in section `Miscellaneous'.

\Xi{\kwd{index} <str>\kwd{,} <substr> [ \kwd{,} <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').

\Xi{\kwd{length} \oEXPR}
Returns the length in characters of <expr>.

\Xi{\kwd{lc} \oEXPR}
Returns a lower case version of <expr>.

\Xi{\kwd{lcfirst} \oEXPR}
Returns <expr> with the first character in lower case.

\Xi{\kwd{quotemeta} \oEXPR}
Returns <expr> with all regexp meta-characters quoted.

\Xi{\kwd{rindex} <str>\kwd{,} <substr> [ \kwd{,} <offset> ]}
Returns the position of the last <substr> in <str> at or
before <offset>.

\Xi{\kwd{substr} <expr>\kwd{,} <offset> [ \kwd{,} <len> ]}
Extracts a substring out of <expr> and returns it. If <offset>
is negative, counts from the end of the string. 
If <len> is negative, leaves that many characters off the end of the string.
May be assigned to.

\Xi{\kwd{uc} \oEXPR}
Returns an upper case version of <expr>.

\Xi{\kwd{ucfirst} \oEXPR}
Returns <expr> with the first character in upper case.

\end{enum}


\section{Array and hash functions} 

\begin{enum}{1cm}

\Xi{\kwd{delete} \$<hash>\{<key>\}}
Deletes the specified value from the specified hash.
Returns the deleted value (unless <hash> is \kwd{tie}d to a package
that does not support this).

\Xi{\kwd{each} |\%|<hash>}
Returns a 2-element array consisting of the key and value for the next
value of the hash.
After all values of the hash have been returned, an empty list is
returned. The next call to \kwd{each} after that will start iterating
again.

\Xi{\kwd{exists} \oEXPR}
Checks whether the specified hash key exists in its hash array.

\Xi{\vbox{\vspace*{3pt}
          \hbox{\kwd{grep} <expr>\kwd{,} <list>}
          \hbox{\kwd{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. 

\Xi{\kwd{join} <expr>\kwd{,} <list>}
Joins the separate strings of <list> into a single string with fields
separated by the value of <expr>, and returns the string.

\Xi{\kwd{keys} |\%|<hash>}
Returns an array of all the keys of the named hash.

\Xi{\vbox{\vspace*{3pt}
          \hbox{\kwd{map} <expr>\kwd{,} <list>}
          \hbox{\kwd{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.

\Xi{\kwd{pop} [ |@|<array> ] }
Pops off and returns the last value of the array.
If |@|<array> is omitted, pops |@ARGV| in main and |@_| in subroutines.

\Xi{\kwd{push} |@|<array>\kwd{,} <list>}
Pushes the values of the list onto the end of the array.

\Xi{\kwd{reverse} <list>}
In array context: returns the <list> in reverse order. \\
In scalar
context: returns the first element of <list> with bytes reversed. 

\Xi{\kwd{scalar} |@|<array>}
Returns the number of elements in the array.

\Xi{\kwd{scalar} |\%|<hash>}
Returns a \true{} value if the hash has elements defined.

\Xi{\kwd{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.  

\Xi{\kwd{sort}  [ <subroutine> ] <list>}
Sorts the <list> and returns the sorted array value. If <subroutine>
is specified, gives the name of a subroutine that returns less than
zero, zero, or greater than zero, depending on how the elements of the
array, available to the routine as package global variables |$a| and |$b|,
 are to be ordered.
\\
<subroutine> may be the name of a user-defined routine, or a <block>.

\Xi{\kwd{splice} |@|<array>\kwd{,} <offset> [ \kwd{,} <length> [ \kwd{,} <list> ] ]}
Removes the elements of |@|<array> designated by <offset> and
<length>, and replaces them with <list> (if specified).
Returns the elements removed.

\Xi{\kwd{split} [ <pattern> [ \kwd{,} \oEXPR{} [ \kwd{,} <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
omitted, splits on whitespace (after skipping any leading whitespace).
If not in array context: returns number of fields and splits to |@_|.

\Xi{\kwd{unshift} |@|<array>\kwd{,} <list>}
Prepends list to the front of the array, and returns the number of
elements in the new array.

\Xi{\kwd{values} |\%|<hash>}
Returns a normal array consisting of all the values of the named
hash. 

\end{enum}




\section{Regular expressions} 
\def\xtraspace{\vspace{5pt}}

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

\begin{enum}{1cm}

\Xj{|.|}
matches an arbitrary character, but not a newline unless 
the modifier |/s| is used.

\Xj{|(|\ldots|)|}
groups a series of pattern elements to a single element.

\Xj{\^}
matches the beginning of the target. In multi-line mode (see
\kwd{m}|//|\kwd{m}) also matches after every newline character.

\Xj{\$}
matches the end of the line.
In multi-line mode also matches before every newline character.

\Xj{|\char`\[|\ldots|\char`\]|}
denotes a class of characters to match. |[|\^\ldots|]| negates the class.

\Xj{|(|\ldots\|\ldots\|\ldots|)|}
matches one of the alternatives.

\Xj{|(?|\char`\# ~<text> |)|}
Comment.

\Xj{|(?:| <regexp> |)|}
Like |(|<regexp>|)| but does not make back-references.

\Xj{|(?=| <regexp> |)|}
Zero width positive look-ahead assertion.

\Xj{|(?!| <regexp> |)|}
Zero width negative look-ahead assertion.

\Xj{|(?| <modifier> |)|}
Embedded pattern-match modifier. <modifier> can be one or more of
\kwd{i}, \kwd{m}, \kwd{s} or \kwd{x}.

\end{enum}

\xtraspace
Quantified subpatterns match as many times as possible. 
When followed with a `|?|' they match the minimum number of times.
These are the quantifiers:

\begin{enum}{1cm}

\Xj{|+|}
matches the preceding pattern element one or more times.

\Xj{|?|}
matches zero or one times.

\Xj{|*|}
matches zero or more times.

\Xj{\{<n>|,|<m>\}}
denotes the minimum <n> and maximum <m> match count. |{|<n>|}| means
exactly <n> times; |{|<n>|,}| means at least <n> times. 

\end{enum}

\xtraspace
A `|\|' escapes any special meaning of the following character
if non-alphanumeric, but it turns most alphanumeric characters
into something special:

\begin{enum}{1cm}

\Xj{|\char`\\w|}
matches alphanumeric, including `|_|', |\W| matches non-alphanumeric.

\Xj{|\char`\\s|}
matches whitespace, |\S| matches non-whitespace.

\Xj{|\char`\\d|}
matches numeric, |\D| matches non-numeric.

\Xj{|\char`\\A|}
matches the beginning of the string, |\Z| matches the end.

\Xj{|\char`\\b|}
matches word boundaries, |\B| matches non-boundaries.

\Xj{|\char`\\G|}
matches where the previous \kwd{m}|//|\kwd{g} search left off.

\Xj{|\char`\\n|, |\char`\\r|, |\char`\\f|, |\char`\\t|, etc.} 
have their usual meaning.

\Xj{|\char`\\w|, |\char`\\s| and |\char`\\d|}
may be used within character classes, 
|\b| denotes a backspace in this context.

\end{enum}

\xtraspace
Back-references:

\begin{enum}{1cm}

\Xj{|\char`\\1|\ldots|\char`\\9|} 
refer to matched sub-expressions, grouped with |()|, inside the match. 

\Xj{|\char`\\10| and up}
can also be used if the pattern matches that many sub-expressions. 

\end{enum}

See also |$1|\ldots|$9|, |$+|, |$&|, |$`| and |$'| in section `Special
variables'.

\xtraspace
With modifier \kwd{x}, whitespace and comments can be used in the
patterns for readability purposes.


\section{Search and replace functions}

\begin{enum}{1cm}

\catcode`\~=\other

\Xi{[ <expr> |=~| ] [ \kwd{m} ] |/|<pattern>|/| [ \kwd{c g i m o s x} ]}
Searches <expr> (default: |$_|) for a pattern. If you prepend an
\kwd{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
sub-expressions matched by the parentheses in pattern, i.e.
|($1,$2,$3,|\ldots|)|.
\\
Optional modifiers:
\kwd{c} continues the previous match (use with \kwd{g});
\kwd{g} matches as many times as possible; 
\kwd{i} searches in a case-insensitive manner; 
\kwd{o} interpolates variables only once.
\newline 
\kwd{m}let `|^|' and `|$|' match even at embedded newline characters;
\kwd{s} let `|.|' match even at embedded newline characters;
\kwd{x} allows for regular expression extensions.
\\
If <pattern> is empty, the most recent pattern from a
previous successful match or replacement is used.
\\
With \kwd{g} the match can be used as an iterator in scalar context.
The iterator is reset upon failure, unless \kwd{c} is also supplied.

\Xi{|?|<pattern>|?|}
This is just like the |/|<pattern>|/| search, except that it matches
only once between calls to the \kwd{reset} operator.

\Xi{[ |\$|<var> |=~| ] \kwd{s}|/|<pattern>|/|<replacement>|/| [ \kwd{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, otherwise it returns \false{}. 
\\
Optional modifiers: \kwd{g} replaces all occurrences of the pattern;
\kwd{e} evaluates the replacement string as a Perl expression; for the other 
modifiers, see |/|<pattern>|/| matching. Almost any delimiter may
replace the slashes; if single quotes are used, no interpolation 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
successful match or replacement is used.

\Xi{[ |\$|<var> |=~| ] \kwd{tr}|/|<searchlist>|/|<replacementlist>|/| [ \kwd{c d s} ]}
Translates all occurrences of the characters found in the search list
into the corresponding character in the replacement list. It returns
the number of characters replaced. \kwd{y} may be used instead of \kwd{tr}. 
\\
Optional modifiers: \kwd{c} complements the <searchlist>; \kwd{d}
deletes all characters found in <searchlist> that do not have a
corresponding character in <replacementlist>; \kwd{s} squeezes all
sequences of characters that are translated into the same target
character into one occurrence of this character.

\Xi{\kwd{pos} [ <scalar>\dag{} ]}
Returns the position where the last \kwd{m}|//|\kwd{g} search left off
for <scalar>. May be assigned to.

\Xi{\kwd{study} [ |\$|<var>\dag{} ]}
Studies the scalar variable |$|<var> in anticipation of performing many
pattern matches on its contents before the variable is next modified.

\end{enum}


\section{File test operators} 

These unary operators take 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 info of the preceding test or \kwd{stat} call.

\begin{enum}{2.5cm}

\Xi{|-r -w -x|}  File is readable/writable/executable by effective uid/gid.

\Xi{|-R -W -X|}  File is readable/writable/executable by real uid/gid.

\Xi{|-o  -O|}  File is owned by effective/real uid. 

\Xi{|-e  -z|}  File exists / has zero size. 

\Xi{|-s|}  File exists and has non-zero size. Returns the size.

\Xi{|-f  -d|}  File is a plain file, a directory.

\Xi{|-l  -S  -p|}  File is a symbolic link, a socket, a named pipe (FIFO). 

\Xi{|-b  -c|}  File is a block/character special file. 

\Xi{|-u  -g  -k|}  File has setuid/setgid/sticky bit set. 

\Xi{|-t|}  Tests if filehandle (|STDIN| by default) is opened to a tty.

\Xi{|-T  -B|}  File is a text/non-text (binary) file.  |-T| and |-B|
return \true{} on a null file, or a file at EOF when testing a filehandle. 

\Xi{|-M  -A  -C|}  File modification/access/inode-change time. Measured
in days. Value returned reflects the file age at the time the script
started. See also |$^T| in section `Special variables'.

\end{enum}


\section{File operations} 

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

\begin{enum}{1cm}

\Xi{\kwd{chmod} <list>}
Changes the permissions of a list of files. The first element of the
list must be the numerical mode. 

\Xi{\kwd{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. 

\Xi{\kwd{truncate} <file>\kwd{,} <size>}
truncates <file> to <size>. <file> may be a filename or a filehandle.

\Xi{\kwd{link} <oldfile>\kwd{,} <newfile>}
Creates a new filename linked to the old filename.

\Xi{\kwd{lstat} <file>\dag}
Like \kwd{stat}, but does not traverse a final symbolic link.

\Xi{\kwd{mkdir} <dir>\kwd{,} <mode>}
Creates a directory with given permissions. Sets |$!| on failure.

\Xi{\kwd{readlink} \oEXPR}
Returns the value of a symbolic link.

\Xi{\kwd{rename} <oldname>\kwd{,} <newname>}
Changes the name of a file.

\Xi{\kwd{rmdir} <filename>\dag}
Deletes the directory if it is empty. Sets |$!| on failure.

\pagebreak[2]
\Xi{\kwd{stat} <file>\dag}
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 \kwd{stat} call.
\\
Returns an empty list if the \kwd{stat} fails.

\Xi{\kwd{symlink} <oldfile>\kwd{,} <newfile>}
Creates a new filename symbolically linked to the old filename.

\Xi{\kwd{unlink} <list>\dag}
Deletes a list of files.

\Xi{\kwd{utime} <list>}
Changes the access and modification times. The first two elements of
the list must be the numerical access and modification times.

\end{enum}



\vspace{-1mm}

\section{Input / Output} 

In input/output operations, <filehandle> may be a filehandle as opened
by the \kwd{open} operator, a pre-defined filehandle (e.g. |STDOUT|)
or a scalar variable that evaluates to a reference to or the name of a
filehandle to be used.

\begin{enum}{1cm}

\Xi{\<<filehandle>\>}
In scalar context: reads a single line from the file opened on <filehandle>. 
In array context: reads the whole file.

\Xi{\<\,\>}
Reads from the input stream formed by the files specified in
|@ARGV|, or standard input if no arguments were supplied.

\Xi{\kwd{binmode} <filehandle>}
Arranges for the file opened on <filehandle> to be read or written in
\textit{binary} mode as opposed to \textit{text} mode (null-operation on UNIX).

\Xi{\kwd{close} <filehandle>}
Closes the file or pipe associated with the file handle.

\Xi{\kwd{dbmclose} |\%|<hash>}
Deprecated, use \kwd{untie} instead.

\Xi{\kwd{dbmopen} |\%|<hash>\kwd{,} <dbmname>\kwd{,} <mode>}
Deprecated, use \kwd{tie} instead.

\Xi{\kwd{eof} <filehandle>}
Returns \true{} if the next read will return end of file, or if the
file is not open.

\Xi{\kwd{eof}}
Returns the eof status for the last file read.

\Xj{\kwd{eof(}\,\kwd{)}}
Indicates eof on the pseudo-file formed of the files listed on the
command line. 

\Xi{\kwd{fcntl} <filehandle>\kwd{,} <function>\kwd{,} |\$|<var>}
Performs \tool{fcntl}(2) on the file. This function has non-standard
return values. 

\Xi{\kwd{fileno} <filehandle>}
Returns the file descriptor for a given (open) file.

\Xi{\kwd{flock} <filehandle>\kwd{,} <op>}
Calls a system-dependent locking routine on the file. <op> is
formed by adding 1 (shared), 2 (exclusive), 4 (non-blocking) or 8
(unlock).

\Xi{\kwd{getc} [ <filehandle> ]}
Yields the next character from the file, or an empty string on eof.
\newline If <filehandle> is omitted, reads from |STDIN|. 

\Xi{\kwd{ioctl} <filehandle>\kwd{,} <function>\kwd{,} |\$|<var>}
Performs \tool{ioctl}(2) on the file. This function has non-standard
return values. 

\Xi{\kwd{open} <filehandle> [ \kwd{,} <filename> ]}
Opens a file and associates it with <filehandle>. 
\kwd{open} returns \true{} upon success.
If <filename> is
omitted, uses the scalar variable of the same name as the <filehandle>.

The following filename conventions apply when opening a file.

\begin{enum}{23mm}
\Xi{|"|<file>|"|} open <file> for input. Also |"<|<file>|"|.

\Xi{|">|<file>|"|} open <file> for output, creating it if necessary.

\Xi{|">>|<file>|"|} open <file> in append mode.

\Xi{|"+\<|<file>|"|} open existing <file> with read/write access.

\Xi{|"+\>|<file>|"|} create new <file> with read/write access.

\Xi{|"+\>\>|<file>|"|} read/write access in append mode.

\Xi{|"\||<cmd>|"|} opens a pipe to command <cmd>; 
forks if <cmd> is `|-|'.

\Xi{|"|<cmd>|\|"|} opens a pipe from command <cmd>;
forks if <cmd> is `|-|'.
\end{enum}

<file> may be |&|<filehnd>, in which case the new file handle is
connected to the (previously opened) filehandle <filehnd>.
If it is |&=|<n>, <file> will be connected to the given file descriptor.

\Xi{\kwd{pipe} <readhandle>\kwd{,} <writehandle>}
Returns a pair of connected pipes.

\Xi{\kwd{print} [ <filehandle> ] [ <list>\dag ]}
Prints the elements of <list>, converting them to strings if needed. If
<filehandle> is omitted, prints by default to standard output (or to
the last selected output channel, see \kwd{select}).

\Xi{\kwd{printf} [ <filehandle> ] [ <list>\dag ]}
Equivalent to |print| <filehandle> |sprintf| <list>.

\Xi{\kwd{read} <filehandle>\kwd{,} |\$|<var>\kwd{,} <length> [ \kwd{,} <offset> ]}
Reads <length> binary bytes from the file into the variable at
<offset>. Returns number of bytes actually read. 

\Xi{\kwd{seek} <filehandle>\kwd{,} <position>\kwd{,} <whence>}
Arbitrarily positions the file. Returns \true{} upon success.

\Xi{\kwd{select} [ <filehandle> ]}
Returns the currently selected filehandle. 
Sets the current default filehandle for output operations if
<filehandle> is supplied.

\Xi{\kwd{select} <rbits>\kwd{,} <wbits>\kwd{,} <nbits>\kwd{,} <timeout>}
Performs a \tool{select}(2) system call with the same parameters.

\Xi{\kwd{sprintf} <format>\kwd{,} <list>}
Returns a string formatted in the style of \tool{printf}(3)
conventions. 

\Xi{\kwd{sysopen} <filehandle>\kwd{,} <path>\kwd{,} <mode> [ \kwd{,} <perms> ]}
Performs an \tool{open}(2) system call.
The possible values and flag bits of <mode> are
system-dependent; they are available via the standard module |Fcntl|.

\Xi{\kwd{sysread} <filehandle>\kwd{,} |\$|<var>\kwd{,} <length> [ \kwd{,} <offset> ]}
Reads <length> bytes into |$|<var> at <offset>.

\Xi{\kwd{sysseek} <filehandle>\kwd{,} <position>\kwd{,} <whence>}
Performs a \tool{seek}(2) system call.

\Xi{\kwd{syswrite} <filehandle>\kwd{,} <scalar>\kwd{,} <length> [ \kwd{,} <offset> ]}
Writes <length> bytes from <scalar> at <offset>.

\Xi{\kwd{tell} [ <filehandle> ]}
Returns the current file position for the file. If <filehandle> is
omitted, assumes the file last read. 

\end{enum}

\clearpage

\section{Formats} 

\begin{enum}{1cm}

\Xi{\kwd{formline} <picture>\kwd{,} <list>}
Formats <list> according to <picture> and accumulates the result into \$\^|A|.

\Xi{\kwd{write} [ <filehandle> ]}
Writes a formatted record to the specified file, using the format
associated with that file.

\end{enum}

Formats are defined as follows:

\kwd{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:

\begin{tabbing}
|  |\=|         |\=\kill
\>|@<<<|\ldots    \> left adjusted field, repeat the |<| to denote the desired
                     width; \\
\>|@>>>|\ldots    \> right adjusted field; \\
\>|@|\|\|\|\ldots \> centered field; \\
\>|@#.##|\ldots   \> numeric format with implied decimal point; \\
\>|@*|            \> a multi-line field.
\end{tabbing}

Use \^ instead of |@| for multi-line 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. 

Set |$-| to zero to force a page break on the next \kwd{write}.

See also |$|\^, |$~|, |$^A|, |$^F|, |$-| and |$=| 
in section `Special variables'.


\section{Directory reading routines} 

\begin{enum}{1cm}

\Xi{\kwd{closedir} <dirhandle>}
Closes a directory opened by \kwd{opendir}.

\Xi{\kwd{opendir} <dirhandle>\kwd{,} <dirname>}
Opens a directory on the handle specified.

\Xi{\kwd{readdir} <dirhandle>}
Returns the next entry (or an array of entries) from the directory.

\Xi{\kwd{rewinddir} <dirhandle>}
Positions the directory to the beginning.

\Xi{\kwd{seekdir} <dirhandle>\kwd{,} <pos>}
Sets position for \kwd{readdir} on the directory.

\Xi{\kwd{telldir} <dirhandle>}
Returns the position in the directory.

\end{enum}


\section{System interaction} 

\begin{enum}{1cm}

\Xi{\kwd{alarm} \oEXPR }
Schedules a |SIGALRM| to be delivered after <expr> seconds. 

\Xi{\kwd{chdir} [ <expr> ]}
Changes the working directory.
\newline Uses |$ENV{"HOME"}| or |$ENV{"LOGNAME"}| if <expr> is omitted.

\Xi{\kwd{chroot} <filename>\dag}
Changes the root directory for the process and its children.

\Xi{\kwd{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"|.
\newline 
Inside an \kwd{eval}, the error message is put into |$@|, and the
\kwd{eval} is terminated with \undef; this makes
\kwd{die} the way to raise an exception.

\Xi{\kwd{exec} <list>}
Executes the system command in <list>; does not return.

\Xi{\kwd{exit} [ <expr> ]}
Exits immediately with the value of |EXPR|, which defaults to |0| (zero).
Calls |END| routines and object destructors before exiting.

\Xi{\kwd{fork}}
Does a \tool{fork}(2) system call. Returns the process ID of the child
to the parent process and zero to the child process.

\Xi{\kwd{getlogin}}
Returns the current login name as known by the system.
If it returns \false{}, use \kwd{getpwuid}.

\Xi{\kwd{getpgrp} [ <pid> ]}
Returns the process group for process <pid> (0, or omitted,  means the
current process). 

\Xi{\kwd{getppid}}
Returns the process ID of the parent process.

\Xi{\kwd{getpriority} <which>\kwd{,} <who>}
Returns the current priority for a process, process group, or user.

\Xi{\kwd{glob} <pat>\dag}
Returns a list of filenames that match the shell pattern <pat>.

\Xi{\kwd{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). 
Negative signals kill process groups instead of processes.

\Xi{\kwd{setpgrp} <pid>\kwd{,} <pgrp>}
Sets the process group for the <pid> (0 indicates the current process).

\Xi{\kwd{setpriority} <which>\kwd{,} <who>\kwd{,} <prio>}
Sets the current priority for a process, process group, or a user.

\Xi{\kwd{sleep} [ <expr> ]}
Causes the program to sleep for <expr> seconds, or forever if no
<expr>. Returns the number of seconds actually slept. 

\Xi{\kwd{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. 

\Xi{\kwd{system} <list>}
Does exactly the same thing as \kwd{exec} <list> except that a fork is
done first, and the parent process waits for the child process to
complete.
Returns the exit status of the child process.

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

\Xi{\kwd{umask} [ <expr> ]}
Sets the umask for the process and returns the old one. If <expr> is
omitted, returns current umask value. 

\Xi{\kwd{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 |$?|. 

\Xi{\kwd{waitpid} <pid>\kwd{,} <flags>}
Performs the same function as the corresponding system call.

\Xi{\kwd{warn} [ <list> ]}
Prints the <list> on |STDERR| like \kwd{die}, but does not exit.
\newline <list> defaults to |"Warning: something's wrong"|.

\end{enum}


\section{Networking} 

\begin{enum}{1cm}

\Xi{\kwd{accept} <newsocket>\kwd{,} <genericsocket>}
Accepts a new socket.

\Xi{\kwd{bind} <socket>\kwd{,} <name>}
Binds the <name> to the <socket>.

\Xi{\kwd{connect} <socket>\kwd{,} <name>}
Connects the <name> to the <socket>.

\Xi{\kwd{getpeername} <socket>}
Returns the socket address of the other end of the <socket>.

\Xi{\kwd{getsockname} <socket>}
Returns the name of the socket.

\Xi{\kwd{getsockopt} <socket>\kwd{,} <level>\kwd{,} <optname>}
Returns the socket options.

\Xi{\kwd{listen} <socket>\kwd{,} <queuesize>}
Starts listening on the specified <socket>.

\Xi{\kwd{recv} <socket>\kwd{,} <scalar>\kwd{,} <length>\kwd{,} <flags>}
Receives a message on <socket>.

\Xi{\kwd{send} <socket>\kwd{,} <msg>\kwd{,} <FLAGS [ >\kwd{,} <to> ]}
Sends a message on the <socket>.

\Xi{\kwd{setsockopt} <socket>\kwd{,} <level>\kwd{,} <optname>\kwd{,} <optval>}
Sets the requested socket option.

\Xi{\kwd{shutdown} <socket>\kwd{,} <how>}
Shuts down a <socket>.

\Xi{\kwd{socket} <socket>\kwd{,} <domain>\kwd{,} <type>\kwd{,} <protocol>}
Creates a <socket> in <domain> with <type> and <protocol>.

\Xi{\kwd{socketpair} <socket1>\kwd{,} <socket2>\kwd{,} <domain>\kwd{,} <type>\kwd{,} <protocol>}
As socket, but creates a pair of bi-directional sockets.

\end{enum}


\section{SystemV IPC} 

Depending on your system configuration, certain system files need to
be \kwd{require}d to access the message and semaphore specific
facilities.

\begin{enum}{1cm}

\Xi{\kwd{msgctl} <id>\kwd{,} <cmd>\kwd{,} <args>}
Calls \tool{msgctl}(2). If <cmd> is |IPC_STAT| then <args> must 
be a single variable.
See the manual for details on the non-standard return values of this function.

\Xi{\kwd{msgget} <key>\kwd{,} <flags>}
Creates a message queue for <key>.
Returns the message queue identifier.

\Xi{\kwd{msgsnd} <id>\kwd{,} <msg>\kwd{,} <flags>}
Sends <msg> to queue <id>.

\Xi{\kwd{msgrcv} <id>\kwd{,} \$<var>\kwd{,} <size>\kwd{,} <type>\kwd{,} <flags>}
Receives a message from queue <id> into <var>.

\Xi{\kwd{semctl} <id>\kwd{,} <semnum>\kwd{,} <cmd>\kwd{,} <arg>}
Calls \tool{semctl}(2).\\
If <cmd> is |IPC_STAT| or |GETALL| then <arg> must 
be a variable.

\Xi{\kwd{semget} <key>\kwd{,} <nsems>\kwd{,} <size>\kwd{,} <flags>}
Creates a set of semaphores for <key>.
Returns the message semaphore identifier.

\Xi{\kwd{semop} <key>\kwd{,} ...}
Performs semaphore operations.

\Xi{\kwd{shmctl} <id>\kwd{,} <cmd>\kwd{,} <arg>}
Calls \tool{shmctl}(2). If <cmd> is |IPC_STAT| then <arg> must 
be a single variable.

\Xi{\kwd{shmget} <key>\kwd{,} <size>\kwd{,} <flags>}
Creates shared memory.
Returns the shared memory segment identifier.

\Xi{\kwd{shmread} <id>\kwd{,} \$<var>\kwd{,} <pos>\kwd{,} <size>}
Reads at most <size> bytes of the contents of shared memory segment <id>
starting at offset <pos> into <var>.

\Xi{\kwd{shmwrite} <id>\kwd{,} <string>\kwd{,} <pos>\kwd{,} <size>}
Writes at most <size> bytes of <string> into the contents of 
shared memory segment <id> at offset <pos>.

\end{enum}


\section{Miscellaneous} 

\begin{enum}{1cm}

\Xi{\kwd{defined} \oEXPR}
Tests whether the <expr> has an actual value.

\Xi{\kwd{do} <filename>}
Executes <filename> as a Perl script.
See also \kwd{require} in section `Subroutines, packages and modules'.

\Xi{\kwd{dump} [ <label> ]}
Immediate core dump. When reincarnated, starts at <label>.

\Xi{\kwd{eval\{}<expr>\kwd{;} \ldots \}}
Executes the code between \{ and \}. Traps run-time errors as described
with \kwd{eval(}<expr>\kwd{)}, section `String~functions'.

\Xi{\kwd{local} <var>}
Creates a scope for <var> local to the enclosing block,
subroutine or \kwd{eval}. 

\Xi{\kwd{my} <var>}
Creates a scope for the variable lexically
local to the enclosing block, subroutine or \kwd{eval}. 

\Xi{\kwd{ref} \oEXPR}
Returns a \true{} value if <expr> is a reference.
Returns the package name if <expr> has been blessed into a package.

\Xi{\kwd{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.

\Xi{\kwd{scalar} <expr> }
Forces evaluation of <expr> in scalar context.

\Xi{\kwd{undef} [ <lvalue> ]}
Undefines the <lvalue>. Always returns the undefined value.

\Xi{\kwd{wantarray}}
Returns \true{} if the current context expects an list value.
\undef{} if the current context does not expect a value at all,
\false{} otherwise.

\end{enum}


\section{Information from system files} 
See the manual about return values in scalar context.

{\largesl passwd} \\
Returns (\$name, \$passwd, \$uid, \$gid, \$quota, \$comment, \$gcos, \$dir, \$shell).

\begin{enum}{6cm}

\Xi{\kwd{endpwent}}
Ends look-up processing.

\Xi{\kwd{getpwent}}
Gets next user information.

\Xi{\kwd{getpwnam} <name>}
Gets information by name. 

\Xi{\kwd{getpwuid} <uid>}
Gets information by user ID.

\Xi{\kwd{setpwent}}
Resets look-up processing.

\end{enum}

{\vskip6pt\largesl group} \\
Returns (\$name, \$passwd, \$gid, \$members).

\begin{enum}{6cm}

\Xi{\kwd{endgrent}}
Ends look-up processing.

\Xi{\kwd{getgrgid} <gid>}
Gets information by group ID. 

\Xi{\kwd{getgrnam} <name>}
Gets information by name.

\Xi{\kwd{getgrent}}
Gets next group information.

\Xi{\kwd{setgrent}}
Resets lookup processing.

\end{enum}

{\vskip6pt\largesl hosts} \\
Returns (\$name, \$aliases, \$addrtype, \$length, @addrs).

\begin{enum}{6cm}

\Xi{\kwd{endhostent}}
Ends look-up processing.

\Xi{\kwd{gethostbyaddr} <addr>\kwd{,} <addrtype>}
Gets information by IP address.

\Xi{\kwd{gethostbyname} <name>}
Gets information by host name.

\Xi{\kwd{gethostent}}
Gets next host information.

\Xi{\kwd{sethostent} <stayopen>}
Resets look-up processing.

\end{enum}

{\vskip6pt\largesl networks} \\
Returns (\$name, \$aliases, \$addrtype, \$net).

\begin{enum}{6cm}

\Xi{\kwd{endnetent}}
Ends look-up processing.

\Xi{\kwd{getnetbyaddr} <addr>\kwd{,} <type>}
Gets information by address and type.

\Xi{\kwd{getnetbyname} <name>}
Gets information by network name.

\Xi{\kwd{getnetent}}
Gets next network information.

\Xi{\kwd{setnetent} <stayopen>}
Resets look-up processing.

\end{enum}

{\vskip6pt\largesl services} \\
Returns (\$name, \$aliases, \$port, \$proto).

\begin{enum}{6cm}

\Xi{\kwd{endservent}}
Ends look-up processing.

\Xi{\kwd{getservbyname} <name>\kwd{, }<proto>}
Gets information by service name. 

\Xi{\kwd{getservbyport} <port>\kwd{, }<proto>}
Gets information by service port.

\Xi{\kwd{getservent}}
Gets next service information.

\Xi{\kwd{setservent} <stayopen>}
Resets look-up processing.

\end{enum}

{\vskip6pt\largesl protocols} \\
Returns (\$name, \$aliases, \$proto).

\begin{enum}{6cm}

\Xi{\kwd{endprotoent}}
Ends look-up processing.

\Xi{\kwd{getprotobyname} <name>}
Gets information by protocol name.

\Xi{\kwd{getprotobynumber} <number>}
Gets information by protocol number.

\Xi{\kwd{getprotoent}}
Gets next protocol information.

\Xi{\kwd{setprotoent} <stayopen>}
Resets look-up processing.

\end{enum}


\section{Special variables} 

The following variables are global and should be localized in subroutines:

\begin{enum}{1cm}

\Xi{|\char`\$\char`\_|}
The default input and pattern-searching space.

\Xi{|\char`\$\char`\.|}
The current input line number of the last filehandle that was read.
Reset only when the filehandle is closed explicitly.

\Xi{|\char`\$\char`\/|}
The input record separator, newline by default. May be multi-character.

\Xi{|\char`\$\char`\,|}
The output field separator for the print operator.

\Xi{|\char`\$\char`\"|}
The separator which joins elements of arrays interpolated in strings.

\Xi{|\char`\$\char`\\|}
The output record separator for the print operator.

\Xi{|\char`\$\char`\#|}
The output format for printed numbers. Deprecated.

\Xi{|\char`\$\char`\*|}
Set to 1 to do multiline matching within strings.
Deprecated, see the \kwd{m} and \kwd{s} modifiers in section 
`Search and replace functions'.

\Xi{|\char`\$\char`\?|}
The status returned by the last |`|\ldots|`| command, pipe \kwd{close} or
\kwd{system} operator. 

\Xi{|\char`\$\char`\]|}
The Perl version number, e.g. |5.004|.

\Xi{|\char`\$\char`\[|}
The index of the first element in an array, and of the first character
in a substring. Default is 0. Deprecated.

\Xi{|\char`\$\char`\;|}
The subscript separator for multi-dimensional array emulation. Default
is |"\034"|. 

\Xi{|\char`\$\char`\!|}
If used in a numeric context, yields the current value of |errno|. If
used in a string context, yields the corresponding error string. 

\Xi{|\char`\$\char`\@|}
The Perl error message from the last \kwd{eval} or \kwd{do} <expr> command.

\Xi{|\char`\$\char`\:|}
The set of characters after which a string may be broken to fill
continuation fields (starting with `|^|') in a format. 

\Xi{|\char`\$\char`\0|}
The name of the file containing the Perl script being executed. May be
assigned to. 

\Xi{|\char`\$\char`\$|}
The process ID of the Perl interpreter running this script. Altered (in the
child process) by \kwd{fork}. 

\Xi{|\char`\$\char`\<|}
The real user ID of this process.

\Xi{|\char`\$\char`\>|}
The effective user ID of this process. 

\Xi{|\char`\$\char`\(|}
The real group ID of this process.

\Xi{|\char`\$\char`\)|}
The effective group ID and groups of this process.

\Xi{|\char`\$\char`\^A|}
The accumulator for \kwd{formline} and \kwd{write} operations.

\Xi{|\char`\$\char`\^D|}
The debug flags as passed to Perl using `|-D|'.

\Xi{|\char`\$\char`\^E|}
Extended error message on some platforms.

\Xi{|\char`\$\char`\^F|}
The highest system file descriptor, ordinarily 2.

\Xi{|\char`\$\char`\^H|}
Set of syntax checks enabled by `|use strict|'.

\Xi{|\char`\${\char`\^}I|}
In-place edit extension as passed to Perl using `|-i|'.

\Xi{|\char`\$\char`\^L|}
Formfeed character used in formats.

\Xi{|\char`\$\char`\^M|}
Out-of-memory emergency pool.

\Xi{|\char`\$\char`\^P|}
Internal debugging flag.

\Xi{|\char`\$\char`\^T|}
The time (as delivered by \kwd{time}) when the program started. This
value is used by the file test operators `|-M|', `|-A|' and `|-C|'.

\Xi{|\char`\$\char`\^W|}
The value of the `|-w|' option as passed to Perl.

\Xi{|\char`\$\char`\^X|}
The name by which this Perl interpreter was invoked.

\end{enum}

The following variables are context dependent and need not be
localized:

\begin{enum}{1cm}

\Xi{|\char`\$\char`\%|}
The current page number of the currently selected output channel.

\Xi{|\char`\$\char`\=|}
The page length of the current output channel. Default is 60 lines.

\Xi{|\char`\$\char`\-|}
The number of lines remaining on the page.

\Xi{|\char`\$\char`\~|}
The name of the current report format.

\Xi{|\char`\$\char`\^|}
The name of the current top-of-page format.

\Xi{|\char`\$\char`\||}
If set to nonzero, forces a flush after every write or print on the
output channel currently selected. Default is 0. 

\Xj{|\char`\$ARGV|}
The name of the current file when reading from |<|\,|>| .
\end{enum}

The following variables are always local to the current block:

\begin{enum}{1cm}

\Xi{|\char`\$\char`\&|}
The string matched by the last successful pattern match.

\Xi{|\char`\$\char`\`|}
The string preceding what was matched by the last successful match.

\Xi{|\char`\$\char`\'|}
The string following what was matched by the last successful match. 

\Xi{|\char`\$\char`\+|}
The last bracket matched by the last search pattern.

\Xj{\$|1|\ldots\$|9|\ldots}
Contain the subpatterns from the corresponding sets of parentheses in
the last pattern successfully matched.
|$10| and up are only available if the
match contained that many subpatterns. 

\end{enum}




\section{Special arrays} 

\begin{enum}{1.5cm}

\Xi{|@ARGV|}
Contains the command line arguments for the script (not including the command name).

\Xi{|@EXPORT|}
Names the methods a package exports by default.

\Xi{|@EXPORT\_OK|}
Names the methods a package can export upon explicit request.

\Xi{|@INC|}
Contains the list of places to look for Perl scripts to be evaluated
by the \kwd{do} <filename>, \kwd{use} and \kwd{require} commands. 
\newline Do not modify directly, but use the `|use lib|' pragma or 
|-I| command line option instead.

\Xi{|@ISA|}
List of base classes of a package.

\Xi{|@\char`\_|}
Parameter array for subroutines. Also used by \kwd{split} if not in
array context. 

\Xi{|\char`\%ENV|}
Contains the current environment.

\Xi{|\char`\%INC|}
List of files that have been included with \kwd{use}, 
\kwd{require} or \kwd{do}.


\Xi{|\char`\%SIG|}Used to set signal handlers for various signals.
\newline \_\,\_|WARN|\_\,\_ and \_\,\_|DIE|\_\,\_ are pseudo-signals to 
attach handlers to Perl warnings and exceptions.

\end{enum}


\section{Standard modules}

\begin{enum}{1cm}

\Xi{AnyDBM\_File}
Provides a framework for multiple dbm files.

\Xi{AutoLoader}
Load functions only on demand.

\Xi{AutoSplit}
Split a package for autoloading.

\Xi{Benchmark}
Benchmark running times of code.

\Xi{CGI}
Web server Common Gateway Interface.

\Xi{CGI::Apache}
Support for Apache's Perl module.

\Xi{CGI::Carp}
Log server errors with helpful context.

\Xi{CGI::Fast}
Support for FastCGI (persistent server process).

\Xi{CGI::Push}
Support for server push.

\Xi{CGI::Switch}
Simple interface for multiple server types.

\Xi{CPAN}
Interface to Comprehensive Perl Archive Network.

\Xi{CPAN::FirstTime}
Utility for creating CPAN configuration file.

\Xi{CPAN::Nox}
Run CPAN while avoiding compiled extensions.

\Xi{Carp}
Warn of errors.

\Xi{Class::Struct}
Declare struct-like datatypes as Perl classes.

\Xi{Config}
Access to Perl configuration information.

\Xi{Cwd}
Get the pathname of current working directory.

\Xi{DB\_File}
Access to Berkeley DB files.

\Xi{Devel::SelfStubber}
Generate stubs for a SelfLoading module.

\Xi{Dirhandle}
Supplies object methods for directory handles.

\Xi{DynaLoader}
Dynamically loads C libraries into Perl code.

\Xi{English}
Use long English names for punctuation variables.

\Xi{Env}
Imports environment variables.

\Xi{Exporter}
Implements default import method for modules.

\Xi{ExtUtils::Embed}
Utilities for embedding Perl in C/C++ applications.

\Xi{ExtUtils::Install}
Install files from here to there.

\Xi{ExtUtils::Liblist}
Determine libraries to use and how to use them.

\Xi{ExtUtils::MakeMaker}
Create an extension Makefile.

\Xi{ExtUtils::Manifest}
Utilities to write and check a MANIFEST file.

\Xi{ExtUtils::Miniperl}
Write the C code for |perlmain.c|.

\Xi{ExtUtils::Mkbootstrap}
Make a bootstrap file for use by DynaLoader.

\Xi{ExtUtils::Mksymlists}
Write linker options files for dynamic extension.

\Xi{ExtUtils::MM\_OS2}
Methods to override Unix behaviour in ExtUtils::MakeMaker.

\Xi{ExtUtils::MM\_Unix}
Methods used by ExtUtils::MakeMaker.

\Xi{ExtUtils::MM\_VMS}
Methods to override Unix behaviour in ExtUtils::MakeMaker.

\Xi{ExtUtils::testlib}
Adds |blib/*| directories to |@INC|.

\Xi{Fatal}
Replaces functions with equivalents which succeed or die.

\Xi{Fcntl}
Loads the C |fcntl.h| defines.

\Xi{File::Basename}
Parse file specifications.

\Xi{FileCache}
Keep more files open than the system permits.

\Xi{File::CheckTree}
Run many filetest checks on a tree.

\Xi{File::Copy}
Copy files or filehandles.

\Xi{File::Find}
Traverse a file tree.

\Xi{FileHandle}
Supplies object methods for filehandles.

\Xi{File::Path}
Create or remove a series of directories.

\Xi{File::stat}
By-name interface to Perl's builtin \kwd{stat}.

\Xi{FindBin}
Locate the directory of the original Perl script.

\Xi{GDBM\_File}
Access to the gdbm library.

\Xi{Getopt::Long}
Extended handling of command line options. Suits all needs.

\Xi{Getopt::Std}
Process single-character switches with switch clustering.

\Xi{I18N::Collate}
Compare 8-bit scalar data according to the current locale.

\Xi{IO}
Loads various IO modules.

\Xi{IO::File}
Supplies object methods for filehandles.

\Xi{IO::Handle}
Supplies object methods for I/O handles.

\Xi{IO::Pipe}
Supplies object methods for pipes.

\Xi{IO::Seekable}
Supplies seek based methods for I/O objects.

\Xi{IO::Select}
Object interface to the \kwd{select} system call.

\Xi{IO::Socket}
Object interface to socket communications.

\Xi{IPC::Open2}
Open a pipe to a process for both reading and writing.

\Xi{IPC::Open3}
Open a pipe to a process for reading, writing, and error handling.

\Xi{Math::BigFloat}
Arbitrary length float math package.

\Xi{Math::BigInt}
Arbitrary size integer math package.

\Xi{Math::Complex}
Complex numbers and associated mathematical functions.

\Xi{Math::Trig}
Trigoniometric functions.

\Xi{NDBM\_File}
Tied access to ndbm files.

\Xi{Net::hostent}
By-name interface to Perl's builtin gethost functions.

\Xi{Net::netent}
By-name interface to Perl's builtin getnet functions.

\Xi{Net::Ping}
Check a host for upness.

\Xi{Net::protoent}
By-name interface to Perl's builtin getproto functions.

\Xi{Net::servent}
By-name interface to Perl's builtin getserv functions.

\Xi{Opcode}
Disable named opcodes when compiling Perl code.

\Xi{Pod::Text}
Convert POD data to formatted ASCII text.

\Xi{POSIX}
Interface to IEEE Std 1003.1.

\Xi{Safe}
Compile and execute code in restricted compartments.

\Xi{SDBM\_File}
Tied access to sdbm files.

\Xi{Search::Dict}
Search for key in dictionary file.

\Xi{SelectSaver}
Save and restore a selected file handle.

\Xi{SelfLoader}
Load functions only on demand.

\Xi{Shell}
Run shell commands transparently within Perl.

\Xi{Socket}
Load the C |socket.h| defines and structure manipulators.

\Xi{Symbol}
Manipulate Perl symbols and their names.

\Xi{Sys::Hostname}
Try every conceivable way to get the name of this system.

\Xi{Sys::Syslog}
Interface to the Unix \tool{syslog}(3) calls.

\Xi{Term::Cap}
Perl interface to Unix \tool{termcap}(3).

\Xi{Term::Complete}
Word completion module.

\Xi{Term::ReadLine}
Interface to various readline packages.

\Xi{Test::Harness}
Run Perl standard test scripts with statistics.

\Xi{Text::Abbrev}
Create an abbreviation table from a list.

\Xi{Text::ParseWords}
Parse text into an array of tokens.

\Xi{Text::Soundex}
Implementation of the Soundex Algorithm as described by Donald Knuth.

\Xi{Text::Tabs}
Expand and unexpand tabs.

\Xi{Text::Wrap}
Line wrapping to form simple paragraphs.

\Xi{Tie::Hash}
Base class definitions for tied hashes.

\Xi{Tie::RefHash}
Base class for tied hashes with references as keys.

\Xi{Tie::StdHash}
Basic methods for tied hashes.

\Xi{Tie::Scalar}
Base class definitions for tied scalars.

\Xi{Tie::StdScalar}
Basic methods for tied scalars.

\Xi{Tie::SubstrHash}
Fixed table-size, fixed key-length hashing.

\Xi{Time::gmtime}
By-name interface to Perl's builtin \kwd{gmtime}.

\Xi{Time::Local}
Efficiently compute time from local and GMT time.

\Xi{Time::localtime}
By-name interface to Perl's builtin \kwd{localtime}.

\Xi{Time::tm}
Internal object for Time::gmtime and Time::localtime.

\Xi{UNIVERSAL}
Base class for all classes (blessed references).

\Xi{User::grent}
By-name interface to Perl's builtin getgroup functions.

\Xi{User::pwent}
By-name interface to Perl's builtin getpasswd functions.

\end{enum}


\section{Environment variables} 

Perl uses the following environment variables.

\begin{enum}{1.5cm}

\Xi{|HOME|}
Used if \kwd{chdir} has no argument.

\Xi{|LOGDIR|}
Used if \kwd{chdir} has no argument and |HOME| is not set.

\Xi{|PATH|}
Used in executing subprocesses, and in finding the Perl script if `|-S|'
is used.

\Xi{|PERL5LIB|}
A colon-separated list of directories to look in for Perl library files
before looking in the standard library and the current directory.

\Xi{|PERL5DB|}
The command to get the debugger code.
\newline Defaults to \hbox{|BEGIN { require 'perl5db.pl' }|}. 

\Xi{|PERLLIB|}
Used instead of |PERL5LIB| if the latter is not defined.

\Xi{|PERL5OPT|}
Used to set initial (command line) options for perl.

\end{enum}


\section{The perl debugger} 

The Perl symbolic debugger is invoked with `|perl -d|'.

\begin{enum}{2.7cm}

\Xi{|h|}
Prints out a long help message.

\Xi{|h| <cmd>}
Prints out help for the command <cmd>.

\Xi{|h h|}
Prints out a concise help message.

\Xi{|T|}
Prints a stack trace.

\Xi{|s| [ <expr> ] }
Single steps.

\Xi{|n| [ <expr> ] }
Single steps around subroutine call.

\Xi{\fbox{<ret>}}
Repeats last `|s|' or `|n|'.

\Xi{|r|}
Returns from the current subroutine.

\Xi{|c| [ <line> ]}
Continues (until <line>, or another breakpoint, or exit).

\Xi{|p| \oEXPR}
Prints <expr>.

\Xi{|l| [ <range> ]}
Lists a range of lines. <range> may be a number, start--end,
start+amount, or a subroutine name. 
If <range> is omitted, lists next window. 

\Xi{|w| [ <line> ]}
Lists window around the specified line.

\Xi{|-|}
Lists previous window.

\Xi{|.|}
Returns to the executed line.

\Xi{|f| <file>}
Switches to <file> and starts listing it.

\Xi{|l| <sub>}
Lists the named subroutine.

\Xi{|S| [|!|]<pattern>}
Lists the names of all subroutines [not] matching the pattern.

\Xi{|/|<pattern>|/|}
Searches forwards for <pattern>.

\Xi{|?|<pattern>|?|}
Searches backwards for <pattern>.

\Xi{|b| [ <line> [ <condition> ]]}
Sets breakpoint at <line>, default is the current line.

\Xi{|b| <sub> [ <condition> ]}
Sets breakpoint at the named subroutine.

\Xi{|d| [ <line> ]}
Deletes breakpoint at the given line.

\Xi{|D|}
Deletes all breakpoints.

\Xi{|L|}
Lists lines that have breakpoints or actions.

\Xi{|a| [ <line> ] <command>}
Sets an action for line.

\Xi{|A|}
Deletes all line actions.

\Xi{|\char`\<| <command>}
Sets an action to be executed before every debugger prompt.

\Xi{|\char`\>| <command>}
Sets an action to be executed after every debugger prompt.

\Xi{|V| [ <package> [ <pattern> ] ]}
Lists variables matching <pattern> in a package. Default package is |main|.

\Xi{|X| [ <pattern> ]}
Like `|V|', but assumes the current package.

\Xi{|!| [ [-]<number> ]}
Re-executes a command. Default is the previous command.

\Xi{|!| [ <pattern> ]}
Re-executes the last command that started with <pattern>.

\Xi{|!!| [ <command> ]}
Runs <command> in a sub-process.

\Xi{|H| [ -<number> ]}
Displays the last -<number> commands.

\Xi{|\|| <cmd>}
Runs debugger command <cmd> through the current pager.

\Xi{|\|\|| <cmd>}
Same, temporarily \kwd{select}s |DB::OUT| as well.

\Xi{|t|}
Toggles trace mode.

\Xi{|t| <expr>}
Traces through execution of <expr>.

\Xi{|x| <expr>}
Evals <expr> in list context, dumps the result.

\Xi{|O| [ <opt> [|=|<val>] ]}
Sets or queries values of debugger options.

\Xi{|=|< > [ <alias value> ]}
Sets alias, or lists current aliases.

\Xi{|R|}
Restarts the debugger.

\Xi{|q|}
Quits. You may also use your \fbox{<eof>} character.

\Xi{<command>}
Executes <command> as a Perl statement.

\end{enum}






\begin{titlepage}
  \hbox{~}
  \vfill
  \vbox{%
    \rule[3pt]{\textwidth}{0.25pt}
    \parbox{\textwidth}{
      {\large
       Perl Reference Guide Revision \refrev\\
       \copyright 2003,1989,1997 Johan Vromans \<jvromans@squirrel.nl\>.\\
       It may be reproduced, printed and distributed freely for
       non-profit purposes, as long as the original author gets the
       credits, and the copyright notice is not removed.
       It may not be turned into a commercial product except with
       written permission of the author.\\
       Perl is \copyright 2003-1997 Larry Wall.\\
       The camel as an image associated with Perl is a trademark of\\
       O'Reilly \char'46{} Associates, Inc. and is used with permission.}}
    \rule[-2pt]{\textwidth}{0.25pt}}
\end{titlepage}



\end{document}