


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
       or 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 such list
       argument.)  For instance, splice() has three scalar
       arguments followed by a list, whereas gethostbyname() has
       four scalar arguments.

       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.



29/Apr/1999            perl 5.005, patch 03                     1





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


       A few functions take no arguments at all, and therefore
       work as neither unary nor list operators.  These include
       such functions as time and endpwent.  For example,
       time+86_400 always means time() + 86_400.

       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 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///




29/Apr/1999            perl 5.005, patch 03                     2





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


       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




29/Apr/1999            perl 5.005, patch 03                     3





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


       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

       Portability

       Perl was born in Unix and can therefore access all common
       Unix system calls.  In non-Unix environments, the
       functionality of some Unix system calls may not be
       available, or details of the available functionality may
       differ slightly.  The Perl functions affected by this are:

       -X, binmode, chmod, chown, chroot, crypt, dbmclose,
       dbmopen, dump, endgrent, endhostent, endnetent,
       endprotoent, endpwent, endservent, exec, fcntl, flock,
       fork, getgrent, getgrgid, gethostent, getlogin,
       getnetbyaddr, getnetbyname, getnetent, getppid, getprgp,
       getpriority, getprotobynumber, getprotoent, getpwent,
       getpwnam, getpwuid, getservbyport, getservent, getsockopt,
       glob, ioctl, kill, link, lstat, msgctl, msgget, msgrcv,
       msgsnd, open, pipe, readlink, rename, select, semctl,



29/Apr/1999            perl 5.005, patch 03                     4





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


       semget, semop, setgrent, sethostent, setnetent, setpgrp,
       setpriority, setprotoent, setpwent, setservent,
       setsockopt, shmctl, shmget, shmread, shmwrite, socket,
       socketpair, stat, symlink, syscall, sysopen, system,
       times, truncate, umask, unlink, utime, wait, waitpid

       For more information about the portability of these
       functions, see the perlport manpage and other available
       platform-specific documentation.

       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.



29/Apr/1999            perl 5.005, patch 03                     5





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


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

               Example:

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

               The interpretation of the file permission
               operators -r, -R, -w, -W, -x, and -X is by default
               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 reasons may be for example network
               filesystem access controls, ACLs (access control
               lists), read-only filesystems, and unrecognized
               executable formats.

               Also note that, for the superuser on the local
               filesystems, the -r, -R, -w, and -W tests 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 their effective uid to something
               else.

               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



29/Apr/1999            perl 5.005, patch 03                     6





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


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



29/Apr/1999            perl 5.005, patch 03                     7





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


               For delays of finer granularity than one second,
               you may use Perl's four-arugment version of
               select() leaving the first three arguments
               undefined, or you might be able to use the
               syscall() interface to access setitimer(2) if your
               system supports it.  The Time::HiRes module from
               CPAN may also prove useful.

               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.



29/Apr/1999            perl 5.005, patch 03                     8





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


       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 many
               sytems, but 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 may need it.  If FILEHANDLE
               is an expression, the value is taken as the name
               of the filehandle.

               If the system does care about it, using it when
               you shouldn't is just as perilous as failing to
               use it when you should.  Fortunately for most of
               us, you can't go wrong using binmode() on systems
               that don't care about it, though.

       bless REF,CLASSNAME

       bless REF
               This function tells the thingy referenced by REF
               that it is now an object in the CLASSNAME package.
               If CLASSNAME is omitted, the current package is
               used.  Because a bless() is often the last thing
               in a constructor.  it returns the reference for
               convenience.  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.

               Consider always blessing objects in CLASSNAMEs
               that are mixed case.  Namespaces with all
               lowercase names are considered reserved for Perl
               pragmata.  Builtin types have all uppercase names,
               so to prevent confusion, you may wish to avoid
               such package names as well.  Make sure that
               CLASSNAME is a true value.

               See the section on Perl Modules in the perlmod
               manpage.

       caller EXPR

       caller  Returns the context of the current subroutine
               call.  In scalar context, returns the caller's



29/Apr/1999            perl 5.005, patch 03                     9





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


               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 the
               user's home directory.  Returns TRUE upon success,
               FALSE otherwise.  See the 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.



29/Apr/1999            perl 5.005, patch 03                    10





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


                   $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 safer version of the chop entry elsewhere in
               this documentremoves any trailing string 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:





