perlfunc man page on BSDi

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDi logo
[printable version]



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.

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

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

16/Sep/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,

16/Sep/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.

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

16/Sep/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.

16/Sep/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.

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

16/Sep/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.

16/Sep/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:

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

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

16/Sep/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 $_.

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

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

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

16/Sep/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:

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

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

16/Sep/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.

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

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

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

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

16/Sep/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,

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

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

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

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

16/Sep/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.

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

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

16/Sep/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.

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

16/Sep/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:

16/Sep/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:

16/Sep/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:

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

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

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

16/Sep/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:

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

16/Sep/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.

16/Sep/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.

16/Sep/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:

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

16/Sep/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.

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

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

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

16/Sep/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");

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

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

16/Sep/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.)

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

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

16/Sep/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)

16/Sep/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.

16/Sep/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,

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

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

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

16/Sep/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:

16/Sep/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.

16/Sep/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:

16/Sep/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:

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

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

16/Sep/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.

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

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

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

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

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

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

16/Sep/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;

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

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

16/Sep/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.

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

16/Sep/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:

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

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

16/Sep/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;

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

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

16/Sep/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.


16/Sep/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.

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

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

16/Sep/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:

16/Sep/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:

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

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

16/Sep/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.

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

16/Sep/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 }

16/Sep/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;

16/Sep/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.

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

16/Sep/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:

16/Sep/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.

16/Sep/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.

16/Sep/1999	       perl 5.005, patch 03		      104

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

16/Sep/1999	       perl 5.005, patch 03		      105

[top]

List of man pages available for BSDi

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net