perlfunc

Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services

NAME

       perlfunc - Perl builtin functions


DESCRIPTION

       The functions in this section can serve as terms in an
       expression.  They fall into two major categories: list
       operators and named unary operators.  These differ in
       their precedence relationship with a following comma.
       (See the precedence table in the perlop manpage.)  List
       operators take more than one argument, while unary
       operators can never take more than one argument.  Thus, a
       comma terminates the argument of a unary operator, but
       merely separates the arguments of a list operator.  A
       unary operator generally provides a scalar context to its
       argument, while a list operator may provide either scalar
       and list contexts for its arguments.  If it does both, the
       scalar arguments will be first, and the list argument will
       follow.  (Note that there can ever be only one list
       argument.)  For instance, splice() has three scalar
       arguments followed by a list.

       In the syntax descriptions that follow, list operators
       that expect a list (and provide list context for the
       elements of the list) are shown with LIST as an argument.
       Such a list may consist of any combination of scalar
       arguments or list values; the list values will be included
       in the list as if each individual element were
       interpolated at that point in the list, forming a longer
       single-dimensional list value.  Elements of the LIST
       should be separated by commas.

       Any function in the list below may be used either with or
       without parentheses around its arguments.  (The syntax
       descriptions omit the parentheses.)  If you use the
       parentheses, the simple (but occasionally surprising) rule
       is this: It LOOKS like a function, therefore it IS a
       function, and precedence doesn't matter.  Otherwise it's a
       list operator or unary operator, and precedence does
       matter.  And whitespace between the function and left
       parenthesis doesn't count--so you need to be careful
       sometimes:

           print 1+2+4;        # Prints 7.
           print(1+2) + 4;     # Prints 3.
           print (1+2)+4;      # Also prints 3!
           print +(1+2)+4;     # Prints 7.
           print ((1+2)+4);    # Prints 7.

       If you run Perl with the -w switch it can warn you about
       this.  For example, the third line above produces:

           print (...) interpreted as function at - line 1.
           Useless use of integer addition in void context at - line 1.

       For functions that can be used in either a scalar or list
       context, nonabortive failure is generally indicated in a
       scalar context by returning the undefined value, and in a
       list context by returning the null list.

       Remember the following rule:

       THERE IS NO GENERAL RULE FOR CONVERTING A LIST INTO A
               SCALAR!

       Each operator and function decides which sort of value it
       would be most appropriate to return in a scalar context.
       Some operators return the length of the list that would
       have been returned in a list context.  Some operators
       return the first value in the list.  Some operators return
       the last value in the list.  Some operators return a count
       of successful operations.  In general, they do what you
       want, unless you want consistency.

       Perl Functions by Category

       Here are Perl's functions (including things that look like
       functions, like some of the keywords and named operators)
       arranged by category.  Some functions appear in more than
       one place.

       Functions for SCALARs or strings
            chomp, chop, chr, crypt, hex, index, lc, lcfirst,
            length, oct, ord, pack, q/STRING/, qq/STRING/,
            reverse, rindex, sprintf, substr, tr///, uc, ucfirst,
            y///

       Regular expressions and pattern matching
            m//, pos, quotemeta, s///, split, study

       Numeric functions
            abs, atan2, cos, exp, hex, int, log, oct, rand, sin,
            sqrt, srand

       Functions for real @ARRAYs
            pop, push, shift, splice, unshift

       Functions for list data
            grep, join, map, qw/STRING/, reverse, sort, unpack

       Functions for real %HASHes
            delete, each, exists, keys, values

       Input and output functions
            binmode, close, closedir, dbmclose, dbmopen, die,
            eof, fileno, flock, format, getc, print, printf,
            read, readdir, rewinddir, seek, seekdir, select,
            syscall, sysread, sysseek, syswrite, tell, telldir,
            truncate, warn, write

       Functions for fixed length data or records
            pack, read, syscall, sysread, syswrite, unpack, vec

       Functions for filehandles, files, or directories
            -X, chdir, chmod, chown, chroot, fcntl, glob, ioctl,
            link, lstat, mkdir, open, opendir, readlink, rename,
            rmdir, stat, symlink, umask, unlink, utime

       Keywords related to the control flow of your perl program
            caller, continue, die, do, dump, eval, exit, goto,
            last, next, redo, return, sub, wantarray

       Keywords related to scoping
            caller, import, local, my, package, use

       Miscellaneous functions
            defined, dump, eval, formline, local, my, reset,
            scalar, undef, wantarray

       Functions for processes and process groups
            alarm, exec, fork, getpgrp, getppid, getpriority,
            kill, pipe, qx/STRING/, setpgrp, setpriority, sleep,
            system, times, wait, waitpid

       Keywords related to perl modules
            do, import, no, package, require, use

       Keywords related to classes and object-orientedness
            bless, dbmclose, dbmopen, package, ref, tie, tied,
            untie, use

       Low-level socket functions
            accept, bind, connect, getpeername, getsockname,
            getsockopt, listen, recv, send, setsockopt, shutdown,
            socket, socketpair

       System V interprocess communication functions
            msgctl, msgget, msgrcv, msgsnd, semctl, semget,
            semop, shmctl, shmget, shmread, shmwrite

       Fetching user and group info
            endgrent, endhostent, endnetent, endpwent, getgrent,
            getgrgid, getgrnam, getlogin, getpwent, getpwnam,
            getpwuid, setgrent, setpwent

       Fetching network info
            endprotoent, endservent, gethostbyaddr,
            gethostbyname, gethostent, getnetbyaddr,
            getnetbyname, getnetent, getprotobyname,
            getprotobynumber, getprotoent, getservbyname,
            getservbyport, getservent, sethostent, setnetent,
            setprotoent, setservent


       Time-related functions
            gmtime, localtime, time, times

       Functions new in perl5
            abs, bless, chomp, chr, exists, formline, glob,
            import, lc, lcfirst, map, my, no, prototype, qx, qw,
            readline, readpipe, ref, sub*, sysopen, tie, tied,
            uc, ucfirst, untie, use

            * - sub was a keyword in perl4, but in perl5 it is an
            operator which can be used in expressions.

       Functions obsoleted in perl5
            dbmclose, dbmopen

       Alphabetical Listing of Perl Functions


       -X FILEHANDLE

       -X EXPR

       -X      A file test, where X is one of the letters listed
               below.  This unary operator takes one argument,
               either a filename or a filehandle, and tests the
               associated file to see if something is true about
               it.  If the argument is omitted, tests $_, except
               for -t, which tests STDIN.  Unless otherwise
               documented, it returns 1 for TRUE and '' for
               FALSE, or the undefined value if the file doesn't
               exist.  Despite the funny names, precedence is the
               same as any other named unary operator, and the
               argument may be parenthesized like any other unary
               operator.  The operator may be any of:

                   -r  File is readable by effective uid/gid.
                   -w  File is writable by effective uid/gid.
                   -x  File is executable by effective uid/gid.
                   -o  File is owned by effective uid.

                   -R  File is readable by real uid/gid.
                   -W  File is writable by real uid/gid.
                   -X  File is executable by real uid/gid.
                   -O  File is owned by real uid.

                   -e  File exists.
                   -z  File has zero size.
                   -s  File has nonzero size (returns size).






                   -f  File is a plain file.
                   -d  File is a directory.
                   -l  File is a symbolic link.
                   -p  File is a named pipe (FIFO).
                   -S  File is a socket.
                   -b  File is a block special file.
                   -c  File is a character special file.
                   -t  Filehandle is opened to a tty.

                   -u  File has setuid bit set.
                   -g  File has setgid bit set.
                   -k  File has sticky bit set.

                   -T  File is a text file.
                   -B  File is a binary file (opposite of -T).

                   -M  Age of file in days when script started.
                   -A  Same for access time.
                   -C  Same for inode change time.

               The interpretation of the file permission
               operators -r, -R, -w, -W, -x, and -X is based
               solely on the mode of the file and the uids and
               gids of the user.  There may be other reasons you
               can't actually read, write or execute the file.
               Also note that, for the superuser, -r, -R, -w, and
               -W always return 1, and -x and -X return 1 if any
               execute bit is set in the mode.  Scripts run by
               the superuser may thus need to do a stat() to
               determine the actual mode of the file, or
               temporarily set the uid to something else.

               Example:

                   while (<>) {
                       chop;
                       next unless -f $_;      # ignore specials
                       ...
                   }

               Note that -s/a/b/ does not do a negated
               substitution.  Saying -exp($foo) still works as
               expected, however--only single letters following a
               minus are interpreted as file tests.

               The -T and -B switches work as follows.  The first
               block or so of the file is examined for odd
               characters such as strange control codes or
               characters with the high bit set.  If too many odd
               characters (>30%) are found, it's a -B file,
               otherwise it's a -T file.  Also, any file
               containing null in the first block is considered a
               binary file.  If -T or -B is used on a filehandle,
               the current stdio buffer is examined rather than
               the first block.  Both -T and -B return TRUE on a
               null file, or a file at EOF when testing a
               filehandle.  Because you have to read a file to do
               the -T test, on most occasions you want to use a
               -f against the file first, as in next unless -f
               $file && -T $file.

               If any of the file tests (or either the stat() or
               lstat() operators) are given the special
               filehandle consisting of a solitary underline,
               then the stat structure of the previous file test
               (or stat operator) is used, saving a system call.
               (This doesn't work with -t, and you need to
               remember that lstat() and -l will leave values in
               the stat structure for the symbolic link, not the
               real file.)  Example:

                   print "Can do.\n" if -r $a || -w _ || -x _;

                   stat($filename);
                   print "Readable\n" if -r _;
                   print "Writable\n" if -w _;
                   print "Executable\n" if -x _;
                   print "Setuid\n" if -u _;
                   print "Setgid\n" if -g _;
                   print "Sticky\n" if -k _;
                   print "Text\n" if -T _;
                   print "Binary\n" if -B _;


       abs VALUE

       abs     Returns the absolute value of its argument.  If
               VALUE is omitted, uses $_.

       accept NEWSOCKET,GENERICSOCKET
               Accepts an incoming socket connect, just as the
               accept(2) system call does.  Returns the packed
               address if it succeeded, FALSE otherwise.  See
               example in the section on Sockets: Client/Server
               Communication in the perlipc manpage.

       alarm SECONDS

       alarm   Arranges to have a SIGALRM delivered to this
               process after the specified number of seconds have
               elapsed.  If SECONDS is not specified, the value
               stored in $_ is used. (On some machines,
               unfortunately, the elapsed time may be up to one
               second less than you specified because of how
               seconds are counted.)  Only one timer may be
               counting at once.  Each call disables the previous
               timer, and an argument of 0 may be supplied to
               cancel the previous timer without starting a new
               one.  The returned value is the amount of time
               remaining on the previous timer.

               For delays of finer granularity than one second,
               you may use Perl's syscall() interface to access
               setitimer(2) if your system supports it, or else
               see the select() entry elsewhere in this document
               .  It is usually a mistake to intermix alarm() and
               sleep() calls.

               If you want to use alarm() to time out a system
               call you need to use an eval/die pair.  You can't
               rely on the alarm causing the system call to fail
               with $! set to EINTR because Perl sets up signal
               handlers to restart system calls on some systems.
               Using eval/die always works.

                   eval {
                       local $SIG{ALRM} = sub { die "alarm\n" };       # NB \n required
                       alarm $timeout;
                       $nread = sysread SOCKET, $buffer, $size;
                       alarm 0;
                   };
                   die if $@ && $@ ne "alarm\n";       # propagate errors
                   if ($@) {
                       # timed out
                   }
                   else {
                       # didn't
                   }


       atan2 Y,X
               Returns the arctangent of Y/X in the range -pi to
               pi.

               For the tangent operation, you may use the
               POSIX::tan() function, or use the familiar
               relation:

                   sub tan { sin($_[0]) / cos($_[0])  }


       bind SOCKET,NAME
               Binds a network address to a socket, just as the
               bind system call does.  Returns TRUE if it
               succeeded, FALSE otherwise.  NAME should be a
               packed address of the appropriate type for the
               socket.  See the examples in the section on
               Sockets: Client/Server Communication in the
               perlipc manpage.

       binmode FILEHANDLE
               Arranges for the file to be read or written in
               "binary" mode in operating systems that
               distinguish between binary and text files.  Files
               that are not in binary mode have CR LF sequences
               translated to LF on input and LF translated to CR
               LF on output.  Binmode has no effect under Unix;
               in MS-DOS and similarly archaic systems, it may be
               imperative--otherwise your MS-DOS-damaged C
               library may mangle your file.  The key distinction
               between systems that need binmode and those that
               don't is their text file formats.  Systems like
               Unix and Plan9 that delimit lines with a single
               character, and that encode that character in C as
               '\n', do not need binmode.  The rest need it.  If
               FILEHANDLE is an expression, the value is taken as
               the name of the filehandle.

       bless REF,CLASSNAME

       bless REF
               This function tells the thingy referenced by REF
               that it is now an object in the CLASSNAME
               package--or the current package if no CLASSNAME is
               specified, which is often the case.  It returns
               the reference for convenience, because a bless()
               is often the last thing in a constructor.  Always
               use the two-argument version if the function doing
               the blessing might be inherited by a derived
               class.  See the perlobj manpage for more about the
               blessing (and blessings) of objects.

       caller EXPR

       caller  Returns the context of the current subroutine
               call.  In a scalar context, returns the caller's
               package name if there is a caller, that is, if
               we're in a subroutine or eval() or require(), and
               the undefined value otherwise.  In a list context,
               returns

                   ($package, $filename, $line) = caller;

               With EXPR, it returns some extra information that
               the debugger uses to print a stack trace.  The
               value of EXPR indicates how many call frames to go
               back before the current one.

                   ($package, $filename, $line, $subroutine,
                    $hasargs, $wantarray, $evaltext, $is_require) = caller($i);

               Here $subroutine may be "(eval)" if the frame is
               not a subroutine call, but an eval.  In such a
               case additional elements $evaltext and $is_require
               are set: $is_require is true if the frame is
               created by a require or use statement, $evaltext
               contains the text of the eval EXPR statement.  In
               particular, for a eval BLOCK statement, $filename
               is "(eval)", but $evaltext is undefined.  (Note
               also that each use statement creates a require
               frame inside an eval EXPR) frame.

               Furthermore, when called from within the DB
               package, caller returns more detailed information:
               it sets the list variable @DB::args to be the
               arguments with which the subroutine was invoked.

       chdir EXPR
               Changes the working directory to EXPR, if
               possible.  If EXPR is omitted, changes to home
               directory.  Returns TRUE upon success, FALSE
               otherwise.  See example under die().

       chmod LIST
               Changes the permissions of a list of files.  The
               first element of the list must be the numerical
               mode, which should probably be an octal number,
               and which definitely should not a string of octal
               digits: 0644 is okay, '0644' is not.  Returns the
               number of files successfully changed.  See also
               the oct entry elsewhere in this document if all
               you have is a string.

                   $cnt = chmod 0755, 'foo', 'bar';
                   chmod 0755, @executables;
                   $mode = '0644'; chmod $mode, 'foo';      # !!! sets mode to --w----r-T
                   $mode = '0644'; chmod oct($mode), 'foo'; # this is better
                   $mode = 0644;   chmod $mode, 'foo';      # this is best


       chomp VARIABLE

       chomp LIST

       chomp   This is a slightly safer version of the chop entry
               elsewhere in this document .  It removes any line
               ending that corresponds to the current value of $/
               (also known as $INPUT_RECORD_SEPARATOR in the
               English module).  It returns the total number of
               characters removed from all its arguments.  It's
               often used to remove the newline from the end of
               an input record when you're worried that the final
               record may be missing its newline.  When in
               paragraph mode ($/ = ""), it removes all trailing
               newlines from the string.  If VARIABLE is omitted,
               it chomps $_.  Example:




                   while (<>) {
                       chomp;  # avoid \n on last field
                       @array = split(/:/);
                       ...
                   }

               You can actually chomp anything that's an lvalue,
               including an assignment:

                   chomp($cwd = `pwd`);
                   chomp($answer = <STDIN>);

               If you chomp a list, each element is chomped, and
               the total number of characters removed is
               returned.

       chop VARIABLE

       chop LIST

       chop    Chops off the last character of a string and
               returns the character chopped.  It's used
               primarily to remove the newline from the end of an
               input record, but is much more efficient than
               s/\n// because it neither scans nor copies the
               string.  If VARIABLE is omitted, chops $_.
               Example:

                   while (<>) {
                       chop;   # avoid \n on last field
                       @array = split(/:/);
                       ...
                   }

               You can actually chop anything that's an lvalue,
               including an assignment:

                   chop($cwd = `pwd`);
                   chop($answer = <STDIN>);

               If you chop a list, each element is chopped.  Only
               the value of the last chop is returned.

               Note that chop returns the last character.  To
               return all but the last character, use
               substr($string, 0, -1).

       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, in that order.  Returns the
               number of files successfully changed.


                   $cnt = chown $uid, $gid, 'foo', 'bar';
                   chown $uid, $gid, @filenames;

               Here's an example that looks up nonnumeric uids in
               the passwd file:

                   print "User: ";
                   chop($user = <STDIN>);
                   print "Files: "
                   chop($pattern = <STDIN>);

                   ($login,$pass,$uid,$gid) = getpwnam($user)
                       or die "$user not in passwd file";

                   @ary = <${pattern}>;        # expand filenames
                   chown $uid, $gid, @ary;

               On most systems, you are not allowed to change the
               ownership of the file unless you're the superuser,
               although you should be able to change the group to
               any of your secondary groups.  On insecure
               systems, these restrictions may be relaxed, but
               this is not a portable assumption.

       chr NUMBER

       chr     Returns the character represented by that NUMBER
               in the character set.  For example, chr(65) is "A"
               in ASCII.  For the reverse, use the ord entry
               elsewhere in this document .

               If NUMBER is omitted, uses $_.

       chroot FILENAME

       chroot  This function works as the system call by the same
               name: it makes the named directory the new root
               directory for all further pathnames that begin
               with a "/" by your process and all of its
               children.  (It doesn't change your current working
               directory, which is unaffected.)  For security
               reasons, this call is restricted to the superuser.
               If FILENAME is omitted, does chroot to $_.

       close FILEHANDLE
               Closes the file or pipe associated with the file
               handle, returning TRUE only if stdio successfully
               flushes buffers and closes the system file
               descriptor.  If the file handle came from a piped
               open close will additionally return FALSE if one
               of the other system calls involved fails or if the
               program exits with non-zero status.  (If the
               problem was that the program exited non-zero $!
               will be set to 0.)  You don't have to close
               FILEHANDLE if you are immediately going to do
               another open() on it, because open() will close it
               for you.  (See open().)  However, an explicit
               close on an input file resets the line counter
               ($.), while the implicit close done by open() does
               not.  Also, closing a pipe will wait for the
               process executing on the pipe to complete, in case
               you want to look at the output of the pipe
               afterwards.  Closing a pipe explicitly also puts
               the status value of the command into $?.  Example:

                   open(OUTPUT, '|sort >foo'); # pipe to sort
                   ...                         # print stuff to output
                   close OUTPUT;               # wait for sort to finish
                   open(INPUT, 'foo');         # get sort's results

               FILEHANDLE may be an expression whose value gives
               the real filehandle name.

       closedir DIRHANDLE
               Closes a directory opened by opendir().

       connect SOCKET,NAME
               Attempts to connect to a remote socket, just as
               the connect system call does.  Returns TRUE if it
               succeeded, FALSE otherwise.  NAME should be a
               packed address of the appropriate type for the
               socket.  See the examples in the section on
               Sockets: Client/Server Communication in the
               perlipc manpage.

       continue BLOCK
               Actually a flow control statement rather than a
               function.  If there is a continue BLOCK attached
               to a BLOCK (typically in a while or foreach), it
               is always executed just before the conditional is
               about to be evaluated again, just like the third
               part of a for loop in C.  Thus it can be used to
               increment a loop variable, even when the loop has
               been continued via the next statement (which is
               similar to the C continue statement).

       cos EXPR
               Returns the cosine of EXPR (expressed in radians).
               If EXPR is omitted takes cosine of $_.

               For the inverse cosine operation, you may use the
               POSIX::acos() function, or use this relation:

                   sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }


       crypt PLAINTEXT,SALT
               Encrypts a string exactly like the crypt(3)
               function in the C library (assuming that you
               actually have a version there that has not been
               extirpated as a potential munition).  This can
               prove useful for checking the password file for
               lousy passwords, amongst other things.  Only the
               guys wearing white hats should do this.

               Note that crypt is intended to be a one-way
               function, much like breaking eggs to make an
               omelette.  There is no (known) corresponding
               decrypt function.  As a result, this function
               isn't all that useful for cryptography.  (For
               that, see your nearby CPAN mirror.)

               Here's an example that makes sure that whoever
               runs this program knows their own password:

                   $pwd = (getpwuid($<))[1];
                   $salt = substr($pwd, 0, 2);

                   system "stty -echo";
                   print "Password: ";
                   chop($word = <STDIN>);
                   print "\n";
                   system "stty echo";

                   if (crypt($word, $salt) ne $pwd) {
                       die "Sorry...\n";
                   } else {
                       print "ok\n";
                   }

               Of course, typing in your own password to whomever
               asks you for it is unwise.

       dbmclose HASH
               [This function has been superseded by the untie()
               function.]

               Breaks the binding between a DBM file and a hash.

       dbmopen HASH,DBNAME,MODE
               [This function has been superseded by the tie()
               function.]

               This binds a dbm(3), ndbm(3), sdbm(3), gdbm(), or
               Berkeley DB file to a hash.  HASH is the name of
               the hash.  (Unlike normal open, the first argument
               is NOT a filehandle, even though it looks like
               one).  DBNAME is the name of the database (without
               the .dir or .pag extension if any).  If the
               database does not exist, it is created with
               protection specified by MODE (as modified by the
               umask()).  If your system supports only the older
               DBM functions, you may perform only one dbmopen()
               in your program.  In older versions of Perl, if
               your system had neither DBM nor ndbm, calling
               dbmopen() produced a fatal error; it now falls
               back to sdbm(3).

               If you don't have write access to the DBM file,
               you can only read hash variables, not set them.
               If you want to test whether you can write, either
               use file tests or try setting a dummy hash entry
               inside an eval(), which will trap the error.

               Note that functions such as keys() and values()
               may return huge array values when used on large
               DBM files.  You may prefer to use the each()
               function to iterate over large DBM files.
               Example:

                   # print out history file offsets
                   dbmopen(%HIST,'/usr/lib/news/history',0666);
                   while (($key,$val) = each %HIST) {
                       print $key, ' = ', unpack('L',$val), "\n";
                   }
                   dbmclose(%HIST);

               See also the AnyDBM_File manpage for a more
               general description of the pros and cons of the
               various dbm approaches, as well as the DB_File
               manpage for a particularly rich implementation.

       defined EXPR

       defined Returns a Boolean value telling whether EXPR has a
               value other than the undefined value undef.  If
               EXPR is not present, $_ will be checked.

               Many operations return undef to indicate failure,
               end of file, system error, uninitialized variable,
               and other exceptional conditions.  This function
               allows you to distinguish undef from other values.
               (A simple Boolean test will not distinguish among
               undef, zero, the empty string, and "0", which are
               all equally false.)  Note that since undef is a
               valid scalar, its presence doesn't necessarily
               indicate an exceptional condition: pop() returns
               undef when its argument is an empty array, or when
               the element to return happens to be undef.

               You may also use defined() to check whether a
               subroutine exists.  On the other hand, use of
               defined() upon aggregates (hashes and arrays) is
               not guaranteed to produce intuitive results, and
               should probably be avoided.

               When used on a hash element, it tells you whether
               the value is defined, not whether the key exists
               in the hash.  Use the exists entry elsewhere in
               this document for the latter purpose.

               Examples:

                   print if defined $switch{'D'};
                   print "$val\n" while defined($val = pop(@ary));
                   die "Can't readlink $sym: $!"
                       unless defined($value = readlink $sym);
                   sub foo { defined &$bar ? &$bar(@_) : die "No bar"; }
                   $debugging = 0 unless defined $debugging;

               Note:  Many folks tend to overuse defined(), and
               then are surprised to discover that the number 0
               and "" (the zero-length string) are, in fact,
               defined values.  For example, if you say

                   "ab" =~ /a(.*)b/;

               the pattern match succeeds, and $1 is defined,
               despite the fact that it matched "nothing".  But
               it didn't really match nothing--rather, it matched
               something that happened to be 0 characters long.
               This is all very above-board and honest.  When a
               function returns an undefined value, it's an
               admission that it couldn't give you an honest
               answer.  So you should use defined() only when
               you're questioning the integrity of what you're
               trying to do.  At other times, a simple comparison
               to 0 or "" is what you want.

               Currently, using defined() on an entire array or
               hash reports whether memory for that aggregate has
               ever been allocated.  So an array you set to the
               empty list appears undefined initially, and one
               that once was full and that you then set to the
               empty list still appears defined.  You should
               instead use a simple test for size:

                   if (@an_array) { print "has array elements\n" }
                   if (%a_hash)   { print "has hash members\n"   }

               Using undef() on these, however, does clear their
               memory and then report them as not defined
               anymore, but you shoudln't do that unless you
               don't plan to use them again, because it saves
               time when you load them up again to have memory
               already ready to be filled.

               This counterintuitive behaviour of defined() on
               aggregates may be changed, fixed, or broken in a
               future release of Perl.
               See also the undef, exists,  and ref entries
               elsewhere in this document .

       delete EXPR
               Deletes the specified key(s) and their associated
               values from a hash.  For each key, returns the
               deleted value associated with that key, or the
               undefined value if there was no such key.
               Deleting from $ENV{} modifies the environment.
               Deleting from a hash tied to a DBM file deletes
               the entry from the DBM file.  (But deleting from a
               tie()d hash doesn't necessarily return anything.)

               The following deletes all the values of a hash:

                   foreach $key (keys %HASH) {
                       delete $HASH{$key};
                   }

               And so does this:

                   delete @HASH{keys %HASH}

               (But both of these are slower than the undef()
               command.)  Note that the EXPR can be arbitrarily
               complicated as long as the final operation is a
               hash element lookup or hash slice:

                   delete $ref->[$x][$y]{$key};
                   delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};


       die LIST
               Outside of an eval(), prints the value of LIST to
               STDERR and exits with the current value of $!
               (errno).  If $! is 0, exits with the value of ($?
               >> 8) (backtick `command` status).  If ($? >> 8)
               is 0, exits with 255.  Inside an eval(), the error
               message is stuffed into $@, and the eval() is
               terminated with the undefined value; this makes
               die() the way to raise an exception.

               Equivalent examples:

                   die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
                   chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"

               If the value of EXPR does not end in a newline,
               the current script line number and input line
               number (if any) are also printed, and a newline is
               supplied.  Hint: sometimes appending ", stopped"
               to your message will cause it to make better sense
               when the string "at foo line 123" is appended.
               Suppose you are running script "canasta".
                   die "/etc/games is no good";
                   die "/etc/games is no good, stopped";

               produce, respectively

                   /etc/games is no good at canasta line 123.
                   /etc/games is no good, stopped at canasta line 123.

               See also exit() and warn().

               You can arrange for a callback to be called just
               before the die() does its deed, by setting the
               $SIG{__DIE__} hook.  The associated handler will
               be called with the error text and can change the
               error message, if it sees fit, by calling die()
               again.  See the perlvar manpage for details on
               setting %SIG entries, and eval() for some
               examples.

       do BLOCK
               Not really a function.  Returns the value of the
               last command in the sequence of commands indicated
               by BLOCK.  When modified by a loop modifier,
               executes the BLOCK once before testing the loop
               condition.  (On other statements the loop
               modifiers test the conditional first.)

       do SUBROUTINE(LIST)
               A deprecated form of subroutine call.  See the
               perlsub manpage.

       do EXPR Uses the value of EXPR as a filename and executes
               the contents of the file as a Perl script.  Its
               primary use is to include subroutines from a Perl
               subroutine library.

                   do 'stat.pl';

               is just like

                   eval `cat stat.pl`;

               except that it's more efficient, more concise,
               keeps track of the current filename for error
               messages, and searches all the -I libraries if the
               file isn't in the current directory (see also the
               @INC array in the section on Predefined Names in
               the perlvar manpage).  It's the same, however, in
               that it does reparse the file every time you call
               it, so you probably don't want to do this inside a
               loop.

               Note that inclusion of library modules is better
               done with the use() and require() operators, which
               also do error checking and raise an exception if
               there's a problem.

       dump LABEL
               This causes an immediate core dump.  Primarily
               this is so that you can use the undump program to
               turn your core dump into an executable binary
               after having initialized all your variables at the
               beginning of the program.  When the new binary is
               executed it will begin by executing a goto LABEL
               (with all the restrictions that goto suffers).
               Think of it as a goto with an intervening core
               dump and reincarnation.  If LABEL is omitted,
               restarts the program from the top.  WARNING: any
               files opened at the time of the dump will NOT be
               open any more when the program is reincarnated,
               with possible resulting confusion on the part of
               Perl.  See also -u option in the perlrun manpage.

               Example:

                   #!/usr/bin/perl
                   require 'getopt.pl';
                   require 'stat.pl';
                   %days = (
                       'Sun' => 1,
                       'Mon' => 2,
                       'Tue' => 3,
                       'Wed' => 4,
                       'Thu' => 5,
                       'Fri' => 6,
                       'Sat' => 7,
                   );

                   dump QUICKSTART if $ARGV[0] eq '-d';

                   QUICKSTART:
                   Getopt('f');


       each HASH
               When called in a list context, returns a 2-element
               array consisting of the key and value for the next
               element of a hash, so that you can iterate over
               it.  When called in a scalar context, returns the
               key for only the next element in the hash.  (Note:
               Keys may be "0" or "", which are logically false;
               you may wish to avoid constructs like while ($k =
               each %foo) {} for this reason.)

               Entries are returned in an apparently random
               order.  When the hash is entirely read, a null
               array is returned in list context (which when
               assigned produces a FALSE (0) value), and undef is
               returned in a scalar context.  The next call to
               each() after that will start iterating again.
               There is a single iterator for each hash, shared
               by all each(), keys(), and values() function calls
               in the program; it can be reset by reading all the
               elements from the hash, or by evaluating keys HASH
               or values HASH.  If you add or delete elements of
               a hash while you're iterating over it, you may get
               entries skipped or duplicated, so don't.

               The following prints out your environment like the
               printenv(1) program, only in a different order:

                   while (($key,$value) = each %ENV) {
                       print "$key=$value\n";
                   }

               See also keys() and values().

       eof FILEHANDLE

       eof ()

       eof     Returns 1 if the next read on FILEHANDLE will
               return end of file, or if FILEHANDLE is not open.
               FILEHANDLE may be an expression whose value gives
               the real filehandle name.  (Note that this
               function actually reads a character and then
               ungetc()s it, so it is not very useful in an
               interactive context.)  Do not read from a terminal
               file (or call eof(FILEHANDLE) on it) after end-of-
               file is reached.  Filetypes such as terminals may
               lose the end-of-file condition if you do.

               An eof without an argument uses the last file read
               as argument.  Empty parentheses () may be used to
               indicate the pseudo file formed of the files
               listed on the command line, i.e., eof() is
               reasonable to use inside a while (<>) loop to
               detect the end of only the last file.  Use
               eof(ARGV) or eof without the parentheses to test
               EACH file in a while (<>) loop.  Examples:

                   # reset line numbering on each input file
                   while (<>) {
                       print "$.\t$_";
                       close(ARGV) if (eof);   # Not eof().
                   }






                   # insert dashes just before last line of last file
                   while (<>) {
                       if (eof()) {
                           print "--------------\n";
                           close(ARGV);        # close or break; is needed if we
                                               # are reading from the terminal
                       }
                       print;
                   }

               Practical hint: you almost never need to use eof
               in Perl, because the input operators return undef
               when they run out of data.

       eval EXPR

       eval BLOCK
               EXPR is parsed and executed as if it were a little
               Perl program.  It is executed in the context of
               the current Perl program, so that any variable
               settings or subroutine and format definitions
               remain afterwards.  The value returned is the
               value of the last expression evaluated, or a
               return statement may be used, just as with
               subroutines.  The last expression is evaluated in
               scalar or array context, depending on the context
               of the eval.

               If there is a syntax error or runtime error, or a
               die() statement is executed, an undefined value is
               returned by eval(), and $@ is set to the error
               message.  If there was no error, $@ is guaranteed
               to be a null string.  If EXPR is omitted,
               evaluates $_.  The final semicolon, if any, may be
               omitted from the expression.  Beware that using
               eval() neither silences perl from printing
               warnings to STDERR, nor does it stuff the text of
               warning messages into $@.  To do either of those,
               you have to use the $SIG{__WARN__} facility.  See
               warn() and the perlvar manpage.

               Note that, because eval() traps otherwise-fatal
               errors, it is useful for determining whether a
               particular feature (such as socket() or symlink())
               is implemented.  It is also Perl's exception
               trapping mechanism, where the die operator is used
               to raise exceptions.

               If the code to be executed doesn't vary, you may
               use the eval-BLOCK form to trap run-time errors
               without incurring the penalty of recompiling each
               time.  The error, if any, is still returned in $@.
               Examples:

                   # make divide-by-zero nonfatal
                   eval { $answer = $a / $b; }; warn $@ if $@;

                   # same thing, but less efficient
                   eval '$answer = $a / $b'; warn $@ if $@;

                   # a compile-time error
                   eval { $answer = };

                   # a run-time error
                   eval '$answer =';   # sets $@

               When using the eval{} form as an exception trap in
               libraries, you may wish not to trigger any __DIE__
               hooks that user code may have installed.  You can
               use the local $SIG{__DIE__} construct for this
               purpose, as shown in this example:

                   # a very private exception trap for divide-by-zero
                   eval { local $SIG{'__DIE__'}; $answer = $a / $b; }; warn $@ if $@;

               This is especially significant, given that __DIE__
               hooks can call die() again, which has the effect
               of changing their error messages:

                   # __DIE__ hooks may modify error messages
                   {
                      local $SIG{'__DIE__'} = sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
                      eval { die "foo foofs here" };
                      print $@ if $@;                # prints "bar barfs here"
                   }

               With an eval(), you should be especially careful
               to remember what's being looked at when:

                   eval $x;            # CASE 1
                   eval "$x";          # CASE 2

                   eval '$x';          # CASE 3
                   eval { $x };        # CASE 4

                   eval "\$$x++"       # CASE 5
                   $$x++;              # CASE 6

               Cases 1 and 2 above behave identically: they run
               the code contained in the variable $x.  (Although
               case 2 has misleading double quotes making the
               reader wonder what else might be happening
               (nothing is).)  Cases 3 and 4 likewise behave in
               the same way: they run the code '$x', which does
               nothing but return the value of $x.  (Case 4 is
               preferred for purely visual reasons, but it also
               has the advantage of compiling at compile-time
               instead of at run-time.)  Case 5 is a place where
               normally you WOULD like to use double quotes,
               except that in this particular situation, you can
               just use symbolic references instead, as in case
               6.

       exec LIST
               The exec() function executes a system command AND
               NEVER RETURNS, unless the command does not exist
               and is executed directly instead of via /bin/sh -c
               (see below).  Use system() instead of exec() if
               you want it to return.

               If there is more than one argument in LIST, or if
               LIST is an array with more than one value, calls
               execvp(3) with the arguments in LIST.  If there is
               only one scalar argument, the argument is checked
               for shell metacharacters.  If there are any, the
               entire argument is passed to /bin/sh -c for
               parsing.  If there are none, the argument is split
               into words and passed directly to execvp(), which
               is more efficient.  Note: exec() and system() do
               not flush your output buffer, so you may need to
               set $| to avoid lost output.  Examples:

                   exec '/bin/echo', 'Your arguments are: ', @ARGV;
                   exec "sort $outfile | uniq";

               If you don't really want to execute the first
               argument, but want to lie to the program you are
               executing about its own name, you can specify the
               program you actually want to run as an "indirect
               object" (without a comma) in front of the LIST.
               (This always forces interpretation of the LIST as
               a multivalued list, even if there is only a single
               scalar in the list.)  Example:

                   $shell = '/bin/csh';
                   exec $shell '-sh';          # pretend it's a login shell

               or, more directly,

                   exec {'/bin/csh'} '-sh';    # pretend it's a login shell


       exists EXPR
               Returns TRUE if the specified hash key exists in
               its hash array, even if the corresponding value is
               undefined.

                   print "Exists\n" if exists $array{$key};
                   print "Defined\n" if defined $array{$key};
                   print "True\n" if $array{$key};

               A hash element can be TRUE only if it's defined,
               and defined if it exists, but the reverse doesn't
               necessarily hold true.

               Note that the EXPR can be arbitrarily complicated
               as long as the final operation is a hash key
               lookup:

                   if (exists $ref->[$x][$y]{$key}) { ... }


       exit EXPR
               Evaluates EXPR and exits immediately with that
               value.  (Actually, it calls any defined END
               routines first, but the END routines may not abort
               the exit.  Likewise any object destructors that
               need to be called are called before exit.)
               Example:

                   $ans = <STDIN>;
                   exit 0 if $ans =~ /^[Xx]/;

               See also die().  If EXPR is omitted, exits with 0
               status.  The only universally portable values for
               EXPR are 0 for success and 1 for error; all other
               values are subject to unpredictable interpretation
               depending on the environment in which the Perl
               program is running.

               You shouldn't use exit() to abort a subroutine if
               there's any chance that someone might want to trap
               whatever error happened.  Use die() instead, which
               can be trapped by an eval().

       exp EXPR

       exp     Returns e (the natural logarithm base) to the
               power of EXPR.  If EXPR is omitted, gives exp($_).

       fcntl FILEHANDLE,FUNCTION,SCALAR
               Implements the fcntl(2) function.  You'll probably
               have to say

                   use Fcntl;

               first to get the correct function definitions.
               Argument processing and value return works just
               like ioctl() below.  Note that fcntl() will
               produce a fatal error if used on a machine that
               doesn't implement fcntl(2).  For example:

                   use Fcntl;
                   fcntl($filehandle, F_GETLK, $packed_return_buffer);


       fileno FILEHANDLE
               Returns the file descriptor for a filehandle.
               This is useful for constructing bitmaps for
               select().  If FILEHANDLE is an expression, the
               value is taken as the name of the filehandle.

       flock FILEHANDLE,OPERATION
               Calls flock(2), or an emulation of it, on
               FILEHANDLE.  Returns TRUE for success, FALSE on
               failure.  Produces a fatal error if used on a
               machine that doesn't implement flock(2), fcntl(2)
               locking, or lockf(3).  flock() is Perl's portable
               file locking interface, although it locks only
               entire files, not records.

               OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN,
               possibly combined with LOCK_NB.  These constants
               are traditionally valued 1, 2, 8 and 4, but you
               can use the symbolic names if import them from the
               Fcntl module, either individually, or as a group
               using the ':flock' tag.  LOCK_SH requests a shared
               lock, LOCK_EX requests an exclusive lock, and
               LOCK_UN releases a previously requested lock.  If
               LOCK_NB is added to LOCK_SH or LOCK_EX then
               flock() will return immediately rather than
               blocking waiting for the lock (check the return
               status to see if you got it).

               To avoid the possibility of mis-coordination, Perl
               flushes FILEHANDLE before (un)locking it.

               Note that the emulation built with lockf(3)
               doesn't provide shared locks, and it requires that
               FILEHANDLE be open with write intent.  These are
               the semantics that lockf(3) implements.  Most
               (all?) systems implement lockf(3) in terms of
               fcntl(2) locking, though, so the differing
               semantics shouldn't bite too many people.

               Note also that some versions of flock() cannot
               lock things over the network; you would need to
               use the more system-specific fcntl() for that.  If
               you like you can force Perl to ignore your
               system's flock(2) function, and so provide its own
               fcntl(2)-based emulation, by passing the switch
               -Ud_flock to the Configure program when you
               configure perl.

               Here's a mailbox appender for BSD systems.

                   use Fcntl ':flock'; # import LOCK_* constants



                   sub lock {
                       flock(MBOX,LOCK_EX);
                       # and, in case someone appended
                       # while we were waiting...
                       seek(MBOX, 0, 2);
                   }

                   sub unlock {
                       flock(MBOX,LOCK_UN);
                   }

                   open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
                           or die "Can't open mailbox: $!";

                   lock();
                   print MBOX $msg,"\n\n";
                   unlock();

               See also the DB_File manpage for other flock()
               examples.

       fork    Does a fork(2) system call.  Returns the child pid
               to the parent process and 0 to the child process,
               or undef if the fork is unsuccessful.  Note:
               unflushed buffers remain unflushed in both
               processes, which means you may need to set $|
               ($AUTOFLUSH in English) or call the autoflush()
               method of IO::Handle to avoid duplicate output.

               If you fork() without ever waiting on your
               children, you will accumulate zombies:

                   $SIG{CHLD} = sub { wait };

               There's also the double-fork trick (error checking
               on fork() returns omitted);

                   unless ($pid = fork) {
                       unless (fork) {
                           exec "what you really wanna do";
                           die "no exec";
                           # ... or ...
                           ## (some_perl_code_here)
                           exit 0;
                       }
                       exit 0;
                   }
                   waitpid($pid,0);

               See also the perlipc manpage for more examples of
               forking and reaping moribund children.

               Note that if your forked child inherits system
               file descriptors like STDIN and STDOUT that are
               actually connected by a pipe or socket, even if
               you exit, the remote server (such as, say, httpd
               or rsh) won't think you're done.  You should
               reopen those to /dev/null if it's any issue.

       format  Declare a picture format with use by the write()
               function.  For example:

                   format Something =
                       Test: @<<<<<<<< @||||| @>>>>>
                             $str,     $%,    '$' . int($num)
                   .

                   $str = "widget";
                   $num = $cost/$quantity;
                   $~ = 'Something';
                   write;

               See the perlform manpage for many details and
               examples.

       formline PICTURE,LIST
               This is an internal function used by formats,
               though you may call it too.  It formats (see the
               perlform manpage) a list of values according to
               the contents of PICTURE, placing the output into
               the format output accumulator, $^A (or
               $ACCUMULATOR in English).  Eventually, when a
               write() is done, the contents of $^A are written
               to some filehandle, but you could also read $^A
               yourself and then set $^A back to "".  Note that a
               format typically does one formline() per line of
               form, but the formline() function itself doesn't
               care how many newlines are embedded in the
               PICTURE.  This means that the ~ and ~~ tokens will
               treat the entire PICTURE as a single line.  You
               may therefore need to use multiple formlines to
               implement a single record format, just like the
               format compiler.

               Be careful if you put double quotes around the
               picture, because an "@" character may be taken to
               mean the beginning of an array name.  formline()
               always returns TRUE.  See the perlform manpage for
               other examples.

       getc FILEHANDLE

       getc    Returns the next character from the input file
               attached to FILEHANDLE, or a null string at end of
               file.  If FILEHANDLE is omitted, reads from STDIN.
               This is not particularly efficient.  It cannot be
               used to get unbuffered single-characters, however.
               For that, try something more like:
                   if ($BSD_STYLE) {
                       system "stty cbreak </dev/tty >/dev/tty 2>&1";
                   }
                   else {
                       system "stty", '-icanon', 'eol', "\001";
                   }

                   $key = getc(STDIN);

                   if ($BSD_STYLE) {
                       system "stty -cbreak </dev/tty >/dev/tty 2>&1";
                   }
                   else {
                       system "stty", 'icanon', 'eol', '^@'; # ASCII null
                   }
                   print "\n";

               Determination of whether $BSD_STYLE should be set
               is left as an exercise to the reader.

               The POSIX::getattr() function can do this more
               portably on systems alleging POSIX compliance.
               See also the Term::ReadKey module from your
               nearest CPAN site; details on CPAN can be found on
               the CPAN entry in the perlmod manpage.

       getlogin
               Returns the current login from /etc/utmp, if any.
               If null, use getpwuid().

                   $login = getlogin || getpwuid($<) || "Kilroy";

               Do not consider getlogin() for authentication: it
               is not as secure as getpwuid().

       getpeername SOCKET
               Returns the packed sockaddr address of other end
               of the SOCKET connection.

                   use Socket;
                   $hersockaddr    = getpeername(SOCK);
                   ($port, $iaddr) = unpack_sockaddr_in($hersockaddr);
                   $herhostname    = gethostbyaddr($iaddr, AF_INET);
                   $herstraddr     = inet_ntoa($iaddr);


       getpgrp PID
               Returns the current process group for the
               specified PID.  Use a PID of 0 to get the current
               process group for the current process.  Will raise
               an exception if used on a machine that doesn't
               implement getpgrp(2).  If PID is omitted, returns
               process group of current process.  Note that the
               POSIX version of getpgrp() does not accept a PID
               argument, so only PID==0 is truly portable.

       getppid Returns the process id of the parent process.

       getpriority WHICH,WHO
               Returns the current priority for a process, a
               process group, or a user.  (See the getpriority(2)
               manpage.)  Will raise a fatal exception if used on
               a machine that doesn't implement getpriority(2).

       getpwnam NAME

       getgrnam NAME

       gethostbyname NAME

       getnetbyname NAME

       getprotobyname NAME

       getpwuid UID

       getgrgid GID

       getservbyname NAME,PROTO

       gethostbyaddr ADDR,ADDRTYPE

       getnetbyaddr ADDR,ADDRTYPE

       getprotobynumber NUMBER

       getservbyport PORT,PROTO

       getpwent

       getgrent

       gethostent

       getnetent

       getprotoent

       getservent

       setpwent

       setgrent

       sethostent STAYOPEN

       setnetent STAYOPEN

       setprotoent STAYOPEN

       setservent STAYOPEN

       endpwent

       endgrent

       endhostent

       endnetent

       endprotoent

       endservent
               These routines perform the same functions as their
               counterparts in the system library.  Within a list
               context, the return values from the various get
               routines are as follows:

                   ($name,$passwd,$uid,$gid,
                      $quota,$comment,$gcos,$dir,$shell) = getpw*
                   ($name,$passwd,$gid,$members) = getgr*
                   ($name,$aliases,$addrtype,$length,@addrs) = gethost*
                   ($name,$aliases,$addrtype,$net) = getnet*
                   ($name,$aliases,$proto) = getproto*
                   ($name,$aliases,$port,$proto) = getserv*

               (If the entry doesn't exist you get a null list.)

               Within a scalar context, you get the name, unless
               the function was a lookup by name, in which case
               you get the other thing, whatever it is.  (If the
               entry doesn't exist you get the undefined value.)
               For example:

                   $uid = getpwnam
                   $name = getpwuid
                   $name = getpwent
                   $gid = getgrnam
                   $name = getgrgid
                   $name = getgrent
                   etc.

               The $members value returned by getgr*() is a space
               separated list of the login names of the members
               of the group.

               For the gethost*() functions, if the h_errno
               variable is supported in C, it will be returned to
               you via $? if the function call fails.  The @addrs
               value returned by a successful call is a list of
               the raw addresses returned by the corresponding
               system library call.  In the Internet domain, each
               address is four bytes long and you can unpack it
               by saying something like:

                   ($a,$b,$c,$d) = unpack('C4',$addr[0]);


       getsockname SOCKET
               Returns the packed sockaddr address of this end of
               the SOCKET connection.

                   use Socket;
                   $mysockaddr = getsockname(SOCK);
                   ($port, $myaddr) = unpack_sockaddr_in($mysockaddr);


       getsockopt SOCKET,LEVEL,OPTNAME
               Returns the socket option requested, or undefined
               if there is an error.

       glob EXPR

       glob    Returns the value of EXPR with filename expansions
               such as a shell would do.  This is the internal
               function implementing the <*.c> operator, but you
               can use it directly.  If EXPR is omitted, $_ is
               used.  The <*.c> operator is discussed in more
               detail in the section on I/O Operators in the
               perlop manpage.

       gmtime EXPR
               Converts a time as returned by the time function
               to a 9-element array with the time localized for
               the standard Greenwich time zone.  Typically used
               as follows:

                   #  0    1    2     3     4    5     6     7     8
                   ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
                                                           gmtime(time);

               All array elements are numeric, and come straight
               out of a struct tm.  In particular this means that
               $mon has the range 0..11 and $wday has the range
               0..6 with sunday as day 0.  Also, $year is the
               number of years since 1900, not simply the last
               two digits of the year.

               If EXPR is omitted, does gmtime(time()).

               In a scalar context, returns the ctime(3) value:

                   $now_string = gmtime;  # e.g., "Thu Oct 13 04:54:34 1994"

               Also see the timegm() function provided by the
               Time::Local module, and the strftime(3) function
               available via the POSIX module.

       goto LABEL

       goto EXPR

       goto &NAME
               The goto-LABEL form finds the statement labeled
               with LABEL and resumes execution there.  It may
               not be used to go into any construct that requires
               initialization, such as a subroutine or a foreach
               loop.  It also can't be used to go into a
               construct that is optimized away, or to get out of
               a block or subroutine given to sort().  It can be
               used to go almost anywhere else within the dynamic
               scope, including out of subroutines, but it's
               usually better to use some other construct such as
               last or die.  The author of Perl has never felt
               the need to use this form of goto (in Perl, that
               is--C is another matter).

               The goto-EXPR form expects a label name, whose
               scope will be resolved dynamically.  This allows
               for computed gotos per FORTRAN, but isn't
               necessarily recommended if you're optimizing for
               maintainability:

                   goto ("FOO", "BAR", "GLARCH")[$i];

               The goto-&NAME form is highly magical, and
               substitutes a call to the named subroutine for the
               currently running subroutine.  This is used by
               AUTOLOAD subroutines that wish to load another
               subroutine and then pretend that the other
               subroutine had been called in the first place
               (except that any modifications to @_ in the
               current subroutine are propagated to the other
               subroutine.)  After the goto, not even caller()
               will be able to tell that this routine was called
               first.

       grep BLOCK LIST

       grep EXPR,LIST
               This is similar in spirit to, but not the same as,
               grep(1) and its relatives.  In particular, it is
               not limited to using regular expressions.

               Evaluates the BLOCK or EXPR for each element of
               LIST (locally setting $_ to each element) and
               returns the list value consisting of those
               elements for which the expression evaluated to
               TRUE.  In a scalar context, returns the number of
               times the expression was TRUE.
                   @foo = grep(!/^#/, @bar);    # weed out comments

               or equivalently,

                   @foo = grep {!/^#/} @bar;    # weed out comments

               Note that, because $_ is a reference into the list
               value, it can be used to modify the elements of
               the array.  While this is useful and supported, it
               can cause bizarre results if the LIST is not a
               named array.  Similarly, grep returns aliases into
               the original list, much like the way that the
               section on Foreach Loops's index variable aliases
               the list elements.  That is, modifying an element
               of a list returned by grep actually modifies the
               element in the original list.

       hex EXPR

       hex     Interprets EXPR as a hex string and returns the
               corresponding value.  (To convert strings that
               might start with either 0 or 0x see the oct entry
               elsewhere in this document .)  If EXPR is omitted,
               uses $_.

                   print hex '0xAf'; # prints '175'
                   print hex 'aF';   # same


       import  There is no builtin import() function.  It is
               merely an ordinary method (subroutine) defined (or
               inherited) by modules that wish to export names to
               another module.  The use() function calls the
               import() method for the package used.  See also
               the use() entry elsewhere in this document the
               perlmod manpage, and the Exporter manpage.

       index STR,SUBSTR,POSITION

       index STR,SUBSTR
               Returns the position of the first occurrence of
               SUBSTR in STR at or after POSITION.  If POSITION
               is omitted, starts searching from the beginning of
               the string.  The return value is based at 0 (or
               whatever you've set the $[ variable to--but don't
               do that).  If the substring is not found, returns
               one less than the base, ordinarily -1.

       int EXPR

       int     Returns the integer portion of EXPR.  If EXPR is
               omitted, uses $_.


       ioctl FILEHANDLE,FUNCTION,SCALAR
               Implements the ioctl(2) function.  You'll probably
               have to say

                   require "ioctl.ph"; # probably in /usr/local/lib/perl/ioctl.ph

               first to get the correct function definitions.  If
               ioctl.ph doesn't exist or doesn't have the correct
               definitions you'll have to roll your own, based on
               your C header files such as <sys/ioctl.h>.  (There
               is a Perl script called h2ph that comes with the
               Perl kit which may help you in this, but it's
               nontrivial.)  SCALAR will be read and/or written
               depending on the FUNCTION--a pointer to the string
               value of SCALAR will be passed as the third
               argument of the actual ioctl call.  (If SCALAR has
               no string value but does have a numeric value,
               that value will be passed rather than a pointer to
               the string value.  To guarantee this to be TRUE,
               add a 0 to the scalar before using it.)  The
               pack() and unpack() functions are useful for
               manipulating the values of structures used by
               ioctl().  The following example sets the erase
               character to DEL.

                   require 'ioctl.ph';
                   $getp = &TIOCGETP;
                   die "NO TIOCGETP" if $@ || !$getp;
                   $sgttyb_t = "ccccs";                # 4 chars and a short
                   if (ioctl(STDIN,$getp,$sgttyb)) {
                       @ary = unpack($sgttyb_t,$sgttyb);
                       $ary[2] = 127;
                       $sgttyb = pack($sgttyb_t,@ary);
                       ioctl(STDIN,&TIOCSETP,$sgttyb)
                           || die "Can't ioctl: $!";
                   }

               The return value of ioctl (and fcntl) is as
               follows:

                       if OS returns:          then Perl returns:
                           -1                    undefined value
                            0                  string "0 but true"
                       anything else               that number

               Thus Perl returns TRUE on success and FALSE on
               failure, yet you can still easily determine the
               actual value returned by the operating system:

                   ($retval = ioctl(...)) || ($retval = -1);
                   printf "System returned %d\n", $retval;



       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.  Example:

                   $_ = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);

               See the split entry in the perlfunc manpage.

       keys HASH
               Returns a normal array consisting of all the keys
               of the named hash.  (In a scalar context, returns
               the number of keys.)  The keys are returned in an
               apparently random order, but it is the same order
               as either the values() or each() function produces
               (given that the hash has not been modified).  As a
               side effect, it resets HASH's iterator.

               Here is yet another way to print your environment:

                   @keys = keys %ENV;
                   @values = values %ENV;
                   while ($#keys >= 0) {
                       print pop(@keys), '=', pop(@values), "\n";
                   }

               or how about sorted by key:

                   foreach $key (sort(keys %ENV)) {
                       print $key, '=', $ENV{$key}, "\n";
                   }

               To sort an array by value, you'll need to use a
               sort function.  Here's a descending numeric sort
               of a hash by its values:

                   foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash)) {
                       printf "%4d %s\n", $hash{$key}, $key;
                   }

               As an lvalue keys allows you to increase the
               number of hash buckets allocated for the given
               hash.  This can gain you a measure of efficiency
               if you know the hash is going to get big.  (This
               is similar to pre-extending an array by assigning
               a larger number to $#array.)  If you say

                   keys %hash = 200;

               then %hash will have at least 200 buckets
               allocated for it.  These buckets will be retained
               even if you do %hash = (), use undef %hash if you
               want to free the storage while %hash is still in
               scope.  You can't shrink the number of buckets
               allocated for the hash using keys in this way (but
               you needn't worry about doing this by accident, as
               trying has no effect).

       kill LIST
               Sends a signal to a list of processes.  The first
               element of the list must be the signal to send.
               Returns the number of processes successfully
               signaled.

                   $cnt = kill 1, $child1, $child2;
                   kill 9, @goners;

               Unlike in the shell, in Perl if the SIGNAL is
               negative, it kills process groups instead of
               processes.  (On System V, a negative PROCESS
               number will also kill process groups, but that's
               not portable.)  That means you usually want to use
               positive not negative signals.  You may also use a
               signal name in quotes.  See the section on Signals
               in the perlipc manpage for details.

       last LABEL

       last    The last command is like the break statement in C
               (as used in loops); it immediately exits the loop
               in question.  If the LABEL is omitted, the command
               refers to the innermost enclosing loop.  The
               continue block, if any, is not executed:

                   LINE: while (<STDIN>) {
                       last LINE if /^$/;      # exit when done with header
                       ...
                   }


       lc EXPR

       lc      Returns an lowercased version of EXPR.  This is
               the internal function implementing the \L escape
               in double-quoted strings.  Respects current
               LC_CTYPE locale if use locale in force.  See the
               perllocale manpage.

               If EXPR is omitted, uses $_.

       lcfirst EXPR

       lcfirst Returns the value of EXPR with the first character
               lowercased.  This is the internal function
               implementing the \l escape in double-quoted
               strings.  Respects current LC_CTYPE locale if use
               locale in force.  See the perllocale manpage.

               If EXPR is omitted, uses $_.

       length EXPR

       length  Returns the length in characters of the value of
               EXPR.  If EXPR is omitted, returns length of $_.

       link OLDFILE,NEWFILE
               Creates a new filename linked to the old filename.
               Returns 1 for success, 0 otherwise.

       listen SOCKET,QUEUESIZE
               Does the same thing that the listen system call
               does.  Returns TRUE if it succeeded, FALSE
               otherwise.  See example in the section on Sockets:
               Client/Server Communication in the perlipc
               manpage.

       local EXPR
               A local modifies the listed variables to be local
               to the enclosing block, subroutine, eval{}, or do.
               If more than one value is listed, the list must be
               placed in parentheses.  See the section on
               Temporary Values via local() in the perlsub
               manpage for details, including issues with tied
               arrays and hashes.

               But you really probably want to be using my()
               instead, because local() isn't what most people
               think of as "local").  See the section on Private
               Variables via my() in the perlsub manpage for
               details.

       localtime EXPR
               Converts a time as returned by the time function
               to a 9-element array with the time analyzed for
               the local time zone.  Typically used as follows:

                   #  0    1    2     3     4    5     6     7     8
                   ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
                                                               localtime(time);

               All array elements are numeric, and come straight
               out of a struct tm.  In particular this means that
               $mon has the range 0..11 and $wday has the range
               0..6 with sunday as day 0.  Also, $year is the
               number of years since 1900, that is, $year is 123
               in year 2023.

               If EXPR is omitted, uses the current time
               (localtime(time)).

               In a scalar context, returns the ctime(3) value:

                   $now_string = localtime;  # e.g., "Thu Oct 13 04:54:34 1994"

               Also see the Time::Local module, and the
               strftime(3) and mktime(3) function available via
               the POSIX module.

       log EXPR

       log     Returns logarithm (base e) of EXPR.  If EXPR is
               omitted, returns log of $_.

       lstat FILEHANDLE

       lstat EXPR

       lstat   Does the same thing as the stat() function, but
               stats a symbolic link instead of the file the
               symbolic link points to.  If symbolic links are
               unimplemented on your system, a normal stat() is
               done.

               If EXPR is omitted, stats $_.

       m//     The match operator.  See the perlop manpage.

       map BLOCK LIST

       map EXPR,LIST
               Evaluates the BLOCK or EXPR for each element of
               LIST (locally setting $_ to each element) and
               returns the list value composed of the results of
               each such evaluation.  Evaluates BLOCK or EXPR in
               a list context, so each element of LIST may
               produce zero, one, or more elements in the
               returned value.

                   @chars = map(chr, @nums);

               translates a list of numbers to the corresponding
               characters.  And

                   %hash = map { getkey($_) => $_ } @array;

               is just a funny way to write

                   %hash = ();
                   foreach $_ (@array) {
                       $hash{getkey($_)} = $_;
                   }


       mkdir FILENAME,MODE
               Creates the directory specified by FILENAME, with
               permissions specified by MODE (as modified by
               umask).  If it succeeds it returns 1, otherwise it
               returns 0 and sets $! (errno).

       msgctl ID,CMD,ARG
               Calls the System V IPC function msgctl(2).  If CMD
               is &IPC_STAT, then ARG must be a variable which
               will hold the returned msqid_ds structure.
               Returns like ioctl: the undefined value for error,
               "0 but true" for zero, or the actual return value
               otherwise.

       msgget KEY,FLAGS
               Calls the System V IPC function msgget(2).
               Returns the message queue id, or the undefined
               value if there is an error.

       msgsnd ID,MSG,FLAGS
               Calls the System V IPC function msgsnd to send the
               message MSG to the message queue ID.  MSG must
               begin with the long integer message type, which
               may be created with pack("l", $type).  Returns
               TRUE if successful, or FALSE if there is an error.

       msgrcv ID,VAR,SIZE,TYPE,FLAGS
               Calls the System V IPC function msgrcv to receive
               a message from message queue ID into variable VAR
               with a maximum message size of SIZE.  Note that if
               a message is received, the message type will be
               the first thing in VAR, and the maximum length of
               VAR is SIZE plus the size of the message type.
               Returns TRUE if successful, or FALSE if there is
               an error.

       my EXPR A "my" declares the listed variables to be local
               (lexically) to the enclosing block, subroutine,
               eval, or do/require/use'd file.  If more than one
               value is listed, the list must be placed in
               parentheses.  See the section on Private Variables
               via my() in the perlsub manpage for details.

       next LABEL

       next    The next command is like the continue statement in
               C; it starts the next iteration of the loop:

                   LINE: while (<STDIN>) {
                       next LINE if /^#/;      # discard comments
                       ...
                   }

               Note that if there were a continue block on the
               above, it would get executed even on discarded
               lines.  If the LABEL is omitted, the command
               refers to the innermost enclosing loop.

       no Module LIST
               See the "use" function, which "no" is the opposite
               of.

       oct EXPR

       oct     Interprets EXPR as an octal string and returns the
               corresponding value.  (If EXPR happens to start
               off with 0x, interprets it as a hex string
               instead.)  The following will handle decimal,
               octal, and hex in the standard Perl or C notation:

                   $val = oct($val) if $val =~ /^0/;

               If EXPR is omitted, uses $_.  This function is
               commonly used when a string such as "644" needs to
               be converted into a file mode, for example.
               (Although perl will automatically convert strings
               into numbers as needed, this automatic conversion
               assumes base 10.)

       open FILEHANDLE,EXPR

       open FILEHANDLE
               Opens the file whose filename is given by EXPR,
               and associates it with FILEHANDLE.  If FILEHANDLE
               is an expression, its value is used as the name of
               the real filehandle wanted.  If EXPR is omitted,
               the scalar variable of the same name as the
               FILEHANDLE contains the filename.  (Note that
               lexical variables--those declared with my--will
               not work for this purpose; so if you're using my,
               specify EXPR in your call to open.)

               If the filename begins with '<' or nothing, the
               file is opened for input.  If the filename begins
               with '>', the file is truncated and opened for
               output.  If the filename begins with '>>', the
               file is opened for appending.  You can put a '+'
               in front of the '>' or '<' to indicate that you
               want both read and write access to the file; thus
               '+<' is almost always preferred for read/write
               updates--the '+>' mode would clobber the file
               first.  The prefix and the filename may be
               separated with spaces.  These various prefixes
               correspond to the fopen(3) modes of 'r', 'r+',
               'w', 'w+', 'a', and 'a+'.

               If the filename begins with "|", the filename is
               interpreted as a command to which output is to be
               piped, and if the filename ends with a "|", the
               filename is interpreted See the section on Using
               open() for IPC in the perlipc manpage for more
               examples of this.  as command which pipes input to
               us.  (You may not have a raw open() to a command
               that pipes both in and out, but see the IPC::Open2
               manpage, the IPC::Open3 manpage, and the section
               on Bidirectional Communication in the perlipc
               manpage for alternatives.)

               Opening '-' opens STDIN and opening '>-' opens
               STDOUT.  Open returns nonzero upon success, the
               undefined value otherwise.  If the open involved a
               pipe, the return value happens to be the pid of
               the subprocess.

               If you're unfortunate enough to be running Perl on
               a system that distinguishes between text files and
               binary files (modern operating systems don't
               care), then you should check out the binmode entry
               elsewhere in this document for tips for dealing
               with this.  The key distinction between systems
               that need binmode and those that don't is their
               text file formats.  Systems like Unix and Plan9
               that delimit lines with a single character, and
               that encode that character in C as '\n', do not
               need binmode.  The rest need it.

               Examples:

                   $ARTICLE = 100;
                   open ARTICLE or die "Can't find article $ARTICLE: $!\n";
                   while (<ARTICLE>) {...

                   open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)

                   open(DBASE, '+<dbase.mine');            # open for update

                   open(ARTICLE, "caesar <$article |");    # decrypt article

                   open(EXTRACT, "|sort >/tmp/Tmp$$");     # $$ is our process id

                   # process argument list of files along with any includes

                   foreach $file (@ARGV) {
                       process($file, 'fh00');
                   }

                   sub process {
                       local($filename, $input) = @_;
                       $input++;               # this is a string increment
                       unless (open($input, $filename)) {
                           print STDERR "Can't open $filename: $!\n";
                           return;
                       }



                       while (<$input>) {              # note use of indirection
                           if (/^#include "(.*)"/) {
                               process($1, $input);
                               next;
                           }
                           ...         # whatever
                       }
                   }

               You may also, in the Bourne shell tradition,
               specify an EXPR beginning with ">&", in which case
               the rest of the string is interpreted as the name
               of a filehandle (or file descriptor, if numeric)
               which is to be duped and opened.  You may use &
               after >, >>, <, +>, +>>, and +<.  The mode you
               specify should match the mode of the original
               filehandle.  (Duping a filehandle does not take
               into account any existing contents of stdio
               buffers.)  Here is a script that saves, redirects,
               and restores STDOUT and STDERR:

                   #!/usr/bin/perl
                   open(SAVEOUT, ">&STDOUT");
                   open(SAVEERR, ">&STDERR");

                   open(STDOUT, ">foo.out") || die "Can't redirect stdout";
                   open(STDERR, ">&STDOUT") || die "Can't dup stdout";

                   select(STDERR); $| = 1;     # make unbuffered
                   select(STDOUT); $| = 1;     # make unbuffered

                   print STDOUT "stdout 1\n";  # this works for
                   print STDERR "stderr 1\n";  # subprocesses too

                   close(STDOUT);
                   close(STDERR);

                   open(STDOUT, ">&SAVEOUT");
                   open(STDERR, ">&SAVEERR");

                   print STDOUT "stdout 2\n";
                   print STDERR "stderr 2\n";

               If you specify "<&=N", where N is a number, then
               Perl will do an equivalent of C's fdopen() of that
               file descriptor; this is more parsimonious of file
               descriptors.  For example:

                   open(FILEHANDLE, "<&=$fd")

               If you open a pipe on the command "-", i.e.,
               either "|-" or "-|", then there is an implicit
               fork done, and the return value of open is the pid
               of the child within the parent process, and 0
               within the child process.  (Use defined($pid) to
               determine whether the open was successful.)  The
               filehandle behaves normally for the parent, but
               i/o to that filehandle is piped from/to the
               STDOUT/STDIN of the child process.  In the child
               process the filehandle isn't opened--i/o happens
               from/to the new STDOUT or STDIN.  Typically this
               is used like the normal piped open when you want
               to exercise more control over just how the pipe
               command gets executed, such as when you are
               running setuid, and don't want to have to scan
               shell commands for metacharacters.  The following
               pairs are more or less equivalent:

                   open(FOO, "|tr '[a-z]' '[A-Z]'");
                   open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]';

                   open(FOO, "cat -n '$file'|");
                   open(FOO, "-|") || exec 'cat', '-n', $file;

               See the section on Safe Pipe Opens in the perlipc
               manpage for more examples of this.

               NOTE: On any operation which may do a fork,
               unflushed buffers remain unflushed in both
               processes, which means you may need to set $| to
               avoid duplicate output.

               Closing any piped filehandle causes the parent
               process to wait for the child to finish, and
               returns the status value in $?.

               Using the constructor from the IO::Handle package
               (or one of its subclasses, such as IO::File or
               IO::Socket), you can generate anonymous
               filehandles which have the scope of whatever
               variables hold references to them, and
               automatically close whenever and however you leave
               that scope:

                   use IO::File;
                   ...
                   sub read_myfile_munged {
                       my $ALL = shift;
                       my $handle = new IO::File;
                       open($handle, "myfile") or die "myfile: $!";
                       $first = <$handle>
                           or return ();     # Automatically closed here.
                       mung $first or die "mung failed";       # Or here.
                       return $first, <$handle> if $ALL;       # Or here.
                       $first;                                 # Or here.
                   }

               The filename that is passed to open will have
               leading and trailing whitespace deleted.  To open
               a file with arbitrary weird characters in it, it's
               necessary to protect any leading and trailing
               whitespace thusly:

                   $file =~ s#^(\s)#./$1#;
                   open(FOO, "< $file\0");

               If you want a "real" C open() (see the open(2)
               manpage on your system), then you should use the
               sysopen() function.  This is another way to
               protect your filenames from interpretation.  For
               example:

                   use IO::Handle;
                   sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL, 0700)
                       or die "sysopen $path: $!";
                   HANDLE->autoflush(1);
                   HANDLE->print("stuff $$\n");
                   seek(HANDLE, 0, 0);
                   print "File contains: ", <HANDLE>;

               See the seek() entry elsewhere in this document
               for some details about mixing reading and writing.

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

       ord EXPR

       ord     Returns the numeric ascii value of the first
               character of EXPR.  If EXPR is omitted, uses $_.
               For the reverse, see the chr entry elsewhere in
               this document .

       pack TEMPLATE,LIST
               Takes an array or list of values and packs it into
               a binary structure, returning the string
               containing the structure.  The TEMPLATE is a
               sequence of characters that give the order and
               type of values, as follows:

                   A   An ascii string, will be space padded.
                   a   An ascii string, will be null padded.
                   b   A bit string (ascending bit order, like vec()).
                   B   A bit string (descending bit order).
                   h   A hex string (low nybble first).
                   H   A hex string (high nybble first).


                   c   A signed char value.
                   C   An unsigned char value.

                   s   A signed short value.
                   S   An unsigned short value.
                         (This 'short' is _exactly_ 16 bits, which may differ from
                          what a local C compiler calls 'short'.)

                   i   A signed integer value.
                   I   An unsigned integer value.
                         (This 'integer' is _at_least_ 32 bits wide.  Its exact size
                          depends on what a local C compiler calls 'int', and may
                          even be larger than the 'long' described in the next item.)

                   l   A signed long value.
                   L   An unsigned long value.
                         (This 'long' is _exactly_ 32 bits, which may differ from
                          what a local C compiler calls 'long'.)

                   n   A short in "network" (big-endian) order.
                   N   A long in "network" (big-endian) order.
                   v   A short in "VAX" (little-endian) order.
                   V   A long in "VAX" (little-endian) order.
                         (These 'shorts' and 'longs' are _exactly_ 16 bits and
                          _exactly_ 32 bits, respectively.)

                   f   A single-precision float in the native format.
                   d   A double-precision float in the native format.

                   p   A pointer to a null-terminated string.
                   P   A pointer to a structure (fixed-length string).

                   u   A uuencoded string.

                   w   A BER compressed integer.  Its bytes represent an unsigned
                       integer in base 128, most significant digit first, with as few
                       digits as possible.  Bit eight (the high bit) is set on each
                       byte except the last.

                   x   A null byte.
                   X   Back up a byte.
                   @   Null fill to absolute position.

               Each letter may optionally be followed by a number
               which gives a repeat count.  With all types except
               "a", "A", "b", "B", "h", "H", and "P" the pack
               function will gobble up that many values from the
               LIST.  A * for the repeat count means to use
               however many items are left.  The "a" and "A"
               types gobble just one value, but pack it as a
               string of length count, padding with nulls or
               spaces as necessary.  (When unpacking, "A" strips
               trailing spaces and nulls, but "a" does not.)
               Likewise, the "b" and "B" fields pack a string
               that many bits long.  The "h" and "H" fields pack
               a string that many nybbles long.  The "P" packs a
               pointer to a structure of the size indicated by
               the length.  Real numbers (floats and doubles) are
               in the native machine format only; due to the
               multiplicity of floating formats around, and the
               lack of a standard "network" representation, no
               facility for interchange has been made.  This
               means that packed floating point data written on
               one machine may not be readable on another - even
               if both use IEEE floating point arithmetic (as the
               endian-ness of the memory representation is not
               part of the IEEE spec).  Note that Perl uses
               doubles internally for all numeric calculation,
               and converting from double into float and thence
               back to double again will lose precision (i.e.,
               unpack("f", pack("f", $foo)) will not in general
               equal $foo).

               Examples:

                   $foo = pack("cccc",65,66,67,68);
                   # foo eq "ABCD"
                   $foo = pack("c4",65,66,67,68);
                   # same thing

                   $foo = pack("ccxxcc",65,66,67,68);
                   # foo eq "AB\0\0CD"

                   $foo = pack("s2",1,2);
                   # "\1\0\2\0" on little-endian
                   # "\0\1\0\2" on big-endian

                   $foo = pack("a4","abcd","x","y","z");
                   # "abcd"

                   $foo = pack("aaaa","abcd","x","y","z");
                   # "axyz"

                   $foo = pack("a14","abcdefg");
                   # "abcdefg\0\0\0\0\0\0\0"

                   $foo = pack("i9pl", gmtime);
                   # a real struct tm (on my system anyway)

                   sub bintodec {
                       unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
                   }

               The same template may generally also be used in
               the unpack function.

       package NAMESPACE
               Declares the compilation unit as being in the
               given namespace.  The scope of the package
               declaration is from the declaration itself through
               the end of the enclosing block (the same scope as
               the local() operator).  All further unqualified
               dynamic identifiers will be in this namespace.  A
               package statement affects only dynamic
               variables--including those you've used local()
               on--but not lexical variables created with my().
               Typically it would be the first declaration in a
               file to be included by the require or use
               operator.  You can switch into a package in more
               than one place; it influences merely which symbol
               table is used by the compiler for the rest of that
               block.  You can refer to variables and filehandles
               in other packages by prefixing the identifier with
               the package name and a double colon:
               $Package::Variable.  If the package name is null,
               the main package as assumed.  That is, $::sail is
               equivalent to $main::sail.

               See the section on Packages in the perlmod manpage
               for more information about packages, modules, and
               classes.  See the perlsub manpage for other
               scoping issues.

       pipe READHANDLE,WRITEHANDLE
               Opens a pair of connected pipes like the
               corresponding system call.  Note that if you set
               up a loop of piped processes, deadlock can occur
               unless you are very careful.  In addition, note
               that Perl's pipes use stdio buffering, so you may
               need to set $| to flush your WRITEHANDLE after
               each command, depending on the application.

               See the IPC::Open2 manpage, the IPC::Open3
               manpage, and the section on Bidirectional
               Communication in the perlipc manpage for examples
               of such things.

       pop ARRAY

       pop     Pops and returns the last value of the array,
               shortening the array by 1.  Has a similar effect
               to

                   $tmp = $ARRAY[$#ARRAY--];

               If there are no elements in the array, returns the
               undefined value.  If ARRAY is omitted, pops the
               @ARGV array in the main program, and the @_ array
               in subroutines, just like shift().

       pos SCALAR

       pos     Returns the offset of where the last m//g search
               left off for the variable is in question ($_ is
               used when the variable is not specified).  May be
               modified to change that offset.  Such modification
               will also influence the \G zero-width assertion in
               regular expressions.  See the perlre manpage and
               the perlop manpage.

       print FILEHANDLE LIST

       print LIST

       print   Prints a string or a comma-separated list of
               strings.  Returns TRUE if successful.  FILEHANDLE
               may be a scalar variable name, in which case the
               variable contains the name of or a reference to
               the filehandle, thus introducing one level of
               indirection.  (NOTE: If FILEHANDLE is a variable
               and the next token is a term, it may be
               misinterpreted as an operator unless you interpose
               a + or put parentheses around the arguments.)  If
               FILEHANDLE is omitted, prints by default to
               standard output (or to the last selected output
               channel--see the select entry elsewhere in this
               document ).  If LIST is also omitted, prints $_ to
               STDOUT.  To set the default output channel to
               something other than STDOUT use the select
               operation.  Note that, because print takes a LIST,
               anything in the LIST is evaluated in a list
               context, and any subroutine that you call will
               have one or more of its expressions evaluated in a
               list context.  Also be careful not to follow the
               print keyword with a left parenthesis unless you
               want the corresponding right parenthesis to
               terminate the arguments to the print--interpose a
               + or put parentheses around all the arguments.

               Note that if you're storing FILEHANDLES in an
               array or other expression, you will have to use a
               block returning its value instead:

                   print { $files[$i] } "stuff\n";
                   print { $OK ? STDOUT : STDERR } "stuff\n";


       printf FILEHANDLE FORMAT, LIST

       printf FORMAT, LIST
               Equivalent to print FILEHANDLE sprintf(FORMAT,
               LIST).  The first argument of the list will be
               interpreted as the printf format.  If use locale
               is in effect, the character used for the decimal
               point in formatted real numbers is affected by the
               LC_NUMERIC locale.  See the perllocale manpage.
               Don't fall into the trap of using a printf() when
               a simple print() would do.  The print() is more
               efficient, and less error prone.

       prototype FUNCTION
               Returns the prototype of a function as a string
               (or undef if the function has no prototype).
               FUNCTION is a reference to, or the name of, the
               function whose prototype you want to retrieve.

       push ARRAY,LIST
               Treats ARRAY as a stack, and pushes the values of
               LIST onto the end of ARRAY.  The length of ARRAY
               increases by the length of LIST.  Has the same
               effect as

                   for $value (LIST) {
                       $ARRAY[++$#ARRAY] = $value;
                   }

               but is more efficient.  Returns the new number of
               elements in the array.

       q/STRING/

       qq/STRING/

       qx/STRING/

       qw/STRING/
               Generalized quotes.  See the perlop manpage.

       quotemeta EXPR

       quotemeta
               Returns the value of EXPR with all non-
               alphanumeric characters backslashed.  (That is,
               all characters not matching /[A-Za-z_0-9]/ will be
               preceded by a backslash in the returned string,
               regardless of any locale settings.)  This is the
               internal function implementing the \Q escape in
               double-quoted strings.

               If EXPR is omitted, uses $_.

       rand EXPR

       rand    Returns a random fractional number greater than or
               equal to 0 and less than the value of EXPR.  (EXPR
               should be positive.)  If EXPR is omitted, the
               value 1 is used.  Automatically calls srand()
               unless srand() has already been called.  See also
               srand().

               (Note: If your rand function consistently returns
               numbers that are too large or too small, then your
               version of Perl was probably compiled with the
               wrong number of RANDBITS.)

       read FILEHANDLE,SCALAR,LENGTH,OFFSET

       read FILEHANDLE,SCALAR,LENGTH
               Attempts to read LENGTH bytes of data into
               variable SCALAR from the specified FILEHANDLE.
               Returns the number of bytes actually read, or
               undef if there was an error.  SCALAR will be grown
               or shrunk to the length actually read.  An OFFSET
               may be specified to place the read data at some
               other place than the beginning of the string.
               This call is actually implemented in terms of
               stdio's fread call.  To get a true read system
               call, see sysread().

       readdir DIRHANDLE
               Returns the next directory entry for a directory
               opened by opendir().  If used in a list context,
               returns all the rest of the entries in the
               directory.  If there are no more entries, returns
               an undefined value in a scalar context or a null
               list in a list context.

               If you're planning to filetest the return values
               out of a readdir(), you'd better prepend the
               directory in question.  Otherwise, because we
               didn't chdir() there, it would have been testing
               the wrong file.

                   opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!";
                   @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
                   closedir DIR;


       readlink EXPR

       readlink
               Returns the value of a symbolic link, if symbolic
               links are implemented.  If not, gives a fatal
               error.  If there is some system error, returns the
               undefined value and sets $! (errno).  If EXPR is
               omitted, uses $_.

       recv SOCKET,SCALAR,LEN,FLAGS
               Receives a message on a socket.  Attempts to
               receive LENGTH bytes of data into variable SCALAR
               from the specified SOCKET filehandle.  Actually
               does a C recvfrom(), so that it can returns the
               address of the sender.  Returns the undefined
               value if there's an error.  SCALAR will be grown
               or shrunk to the length actually read.  Takes the
               same flags as the system call of the same name.
               See the section on UDP: Message Passing in the
               perlipc manpage for examples.

       redo LABEL

       redo    The redo command restarts the loop block without
               evaluating the conditional again.  The continue
               block, if any, is not executed.  If the LABEL is
               omitted, the command refers to the innermost
               enclosing loop.  This command is normally used by
               programs that want to lie to themselves about what
               was just input:

                   # a simpleminded Pascal comment stripper
                   # (warning: assumes no { or } in strings)
                   LINE: while (<STDIN>) {
                       while (s|({.*}.*){.*}|$1 |) {}
                       s|{.*}| |;
                       if (s|{.*| |) {
                           $front = $_;
                           while (<STDIN>) {
                               if (/}/) {      # end of comment?
                                   s|^|$front{|;
                                   redo LINE;
                               }
                           }
                       }
                       print;
                   }


       ref EXPR

       ref     Returns a TRUE value if EXPR is a reference, FALSE
               otherwise.  If EXPR is not specified, $_ will be
               used.  The value returned depends on the type of
               thing the reference is a reference to.  Builtin
               types include:

                   REF
                   SCALAR
                   ARRAY
                   HASH
                   CODE
                   GLOB

               If the referenced object has been blessed into a
               package, then that package name is returned
               instead.  You can think of ref() as a typeof()
               operator.


                   if (ref($r) eq "HASH") {
                       print "r is a reference to a hash.\n";
                   }
                   if (!ref ($r) {
                       print "r is not a reference at all.\n";
                   }

               See also the perlref manpage.

       rename OLDNAME,NEWNAME
               Changes the name of a file.  Returns 1 for
               success, 0 otherwise.  Will not work across file
               system boundaries.

       require EXPR

       require Demands some semantics specified by EXPR, or by $_
               if EXPR is not supplied.  If EXPR is numeric,
               demands that the current version of Perl ($] or
               $PERL_VERSION) be equal or greater than EXPR.

               Otherwise, demands that a library file be included
               if it hasn't already been included.  The file is
               included via the do-FILE mechanism, which is
               essentially just a variety of eval().  Has
               semantics similar to the following subroutine:

                   sub require {
                       local($filename) = @_;
                       return 1 if $INC{$filename};
                       local($realfilename,$result);
                       ITER: {
                           foreach $prefix (@INC) {
                               $realfilename = "$prefix/$filename";
                               if (-f $realfilename) {
                                   $result = do $realfilename;
                                   last ITER;
                               }
                           }
                           die "Can't find $filename in \@INC";
                       }
                       die $@ if $@;
                       die "$filename did not return true value" unless $result;
                       $INC{$filename} = $realfilename;
                       $result;
                   }

               Note that the file will not be included twice
               under the same specified name.  The file must
               return TRUE as the last statement to indicate
               successful execution of any initialization code,
               so it's customary to end such a file with "1;"
               unless you're sure it'll return TRUE otherwise.
               But it's better just to put the "1;", in case you
               add more statements.

               If EXPR is a bareword, the require assumes a ".pm"
               extension and replaces "::" with "/" in the
               filename for you, to make it easy to load standard
               modules.  This form of loading of modules does not
               risk altering your namespace.

               For a yet-more-powerful import facility, see the
               use entry elsewhere in this document the perlmod
               manpage.

       reset EXPR

       reset   Generally used in a continue block at the end of a
               loop to clear variables and reset ?? searches so
               that they work again.  The expression is
               interpreted as a list of single characters
               (hyphens allowed for ranges).  All variables and
               arrays beginning with one of those letters are
               reset to their pristine state.  If the expression
               is omitted, one-match searches (?pattern?) are
               reset to match again.  Resets only variables or
               searches in the current package.  Always returns
               1.  Examples:

                   reset 'X';          # reset all X variables
                   reset 'a-z';        # reset lower case variables
                   reset;              # just reset ?? searches

               Resetting "A-Z" is not recommended because you'll
               wipe out your ARGV and ENV arrays.  Resets only
               package variables--lexical variables are
               unaffected, but they clean themselves up on scope
               exit anyway, so you'll probably want to use them
               instead.  See the my entry elsewhere in this
               document .

       return EXPR

       return  Returns from a subroutine, eval(), or do FILE with
               the value of the given EXPR.  Evaluation of EXPR
               may be in a list, scalar, or void context,
               depending on how the return value will be used,
               and the context may vary from one execution to the
               next (see wantarray()).  If no EXPR is given,
               returns an empty list in a list context, an
               undefined value in a scalar context, or nothing in
               a void context.

               (Note that in the absence of a return, a
               subroutine, eval, or do FILE will automatically
               return the value of the last expression
               evaluated.)

       reverse LIST
               In a list context, returns a list value consisting
               of the elements of LIST in the opposite order.  In
               a scalar context, concatenates the elements of
               LIST, and returns a string value consisting of
               those bytes, but in the opposite order.

                   print reverse <>;           # line tac, last line first

                   undef $/;                   # for efficiency of <>
                   print scalar reverse <>;    # byte tac, last line tsrif

               This operator is also handy for inverting a hash,
               although there are some caveats.  If a value is
               duplicated in the original hash, only one of those
               can be represented as a key in the inverted hash.
               Also, this has to unwind one hash and build a
               whole new one, which may take some time on a large
               hash.

                   %by_name = reverse %by_address;     # Invert the hash


       rewinddir DIRHANDLE
               Sets the current position to the beginning of the
               directory for the readdir() routine on DIRHANDLE.

       rindex STR,SUBSTR,POSITION

       rindex STR,SUBSTR
               Works just like index except that it returns the
               position of the LAST occurrence of SUBSTR in STR.
               If POSITION is specified, returns the last
               occurrence at or before that position.

       rmdir FILENAME

       rmdir   Deletes the directory specified by FILENAME if it
               is empty.  If it succeeds it returns 1, otherwise
               it returns 0 and sets $! (errno).  If FILENAME is
               omitted, uses $_.

       s///    The substitution operator.  See the perlop
               manpage.

       scalar EXPR
               Forces EXPR to be interpreted in a scalar context
               and returns the value of EXPR.

                   @counts = ( scalar @a, scalar @b, scalar @c );

               There is no equivalent operator to force an
               expression to be interpolated in a list context
               because it's in practice never needed.  If you
               really wanted to do so, however, you could use the
               construction @{[ (some expression) ]}, but usually
               a simple (some expression) suffices.

       seek FILEHANDLE,POSITION,WHENCE
               Sets FILEHANDLE's position, just like the fseek()
               call of stdio.  FILEHANDLE may be an expression
               whose value gives the name of the filehandle.  The
               values for WHENCE are 0 to set the new position to
               POSITION, 1 to set it to the current position plus
               POSITION, and 2 to set it to EOF plus POSITION
               (typically negative).  For WHENCE you may use the
               constants SEEK_SET, SEEK_CUR, and SEEK_END from
               either the IO::Seekable or the POSIX module.
               Returns 1 upon success, 0 otherwise.

               If you want to position file for sysread() or
               syswrite(), don't use seek() -- buffering makes
               its effect on the file's system position
               unpredictable and non-portable.  Use sysseek()
               instead.

               On some systems you have to do a seek whenever you
               switch between reading and writing.  Amongst other
               things, this may have the effect of calling
               stdio's clearerr(3).  A WHENCE of 1 (SEEK_CUR) is
               useful for not moving the file position:

                   seek(TEST,0,1);

               This is also useful for applications emulating
               tail -f.  Once you hit EOF on your read, and then
               sleep for a while, you might have to stick in a
               seek() to reset things.  The seek() doesn't change
               the current position, but it does clear the end-
               of-file condition on the handle, so that the next
               <FILE> makes Perl try again to read something.  We
               hope.

               If that doesn't work (some stdios are particularly
               cantankerous), then you may need something more
               like this:

                   for (;;) {
                       for ($curpos = tell(FILE); $_ = <FILE>; $curpos = tell(FILE)) {
                           # search for some stuff and put it into files
                       }
                       sleep($for_a_while);
                       seek(FILE, $curpos, 0);
                   }


       seekdir DIRHANDLE,POS
               Sets the current position for the readdir()
               routine on DIRHANDLE.  POS must be a value
               returned by telldir().  Has the same caveats about
               possible directory compaction as the corresponding
               system library routine.

       select FILEHANDLE

       select  Returns the currently selected filehandle.  Sets
               the current default filehandle for output, if
               FILEHANDLE is supplied.  This has two effects:
               first, a write or a print without a filehandle
               will default to this FILEHANDLE.  Second,
               references to variables related to output will
               refer to this output channel.  For example, if you
               have to set the top of form format for more than
               one output channel, you might do the following:

                   select(REPORT1);
                   $^ = 'report1_top';
                   select(REPORT2);
                   $^ = 'report2_top';

               FILEHANDLE may be an expression whose value gives
               the name of the actual filehandle.  Thus:

                   $oldfh = select(STDERR); $| = 1; select($oldfh);

               Some programmers may prefer to think of
               filehandles as objects with methods, preferring to
               write the last example as:

                   use IO::Handle;
                   STDERR->autoflush(1);


       select RBITS,WBITS,EBITS,TIMEOUT
               This calls the select(2) system call with the bit
               masks specified, which can be constructed using
               fileno() and vec(), along these lines:

                   $rin = $win = $ein = '';
                   vec($rin,fileno(STDIN),1) = 1;
                   vec($win,fileno(STDOUT),1) = 1;
                   $ein = $rin | $win;

               If you want to select on many filehandles you
               might wish to write a subroutine:







                   sub fhbits {
                       local(@fhlist) = split(' ',$_[0]);
                       local($bits);
                       for (@fhlist) {
                           vec($bits,fileno($_),1) = 1;
                       }
                       $bits;
                   }
                   $rin = fhbits('STDIN TTY SOCK');

               The usual idiom is:

                   ($nfound,$timeleft) =
                     select($rout=$rin, $wout=$win, $eout=$ein, $timeout);

               or to block until something becomes ready just do
               this

                   $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);

               Most systems do not bother to return anything
               useful in $timeleft, so calling select() in a
               scalar context just returns $nfound.

               Any of the bit masks can also be undef.  The
               timeout, if specified, is in seconds, which may be
               fractional.  Note: not all implementations are
               capable of returning the $timeleft.  If not, they
               always return $timeleft equal to the supplied
               $timeout.

               You can effect a sleep of 250 milliseconds this
               way:

                   select(undef, undef, undef, 0.25);

               WARNING: Do not attempt to mix buffered I/O (like
               read() or <FH>) with select().  You have to use
               sysread() instead.

       semctl ID,SEMNUM,CMD,ARG
               Calls the System V IPC function semctl.  If CMD is
               &IPC_STAT or &GETALL, then ARG must be a variable
               which will hold the returned semid_ds structure or
               semaphore value array.  Returns like ioctl: the
               undefined value for error, "0 but true" for zero,
               or the actual return value otherwise.

       semget KEY,NSEMS,FLAGS
               Calls the System V IPC function semget.  Returns
               the semaphore id, or the undefined value if there
               is an error.


       semop KEY,OPSTRING
               Calls the System V IPC function semop to perform
               semaphore operations such as signaling and
               waiting.  OPSTRING must be a packed array of semop
               structures.  Each semop structure can be generated
               with pack("sss", $semnum, $semop, $semflag).  The
               number of semaphore operations is implied by the
               length of OPSTRING.  Returns TRUE if successful,
               or FALSE if there is an error.  As an example, the
               following code waits on semaphore $semnum of
               semaphore id $semid:

                   $semop = pack("sss", $semnum, -1, 0);
                   die "Semaphore trouble: $!\n" unless semop($semid, $semop);

               To signal the semaphore, replace "-1" with "1".

       send SOCKET,MSG,FLAGS,TO

       send SOCKET,MSG,FLAGS
               Sends a message on a socket.  Takes the same flags
               as the system call of the same name.  On
               unconnected sockets you must specify a destination
               to send TO, in which case it does a C sendto().
               Returns the number of characters sent, or the
               undefined value if there is an error.  See the
               section on UDP: Message Passing in the perlipc
               manpage for examples.

       setpgrp PID,PGRP
               Sets the current process group for the specified
               PID, 0 for the current process.  Will produce a
               fatal error if used on a machine that doesn't
               implement setpgrp(2).  If the arguments are
               omitted, it defaults to 0,0.  Note that the POSIX
               version of setpgrp() does not accept any
               arguments, so only setpgrp 0,0 is portable.

       setpriority WHICH,WHO,PRIORITY
               Sets the current priority for a process, a process
               group, or a user.  (See setpriority(2).)  Will
               produce a fatal error if used on a machine that
               doesn't implement setpriority(2).

       setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
               Sets the socket option requested.  Returns
               undefined if there is an error.  OPTVAL may be
               specified as undef if you don't want to pass an
               argument.

       shift ARRAY

       shift   Shifts the first value of the array off and
               returns it, shortening the array by 1 and moving
               everything down.  If there are no elements in the
               array, returns the undefined value.  If ARRAY is
               omitted, shifts the @ARGV array in the main
               program, and the @_ array in subroutines.  (This
               is determined lexically.)  See also unshift(),
               push(), and pop().  Shift() and unshift() do the
               same thing to the left end of an array that pop()
               and push() do to the right end.

       shmctl ID,CMD,ARG
               Calls the System V IPC function shmctl.  If CMD is
               &IPC_STAT, then ARG must be a variable which will
               hold the returned shmid_ds structure.  Returns
               like ioctl: the undefined value for error, "0 but
               true" for zero, or the actual return value
               otherwise.

       shmget KEY,SIZE,FLAGS
               Calls the System V IPC function shmget.  Returns
               the shared memory segment id, or the undefined
               value if there is an error.

       shmread ID,VAR,POS,SIZE

       shmwrite ID,STRING,POS,SIZE
               Reads or writes the System V shared memory segment
               ID starting at position POS for size SIZE by
               attaching to it, copying in/out, and detaching
               from it.  When reading, VAR must be a variable
               which will hold the data read.  When writing, if
               STRING is too long, only SIZE bytes are used; if
               STRING is too short, nulls are written to fill out
               SIZE bytes.  Return TRUE if successful, or FALSE
               if there is an error.

       shutdown SOCKET,HOW
               Shuts down a socket connection in the manner
               indicated by HOW, which has the same
               interpretation as in the system call of the same
               name.

       sin EXPR

       sin     Returns the sine of EXPR (expressed in radians).
               If EXPR is omitted, returns sine of $_.

               For the inverse sine operation, you may use the
               POSIX::asin() function, or use this relation:

                   sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }


       sleep EXPR

       sleep   Causes the script to sleep for EXPR seconds, or
               forever if no EXPR.  May be interrupted by sending
               the process a SIGALRM.  Returns the number of
               seconds actually slept.  You probably cannot mix
               alarm() and sleep() calls, because sleep() is
               often implemented using alarm().

               On some older systems, it may sleep up to a full
               second less than what you requested, depending on
               how it counts seconds.  Most modern systems always
               sleep the full amount.

               For delays of finer granularity than one second,
               you may use Perl's syscall() interface to access
               setitimer(2) if your system supports it, or else
               see the select() entry elsewhere in this document
               below.

               See also the POSIX module's sigpause() function.

       socket SOCKET,DOMAIN,TYPE,PROTOCOL
               Opens a socket of the specified kind and attaches
               it to filehandle SOCKET.  DOMAIN, TYPE, and
               PROTOCOL are specified the same as for the system
               call of the same name.  You should "use Socket;"
               first to get the proper definitions imported.  See
               the example in the section on Sockets:
               Client/Server Communication in the perlipc
               manpage.

       socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
               Creates an unnamed pair of sockets in the
               specified domain, of the specified type.  DOMAIN,
               TYPE, and PROTOCOL are specified the same as for
               the system call of the same name.  If
               unimplemented, yields a fatal error.  Returns TRUE
               if successful.

       sort SUBNAME LIST

       sort BLOCK LIST

       sort LIST
               Sorts the LIST and returns the sorted list value.
               If SUBNAME or BLOCK is omitted, sorts in standard
               string comparison order.  If SUBNAME is specified,
               it gives the name of a subroutine that returns an
               integer less than, equal to, or greater than 0,
               depending on how the elements of the array are to
               be ordered.  (The <=> and cmp operators are
               extremely useful in such routines.)  SUBNAME may
               be a scalar variable name, in which case the value
               provides the name of the subroutine to use.  In
               place of a SUBNAME, you can provide a BLOCK as an
               anonymous, in-line sort subroutine.

               In the interests of efficiency the normal calling
               code for subroutines is bypassed, with the
               following effects: the subroutine may not be a
               recursive subroutine, and the two elements to be
               compared are passed into the subroutine not via @_
               but as the package global variables $a and $b (see
               example below).  They are passed by reference, so
               don't modify $a and $b.  And don't try to declare
               them as lexicals either.

               You also cannot exit out of the sort block or
               subroutine using any of the loop control operators
               described in the perlsyn manpage or with goto().

               When use locale is in effect, sort LIST sorts LIST
               according to the current collation locale.  See
               the perllocale manpage.

               Examples:

                   # sort lexically
                   @articles = sort @files;

                   # same thing, but with explicit sort routine
                   @articles = sort {$a cmp $b} @files;

                   # now case-insensitively
                   @articles = sort {uc($a) cmp uc($b)} @files;

                   # same thing in reversed order
                   @articles = sort {$b cmp $a} @files;

                   # sort numerically ascending
                   @articles = sort {$a <=> $b} @files;

                   # sort numerically descending
                   @articles = sort {$b <=> $a} @files;

                   # sort using explicit subroutine name
                   sub byage {
                       $age{$a} <=> $age{$b};  # presuming numeric
                   }
                   @sortedclass = sort byage @class;

                   # this sorts the %age hash by value instead of key
                   # using an in-line function
                   @eldest = sort { $age{$b} <=> $age{$a} } keys %age;





                   sub backwards { $b cmp $a; }
                   @harry = ('dog','cat','x','Cain','Abel');
                   @george = ('gone','chased','yz','Punished','Axed');
                   print sort @harry;
                           # prints AbelCaincatdogx
                   print sort backwards @harry;
                           # prints xdogcatCainAbel
                   print sort @george, 'to', @harry;
                           # prints AbelAxedCainPunishedcatchaseddoggonetoxyz

                   # inefficiently sort by descending numeric compare using
                   # the first integer after the first = sign, or the
                   # whole record case-insensitively otherwise

                   @new = sort {
                       ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
                                           ||
                                   uc($a)  cmp  uc($b)
                   } @old;

                   # same thing, but much more efficiently;
                   # we'll build auxiliary indices instead
                   # for speed
                   @nums = @caps = ();
                   for (@old) {
                       push @nums, /=(\d+)/;
                       push @caps, uc($_);
                   }

                   @new = @old[ sort {
                                       $nums[$b] <=> $nums[$a]
                                                ||
                                       $caps[$a] cmp $caps[$b]
                                      } 0..$#old
                              ];

                   # same thing using a Schwartzian Transform (no temps)
                   @new = map { $_->[0] }
                       sort { $b->[1] <=> $a->[1]
                                       ||
                              $a->[2] cmp $b->[2]
                       } map { [$_, /=(\d+)/, uc($_)] } @old;

               If you're using strict, you MUST NOT declare $a
               and $b as lexicals.  They are package globals.
               That means if you're in the main package, it's

                   @articles = sort {$main::b <=> $main::a} @files;

               or just

                   @articles = sort {$::b <=> $::a} @files;

               but if you're in the FooPack package, it's
                   @articles = sort {$FooPack::b <=> $FooPack::a} @files;

               The comparison function is required to behave.  If
               it returns inconsistent results (sometimes saying
               $x[1] is less than $x[2] and sometimes saying the
               opposite, for example) the Perl interpreter will
               probably crash and dump core.  This is entirely
               due to and dependent upon your system's qsort(3)
               library routine; this routine often avoids sanity
               checks in the interest of speed.

       splice ARRAY,OFFSET,LENGTH,LIST

       splice ARRAY,OFFSET,LENGTH

       splice ARRAY,OFFSET
               Removes the elements designated by OFFSET and
               LENGTH from an array, and replaces them with the
               elements of LIST, if any.  Returns the elements
               removed from the array.  The array grows or
               shrinks as necessary.  If LENGTH is omitted,
               removes everything from OFFSET onward.  The
               following equivalences hold (assuming $[ == 0):

                   push(@a,$x,$y)      splice(@a,$#a+1,0,$x,$y)
                   pop(@a)             splice(@a,-1)
                   shift(@a)           splice(@a,0,1)
                   unshift(@a,$x,$y)   splice(@a,0,0,$x,$y)
                   $a[$x] = $y         splice(@a,$x,1,$y);

               Example, assuming array lengths are passed before
               arrays:

                   sub aeq {   # compare two list values
                       local(@a) = splice(@_,0,shift);
                       local(@b) = splice(@_,0,shift);
                       return 0 unless @a == @b;       # same len?
                       while (@a) {
                           return 0 if pop(@a) ne pop(@b);
                       }
                       return 1;
                   }
                   if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }


       split /PATTERN/,EXPR,LIMIT

       split /PATTERN/,EXPR

       split /PATTERN/

       split   Splits a string into an array of strings, and
               returns it.

               If not in a list context, returns the number of
               fields found and splits into the @_ array.  (In a
               list context, you can force the split into @_ by
               using ?? as the pattern delimiters, but it still
               returns the array value.)  The use of implicit
               split to @_ is deprecated, however.

               If EXPR is omitted, splits the $_ string.  If
               PATTERN is also omitted, splits on whitespace
               (after skipping any leading whitespace).  Anything
               matching PATTERN is taken to be a delimiter
               separating the fields.  (Note that the delimiter
               may be longer than one character.)  If LIMIT is
               specified and is not negative, splits into no more
               than that many fields (though it may split into
               fewer).  If LIMIT is unspecified, trailing null
               fields are stripped (which potential users of
               pop() would do well to remember).  If LIMIT is
               negative, it is treated as if an arbitrarily large
               LIMIT had been specified.

               A pattern matching the null string (not to be
               confused with a null pattern //, which is just one
               member of the set of patterns matching a null
               string) will split the value of EXPR into separate
               characters at each point it matches that way.  For
               example:

                   print join(':', split(/ */, 'hi there'));

               produces the output 'h:i:t:h:e:r:e'.

               The LIMIT parameter can be used to split a line
               partially

                   ($login, $passwd, $remainder) = split(/:/, $_, 3);

               When assigning to a list, if LIMIT is omitted,
               Perl supplies a LIMIT one larger than the number
               of variables in the list, to avoid unnecessary
               work.  For the list above LIMIT would have been 4
               by default.  In time critical applications it
               behooves you not to split into more fields than
               you really need.

               If the PATTERN contains parentheses, additional
               array elements are created from each matching
               substring in the delimiter.

                   split(/([,-])/, "1-10,20", 3);

               produces the list value

                   (1, '-', 10, ',', 20)

               If you had the entire header of a normal Unix
               email message in $header, you could split it up
               into fields and their values this way:

                   $header =~ s/\n\s+/ /g;  # fix continuation lines
                   %hdrs   =  (UNIX_FROM => split /^(.*?):\s*/m, $header);

               The pattern /PATTERN/ may be replaced with an
               expression to specify patterns that vary at
               runtime.  (To do runtime compilation only once,
               use /$variable/o.)

               As a special case, specifying a PATTERN of space
               (' ') will split on white space just as split with
               no arguments does.  Thus, split(' ') can be used
               to emulate awk's default behavior, whereas split(/
               /) will give you as many null initial fields as
               there are leading spaces.  A split on /\s+/ is
               like a split(' ') except that any leading
               whitespace produces a null first field.  A split
               with no arguments really does a split(' ', $_)
               internally.

               Example:

                   open(passwd, '/etc/passwd');
                   while (<passwd>) {
                       ($login, $passwd, $uid, $gid, $gcos,
                           $home, $shell) = split(/:/);
                       ...
                   }

               (Note that $shell above will still have a newline
               on it.  See the chop, chomp,  and join entries
               elsewhere in this document .)

       sprintf FORMAT, LIST
               Returns a string formatted by the usual printf
               conventions of the C library function sprintf().
               See the sprintf(3) manpage or the printf(3)
               manpage on your system for an explanation of the
               general principles.

               Perl does all of its own sprintf() formatting --
               it emulates the C function sprintf(), but it
               doesn't use it (except for floating-point numbers,
               and even then only the standard modifiers are
               allowed).  As a result, any non-standard
               extensions in your local sprintf() are not
               available from Perl.

               Perl's sprintf() permits the following
               universally-known conversions:

                  %%   a percent sign
                  %c   a character with the given number
                  %s   a string
                  %d   a signed integer, in decimal
                  %u   an unsigned integer, in decimal
                  %o   an unsigned integer, in octal
                  %x   an unsigned integer, in hexadecimal
                  %e   a floating-point number, in scientific notation
                  %f   a floating-point number, in fixed decimal notation
                  %g   a floating-point number, in %e or %f notation

               In addition, Perl permits the following widely-
               supported conversions:

                  %X   like %x, but using upper-case letters
                  %E   like %e, but using an upper-case "E"
                  %G   like %g, but with an upper-case "E" (if applicable)
                  %p   a pointer (outputs the Perl value's address in hexadecimal)
                  %n   special: *stores* the number of characters output so far
                       into the next variable in the parameter list

               Finally, for backward (and we do mean "backward")
               compatibility, Perl permits these unnecessary but
               widely-supported conversions:

                  %i   a synonym for %d
                  %D   a synonym for %ld
                  %U   a synonym for %lu
                  %O   a synonym for %lo
                  %F   a synonym for %f

               Perl permits the following universally-known flags
               between the % and the conversion letter:

                  space   prefix positive number with a space
                  +       prefix positive number with a plus sign
                  -       left-justify within the field
                  0       use zeros, not spaces, to right-justify
                  #       prefix octal with "0", hex with "0x"
                  number  minimum field width
                  .number "precision": digits after decimal point for floating-point,
                          max length for string, minimum length for integer
                  l       interpret integer as C type "long" or "unsigned long"
                  h       interpret integer as C type "short" or "unsigned short"

               There is also one Perl-specific flag:

                  V       interpret integer as Perl's standard integer type

               Where a number would appear in the flags, an
               asterisk ("*") may be used instead, in which case
               Perl uses the next item in the parameter list as
               the given number (that is, as the field width or
               precision).  If a field width obtained through "*"
               is negative, it has the same effect as the '-'
               flag: left-justification.

               If use locale is in effect, the character used for
               the decimal point in formatted real numbers is
               affected by the LC_NUMERIC locale.  See the
               perllocale manpage.

       sqrt EXPR

       sqrt    Return the square root of EXPR.  If EXPR is
               omitted, returns square root of $_.

       srand EXPR

       srand   Sets the random number seed for the rand operator.
               If EXPR is omitted, uses a semi-random value based
               on the current time and process ID, among other
               things.  In versions of Perl prior to 5.004 the
               default seed was just the current time().  This
               isn't a particularly good seed, so many old
               programs supply their own seed value (often time ^
               $$ or C<time ^ ($$ + ($$ << 15))>), but that isn't
               necessary any more.

               In fact, it's usually not necessary to call
               srand() at all, because if it is not called
               explicitly, it is called implicitly at the first
               use of the rand operator.  However, this was not
               the case in version of Perl before 5.004, so if
               your script will run under older Perl versions, it
               should call srand().

               Note that you need something much more random than
               the default seed for cryptographic purposes.
               Checksumming the compressed output of one or more
               rapidly changing operating system status programs
               is the usual method.  For example:

                   srand (time ^ $$ ^ unpack "%L*", `ps axww | gzip`);

               If you're particularly concerned with this, see
               the Math::TrulyRandom module in CPAN.

               Do not call srand() multiple times in your program
               unless you know exactly what you're doing and why
               you're doing it.  The point of the function is to
               "seed" the rand() function so that rand() can
               produce a different sequence each time you run
               your program.  Just do it once at the top of your
               program, or you won't get random numbers out of
               rand()!

               Frequently called programs (like CGI scripts) that
               simply use

                   time ^ $$

               for a seed can fall prey to the mathematical
               property that

                   a^b == (a+1)^(b+1)

               one-third of the time.  So don't do that.

       stat FILEHANDLE

       stat EXPR

       stat    Returns a 13-element array giving the status info
               for a file, either the file opened via FILEHANDLE,
               or named by EXPR.  If EXPR is omitted, it stats
               $_.  Returns a null list if the stat fails.
               Typically used as follows:

                   ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
                      $atime,$mtime,$ctime,$blksize,$blocks)
                          = stat($filename);

               Not all fields are supported on all filesystem
               types.  Here are the meaning of the fields:

                 0 dev      device number of filesystem
                 1 ino      inode number
                 2 mode     file mode  (type and permissions)
                 3 nlink    number of (hard) links to the file
                 4 uid      numeric user ID of file's owner
                 5 gid      numeric group ID of file's owner
                 6 rdev     the device identifier (special files only)
                 7 size     total size of file, in bytes
                 8 atime    last access time since the epoch
                 9 mtime    last modify time since the epoch
                10 ctime    inode change time (NOT creation time!) since the epoch
                11 blksize  preferred block size for file system I/O
                12 blocks   actual number of blocks allocated

               (The epoch was at 00:00 January 1, 1970 GMT.)

               If stat is passed the special filehandle
               consisting of an underline, no stat is done, but
               the current contents of the stat structure from
               the last stat or filetest are returned.  Example:

                   if (-x $file && (($d) = stat(_)) && $d < 0) {
                       print "$file is executable NFS file\n";
                   }

               (This works on machines only for which the device
               number is negative under NFS.)

       study SCALAR

       study   Takes extra time to study SCALAR ($_ if
               unspecified) in anticipation of doing many pattern
               matches on the string before it is next modified.
               This may or may not save time, depending on the
               nature and number of patterns you are searching
               on, and on the distribution of character
               frequencies in the string to be searched -- you
               probably want to compare run times with and
               without it to see which runs faster.  Those loops
               which scan for many short constant strings
               (including the constant parts of more complex
               patterns) will benefit most.  You may have only
               one study active at a time -- if you study a
               different scalar the first is "unstudied".  (The
               way study works is this: a linked list of every
               character in the string to be searched is made, so
               we know, for example, where all the 'k' characters
               are.  From each search string, the rarest
               character is selected, based on some static
               frequency tables constructed from some C programs
               and English text.  Only those places that contain
               this "rarest" character are examined.)

               For example, here is a loop which inserts index
               producing entries before any line containing a
               certain pattern:

                   while (<>) {
                       study;
                       print ".IX foo\n" if /\bfoo\b/;
                       print ".IX bar\n" if /\bbar\b/;
                       print ".IX blurfl\n" if /\bblurfl\b/;
                       ...
                       print;
                   }

               In searching for /\bfoo\b/, only those locations
               in $_ that contain "f" will be looked at, because
               "f" is rarer than "o".  In general, this is a big
               win except in pathological cases.  The only
               question is whether it saves you more time than it
               took to build the linked list in the first place.

               Note that if you have to look for strings that you
               don't know till runtime, you can build an entire
               loop as a string and eval that to avoid
               recompiling all your patterns all the time.
               Together with undefining $/ to input entire files
               as one record, this can be very fast, often faster
               than specialized programs like fgrep(1).  The
               following scans a list of files (@files) for a
               list of words (@words), and prints out the names
               of those files that contain a match:

                   $search = 'while (<>) { study;';
                   foreach $word (@words) {
                       $search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n";
                   }
                   $search .= "}";
                   @ARGV = @files;
                   undef $/;
                   eval $search;               # this screams
                   $/ = "\n";          # put back to normal input delimiter
                   foreach $file (sort keys(%seen)) {
                       print $file, "\n";
                   }


       sub BLOCK

       sub NAME

       sub NAME BLOCK
               This is subroutine definition, not a real function
               per se.  With just a NAME (and possibly
               prototypes), it's just a forward declaration.
               Without a NAME, it's an anonymous function
               declaration, and does actually return a value: the
               CODE ref of the closure you just created.  See the
               perlsub manpage and the perlref manpage for
               details.

       substr EXPR,OFFSET,LEN

       substr EXPR,OFFSET
               Extracts a substring out of EXPR and returns it.
               First character is at offset 0, or whatever you've
               set $[ to (but don't do that).  If OFFSET is
               negative, starts that far from the end of the
               string.  If LEN is omitted, returns everything to
               the end of the string.  If LEN is negative, leaves
               that many characters off the end of the string.

               You can use the substr() function as an lvalue, in
               which case EXPR must be an lvalue.  If you assign
               something shorter than LEN, the string will
               shrink, and if you assign something longer than
               LEN, the string will grow to accommodate it.  To
               keep the string the same length you may need to
               pad or chop your value using sprintf().

       symlink OLDFILE,NEWFILE
               Creates a new filename symbolically linked to the
               old filename.  Returns 1 for success, 0 otherwise.
               On systems that don't support symbolic links,
               produces a fatal error at run time.  To check for
               that, use eval:

                   $symlink_exists = (eval {symlink("","")};, $@ eq '');


       syscall LIST
               Calls the system call specified as the first
               element of the list, passing the remaining
               elements as arguments to the system call.  If
               unimplemented, produces a fatal error.  The
               arguments are interpreted as follows: if a given
               argument is numeric, the argument is passed as an
               int.  If not, the pointer to the string value is
               passed.  You are responsible to make sure a string
               is pre-extended long enough to receive any result
               that might be written into a string.  If your
               integer arguments are not literals and have never
               been interpreted in a numeric context, you may
               need to add 0 to them to force them to look like
               numbers.

                   require 'syscall.ph';               # may need to run h2ph
                   syscall(&SYS_write, fileno(STDOUT), "hi there\n", 9);

               Note that Perl supports passing of up to only 14
               arguments to your system call, which in practice
               should usually suffice.

       sysopen FILEHANDLE,FILENAME,MODE

       sysopen FILEHANDLE,FILENAME,MODE,PERMS
               Opens the file whose filename is given by
               FILENAME, and associates it with FILEHANDLE.  If
               FILEHANDLE is an expression, its value is used as
               the name of the real filehandle wanted.  This
               function calls the underlying operating system's
               open function with the parameters FILENAME, MODE,
               PERMS.

               The possible values and flag bits of the MODE
               parameter are system-dependent; they are available
               via the standard module Fcntl.  However, for
               historical reasons, some values are universal:
               zero means read-only, one means write-only, and
               two means read/write.

               If the file named by FILENAME does not exist and
               the open call creates it (typically because MODE
               includes the O_CREAT flag), then the value of
               PERMS specifies the permissions of the newly
               created file.  If PERMS is omitted, the default
               value is 0666, which allows read and write for
               all.  This default is reasonable: see umask.

               The IO::File module provides a more object-
               oriented approach, if you're into that kind of
               thing.

       sysread FILEHANDLE,SCALAR,LENGTH,OFFSET

       sysread FILEHANDLE,SCALAR,LENGTH
               Attempts to read LENGTH bytes of data into
               variable SCALAR from the specified FILEHANDLE,
               using the system call read(2).  It bypasses stdio,
               so mixing this with other kinds of reads, print(),
               write(), seek(), or tell() can cause confusion.
               Returns the number of bytes actually read, or
               undef if there was an error.  SCALAR will be grown
               or shrunk so that the last byte actually read is
               the last byte of the scalar after the read.

               An OFFSET may be specified to place the read data
               at some place in the string other than the
               beginning.  A negative OFFSET specifies placement
               at that many bytes counting backwards from the end
               of the string.  A positive OFFSET greater than the
               length of SCALAR results in the string being
               padded to the required size with "\0" bytes before
               the result of the read is appended.

       sysseek FILEHANDLE,POSITION,WHENCE
               Sets FILEHANDLE's system position using the system
               call lseek(2).  It bypasses stdio, so mixing this
               with reads (other than sysread()), print(),
               write(), seek(), or tell() may cause confusion.
               FILEHANDLE may be an expression whose value gives
               the name of the filehandle.  The values for WHENCE
               are 0 to set the new position to POSITION, 1 to
               set the it to the current position plus POSITION,
               and 2 to set it to EOF plus POSITION (typically
               negative).  For WHENCE, you may use the constants
               SEEK_SET, SEEK_CUR, and SEEK_END from either the
               IO::Seekable or the POSIX module.

               Returns the new position, or the undefined value
               on failure.  A position of zero is returned as the
               string "0 but true"; thus sysseek() returns TRUE
               on success and FALSE on failure, yet you can still
               easily determine the new position.

       system LIST
               Does exactly the same thing as "exec LIST" except
               that a fork is done first, and the parent process
               waits for the child process to complete.  Note
               that argument processing varies depending on the
               number of arguments.  The return value is the exit
               status of the program as returned by the wait()
               call.  To get the actual exit value divide by 256.
               See also the exec entry elsewhere in this document
               .  This is NOT what you want to use to capture the
               output from a command, for that you should use
               merely backticks or qx//, as described in the
               section on `STRING` in the perlop manpage.

               Because system() and backticks block SIGINT and
               SIGQUIT, killing the program they're running
               doesn't actually interrupt your program.

                   @args = ("command", "arg1", "arg2");
                   system(@args) == 0
                        or die "system @args failed: $?"

               Here's a more elaborate example of analysing the
               return value from system() on a Unix system to
               check for all possibilities, including for signals
               and core dumps.

                   $rc = 0xffff & system @args;
                   printf "system(%s) returned %#04x: ", "@args", $rc;
                   if ($rc == 0) {
                       print "ran with normal exit\n";
                   }
                   elsif ($rc == 0xff00) {
                       print "command failed: $!\n";
                   }
                   elsif ($rc > 0x80) {
                       $rc >>= 8;
                       print "ran with non-zero exit status $rc\n";
                   }
                   else {
                       print "ran with ";
                       if ($rc &   0x80) {
                           $rc &= ~0x80;
                           print "core dump from ";
                       }
                       print "signal $rc\n"
                   }
                   $ok = ($rc != 0);


       syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET

       syswrite FILEHANDLE,SCALAR,LENGTH
               Attempts to write LENGTH bytes of data from
               variable SCALAR to the specified FILEHANDLE, using
               the system call write(2).  It bypasses stdio, so
               mixing this with reads (other than sysread()),
               print(), write(), seek(), or tell() may cause
               confusion.  Returns the number of bytes actually
               written, or undef if there was an error.  If the
               length is greater than the available data, only as
               much data as is available will be written.

               An OFFSET may be specified to write the data from
               some part of the string other than the beginning.
               A negative OFFSET specifies writing that many
               bytes counting backwards from the end of the
               string.

       tell FILEHANDLE

       tell    Returns the current position for FILEHANDLE.
               FILEHANDLE may be an expression whose value gives
               the name of the actual filehandle.  If FILEHANDLE
               is omitted, assumes the file last read.

       telldir DIRHANDLE
               Returns the current position of the readdir()
               routines on DIRHANDLE.  Value may be given to
               seekdir() to access a particular location in a
               directory.  Has the same caveats about possible
               directory compaction as the corresponding system
               library routine.

       tie VARIABLE,CLASSNAME,LIST
               This function binds a variable to a package class
               that will provide the implementation for the
               variable.  VARIABLE is the name of the variable to
               be enchanted.  CLASSNAME is the name of a class
               implementing objects of correct type.  Any
               additional arguments are passed to the "new"
               method of the class (meaning TIESCALAR, TIEARRAY,
               or TIEHASH).  Typically these are arguments such
               as might be passed to the dbm_open() function of
               C.  The object returned by the "new" method is
               also returned by the tie() function, which would
               be useful if you want to access other methods in
               CLASSNAME.

               Note that functions such as keys() and values()
               may return huge array values when used on large
               objects, like DBM files.  You may prefer to use
               the each() function to iterate over such.
               Example:

                   # print out history file offsets
                   use NDBM_File;
                   tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
                   while (($key,$val) = each %HIST) {
                       print $key, ' = ', unpack('L',$val), "\n";
                   }
                   untie(%HIST);

               A class implementing a hash should have the
               following methods:

                   TIEHASH classname, LIST
                   DESTROY this
                   FETCH this, key
                   STORE this, key, value
                   DELETE this, key
                   EXISTS this, key
                   FIRSTKEY this
                   NEXTKEY this, lastkey

               A class implementing an ordinary array should have
               the following methods:

                   TIEARRAY classname, LIST
                   DESTROY this
                   FETCH this, key
                   STORE this, key, value
                   [others TBD]

               A class implementing a scalar should have the
               following methods:

                   TIESCALAR classname, LIST
                   DESTROY this
                   FETCH this,
                   STORE this, value

               Unlike dbmopen(), the tie() function will not use
               or require a module for you--you need to do that
               explicitly yourself.  See the DB_File manpage or
               the Config module for interesting tie()
               implementations.

       tied VARIABLE
               Returns a reference to the object underlying
               VARIABLE (the same value that was originally
               returned by the tie() call which bound the
               variable to a package.)  Returns the undefined
               value if VARIABLE isn't tied to a package.

       time    Returns the number of non-leap seconds since
               whatever time the system considers to be the epoch
               (that's 00:00:00, January 1, 1904 for MacOS, and
               00:00:00 UTC, January 1, 1970 for most other
               systems).  Suitable for feeding to gmtime() and
               localtime().

       times   Returns a four-element array giving the user and
               system times, in seconds, for this process and the
               children of this process.

                   ($user,$system,$cuser,$csystem) = times;

       tr///   The translation operator.  Same as y///. See the
               perlop manpage.

       truncate FILEHANDLE,LENGTH

       truncate EXPR,LENGTH
               Truncates the file opened on FILEHANDLE, or named
               by EXPR, to the specified length.  Produces a
               fatal error if truncate isn't implemented on your
               system.

       uc EXPR

       uc      Returns an uppercased version of EXPR.  This is
               the internal function implementing the \U escape
               in double-quoted strings.  Respects current
               LC_CTYPE locale if use locale in force.  See the
               perllocale manpage.

               If EXPR is omitted, uses $_.

       ucfirst EXPR

       ucfirst Returns the value of EXPR with the first character
               uppercased.  This is the internal function
               implementing the \u escape in double-quoted
               strings.  Respects current LC_CTYPE locale if use
               locale in force.  See the perllocale manpage.

               If EXPR is omitted, uses $_.

       umask EXPR

       umask   Sets the umask for the process to EXPR and returns
               the previous value.  If EXPR is omitted, merely
               returns the current umask.  Remember that a umask
               is a number, usually given in octal; it is not a
               string of octal digits.  See also the oct entry
               elsewhere in this document if all you have is a
               string.

       undef EXPR

       undef   Undefines the value of EXPR, which must be an
               lvalue.  Use only on a scalar value, an entire
               array, an entire hash, or a subroutine name (using
               "&").  (Using undef() will probably not do what
               you expect on most predefined variables or DBM
               list values, so don't do that.)  Always returns
               the undefined value.  You can omit the EXPR, in
               which case nothing is undefined, but you still get
               an undefined value that you could, for instance,
               return from a subroutine, assign to a variable or
               pass as a parameter.  Examples:
                   undef $foo;
                   undef $bar{'blurfl'};             # Compare to: delete $bar{'blurfl'};
                   undef @ary;
                   undef %hash;
                   undef &mysub;
                   return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
                   select undef, undef, undef, 0.25;
                   ($a, $b, undef, $c) = &foo;       # Ignore third value returned


       unlink LIST

       unlink  Deletes a list of files.  Returns the number of
               files successfully deleted.

                   $cnt = unlink 'a', 'b', 'c';
                   unlink @goners;
                   unlink <*.bak>;

               Note: unlink will not delete directories unless
               you are superuser and the -U flag is supplied to
               Perl.  Even if these conditions are met, be warned
               that unlinking a directory can inflict damage on
               your filesystem.  Use rmdir instead.

               If LIST is omitted, uses $_.

       unpack TEMPLATE,EXPR
               Unpack does the reverse of pack: it takes a string
               representing a structure and expands it out into a
               list value, returning the array value.  (In a
               scalar context, it returns merely the first value
               produced.)  The TEMPLATE has the same format as in
               the pack function.  Here's a subroutine that does
               substring:

                   sub substr {
                       local($what,$where,$howmuch) = @_;
                       unpack("x$where a$howmuch", $what);
                   }

               and then there's

                   sub ordinal { unpack("c",$_[0]); } # same as ord()

               In addition, you may prefix a field with a
               %<number> to indicate that you want a <number>-bit
               checksum of the items instead of the items
               themselves.  Default is a 16-bit checksum.  For
               example, the following computes the same number as
               the System V sum program:



                   while (<>) {
                       $checksum += unpack("%16C*", $_);
                   }
                   $checksum %= 65536;

               The following efficiently counts the number of set
               bits in a bit vector:

                   $setbits = unpack("%32b*", $selectmask);


       untie VARIABLE
               Breaks the binding between a variable and a
               package.  (See tie().)

       unshift ARRAY,LIST
               Does the opposite of a shift.  Or the opposite of
               a push, depending on how you look at it.  Prepends
               list to the front of the array, and returns the
               new number of elements in the array.

                   unshift(ARGV, '-e') unless $ARGV[0] =~ /^-/;

               Note the LIST is prepended whole, not one element
               at a time, so the prepended elements stay in the
               same order.  Use reverse to do the reverse.

       use Module LIST

       use Module

       use Module VERSION LIST

       use VERSION
               Imports some semantics into the current package
               from the named module, generally by aliasing
               certain subroutine or variable names into your
               package.  It is exactly equivalent to

                   BEGIN { require Module; import Module LIST; }

               except that Module must be a bareword.

               If the first argument to use is a number, it is
               treated as a version number instead of a module
               name.  If the version of the Perl interpreter is
               less than VERSION, then an error message is
               printed and Perl exits immediately.  This is often
               useful if you need to check the current Perl
               version before useing library modules which have
               changed in incompatible ways from older versions
               of Perl.  (We try not to do this more than we have
               to.)

               The BEGIN forces the require and import to happen
               at compile time.  The require makes sure the
               module is loaded into memory if it hasn't been
               yet.  The import is not a builtin--it's just an
               ordinary static method call into the "Module"
               package to tell the module to import the list of
               features back into the current package.  The
               module can implement its import method any way it
               likes, though most modules just choose to derive
               their import method via inheritance from the
               Exporter class that is defined in the Exporter
               module.  See the Exporter manpage.  If no import
               method can be found then the error is currently
               silently ignored.  This may change to a fatal
               error in a future version.

               If you don't want your namespace altered,
               explicitly supply an empty list:

                   use Module ();

               That is exactly equivalent to

                   BEGIN { require Module; }

               If the VERSION argument is present between Module
               and LIST, then the use will call the VERSION
               method in class Module with the given version as
               an argument.  The default VERSION method,
               inherited from the Universal class, croaks if the
               given version is larger than the value of the
               variable $Module::VERSION.  (Note that there is
               not a comma after VERSION!)

               Because this is a wide-open interface, pragmas
               (compiler directives) are also implemented this
               way.  Currently implemented pragmas are:

                   use integer;
                   use diagnostics;
                   use sigtrap qw(SEGV BUS);
                   use strict  qw(subs vars refs);
                   use subs    qw(afunc blurfl);

               These pseudo-modules import semantics into the
               current block scope, unlike ordinary modules,
               which import symbols into the current package
               (which are effective through the end of the file).

               There's a corresponding "no" command that
               unimports meanings imported by use, i.e., it calls
               unimport Module LIST instead of import.


                   no integer;
                   no strict 'refs';

               If no unimport method can be found the call fails
               with a fatal error.

               See the perlmod manpage for a list of standard
               modules and pragmas.

       utime LIST
               Changes the access and modification times on each
               file of a list of files.  The first two elements
               of the list must be the NUMERICAL access and
               modification times, in that order.  Returns the
               number of files successfully changed.  The inode
               modification time of each file is set to the
               current time.  Example of a "touch" command:

                   #!/usr/bin/perl
                   $now = time;
                   utime $now, $now, @ARGV;


       values HASH
               Returns a normal array consisting of all the
               values of the named hash.  (In a scalar context,
               returns the number of values.)  The values are
               returned in an apparently random order, but it is
               the same order as either the keys() or each()
               function would produce on the same hash.  As a
               side effect, it resets HASH's iterator.  See also
               keys(), each(), and sort().

       vec EXPR,OFFSET,BITS
               Treats the string in EXPR as a vector of unsigned
               integers, and returns the value of the bit field
               specified by OFFSET.  BITS specifies the number of
               bits that are reserved for each entry in the bit
               vector.  This must be a power of two from 1 to 32.
               vec() may also be assigned to, in which case
               parentheses are needed to give the expression the
               correct precedence as in

                   vec($image, $max_x * $x + $y, 8) = 3;

               Vectors created with vec() can also be manipulated
               with the logical operators |, &, and ^, which will
               assume a bit vector operation is desired when both
               operands are strings.

               To transform a bit vector into a string or array
               of 0's and 1's, use these:


                   $bits = unpack("b*", $vector);
                   @bits = split(//, unpack("b*", $vector));

               If you know the exact length in bits, it can be
               used in place of the *.

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

       waitpid PID,FLAGS
               Waits for a particular child process to terminate
               and returns the pid of the deceased process, or -1
               if there is no such child process.  The status is
               returned in $?.  If you say

                   use POSIX ":sys_wait_h";
                   ...
                   waitpid(-1,&WNOHANG);

               then you can do a non-blocking wait for any
               process.  Non-blocking wait is available on
               machines supporting either the waitpid(2) or
               wait4(2) system calls.  However, waiting for a
               particular pid with FLAGS of 0 is implemented
               everywhere.  (Perl emulates the system call by
               remembering the status values of processes that
               have exited but have not been harvested by the
               Perl script yet.)

       wantarray
               Returns TRUE if the context of the currently
               executing subroutine is looking for a list value.
               Returns FALSE if the context is looking for a
               scalar.  Returns the undefined value if the
               context is looking for no value (void context).

                   return unless defined wantarray;    # don't bother doing more
                   my @a = complex_calculation();
                   return wantarray ? @a : "@a";


       warn LIST
               Produces a message on STDERR just like die(), but
               doesn't exit or throw an exception.

               No message is printed if there is a $SIG{__WARN__}
               handler installed.  It is the handler's
               responsibility to deal with the message as it sees
               fit (like, for instance, converting it into a
               die()).  Most handlers must therefore make
               arrangements to actually display the warnings that
               they are not prepared to deal with, by calling
               warn() again in the handler.  Note that this is
               quite safe and will not produce an endless loop,
               since __WARN__ hooks are not called from inside
               one.

               You will find this behavior is slightly different
               from that of $SIG{__DIE__} handlers (which don't
               suppress the error text, but can instead call
               die() again to change it).

               Using a __WARN__ handler provides a powerful way
               to silence all warnings (even the so-called
               mandatory ones).  An example:

                   # wipe out *all* compile-time warnings
                   BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } }
                   my $foo = 10;
                   my $foo = 20;          # no warning about duplicate my $foo,
                                          # but hey, you asked for it!
                   # no compile-time or run-time warnings before here
                   $DOWARN = 1;

                   # run-time warnings enabled after here
                   warn "\$foo is alive and $foo!";     # does show up

               See the perlvar manpage for details on setting
               %SIG entries, and for more examples.

       write FILEHANDLE

       write EXPR

       write   Writes a formatted record (possibly multi-line) to
               the specified file, using the format associated
               with that file.  By default the format for a file
               is the one having the same name as the filehandle,
               but the format for the current output channel (see
               the select() function) may be set explicitly by
               assigning the name of the format to the $~
               variable.

               Top of form processing is handled automatically:
               if there is insufficient room on the current page
               for the formatted record, the page is advanced by
               writing a form feed, a special top-of-page format
               is used to format the new page header, and then
               the record is written.  By default the top-of-page
               format is the name of the filehandle with "_TOP"
               appended, but it may be dynamically set to the
               format of your choice by assigning the name to the
               $^ variable while the filehandle is selected.  The
               number of lines remaining on the current page is
               in variable $-, which can be set to 0 to force a
               new page.
               If FILEHANDLE is unspecified, output goes to the
               current default output channel, which starts out
               as STDOUT but may be changed by the select
               operator.  If the FILEHANDLE is an EXPR, then the
               expression is evaluated and the resulting string
               is used to look up the name of the FILEHANDLE at
               run time.  For more on formats, see the perlform
               manpage.

               Note that write is NOT the opposite of read.
               Unfortunately.

       y///    The translation operator.  Same as tr///.  See the
               perlop manpage.
Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services
Copyright (C) 1998 Hurricane Electric. All Rights Reserved.