29/Apr/1999            perl 5.005, patch 03                    11





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


                   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



29/Apr/1999            perl 5.005, patch 03                    12





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


               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.)  Closing a pipe also waits for the
               process executing on the pipe to complete, in case
               you want to look at the output of the pipe
               afterwards, and implicitly puts the exit status
               value of that 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



29/Apr/1999            perl 5.005, patch 03                    13





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


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



29/Apr/1999            perl 5.005, patch 03                    14





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


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

               When verifying an existing encrypted string you
               should use the encrypted text as the salt (like
               crypt($plain, $crypted) eq $crypted).  This allows
               your code to work with the standard crypt() and
               with more exotic implementations.  When choosing a
               new salt create a random two character string
               whose characters come from the set [./0-9A-Za-z]
               (like join '', ('.', '/', 0..9, 'A'..'Z',
               'a'..'z')[rand 64, rand 64]).

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

                   $pwd = (getpwuid($<))[1];

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

                   if (crypt($word, $pwd) 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 largely superseded by the



29/Apr/1999            perl 5.005, patch 03                    15





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


               untie() function.]

               Breaks the binding between a DBM file and a hash.

       dbmopen HASH,DBNAME,MODE
               [This function has been largely 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.

               You can control which DBM library you use by
               loading that library before you call dbmopen():

                   use DB_File;
                   dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db")
                       or die "Can't open netscape history file: $!";





29/Apr/1999            perl 5.005, patch 03                    16





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


       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 zero 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



29/Apr/1999            perl 5.005, patch 03                    17





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


               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 undefining it:




29/Apr/1999            perl 5.005, patch 03                    18





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


                   %hash = ();         # completely empty %hash
                   undef %hash;        # forget %hash every existed

               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.  Note that the "input line number" (also
               known as "chunk") is subject to whatever notion of
               "line" happens to be currently in effect, and is
               also available as the special variable $..  See
               the section on $/ in the perlvar manpage and the
               section on $. in the perlvar manpage.

               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(), warn(), and the Carp module.

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



29/Apr/1999            perl 5.005, patch 03                    19





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


               useful for propagating exceptions:

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

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

               die() can also be called with a reference
               argument.  If this happens to be trapped within an
               eval(), $@ contains the reference.  This behavior
               permits a more elaborate exception handling
               implementation using objects that maintain
               arbitary state about the nature of the exception.
               Such a scheme is sometimes preferable to matching
               particular string values of $@ using regular
               expressions.  Here's an example:

                   eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
                   if ($@) {
                       if (ref($@) && UNIVERSAL::isa($@,"Some::Module::Exception")) {
                           # handle Some::Module::Exception
                       }
                       else {
                           # handle all other possible exceptions
                       }
                   }

               Since perl will stringify uncaught exception
               messages before displaying them, you may want to
               overload stringification operations on such custom
               exception objects.  See the overload manpage for
               details about that.

               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 currently
               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).  Because this
               promotes action at a distance, this
               counterintuitive behavior may be fixed in a future



29/Apr/1999            perl 5.005, patch 03                    20





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


               release.

       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 BLOCK does not count as a loop, so the loop
               control statements next, last, or redo cannot be
               used to leave or restart the block.  See the
               perlsyn manpage for alternative strategies.

       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,
               searches the @INC libraries, and updates %INC if
               the file is found.  See the section on Predefined
               Names in the perlvar manpage for these variables.
               It also differs in that code evaluated with do
               FILENAME cannot see lexicals in the enclosing
               scope; 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.




29/Apr/1999            perl 5.005, patch 03                    21





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


               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

       dump    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



29/Apr/1999            perl 5.005, patch 03                    22





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


               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.  The actual random order is subject to
               change in future versions of perl, but it is
               guaranteed to be in the same order as either the
               keys() or values() function would produce on the
               same (unmodified) hash.

               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(), values() and sort().

       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



29/Apr/1999            perl 5.005, patch 03                    23





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


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



29/Apr/1999            perl 5.005, patch 03                    24





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


               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




29/Apr/1999            perl 5.005, patch 03                    25





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


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

               Due to the current arguably broken state of
               __DIE__ hooks, 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"
                   }

               Because this promotes action at a distance, this
               counterintuive behavior may be fixed in a future
               release.

               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,



