perlfunc

PERLFUNC(1)            Perl Programmers Reference Guide            PERLFUNC(1)



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 important rule: There is no rule that relates
       the behavior of an expression in list context to its behavior in scalar
       context, or vice versa.  It might do two totally different things.
       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 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.

       An named array in scalar context is quite different from what would at
       first glance appear to be a list in scalar context.  You can't get a
       list like (1,2,3) into being in scalar context, because the compiler
       knows the context at compile time.  It would generate the scalar comma
       operator there, not the list construction version of the comma.  That
       means it was never a list to start with.

       In general, functions in Perl that serve as wrappers for system calls
       of the same name (like chown(2), fork(2), closedir(2), etc.) all return
       true when they succeed and undef otherwise, as is usually mentioned in
       the descriptions below.  This is different from the C interfaces, which
       return -1 on failure.  Exceptions to this rule are wait(), waitpid(),
       and syscall().  System calls also set the special $!  variable on
       failure.  Other functions do not, except accidentally.

       Perl Functions by Category

       Here are Perl's functions (including things that look like functions,
       like some 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, qr//

       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), or Filehandle is a pipe.
                   -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, such as AFS
               access control lists.  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
               strange 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, modulo the caveats
               given in the section on Signals in the perlipc manpage.

                   eval {
                       local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
                       alarm $timeout;
                       $nread = sysread SOCKET, $buffer, $size;
                       alarm 0;
                   };
                   if ($@) {
                       die unless $@ eq "alarm\n";   # propagate unexpected errors
                       # 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, MacOS,
               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 perltoot manpage and the perlobj
               manpage for more about the blessing (and blessings) of objects.

       caller EXPR

       caller  Returns the context of the current subroutine call.  In 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 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.

               Be aware that the optimizer might have optimized call frames
               away before caller() had a chance to get the information. That
               means that caller(N) might not return information about the
               call frame you expect it do, for N > 1. In particular,
               @DB::args might have information from the previous time
               caller() was called.

       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 documentif 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 = glob($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 like 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
               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 a chroot() to $_.

       close FILEHANDLE

       close   Closes the file or pipe associated with the file handle,
               returning TRUE only if stdio successfully flushes buffers and
               closes the system file descriptor. Closes the currently
               selected filehandle if the argument is omitted.

               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.

               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 only problem was that the program exited non-zero $!
               will be set to 0.)  Also, closing a pipe waits 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 exit status value of the command into $?.

               Example:

                   open(OUTPUT, '⎪sort >foo')  # pipe to sort
                       or die "Can't start sort: $!";
                   #...                        # print stuff to output
                   close OUTPUT                # wait for sort to finish
                       or warn $! ? "Error closing sort pipe: $!"
                                  : "Exit status $? from sort";
                   open(INPUT, 'foo')          # get sort's results
                       or die "Can't open 'foo' for input: $!";

               FILEHANDLE may be an expression whose value can be used as an
               indirect filehandle, usually the real filehandle name.

       closedir DIRHANDLE
               Closes a directory opened by opendir() and returns the success
               of that system call.

               DIRHANDLE may be an expression whose value can be used as an
               indirect dirhandle, usually the real dirhandle name.

       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).

               last, next, or redo may appear within a continue block. last
               and redo will behave as if they had been executed within the
               main block. So will next, but since it will execute a continue
               block, it may be more entertaining.

                   while (EXPR) {
                       ### redo always comes here
                       do_something;
                   } continue {
                       ### next always comes here
                       do_something_else;
                       # then back the top to re-check EXPR
                   }
                   ### last always comes here

               Omitting the continue section is semantically equivalent to
               using an empty one, logically enough. In that case, next goes
               directly back to check the condition at the top of the loop.

       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 whoever 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(3), 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
               lists 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, by saying defined &func without parentheses.  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 documentfor 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 shouldn'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.  The normal way to free up space used by an
               aggregate is to assign the empty list.

               This counterintuitive behavior 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 just assigning the empty
               list, or using undef().)  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 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().

               If LIST is empty and $@ already contains a value (typically
               from a previous eval) that value is reused after appending
               "\t...propagated".  This is useful for propagating exceptions:

                   eval { ... };
                   die unless $@ =~ /Expected exception/;

               If $@ is empty then the string "Died" is used.

               You can arrange for a callback to be run 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 section on $SIG{expr} in the perlvar manpage
               for details on setting %SIG entries, and the section on eval
               BLOCK for some examples.

               Note that the $SIG{__DIE__} hook is called even inside eval()ed
               blocks/strings.  If one wants the hook to do nothing in such
               situations, put

                       die @_ if $^S;

               as the first line of the handler (see the section on $^S in the
               perlvar manpage).

       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

                   scalar eval `cat stat.pl`;

               except that it's more efficient and 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 is also different in how code evaluated
               with do FILENAME doesn't see lexicals in the enclosing scope
               like eval STRING does.  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.

               If do cannot read the file, it returns undef and sets $! to the
               error.    If do can read the file but cannot compile it, it
               returns undef and sets an error message in $@.   If the file is
               successfully compiled, do returns the value of the last
               expression evaluated.

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

               You might like to use do to read in a program configuration
               file.  Manual error checking can be done this way:

                   # read in config files: system first, then user
                   for $file ("/share/prog/defaults.rc",
                              "$ENV{HOME}/.someprogrc") {
                       unless ($return = do $file) {
                           warn "couldn't parse $file: $@" if $@;
                           warn "couldn't do $file: $!"    unless defined $return;
                           warn "couldn't run $file"       unless $return;
                       }
                   }


       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');

               This operator is largely obsolete, partly because it's very
               hard to convert a core file into an executable, and because the
               real perl-to-C compiler has superseded it.

       each HASH
               When called in list context, returns a 2-element list
               consisting of the key and value for the next element of a hash,
               so that you can iterate over it.  When called in 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 in
               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.  (Note that
               this function actually reads a character and then ungetc()s it,
               so isn't 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.
               Using eof() with empty parentheses is very different.  It
               indicates 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 (<>) {
                       next if /^\s*#/;        # skip comments
                       print "$.\t$_";
                   } continue {
                       close ARGV  if eof;     # Not eof()!
                   }

                   # insert dashes just before last line of last file
                   while (<>) {
                       if (eof()) {            # check for end of current file
                           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 false values when they run
               out of data, or if there was an error.

       eval EXPR

       eval BLOCK
               In the first form, the return value of EXPR is parsed and
               executed as if it were a little Perl program.  The value of the
               expression (which is itself determined within scalar context)
               is first parsed, and if there weren't any errors, executed in
               the context of the current Perl program, so that any variable
               settings or subroutine and format definitions remain
               afterwards.  Note that the value is parsed every time the eval
               executes.  If EXPR is omitted, evaluates $_.  This form is
               typically used to delay parsing and subsequent execution of the
               text of EXPR until run time.

               In the second form, the code within the BLOCK is parsed only
               once--at the same time the code surrounding the eval itself was
               parsed--and executed within the context of the current Perl
               program.  This form is typically used to trap exceptions more
               efficiently than the first (see below), while also providing
               the benefit of checking the code within BLOCK at compile time.

               The final semicolon, if any, may be omitted from the value of
               EXPR or within the BLOCK.

               In both forms, the value returned is the value of the last
               expression evaluated inside the mini-program; a return
               statement may be also used, just as with subroutines.  The
               expression providing the return value is evaluated in void,
               scalar, or list context, depending on the context of the eval
               itself.  See the wantarray entry elsewhere in this documentfor
               more on how the evaluation context can be determined.

               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.  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 the warn entry elsewhere in this document 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 = };                 # WRONG

                   # 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 lives here" };
                      print $@ if $@;                # prints "bar lives 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

       exec PROGRAM LIST
               The exec() function executes a system command AND NEVER RETURNS
               - use system() instead of exec() if you want it to return. It
               fails and returns FALSE only if the command does not exist and
               it is executed directly instead of via your system's command
               shell (see below).

               Since it's a common mistake to use exec() instead of system(),
               Perl warns you if there is a following statement which isn't
               die(), warn(), or exit() (if -w is set  -  but you always do
               that).   If you really want to follow an exec() with some other
               statement, you can use one of these styles to avoid the
               warning:

                   exec ('foo')   or print STDERR "couldn't exec foo: $!";
                   { exec ('foo') }; print STDERR "couldn't exec foo: $!";

               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 or an
               array with one element in it, the argument is checked for shell
               metacharacters, and if there are any, the entire argument is
               passed to the system's command shell for parsing (this is
               /bin/sh -c on Unix platforms, but varies on other platforms).
               If there are no shell metacharacters in the argument, it 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

               When the arguments get executed via the system shell, results
               will be subject to its quirks and capabilities.  See the
               section on `STRING` in the perlop manpage for details.

               Using an indirect object with exec() or system() is also more
               secure.  This usage forces interpretation of the arguments as a
               multivalued list, even if the list had just one argument.  That
               way you're safe from the shell expanding wildcards or splitting
               up words with whitespace in them.

                   @args = ( "echo surprise" );

                   system @args;               # subject to shell escapes
                                               # if @args == 1
                   system { $args[0] } @args;  # safe even with one-arg list

               The first version, the one without the indirect object, ran the
               echo program, passing it "surprise" an argument.  The second
               version didn't--it tried to run a program literally called
               "echo surprise", didn't find it, and set $? to a non-zero value
               indicating failure.

               Note that exec() will not call your END blocks, nor will it
               call any DESTROY methods in your objects.

       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->{"A"}{"B"}{$key}) { ... }

               Although the last element will not spring into existence just
               because its existence was tested, intervening ones will.  Thus
               $ref->{"A"} $ref->{"B"} will spring into existence due to the
               existence test for a $key element.  This autovivification may
               be fixed in a later release.

       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().

               All END{} blocks are run at exit time.  See the perlsub manpage
               for details.

       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 constant definitions.  Argument
               processing and value return works just like ioctl() below.  For
               example:

                   use Fcntl;
                   fcntl($filehandle, F_GETFL, $packed_return_buffer)
                       or die "can't fcntl F_GETFL: $!";

               You don't have to check for defined() on the return from
               fnctl().  Like ioctl(), it maps a 0 return from the system call
               into "0 but true" in Perl.  This string is true in boolean
               context and 0 in numeric context.  It is also exempt from the
               normal -w warnings on improper numeric conversions.

               Note that fcntl() will produce a fatal error if used on a
               machine that doesn't implement fcntl(2).

       fileno FILEHANDLE
               Returns the file descriptor for a filehandle.  This is useful
               for constructing bitmaps for select() and low-level POSIX tty-
               handling operations.  If FILEHANDLE is an expression, the value
               is taken as an indirect filehandle, generally its name.

               You can use this to find out whether two handles refer to the
               same underlying descriptor:

                   if (fileno(THIS) == fileno(THAT)) {
                       print "THIS and THAT are dups\n";
                   }


       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.

               On many platforms (including most versions or clones of Unix),
               locks established by flock() are merely advisory.  Such
               discretionary locks are more flexible, but offer fewer
               guarantees.  This means that files locked with flock() may be
               modified by programs that do not also use flock().  Windows NT
               and OS/2 are among the platforms which enforce mandatory
               locking.  See your local documentation for details.

               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, 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, then 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 for 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 the undefined value at end of file, or if there
               was an error.  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 purporting 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
               Implements the C library function of the same name, which on
               most systems 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.  In list context, the return values from
               the various get routines are as follows:

                   ($name,$passwd,$uid,$gid,
                      $quota,$comment,$gcos,$dir,$shell,$expire) = 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.)

               In 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);
                   $name  = getpwuid($num);
                   $name  = getpwent();
                   $gid   = getgrnam($name);
                   $name  = getgrgid($num;
                   $name  = getgrent();
                   #etc.

               In getpw*() the fields $quota, $comment, and $expire are
               special cases in the sense that in many systems they are
               unsupported.  If the $quota is unsupported, it is an empty
               scalar.  If it is supported, it usually encodes the disk quota.
               If the $comment field is unsupported, it is an empty scalar.
               If it is supported it usually encodes some administrative
               comment about the user.  In some systems the $quota field may
               be $change or $age, fields that have to do with password aging.
               In some systems the $comment field may be $class.  The $expire
               field, if present, encodes the expiration period of the account
               or the password.  For the availability and the exact meaning of
               these fields in your system, please consult your getpwnam(3)
               documentation and your pwd.h file.  You can also find out from
               within Perl which meaning your $quota and $comment fields have
               and whether you have the $expire field by using the Config
               module and the values d_pwquota, d_pwage, d_pwchange,
               d_pwcomment, and d_pwexpire.

               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]);

               If you get tired of remembering which element of the return
               list contains which return value, by-name interfaces are also
               provided in modules: File::stat, Net::hostent, Net::netent,
               Net::protoent, Net::servent, Time::gmtime, Time::localtime, and
               User::grent.  These override the normal built-in, replacing
               them with versions that return objects with the appropriate
               names for each field.  For example:

                  use File::stat;
                  use User::pwent;
                  $is_his = (stat($filename)->uid == pwent($whoever)->uid);

               Even though it looks like they're the same method calls (uid),
               they aren't, because a File::stat object is different from a
               User::pwent object.

       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 undef if there is an
               error.

       glob EXPR

       glob    Returns the value of EXPR with filename expansions such as the
               standard Unix shell /bin/sh 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, that is, $year is 123
               in year 2023, not simply the last two digits of the year.

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

               In 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.

               This scalar value is not locale dependent, see the perllocale
               manpage, but instead a Perl builtin.  Also see the Time::Local
               module, and the strftime(3) and mktime(3) function available
               via the POSIX module.  To get somewhat similar but locale
               dependent date strings, set up your locale environment
               variables appropriately (please see the perllocale manpage) and
               try for example:

                   use POSIX qw(strftime);
                       $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;

               Note that the %a and %b, the short forms of the day of the week
               and the month of the year, may not necessarily be three
               characters wide.

       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 a for loop's index
               variable aliases the list elements.  That is, modifying an
               element of a list returned by grep (for example, in a foreach,
               map() or another grep()) actually modifies the element in the
               original list.

               See also the map entry elsewhere in this documentfor an array
               composed of the results of the BLOCK or EXPR.

       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 just 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 documentthe 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
               $_.  You should not use this for rounding, because it truncates
               towards 0, and because machine representations of floating
               point numbers can sometimes produce counterintuitive results.
               Usually sprintf() or printf(), or the POSIX::floor or
               POSIX::ceil functions, would serve you better.

       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 that 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;

               The special string "0 but true" is excempt from -w complaints
               about improper numeric conversions.

       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 elsewhere in this document.

       keys HASH
               Returns a list 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--256
               of them, in fact, since it rounds up to the next power of two.
               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
                       #...
                   }

               See also the continue entry elsewhere in this documentfor an
               illustration of how last, next, and redo work.

       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 bytes 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
               TRUE for success, FALSE 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, file, or eval.  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.

               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, and not simply the last two digits of the year.

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

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

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

               This scalar value is not locale dependent, see the perllocale
               manpage, but instead a Perl builtin.  Also see the Time::Local
               module, and the strftime(3) and mktime(3) function available
               via the POSIX module.  To get somewhat similar but locale
               dependent date strings, set up your locale environment
               variables appropriately (please see the perllocale manpage) and
               try for example:

                   use POSIX qw(strftime);
                       $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;

               Note that the %a and %b, the short forms of the day of the week
               and the month of the year, may not necessarily be three
               characters wide.

       log EXPR

       log     Returns the natural 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 (including setting
               the special _ filehandle) 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($_)} = $_;
                   }

               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.  See also the grep entry elsewhere in
               this documentfor an array composed of those items of the
               original list for which the BLOCK or EXPR evaluates to true.

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

       msgctl ID,CMD,ARG
               Calls the System V IPC function msgctl(2).  You'll probably
               have to say

                   use IPC::SysV;

               first to get the correct constant definitions.  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.  See also IPC::SysV and
               IPC::Semaphore::Msg documentation.

       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.  See
               also IPC::SysV and IPC::SysV::Msg documentation.

       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.  See
               also IPC::SysV and IPC::SysV::Msg documentation.

       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.  See also IPC::SysV
               and IPC::SysV::Msg documentation.

       my EXPR A my() declares the listed variables to be local (lexically) to
               the enclosing block, file, or eval().  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.

               See also the continue entry elsewhere in this documentfor an
               illustration of how last, next, and redo work.

       no Module LIST
               See the the use entry elsewhere in this documentfunction, 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, being created if necessary. If
               the filename begins with '>>', the file is opened for
               appending, again being created if necessary.  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.  You can't usually use either read-write mode
               for updating textfiles, since they have variable length
               records.  See the -i switch in the perlrun manpage for a better
               approach.

               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.  (You are not allowed to 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 documentfor 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, MacOS, and Plan9, which delimit lines with a
               single character, and which encode that character in C as "\n",
               do not need binmode().  The rest need it.

               When opening a file, it's usually a bad idea to continue normal
               execution if the request failed, so open() is frequently used
               in connection with die(). Even if die() won't do what you want
               (say, in a CGI script, where you want to make a nicely
               formatted error message (but there are modules that can help
               with that problem)) you should always check the return value
               from opening a file. The infrequent exception is when working
               with an unopened filehandle is actually what you want to do.

               Examples:

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

                   open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
                   # if the open fails, output is discarded

                   open(DBASE, '+<dbase.mine')             # open for update
                       or die "Can't open 'dbase.mine' for update: $!";

                   open(ARTICLE, "caesar <$article ⎪")     # decrypt article
                       or die "Can't start caesar: $!";

                   open(EXTRACT, "⎪sort >/tmp/Tmp$$")      # $$ is our process id
                       or die "Can't start sort: $!";

                   # process argument list of files along with any includes

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

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

                       local $_;
                       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) 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(OLDOUT, ">&STDOUT");
                   open(OLDERR, ">&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, ">&OLDOUT");
                   open(STDERR, ">&OLDERR");

                   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 that may do a fork, any 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 $?.

               The filename passed to open will have leading and trailing
               whitespace deleted, and the normal redirection characters
               honored.  This property, known as "magic open", can often be
               used to good effect.  A user could specify a filename of "rsh
               cat file ⎪", or you could change certain filenames as needed:

                   $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1⎪/;
                   open(FH, $filename) or die "Can't open $filename: $!";

               However, to open a file with arbitrary weird characters in it,
               it's necessary to protect any leading and trailing whitespace:

                   $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, which
               involves no such magic.  This is another way to protect your
               filenames from interpretation.  For example:

                   use IO::Handle;
                   sysopen(HANDLE, $path, O_RDWR⎪O_CREAT⎪O_EXCL)
                       or die "sysopen $path: $!";
                   $oldfh = select(HANDLE); $⎪ = 1; select($oldfh);
                   print HANDLE "stuff $$\n");
                   seek(HANDLE, 0, 0);
                   print "File contains: ", <HANDLE>;

               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 that 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.
                   }

               See the seek() entry elsewhere in this documentfor 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 giving 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"
               type packs a pointer to a null- terminated string.  You are
               responsible for ensuring the string is not a temporary value
               (which can potentially get deallocated before you get around to
               using the packed result).  The "P" packs a pointer to a
               structure of the size indicated by the length. A NULL pointer
               is created if the corresponding value for "p" or "P" is undef.
               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

       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 merely influences 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.

               If NAMESPACE is omitted, then there is no current package, and
               all identifiers must be fully qualified or lexicals.  This is
               stricter than use strict, since it also extends to function
               names.

               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 the currently selected output channel.  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 list context, and any
               subroutine that you call will have one or more of its
               expressions evaluated in 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), except
               that $\ (the output record separator) is not appended.  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.

               If FUNCTION is a string starting with CORE::, the rest is taken
               as a name for Perl builtin.  If builtin is not overridable
               (such as qw//) or its arguments cannot be expressed by a
               prototype (such as system()) - in other words, the builtin does
               not behave like a Perl function - returns undef.  Otherwise,
               the string describing the equivalent prototype is returned.

       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/

       qr/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, 0 at end of file, 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(3) call.  To get a true
               read(2) system call, see sysread().

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


       readline EXPR
               Reads from the filehandle whose typeglob is contained in EXPR.
               In scalar context, a single line is read and returned.  In list
               context, reads until end-of-file is reached and returns a list
               of lines (however you've defined lines with $/ or
               $INPUT_RECORD_SEPARATOR).  This is the internal function
               implementing the <EXPR> operator, but you can use it directly.
               The <EXPR> operator is discussed in more detail in the section
               on I/O Operators in the perlop manpage.

                   $line = <STDIN>;
                   $line = readline(*STDIN);           # same thing


       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 $_.

       readpipe EXPR
               EXPR is executed as a system command.  The collected standard
               output of the command is returned.  In scalar context, it comes
               back as a single (potentially multi-line) string.  In list
               context, returns a list of lines (however you've defined lines
               with $/ or $INPUT_RECORD_SEPARATOR).  This is the internal
               function implementing the qx/EXPR/ operator, but you can use it
               directly.  The qx/EXPR/ operator is discussed in more detail in
               the section on I/O Operators in the perlop manpage.

       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
               return 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;
                   }

               See also the continue entry elsewhere in this documentfor an
               illustration of how last, next, and redo work.

       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 {
                       my($filename) = @_;
                       return 1 if $INC{$filename};
                       my($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;
                       return $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.

               In other words, if you try this:

                       require Foo::Bar;    # a splendid bareword

               The require function will actually look for the "Foo/Bar.pm"
               file in the directories specified in the @INC array.

               But if you try this:

                       $class = 'Foo::Bar';
                       require $class;      # $class is not a bareword
                   #or
                       require "Foo::Bar";  # not a bareword because of the ""

               The require function will look for the "Foo::Bar" file in the
               @INC array and will complain about not finding "Foo::Bar"
               there. In this case you can do:

                       eval "require $class";

               For a yet-more-powerful import facility, see the use entry
               elsewhere in this document and 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 @INC arrays and your %ENV hash.  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
               given in EXPR.  Evaluation of EXPR may be in 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
               list context, an undefined value in 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 list context, returns a list value consisting of the
               elements of LIST in the opposite order.  In 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 that directory
               is empty.  If it succeeds it returns TRUE, otherwise it returns
               FALSE and sets $! (errno).  If FILENAME is omitted, uses $_.

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

       scalar EXPR
               Forces EXPR to be interpreted in 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 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 {
                       my(@fhlist) = split(' ',$_[0]);
                       my($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 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: One should not attempt to mix buffered I/O (like
               read() or <FH>) with select(), except as permitted by POSIX,
               and even then only on POSIX systems.  You have to use sysread()
               instead.

       semctl ID,SEMNUM,CMD,ARG
               Calls the System V IPC function semctl().  You'll probably have
               to say

                   use IPC::SysV;

               first to get the correct constant definitions.  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.  See also
               IPC::SysV and IPC::Semaphore documentation.

       semget KEY,NSEMS,FLAGS
               Calls the System V IPC function semget.  Returns the semaphore
               id, or the undefined value if there is an error.  See also
               IPC::SysV and IPC::SysV::Semaphore documentation.

       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.  See also IPC::SysV
               and IPC::SysV::Semaphore documentation.

       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 @_ array within the lexical scope
               of subroutines and formats, and the @ARGV array at file scopes
               or within the lexical scopes established by the eval '', BEGIN
               {}, END {}, and INIT {} constructs.  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.  You'll probably have
               to say

                   use IPC::SysV;

               first to get the correct constant definitions.  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.  See also IPC::SysV documentation.

       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.
               See also IPC::SysV documentation.

       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 that 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.  See also IPC::SysV
               documentation.

       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.

                   shutdown(SOCKET, 0);    # I/we have stopped reading data
                   shutdown(SOCKET, 1);    # I/we have stopped writing data
                   shutdown(SOCKET, 2);    # I/we have stopped using this socket

               This is useful with sockets when you want to tell the other
               side you're done writing but not done reading, or vice versa.
               It's also a more insistent form of close because it also
               disables the filedescriptor in any forked copies in other
               processes.

       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 if the process receives a signal such
               as 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.  They may
               appear to sleep longer than that, however, because your process
               might not be scheduled right away in a busy multitasking
               system.

               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 documentabove.

               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.

               Some systems defined pipe() in terms of socketpair(), in which
               a call to pipe(Rdr, Wtr) is essentially:

                   use Socket;
                   socketpair(Rdr, Wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC);
                   shutdown(Rdr, 1);        # no more writing for reader
                   shutdown(Wtr, 0);        # no more reading for writer

               See the perlipc manpage for an example of socketpair use.

       sort SUBNAME LIST

       sort BLOCK LIST

       sort LIST
               Sorts the LIST and returns the sorted list value.  If SUBNAME
               or BLOCK is omitted, sort()s 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
               (unsubscripted), in which case the value provides the name of
               (or a reference to) the actual 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 results are
               not well-defined.

       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.  In
               list context, returns the elements removed from the array.  In
               scalar context, returns the last element removed, or undef if
               no elements are removed.  The array grows or shrinks as
               necessary.  If OFFSET is negative then it start that far from
               the end of the array.  If LENGTH is omitted, removes everything
               from OFFSET onward.  If LENGTH is negative, leave that many
               elements off the end of the array.  The following equivalences
               hold (assuming $[ == 0):

                   push(@a,$x,$y)      splice(@a,@a,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
                       my(@a) = splice(@_,0,shift);
                       my(@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.  By
               default, empty leading fields are preserved, and empty trailing
               ones are deleted.

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

               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 positive, splits into no more than
               that many fields (though it may split into fewer).  If LIMIT is
               unspecified or zero, 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*?):\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 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 non-zero octal with "0", non-zero 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 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 list 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.)

               In scalar context, stat() returns a boolean value indicating
               success or failure, and, if successful, sets the information
               associated with the special filehandle _.

       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 that 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,REPLACEMENT

       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 (or more precisely, less
               than $[), 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.

               If you specify a substring that is partly outside the string,
               the part within the string is returned.    If the substring is
               totally outside the string a warning is produced.

               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().

               An alternative to using substr() as an lvalue is to specify the
               replacement string as the 4th argument.  This allows you to
               replace parts of the EXPR and return what was there before in
               one operation.

       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("",""); 1 };


       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.  You can't use a string literal
               (or other read-only string) as an argument to syscall() because
               Perl has to assume that any string pointer might be written
               through.  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.  This
               emulates the syswrite() function (or vice versa):

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

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

               Syscall returns whatever value returned by the system call it
               calls.  If the system call fails, syscall() returns -1 and sets
               $! (errno).  Note that some system calls can legitimately
               return -1.  The proper way to handle such calls is to assign
               $!=0; before the call and check the value of $! if syscall
               returns -1.

               There's a problem with syscall(&SYS_pipe): it returns the file
               number of the read end of the pipe it creates.  There is no way
               to retrieve the file number of the other end.  You can avoid
               this problem by using pipe() instead.

       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.  For historical reasons, some values work on almost
               every system supported by perl: zero means read-only, one means
               write-only, and two means read/write.  We know that these
               values do not work under OS/390 Unix and on the Macintosh; you
               probably don't want to use them in new code.

               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 you omit the PERMS argument to
               sysopen(), Perl uses the octal value 0666.  These permission
               values need to be in octal, and are modified by your process's
               current umask.  The umask value is a number representing
               disabled permissions bits--if your umask were 027 (group can't
               write; others can't read, write, or execute), then passing
               sysopen() 0666 would create a file with mode 0640 (0666 &~ 027
               is 0640).

               If you find this umask() talk confusing, here's some advice:
               supply a creation mode of 0666 for regular files and one of
               0777 for directories (in mkdir()) and executable files.  This
               gives users the freedom of choice: if they want protected
               files, they might choose process umasks of 022, 027, or even
               the particularly antisocial mask of 077.  Programs should
               rarely if ever make policy decisions better left to the user.
               The exception to this is when writing files that should be kept
               private: mail files, web browser cookies, .rhosts files, and so
               on.  In short, seldom if ever use 0644 as argument to sysopen()
               because that takes away the user's option to have a more
               permissive umask.  Better to omit it.

               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 because
               stdio usually buffers data.  Returns the number of bytes
               actually read, 0 at end of file, 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

       system PROGRAM 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.  If there is more than
               one argument in LIST, or if LIST is an array with more than one
               value, starts the program given by the first element of the
               list with arguments given by the rest of the list.  If there is
               only one scalar argument, the argument is checked for shell
               metacharacters, and if there are any, the entire argument is
               passed to the system's command shell for parsing (this is
               /bin/sh -c on Unix platforms, but varies on other platforms).
               If there are no shell metacharacters in the argument, it is
               split into words and passed directly to execvp(), which is more
               efficient.

               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.

               Like exec(), system() allows you to lie to a program about its
               name if you use the "system PROGRAM LIST" syntax.  Again, see
               the exec entry elsewhere in this document.

               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: $?"

               You can check all the failure possibilities by inspecting $?
               like this:

                   $exit_value  = $? >> 8;
                   $signal_num  = $? & 127;
                   $dumped_core = $? & 128;

               When the arguments get executed via the system shell, results
               and return codes will be subject to its quirks and
               capabilities.  See the section on `STRING` in the perlop
               manpage and the exec entry elsewhere in this documentfor
               details.

       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 because stdio usually buffers data.  Returns the
               number of bytes actually written, or undef if there was an
               error.  If the LENGTH is greater than the available data in the
               SCALAR after the OFFSET, 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.  In the case the SCALAR is empty you can use
               OFFSET but only zero offset.

       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
               lists 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.

               For further details see the perltie manpage, the section on
               tied VARIABLE.

       tied VARIABLE
               Returns a reference to the object underlying VARIABLE (the same
               value that was originally returned by the tie() call that 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 list giving the user and system times,
               in seconds, for this process and the children of this process.

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


       tr///   The transliteration 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.  Returns TRUE if successful, the
               undefined value otherwise.

       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.

               If umask(2) is not implemented on your system and you are
               trying to restrict access for yourself (i.e., (EXPR & 0700) >
               0), produces a fatal error at run time.  If umask(2) is not
               implemented and you are not trying to restrict access for
               yourself, returns undef.

               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 documentif 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 array (using "@"), a hash (using "%"), a
               subroutine (using "&"), or a typeglob (using "<*>").  (Saying
               undef $hash{$key} will probably not do what you expect on most
               predefined variables or DBM list values, so don't do that; see
               the delete manpage.)  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;
                   undef *xyz;       # destroys $xyz, @xyz, %xyz, &xyz, etc.
                   return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
                   select undef, undef, undef, 0.25;
                   ($a, $b, undef, $c) = &foo;       # Ignore third value returned

               Note that this is a unary operator, not a list operator.

       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 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 {
                       my($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 that 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);

               Some of these these pseudo-modules import semantics into the
               current block scope (like strict or integer, 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.
               This code has the same effect as the "touch" command if the
               files already exist:

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


       values HASH
               Returns a list 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.

               The following code will build up an ASCII string saying
               'PerlPerlPerl'.  The comments show the string after each step.
               Note that this code works in the same way on big-endian or
               little-endian machines.

                   my $foo = '';
                   vec($foo,  0, 32) = 0x5065726C;     # 'Perl'
                   vec($foo,  2, 16) = 0x5065;         # 'PerlPe'
                   vec($foo,  3, 16) = 0x726C;         # 'PerlPerl'
                   vec($foo,  8,  8) = 0x50;           # 'PerlPerlP'
                   vec($foo,  9,  8) = 0x65;           # 'PerlPerlPe'
                   vec($foo, 20,  4) = 2;              # 'PerlPerlPe'   . "\x02"
                   vec($foo, 21,  4) = 7;              # 'PerlPerlPer'
                                                       # 'r' is "\x72"
                   vec($foo, 45,  2) = 3;              # 'PerlPerlPer'  . "\x0c"
                   vec($foo, 93,  1) = 1;              # 'PerlPerlPer'  . "\x2c"
                   vec($foo, 94,  1) = 1;              # 'PerlPerlPerl'
                                                       # 'l' is "\x6c"

               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.)

               See the perlipc manpage for other examples.

       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.

               If LIST is empty and $@ already contains a value (typically
               from a previous eval) that value is used after appending
               "\t...caught" to $@. This is useful for staying almost, but not
               entirely similar to die().

               If $@ is empty then the string "Warning: Something's wrong" is
               used.

               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 FILEHANDLE, 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 transliteration operator.  Same as tr///.  See the perlop
               manpage.




















































































































































































































































































































































3rd Berkeley Distribution    perl 5.005, patch 02                  PERLFUNC(1)