29/Apr/1999            perl 5.005, patch 03                    26





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


               except that in this particular situation, you can
               just use symbolic references instead, as in case
               6.

               eval BLOCK does not count as a loop, so the loop
               control statements next, last, or redo cannot be
               used to leave or restart the block.

       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



29/Apr/1999            perl 5.005, patch 03                    27





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


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

                   exec @args;               # subject to shell escapes
                                               # if @args == 1
                   exec { $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



29/Apr/1999            perl 5.005, patch 03                    28





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


               lookup:

                   if (exists $ref->{A}->{B}->{$key})  { }
                   if (exists $hash{A}{B}{$key})       { }

               Although the last element will not spring into
               existence just because its existence was tested,
               intervening ones will.  Thus $ref->{"A"} and
               $ref->{"A"}->{"B"} will spring into existence due
               to the existence test for a $key element.  This
               happens anywhere the arrow operator is used,
               including even

                   undef $ref;
                   if (exists $ref->{"Some key"})      { }
                   print $ref;             # prints HASH(0x80d3d5c)

               This surprising autovivification in what does not
               at first--or even second--glance appear to be an
               lvalue context may be fixed in a future release.

       exit EXPR
               Evaluates EXPR and exits immediately with that
               value.    Example:

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

               See also die().  If EXPR is omitted, exits with 0
               status.  The only universally recognized values
               for EXPR are 0 for success and 1 for error; other
               values are subject to interpretation depending on
               the environment in which the Perl program is
               running.  For example, exiting 69 (EX_UNAVAILABLE)
               from a sendmail incoming-mail filter will cause
               the mailer to return the item undelivered, but
               that's not true everywhere.

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

               The exit() function does not always exit
               immediately. It calls any defined END routines
               first, but these END routines may not themselves
               abort the exit. Likewise any object destructors
               that need to be called are called before the real
               exit.  If this is a problem, you can call
               POSIX:_exit($status) to avoid END and destructor
               processing.  See the perlsub manpage for details.

       exp EXPR




29/Apr/1999            perl 5.005, patch 03                    29





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


       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).
               See the Fcntl module or your fcntl(2) manpage to
               learn what functions are available on your system.

       fileno FILEHANDLE
               Returns the file descriptor for a filehandle, or
               undefined if the filehandle is not open.  This is
               mainly 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



29/Apr/1999            perl 5.005, patch 03                    30





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


               entire files, not records.

               Two potentially non-obvious but traditional flock
               semantics are that it waits indefinitely until the
               lock is granted, and that its locks 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().  See the
               perlport manpage, your port's specific
               documentation, or your system-specific local
               manpages for details.  It's best to assume
               traditional behavior if you're writing portable
               programs.  (But if you're not, you should as
               always feel perfectly free to write for your own
               system's idiosyncrasies (sometimes called
               "features").  Slavish adherence to portability
               concerns shouldn't get in the way of your getting
               your job done.)

               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 miscoordination, Perl
               now flushes FILEHANDLE before locking or unlocking
               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 if
               not 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.




29/Apr/1999            perl 5.005, patch 03                    31





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


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

               On systems that support a real flock(), locks are
               inherited across fork() calls, whereas those that
               must resort to the more capricious fcntl()
               function lose the locks, making it harder to write
               servers.

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

       fork    Does a fork(2) system call to create a new process
               running the same program at the same point.  It
               returns the child pid to the parent process, 0 to
               the child process, or undef if the fork is
               unsuccessful.  File descriptors (and sometimes
               locks on those descriptors) are shared, while
               everything else is copied.  On most systems
               supporting fork(), great care has gone into making
               it extremely efficient (for example, using copy-
               on-write technology on data pages), making it the
               dominant paradigm for multitasking over the last
               few decades.

               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.  On some
               systems, you can avoid this by setting $SIG{CHLD}
               to "IGNORE".  See also the perlipc manpage for
               more examples of forking and reaping moribund



29/Apr/1999            perl 5.005, patch 03                    32





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


               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, a
               CGI script or a backgrounded job launced from a
               remote shell) 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





29/Apr/1999            perl 5.005, patch 03                    33





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


       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.  However, it cannot be
               used by itself to fetch single characters without
               waiting for the user to hit enter.  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 perlmodlib 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.








29/Apr/1999            perl 5.005, patch 03                    34





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


                   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





29/Apr/1999            perl 5.005, patch 03                    35





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


       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:






29/Apr/1999            perl 5.005, patch 03                    36





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


                   $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 what your
               $quota and $comment fields mean 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.  Shadow password
               files are only supported if your vendor has
               implemented them in the intuitive fashion that
               calling the regular C library routines gets the
               shadow versions if you're running under privilege.
               Those that incorrectly implement a separate
               library call are not supported.

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

               The Socket library makes this slightly easier:





29/Apr/1999            perl 5.005, patch 03                    37





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


                   use Socket;
                   $iaddr = inet_aton("127.1"); # or whatever address
                   $name  = gethostbyaddr($iaddr, AF_INET);

                   # or going the other way
                   $straddr = inet_ntoa($iaddr");

               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/csh 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:




29/Apr/1999            perl 5.005, patch 03                    38





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


                   #  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 you assume it is, then you create
               non-Y2K-compliant programs--and you wouldn't want
               to do that, would you?

               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 is instead a Perl
               builtin.  Also see the Time::Local module, and the
               strftime(3) and mktime(3) functions 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 escapes, which represent
               the short forms of the day of the week and the
               month of the year, may not necessarily be three
               characters wide in all locales.

       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



29/Apr/1999            perl 5.005, patch 03                    39





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


               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 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 as a for loop's index
               variable aliases the list elements.  That is,
               modifying an element of a list returned by grep



29/Apr/1999            perl 5.005, patch 03                    40





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


               (for example, in a foreach, map() or another
               grep()) actually modifies the element in the
               original list.  This is usually something to be
               avoided when writing clear code.

               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, 0x, or 0b, 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
               The index function searches for one string within
               another, but without the wildcard-like behavior of
               a full regular-expression pattern match.  It
               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
               function for rounding: one because it truncates
               towards 0, and two because machine representations
               of floating point numbers can sometimes produce
               counterintuitive results.  For example,
               int(-6.725/0.025) produces -268 rather than the
               correct -269; that's because it's really more like
               -268.99999999999994315658 instead.  Usually, the



29/Apr/1999            perl 5.005, patch 03                    41





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


               sprintf(), printf(), or the POSIX::floor and
               POSIX::ceil functions will serve you better than
               will int().

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

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

               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:





29/Apr/1999            perl 5.005, patch 03                    42





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


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

               The special string "0 but true" is exempt 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 that new string.  Example:

                   $rec = 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.  The actual random order
               is subject to change in future versions of perl,
               but it is guaranteed to be 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 a hash 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



29/Apr/1999            perl 5.005, patch 03                    43





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


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

               See also each(), values() and sort().

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

               last cannot be used to exit a block which returns
               a value such as eval {}, sub {} or do {}, and
               should not be used to exit a grep() or map()
               operation.

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




29/Apr/1999            perl 5.005, patch 03                    44





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


       lc EXPR

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

               If EXPR is omitted, uses $_.

       lcfirst EXPR

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

               If EXPR is omitted, uses $_.

       length EXPR

       length  Returns the length in characters of the value of
               EXPR.  If EXPR is omitted, returns length of $_.
               Note that this cannot be used on an entire array
               or hash to find out how many elements these have.
               For that, use scalar @array and scalar keys %hash
               respectively.

       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 the example in the section on
               Sockets: Client/Server Communication in the
               perlipc manpage.

       local EXPR
               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.

               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.




29/Apr/1999            perl 5.005, patch 03                    45





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


       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 you assume it is, then you create
               non-Y2K-compliant programs--and you wouldn't want
               to do that, would you?

               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 $_.  To get the
               log of another base, use basic algebra: The base-N
               log of a number is is equal to the natural log of
               that number divided by the natural log of N.  For
               example:







29/Apr/1999            perl 5.005, patch 03                    46





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


                   sub log10 {
                       my $n = shift;
                       return log($n)/log(10);
                   }

               See also the exp entry elsewhere in this
               documentfor the inverse operation.

       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.

               In scalar context, returns the total number of
               elements so generated.

                   @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



29/Apr/1999            perl 5.005, patch 03                    47





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


               can cause bizarre results if the LIST is not a
               named array.  Using a regular foreach loop for
               this purpose would be clearer in most cases.  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).

               In general, it is better to create directories
               with permissive MODEs, and let the user modify
               that with their umask, than it is to supply a
               restrictive MODE and give the user no way to be
               more permissive.  The exceptions to this rule are
               when the file or directory should be kept private
               (mail files, for instance).  The perlfunc(1) entry
               on umask discusses the choice of MODE in more
               detail.

       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.





29/Apr/1999            perl 5.005, patch 03                    48





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


       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.

               next cannot be used to exit a block which returns
               a value such as eval {}, sub {} or do {}, and
               should not be used to exit a grep() or map()
               operation.

               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.  If
               EXPR starts off with 0b, it is interpreted as a
               binary string.)  The following will handle
               decimal, binary, octal, and hex in the standard



29/Apr/1999            perl 5.005, patch 03                    49





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


               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.)  See the
               perlopentut manpage for a kinder, gentler
               explanation of opening files.

               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 file is created with permissions of
               0666 modified by the process' umask value.

               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 as a command which pipes
               output to us.  See the section on Using open() for
               IPC in the perlipc manpage for more examples of



29/Apr/1999            perl 5.005, patch 03                    50





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


               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: $!";




29/Apr/1999            perl 5.005, patch 03                    51





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


                   # 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");



29/Apr/1999            perl 5.005, patch 03                    52





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


                   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.  On systems that support a
               close-on-exec flag on files, the flag will be set
               for the newly opened file descriptor as determined
               by the value of $^F.  See the section on $^F in
               the perlvar manpage.

               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



29/Apr/1999            perl 5.005, patch 03                    53





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


               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



29/Apr/1999            perl 5.005, patch 03                    54





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


               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   A string with arbitrary binary data, will be null padded.
                   A   An ascii string, will be space padded.
                   Z   A null terminated (asciz) 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.)



29/Apr/1999            perl 5.005, patch 03                    55





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


                   q   A signed quad (64-bit) value.
                   Q   An unsigned quad value.
                         (Available only if your system supports 64-bit integer values
                          _and_ if Perl has been compiled to support those.
                          Causes a fatal error otherwise.)

                   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.

               The following rules apply:

       o               Each letter may optionally be followed by
                       a number giving a repeat count.  With all
                       types except "a", "A", "Z", "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.

       o               The "a", "A", and "Z" 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, "Z" strips
                       everything after the first null, and "a"
                       returns data verbatim.

       o               Likewise, the "b" and "B" fields pack a
                       string that many bits long.

       o               The "h" and "H" fields pack a string that
                       many nybbles long.

       o               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" type packs a
                       pointer to a structure of the size



29/Apr/1999            perl 5.005, patch 03                    56





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


                       indicated by the length. A NULL pointer is
                       created if the corresponding value for "p"
                       or "P" is undef.

       o               The integer formats "s", "S", "i", "I",
                       "l", and "L" are inherently non-portable
                       between processors and operating systems
                       because they obey the native byteorder and
                       endianness.  For example a 4-byte integer
                       0x87654321 (2271560481 decimal) be ordered
                       natively (arranged in and handled by the
                       CPU registers) into bytes as

                            0x12 0x34 0x56 0x78 # little-endian
                            0x78 0x56 0x34 0x12 # big-endian

                       Basically, the Intel, Alpha, and VAX CPUs
                       and little-endian, while everybody else,
                       for example Motorola m68k/88k, PPC, Sparc,
                       HP PA, Power, and Cray are big-endian.
                       MIPS can be either: Digital used it in
                       little-endian mode, SGI uses it in big-
                       endian mode.

                       The names `big-endian' and `little-endian'
                       are joking references to the classic
                       "Gulliver's Travels" (via the paper "On
                       Holy Wars and a Plea for Peace" by Danny
                       Cohen, USC/ISI IEN 137, April 1, 1980) and
                       the egg-eating habits of the lilliputs.

                       Some systems may even have weird byte
                       orders such as

                            0x56 0x78 0x12 0x34
                            0x34 0x12 0x78 0x56

                       You can see your system's preference with

                               print join(" ", map { sprintf "%#02x", $_ }
                                                   unpack("C*",pack("L",0x12345678))), "\n";

                       The byteorder on the platform where Perl
                       was built is also available via the Config
                       manpage:

                               use Config;
                               print $Config{byteorder}, "\n";

                       Byteorders '1234' and '12345678' are
                       little-endian, '4321' and '87654321' are
                       big-endian.

                       If you want portable packed integers use



29/Apr/1999            perl 5.005, patch 03                    57





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


                       the formats "n", "N", "v", and "V", their
                       byte endianness and size is known.

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

                           $utmp_template = "Z8 Z8 Z16 L";
                           $utmp = pack($utmp_template, @utmp1);
                           # a struct utmp (BSDish)





29/Apr/1999            perl 5.005, patch 03                    58





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


                           @utmp2 = unpack($utmp_template, $utmp);
                           # "@utmp1" eq "@utmp2"

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

                       The same template may generally also be
                       used in unpack().

       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, file, or eval (the
               same as the my() 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, which are
               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 (as well as to
               $main'sail, still seen in older code).

               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.



29/Apr/1999            perl 5.005, patch 03                    59





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


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

               On systems that support a close-on-exec flag on
               files, the flag will be set for the newly opened
               file descriptors as determined by the value of
               $^F.  See the section on $^F in the perlvar
               manpage.

       pop ARRAY

       pop     Pops and returns the last value of the array,
               shortening the array by one element.  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,



29/Apr/1999            perl 5.005, patch 03                    60





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


               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 the
               builtin is not overridable (such as qw//) or its
               arguments cannot be expressed by a prototype (such
               as system()) returns undef because the builtin
               does not really behave like a Perl function.
               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



29/Apr/1999            perl 5.005, patch 03                    61





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


                   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 section on Regexp
               Quote-Like Operators in 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



29/Apr/1999            perl 5.005, patch 03                    62





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


               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, each call
               reads and returns the next line, until end-of-file
               is reached, whereupon the subsequent call returns
               undef.  In list context, reads until end-of-file
               is reached and returns a list of lines.  Note that
               the notion of "line" used here is however you may
               have defined it with $/ or
               $INPUT_RECORD_SEPARATOR).  See the section on $/
               in the perlvar manpage.

               When $/ is set to undef, when readline() is in
               scalar context (i.e. file slurp mode), and when an
               empty file is read, it returns '' the first time,
               followed by undef subsequently.

               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





29/Apr/1999            perl 5.005, patch 03                    63





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


       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,LENGTH,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:
















29/Apr/1999            perl 5.005, patch 03                    64





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


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

               redo cannot be used to retry a block which returns
               a value such as eval {}, sub {} or do {}, and
               should not be used to exit a grep() or map()
               operation.

               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.












29/Apr/1999            perl 5.005, patch 03                    65





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


                   if (ref($r) eq "HASH") {
                       print "r is a reference to a hash.\n";
                   }
                   unless (ref($r)) {
                       print "r is not a reference at all.\n";
                   }
                   if (UNIVERSAL::isa($r, "HASH")) {  # for subclassing
                       print "r is a reference to something that isa hash.\n";
                   }

               See also the perlref manpage.

       rename OLDNAME,NEWNAME
               Changes the name of a file.  Returns 1 for
               success, 0 otherwise.  Behavior of this function
               varies wildly depending on your system
               implementation.  For example, it will usually not
               work across file system boundaries, even though
               the system mv command sometimes compensates for
               this.  Other restrictions include whether it works
               on directories, open files, or pre-existing files.
               Check the perlport manpage and either the
               rename(2) manpage or equivalent system
               documentation for details.

       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:




















29/Apr/1999            perl 5.005, patch 03                    66





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


                   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:




29/Apr/1999            perl 5.005, patch 03                    67





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


                       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 ?one-time? 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, the undefined value in
               scalar context, and (of course) nothing at all in
               a void context.

               (Note that in the absence of a explicit 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 with all characters in



29/Apr/1999            perl 5.005, patch 03                    68





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


               the opposite order.

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

                   undef $/;                   # for efficiency of <>
                   print scalar reverse <>;    # character 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, such as from a DBM file.

                   %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 in practice, this is never needed.  If you
               really wanted to do so, however, you could use the
               construction @{[ (some expression) ]}, but usually
               a simple (some expression) suffices.

               Since scalar is a unary operator, if you



29/Apr/1999            perl 5.005, patch 03                    69





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


               accidentally use for EXPR a parenthesized list,
               this behaves as a scalar comma expression,
               evaluating all but the last element in void
               context and returning the final element evaluated
               in scalar context.  This is seldom what you want.

               The following single statement:

                       print uc(scalar(&foo,$bar)),$baz;

               is the moral equivalent of these two:

                       &foo;
                       print(uc($bar),$baz);

               See the perlop manpage for more details on unary
               operators and the comma operator.

       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.

               Due to the rules and rigors of ANSI C, 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.




29/Apr/1999            perl 5.005, patch 03                    70





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


               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



29/Apr/1999            perl 5.005, patch 03                    71





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


               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



29/Apr/1999            perl 5.005, patch 03                    72





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


                   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.  The C
               system call sendmsg(2) is currently unimplemented.
               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



29/Apr/1999            perl 5.005, patch 03                    73





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


               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.  See
               also POSIX::setsid().

       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





29/Apr/1999            perl 5.005, patch 03                    74





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


       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 and the IPC::Shareable module from
               CPAN.

       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



29/Apr/1999            perl 5.005, patch 03                    75





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


               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 examples 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



29/Apr/1999            perl 5.005, patch 03                    76





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


               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;






29/Apr/1999            perl 5.005, patch 03                    77





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


                   # 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



29/Apr/1999            perl 5.005, patch 03                    78





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


                   @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




29/Apr/1999            perl 5.005, patch 03                    79





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


       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.



29/Apr/1999            perl 5.005, patch 03                    80





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


               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



29/Apr/1999            perl 5.005, patch 03                    81





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


               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:














29/Apr/1999            perl 5.005, patch 03                    82





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


                  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 $_.  Only works on
               non-negative operands, unless you've loaded the
               standard Math::Complex module.

                   use Math::Complex;
                   print sqrt(-2);    # prints 1.4142135623731i


       srand EXPR

       srand   Sets the random number seed for the rand()
               operator.  If EXPR is omitted, uses a semi-random
               value supplied by the kernel (if it supports the
               /dev/urandom device) or 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



29/Apr/1999            perl 5.005, patch 03                    83





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


               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



29/Apr/1999            perl 5.005, patch 03                    84





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


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

               Because the mode contains both the file type and
               its permissions, you should mask off the file type
               portion and (s)printf using a "%o" if you want to
               see the real permissions.

                   $mode = (stat($filename))[2];
                   printf "Permissions are %04o\n", $mode & 07777;

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

               The File::stat module provides a convenient, by-
               name access mechanism:

                   use File::stat;
                   $sb = stat($filename);
                   printf "File is %s, size is %s, perm %04o, mtime %s\n",
                       $filename, $sb->size, $sb->mode & 07777,
                       scalar localtime $sb->mtime;






29/Apr/1999            perl 5.005, patch 03                    85





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


       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



29/Apr/1999            perl 5.005, patch 03                    86





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


               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 itself 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



29/Apr/1999            perl 5.005, patch 03                    87





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


               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, just as you can with splice().

       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.



29/Apr/1999            perl 5.005, patch 03                    88





PERLFUNC(1)      Perl Programmers Reference Guide     PERLFUNC(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 &
               VM/ESA 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.

               You should 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.  See the perlfunc(1) entry on umask for
               more on this.

               See the perlopentut manpage for a kinder, gentler
               explanation of opening files.

       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(), tell(), or eof() can cause
               confusion because stdio usually buffers data.



29/Apr/1999            perl 5.005, patch 03                    89





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


               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.

               There is no syseof() function, which is ok, since
               eof() doesn't work very well on device files (like
               ttys) anyway.  Use sysread() and check for a
               return value for 0 to decide whether you're done.

       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(), tell(), or eof() 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



29/Apr/1999            perl 5.005, patch 03                    90





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


               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

       syswrite FILEHANDLE,SCALAR
               Attempts to write LENGTH bytes of data from
               variable SCALAR to the specified FILEHANDLE, using
               the system call write(2).  If LENGTH is not
               specified, writes whole SCALAR. It bypasses stdio,
               so mixing this with reads (other than sysread()),
               print(), write(), seek(), tell(), or eof() may



29/Apr/1999            perl 5.005, patch 03                    91





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


               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.

               There is no systell() function.  Use sysseek(FH,
               0, 1) for that.

       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, TIEHANDLE,
               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:






29/Apr/1999            perl 5.005, patch 03                    92





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


                   # 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
                   FETCH this, key
                   STORE this, key, value
                   DELETE this, key
                   CLEAR this
                   EXISTS this, key
                   FIRSTKEY this
                   NEXTKEY this, lastkey
                   DESTROY this

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

                   TIEARRAY classname, LIST
                   FETCH this, key
                   STORE this, key, value
                   FETCHSIZE this
                   STORESIZE this, count
                   CLEAR this
                   PUSH this, LIST
                   POP this
                   SHIFT this
                   UNSHIFT this, LIST
                   SPLICE this, offset, length, LIST
                   EXTEND this, count
                   DESTROY this

               A class implementing a file handle should have the
               following methods:

                   TIEHANDLE classname, LIST
                   READ this, scalar, length, offset
                   READLINE this
                   GETC this
                   WRITE this, scalar, length, offset
                   PRINT this, LIST
                   PRINTF this, format, LIST
                   CLOSE this
                   DESTROY this

               A class implementing a scalar should have the
               following methods:




29/Apr/1999            perl 5.005, patch 03                    93





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


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

               Not all methods indicated above need be
               implemented.  See the perltie manpage, the
               Tie::Hash manpage, the Tie::Array manpage, the
               Tie::Scalar manpage, and the Tie::Handle manpage.

               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




29/Apr/1999            perl 5.005, patch 03                    94





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


       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.  (It does not attempt to do
               titlecase mapping on initial letters.  See
               ucfirst() for that.)

               If EXPR is omitted, uses $_.

       ucfirst EXPR

       ucfirst Returns the value of EXPR with the first character
               in uppercase.  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.

               The Unix permission rwxr-x--- is represented as
               three sets of three bits, or three octal digits:
               0750 (the leading 0 indicates octal and isn't one
               of the digits).  The umask value is such a number
               representing disabled permissions bits.  The
               permission (or "mode") values you pass mkdir or
               sysopen are modified by your umask, so even if you
               tell sysopen to create a file with permissions
               0777, if your umask is 0022 then the file will
               actually be created with permissions 0755.  If
               your umask were 0027 (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).

               Here's some advice: supply a creation mode of 0666
               for regular files (in sysopen()) 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.

               If umask(2) is not implemented on your system and



29/Apr/1999            perl 5.005, patch 03                    95





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


               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.




29/Apr/1999            perl 5.005, patch 03                    96





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


               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("%32C*", $_);
                   }
                   $checksum %= 65535;

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

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

               See the pack entry elsewhere in this documentfor
               more examples.

       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



29/Apr/1999            perl 5.005, patch 03                    97





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


               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 }




29/Apr/1999            perl 5.005, patch 03                    98





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


               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;






29/Apr/1999            perl 5.005, patch 03                    99





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


       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.  The actual random order
               is subject to change in future versions of perl,
               but it is guaranteed to be the same order as
               either the keys() or each() function would produce
               on the same (unmodified) hash.

               Note that you cannot modify the values of a hash
               this way, because the returned list is just a
               copy.  You need to use a hash slice for that,
               since it's lvaluable in a way that values() is
               not.

                   for (values %hash)      { s/foo/bar/g }   # FAILS!
                   for (@hash{keys %hash}) { s/foo/bar/g }   # ok

               As a side effect, calling values() resets the
               HASH's internal 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.  See the section on Bitwise
               String Operators in the perlop manpage.

               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.











29/Apr/1999            perl 5.005, patch 03                   100





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


                   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    Behaves like the wait(2) system call on your
               system: it 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
               rketurned in $?.  Note that a return value of -1
               could mean that child processes are being
               automatically reaped, as described in the perlipc
               manpage.

       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.  On some
               systems, a value of 0 indicates that there are
               processes still running.  The status is returned
               in $?.  If you say

                   use POSIX ":sys_wait_h";
                   #...
                   do {
                       $kid = waitpid(-1,&WNOHANG);
                   } until $kid == -1;

               then you can do a non-blocking wait for all
               pending zombie processes.  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



29/Apr/1999            perl 5.005, patch 03                   101





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


               the Perl script yet.)

               Note that on some systems, a return value of -1
               could mean that child processes are being
               automatically reaped.  See the perlipc manpage for
               details, and 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:





29/Apr/1999            perl 5.005, patch 03                   102





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


                   # 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.  See the Carp
               module for other kinds of warnings using its
               carp() and cluck() functions.

       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.



29/Apr/1999            perl 5.005, patch 03                   103





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


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























































29/Apr/1999            perl 5.005, patch 03                   104





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



























































29/Apr/1999            perl 5.005, patch 03                   105


