home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / perlfunc < prev    next >
Text File  |  1999-04-17  |  229KB  |  5,391 lines

  1. NAME
  2.     perlfunc - Perl builtin functions
  3.  
  4. DESCRIPTION
  5.     The functions in this section can serve as terms in an
  6.     expression. They fall into two major categories: list operators
  7.     and named unary operators. These differ in their precedence
  8.     relationship with a following comma. (See the precedence table
  9.     in the perlop manpage.) List operators take more than one
  10.     argument, while unary operators can never take more than one
  11.     argument. Thus, a comma terminates the argument of a unary
  12.     operator, but merely separates the arguments of a list operator.
  13.     A unary operator generally provides a scalar context to its
  14.     argument, while a list operator may provide either scalar or
  15.     list contexts for its arguments. If it does both, the scalar
  16.     arguments will be first, and the list argument will follow.
  17.     (Note that there can ever be only one such list argument.) For
  18.     instance, splice() has three scalar arguments followed by a
  19.     list, whereas gethostbyname() has four scalar arguments.
  20.  
  21.     In the syntax descriptions that follow, list operators that
  22.     expect a list (and provide list context for the elements of the
  23.     list) are shown with LIST as an argument. Such a list may
  24.     consist of any combination of scalar arguments or list values;
  25.     the list values will be included in the list as if each
  26.     individual element were interpolated at that point in the list,
  27.     forming a longer single-dimensional list value. Elements of the
  28.     LIST should be separated by commas.
  29.  
  30.     Any function in the list below may be used either with or
  31.     without parentheses around its arguments. (The syntax
  32.     descriptions omit the parentheses.) If you use the parentheses,
  33.     the simple (but occasionally surprising) rule is this: It
  34.     *LOOKS* like a function, therefore it *IS* a function, and
  35.     precedence doesn't matter. Otherwise it's a list operator or
  36.     unary operator, and precedence does matter. And whitespace
  37.     between the function and left parenthesis doesn't count--so you
  38.     need to be careful sometimes:
  39.  
  40.         print 1+2+4;    # Prints 7.
  41.         print(1+2) + 4;    # Prints 3.
  42.         print (1+2)+4;    # Also prints 3!
  43.         print +(1+2)+4;    # Prints 7.
  44.         print ((1+2)+4);    # Prints 7.
  45.  
  46.  
  47.     If you run Perl with the -w switch it can warn you about this.
  48.     For example, the third line above produces:
  49.  
  50.         print (...) interpreted as function at - line 1.
  51.         Useless use of integer addition in void context at - line 1.
  52.  
  53.  
  54.     A few functions take no arguments at all, and therefore work as
  55.     neither unary nor list operators. These include such functions
  56.     as `time' and `endpwent'. For example, `time+86_400' always
  57.     means `time() + 86_400'.
  58.  
  59.     For functions that can be used in either a scalar or list
  60.     context, nonabortive failure is generally indicated in a scalar
  61.     context by returning the undefined value, and in a list context
  62.     by returning the null list.
  63.  
  64.     Remember the following important rule: There is no rule that
  65.     relates the behavior of an expression in list context to its
  66.     behavior in scalar context, or vice versa. It might do two
  67.     totally different things. Each operator and function decides
  68.     which sort of value it would be most appropriate to return in
  69.     scalar context. Some operators return the length of the list
  70.     that would have been returned in list context. Some operators
  71.     return the first value in the list. Some operators return the
  72.     last value in the list. Some operators return a count of
  73.     successful operations. In general, they do what you want, unless
  74.     you want consistency.
  75.  
  76.     An named array in scalar context is quite different from what
  77.     would at first glance appear to be a list in scalar context. You
  78.     can't get a list like `(1,2,3)' into being in scalar context,
  79.     because the compiler knows the context at compile time. It would
  80.     generate the scalar comma operator there, not the list
  81.     construction version of the comma. That means it was never a
  82.     list to start with.
  83.  
  84.     In general, functions in Perl that serve as wrappers for system
  85.     calls of the same name (like chown(2), fork(2), closedir(2),
  86.     etc.) all return true when they succeed and `undef' otherwise,
  87.     as is usually mentioned in the descriptions below. This is
  88.     different from the C interfaces, which return `-1' on failure.
  89.     Exceptions to this rule are `wait()', `waitpid()', and
  90.     `syscall()'. System calls also set the special `$!' variable on
  91.     failure. Other functions do not, except accidentally.
  92.  
  93.   Perl Functions by Category
  94.  
  95.     Here are Perl's functions (including things that look like
  96.     functions, like some keywords and named operators) arranged by
  97.     category. Some functions appear in more than one place.
  98.  
  99.     Functions for SCALARs or strings
  100.         `chomp', `chop', `chr', `crypt', `hex', `index', `lc',
  101.         `lcfirst', `length', `oct', `ord', `pack', `q/STRING/',
  102.         `qq/STRING/', `reverse', `rindex', `sprintf', `substr',
  103.         `tr///', `uc', `ucfirst', `y///'
  104.  
  105.     Regular expressions and pattern matching
  106.         `m//', `pos', `quotemeta', `s///', `split', `study', `qr//'
  107.  
  108.     Numeric functions
  109.         `abs', `atan2', `cos', `exp', `hex', `int', `log', `oct',
  110.         `rand', `sin', `sqrt', `srand'
  111.  
  112.     Functions for real @ARRAYs
  113.         `pop', `push', `shift', `splice', `unshift'
  114.  
  115.     Functions for list data
  116.         `grep', `join', `map', `qw/STRING/', `reverse', `sort',
  117.         `unpack'
  118.  
  119.     Functions for real %HASHes
  120.         `delete', `each', `exists', `keys', `values'
  121.  
  122.     Input and output functions
  123.         `binmode', `close', `closedir', `dbmclose', `dbmopen',
  124.         `die', `eof', `fileno', `flock', `format', `getc', `print',
  125.         `printf', `read', `readdir', `rewinddir', `seek', `seekdir',
  126.         `select', `syscall', `sysread', `sysseek', `syswrite',
  127.         `tell', `telldir', `truncate', `warn', `write'
  128.  
  129.     Functions for fixed length data or records
  130.         `pack', `read', `syscall', `sysread', `syswrite', `unpack',
  131.         `vec'
  132.  
  133.     Functions for filehandles, files, or directories
  134.         `-*X*', `chdir', `chmod', `chown', `chroot', `fcntl',
  135.         `glob', `ioctl', `link', `lstat', `mkdir', `open',
  136.         `opendir', `readlink', `rename', `rmdir', `stat', `symlink',
  137.         `umask', `unlink', `utime'
  138.  
  139.     Keywords related to the control flow of your perl program
  140.         `caller', `continue', `die', `do', `dump', `eval', `exit',
  141.         `goto', `last', `next', `redo', `return', `sub', `wantarray'
  142.  
  143.     Keywords related to scoping
  144.         `caller', `import', `local', `my', `package', `use'
  145.  
  146.     Miscellaneous functions
  147.         `defined', `dump', `eval', `formline', `local', `my',
  148.         `reset', `scalar', `undef', `wantarray'
  149.  
  150.     Functions for processes and process groups
  151.         `alarm', `exec', `fork', `getpgrp', `getppid',
  152.         `getpriority', `kill', `pipe', `qx/STRING/', `setpgrp',
  153.         `setpriority', `sleep', `system', `times', `wait', `waitpid'
  154.  
  155.     Keywords related to perl modules
  156.         `do', `import', `no', `package', `require', `use'
  157.  
  158.     Keywords related to classes and object-orientedness
  159.         `bless', `dbmclose', `dbmopen', `package', `ref', `tie',
  160.         `tied', `untie', `use'
  161.  
  162.     Low-level socket functions
  163.         `accept', `bind', `connect', `getpeername', `getsockname',
  164.         `getsockopt', `listen', `recv', `send', `setsockopt',
  165.         `shutdown', `socket', `socketpair'
  166.  
  167.     System V interprocess communication functions
  168.         `msgctl', `msgget', `msgrcv', `msgsnd', `semctl', `semget',
  169.         `semop', `shmctl', `shmget', `shmread', `shmwrite'
  170.  
  171.     Fetching user and group info
  172.         `endgrent', `endhostent', `endnetent', `endpwent',
  173.         `getgrent', `getgrgid', `getgrnam', `getlogin', `getpwent',
  174.         `getpwnam', `getpwuid', `setgrent', `setpwent'
  175.  
  176.     Fetching network info
  177.         `endprotoent', `endservent', `gethostbyaddr',
  178.         `gethostbyname', `gethostent', `getnetbyaddr',
  179.         `getnetbyname', `getnetent', `getprotobyname',
  180.         `getprotobynumber', `getprotoent', `getservbyname',
  181.         `getservbyport', `getservent', `sethostent', `setnetent',
  182.         `setprotoent', `setservent'
  183.  
  184.     Time-related functions
  185.         `gmtime', `localtime', `time', `times'
  186.  
  187.     Functions new in perl5
  188.         `abs', `bless', `chomp', `chr', `exists', `formline',
  189.         `glob', `import', `lc', `lcfirst', `map', `my', `no',
  190.         `prototype', `qx', `qw', `readline', `readpipe', `ref',
  191.         `sub*', `sysopen', `tie', `tied', `uc', `ucfirst', `untie',
  192.         `use'
  193.  
  194.         * - `sub' was a keyword in perl4, but in perl5 it is an
  195.         operator, which can be used in expressions.
  196.  
  197.     Functions obsoleted in perl5
  198.         `dbmclose', `dbmopen'
  199.  
  200.  
  201.   Portability
  202.  
  203.     Perl was born in Unix and can therefore access all common Unix
  204.     system calls. In non-Unix environments, the functionality of
  205.     some Unix system calls may not be available, or details of the
  206.     available functionality may differ slightly. The Perl functions
  207.     affected by this are:
  208.  
  209.     `-X', `binmode', `chmod', `chown', `chroot', `crypt',
  210.     `dbmclose', `dbmopen', `dump', `endgrent', `endhostent',
  211.     `endnetent', `endprotoent', `endpwent', `endservent', `exec',
  212.     `fcntl', `flock', `fork', `getgrent', `getgrgid', `gethostent',
  213.     `getlogin', `getnetbyaddr', `getnetbyname', `getnetent',
  214.     `getppid', `getprgp', `getpriority', `getprotobynumber',
  215.     `getprotoent', `getpwent', `getpwnam', `getpwuid',
  216.     `getservbyport', `getservent', `getsockopt', `glob', `ioctl',
  217.     `kill', `link', `lstat', `msgctl', `msgget', `msgrcv', `msgsnd',
  218.     `open', `pipe', `readlink', `rename', `select', `semctl',
  219.     `semget', `semop', `setgrent', `sethostent', `setnetent',
  220.     `setpgrp', `setpriority', `setprotoent', `setpwent',
  221.     `setservent', `setsockopt', `shmctl', `shmget', `shmread',
  222.     `shmwrite', `socket', `socketpair', `stat', `symlink',
  223.     `syscall', `sysopen', `system', `times', `truncate', `umask',
  224.     `unlink', `utime', `wait', `waitpid'
  225.  
  226.     For more information about the portability of these functions,
  227.     see the perlport manpage and other available platform-specific
  228.     documentation.
  229.  
  230.   Alphabetical Listing of Perl Functions
  231.  
  232.     *-X* FILEHANDLE
  233.  
  234.     *-X* EXPR
  235.  
  236.     *-X*    A file test, where X is one of the letters listed below.
  237.             This unary operator takes one argument, either a
  238.             filename or a filehandle, and tests the associated file
  239.             to see if something is true about it. If the argument is
  240.             omitted, tests `$_', except for `-t', which tests STDIN.
  241.             Unless otherwise documented, it returns `1' for TRUE and
  242.             `''' for FALSE, or the undefined value if the file
  243.             doesn't exist. Despite the funny names, precedence is
  244.             the same as any other named unary operator, and the
  245.             argument may be parenthesized like any other unary
  246.             operator. The operator may be any of:
  247.  
  248.                 -r    File is readable by effective uid/gid.
  249.                 -w    File is writable by effective uid/gid.
  250.                 -x    File is executable by effective uid/gid.
  251.                 -o    File is owned by effective uid.
  252.  
  253.                 -R    File is readable by real uid/gid.
  254.                 -W    File is writable by real uid/gid.
  255.                 -X    File is executable by real uid/gid.
  256.                 -O    File is owned by real uid.
  257.  
  258.                 -e    File exists.
  259.                 -z    File has zero size.
  260.                 -s    File has nonzero size (returns size).
  261.  
  262.                 -f    File is a plain file.
  263.                 -d    File is a directory.
  264.                 -l    File is a symbolic link.
  265.                 -p    File is a named pipe (FIFO), or Filehandle is a pipe.
  266.                 -S    File is a socket.
  267.                 -b    File is a block special file.
  268.                 -c    File is a character special file.
  269.                 -t    Filehandle is opened to a tty.
  270.  
  271.                 -u    File has setuid bit set.
  272.                 -g    File has setgid bit set.
  273.                 -k    File has sticky bit set.
  274.  
  275.                 -T    File is a text file.
  276.                 -B    File is a binary file (opposite of -T).
  277.  
  278.                 -M    Age of file in days when script started.
  279.                 -A    Same for access time.
  280.                 -C    Same for inode change time.
  281.  
  282.  
  283.             Example:
  284.  
  285.                 while (<>) {
  286.                 chop;
  287.                 next unless -f $_;    # ignore specials
  288.                 #...
  289.                 }
  290.  
  291.  
  292.             The interpretation of the file permission operators `-
  293.             r', `-R', `-w', `-W', `-x', and `-X' is by default based
  294.             solely on the mode of the file and the uids and gids of
  295.             the user. There may be other reasons you can't actually
  296.             read, write, or execute the file. Such reasons may be
  297.             for example network filesystem access controls, ACLs
  298.             (access control lists), read-only filesystems, and
  299.             unrecognized executable formats.
  300.  
  301.             Also note that, for the superuser on the local
  302.             filesystems, the `-r', `-R', `-w', and `-W' tests always
  303.             return 1, and `-x' and `-X' return 1 if any execute bit
  304.             is set in the mode. Scripts run by the superuser may
  305.             thus need to do a stat() to determine the actual mode of
  306.             the file, or temporarily set their effective uid to
  307.             something else.
  308.  
  309.             Note that `-s/a/b/' does not do a negated substitution.
  310.             Saying `-exp($foo)' still works as expected, however--
  311.             only single letters following a minus are interpreted as
  312.             file tests.
  313.  
  314.             The `-T' and `-B' switches work as follows. The first
  315.             block or so of the file is examined for odd characters
  316.             such as strange control codes or characters with the
  317.             high bit set. If too many strange characters (>30%) are
  318.             found, it's a `-B' file, otherwise it's a `-T' file.
  319.             Also, any file containing null in the first block is
  320.             considered a binary file. If `-T' or `-B' is used on a
  321.             filehandle, the current stdio buffer is examined rather
  322.             than the first block. Both `-T' and `-B' return TRUE on
  323.             a null file, or a file at EOF when testing a filehandle.
  324.             Because you have to read a file to do the `-T' test, on
  325.             most occasions you want to use a `-f' against the file
  326.             first, as in `next unless -f $file && -T $file'.
  327.  
  328.             If any of the file tests (or either the `stat()' or
  329.             `lstat()' operators) are given the special filehandle
  330.             consisting of a solitary underline, then the stat
  331.             structure of the previous file test (or stat operator)
  332.             is used, saving a system call. (This doesn't work with
  333.             `-t', and you need to remember that lstat() and `-l'
  334.             will leave values in the stat structure for the symbolic
  335.             link, not the real file.) Example:
  336.  
  337.                 print "Can do.\n" if -r $a || -w _ || -x _;
  338.  
  339.                 stat($filename);
  340.                 print "Readable\n" if -r _;
  341.                 print "Writable\n" if -w _;
  342.                 print "Executable\n" if -x _;
  343.                 print "Setuid\n" if -u _;
  344.                 print "Setgid\n" if -g _;
  345.                 print "Sticky\n" if -k _;
  346.                 print "Text\n" if -T _;
  347.                 print "Binary\n" if -B _;
  348.  
  349.  
  350.     abs VALUE
  351.  
  352.     abs     Returns the absolute value of its argument. If VALUE is
  353.             omitted, uses `$_'.
  354.  
  355.     accept NEWSOCKET,GENERICSOCKET
  356.             Accepts an incoming socket connect, just as the
  357.             accept(2) system call does. Returns the packed address
  358.             if it succeeded, FALSE otherwise. See the example in the
  359.             section on "Sockets: Client/Server Communication" in the
  360.             perlipc manpage.
  361.  
  362.     alarm SECONDS
  363.  
  364.     alarm   Arranges to have a SIGALRM delivered to this process after
  365.             the specified number of seconds have elapsed. If SECONDS
  366.             is not specified, the value stored in `$_' is used. (On
  367.             some machines, unfortunately, the elapsed time may be up
  368.             to one second less than you specified because of how
  369.             seconds are counted.) Only one timer may be counting at
  370.             once. Each call disables the previous timer, and an
  371.             argument of `0' may be supplied to cancel the previous
  372.             timer without starting a new one. The returned value is
  373.             the amount of time remaining on the previous timer.
  374.  
  375.             For delays of finer granularity than one second, you may
  376.             use Perl's four-arugment version of select() leaving the
  377.             first three arguments undefined, or you might be able to
  378.             use the `syscall()' interface to access setitimer(2) if
  379.             your system supports it. The Time::HiRes module from
  380.             CPAN may also prove useful.
  381.  
  382.             It is usually a mistake to intermix `alarm()' and
  383.             `sleep()' calls.
  384.  
  385.             If you want to use `alarm()' to time out a system call
  386.             you need to use an `eval()'/`die()' pair. You can't rely
  387.             on the alarm causing the system call to fail with `$!'
  388.             set to `EINTR' because Perl sets up signal handlers to
  389.             restart system calls on some systems. Using
  390.             `eval()'/`die()' always works, modulo the caveats given
  391.             in the section on "Signals" in the perlipc manpage.
  392.  
  393.                 eval {
  394.                 local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
  395.                 alarm $timeout;
  396.                 $nread = sysread SOCKET, $buffer, $size;
  397.                 alarm 0;
  398.                 };
  399.                 if ($@) {
  400.                 die unless $@ eq "alarm\n";   # propagate unexpected errors
  401.                     # timed out
  402.                 }
  403.                 else {
  404.                     # didn't
  405.                 }
  406.  
  407.  
  408.     atan2 Y,X
  409.             Returns the arctangent of Y/X in the range -PI to PI.
  410.  
  411.             For the tangent operation, you may use the
  412.             `POSIX::tan()' function, or use the familiar relation:
  413.  
  414.                 sub tan { sin($_[0]) / cos($_[0])  }
  415.  
  416.  
  417.     bind SOCKET,NAME
  418.             Binds a network address to a socket, just as the bind
  419.             system call does. Returns TRUE if it succeeded, FALSE
  420.             otherwise. NAME should be a packed address of the
  421.             appropriate type for the socket. See the examples in the
  422.             section on "Sockets: Client/Server Communication" in the
  423.             perlipc manpage.
  424.  
  425.     binmode FILEHANDLE
  426.             Arranges for the file to be read or written in "binary"
  427.             mode in operating systems that distinguish between
  428.             binary and text files. Files that are not in binary mode
  429.             have CR LF sequences translated to LF on input and LF
  430.             translated to CR LF on output. Binmode has no effect
  431.             under many sytems, but in MS-DOS and similarly archaic
  432.             systems, it may be imperative--otherwise your MS-DOS-
  433.             damaged C library may mangle your file. The key
  434.             distinction between systems that need `binmode()' and
  435.             those that don't is their text file formats. Systems
  436.             like Unix, MacOS, and Plan9 that delimit lines with a
  437.             single character, and that encode that character in C as
  438.             `"\n"', do not need `binmode()'. The rest may need it.
  439.             If FILEHANDLE is an expression, the value is taken as
  440.             the name of the filehandle.
  441.  
  442.             If the system does care about it, using it when you
  443.             shouldn't is just as perilous as failing to use it when
  444.             you should. Fortunately for most of us, you can't go
  445.             wrong using binmode() on systems that don't care about
  446.             it, though.
  447.  
  448.     bless REF,CLASSNAME
  449.  
  450.     bless REF
  451.             This function tells the thingy referenced by REF that it
  452.             is now an object in the CLASSNAME package. If CLASSNAME
  453.             is omitted, the current package is used. Because a
  454.             `bless()' is often the last thing in a constructor. it
  455.             returns the reference for convenience. Always use the
  456.             two-argument version if the function doing the blessing
  457.             might be inherited by a derived class. See the perltoot
  458.             manpage and the perlobj manpage for more about the
  459.             blessing (and blessings) of objects.
  460.  
  461.             Consider always blessing objects in CLASSNAMEs that are
  462.             mixed case. Namespaces with all lowercase names are
  463.             considered reserved for Perl pragmata. Builtin types
  464.             have all uppercase names, so to prevent confusion, you
  465.             may wish to avoid such package names as well. Make sure
  466.             that CLASSNAME is a true value.
  467.  
  468.             See the section on "Perl Modules" in the perlmod
  469.             manpage.
  470.  
  471.     caller EXPR
  472.  
  473.     caller  Returns the context of the current subroutine call. In
  474.             scalar context, returns the caller's package name if
  475.             there is a caller, that is, if we're in a subroutine or
  476.             `eval()' or `require()', and the undefined value
  477.             otherwise. In list context, returns
  478.  
  479.                 ($package, $filename, $line) = caller;
  480.  
  481.  
  482.             With EXPR, it returns some extra information that the
  483.             debugger uses to print a stack trace. The value of EXPR
  484.             indicates how many call frames to go back before the
  485.             current one.
  486.  
  487.                 ($package, $filename, $line, $subroutine,
  488.                  $hasargs, $wantarray, $evaltext, $is_require) = caller($i);
  489.  
  490.  
  491.             Here `$subroutine' may be `"(eval)"' if the frame is not
  492.             a subroutine call, but an `eval()'. In such a case
  493.             additional elements `$evaltext' and `$is_require' are
  494.             set: `$is_require' is true if the frame is created by a
  495.             `require' or `use' statement, `$evaltext' contains the
  496.             text of the `eval EXPR' statement. In particular, for a
  497.             `eval BLOCK' statement, `$filename' is `"(eval)"', but
  498.             `$evaltext' is undefined. (Note also that each `use'
  499.             statement creates a `require' frame inside an `eval
  500.             EXPR') frame.
  501.  
  502.             Furthermore, when called from within the DB package,
  503.             caller returns more detailed information: it sets the
  504.             list variable `@DB::args' to be the arguments with which
  505.             the subroutine was invoked.
  506.  
  507.             Be aware that the optimizer might have optimized call
  508.             frames away before `caller()' had a chance to get the
  509.             information. That means that `caller(N)' might not
  510.             return information about the call frame you expect it
  511.             do, for `N > 1'. In particular, `@DB::args' might have
  512.             information from the previous time `caller()' was
  513.             called.
  514.  
  515.     chdir EXPR
  516.             Changes the working directory to EXPR, if possible. If
  517.             EXPR is omitted, changes to the user's home directory.
  518.             Returns TRUE upon success, FALSE otherwise. See the
  519.             example under `die()'.
  520.  
  521.     chmod LIST
  522.             Changes the permissions of a list of files. The first
  523.             element of the list must be the numerical mode, which
  524.             should probably be an octal number, and which definitely
  525.             should *not* a string of octal digits: `0644' is okay,
  526.             `'0644'' is not. Returns the number of files
  527.             successfully changed. See also the "oct" entry in this
  528.             manpage, if all you have is a string.
  529.  
  530.                 $cnt = chmod 0755, 'foo', 'bar';
  531.                 chmod 0755, @executables;
  532.                 $mode = '0644'; chmod $mode, 'foo';      # !!! sets mode to
  533.                                                          # --w----r-T
  534.                 $mode = '0644'; chmod oct($mode), 'foo'; # this is better
  535.                 $mode = 0644;   chmod $mode, 'foo';      # this is best
  536.  
  537.  
  538.     chomp VARIABLE
  539.  
  540.     chomp LIST
  541.  
  542.     chomp   This safer version of the "chop" entry in this manpage
  543.             removes any trailing string that corresponds to the
  544.             current value of `$/' (also known as
  545.             $INPUT_RECORD_SEPARATOR in the `English' module). It
  546.             returns the total number of characters removed from all
  547.             its arguments. It's often used to remove the newline
  548.             from the end of an input record when you're worried that
  549.             the final record may be missing its newline. When in
  550.             paragraph mode (`$/ = ""'), it removes all trailing
  551.             newlines from the string. If VARIABLE is omitted, it
  552.             chomps `$_'. Example:
  553.  
  554.                 while (<>) {
  555.                 chomp;    # avoid \n on last field
  556.                 @array = split(/:/);
  557.                 # ...
  558.                 }
  559.  
  560.  
  561.             You can actually chomp anything that's an lvalue,
  562.             including an assignment:
  563.  
  564.                 chomp($cwd = `pwd`);
  565.                 chomp($answer = <STDIN>);
  566.  
  567.  
  568.             If you chomp a list, each element is chomped, and the
  569.             total number of characters removed is returned.
  570.  
  571.     chop VARIABLE
  572.  
  573.     chop LIST
  574.  
  575.     chop    Chops off the last character of a string and returns the
  576.             character chopped. It's used primarily to remove the
  577.             newline from the end of an input record, but is much
  578.             more efficient than `s/\n//' because it neither scans
  579.             nor copies the string. If VARIABLE is omitted, chops
  580.             `$_'. Example:
  581.  
  582.                 while (<>) {
  583.                 chop;    # avoid \n on last field
  584.                 @array = split(/:/);
  585.                 #...
  586.                 }
  587.  
  588.  
  589.             You can actually chop anything that's an lvalue,
  590.             including an assignment:
  591.  
  592.                 chop($cwd = `pwd`);
  593.                 chop($answer = <STDIN>);
  594.  
  595.  
  596.             If you chop a list, each element is chopped. Only the
  597.             value of the last `chop()' is returned.
  598.  
  599.             Note that `chop()' returns the last character. To return
  600.             all but the last character, use `substr($string, 0, -
  601.             1)'.
  602.  
  603.     chown LIST
  604.             Changes the owner (and group) of a list of files. The
  605.             first two elements of the list must be the *NUMERICAL*
  606.             uid and gid, in that order. Returns the number of files
  607.             successfully changed.
  608.  
  609.                 $cnt = chown $uid, $gid, 'foo', 'bar';
  610.                 chown $uid, $gid, @filenames;
  611.  
  612.  
  613.             Here's an example that looks up nonnumeric uids in the
  614.             passwd file:
  615.  
  616.                 print "User: ";
  617.                 chop($user = <STDIN>);
  618.                 print "Files: ";
  619.                 chop($pattern = <STDIN>);
  620.  
  621.                 ($login,$pass,$uid,$gid) = getpwnam($user)
  622.                 or die "$user not in passwd file";
  623.  
  624.                 @ary = glob($pattern);    # expand filenames
  625.                 chown $uid, $gid, @ary;
  626.  
  627.  
  628.             On most systems, you are not allowed to change the
  629.             ownership of the file unless you're the superuser,
  630.             although you should be able to change the group to any
  631.             of your secondary groups. On insecure systems, these
  632.             restrictions may be relaxed, but this is not a portable
  633.             assumption.
  634.  
  635.     chr NUMBER
  636.  
  637.     chr     Returns the character represented by that NUMBER in the
  638.             character set. For example, `chr(65)' is `"A"' in ASCII.
  639.             For the reverse, use the "ord" entry in this manpage.
  640.  
  641.             If NUMBER is omitted, uses `$_'.
  642.  
  643.     chroot FILENAME
  644.  
  645.     chroot  This function works like the system call by the same name:
  646.             it makes the named directory the new root directory for
  647.             all further pathnames that begin with a `"/"' by your
  648.             process and all its children. (It doesn't change your
  649.             current working directory, which is unaffected.) For
  650.             security reasons, this call is restricted to the
  651.             superuser. If FILENAME is omitted, does a `chroot()' to
  652.             `$_'.
  653.  
  654.     close FILEHANDLE
  655.  
  656.     close   Closes the file or pipe associated with the file handle,
  657.             returning TRUE only if stdio successfully flushes
  658.             buffers and closes the system file descriptor. Closes
  659.             the currently selected filehandle if the argument is
  660.             omitted.
  661.  
  662.             You don't have to close FILEHANDLE if you are
  663.             immediately going to do another `open()' on it, because
  664.             `open()' will close it for you. (See `open()'.) However,
  665.             an explicit `close()' on an input file resets the line
  666.             counter (`$.'), while the implicit close done by
  667.             `open()' does not.
  668.  
  669.             If the file handle came from a piped open `close()' will
  670.             additionally return FALSE if one of the other system
  671.             calls involved fails or if the program exits with non-
  672.             zero status. (If the only problem was that the program
  673.             exited non-zero `$!' will be set to `0'.) Closing a pipe
  674.             also waits for the process executing on the pipe to
  675.             complete, in case you want to look at the output of the
  676.             pipe afterwards, and implicitly puts the exit status
  677.             value of that command into `$?'.
  678.  
  679.             Example:
  680.  
  681.                 open(OUTPUT, '|sort >foo')  # pipe to sort
  682.                     or die "Can't start sort: $!";
  683.                 #...            # print stuff to output
  684.                 close OUTPUT        # wait for sort to finish
  685.                     or warn $! ? "Error closing sort pipe: $!"
  686.                                : "Exit status $? from sort";
  687.                 open(INPUT, 'foo')        # get sort's results
  688.                     or die "Can't open 'foo' for input: $!";
  689.  
  690.  
  691.             FILEHANDLE may be an expression whose value can be used
  692.             as an indirect filehandle, usually the real filehandle
  693.             name.
  694.  
  695.     closedir DIRHANDLE
  696.             Closes a directory opened by `opendir()' and returns the
  697.             success of that system call.
  698.  
  699.             DIRHANDLE may be an expression whose value can be used
  700.             as an indirect dirhandle, usually the real dirhandle
  701.             name.
  702.  
  703.     connect SOCKET,NAME
  704.             Attempts to connect to a remote socket, just as the
  705.             connect system call does. Returns TRUE if it succeeded,
  706.             FALSE otherwise. NAME should be a packed address of the
  707.             appropriate type for the socket. See the examples in the
  708.             section on "Sockets: Client/Server Communication" in the
  709.             perlipc manpage.
  710.  
  711.     continue BLOCK
  712.             Actually a flow control statement rather than a
  713.             function. If there is a `continue' BLOCK attached to a
  714.             BLOCK (typically in a `while' or `foreach'), it is
  715.             always executed just before the conditional is about to
  716.             be evaluated again, just like the third part of a `for'
  717.             loop in C. Thus it can be used to increment a loop
  718.             variable, even when the loop has been continued via the
  719.             `next' statement (which is similar to the C `continue'
  720.             statement).
  721.  
  722.             `last', `next', or `redo' may appear within a `continue'
  723.             block. `last' and `redo' will behave as if they had been
  724.             executed within the main block. So will `next', but
  725.             since it will execute a `continue' block, it may be more
  726.             entertaining.
  727.  
  728.                 while (EXPR) {
  729.                 ### redo always comes here
  730.                 do_something;
  731.                 } continue {
  732.                 ### next always comes here
  733.                 do_something_else;
  734.                 # then back the top to re-check EXPR
  735.                 }
  736.                 ### last always comes here
  737.  
  738.  
  739.             Omitting the `continue' section is semantically
  740.             equivalent to using an empty one, logically enough. In
  741.             that case, `next' goes directly back to check the
  742.             condition at the top of the loop.
  743.  
  744.     cos EXPR
  745.             Returns the cosine of EXPR (expressed in radians). If
  746.             EXPR is omitted, takes cosine of `$_'.
  747.  
  748.             For the inverse cosine operation, you may use the
  749.             `POSIX::acos()' function, or use this relation:
  750.  
  751.                 sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
  752.  
  753.  
  754.     crypt PLAINTEXT,SALT
  755.             Encrypts a string exactly like the crypt(3) function in
  756.             the C library (assuming that you actually have a version
  757.             there that has not been extirpated as a potential
  758.             munition). This can prove useful for checking the
  759.             password file for lousy passwords, amongst other things.
  760.             Only the guys wearing white hats should do this.
  761.  
  762.             Note that `crypt()' is intended to be a one-way
  763.             function, much like breaking eggs to make an omelette.
  764.             There is no (known) corresponding decrypt function. As a
  765.             result, this function isn't all that useful for
  766.             cryptography. (For that, see your nearby CPAN mirror.)
  767.  
  768.             When verifying an existing encrypted string you should
  769.             use the encrypted text as the salt (like `crypt($plain,
  770.             $crypted) eq $crypted'). This allows your code to work
  771.             with the standard `crypt()' and with more exotic
  772.             implementations. When choosing a new salt create a
  773.             random two character string whose characters come from
  774.             the set `[./0-9A-Za-z]' (like `join '', ('.', '/', 0..9,
  775.             'A'..'Z', 'a'..'z')[rand 64, rand 64]').
  776.  
  777.             Here's an example that makes sure that whoever runs this
  778.             program knows their own password:
  779.  
  780.                 $pwd = (getpwuid($<))[1];
  781.  
  782.                 system "stty -echo";
  783.                 print "Password: ";
  784.                 chomp($word = <STDIN>);
  785.                 print "\n";
  786.                 system "stty echo";
  787.  
  788.                 if (crypt($word, $pwd) ne $pwd) {
  789.                 die "Sorry...\n";
  790.                 } else {
  791.                 print "ok\n";
  792.                 }
  793.  
  794.  
  795.             Of course, typing in your own password to whoever asks
  796.             you for it is unwise.
  797.  
  798.     dbmclose HASH
  799.             [This function has been largely superseded by the
  800.             `untie()' function.]
  801.  
  802.             Breaks the binding between a DBM file and a hash.
  803.  
  804.     dbmopen HASH,DBNAME,MODE
  805.             [This function has been largely superseded by the
  806.             `tie()' function.]
  807.  
  808.             This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or
  809.             Berkeley DB file to a hash. HASH is the name of the
  810.             hash. (Unlike normal `open()', the first argument is
  811.             *NOT* a filehandle, even though it looks like one).
  812.             DBNAME is the name of the database (without the .dir or
  813.             .pag extension if any). If the database does not exist,
  814.             it is created with protection specified by MODE (as
  815.             modified by the `umask()'). If your system supports only
  816.             the older DBM functions, you may perform only one
  817.             `dbmopen()' in your program. In older versions of Perl,
  818.             if your system had neither DBM nor ndbm, calling
  819.             `dbmopen()' produced a fatal error; it now falls back to
  820.             sdbm(3).
  821.  
  822.             If you don't have write access to the DBM file, you can
  823.             only read hash variables, not set them. If you want to
  824.             test whether you can write, either use file tests or try
  825.             setting a dummy hash entry inside an `eval()', which
  826.             will trap the error.
  827.  
  828.             Note that functions such as `keys()' and `values()' may
  829.             return huge lists when used on large DBM files. You may
  830.             prefer to use the `each()' function to iterate over
  831.             large DBM files. Example:
  832.  
  833.                 # print out history file offsets
  834.                 dbmopen(%HIST,'/usr/lib/news/history',0666);
  835.                 while (($key,$val) = each %HIST) {
  836.                 print $key, ' = ', unpack('L',$val), "\n";
  837.                 }
  838.                 dbmclose(%HIST);
  839.  
  840.  
  841.             See also the AnyDBM_File manpage for a more general
  842.             description of the pros and cons of the various dbm
  843.             approaches, as well as the DB_File manpage for a
  844.             particularly rich implementation.
  845.  
  846.             You can control which DBM library you use by loading
  847.             that library before you call dbmopen():
  848.  
  849.                 use DB_File;
  850.                 dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db")
  851.                 or die "Can't open netscape history file: $!";
  852.  
  853.  
  854.     defined EXPR
  855.  
  856.     defined Returns a Boolean value telling whether EXPR has a value
  857.             other than the undefined value `undef'. If EXPR is not
  858.             present, `$_' will be checked.
  859.  
  860.             Many operations return `undef' to indicate failure, end
  861.             of file, system error, uninitialized variable, and other
  862.             exceptional conditions. This function allows you to
  863.             distinguish `undef' from other values. (A simple Boolean
  864.             test will not distinguish among `undef', zero, the empty
  865.             string, and `"0"', which are all equally false.) Note
  866.             that since `undef' is a valid scalar, its presence
  867.             doesn't *necessarily* indicate an exceptional condition:
  868.             `pop()' returns `undef' when its argument is an empty
  869.             array, *or* when the element to return happens to be
  870.             `undef'.
  871.  
  872.             You may also use `defined()' to check whether a
  873.             subroutine exists, by saying `defined &func' without
  874.             parentheses. On the other hand, use of `defined()' upon
  875.             aggregates (hashes and arrays) is not guaranteed to
  876.             produce intuitive results, and should probably be
  877.             avoided.
  878.  
  879.             When used on a hash element, it tells you whether the
  880.             value is defined, not whether the key exists in the
  881.             hash. Use the "exists" entry in this manpage for the
  882.             latter purpose.
  883.  
  884.             Examples:
  885.  
  886.                 print if defined $switch{'D'};
  887.                 print "$val\n" while defined($val = pop(@ary));
  888.                 die "Can't readlink $sym: $!"
  889.                 unless defined($value = readlink $sym);
  890.                 sub foo { defined &$bar ? &$bar(@_) : die "No bar"; }
  891.                 $debugging = 0 unless defined $debugging;
  892.  
  893.  
  894.             Note: Many folks tend to overuse `defined()', and then
  895.             are surprised to discover that the number `0' and `""'
  896.             (the zero-length string) are, in fact, defined values.
  897.             For example, if you say
  898.  
  899.                 "ab" =~ /a(.*)b/;
  900.  
  901.  
  902.             The pattern match succeeds, and `$1' is defined, despite
  903.             the fact that it matched "nothing". But it didn't really
  904.             match nothing--rather, it matched something that
  905.             happened to be zero characters long. This is all very
  906.             above-board and honest. When a function returns an
  907.             undefined value, it's an admission that it couldn't give
  908.             you an honest answer. So you should use `defined()' only
  909.             when you're questioning the integrity of what you're
  910.             trying to do. At other times, a simple comparison to `0'
  911.             or `""' is what you want.
  912.  
  913.             Currently, using `defined()' on an entire array or hash
  914.             reports whether memory for that aggregate has ever been
  915.             allocated. So an array you set to the empty list appears
  916.             undefined initially, and one that once was full and that
  917.             you then set to the empty list still appears defined.
  918.             You should instead use a simple test for size:
  919.  
  920.                 if (@an_array) { print "has array elements\n" }
  921.                 if (%a_hash)   { print "has hash members\n"   }
  922.  
  923.  
  924.             Using `undef()' on these, however, does clear their
  925.             memory and then report them as not defined anymore, but
  926.             you shouldn't do that unless you don't plan to use them
  927.             again, because it saves time when you load them up again
  928.             to have memory already ready to be filled. The normal
  929.             way to free up space used by an aggregate is to assign
  930.             the empty list.
  931.  
  932.             This counterintuitive behavior of `defined()' on
  933.             aggregates may be changed, fixed, or broken in a future
  934.             release of Perl.
  935.  
  936.             See also the "undef" entry in this manpage, the "exists"
  937.             entry in this manpage, the "ref" entry in this manpage.
  938.  
  939.     delete EXPR
  940.             Deletes the specified key(s) and their associated values
  941.             from a hash. For each key, returns the deleted value
  942.             associated with that key, or the undefined value if
  943.             there was no such key. Deleting from `$ENV{}' modifies
  944.             the environment. Deleting from a hash tied to a DBM file
  945.             deletes the entry from the DBM file. (But deleting from
  946.             a `tie()'d hash doesn't necessarily return anything.)
  947.  
  948.             The following deletes all the values of a hash:
  949.  
  950.                 foreach $key (keys %HASH) {
  951.                 delete $HASH{$key};
  952.                 }
  953.  
  954.  
  955.             And so does this:
  956.  
  957.                 delete @HASH{keys %HASH}
  958.  
  959.  
  960.             But both of these are slower than just assigning the
  961.             empty list or undefining it:
  962.  
  963.                 %hash = ();        # completely empty %hash
  964.                 undef %hash;    # forget %hash every existed
  965.  
  966.  
  967.             Note that the EXPR can be arbitrarily complicated as
  968.             long as the final operation is a hash element lookup or
  969.             hash slice:
  970.  
  971.                 delete $ref->[$x][$y]{$key};
  972.                 delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};
  973.  
  974.  
  975.     die LIST
  976.             Outside an `eval()', prints the value of LIST to
  977.             `STDERR' and exits with the current value of `$!'
  978.             (errno). If `$!' is `0', exits with the value of `($? >>
  979.             8)' (backtick `command` status). If `($? >> 8)' is `0',
  980.             exits with `255'. Inside an `eval(),' the error message
  981.             is stuffed into `$@' and the `eval()' is terminated with
  982.             the undefined value. This makes `die()' the way to raise
  983.             an exception.
  984.  
  985.             Equivalent examples:
  986.  
  987.                 die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
  988.                 chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
  989.  
  990.  
  991.             If the value of EXPR does not end in a newline, the
  992.             current script line number and input line number (if
  993.             any) are also printed, and a newline is supplied. Note
  994.             that the "input line number" (also known as "chunk") is
  995.             subject to whatever notion of "line" happens to be
  996.             currently in effect, and is also available as the
  997.             special variable `$.'. See the section on "$/" in the
  998.             perlvar manpage and the section on "$." in the perlvar
  999.             manpage.
  1000.  
  1001.             Hint: sometimes appending `", stopped"' to your message
  1002.             will cause it to make better sense when the string `"at
  1003.             foo line 123"' is appended. Suppose you are running
  1004.             script "canasta".
  1005.  
  1006.                 die "/etc/games is no good";
  1007.                 die "/etc/games is no good, stopped";
  1008.  
  1009.  
  1010.             produce, respectively
  1011.  
  1012.                 /etc/games is no good at canasta line 123.
  1013.                 /etc/games is no good, stopped at canasta line 123.
  1014.  
  1015.  
  1016.             See also exit(), warn(), and the Carp module.
  1017.  
  1018.             If LIST is empty and `$@' already contains a value
  1019.             (typically from a previous eval) that value is reused
  1020.             after appending `"\t...propagated"'. This is useful for
  1021.             propagating exceptions:
  1022.  
  1023.                 eval { ... };
  1024.                 die unless $@ =~ /Expected exception/;
  1025.  
  1026.  
  1027.             If `$@' is empty then the string `"Died"' is used.
  1028.  
  1029.             die() can also be called with a reference argument. If
  1030.             this happens to be trapped within an eval(), $@ contains
  1031.             the reference. This behavior permits a more elaborate
  1032.             exception handling implementation using objects that
  1033.             maintain arbitary state about the nature of the
  1034.             exception. Such a scheme is sometimes preferable to
  1035.             matching particular string values of $@ using regular
  1036.             expressions. Here's an example:
  1037.  
  1038.                 eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
  1039.                 if ($@) {
  1040.                     if (ref($@) && UNIVERSAL::isa($@,"Some::Module::Exception")) {
  1041.                         # handle Some::Module::Exception
  1042.                     }
  1043.                     else {
  1044.                         # handle all other possible exceptions
  1045.                     }
  1046.                 }
  1047.  
  1048.  
  1049.             Since perl will stringify uncaught exception messages
  1050.             before displaying them, you may want to overload
  1051.             stringification operations on such custom exception
  1052.             objects. See the overload manpage for details about
  1053.             that.
  1054.  
  1055.             You can arrange for a callback to be run just before the
  1056.             `die()' does its deed, by setting the `$SIG{__DIE__}'
  1057.             hook. The associated handler will be called with the
  1058.             error text and can change the error message, if it sees
  1059.             fit, by calling `die()' again. See the "$SIG{expr}"
  1060.             entry in the perlvar manpage for details on setting
  1061.             `%SIG' entries, and the section on "eval BLOCK" for some
  1062.             examples.
  1063.  
  1064.             Note that the `$SIG{__DIE__}' hook is currently called
  1065.             even inside eval()ed blocks/strings! If one wants the
  1066.             hook to do nothing in such situations, put
  1067.  
  1068.                 die @_ if $^S;
  1069.  
  1070.  
  1071.             as the first line of the handler (see the "$^S" entry in
  1072.             the perlvar manpage). Because this promotes action at a
  1073.             distance, this counterintuitive behavior may be fixed in
  1074.             a future release.
  1075.  
  1076.     do BLOCK
  1077.             Not really a function. Returns the value of the last
  1078.             command in the sequence of commands indicated by BLOCK.
  1079.             When modified by a loop modifier, executes the BLOCK
  1080.             once before testing the loop condition. (On other
  1081.             statements the loop modifiers test the conditional
  1082.             first.)
  1083.  
  1084.             `do BLOCK' does *not* count as a loop, so the loop
  1085.             control statements `next', `last', or `redo' cannot be
  1086.             used to leave or restart the block. See the perlsyn
  1087.             manpage for alternative strategies.
  1088.  
  1089.     do SUBROUTINE(LIST)
  1090.             A deprecated form of subroutine call. See the perlsub
  1091.             manpage.
  1092.  
  1093.     do EXPR Uses the value of EXPR as a filename and executes the
  1094.             contents of the file as a Perl script. Its primary use
  1095.             is to include subroutines from a Perl subroutine
  1096.             library.
  1097.  
  1098.                 do 'stat.pl';
  1099.  
  1100.  
  1101.             is just like
  1102.  
  1103.                 scalar eval `cat stat.pl`;
  1104.  
  1105.  
  1106.             except that it's more efficient and concise, keeps track
  1107.             of the current filename for error messages, searches the
  1108.             @INC libraries, and updates `%INC' if the file is found.
  1109.             See the "Predefined Names" entry in the perlvar manpage
  1110.             for these variables. It also differs in that code
  1111.             evaluated with `do FILENAME' cannot see lexicals in the
  1112.             enclosing scope; `eval STRING' does. It's the same,
  1113.             however, in that it does reparse the file every time you
  1114.             call it, so you probably don't want to do this inside a
  1115.             loop.
  1116.  
  1117.             If `do' cannot read the file, it returns undef and sets
  1118.             `$!' to the error. If `do' can read the file but cannot
  1119.             compile it, it returns undef and sets an error message
  1120.             in `$@'. If the file is successfully compiled, `do'
  1121.             returns the value of the last expression evaluated.
  1122.  
  1123.             Note that inclusion of library modules is better done
  1124.             with the `use()' and `require()' operators, which also
  1125.             do automatic error checking and raise an exception if
  1126.             there's a problem.
  1127.  
  1128.             You might like to use `do' to read in a program
  1129.             configuration file. Manual error checking can be done
  1130.             this way:
  1131.  
  1132.                 # read in config files: system first, then user 
  1133.                 for $file ("/share/prog/defaults.rc",
  1134.                            "$ENV{HOME}/.someprogrc") 
  1135.                {
  1136.                 unless ($return = do $file) {
  1137.                     warn "couldn't parse $file: $@" if $@;
  1138.                     warn "couldn't do $file: $!"    unless defined $return;
  1139.                     warn "couldn't run $file"       unless $return;
  1140.                 }
  1141.                 }
  1142.  
  1143.  
  1144.     dump LABEL
  1145.  
  1146.     dump    This causes an immediate core dump. Primarily this is so
  1147.             that you can use the undump program to turn your core
  1148.             dump into an executable binary after having initialized
  1149.             all your variables at the beginning of the program. When
  1150.             the new binary is executed it will begin by executing a
  1151.             `goto LABEL' (with all the restrictions that `goto'
  1152.             suffers). Think of it as a goto with an intervening core
  1153.             dump and reincarnation. If `LABEL' is omitted, restarts
  1154.             the program from the top. WARNING: Any files opened at
  1155.             the time of the dump will NOT be open any more when the
  1156.             program is reincarnated, with possible resulting
  1157.             confusion on the part of Perl. See also -u option in the
  1158.             perlrun manpage.
  1159.  
  1160.             Example:
  1161.  
  1162.                 #!/usr/bin/perl
  1163.                 require 'getopt.pl';
  1164.                 require 'stat.pl';
  1165.                 %days = (
  1166.                 'Sun' => 1,
  1167.                 'Mon' => 2,
  1168.                 'Tue' => 3,
  1169.                 'Wed' => 4,
  1170.                 'Thu' => 5,
  1171.                 'Fri' => 6,
  1172.                 'Sat' => 7,
  1173.                 );
  1174.  
  1175.                 dump QUICKSTART if $ARGV[0] eq '-d';
  1176.  
  1177.                 QUICKSTART:
  1178.                 Getopt('f');
  1179.  
  1180.  
  1181.             This operator is largely obsolete, partly because it's
  1182.             very hard to convert a core file into an executable, and
  1183.             because the real perl-to-C compiler has superseded it.
  1184.  
  1185.     each HASH
  1186.             When called in list context, returns a 2-element list
  1187.             consisting of the key and value for the next element of
  1188.             a hash, so that you can iterate over it. When called in
  1189.             scalar context, returns the key for only the "next"
  1190.             element in the hash. (Note: Keys may be `"0"' or `""',
  1191.             which are logically false; you may wish to avoid
  1192.             constructs like `while ($k = each %foo) {}' for this
  1193.             reason.)
  1194.  
  1195.             Entries are returned in an apparently random order. The
  1196.             actual random order is subject to change in future
  1197.             versions of perl, but it is guaranteed to be in the same
  1198.             order as either the `keys()' or `values()' function
  1199.             would produce on the same (unmodified) hash.
  1200.  
  1201.             When the hash is entirely read, a null array is returned
  1202.             in list context (which when assigned produces a FALSE
  1203.             (`0') value), and `undef' in scalar context. The next
  1204.             call to `each()' after that will start iterating again.
  1205.             There is a single iterator for each hash, shared by all
  1206.             `each()', `keys()', and `values()' function calls in the
  1207.             program; it can be reset by reading all the elements
  1208.             from the hash, or by evaluating `keys HASH' or `values
  1209.             HASH'. If you add or delete elements of a hash while
  1210.             you're iterating over it, you may get entries skipped or
  1211.             duplicated, so don't.
  1212.  
  1213.             The following prints out your environment like the
  1214.             printenv(1) program, only in a different order:
  1215.  
  1216.                 while (($key,$value) = each %ENV) {
  1217.                 print "$key=$value\n";
  1218.                 }
  1219.  
  1220.  
  1221.             See also `keys()', `values()' and `sort()'.
  1222.  
  1223.     eof FILEHANDLE
  1224.  
  1225.     eof ()
  1226.  
  1227.     eof     Returns 1 if the next read on FILEHANDLE will return end of
  1228.             file, or if FILEHANDLE is not open. FILEHANDLE may be an
  1229.             expression whose value gives the real filehandle. (Note
  1230.             that this function actually reads a character and then
  1231.             `ungetc()'s it, so isn't very useful in an interactive
  1232.             context.) Do not read from a terminal file (or call
  1233.             `eof(FILEHANDLE)' on it) after end-of-file is reached.
  1234.             Filetypes such as terminals may lose the end-of-file
  1235.             condition if you do.
  1236.  
  1237.             An `eof' without an argument uses the last file read as
  1238.             argument. Using `eof()' with empty parentheses is very
  1239.             different. It indicates the pseudo file formed of the
  1240.             files listed on the command line, i.e., `eof()' is
  1241.             reasonable to use inside a `while (<>)' loop to detect
  1242.             the end of only the last file. Use `eof(ARGV)' or eof
  1243.             without the parentheses to test *EACH* file in a while
  1244.             (<>) loop. Examples:
  1245.  
  1246.                 # reset line numbering on each input file
  1247.                 while (<>) {
  1248.                 next if /^\s*#/;    # skip comments 
  1249.                 print "$.\t$_";
  1250.                 } continue {
  1251.                 close ARGV  if eof;    # Not eof()!
  1252.                 }
  1253.  
  1254.                 # insert dashes just before last line of last file
  1255.                 while (<>) {
  1256.                 if (eof()) {        # check for end of current file
  1257.                     print "--------------\n";
  1258.                     close(ARGV);    # close or last; is needed if we
  1259.                             # are reading from the terminal
  1260.                 }
  1261.                 print;
  1262.                 }
  1263.  
  1264.  
  1265.             Practical hint: you almost never need to use `eof' in
  1266.             Perl, because the input operators return false values
  1267.             when they run out of data, or if there was an error.
  1268.  
  1269.     eval EXPR
  1270.  
  1271.     eval BLOCK
  1272.             In the first form, the return value of EXPR is parsed
  1273.             and executed as if it were a little Perl program. The
  1274.             value of the expression (which is itself determined
  1275.             within scalar context) is first parsed, and if there
  1276.             weren't any errors, executed in the context of the
  1277.             current Perl program, so that any variable settings or
  1278.             subroutine and format definitions remain afterwards.
  1279.             Note that the value is parsed every time the eval
  1280.             executes. If EXPR is omitted, evaluates `$_'. This form
  1281.             is typically used to delay parsing and subsequent
  1282.             execution of the text of EXPR until run time.
  1283.  
  1284.             In the second form, the code within the BLOCK is parsed
  1285.             only once--at the same time the code surrounding the
  1286.             eval itself was parsed--and executed within the context
  1287.             of the current Perl program. This form is typically used
  1288.             to trap exceptions more efficiently than the first (see
  1289.             below), while also providing the benefit of checking the
  1290.             code within BLOCK at compile time.
  1291.  
  1292.             The final semicolon, if any, may be omitted from the
  1293.             value of EXPR or within the BLOCK.
  1294.  
  1295.             In both forms, the value returned is the value of the
  1296.             last expression evaluated inside the mini-program; a
  1297.             return statement may be also used, just as with
  1298.             subroutines. The expression providing the return value
  1299.             is evaluated in void, scalar, or list context, depending
  1300.             on the context of the eval itself. See the "wantarray"
  1301.             entry in this manpage for more on how the evaluation
  1302.             context can be determined.
  1303.  
  1304.             If there is a syntax error or runtime error, or a
  1305.             `die()' statement is executed, an undefined value is
  1306.             returned by `eval()', and `$@' is set to the error
  1307.             message. If there was no error, `$@' is guaranteed to be
  1308.             a null string. Beware that using `eval()' neither
  1309.             silences perl from printing warnings to STDERR, nor does
  1310.             it stuff the text of warning messages into `$@'. To do
  1311.             either of those, you have to use the `$SIG{__WARN__}'
  1312.             facility. See the "warn" entry in this manpage and the
  1313.             perlvar manpage.
  1314.  
  1315.             Note that, because `eval()' traps otherwise-fatal
  1316.             errors, it is useful for determining whether a
  1317.             particular feature (such as `socket()' or `symlink()')
  1318.             is implemented. It is also Perl's exception trapping
  1319.             mechanism, where the die operator is used to raise
  1320.             exceptions.
  1321.  
  1322.             If the code to be executed doesn't vary, you may use the
  1323.             eval-BLOCK form to trap run-time errors without
  1324.             incurring the penalty of recompiling each time. The
  1325.             error, if any, is still returned in `$@'. Examples:
  1326.  
  1327.                 # make divide-by-zero nonfatal
  1328.                 eval { $answer = $a / $b; }; warn $@ if $@;
  1329.  
  1330.                 # same thing, but less efficient
  1331.                 eval '$answer = $a / $b'; warn $@ if $@;
  1332.  
  1333.                 # a compile-time error
  1334.                 eval { $answer = };            # WRONG
  1335.  
  1336.                 # a run-time error
  1337.                 eval '$answer =';    # sets $@
  1338.  
  1339.  
  1340.             Due to the current arguably broken state of `__DIE__'
  1341.             hooks, when using the `eval{}' form as an exception trap
  1342.             in libraries, you may wish not to trigger any `__DIE__'
  1343.             hooks that user code may have installed. You can use the
  1344.             `local $SIG{__DIE__}' construct for this purpose, as
  1345.             shown in this example:
  1346.  
  1347.                 # a very private exception trap for divide-by-zero
  1348.                 eval { local $SIG{'__DIE__'}; $answer = $a / $b; };
  1349.                 warn $@ if $@;
  1350.  
  1351.  
  1352.             This is especially significant, given that `__DIE__'
  1353.             hooks can call `die()' again, which has the effect of
  1354.             changing their error messages:
  1355.  
  1356.                 # __DIE__ hooks may modify error messages
  1357.                 {
  1358.                    local $SIG{'__DIE__'} =
  1359.                           sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
  1360.                    eval { die "foo lives here" };
  1361.                    print $@ if $@;                # prints "bar lives here"
  1362.                 }
  1363.  
  1364.  
  1365.             Because this promotes action at a distance, this
  1366.             counterintuive behavior may be fixed in a future
  1367.             release.
  1368.  
  1369.             With an `eval()', you should be especially careful to
  1370.             remember what's being looked at when:
  1371.  
  1372.                 eval $x;        # CASE 1
  1373.                 eval "$x";        # CASE 2
  1374.  
  1375.                 eval '$x';        # CASE 3
  1376.                 eval { $x };    # CASE 4
  1377.  
  1378.                 eval "\$$x++";    # CASE 5
  1379.                 $$x++;        # CASE 6
  1380.  
  1381.  
  1382.             Cases 1 and 2 above behave identically: they run the
  1383.             code contained in the variable `$x'. (Although case 2
  1384.             has misleading double quotes making the reader wonder
  1385.             what else might be happening (nothing is).) Cases 3 and
  1386.             4 likewise behave in the same way: they run the code
  1387.             `'$x'', which does nothing but return the value of `$x'.
  1388.             (Case 4 is preferred for purely visual reasons, but it
  1389.             also has the advantage of compiling at compile-time
  1390.             instead of at run-time.) Case 5 is a place where
  1391.             normally you *WOULD* like to use double quotes, except
  1392.             that in this particular situation, you can just use
  1393.             symbolic references instead, as in case 6.
  1394.  
  1395.             `eval BLOCK' does *not* count as a loop, so the loop
  1396.             control statements `next', `last', or `redo' cannot be
  1397.             used to leave or restart the block.
  1398.  
  1399.     exec LIST
  1400.  
  1401.     exec PROGRAM LIST
  1402.             The `exec()' function executes a system command *AND
  1403.             NEVER RETURNS* - use `system()' instead of `exec()' if
  1404.             you want it to return. It fails and returns FALSE only
  1405.             if the command does not exist *and* it is executed
  1406.             directly instead of via your system's command shell (see
  1407.             below).
  1408.  
  1409.             Since it's a common mistake to use `exec()' instead of
  1410.             `system()', Perl warns you if there is a following
  1411.             statement which isn't `die()', `warn()', or `exit()' (if
  1412.             `-w' is set - but you always do that). If you *really*
  1413.             want to follow an `exec()' with some other statement,
  1414.             you can use one of these styles to avoid the warning:
  1415.  
  1416.                 exec ('foo')   or print STDERR "couldn't exec foo: $!";
  1417.                 { exec ('foo') }; print STDERR "couldn't exec foo: $!";
  1418.  
  1419.  
  1420.             If there is more than one argument in LIST, or if LIST
  1421.             is an array with more than one value, calls execvp(3)
  1422.             with the arguments in LIST. If there is only one scalar
  1423.             argument or an array with one element in it, the
  1424.             argument is checked for shell metacharacters, and if
  1425.             there are any, the entire argument is passed to the
  1426.             system's command shell for parsing (this is `/bin/sh -c'
  1427.             on Unix platforms, but varies on other platforms). If
  1428.             there are no shell metacharacters in the argument, it is
  1429.             split into words and passed directly to `execvp()',
  1430.             which is more efficient. Note: `exec()' and `system()'
  1431.             do not flush your output buffer, so you may need to set
  1432.             `$|' to avoid lost output. Examples:
  1433.  
  1434.                 exec '/bin/echo', 'Your arguments are: ', @ARGV;
  1435.                 exec "sort $outfile | uniq";
  1436.  
  1437.  
  1438.             If you don't really want to execute the first argument,
  1439.             but want to lie to the program you are executing about
  1440.             its own name, you can specify the program you actually
  1441.             want to run as an "indirect object" (without a comma) in
  1442.             front of the LIST. (This always forces interpretation of
  1443.             the LIST as a multivalued list, even if there is only a
  1444.             single scalar in the list.) Example:
  1445.  
  1446.                 $shell = '/bin/csh';
  1447.                 exec $shell '-sh';        # pretend it's a login shell
  1448.  
  1449.  
  1450.             or, more directly,
  1451.  
  1452.                 exec {'/bin/csh'} '-sh';    # pretend it's a login shell
  1453.  
  1454.  
  1455.             When the arguments get executed via the system shell,
  1456.             results will be subject to its quirks and capabilities.
  1457.             See the section on "`STRING`" in the perlop manpage for
  1458.             details.
  1459.  
  1460.             Using an indirect object with `exec()' or `system()' is
  1461.             also more secure. This usage forces interpretation of
  1462.             the arguments as a multivalued list, even if the list
  1463.             had just one argument. That way you're safe from the
  1464.             shell expanding wildcards or splitting up words with
  1465.             whitespace in them.
  1466.  
  1467.                 @args = ( "echo surprise" );
  1468.  
  1469.                 exec @args;               # subject to shell escapes
  1470.                                             # if @args == 1
  1471.                 exec { $args[0] } @args;  # safe even with one-arg list
  1472.  
  1473.  
  1474.             The first version, the one without the indirect object,
  1475.             ran the *echo* program, passing it `"surprise"' an
  1476.             argument. The second version didn't--it tried to run a
  1477.             program literally called *"echo surprise"*, didn't find
  1478.             it, and set `$?' to a non-zero value indicating failure.
  1479.  
  1480.             Note that `exec()' will not call your `END' blocks, nor
  1481.             will it call any `DESTROY' methods in your objects.
  1482.  
  1483.     exists EXPR
  1484.             Returns TRUE if the specified hash key exists in its
  1485.             hash array, even if the corresponding value is
  1486.             undefined.
  1487.  
  1488.                 print "Exists\n"     if exists $array{$key};
  1489.                 print "Defined\n"     if defined $array{$key};
  1490.                 print "True\n"      if $array{$key};
  1491.  
  1492.  
  1493.             A hash element can be TRUE only if it's defined, and
  1494.             defined if it exists, but the reverse doesn't
  1495.             necessarily hold true.
  1496.  
  1497.             Note that the EXPR can be arbitrarily complicated as
  1498.             long as the final operation is a hash key lookup:
  1499.  
  1500.                 if (exists $ref->{A}->{B}->{$key})     { }
  1501.                 if (exists $hash{A}{B}{$key})     { }
  1502.  
  1503.  
  1504.             Although the last element will not spring into existence
  1505.             just because its existence was tested, intervening ones
  1506.             will. Thus `$ref->{"A"}' and `$ref->{"A"}->{"B"}' will
  1507.             spring into existence due to the existence test for a
  1508.             $key element. This happens anywhere the arrow operator
  1509.             is used, including even
  1510.  
  1511.                 undef $ref;
  1512.                 if (exists $ref->{"Some key"})    { }
  1513.                 print $ref;         # prints HASH(0x80d3d5c)
  1514.  
  1515.  
  1516.             This surprising autovivification in what does not at
  1517.             first--or even second--glance appear to be an lvalue
  1518.             context may be fixed in a future release.
  1519.  
  1520.     exit EXPR
  1521.             Evaluates EXPR and exits immediately with that value.
  1522.             Example:
  1523.  
  1524.                 $ans = <STDIN>;
  1525.                 exit 0 if $ans =~ /^[Xx]/;
  1526.  
  1527.  
  1528.             See also `die()'. If EXPR is omitted, exits with `0'
  1529.             status. The only universally recognized values for EXPR
  1530.             are `0' for success and `1' for error; other values are
  1531.             subject to interpretation depending on the environment
  1532.             in which the Perl program is running. For example,
  1533.             exiting 69 (EX_UNAVAILABLE) from a *sendmail* incoming-
  1534.             mail filter will cause the mailer to return the item
  1535.             undelivered, but that's not true everywhere.
  1536.  
  1537.             Don't use `exit()' to abort a subroutine if there's any
  1538.             chance that someone might want to trap whatever error
  1539.             happened. Use `die()' instead, which can be trapped by
  1540.             an `eval()'.
  1541.  
  1542.             The exit() function does not always exit immediately. It
  1543.             calls any defined `END' routines first, but these `END'
  1544.             routines may not themselves abort the exit. Likewise any
  1545.             object destructors that need to be called are called
  1546.             before the real exit. If this is a problem, you can call
  1547.             `POSIX:_exit($status)' to avoid END and destructor
  1548.             processing. See the perlsub manpage for details.
  1549.  
  1550.     exp EXPR
  1551.  
  1552.     exp     Returns *e* (the natural logarithm base) to the power of
  1553.             EXPR. If EXPR is omitted, gives `exp($_)'.
  1554.  
  1555.     fcntl FILEHANDLE,FUNCTION,SCALAR
  1556.             Implements the fcntl(2) function. You'll probably have
  1557.             to say
  1558.  
  1559.                 use Fcntl;
  1560.  
  1561.  
  1562.             first to get the correct constant definitions. Argument
  1563.             processing and value return works just like `ioctl()'
  1564.             below. For example:
  1565.  
  1566.                 use Fcntl;
  1567.                 fcntl($filehandle, F_GETFL, $packed_return_buffer)
  1568.                 or die "can't fcntl F_GETFL: $!";
  1569.  
  1570.  
  1571.             You don't have to check for `defined()' on the return
  1572.             from `fnctl()'. Like `ioctl()', it maps a `0' return
  1573.             from the system call into "`0' but true" in Perl. This
  1574.             string is true in boolean context and `0' in numeric
  1575.             context. It is also exempt from the normal -w warnings
  1576.             on improper numeric conversions.
  1577.  
  1578.             Note that `fcntl()' will produce a fatal error if used
  1579.             on a machine that doesn't implement fcntl(2). See the
  1580.             Fcntl module or your fcntl(2) manpage to learn what
  1581.             functions are available on your system.
  1582.  
  1583.     fileno FILEHANDLE
  1584.             Returns the file descriptor for a filehandle, or
  1585.             undefined if the filehandle is not open. This is mainly
  1586.             useful for constructing bitmaps for `select()' and low-
  1587.             level POSIX tty-handling operations. If FILEHANDLE is an
  1588.             expression, the value is taken as an indirect
  1589.             filehandle, generally its name.
  1590.  
  1591.             You can use this to find out whether two handles refer
  1592.             to the same underlying descriptor:
  1593.  
  1594.                 if (fileno(THIS) == fileno(THAT)) {
  1595.                 print "THIS and THAT are dups\n";
  1596.                 } 
  1597.  
  1598.  
  1599.     flock FILEHANDLE,OPERATION
  1600.             Calls flock(2), or an emulation of it, on FILEHANDLE.
  1601.             Returns TRUE for success, FALSE on failure. Produces a
  1602.             fatal error if used on a machine that doesn't implement
  1603.             flock(2), fcntl(2) locking, or lockf(3). `flock()' is
  1604.             Perl's portable file locking interface, although it
  1605.             locks only entire files, not records.
  1606.  
  1607.             Two potentially non-obvious but traditional `flock'
  1608.             semantics are that it waits indefinitely until the lock
  1609.             is granted, and that its locks merely advisory. Such
  1610.             discretionary locks are more flexible, but offer fewer
  1611.             guarantees. This means that files locked with `flock()'
  1612.             may be modified by programs that do not also use
  1613.             `flock()'. See the perlport manpage, your port's
  1614.             specific documentation, or your system-specific local
  1615.             manpages for details. It's best to assume traditional
  1616.             behavior if you're writing portable programs. (But if
  1617.             you're not, you should as always feel perfectly free to
  1618.             write for your own system's idiosyncrasies (sometimes
  1619.             called "features"). Slavish adherence to portability
  1620.             concerns shouldn't get in the way of your getting your
  1621.             job done.)
  1622.  
  1623.             OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN,
  1624.             possibly combined with LOCK_NB. These constants are
  1625.             traditionally valued 1, 2, 8 and 4, but you can use the
  1626.             symbolic names if import them from the Fcntl module,
  1627.             either individually, or as a group using the ':flock'
  1628.             tag. LOCK_SH requests a shared lock, LOCK_EX requests an
  1629.             exclusive lock, and LOCK_UN releases a previously
  1630.             requested lock. If LOCK_NB is added to LOCK_SH or
  1631.             LOCK_EX then `flock()' will return immediately rather
  1632.             than blocking waiting for the lock (check the return
  1633.             status to see if you got it).
  1634.  
  1635.             To avoid the possibility of miscoordination, Perl now
  1636.             flushes FILEHANDLE before locking or unlocking it.
  1637.  
  1638.             Note that the emulation built with lockf(3) doesn't
  1639.             provide shared locks, and it requires that FILEHANDLE be
  1640.             open with write intent. These are the semantics that
  1641.             lockf(3) implements. Most if not all systems implement
  1642.             lockf(3) in terms of fcntl(2) locking, though, so the
  1643.             differing semantics shouldn't bite too many people.
  1644.  
  1645.             Note also that some versions of `flock()' cannot lock
  1646.             things over the network; you would need to use the more
  1647.             system-specific `fcntl()' for that. If you like you can
  1648.             force Perl to ignore your system's flock(2) function,
  1649.             and so provide its own fcntl(2)-based emulation, by
  1650.             passing the switch `-Ud_flock' to the Configure program
  1651.             when you configure perl.
  1652.  
  1653.             Here's a mailbox appender for BSD systems.
  1654.  
  1655.                 use Fcntl ':flock'; # import LOCK_* constants
  1656.  
  1657.                 sub lock {
  1658.                 flock(MBOX,LOCK_EX);
  1659.                 # and, in case someone appended
  1660.                 # while we were waiting...
  1661.                 seek(MBOX, 0, 2);
  1662.                 }
  1663.  
  1664.                 sub unlock {
  1665.                 flock(MBOX,LOCK_UN);
  1666.                 }
  1667.  
  1668.                 open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
  1669.                     or die "Can't open mailbox: $!";
  1670.  
  1671.                 lock();
  1672.                 print MBOX $msg,"\n\n";
  1673.                 unlock();
  1674.  
  1675.  
  1676.             On systems that support a real flock(), locks are
  1677.             inherited across fork() calls, whereas those that must
  1678.             resort to the more capricious fcntl() function lose the
  1679.             locks, making it harder to write servers.
  1680.  
  1681.             See also the DB_File manpage for other flock() examples.
  1682.  
  1683.     fork    Does a fork(2) system call to create a new process running
  1684.             the same program at the same point. It returns the child
  1685.             pid to the parent process, `0' to the child process, or
  1686.             `undef' if the fork is unsuccessful. File descriptors
  1687.             (and sometimes locks on those descriptors) are shared,
  1688.             while everything else is copied. On most systems
  1689.             supporting fork(), great care has gone into making it
  1690.             extremely efficient (for example, using copy-on-write
  1691.             technology on data pages), making it the dominant
  1692.             paradigm for multitasking over the last few decades.
  1693.  
  1694.             Note: unflushed buffers remain unflushed in both
  1695.             processes, which means you may need to set `$|'
  1696.             ($AUTOFLUSH in English) or call the `autoflush()' method
  1697.             of `IO::Handle' to avoid duplicate output.
  1698.  
  1699.             If you `fork()' without ever waiting on your children,
  1700.             you will accumulate zombies. On some systems, you can
  1701.             avoid this by setting `$SIG{CHLD}' to `"IGNORE"'. See
  1702.             also the perlipc manpage for more examples of forking
  1703.             and reaping moribund children.
  1704.  
  1705.             Note that if your forked child inherits system file
  1706.             descriptors like STDIN and STDOUT that are actually
  1707.             connected by a pipe or socket, even if you exit, then
  1708.             the remote server (such as, say, a CGI script or a
  1709.             backgrounded job launced from a remote shell) won't
  1710.             think you're done. You should reopen those to /dev/null
  1711.             if it's any issue.
  1712.  
  1713.     format  Declare a picture format for use by the `write()' function.
  1714.             For example:
  1715.  
  1716.                 format Something =
  1717.                 Test: @<<<<<<<< @||||| @>>>>>
  1718.                       $str,     $%,    '$' . int($num)
  1719.                 .
  1720.  
  1721.                 $str = "widget";
  1722.                 $num = $cost/$quantity;
  1723.                 $~ = 'Something';
  1724.                 write;
  1725.  
  1726.  
  1727.             See the perlform manpage for many details and examples.
  1728.  
  1729.     formline PICTURE,LIST
  1730.             This is an internal function used by `format's, though
  1731.             you may call it, too. It formats (see the perlform
  1732.             manpage) a list of values according to the contents of
  1733.             PICTURE, placing the output into the format output
  1734.             accumulator, `$^A' (or `$ACCUMULATOR' in English).
  1735.             Eventually, when a `write()' is done, the contents of
  1736.             `$^A' are written to some filehandle, but you could also
  1737.             read `$^A' yourself and then set `$^A' back to `""'.
  1738.             Note that a format typically does one `formline()' per
  1739.             line of form, but the `formline()' function itself
  1740.             doesn't care how many newlines are embedded in the
  1741.             PICTURE. This means that the `~' and `~~' tokens will
  1742.             treat the entire PICTURE as a single line. You may
  1743.             therefore need to use multiple formlines to implement a
  1744.             single record format, just like the format compiler.
  1745.  
  1746.             Be careful if you put double quotes around the picture,
  1747.             because an "`@'" character may be taken to mean the
  1748.             beginning of an array name. `formline()' always returns
  1749.             TRUE. See the perlform manpage for other examples.
  1750.  
  1751.     getc FILEHANDLE
  1752.  
  1753.     getc    Returns the next character from the input file attached to
  1754.             FILEHANDLE, or the undefined value at end of file, or if
  1755.             there was an error. If FILEHANDLE is omitted, reads from
  1756.             STDIN. This is not particularly efficient. However, it
  1757.             cannot be used by itself to fetch single characters
  1758.             without waiting for the user to hit enter. For that, try
  1759.             something more like:
  1760.  
  1761.                 if ($BSD_STYLE) {
  1762.                 system "stty cbreak </dev/tty >/dev/tty 2>&1";
  1763.                 }
  1764.                 else {
  1765.                 system "stty", '-icanon', 'eol', "\001";
  1766.                 }
  1767.  
  1768.                 $key = getc(STDIN);
  1769.  
  1770.                 if ($BSD_STYLE) {
  1771.                 system "stty -cbreak </dev/tty >/dev/tty 2>&1";
  1772.                 }
  1773.                 else {
  1774.                 system "stty", 'icanon', 'eol', '^@'; # ASCII null
  1775.                 }
  1776.                 print "\n";
  1777.  
  1778.  
  1779.             Determination of whether $BSD_STYLE should be set is
  1780.             left as an exercise to the reader.
  1781.  
  1782.             The `POSIX::getattr()' function can do this more
  1783.             portably on systems purporting POSIX compliance. See
  1784.             also the `Term::ReadKey' module from your nearest CPAN
  1785.             site; details on CPAN can be found on the "CPAN" entry
  1786.             in the perlmodlib manpage.
  1787.  
  1788.     getlogin
  1789.             Implements the C library function of the same name,
  1790.             which on most systems returns the current login from
  1791.             /etc/utmp, if any. If null, use `getpwuid()'.
  1792.  
  1793.                 $login = getlogin || getpwuid($<) || "Kilroy";
  1794.  
  1795.  
  1796.             Do not consider `getlogin()' for authentication: it is
  1797.             not as secure as `getpwuid()'.
  1798.  
  1799.     getpeername SOCKET
  1800.             Returns the packed sockaddr address of other end of the
  1801.             SOCKET connection.
  1802.  
  1803.                 use Socket;
  1804.                 $hersockaddr    = getpeername(SOCK);
  1805.                 ($port, $iaddr) = unpack_sockaddr_in($hersockaddr);
  1806.                 $herhostname    = gethostbyaddr($iaddr, AF_INET);
  1807.                 $herstraddr     = inet_ntoa($iaddr);
  1808.  
  1809.  
  1810.     getpgrp PID
  1811.             Returns the current process group for the specified PID.
  1812.             Use a PID of `0' to get the current process group for
  1813.             the current process. Will raise an exception if used on
  1814.             a machine that doesn't implement getpgrp(2). If PID is
  1815.             omitted, returns process group of current process. Note
  1816.             that the POSIX version of `getpgrp()' does not accept a
  1817.             PID argument, so only `PID==0' is truly portable.
  1818.  
  1819.     getppid Returns the process id of the parent process.
  1820.  
  1821.     getpriority WHICH,WHO
  1822.             Returns the current priority for a process, a process
  1823.             group, or a user. (See the getpriority(2) manpage.) Will
  1824.             raise a fatal exception if used on a machine that
  1825.             doesn't implement getpriority(2).
  1826.  
  1827.     getpwnam NAME
  1828.  
  1829.     getgrnam NAME
  1830.  
  1831.     gethostbyname NAME
  1832.  
  1833.     getnetbyname NAME
  1834.  
  1835.     getprotobyname NAME
  1836.  
  1837.     getpwuid UID
  1838.  
  1839.     getgrgid GID
  1840.  
  1841.     getservbyname NAME,PROTO
  1842.  
  1843.     gethostbyaddr ADDR,ADDRTYPE
  1844.  
  1845.     getnetbyaddr ADDR,ADDRTYPE
  1846.  
  1847.     getprotobynumber NUMBER
  1848.  
  1849.     getservbyport PORT,PROTO
  1850.  
  1851.     getpwent
  1852.  
  1853.     getgrent
  1854.  
  1855.     gethostent
  1856.  
  1857.     getnetent
  1858.  
  1859.     getprotoent
  1860.  
  1861.     getservent
  1862.  
  1863.     setpwent
  1864.  
  1865.     setgrent
  1866.  
  1867.     sethostent STAYOPEN
  1868.  
  1869.     setnetent STAYOPEN
  1870.  
  1871.     setprotoent STAYOPEN
  1872.  
  1873.     setservent STAYOPEN
  1874.  
  1875.     endpwent
  1876.  
  1877.     endgrent
  1878.  
  1879.     endhostent
  1880.  
  1881.     endnetent
  1882.  
  1883.     endprotoent
  1884.  
  1885.     endservent
  1886.             These routines perform the same functions as their
  1887.             counterparts in the system library. In list context, the
  1888.             return values from the various get routines are as
  1889.             follows:
  1890.  
  1891.                 ($name,$passwd,$uid,$gid,
  1892.                    $quota,$comment,$gcos,$dir,$shell,$expire) = getpw*
  1893.                 ($name,$passwd,$gid,$members) = getgr*
  1894.                 ($name,$aliases,$addrtype,$length,@addrs) = gethost*
  1895.                 ($name,$aliases,$addrtype,$net) = getnet*
  1896.                 ($name,$aliases,$proto) = getproto*
  1897.                 ($name,$aliases,$port,$proto) = getserv*
  1898.  
  1899.  
  1900.             (If the entry doesn't exist you get a null list.)
  1901.  
  1902.             In scalar context, you get the name, unless the function
  1903.             was a lookup by name, in which case you get the other
  1904.             thing, whatever it is. (If the entry doesn't exist you
  1905.             get the undefined value.) For example:
  1906.  
  1907.                 $uid   = getpwnam($name);
  1908.                 $name  = getpwuid($num);
  1909.                 $name  = getpwent();
  1910.                 $gid   = getgrnam($name);
  1911.                 $name  = getgrgid($num;
  1912.                 $name  = getgrent();
  1913.                 #etc.
  1914.  
  1915.  
  1916.             In *getpw*()* the fields `$quota', `$comment', and
  1917.             `$expire' are special cases in the sense that in many
  1918.             systems they are unsupported. If the `$quota' is
  1919.             unsupported, it is an empty scalar. If it is supported,
  1920.             it usually encodes the disk quota. If the `$comment'
  1921.             field is unsupported, it is an empty scalar. If it is
  1922.             supported it usually encodes some administrative comment
  1923.             about the user. In some systems the $quota field may be
  1924.             `$change' or `$age', fields that have to do with
  1925.             password aging. In some systems the `$comment' field may
  1926.             be `$class'. The `$expire' field, if present, encodes
  1927.             the expiration period of the account or the password.
  1928.             For the availability and the exact meaning of these
  1929.             fields in your system, please consult your getpwnam(3)
  1930.             documentation and your pwd.h file. You can also find out
  1931.             from within Perl what your `$quota' and `$comment'
  1932.             fields mean and whether you have the `$expire' field by
  1933.             using the `Config' module and the values `d_pwquota',
  1934.             `d_pwage', `d_pwchange', `d_pwcomment', and
  1935.             `d_pwexpire'. Shadow password files are only supported
  1936.             if your vendor has implemented them in the intuitive
  1937.             fashion that calling the regular C library routines gets
  1938.             the shadow versions if you're running under privilege.
  1939.             Those that incorrectly implement a separate library call
  1940.             are not supported.
  1941.  
  1942.             The `$members' value returned by *getgr*()* is a space
  1943.             separated list of the login names of the members of the
  1944.             group.
  1945.  
  1946.             For the *gethost*()* functions, if the `h_errno'
  1947.             variable is supported in C, it will be returned to you
  1948.             via `$?' if the function call fails. The `@addrs' value
  1949.             returned by a successful call is a list of the raw
  1950.             addresses returned by the corresponding system library
  1951.             call. In the Internet domain, each address is four bytes
  1952.             long and you can unpack it by saying something like:
  1953.  
  1954.                 ($a,$b,$c,$d) = unpack('C4',$addr[0]);
  1955.  
  1956.  
  1957.             The Socket library makes this slightly easier:
  1958.  
  1959.                 use Socket;
  1960.                 $iaddr = inet_aton("127.1"); # or whatever address
  1961.                 $name  = gethostbyaddr($iaddr, AF_INET);
  1962.  
  1963.                 # or going the other way
  1964.                 $straddr = inet_ntoa($iaddr");
  1965.  
  1966.  
  1967.             If you get tired of remembering which element of the
  1968.             return list contains which return value, by-name
  1969.             interfaces are also provided in modules: `File::stat',
  1970.             `Net::hostent', `Net::netent', `Net::protoent',
  1971.             `Net::servent', `Time::gmtime', `Time::localtime', and
  1972.             `User::grent'. These override the normal built-in,
  1973.             replacing them with versions that return objects with
  1974.             the appropriate names for each field. For example:
  1975.  
  1976.                use File::stat;
  1977.                use User::pwent;
  1978.                $is_his = (stat($filename)->uid == pwent($whoever)->uid);
  1979.  
  1980.  
  1981.             Even though it looks like they're the same method calls
  1982.             (uid), they aren't, because a `File::stat' object is
  1983.             different from a `User::pwent' object.
  1984.  
  1985.     getsockname SOCKET
  1986.             Returns the packed sockaddr address of this end of the
  1987.             SOCKET connection.
  1988.  
  1989.                 use Socket;
  1990.                 $mysockaddr = getsockname(SOCK);
  1991.                 ($port, $myaddr) = unpack_sockaddr_in($mysockaddr);
  1992.  
  1993.  
  1994.     getsockopt SOCKET,LEVEL,OPTNAME
  1995.             Returns the socket option requested, or undef if there
  1996.             is an error.
  1997.  
  1998.     glob EXPR
  1999.  
  2000.     glob    Returns the value of EXPR with filename expansions such as
  2001.             the standard Unix shell /bin/csh would do. This is the
  2002.             internal function implementing the `<*.c>' operator, but
  2003.             you can use it directly. If EXPR is omitted, `$_' is
  2004.             used. The `<*.c>' operator is discussed in more detail
  2005.             in the section on "I/O Operators" in the perlop manpage.
  2006.  
  2007.     gmtime EXPR
  2008.             Converts a time as returned by the time function to a 9-
  2009.             element array with the time localized for the standard
  2010.             Greenwich time zone. Typically used as follows:
  2011.  
  2012.                 #  0    1    2     3     4    5     6     7     8
  2013.                 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
  2014.                                     gmtime(time);
  2015.  
  2016.  
  2017.             All array elements are numeric, and come straight out of
  2018.             a struct tm. In particular this means that `$mon' has
  2019.             the range `0..11' and `$wday' has the range `0..6' with
  2020.             sunday as day `0'. Also, `$year' is the number of years
  2021.             since 1900, that is, `$year' is `123' in year 2023,
  2022.             *not* simply the last two digits of the year. If you
  2023.             assume it is, then you create non-Y2K-compliant
  2024.             programs--and you wouldn't want to do that, would you?
  2025.  
  2026.             If EXPR is omitted, does `gmtime(time())'.
  2027.  
  2028.             In scalar context, returns the ctime(3) value:
  2029.  
  2030.                 $now_string = gmtime;  # e.g., "Thu Oct 13 04:54:34 1994"
  2031.  
  2032.  
  2033.             Also see the `timegm()' function provided by the
  2034.             `Time::Local' module, and the strftime(3) function
  2035.             available via the POSIX module.
  2036.  
  2037.             This scalar value is not locale dependent (see the
  2038.             perllocale manpage), but is instead a Perl builtin. Also
  2039.             see the `Time::Local' module, and the strftime(3) and
  2040.             mktime(3) functions available via the POSIX module. To
  2041.             get somewhat similar but locale dependent date strings,
  2042.             set up your locale environment variables appropriately
  2043.             (please see the perllocale manpage) and try for example:
  2044.  
  2045.                 use POSIX qw(strftime);
  2046.                 $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
  2047.  
  2048.  
  2049.             Note that the `%a' and `%b' escapes, which represent the
  2050.             short forms of the day of the week and the month of the
  2051.             year, may not necessarily be three characters wide in
  2052.             all locales.
  2053.  
  2054.     goto LABEL
  2055.  
  2056.     goto EXPR
  2057.  
  2058.     goto &NAME
  2059.             The `goto-LABEL' form finds the statement labeled with
  2060.             LABEL and resumes execution there. It may not be used to
  2061.             go into any construct that requires initialization, such
  2062.             as a subroutine or a `foreach' loop. It also can't be
  2063.             used to go into a construct that is optimized away, or
  2064.             to get out of a block or subroutine given to `sort()'.
  2065.             It can be used to go almost anywhere else within the
  2066.             dynamic scope, including out of subroutines, but it's
  2067.             usually better to use some other construct such as
  2068.             `last' or `die()'. The author of Perl has never felt the
  2069.             need to use this form of `goto' (in Perl, that is--C is
  2070.             another matter).
  2071.  
  2072.             The `goto-EXPR' form expects a label name, whose scope
  2073.             will be resolved dynamically. This allows for computed
  2074.             `goto's per FORTRAN, but isn't necessarily recommended
  2075.             if you're optimizing for maintainability:
  2076.  
  2077.                 goto ("FOO", "BAR", "GLARCH")[$i];
  2078.  
  2079.  
  2080.             The `goto-&NAME' form is highly magical, and substitutes
  2081.             a call to the named subroutine for the currently running
  2082.             subroutine. This is used by `AUTOLOAD' subroutines that
  2083.             wish to load another subroutine and then pretend that
  2084.             the other subroutine had been called in the first place
  2085.             (except that any modifications to `@_' in the current
  2086.             subroutine are propagated to the other subroutine.)
  2087.             After the `goto', not even `caller()' will be able to
  2088.             tell that this routine was called first.
  2089.  
  2090.     grep BLOCK LIST
  2091.  
  2092.     grep EXPR,LIST
  2093.             This is similar in spirit to, but not the same as,
  2094.             grep(1) and its relatives. In particular, it is not
  2095.             limited to using regular expressions.
  2096.  
  2097.             Evaluates the BLOCK or EXPR for each element of LIST
  2098.             (locally setting `$_' to each element) and returns the
  2099.             list value consisting of those elements for which the
  2100.             expression evaluated to TRUE. In scalar context, returns
  2101.             the number of times the expression was TRUE.
  2102.  
  2103.                 @foo = grep(!/^#/, @bar);    # weed out comments
  2104.  
  2105.  
  2106.             or equivalently,
  2107.  
  2108.                 @foo = grep {!/^#/} @bar;    # weed out comments
  2109.  
  2110.  
  2111.             Note that, because `$_' is a reference into the list
  2112.             value, it can be used to modify the elements of the
  2113.             array. While this is useful and supported, it can cause
  2114.             bizarre results if the LIST is not a named array.
  2115.             Similarly, grep returns aliases into the original list,
  2116.             much as a for loop's index variable aliases the list
  2117.             elements. That is, modifying an element of a list
  2118.             returned by grep (for example, in a `foreach', `map()'
  2119.             or another `grep()') actually modifies the element in
  2120.             the original list. This is usually something to be
  2121.             avoided when writing clear code.
  2122.  
  2123.             See also the "map" entry in this manpage for an array
  2124.             composed of the results of the BLOCK or EXPR.
  2125.  
  2126.     hex EXPR
  2127.  
  2128.     hex     Interprets EXPR as a hex string and returns the
  2129.             corresponding value. (To convert strings that might
  2130.             start with either 0, 0x, or 0b, see the "oct" entry in
  2131.             this manpage.) If EXPR is omitted, uses `$_'.
  2132.  
  2133.                 print hex '0xAf'; # prints '175'
  2134.                 print hex 'aF';   # same
  2135.  
  2136.  
  2137.     import  There is no builtin `import()' function. It is just an
  2138.             ordinary method (subroutine) defined (or inherited) by
  2139.             modules that wish to export names to another module. The
  2140.             `use()' function calls the `import()' method for the
  2141.             package used. See also the "use()" entry in this
  2142.             manpage, the perlmod manpage, and the Exporter manpage.
  2143.  
  2144.     index STR,SUBSTR,POSITION
  2145.  
  2146.     index STR,SUBSTR
  2147.             The index function searches for one string within
  2148.             another, but without the wildcard-like behavior of a
  2149.             full regular-expression pattern match. It returns the
  2150.             position of the first occurrence of SUBSTR in STR at or
  2151.             after POSITION. If POSITION is omitted, starts searching
  2152.             from the beginning of the string. The return value is
  2153.             based at `0' (or whatever you've set the `$[' variable
  2154.             to--but don't do that). If the substring is not found,
  2155.             returns one less than the base, ordinarily `-1'.
  2156.  
  2157.     int EXPR
  2158.  
  2159.     int     Returns the integer portion of EXPR. If EXPR is omitted,
  2160.             uses `$_'. You should not use this function for
  2161.             rounding: one because it truncates towards `0', and two
  2162.             because machine representations of floating point
  2163.             numbers can sometimes produce counterintuitive results.
  2164.             For example, `int(-6.725/0.025)' produces -268 rather
  2165.             than the correct -269; that's because it's really more
  2166.             like -268.99999999999994315658 instead. Usually, the
  2167.             `sprintf()', `printf()', or the `POSIX::floor' and
  2168.             `POSIX::ceil' functions will serve you better than will
  2169.             int().
  2170.  
  2171.     ioctl FILEHANDLE,FUNCTION,SCALAR
  2172.             Implements the ioctl(2) function. You'll probably first
  2173.             have to say
  2174.  
  2175.                 require "ioctl.ph";    # probably in /usr/local/lib/perl/ioctl.ph
  2176.  
  2177.  
  2178.             to get the correct function definitions. If ioctl.ph
  2179.             doesn't exist or doesn't have the correct definitions
  2180.             you'll have to roll your own, based on your C header
  2181.             files such as <sys/ioctl.h>. (There is a Perl script
  2182.             called h2ph that comes with the Perl kit that may help
  2183.             you in this, but it's nontrivial.) SCALAR will be read
  2184.             and/or written depending on the FUNCTION--a pointer to
  2185.             the string value of SCALAR will be passed as the third
  2186.             argument of the actual `ioctl()' call. (If SCALAR has no
  2187.             string value but does have a numeric value, that value
  2188.             will be passed rather than a pointer to the string
  2189.             value. To guarantee this to be TRUE, add a `0' to the
  2190.             scalar before using it.) The `pack()' and `unpack()'
  2191.             functions are useful for manipulating the values of
  2192.             structures used by `ioctl()'. The following example sets
  2193.             the erase character to DEL.
  2194.  
  2195.                 require 'ioctl.ph';
  2196.                 $getp = &TIOCGETP;
  2197.                 die "NO TIOCGETP" if $@ || !$getp;
  2198.                 $sgttyb_t = "ccccs";        # 4 chars and a short
  2199.                 if (ioctl(STDIN,$getp,$sgttyb)) {
  2200.                 @ary = unpack($sgttyb_t,$sgttyb);
  2201.                 $ary[2] = 127;
  2202.                 $sgttyb = pack($sgttyb_t,@ary);
  2203.                 ioctl(STDIN,&TIOCSETP,$sgttyb)
  2204.                     || die "Can't ioctl: $!";
  2205.                 }
  2206.  
  2207.  
  2208.             The return value of `ioctl()' (and `fcntl()') is as
  2209.             follows:
  2210.  
  2211.                 if OS returns:        then Perl returns:
  2212.                     -1                undefined value
  2213.                      0             string "0 but true"
  2214.                 anything else            that number
  2215.  
  2216.  
  2217.             Thus Perl returns TRUE on success and FALSE on failure,
  2218.             yet you can still easily determine the actual value
  2219.             returned by the operating system:
  2220.  
  2221.                 $retval = ioctl(...) || -1;
  2222.                 printf "System returned %d\n", $retval;
  2223.  
  2224.  
  2225.             The special string "`0' but true" is exempt from -w
  2226.             complaints about improper numeric conversions.
  2227.  
  2228.     join EXPR,LIST
  2229.             Joins the separate strings of LIST into a single string
  2230.             with fields separated by the value of EXPR, and returns
  2231.             that new string. Example:
  2232.  
  2233.                 $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
  2234.  
  2235.  
  2236.             See the "split" entry in this manpage.
  2237.  
  2238.     keys HASH
  2239.             Returns a list consisting of all the keys of the named
  2240.             hash. (In a scalar context, returns the number of keys.)
  2241.             The keys are returned in an apparently random order. The
  2242.             actual random order is subject to change in future
  2243.             versions of perl, but it is guaranteed to be the same
  2244.             order as either the `values()' or `each()' function
  2245.             produces (given that the hash has not been modified). As
  2246.             a side effect, it resets HASH's iterator.
  2247.  
  2248.             Here is yet another way to print your environment:
  2249.  
  2250.                 @keys = keys %ENV;
  2251.                 @values = values %ENV;
  2252.                 while ($#keys >= 0) {
  2253.                 print pop(@keys), '=', pop(@values), "\n";
  2254.                 }
  2255.  
  2256.  
  2257.             or how about sorted by key:
  2258.  
  2259.                 foreach $key (sort(keys %ENV)) {
  2260.                 print $key, '=', $ENV{$key}, "\n";
  2261.                 }
  2262.  
  2263.  
  2264.             To sort a hash by value, you'll need to use a `sort()'
  2265.             function. Here's a descending numeric sort of a hash by
  2266.             its values:
  2267.  
  2268.                 foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
  2269.                 printf "%4d %s\n", $hash{$key}, $key;
  2270.                 }
  2271.  
  2272.  
  2273.             As an lvalue `keys()' allows you to increase the number
  2274.             of hash buckets allocated for the given hash. This can
  2275.             gain you a measure of efficiency if you know the hash is
  2276.             going to get big. (This is similar to pre-extending an
  2277.             array by assigning a larger number to $#array.) If you
  2278.             say
  2279.  
  2280.                 keys %hash = 200;
  2281.  
  2282.  
  2283.             then `%hash' will have at least 200 buckets allocated
  2284.             for it--256 of them, in fact, since it rounds up to the
  2285.             next power of two. These buckets will be retained even
  2286.             if you do `%hash = ()', use `undef %hash' if you want to
  2287.             free the storage while `%hash' is still in scope. You
  2288.             can't shrink the number of buckets allocated for the
  2289.             hash using `keys()' in this way (but you needn't worry
  2290.             about doing this by accident, as trying has no effect).
  2291.  
  2292.             See also `each()', `values()' and `sort()'.
  2293.  
  2294.     kill LIST
  2295.             Sends a signal to a list of processes. The first element
  2296.             of the list must be the signal to send. Returns the
  2297.             number of processes successfully signaled.
  2298.  
  2299.                 $cnt = kill 1, $child1, $child2;
  2300.                 kill 9, @goners;
  2301.  
  2302.  
  2303.             Unlike in the shell, in Perl if the *SIGNAL* is
  2304.             negative, it kills process groups instead of processes.
  2305.             (On System V, a negative *PROCESS* number will also kill
  2306.             process groups, but that's not portable.) That means you
  2307.             usually want to use positive not negative signals. You
  2308.             may also use a signal name in quotes. See the section on
  2309.             "Signals" in the perlipc manpage for details.
  2310.  
  2311.     last LABEL
  2312.  
  2313.     last    The `last' command is like the `break' statement in C (as
  2314.             used in loops); it immediately exits the loop in
  2315.             question. If the LABEL is omitted, the command refers to
  2316.             the innermost enclosing loop. The `continue' block, if
  2317.             any, is not executed:
  2318.  
  2319.                 LINE: while (<STDIN>) {
  2320.                 last LINE if /^$/;    # exit when done with header
  2321.                 #...
  2322.                 }
  2323.  
  2324.  
  2325.             `last' cannot be used to exit a block which returns a
  2326.             value such as `eval {}', `sub {}' or `do {}', and should
  2327.             not be used to exit a grep() or map() operation.
  2328.  
  2329.             See also the "continue" entry in this manpage for an
  2330.             illustration of how `last', `next', and `redo' work.
  2331.  
  2332.     lc EXPR
  2333.  
  2334.     lc      Returns an lowercased version of EXPR. This is the internal
  2335.             function implementing the `\L' escape in double-quoted
  2336.             strings. Respects current LC_CTYPE locale if `use
  2337.             locale' in force. See the perllocale manpage.
  2338.  
  2339.             If EXPR is omitted, uses `$_'.
  2340.  
  2341.     lcfirst EXPR
  2342.  
  2343.     lcfirst Returns the value of EXPR with the first character
  2344.             lowercased. This is the internal function implementing
  2345.             the `\l' escape in double-quoted strings. Respects
  2346.             current LC_CTYPE locale if `use locale' in force. See
  2347.             the perllocale manpage.
  2348.  
  2349.             If EXPR is omitted, uses `$_'.
  2350.  
  2351.     length EXPR
  2352.  
  2353.     length  Returns the length in characters of the value of EXPR. If
  2354.             EXPR is omitted, returns length of `$_'. Note that this
  2355.             cannot be used on an entire array or hash to find out
  2356.             how many elements these have. For that, use `scalar
  2357.             @array' and `scalar keys %hash' respectively.
  2358.  
  2359.     link OLDFILE,NEWFILE
  2360.             Creates a new filename linked to the old filename.
  2361.             Returns TRUE for success, FALSE otherwise.
  2362.  
  2363.     listen SOCKET,QUEUESIZE
  2364.             Does the same thing that the listen system call does.
  2365.             Returns TRUE if it succeeded, FALSE otherwise. See the
  2366.             example in the section on "Sockets: Client/Server
  2367.             Communication" in the perlipc manpage.
  2368.  
  2369.     local EXPR
  2370.             You really probably want to be using `my()' instead,
  2371.             because `local()' isn't what most people think of as
  2372.             "local". See the section on "Private Variables via my()"
  2373.             in the perlsub manpage for details.
  2374.  
  2375.             A local modifies the listed variables to be local to the
  2376.             enclosing block, file, or eval. If more than one value
  2377.             is listed, the list must be placed in parentheses. See
  2378.             the section on "Temporary Values via local()" in the
  2379.             perlsub manpage for details, including issues with tied
  2380.             arrays and hashes.
  2381.  
  2382.     localtime EXPR
  2383.             Converts a time as returned by the time function to a 9-
  2384.             element array with the time analyzed for the local time
  2385.             zone. Typically used as follows:
  2386.  
  2387.                 #  0    1    2     3     4    5     6     7     8
  2388.                 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
  2389.                                     localtime(time);
  2390.  
  2391.  
  2392.             All array elements are numeric, and come straight out of
  2393.             a struct tm. In particular this means that `$mon' has
  2394.             the range `0..11' and `$wday' has the range `0..6' with
  2395.             sunday as day `0'. Also, `$year' is the number of years
  2396.             since 1900, that is, `$year' is `123' in year 2023, and
  2397.             *not* simply the last two digits of the year. If you
  2398.             assume it is, then you create non-Y2K-compliant
  2399.             programs--and you wouldn't want to do that, would you?
  2400.  
  2401.             If EXPR is omitted, uses the current time
  2402.             (`localtime(time)').
  2403.  
  2404.             In scalar context, returns the ctime(3) value:
  2405.  
  2406.                 $now_string = localtime;  # e.g., "Thu Oct 13 04:54:34 1994"
  2407.  
  2408.  
  2409.             This scalar value is not locale dependent, see the
  2410.             perllocale manpage, but instead a Perl builtin. Also see
  2411.             the `Time::Local' module, and the strftime(3) and
  2412.             mktime(3) function available via the POSIX module. To
  2413.             get somewhat similar but locale dependent date strings,
  2414.             set up your locale environment variables appropriately
  2415.             (please see the perllocale manpage) and try for example:
  2416.  
  2417.                 use POSIX qw(strftime);
  2418.                 $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
  2419.  
  2420.  
  2421.             Note that the `%a' and `%b', the short forms of the day
  2422.             of the week and the month of the year, may not
  2423.             necessarily be three characters wide.
  2424.  
  2425.     log EXPR
  2426.  
  2427.     log     Returns the natural logarithm (base *e*) of EXPR. If EXPR is
  2428.             omitted, returns log of `$_'. To get the log of another
  2429.             base, use basic algebra: The base-N log of a number is
  2430.             is equal to the natural log of that number divided by
  2431.             the natural log of N. For example:
  2432.  
  2433.                 sub log10 {
  2434.                 my $n = shift;
  2435.                 return log($n)/log(10);
  2436.                 } 
  2437.  
  2438.  
  2439.             See also the "exp" entry in this manpage for the inverse
  2440.             operation.
  2441.  
  2442.     lstat FILEHANDLE
  2443.  
  2444.     lstat EXPR
  2445.  
  2446.     lstat   Does the same thing as the `stat()' function (including
  2447.             setting the special `_' filehandle) but stats a symbolic
  2448.             link instead of the file the symbolic link points to. If
  2449.             symbolic links are unimplemented on your system, a
  2450.             normal `stat()' is done.
  2451.  
  2452.             If EXPR is omitted, stats `$_'.
  2453.  
  2454.     m//     The match operator. See the perlop manpage.
  2455.  
  2456.     map BLOCK LIST
  2457.  
  2458.     map EXPR,LIST
  2459.             Evaluates the BLOCK or EXPR for each element of LIST
  2460.             (locally setting `$_' to each element) and returns the
  2461.             list value composed of the results of each such
  2462.             evaluation. Evaluates BLOCK or EXPR in a list context,
  2463.             so each element of LIST may produce zero, one, or more
  2464.             elements in the returned value.
  2465.  
  2466.             In scalar context, returns the total number of elements
  2467.             so generated.
  2468.  
  2469.                 @chars = map(chr, @nums);
  2470.  
  2471.  
  2472.             translates a list of numbers to the corresponding
  2473.             characters. And
  2474.  
  2475.                 %hash = map { getkey($_) => $_ } @array;
  2476.  
  2477.  
  2478.             is just a funny way to write
  2479.  
  2480.                 %hash = ();
  2481.                 foreach $_ (@array) {
  2482.                 $hash{getkey($_)} = $_;
  2483.                 }
  2484.  
  2485.  
  2486.             Note that, because `$_' is a reference into the list
  2487.             value, it can be used to modify the elements of the
  2488.             array. While this is useful and supported, it can cause
  2489.             bizarre results if the LIST is not a named array. Using
  2490.             a regular `foreach' loop for this purpose would be
  2491.             clearer in most cases. See also the "grep" entry in this
  2492.             manpage for an array composed of those items of the
  2493.             original list for which the BLOCK or EXPR evaluates to
  2494.             true.
  2495.  
  2496.     mkdir FILENAME,MODE
  2497.             Creates the directory specified by FILENAME, with
  2498.             permissions specified by MODE (as modified by `umask').
  2499.             If it succeeds it returns TRUE, otherwise it returns
  2500.             FALSE and sets `$!' (errno).
  2501.  
  2502.             In general, it is better to create directories with
  2503.             permissive MODEs, and let the user modify that with
  2504.             their `umask', than it is to supply a restrictive MODE
  2505.             and give the user no way to be more permissive. The
  2506.             exceptions to this rule are when the file or directory
  2507.             should be kept private (mail files, for instance). The
  2508.             perlfunc(1) entry on `umask' discusses the choice of
  2509.             MODE in more detail.
  2510.  
  2511.     msgctl ID,CMD,ARG
  2512.             Calls the System V IPC function msgctl(2). You'll
  2513.             probably have to say
  2514.  
  2515.                 use IPC::SysV;
  2516.  
  2517.  
  2518.             first to get the correct constant definitions. If CMD is
  2519.             `IPC_STAT', then ARG must be a variable which will hold
  2520.             the returned `msqid_ds' structure. Returns like
  2521.             `ioctl()': the undefined value for error, "`0' but true"
  2522.             for zero, or the actual return value otherwise. See also
  2523.             `IPC::SysV' and `IPC::Semaphore::Msg' documentation.
  2524.  
  2525.     msgget KEY,FLAGS
  2526.             Calls the System V IPC function msgget(2). Returns the
  2527.             message queue id, or the undefined value if there is an
  2528.             error. See also `IPC::SysV' and `IPC::SysV::Msg'
  2529.             documentation.
  2530.  
  2531.     msgsnd ID,MSG,FLAGS
  2532.             Calls the System V IPC function msgsnd to send the
  2533.             message MSG to the message queue ID. MSG must begin with
  2534.             the long integer message type, which may be created with
  2535.             `pack("l", $type)'. Returns TRUE if successful, or FALSE
  2536.             if there is an error. See also `IPC::SysV' and
  2537.             `IPC::SysV::Msg' documentation.
  2538.  
  2539.     msgrcv ID,VAR,SIZE,TYPE,FLAGS
  2540.             Calls the System V IPC function msgrcv to receive a
  2541.             message from message queue ID into variable VAR with a
  2542.             maximum message size of SIZE. Note that if a message is
  2543.             received, the message type will be the first thing in
  2544.             VAR, and the maximum length of VAR is SIZE plus the size
  2545.             of the message type. Returns TRUE if successful, or
  2546.             FALSE if there is an error. See also `IPC::SysV' and
  2547.             `IPC::SysV::Msg' documentation.
  2548.  
  2549.     my EXPR A `my()' declares the listed variables to be local
  2550.             (lexically) to the enclosing block, file, or `eval()'.
  2551.             If more than one value is listed, the list must be
  2552.             placed in parentheses. See the section on "Private
  2553.             Variables via my()" in the perlsub manpage for details.
  2554.  
  2555.     next LABEL
  2556.  
  2557.     next    The `next' command is like the `continue' statement in C; it
  2558.             starts the next iteration of the loop:
  2559.  
  2560.                 LINE: while (<STDIN>) {
  2561.                 next LINE if /^#/;    # discard comments
  2562.                 #...
  2563.                 }
  2564.  
  2565.  
  2566.             Note that if there were a `continue' block on the above,
  2567.             it would get executed even on discarded lines. If the
  2568.             LABEL is omitted, the command refers to the innermost
  2569.             enclosing loop.
  2570.  
  2571.             `next' cannot be used to exit a block which returns a
  2572.             value such as `eval {}', `sub {}' or `do {}', and should
  2573.             not be used to exit a grep() or map() operation.
  2574.  
  2575.             See also the "continue" entry in this manpage for an
  2576.             illustration of how `last', `next', and `redo' work.
  2577.  
  2578.     no Module LIST
  2579.             See the the "use" entry in this manpage function, which
  2580.             `no' is the opposite of.
  2581.  
  2582.     oct EXPR
  2583.  
  2584.     oct     Interprets EXPR as an octal string and returns the
  2585.             corresponding value. (If EXPR happens to start off with
  2586.             `0x', interprets it as a hex string. If EXPR starts off
  2587.             with `0b', it is interpreted as a binary string.) The
  2588.             following will handle decimal, binary, octal, and hex in
  2589.             the standard Perl or C notation:
  2590.  
  2591.                 $val = oct($val) if $val =~ /^0/;
  2592.  
  2593.  
  2594.             If EXPR is omitted, uses `$_'. This function is commonly
  2595.             used when a string such as `644' needs to be converted
  2596.             into a file mode, for example. (Although perl will
  2597.             automatically convert strings into numbers as needed,
  2598.             this automatic conversion assumes base 10.)
  2599.  
  2600.     open FILEHANDLE,EXPR
  2601.  
  2602.     open FILEHANDLE
  2603.             Opens the file whose filename is given by EXPR, and
  2604.             associates it with FILEHANDLE. If FILEHANDLE is an
  2605.             expression, its value is used as the name of the real
  2606.             filehandle wanted. If EXPR is omitted, the scalar
  2607.             variable of the same name as the FILEHANDLE contains the
  2608.             filename. (Note that lexical variables--those declared
  2609.             with `my()'--will not work for this purpose; so if
  2610.             you're using `my()', specify EXPR in your call to open.)
  2611.             See the perlopentut manpage for a kinder, gentler
  2612.             explanation of opening files.
  2613.  
  2614.             If the filename begins with `'<'' or nothing, the file
  2615.             is opened for input. If the filename begins with `'>'',
  2616.             the file is truncated and opened for output, being
  2617.             created if necessary. If the filename begins with
  2618.             `'>>'', the file is opened for appending, again being
  2619.             created if necessary. You can put a `'+'' in front of
  2620.             the `'>'' or `'<'' to indicate that you want both read
  2621.             and write access to the file; thus `'+<'' is almost
  2622.             always preferred for read/write updates--the `'+>'' mode
  2623.             would clobber the file first. You can't usually use
  2624.             either read-write mode for updating textfiles, since
  2625.             they have variable length records. See the -i switch in
  2626.             the perlrun manpage for a better approach. The file is
  2627.             created with permissions of `0666' modified by the
  2628.             process' `umask' value.
  2629.  
  2630.             The prefix and the filename may be separated with
  2631.             spaces. These various prefixes correspond to the
  2632.             fopen(3) modes of `'r'', `'r+'', `'w'', `'w+'', `'a'',
  2633.             and `'a+''.
  2634.  
  2635.             If the filename begins with `'|'', the filename is
  2636.             interpreted as a command to which output is to be piped,
  2637.             and if the filename ends with a `'|'', the filename is
  2638.             interpreted as a command which pipes output to us. See
  2639.             the section on "Using open() for IPC" in the perlipc
  2640.             manpage for more examples of this. (You are not allowed
  2641.             to `open()' to a command that pipes both in *and* out,
  2642.             but see the IPC::Open2 manpage, the IPC::Open3 manpage,
  2643.             and the section on "Bidirectional Communication" in the
  2644.             perlipc manpage for alternatives.)
  2645.  
  2646.             Opening `'-'' opens STDIN and opening `'>-'' opens
  2647.             STDOUT. Open returns nonzero upon success, the undefined
  2648.             value otherwise. If the `open()' involved a pipe, the
  2649.             return value happens to be the pid of the subprocess.
  2650.  
  2651.             If you're unfortunate enough to be running Perl on a
  2652.             system that distinguishes between text files and binary
  2653.             files (modern operating systems don't care), then you
  2654.             should check out the "binmode" entry in this manpage for
  2655.             tips for dealing with this. The key distinction between
  2656.             systems that need `binmode()' and those that don't is
  2657.             their text file formats. Systems like Unix, MacOS, and
  2658.             Plan9, which delimit lines with a single character, and
  2659.             which encode that character in C as `"\n"', do not need
  2660.             `binmode()'. The rest need it.
  2661.  
  2662.             When opening a file, it's usually a bad idea to continue
  2663.             normal execution if the request failed, so `open()' is
  2664.             frequently used in connection with `die()'. Even if
  2665.             `die()' won't do what you want (say, in a CGI script,
  2666.             where you want to make a nicely formatted error message
  2667.             (but there are modules that can help with that problem))
  2668.             you should always check the return value from opening a
  2669.             file. The infrequent exception is when working with an
  2670.             unopened filehandle is actually what you want to do.
  2671.  
  2672.             Examples:
  2673.  
  2674.                 $ARTICLE = 100;
  2675.                 open ARTICLE or die "Can't find article $ARTICLE: $!\n";
  2676.                 while (<ARTICLE>) {...
  2677.  
  2678.                 open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
  2679.                 # if the open fails, output is discarded
  2680.  
  2681.                 open(DBASE, '+<dbase.mine')            # open for update
  2682.                 or die "Can't open 'dbase.mine' for update: $!";
  2683.  
  2684.                 open(ARTICLE, "caesar <$article |")     # decrypt article
  2685.                 or die "Can't start caesar: $!";
  2686.  
  2687.                 open(EXTRACT, "|sort >/tmp/Tmp$$")      # $$ is our process id
  2688.                 or die "Can't start sort: $!";
  2689.  
  2690.                 # process argument list of files along with any includes
  2691.  
  2692.                 foreach $file (@ARGV) {
  2693.                 process($file, 'fh00');
  2694.                 }
  2695.  
  2696.                 sub process {
  2697.                 my($filename, $input) = @_;
  2698.                 $input++;        # this is a string increment
  2699.                 unless (open($input, $filename)) {
  2700.                     print STDERR "Can't open $filename: $!\n";
  2701.                     return;
  2702.                 }
  2703.  
  2704.                 local $_;
  2705.                 while (<$input>) {        # note use of indirection
  2706.                     if (/^#include "(.*)"/) {
  2707.                     process($1, $input);
  2708.                     next;
  2709.                     }
  2710.                     #...        # whatever
  2711.                 }
  2712.                 }
  2713.  
  2714.  
  2715.             You may also, in the Bourne shell tradition, specify an
  2716.             EXPR beginning with `'>&'', in which case the rest of
  2717.             the string is interpreted as the name of a filehandle
  2718.             (or file descriptor, if numeric) to be duped and opened.
  2719.             You may use `&' after `>', `>>', `<', `+>', `+>>', and
  2720.             `+<'. The mode you specify should match the mode of the
  2721.             original filehandle. (Duping a filehandle does not take
  2722.             into account any existing contents of stdio buffers.)
  2723.             Here is a script that saves, redirects, and restores
  2724.             STDOUT and STDERR:
  2725.  
  2726.                 #!/usr/bin/perl
  2727.                 open(OLDOUT, ">&STDOUT");
  2728.                 open(OLDERR, ">&STDERR");
  2729.  
  2730.                 open(STDOUT, ">foo.out") || die "Can't redirect stdout";
  2731.                 open(STDERR, ">&STDOUT") || die "Can't dup stdout";
  2732.  
  2733.                 select(STDERR); $| = 1;    # make unbuffered
  2734.                 select(STDOUT); $| = 1;    # make unbuffered
  2735.  
  2736.                 print STDOUT "stdout 1\n";    # this works for
  2737.                 print STDERR "stderr 1\n";     # subprocesses too
  2738.  
  2739.                 close(STDOUT);
  2740.                 close(STDERR);
  2741.  
  2742.                 open(STDOUT, ">&OLDOUT");
  2743.                 open(STDERR, ">&OLDERR");
  2744.  
  2745.                 print STDOUT "stdout 2\n";
  2746.                 print STDERR "stderr 2\n";
  2747.  
  2748.  
  2749.             If you specify `'<&=N'', where `N' is a number, then
  2750.             Perl will do an equivalent of C's `fdopen()' of that
  2751.             file descriptor; this is more parsimonious of file
  2752.             descriptors. For example:
  2753.  
  2754.                 open(FILEHANDLE, "<&=$fd")
  2755.  
  2756.  
  2757.             If you open a pipe on the command `'-'', i.e., either
  2758.             `'|-'' or `'-|'', then there is an implicit fork done,
  2759.             and the return value of open is the pid of the child
  2760.             within the parent process, and `0' within the child
  2761.             process. (Use `defined($pid)' to determine whether the
  2762.             open was successful.) The filehandle behaves normally
  2763.             for the parent, but i/o to that filehandle is piped
  2764.             from/to the STDOUT/STDIN of the child process. In the
  2765.             child process the filehandle isn't opened--i/o happens
  2766.             from/to the new STDOUT or STDIN. Typically this is used
  2767.             like the normal piped open when you want to exercise
  2768.             more control over just how the pipe command gets
  2769.             executed, such as when you are running setuid, and don't
  2770.             want to have to scan shell commands for metacharacters.
  2771.             The following pairs are more or less equivalent:
  2772.  
  2773.                 open(FOO, "|tr '[a-z]' '[A-Z]'");
  2774.                 open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]';
  2775.  
  2776.                 open(FOO, "cat -n '$file'|");
  2777.                 open(FOO, "-|") || exec 'cat', '-n', $file;
  2778.  
  2779.  
  2780.             See the section on "Safe Pipe Opens" in the perlipc
  2781.             manpage for more examples of this.
  2782.  
  2783.             NOTE: On any operation that may do a fork, any unflushed
  2784.             buffers remain unflushed in both processes, which means
  2785.             you may need to set `$|' to avoid duplicate output. On
  2786.             systems that support a close-on-exec flag on files, the
  2787.             flag will be set for the newly opened file descriptor as
  2788.             determined by the value of $^F. See the "$^F" entry in
  2789.             the perlvar manpage.
  2790.  
  2791.             Closing any piped filehandle causes the parent process
  2792.             to wait for the child to finish, and returns the status
  2793.             value in `$?'.
  2794.  
  2795.             The filename passed to open will have leading and
  2796.             trailing whitespace deleted, and the normal redirection
  2797.             characters honored. This property, known as "magic
  2798.             open", can often be used to good effect. A user could
  2799.             specify a filename of "rsh cat file |", or you could
  2800.             change certain filenames as needed:
  2801.  
  2802.                 $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
  2803.                 open(FH, $filename) or die "Can't open $filename: $!";
  2804.  
  2805.  
  2806.             However, to open a file with arbitrary weird characters
  2807.             in it, it's necessary to protect any leading and
  2808.             trailing whitespace:
  2809.  
  2810.                 $file =~ s#^(\s)#./$1#;
  2811.                 open(FOO, "< $file\0");
  2812.  
  2813.  
  2814.             If you want a "real" C `open()' (see the open(2) manpage
  2815.             on your system), then you should use the `sysopen()'
  2816.             function, which involves no such magic. This is another
  2817.             way to protect your filenames from interpretation. For
  2818.             example:
  2819.  
  2820.                 use IO::Handle;
  2821.                 sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL)
  2822.                 or die "sysopen $path: $!";
  2823.                 $oldfh = select(HANDLE); $| = 1; select($oldfh);
  2824.                 print HANDLE "stuff $$\n");
  2825.                 seek(HANDLE, 0, 0);
  2826.                 print "File contains: ", <HANDLE>;
  2827.  
  2828.  
  2829.             Using the constructor from the `IO::Handle' package (or
  2830.             one of its subclasses, such as `IO::File' or
  2831.             `IO::Socket'), you can generate anonymous filehandles
  2832.             that have the scope of whatever variables hold
  2833.             references to them, and automatically close whenever and
  2834.             however you leave that scope:
  2835.  
  2836.                 use IO::File;
  2837.                 #...
  2838.                 sub read_myfile_munged {
  2839.                 my $ALL = shift;
  2840.                 my $handle = new IO::File;
  2841.                 open($handle, "myfile") or die "myfile: $!";
  2842.                 $first = <$handle>
  2843.                     or return ();     # Automatically closed here.
  2844.                 mung $first or die "mung failed";    # Or here.
  2845.                 return $first, <$handle> if $ALL;    # Or here.
  2846.                 $first;                    # Or here.
  2847.                 }
  2848.  
  2849.  
  2850.             See the "seek" entry in this manpage for some details
  2851.             about mixing reading and writing.
  2852.  
  2853.     opendir DIRHANDLE,EXPR
  2854.             Opens a directory named EXPR for processing by
  2855.             `readdir()', `telldir()', `seekdir()', `rewinddir()',
  2856.             and `closedir()'. Returns TRUE if successful. DIRHANDLEs
  2857.             have their own namespace separate from FILEHANDLEs.
  2858.  
  2859.     ord EXPR
  2860.  
  2861.     ord     Returns the numeric ascii value of the first character of
  2862.             EXPR. If EXPR is omitted, uses `$_'. For the reverse,
  2863.             see the "chr" entry in this manpage.
  2864.  
  2865.     pack TEMPLATE,LIST
  2866.             Takes an array or list of values and packs it into a
  2867.             binary structure, returning the string containing the
  2868.             structure. The TEMPLATE is a sequence of characters that
  2869.             give the order and type of values, as follows:
  2870.  
  2871.                 a    A string with arbitrary binary data, will be null padded.
  2872.                 A    An ascii string, will be space padded.
  2873.                 Z    A null terminated (asciz) string, will be null padded.
  2874.  
  2875.                 b    A bit string (ascending bit order, like vec()).
  2876.                 B    A bit string (descending bit order).
  2877.                 h    A hex string (low nybble first).
  2878.                 H    A hex string (high nybble first).
  2879.  
  2880.                 c    A signed char value.
  2881.                 C    An unsigned char value.
  2882.  
  2883.                 s    A signed short value.
  2884.                 S    An unsigned short value.
  2885.                   (This 'short' is _exactly_ 16 bits, which may differ from
  2886.                    what a local C compiler calls 'short'.)
  2887.  
  2888.                 i    A signed integer value.
  2889.                 I    An unsigned integer value.
  2890.                   (This 'integer' is _at least_ 32 bits wide.  Its exact
  2891.                        size depends on what a local C compiler calls 'int',
  2892.                        and may even be larger than the 'long' described in
  2893.                        the next item.)
  2894.  
  2895.                 l    A signed long value.
  2896.                 L    An unsigned long value.
  2897.                   (This 'long' is _exactly_ 32 bits, which may differ from
  2898.                    what a local C compiler calls 'long'.)
  2899.  
  2900.                 n    A short in "network" (big-endian) order.
  2901.                 N    A long in "network" (big-endian) order.
  2902.                 v    A short in "VAX" (little-endian) order.
  2903.                 V    A long in "VAX" (little-endian) order.
  2904.                   (These 'shorts' and 'longs' are _exactly_ 16 bits and
  2905.                    _exactly_ 32 bits, respectively.)
  2906.  
  2907.                 q    A signed quad (64-bit) value.
  2908.                 Q    An unsigned quad value.
  2909.                   (Available only if your system supports 64-bit integer values
  2910.                    _and_ if Perl has been compiled to support those.
  2911.                        Causes a fatal error otherwise.)
  2912.  
  2913.                 f    A single-precision float in the native format.
  2914.                 d    A double-precision float in the native format.
  2915.  
  2916.                 p    A pointer to a null-terminated string.
  2917.                 P    A pointer to a structure (fixed-length string).
  2918.  
  2919.                 u    A uuencoded string.
  2920.  
  2921.                 w    A BER compressed integer.  Its bytes represent an unsigned
  2922.                 integer in base 128, most significant digit first, with as
  2923.                     few digits as possible.  Bit eight (the high bit) is set
  2924.                     on each byte except the last.
  2925.  
  2926.                 x    A null byte.
  2927.                 X    Back up a byte.
  2928.                 @    Null fill to absolute position.
  2929.  
  2930.  
  2931.             The following rules apply:
  2932.  
  2933.     *               Each letter may optionally be followed by a number
  2934.                     giving a repeat count. With all types except
  2935.                     `"a"', `"A"', `"Z"', `"b"', `"B"', `"h"', `"H"',
  2936.                     and `"P"' the pack function will gobble up that
  2937.                     many values from the LIST. A `*' for the repeat
  2938.                     count means to use however many items are left.
  2939.  
  2940.     *               The `"a"', `"A"', and `"Z"' types gobble just one
  2941.                     value, but pack it as a string of length count,
  2942.                     padding with nulls or spaces as necessary. When
  2943.                     unpacking, `"A"' strips trailing spaces and
  2944.                     nulls, `"Z"' strips everything after the first
  2945.                     null, and `"a"' returns data verbatim.
  2946.  
  2947.     *               Likewise, the `"b"' and `"B"' fields pack a string
  2948.                     that many bits long.
  2949.  
  2950.     *               The `"h"' and `"H"' fields pack a string that many
  2951.                     nybbles long.
  2952.  
  2953.     *               The `"p"' type packs a pointer to a null-terminated
  2954.                     string. You are responsible for ensuring the
  2955.                     string is not a temporary value (which can
  2956.                     potentially get deallocated before you get
  2957.                     around to using the packed result). The `"P"'
  2958.                     type packs a pointer to a structure of the size
  2959.                     indicated by the length. A NULL pointer is
  2960.                     created if the corresponding value for `"p"' or
  2961.                     `"P"' is `undef'.
  2962.  
  2963.     *               The integer formats `"s"', `"S"', `"i"', `"I"',
  2964.                     `"l"', and `"L"' are inherently non-portable
  2965.                     between processors and operating systems because
  2966.                     they obey the native byteorder and endianness.
  2967.                     For example a 4-byte integer 0x87654321
  2968.                     (2271560481 decimal) be ordered natively
  2969.                     (arranged in and handled by the CPU registers)
  2970.                     into bytes as
  2971.  
  2972.                          0x12 0x34 0x56 0x78    # little-endian
  2973.                          0x78 0x56 0x34 0x12    # big-endian
  2974.  
  2975.  
  2976.                     Basically, the Intel, Alpha, and VAX CPUs and
  2977.                     little-endian, while everybody else, for example
  2978.                     Motorola m68k/88k, PPC, Sparc, HP PA, Power, and
  2979.                     Cray are big-endian. MIPS can be either: Digital
  2980.                     used it in little-endian mode, SGI uses it in
  2981.                     big-endian mode.
  2982.  
  2983.                     The names `big-endian' and `little-endian' are
  2984.                     joking references to the classic "Gulliver's
  2985.                     Travels" (via the paper "On Holy Wars and a Plea
  2986.                     for Peace" by Danny Cohen, USC/ISI IEN 137,
  2987.                     April 1, 1980) and the egg-eating habits of the
  2988.                     lilliputs.
  2989.  
  2990.                     Some systems may even have weird byte orders
  2991.                     such as
  2992.  
  2993.                          0x56 0x78 0x12 0x34
  2994.                          0x34 0x12 0x78 0x56
  2995.  
  2996.  
  2997.                     You can see your system's preference with
  2998.  
  2999.                          print join(" ", map { sprintf "%#02x", $_ }
  3000.                                                 unpack("C*",pack("L",0x12345678))), "\n";
  3001.  
  3002.  
  3003.                     The byteorder on the platform where Perl was
  3004.                     built is also available via the Config manpage:
  3005.  
  3006.                         use Config;
  3007.                         print $Config{byteorder}, "\n";
  3008.  
  3009.  
  3010.                     Byteorders `'1234'' and `'12345678'' are little-
  3011.                     endian, `'4321'' and `'87654321'' are big-
  3012.                     endian.
  3013.  
  3014.                     If you want portable packed integers use the
  3015.                     formats `"n"', `"N"', `"v"', and `"V"', their
  3016.                     byte endianness and size is known.
  3017.  
  3018.     *               Real numbers (floats and doubles) are in the native
  3019.                     machine format only; due to the multiplicity of
  3020.                     floating formats around, and the lack of a
  3021.                     standard "network" representation, no facility
  3022.                     for interchange has been made. This means that
  3023.                     packed floating point data written on one
  3024.                     machine may not be readable on another - even if
  3025.                     both use IEEE floating point arithmetic (as the
  3026.                     endian-ness of the memory representation is not
  3027.                     part of the IEEE spec).
  3028.  
  3029.                     Note that Perl uses doubles internally for all
  3030.                     numeric calculation, and converting from double
  3031.                     into float and thence back to double again will
  3032.                     lose precision (i.e., `unpack("f", pack("f",
  3033.                     $foo)') will not in general equal `$foo').
  3034.  
  3035.  
  3036.             Examples:
  3037.  
  3038.                 $foo = pack("CCCC",65,66,67,68);
  3039.                 # foo eq "ABCD"
  3040.                 $foo = pack("C4",65,66,67,68);
  3041.                 # same thing
  3042.  
  3043.                 $foo = pack("ccxxcc",65,66,67,68);
  3044.                 # foo eq "AB\0\0CD"
  3045.  
  3046.                 $foo = pack("s2",1,2);
  3047.                 # "\1\0\2\0" on little-endian
  3048.                 # "\0\1\0\2" on big-endian
  3049.  
  3050.                 $foo = pack("a4","abcd","x","y","z");
  3051.                 # "abcd"
  3052.  
  3053.                 $foo = pack("aaaa","abcd","x","y","z");
  3054.                 # "axyz"
  3055.  
  3056.                 $foo = pack("a14","abcdefg");
  3057.                 # "abcdefg\0\0\0\0\0\0\0"
  3058.  
  3059.                 $foo = pack("i9pl", gmtime);
  3060.                 # a real struct tm (on my system anyway)
  3061.  
  3062.                 $utmp_template = "Z8 Z8 Z16 L";
  3063.                 $utmp = pack($utmp_template, @utmp1);
  3064.                 # a struct utmp (BSDish)
  3065.  
  3066.                 @utmp2 = unpack($utmp_template, $utmp);
  3067.                 # "@utmp1" eq "@utmp2"
  3068.  
  3069.                 sub bintodec {
  3070.                 unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
  3071.                 }
  3072.  
  3073.  
  3074.             The same template may generally also be used in
  3075.             unpack().
  3076.  
  3077.     package
  3078.  
  3079.     package NAMESPACE
  3080.             Declares the compilation unit as being in the given
  3081.             namespace. The scope of the package declaration is from
  3082.             the declaration itself through the end of the enclosing
  3083.             block, file, or eval (the same as the `my()' operator).
  3084.             All further unqualified dynamic identifiers will be in
  3085.             this namespace. A package statement affects only dynamic
  3086.             variables--including those you've used `local()' on--but
  3087.             *not* lexical variables, which are created with `my()'.
  3088.             Typically it would be the first declaration in a file to
  3089.             be included by the `require' or `use' operator. You can
  3090.             switch into a package in more than one place; it merely
  3091.             influences which symbol table is used by the compiler
  3092.             for the rest of that block. You can refer to variables
  3093.             and filehandles in other packages by prefixing the
  3094.             identifier with the package name and a double colon:
  3095.             `$Package::Variable'. If the package name is null, the
  3096.             `main' package as assumed. That is, `$::sail' is
  3097.             equivalent to `$main::sail' (as well as to `$main'sail',
  3098.             still seen in older code).
  3099.  
  3100.             If NAMESPACE is omitted, then there is no current
  3101.             package, and all identifiers must be fully qualified or
  3102.             lexicals. This is stricter than `use strict', since it
  3103.             also extends to function names.
  3104.  
  3105.             See the section on "Packages" in the perlmod manpage for
  3106.             more information about packages, modules, and classes.
  3107.             See the perlsub manpage for other scoping issues.
  3108.  
  3109.     pipe READHANDLE,WRITEHANDLE
  3110.             Opens a pair of connected pipes like the corresponding
  3111.             system call. Note that if you set up a loop of piped
  3112.             processes, deadlock can occur unless you are very
  3113.             careful. In addition, note that Perl's pipes use stdio
  3114.             buffering, so you may need to set `$|' to flush your
  3115.             WRITEHANDLE after each command, depending on the
  3116.             application.
  3117.  
  3118.             See the IPC::Open2 manpage, the IPC::Open3 manpage, and
  3119.             the section on "Bidirectional Communication" in the
  3120.             perlipc manpage for examples of such things.
  3121.  
  3122.             On systems that support a close-on-exec flag on files,
  3123.             the flag will be set for the newly opened file
  3124.             descriptors as determined by the value of $^F. See the
  3125.             "$^F" entry in the perlvar manpage.
  3126.  
  3127.     pop ARRAY
  3128.  
  3129.     pop     Pops and returns the last value of the array, shortening the
  3130.             array by one element. Has a similar effect to
  3131.  
  3132.                 $tmp = $ARRAY[$#ARRAY--];
  3133.  
  3134.  
  3135.             If there are no elements in the array, returns the
  3136.             undefined value. If ARRAY is omitted, pops the `@ARGV'
  3137.             array in the main program, and the `@_' array in
  3138.             subroutines, just like `shift()'.
  3139.  
  3140.     pos SCALAR
  3141.  
  3142.     pos     Returns the offset of where the last `m//g' search left off
  3143.             for the variable is in question (`$_' is used when the
  3144.             variable is not specified). May be modified to change
  3145.             that offset. Such modification will also influence the
  3146.             `\G' zero-width assertion in regular expressions. See
  3147.             the perlre manpage and the perlop manpage.
  3148.  
  3149.     print FILEHANDLE LIST
  3150.  
  3151.     print LIST
  3152.  
  3153.     print   Prints a string or a comma-separated list of strings.
  3154.             Returns TRUE if successful. FILEHANDLE may be a scalar
  3155.             variable name, in which case the variable contains the
  3156.             name of or a reference to the filehandle, thus
  3157.             introducing one level of indirection. (NOTE: If
  3158.             FILEHANDLE is a variable and the next token is a term,
  3159.             it may be misinterpreted as an operator unless you
  3160.             interpose a `+' or put parentheses around the
  3161.             arguments.) If FILEHANDLE is omitted, prints by default
  3162.             to standard output (or to the last selected output
  3163.             channel--see the "select" entry in this manpage). If
  3164.             LIST is also omitted, prints `$_' to the currently
  3165.             selected output channel. To set the default output
  3166.             channel to something other than STDOUT use the select
  3167.             operation. Note that, because print takes a LIST,
  3168.             anything in the LIST is evaluated in list context, and
  3169.             any subroutine that you call will have one or more of
  3170.             its expressions evaluated in list context. Also be
  3171.             careful not to follow the print keyword with a left
  3172.             parenthesis unless you want the corresponding right
  3173.             parenthesis to terminate the arguments to the print--
  3174.             interpose a `+' or put parentheses around all the
  3175.             arguments.
  3176.  
  3177.             Note that if you're storing FILEHANDLES in an array or
  3178.             other expression, you will have to use a block returning
  3179.             its value instead:
  3180.  
  3181.                 print { $files[$i] } "stuff\n";
  3182.                 print { $OK ? STDOUT : STDERR } "stuff\n";
  3183.  
  3184.  
  3185.     printf FILEHANDLE FORMAT, LIST
  3186.  
  3187.     printf FORMAT, LIST
  3188.             Equivalent to `print FILEHANDLE sprintf(FORMAT, LIST)',
  3189.             except that `$\' (the output record separator) is not
  3190.             appended. The first argument of the list will be
  3191.             interpreted as the `printf()' format. If `use locale' is
  3192.             in effect, the character used for the decimal point in
  3193.             formatted real numbers is affected by the LC_NUMERIC
  3194.             locale. See the perllocale manpage.
  3195.  
  3196.             Don't fall into the trap of using a `printf()' when a
  3197.             simple `print()' would do. The `print()' is more
  3198.             efficient and less error prone.
  3199.  
  3200.     prototype FUNCTION
  3201.             Returns the prototype of a function as a string (or
  3202.             `undef' if the function has no prototype). FUNCTION is a
  3203.             reference to, or the name of, the function whose
  3204.             prototype you want to retrieve.
  3205.  
  3206.             If FUNCTION is a string starting with `CORE::', the rest
  3207.             is taken as a name for Perl builtin. If the builtin is
  3208.             not *overridable* (such as `qw//') or its arguments
  3209.             cannot be expressed by a prototype (such as `system()')
  3210.             returns `undef' because the builtin does not really
  3211.             behave like a Perl function. Otherwise, the string
  3212.             describing the equivalent prototype is returned.
  3213.  
  3214.     push ARRAY,LIST
  3215.             Treats ARRAY as a stack, and pushes the values of LIST
  3216.             onto the end of ARRAY. The length of ARRAY increases by
  3217.             the length of LIST. Has the same effect as
  3218.  
  3219.                 for $value (LIST) {
  3220.                 $ARRAY[++$#ARRAY] = $value;
  3221.                 }
  3222.  
  3223.  
  3224.             but is more efficient. Returns the new number of
  3225.             elements in the array.
  3226.  
  3227.     q/STRING/
  3228.  
  3229.     qq/STRING/
  3230.  
  3231.     qr/STRING/
  3232.  
  3233.     qx/STRING/
  3234.  
  3235.     qw/STRING/
  3236.             Generalized quotes. See the section on "Regexp Quote-
  3237.             Like Operators" in the perlop manpage.
  3238.  
  3239.     quotemeta EXPR
  3240.  
  3241.     quotemeta
  3242.             Returns the value of EXPR with all non-alphanumeric
  3243.             characters backslashed. (That is, all characters not
  3244.             matching `/[A-Za-z_0-9]/' will be preceded by a
  3245.             backslash in the returned string, regardless of any
  3246.             locale settings.) This is the internal function
  3247.             implementing the `\Q' escape in double-quoted strings.
  3248.  
  3249.             If EXPR is omitted, uses `$_'.
  3250.  
  3251.     rand EXPR
  3252.  
  3253.     rand    Returns a random fractional number greater than or equal to
  3254.             `0' and less than the value of EXPR. (EXPR should be
  3255.             positive.) If EXPR is omitted, the value `1' is used.
  3256.             Automatically calls `srand()' unless `srand()' has
  3257.             already been called. See also `srand()'.
  3258.  
  3259.             (Note: If your rand function consistently returns
  3260.             numbers that are too large or too small, then your
  3261.             version of Perl was probably compiled with the wrong
  3262.             number of RANDBITS.)
  3263.  
  3264.     read FILEHANDLE,SCALAR,LENGTH,OFFSET
  3265.  
  3266.     read FILEHANDLE,SCALAR,LENGTH
  3267.             Attempts to read LENGTH bytes of data into variable
  3268.             SCALAR from the specified FILEHANDLE. Returns the number
  3269.             of bytes actually read, `0' at end of file, or undef if
  3270.             there was an error. SCALAR will be grown or shrunk to
  3271.             the length actually read. An OFFSET may be specified to
  3272.             place the read data at some other place than the
  3273.             beginning of the string. This call is actually
  3274.             implemented in terms of stdio's fread(3) call. To get a
  3275.             true read(2) system call, see `sysread()'.
  3276.  
  3277.     readdir DIRHANDLE
  3278.             Returns the next directory entry for a directory opened
  3279.             by `opendir()'. If used in list context, returns all the
  3280.             rest of the entries in the directory. If there are no
  3281.             more entries, returns an undefined value in scalar
  3282.             context or a null list in list context.
  3283.  
  3284.             If you're planning to filetest the return values out of
  3285.             a `readdir()', you'd better prepend the directory in
  3286.             question. Otherwise, because we didn't `chdir()' there,
  3287.             it would have been testing the wrong file.
  3288.  
  3289.                 opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!";
  3290.                 @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
  3291.                 closedir DIR;
  3292.  
  3293.  
  3294.     readline EXPR
  3295.             Reads from the filehandle whose typeglob is contained in
  3296.             EXPR. In scalar context, each call reads and returns the
  3297.             next line, until end-of-file is reached, whereupon the
  3298.             subsequent call returns undef. In list context, reads
  3299.             until end-of-file is reached and returns a list of
  3300.             lines. Note that the notion of "line" used here is
  3301.             however you may have defined it with `$/' or
  3302.             `$INPUT_RECORD_SEPARATOR'). See the section on "$/" in
  3303.             the perlvar manpage.
  3304.  
  3305.             When `$/' is set to `undef', when readline() is in
  3306.             scalar context (i.e. file slurp mode), and when an empty
  3307.             file is read, it returns `''' the first time, followed
  3308.             by `undef' subsequently.
  3309.  
  3310.             This is the internal function implementing the `<EXPR>'
  3311.             operator, but you can use it directly. The `<EXPR>'
  3312.             operator is discussed in more detail in the section on
  3313.             "I/O Operators" in the perlop manpage.
  3314.  
  3315.                 $line = <STDIN>;
  3316.                 $line = readline(*STDIN);        # same thing
  3317.  
  3318.  
  3319.     readlink EXPR
  3320.  
  3321.     readlink
  3322.             Returns the value of a symbolic link, if symbolic links
  3323.             are implemented. If not, gives a fatal error. If there
  3324.             is some system error, returns the undefined value and
  3325.             sets `$!' (errno). If EXPR is omitted, uses `$_'.
  3326.  
  3327.     readpipe EXPR
  3328.             EXPR is executed as a system command. The collected
  3329.             standard output of the command is returned. In scalar
  3330.             context, it comes back as a single (potentially multi-
  3331.             line) string. In list context, returns a list of lines
  3332.             (however you've defined lines with `$/' or
  3333.             `$INPUT_RECORD_SEPARATOR'). This is the internal
  3334.             function implementing the `qx/EXPR/' operator, but you
  3335.             can use it directly. The `qx/EXPR/' operator is
  3336.             discussed in more detail in the section on "I/O
  3337.             Operators" in the perlop manpage.
  3338.  
  3339.     recv SOCKET,SCALAR,LENGTH,FLAGS
  3340.             Receives a message on a socket. Attempts to receive
  3341.             LENGTH bytes of data into variable SCALAR from the
  3342.             specified SOCKET filehandle. Actually does a C
  3343.             `recvfrom()', so that it can return the address of the
  3344.             sender. Returns the undefined value if there's an error.
  3345.             SCALAR will be grown or shrunk to the length actually
  3346.             read. Takes the same flags as the system call of the
  3347.             same name. See the section on "UDP: Message Passing" in
  3348.             the perlipc manpage for examples.
  3349.  
  3350.     redo LABEL
  3351.  
  3352.     redo    The `redo' command restarts the loop block without
  3353.             evaluating the conditional again. The `continue' block,
  3354.             if any, is not executed. If the LABEL is omitted, the
  3355.             command refers to the innermost enclosing loop. This
  3356.             command is normally used by programs that want to lie to
  3357.             themselves about what was just input:
  3358.  
  3359.                 # a simpleminded Pascal comment stripper
  3360.                 # (warning: assumes no { or } in strings)
  3361.                 LINE: while (<STDIN>) {
  3362.                 while (s|({.*}.*){.*}|$1 |) {}
  3363.                 s|{.*}| |;
  3364.                 if (s|{.*| |) {
  3365.                     $front = $_;
  3366.                     while (<STDIN>) {
  3367.                     if (/}/) {    # end of comment?
  3368.                         s|^|$front\{|;
  3369.                         redo LINE;
  3370.                     }
  3371.                     }
  3372.                 }
  3373.                 print;
  3374.                 }
  3375.  
  3376.  
  3377.             `redo' cannot be used to retry a block which returns a
  3378.             value such as `eval {}', `sub {}' or `do {}', and should
  3379.             not be used to exit a grep() or map() operation.
  3380.  
  3381.             See also the "continue" entry in this manpage for an
  3382.             illustration of how `last', `next', and `redo' work.
  3383.  
  3384.     ref EXPR
  3385.  
  3386.     ref     Returns a TRUE value if EXPR is a reference, FALSE
  3387.             otherwise. If EXPR is not specified, `$_' will be used.
  3388.             The value returned depends on the type of thing the
  3389.             reference is a reference to. Builtin types include:
  3390.  
  3391.                 REF
  3392.                 SCALAR
  3393.                 ARRAY
  3394.                 HASH
  3395.                 CODE
  3396.                 GLOB
  3397.  
  3398.  
  3399.             If the referenced object has been blessed into a
  3400.             package, then that package name is returned instead. You
  3401.             can think of `ref()' as a `typeof()' operator.
  3402.  
  3403.                 if (ref($r) eq "HASH") {
  3404.                 print "r is a reference to a hash.\n";
  3405.                 }
  3406.                 unless (ref($r)) {
  3407.                 print "r is not a reference at all.\n";
  3408.                 }
  3409.                 if (UNIVERSAL::isa($r, "HASH")) {  # for subclassing
  3410.                 print "r is a reference to something that isa hash.\n";
  3411.                 } 
  3412.  
  3413.  
  3414.             See also the perlref manpage.
  3415.  
  3416.     rename OLDNAME,NEWNAME
  3417.             Changes the name of a file. Returns `1' for success, `0'
  3418.             otherwise. Behavior of this function varies wildly
  3419.             depending on your system implementation. For example, it
  3420.             will usually not work across file system boundaries,
  3421.             even though the system *mv* command sometimes
  3422.             compensates for this. Other restrictions include whether
  3423.             it works on directories, open files, or pre-existing
  3424.             files. Check the perlport manpage and either the
  3425.             rename(2) manpage or equivalent system documentation for
  3426.             details.
  3427.  
  3428.     require EXPR
  3429.  
  3430.     require Demands some semantics specified by EXPR, or by `$_' if EXPR
  3431.             is not supplied. If EXPR is numeric, demands that the
  3432.             current version of Perl (`$]' or $PERL_VERSION) be equal
  3433.             or greater than EXPR.
  3434.  
  3435.             Otherwise, demands that a library file be included if it
  3436.             hasn't already been included. The file is included via
  3437.             the do-FILE mechanism, which is essentially just a
  3438.             variety of `eval()'. Has semantics similar to the
  3439.             following subroutine:
  3440.  
  3441.                 sub require {
  3442.                 my($filename) = @_;
  3443.                 return 1 if $INC{$filename};
  3444.                 my($realfilename,$result);
  3445.                 ITER: {
  3446.                     foreach $prefix (@INC) {
  3447.                     $realfilename = "$prefix/$filename";
  3448.                     if (-f $realfilename) {
  3449.                         $result = do $realfilename;
  3450.                         last ITER;
  3451.                     }
  3452.                     }
  3453.                     die "Can't find $filename in \@INC";
  3454.                 }
  3455.                 die $@ if $@;
  3456.                 die "$filename did not return true value" unless $result;
  3457.                 $INC{$filename} = $realfilename;
  3458.                 return $result;
  3459.                 }
  3460.  
  3461.  
  3462.             Note that the file will not be included twice under the
  3463.             same specified name. The file must return TRUE as the
  3464.             last statement to indicate successful execution of any
  3465.             initialization code, so it's customary to end such a
  3466.             file with "`1;'" unless you're sure it'll return TRUE
  3467.             otherwise. But it's better just to put the "`1;'", in
  3468.             case you add more statements.
  3469.  
  3470.             If EXPR is a bareword, the require assumes a ".pm"
  3471.             extension and replaces "::" with "/" in the filename for
  3472.             you, to make it easy to load standard modules. This form
  3473.             of loading of modules does not risk altering your
  3474.             namespace.
  3475.  
  3476.             In other words, if you try this:
  3477.  
  3478.                     require Foo::Bar;    # a splendid bareword 
  3479.  
  3480.  
  3481.             The require function will actually look for the
  3482.             "Foo/Bar.pm" file in the directories specified in the
  3483.             `@INC' array.
  3484.  
  3485.             But if you try this:
  3486.  
  3487.                     $class = 'Foo::Bar';
  3488.                     require $class;         # $class is not a bareword
  3489.                 #or
  3490.                     require "Foo::Bar";  # not a bareword because of the ""
  3491.  
  3492.  
  3493.             The require function will look for the "Foo::Bar" file
  3494.             in the @INC array and will complain about not finding
  3495.             "Foo::Bar" there. In this case you can do:
  3496.  
  3497.                     eval "require $class";
  3498.  
  3499.  
  3500.             For a yet-more-powerful import facility, see the "use"
  3501.             entry in this manpage and the perlmod manpage.
  3502.  
  3503.     reset EXPR
  3504.  
  3505.     reset   Generally used in a `continue' block at the end of a loop to
  3506.             clear variables and reset `??' searches so that they
  3507.             work again. The expression is interpreted as a list of
  3508.             single characters (hyphens allowed for ranges). All
  3509.             variables and arrays beginning with one of those letters
  3510.             are reset to their pristine state. If the expression is
  3511.             omitted, one-match searches (`?pattern?') are reset to
  3512.             match again. Resets only variables or searches in the
  3513.             current package. Always returns 1. Examples:
  3514.  
  3515.                 reset 'X';        # reset all X variables
  3516.                 reset 'a-z';    # reset lower case variables
  3517.                 reset;        # just reset ?one-time? searches
  3518.  
  3519.  
  3520.             Resetting `"A-Z"' is not recommended because you'll wipe
  3521.             out your `@ARGV' and `@INC' arrays and your `%ENV' hash.
  3522.             Resets only package variables--lexical variables are
  3523.             unaffected, but they clean themselves up on scope exit
  3524.             anyway, so you'll probably want to use them instead. See
  3525.             the "my" entry in this manpage.
  3526.  
  3527.     return EXPR
  3528.  
  3529.     return  Returns from a subroutine, `eval()', or `do FILE' with the
  3530.             value given in EXPR. Evaluation of EXPR may be in list,
  3531.             scalar, or void context, depending on how the return
  3532.             value will be used, and the context may vary from one
  3533.             execution to the next (see `wantarray()'). If no EXPR is
  3534.             given, returns an empty list in list context, the
  3535.             undefined value in scalar context, and (of course)
  3536.             nothing at all in a void context.
  3537.  
  3538.             (Note that in the absence of a explicit `return', a
  3539.             subroutine, eval, or do FILE will automatically return
  3540.             the value of the last expression evaluated.)
  3541.  
  3542.     reverse LIST
  3543.             In list context, returns a list value consisting of the
  3544.             elements of LIST in the opposite order. In scalar
  3545.             context, concatenates the elements of LIST and returns a
  3546.             string value with all characters in the opposite order.
  3547.  
  3548.                 print reverse <>;        # line tac, last line first
  3549.  
  3550.                 undef $/;            # for efficiency of <>
  3551.                 print scalar reverse <>;    # character tac, last line tsrif
  3552.  
  3553.  
  3554.             This operator is also handy for inverting a hash,
  3555.             although there are some caveats. If a value is
  3556.             duplicated in the original hash, only one of those can
  3557.             be represented as a key in the inverted hash. Also, this
  3558.             has to unwind one hash and build a whole new one, which
  3559.             may take some time on a large hash, such as from a DBM
  3560.             file.
  3561.  
  3562.                 %by_name = reverse %by_address;    # Invert the hash
  3563.  
  3564.  
  3565.     rewinddir DIRHANDLE
  3566.             Sets the current position to the beginning of the
  3567.             directory for the `readdir()' routine on DIRHANDLE.
  3568.  
  3569.     rindex STR,SUBSTR,POSITION
  3570.  
  3571.     rindex STR,SUBSTR
  3572.             Works just like index() except that it returns the
  3573.             position of the LAST occurrence of SUBSTR in STR. If
  3574.             POSITION is specified, returns the last occurrence at or
  3575.             before that position.
  3576.  
  3577.     rmdir FILENAME
  3578.  
  3579.     rmdir   Deletes the directory specified by FILENAME if that
  3580.             directory is empty. If it succeeds it returns TRUE,
  3581.             otherwise it returns FALSE and sets `$!' (errno). If
  3582.             FILENAME is omitted, uses `$_'.
  3583.  
  3584.     s///    The substitution operator. See the perlop manpage.
  3585.  
  3586.     scalar EXPR
  3587.             Forces EXPR to be interpreted in scalar context and
  3588.             returns the value of EXPR.
  3589.  
  3590.                 @counts = ( scalar @a, scalar @b, scalar @c );
  3591.  
  3592.  
  3593.             There is no equivalent operator to force an expression
  3594.             to be interpolated in list context because in practice,
  3595.             this is never needed. If you really wanted to do so,
  3596.             however, you could use the construction `@{[ (some
  3597.             expression) ]}', but usually a simple `(some
  3598.             expression)' suffices.
  3599.  
  3600.             Since `scalar' is a unary operator, if you accidentally
  3601.             use for EXPR a parenthesized list, this behaves as a
  3602.             scalar comma expression, evaluating all but the last
  3603.             element in void context and returning the final element
  3604.             evaluated in scalar context. This is seldom what you
  3605.             want.
  3606.  
  3607.             The following single statement:
  3608.  
  3609.                 print uc(scalar(&foo,$bar)),$baz;
  3610.  
  3611.  
  3612.             is the moral equivalent of these two:
  3613.  
  3614.                 &foo;
  3615.                 print(uc($bar),$baz);
  3616.  
  3617.  
  3618.             See the perlop manpage for more details on unary
  3619.             operators and the comma operator.
  3620.  
  3621.     seek FILEHANDLE,POSITION,WHENCE
  3622.             Sets FILEHANDLE's position, just like the `fseek()' call
  3623.             of `stdio()'. FILEHANDLE may be an expression whose
  3624.             value gives the name of the filehandle. The values for
  3625.             WHENCE are `0' to set the new position to POSITION, `1'
  3626.             to set it to the current position plus POSITION, and `2'
  3627.             to set it to EOF plus POSITION (typically negative). For
  3628.             WHENCE you may use the constants `SEEK_SET', `SEEK_CUR',
  3629.             and `SEEK_END' from either the `IO::Seekable' or the
  3630.             POSIX module. Returns `1' upon success, `0' otherwise.
  3631.  
  3632.             If you want to position file for `sysread()' or
  3633.             `syswrite()', don't use `seek()' -- buffering makes its
  3634.             effect on the file's system position unpredictable and
  3635.             non-portable. Use `sysseek()' instead.
  3636.  
  3637.             Due to the rules and rigors of ANSI C, on some systems
  3638.             you have to do a seek whenever you switch between
  3639.             reading and writing. Amongst other things, this may have
  3640.             the effect of calling stdio's clearerr(3). A WHENCE of
  3641.             `1' (`SEEK_CUR') is useful for not moving the file
  3642.             position:
  3643.  
  3644.                 seek(TEST,0,1);
  3645.  
  3646.  
  3647.             This is also useful for applications emulating `tail -
  3648.             f'. Once you hit EOF on your read, and then sleep for a
  3649.             while, you might have to stick in a seek() to reset
  3650.             things. The `seek()' doesn't change the current
  3651.             position, but it *does* clear the end-of-file condition
  3652.             on the handle, so that the next `<FILE>' makes Perl try
  3653.             again to read something. We hope.
  3654.  
  3655.             If that doesn't work (some stdios are particularly
  3656.             cantankerous), then you may need something more like
  3657.             this:
  3658.  
  3659.                 for (;;) {
  3660.                 for ($curpos = tell(FILE); $_ = <FILE>;
  3661.                          $curpos = tell(FILE)) {
  3662.                     # search for some stuff and put it into files
  3663.                 }
  3664.                 sleep($for_a_while);
  3665.                 seek(FILE, $curpos, 0);
  3666.                 }
  3667.  
  3668.  
  3669.     seekdir DIRHANDLE,POS
  3670.             Sets the current position for the `readdir()' routine on
  3671.             DIRHANDLE. POS must be a value returned by `telldir()'.
  3672.             Has the same caveats about possible directory compaction
  3673.             as the corresponding system library routine.
  3674.  
  3675.     select FILEHANDLE
  3676.  
  3677.     select  Returns the currently selected filehandle. Sets the current
  3678.             default filehandle for output, if FILEHANDLE is
  3679.             supplied. This has two effects: first, a `write()' or a
  3680.             `print()' without a filehandle will default to this
  3681.             FILEHANDLE. Second, references to variables related to
  3682.             output will refer to this output channel. For example,
  3683.             if you have to set the top of form format for more than
  3684.             one output channel, you might do the following:
  3685.  
  3686.                 select(REPORT1);
  3687.                 $^ = 'report1_top';
  3688.                 select(REPORT2);
  3689.                 $^ = 'report2_top';
  3690.  
  3691.  
  3692.             FILEHANDLE may be an expression whose value gives the
  3693.             name of the actual filehandle. Thus:
  3694.  
  3695.                 $oldfh = select(STDERR); $| = 1; select($oldfh);
  3696.  
  3697.  
  3698.             Some programmers may prefer to think of filehandles as
  3699.             objects with methods, preferring to write the last
  3700.             example as:
  3701.  
  3702.                 use IO::Handle;
  3703.                 STDERR->autoflush(1);
  3704.  
  3705.  
  3706.     select RBITS,WBITS,EBITS,TIMEOUT
  3707.             This calls the select(2) system call with the bit masks
  3708.             specified, which can be constructed using `fileno()' and
  3709.             `vec()', along these lines:
  3710.  
  3711.                 $rin = $win = $ein = '';
  3712.                 vec($rin,fileno(STDIN),1) = 1;
  3713.                 vec($win,fileno(STDOUT),1) = 1;
  3714.                 $ein = $rin | $win;
  3715.  
  3716.  
  3717.             If you want to select on many filehandles you might wish
  3718.             to write a subroutine:
  3719.  
  3720.                 sub fhbits {
  3721.                 my(@fhlist) = split(' ',$_[0]);
  3722.                 my($bits);
  3723.                 for (@fhlist) {
  3724.                     vec($bits,fileno($_),1) = 1;
  3725.                 }
  3726.                 $bits;
  3727.                 }
  3728.                 $rin = fhbits('STDIN TTY SOCK');
  3729.  
  3730.  
  3731.             The usual idiom is:
  3732.  
  3733.                 ($nfound,$timeleft) =
  3734.                   select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
  3735.  
  3736.  
  3737.             or to block until something becomes ready just do this
  3738.  
  3739.                 $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
  3740.  
  3741.  
  3742.             Most systems do not bother to return anything useful in
  3743.             `$timeleft', so calling select() in scalar context just
  3744.             returns `$nfound'.
  3745.  
  3746.             Any of the bit masks can also be undef. The timeout, if
  3747.             specified, is in seconds, which may be fractional. Note:
  3748.             not all implementations are capable of returning
  3749.             the`$timeleft'. If not, they always return `$timeleft'
  3750.             equal to the supplied `$timeout'.
  3751.  
  3752.             You can effect a sleep of 250 milliseconds this way:
  3753.  
  3754.                 select(undef, undef, undef, 0.25);
  3755.  
  3756.  
  3757.             WARNING: One should not attempt to mix buffered I/O
  3758.             (like `read()' or <FH>) with `select()', except as
  3759.             permitted by POSIX, and even then only on POSIX systems.
  3760.             You have to use `sysread()' instead.
  3761.  
  3762.     semctl ID,SEMNUM,CMD,ARG
  3763.             Calls the System V IPC function `semctl()'. You'll
  3764.             probably have to say
  3765.  
  3766.                 use IPC::SysV;
  3767.  
  3768.  
  3769.             first to get the correct constant definitions. If CMD is
  3770.             IPC_STAT or GETALL, then ARG must be a variable which
  3771.             will hold the returned semid_ds structure or semaphore
  3772.             value array. Returns like `ioctl()': the undefined value
  3773.             for error, "`0' but true" for zero, or the actual return
  3774.             value otherwise. See also `IPC::SysV' and
  3775.             `IPC::Semaphore' documentation.
  3776.  
  3777.     semget KEY,NSEMS,FLAGS
  3778.             Calls the System V IPC function semget. Returns the
  3779.             semaphore id, or the undefined value if there is an
  3780.             error. See also `IPC::SysV' and `IPC::SysV::Semaphore'
  3781.             documentation.
  3782.  
  3783.     semop KEY,OPSTRING
  3784.             Calls the System V IPC function semop to perform
  3785.             semaphore operations such as signaling and waiting.
  3786.             OPSTRING must be a packed array of semop structures.
  3787.             Each semop structure can be generated with `pack("sss",
  3788.             $semnum, $semop, $semflag)'. The number of semaphore
  3789.             operations is implied by the length of OPSTRING. Returns
  3790.             TRUE if successful, or FALSE if there is an error. As an
  3791.             example, the following code waits on semaphore `$semnum'
  3792.             of semaphore id `$semid':
  3793.  
  3794.                 $semop = pack("sss", $semnum, -1, 0);
  3795.                 die "Semaphore trouble: $!\n" unless semop($semid, $semop);
  3796.  
  3797.  
  3798.             To signal the semaphore, replace `-1' with `1'. See also
  3799.             `IPC::SysV' and `IPC::SysV::Semaphore' documentation.
  3800.  
  3801.     send SOCKET,MSG,FLAGS,TO
  3802.  
  3803.     send SOCKET,MSG,FLAGS
  3804.             Sends a message on a socket. Takes the same flags as the
  3805.             system call of the same name. On unconnected sockets you
  3806.             must specify a destination to send TO, in which case it
  3807.             does a C `sendto()'. Returns the number of characters
  3808.             sent, or the undefined value if there is an error. The C
  3809.             system call sendmsg(2) is currently unimplemented. See
  3810.             the section on "UDP: Message Passing" in the perlipc
  3811.             manpage for examples.
  3812.  
  3813.     setpgrp PID,PGRP
  3814.             Sets the current process group for the specified PID,
  3815.             `0' for the current process. Will produce a fatal error
  3816.             if used on a machine that doesn't implement setpgrp(2).
  3817.             If the arguments are omitted, it defaults to `0,0'. Note
  3818.             that the POSIX version of `setpgrp()' does not accept
  3819.             any arguments, so only `setpgrp(0,0)' is portable. See
  3820.             also `POSIX::setsid()'.
  3821.  
  3822.     setpriority WHICH,WHO,PRIORITY
  3823.             Sets the current priority for a process, a process
  3824.             group, or a user. (See setpriority(2).) Will produce a
  3825.             fatal error if used on a machine that doesn't implement
  3826.             setpriority(2).
  3827.  
  3828.     setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
  3829.             Sets the socket option requested. Returns undefined if
  3830.             there is an error. OPTVAL may be specified as `undef' if
  3831.             you don't want to pass an argument.
  3832.  
  3833.     shift ARRAY
  3834.  
  3835.     shift   Shifts the first value of the array off and returns it,
  3836.             shortening the array by 1 and moving everything down. If
  3837.             there are no elements in the array, returns the
  3838.             undefined value. If ARRAY is omitted, shifts the `@_'
  3839.             array within the lexical scope of subroutines and
  3840.             formats, and the `@ARGV' array at file scopes or within
  3841.             the lexical scopes established by the `eval ''', `BEGIN
  3842.             {}', `END {}', and `INIT {}' constructs. See also
  3843.             `unshift()', `push()', and `pop()'. `Shift()' and
  3844.             `unshift()' do the same thing to the left end of an
  3845.             array that `pop()' and `push()' do to the right end.
  3846.  
  3847.     shmctl ID,CMD,ARG
  3848.             Calls the System V IPC function shmctl. You'll probably
  3849.             have to say
  3850.  
  3851.                 use IPC::SysV;
  3852.  
  3853.  
  3854.             first to get the correct constant definitions. If CMD is
  3855.             `IPC_STAT', then ARG must be a variable which will hold
  3856.             the returned `shmid_ds' structure. Returns like ioctl:
  3857.             the undefined value for error, "`0' but true" for zero,
  3858.             or the actual return value otherwise. See also
  3859.             `IPC::SysV' documentation.
  3860.  
  3861.     shmget KEY,SIZE,FLAGS
  3862.             Calls the System V IPC function shmget. Returns the
  3863.             shared memory segment id, or the undefined value if
  3864.             there is an error. See also `IPC::SysV' documentation.
  3865.  
  3866.     shmread ID,VAR,POS,SIZE
  3867.  
  3868.     shmwrite ID,STRING,POS,SIZE
  3869.             Reads or writes the System V shared memory segment ID
  3870.             starting at position POS for size SIZE by attaching to
  3871.             it, copying in/out, and detaching from it. When reading,
  3872.             VAR must be a variable that will hold the data read.
  3873.             When writing, if STRING is too long, only SIZE bytes are
  3874.             used; if STRING is too short, nulls are written to fill
  3875.             out SIZE bytes. Return TRUE if successful, or FALSE if
  3876.             there is an error. See also `IPC::SysV' documentation
  3877.             and the `IPC::Shareable' module from CPAN.
  3878.  
  3879.     shutdown SOCKET,HOW
  3880.             Shuts down a socket connection in the manner indicated
  3881.             by HOW, which has the same interpretation as in the
  3882.             system call of the same name.
  3883.  
  3884.                 shutdown(SOCKET, 0);    # I/we have stopped reading data
  3885.                 shutdown(SOCKET, 1);    # I/we have stopped writing data
  3886.                 shutdown(SOCKET, 2);    # I/we have stopped using this socket
  3887.  
  3888.  
  3889.             This is useful with sockets when you want to tell the
  3890.             other side you're done writing but not done reading, or
  3891.             vice versa. It's also a more insistent form of close
  3892.             because it also disables the filedescriptor in any
  3893.             forked copies in other processes.
  3894.  
  3895.     sin EXPR
  3896.  
  3897.     sin     Returns the sine of EXPR (expressed in radians). If EXPR is
  3898.             omitted, returns sine of `$_'.
  3899.  
  3900.             For the inverse sine operation, you may use the
  3901.             `POSIX::asin()' function, or use this relation:
  3902.  
  3903.                 sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
  3904.  
  3905.  
  3906.     sleep EXPR
  3907.  
  3908.     sleep   Causes the script to sleep for EXPR seconds, or forever if
  3909.             no EXPR. May be interrupted if the process receives a
  3910.             signal such as `SIGALRM'. Returns the number of seconds
  3911.             actually slept. You probably cannot mix `alarm()' and
  3912.             `sleep()' calls, because `sleep()' is often implemented
  3913.             using `alarm()'.
  3914.  
  3915.             On some older systems, it may sleep up to a full second
  3916.             less than what you requested, depending on how it counts
  3917.             seconds. Most modern systems always sleep the full
  3918.             amount. They may appear to sleep longer than that,
  3919.             however, because your process might not be scheduled
  3920.             right away in a busy multitasking system.
  3921.  
  3922.             For delays of finer granularity than one second, you may
  3923.             use Perl's `syscall()' interface to access setitimer(2)
  3924.             if your system supports it, or else see the "select"
  3925.             entry in this manpage above.
  3926.  
  3927.             See also the POSIX module's `sigpause()' function.
  3928.  
  3929.     socket SOCKET,DOMAIN,TYPE,PROTOCOL
  3930.             Opens a socket of the specified kind and attaches it to
  3931.             filehandle SOCKET. DOMAIN, TYPE, and PROTOCOL are
  3932.             specified the same as for the system call of the same
  3933.             name. You should "`use Socket;'" first to get the proper
  3934.             definitions imported. See the examples in the section on
  3935.             "Sockets: Client/Server Communication" in the perlipc
  3936.             manpage.
  3937.  
  3938.     socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
  3939.             Creates an unnamed pair of sockets in the specified
  3940.             domain, of the specified type. DOMAIN, TYPE, and
  3941.             PROTOCOL are specified the same as for the system call
  3942.             of the same name. If unimplemented, yields a fatal
  3943.             error. Returns TRUE if successful.
  3944.  
  3945.             Some systems defined `pipe()' in terms of
  3946.             `socketpair()', in which a call to `pipe(Rdr, Wtr)' is
  3947.             essentially:
  3948.  
  3949.                 use Socket;
  3950.                 socketpair(Rdr, Wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC);
  3951.                 shutdown(Rdr, 1);        # no more writing for reader
  3952.                 shutdown(Wtr, 0);        # no more reading for writer
  3953.  
  3954.  
  3955.             See the perlipc manpage for an example of socketpair
  3956.             use.
  3957.  
  3958.     sort SUBNAME LIST
  3959.  
  3960.     sort BLOCK LIST
  3961.  
  3962.     sort LIST
  3963.             Sorts the LIST and returns the sorted list value. If
  3964.             SUBNAME or BLOCK is omitted, `sort()'s in standard
  3965.             string comparison order. If SUBNAME is specified, it
  3966.             gives the name of a subroutine that returns an integer
  3967.             less than, equal to, or greater than `0', depending on
  3968.             how the elements of the array are to be ordered. (The
  3969.             `<=>' and `cmp' operators are extremely useful in such
  3970.             routines.) SUBNAME may be a scalar variable name
  3971.             (unsubscripted), in which case the value provides the
  3972.             name of (or a reference to) the actual subroutine to
  3973.             use. In place of a SUBNAME, you can provide a BLOCK as
  3974.             an anonymous, in-line sort subroutine.
  3975.  
  3976.             In the interests of efficiency the normal calling code
  3977.             for subroutines is bypassed, with the following effects:
  3978.             the subroutine may not be a recursive subroutine, and
  3979.             the two elements to be compared are passed into the
  3980.             subroutine not via `@_' but as the package global
  3981.             variables `$a' and `$b' (see example below). They are
  3982.             passed by reference, so don't modify `$a' and `$b'. And
  3983.             don't try to declare them as lexicals either.
  3984.  
  3985.             You also cannot exit out of the sort block or subroutine
  3986.             using any of the loop control operators described in the
  3987.             perlsyn manpage or with `goto()'.
  3988.  
  3989.             When `use locale' is in effect, `sort LIST' sorts LIST
  3990.             according to the current collation locale. See the
  3991.             perllocale manpage.
  3992.  
  3993.             Examples:
  3994.  
  3995.                 # sort lexically
  3996.                 @articles = sort @files;
  3997.  
  3998.                 # same thing, but with explicit sort routine
  3999.                 @articles = sort {$a cmp $b} @files;
  4000.  
  4001.                 # now case-insensitively
  4002.                 @articles = sort {uc($a) cmp uc($b)} @files;
  4003.  
  4004.                 # same thing in reversed order
  4005.                 @articles = sort {$b cmp $a} @files;
  4006.  
  4007.                 # sort numerically ascending
  4008.                 @articles = sort {$a <=> $b} @files;
  4009.  
  4010.                 # sort numerically descending
  4011.                 @articles = sort {$b <=> $a} @files;
  4012.  
  4013.                 # sort using explicit subroutine name
  4014.                 sub byage {
  4015.                 $age{$a} <=> $age{$b};    # presuming numeric
  4016.                 }
  4017.                 @sortedclass = sort byage @class;
  4018.  
  4019.                 # this sorts the %age hash by value instead of key
  4020.                 # using an in-line function
  4021.                 @eldest = sort { $age{$b} <=> $age{$a} } keys %age;
  4022.  
  4023.                 sub backwards { $b cmp $a; }
  4024.                 @harry = ('dog','cat','x','Cain','Abel');
  4025.                 @george = ('gone','chased','yz','Punished','Axed');
  4026.                 print sort @harry;
  4027.                     # prints AbelCaincatdogx
  4028.                 print sort backwards @harry;
  4029.                     # prints xdogcatCainAbel
  4030.                 print sort @george, 'to', @harry;
  4031.                     # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
  4032.  
  4033.                 # inefficiently sort by descending numeric compare using
  4034.                 # the first integer after the first = sign, or the
  4035.                 # whole record case-insensitively otherwise
  4036.  
  4037.                 @new = sort {
  4038.                 ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
  4039.                             ||
  4040.                             uc($a)  cmp  uc($b)
  4041.                 } @old;
  4042.  
  4043.                 # same thing, but much more efficiently;
  4044.                 # we'll build auxiliary indices instead
  4045.                 # for speed
  4046.                 @nums = @caps = ();
  4047.                 for (@old) {
  4048.                 push @nums, /=(\d+)/;
  4049.                 push @caps, uc($_);
  4050.                 }
  4051.  
  4052.                 @new = @old[ sort {
  4053.                         $nums[$b] <=> $nums[$a]
  4054.                              ||
  4055.                         $caps[$a] cmp $caps[$b]
  4056.                            } 0..$#old
  4057.                        ];
  4058.  
  4059.                 # same thing using a Schwartzian Transform (no temps)
  4060.                 @new = map { $_->[0] }
  4061.                     sort { $b->[1] <=> $a->[1]
  4062.                                     ||
  4063.                            $a->[2] cmp $b->[2]
  4064.                     } map { [$_, /=(\d+)/, uc($_)] } @old;
  4065.  
  4066.  
  4067.             If you're using strict, you *MUST NOT* declare `$a' and
  4068.             `$b' as lexicals. They are package globals. That means
  4069.             if you're in the `main' package, it's
  4070.  
  4071.                 @articles = sort {$main::b <=> $main::a} @files;
  4072.  
  4073.  
  4074.             or just
  4075.  
  4076.                 @articles = sort {$::b <=> $::a} @files;
  4077.  
  4078.  
  4079.             but if you're in the `FooPack' package, it's
  4080.  
  4081.                 @articles = sort {$FooPack::b <=> $FooPack::a} @files;
  4082.  
  4083.  
  4084.             The comparison function is required to behave. If it
  4085.             returns inconsistent results (sometimes saying `$x[1]'
  4086.             is less than `$x[2]' and sometimes saying the opposite,
  4087.             for example) the results are not well-defined.
  4088.  
  4089.     splice ARRAY,OFFSET,LENGTH,LIST
  4090.  
  4091.     splice ARRAY,OFFSET,LENGTH
  4092.  
  4093.     splice ARRAY,OFFSET
  4094.             Removes the elements designated by OFFSET and LENGTH
  4095.             from an array, and replaces them with the elements of
  4096.             LIST, if any. In list context, returns the elements
  4097.             removed from the array. In scalar context, returns the
  4098.             last element removed, or `undef' if no elements are
  4099.             removed. The array grows or shrinks as necessary. If
  4100.             OFFSET is negative then it start that far from the end
  4101.             of the array. If LENGTH is omitted, removes everything
  4102.             from OFFSET onward. If LENGTH is negative, leave that
  4103.             many elements off the end of the array. The following
  4104.             equivalences hold (assuming `$[ == 0'):
  4105.  
  4106.                 push(@a,$x,$y)    splice(@a,@a,0,$x,$y)
  4107.                 pop(@a)        splice(@a,-1)
  4108.                 shift(@a)        splice(@a,0,1)
  4109.                 unshift(@a,$x,$y)    splice(@a,0,0,$x,$y)
  4110.                 $a[$x] = $y        splice(@a,$x,1,$y)
  4111.  
  4112.  
  4113.             Example, assuming array lengths are passed before
  4114.             arrays:
  4115.  
  4116.                 sub aeq {    # compare two list values
  4117.                 my(@a) = splice(@_,0,shift);
  4118.                 my(@b) = splice(@_,0,shift);
  4119.                 return 0 unless @a == @b;    # same len?
  4120.                 while (@a) {
  4121.                     return 0 if pop(@a) ne pop(@b);
  4122.                 }
  4123.                 return 1;
  4124.                 }
  4125.                 if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
  4126.  
  4127.  
  4128.     split /PATTERN/,EXPR,LIMIT
  4129.  
  4130.     split /PATTERN/,EXPR
  4131.  
  4132.     split /PATTERN/
  4133.  
  4134.     split   Splits a string into an array of strings, and returns it. By
  4135.             default, empty leading fields are preserved, and empty
  4136.             trailing ones are deleted.
  4137.  
  4138.             If not in list context, returns the number of fields
  4139.             found and splits into the `@_' array. (In list context,
  4140.             you can force the split into `@_' by using `??' as the
  4141.             pattern delimiters, but it still returns the list
  4142.             value.) The use of implicit split to `@_' is deprecated,
  4143.             however, because it clobbers your subroutine arguments.
  4144.  
  4145.             If EXPR is omitted, splits the `$_' string. If PATTERN
  4146.             is also omitted, splits on whitespace (after skipping
  4147.             any leading whitespace). Anything matching PATTERN is
  4148.             taken to be a delimiter separating the fields. (Note
  4149.             that the delimiter may be longer than one character.)
  4150.  
  4151.             If LIMIT is specified and positive, splits into no more
  4152.             than that many fields (though it may split into fewer).
  4153.             If LIMIT is unspecified or zero, trailing null fields
  4154.             are stripped (which potential users of `pop()' would do
  4155.             well to remember). If LIMIT is negative, it is treated
  4156.             as if an arbitrarily large LIMIT had been specified.
  4157.  
  4158.             A pattern matching the null string (not to be confused
  4159.             with a null pattern `//', which is just one member of
  4160.             the set of patterns matching a null string) will split
  4161.             the value of EXPR into separate characters at each point
  4162.             it matches that way. For example:
  4163.  
  4164.                 print join(':', split(/ */, 'hi there'));
  4165.  
  4166.  
  4167.             produces the output 'h:i:t:h:e:r:e'.
  4168.  
  4169.             The LIMIT parameter can be used to split a line
  4170.             partially
  4171.  
  4172.                 ($login, $passwd, $remainder) = split(/:/, $_, 3);
  4173.  
  4174.  
  4175.             When assigning to a list, if LIMIT is omitted, Perl
  4176.             supplies a LIMIT one larger than the number of variables
  4177.             in the list, to avoid unnecessary work. For the list
  4178.             above LIMIT would have been 4 by default. In time
  4179.             critical applications it behooves you not to split into
  4180.             more fields than you really need.
  4181.  
  4182.             If the PATTERN contains parentheses, additional array
  4183.             elements are created from each matching substring in the
  4184.             delimiter.
  4185.  
  4186.                 split(/([,-])/, "1-10,20", 3);
  4187.  
  4188.  
  4189.             produces the list value
  4190.  
  4191.                 (1, '-', 10, ',', 20)
  4192.  
  4193.  
  4194.             If you had the entire header of a normal Unix email
  4195.             message in `$header', you could split it up into fields
  4196.             and their values this way:
  4197.  
  4198.                 $header =~ s/\n\s+/ /g;  # fix continuation lines
  4199.                 %hdrs   =  (UNIX_FROM => split /^(\S*?):\s*/m, $header);
  4200.  
  4201.  
  4202.             The pattern `/PATTERN/' may be replaced with an
  4203.             expression to specify patterns that vary at runtime. (To
  4204.             do runtime compilation only once, use `/$variable/o'.)
  4205.  
  4206.             As a special case, specifying a PATTERN of space (`' '')
  4207.             will split on white space just as `split()' with no
  4208.             arguments does. Thus, `split(' ')' can be used to
  4209.             emulate awk's default behavior, whereas `split(/ /)'
  4210.             will give you as many null initial fields as there are
  4211.             leading spaces. A `split()' on `/\s+/' is like a
  4212.             `split(' ')' except that any leading whitespace produces
  4213.             a null first field. A `split()' with no arguments really
  4214.             does a `split(' ', $_)' internally.
  4215.  
  4216.             Example:
  4217.  
  4218.                 open(PASSWD, '/etc/passwd');
  4219.                 while (<PASSWD>) {
  4220.                 ($login, $passwd, $uid, $gid,
  4221.                      $gcos, $home, $shell) = split(/:/);
  4222.                 #...
  4223.                 }
  4224.  
  4225.  
  4226.             (Note that `$shell' above will still have a newline on
  4227.             it. See the "chop" entry in this manpage, the "chomp"
  4228.             entry in this manpage, and the "join" entry in this
  4229.             manpage.)
  4230.  
  4231.     sprintf FORMAT, LIST
  4232.             Returns a string formatted by the usual `printf()'
  4233.             conventions of the C library function `sprintf()'. See
  4234.             the sprintf(3) manpage or the printf(3) manpage on your
  4235.             system for an explanation of the general principles.
  4236.  
  4237.             Perl does its own `sprintf()' formatting -- it emulates
  4238.             the C function `sprintf()', but it doesn't use it
  4239.             (except for floating-point numbers, and even then only
  4240.             the standard modifiers are allowed). As a result, any
  4241.             non-standard extensions in your local `sprintf()' are
  4242.             not available from Perl.
  4243.  
  4244.             Perl's `sprintf()' permits the following universally-
  4245.             known conversions:
  4246.  
  4247.                %%    a percent sign
  4248.                %c    a character with the given number
  4249.                %s    a string
  4250.                %d    a signed integer, in decimal
  4251.                %u    an unsigned integer, in decimal
  4252.                %o    an unsigned integer, in octal
  4253.                %x    an unsigned integer, in hexadecimal
  4254.                %e    a floating-point number, in scientific notation
  4255.                %f    a floating-point number, in fixed decimal notation
  4256.                %g    a floating-point number, in %e or %f notation
  4257.  
  4258.  
  4259.             In addition, Perl permits the following widely-supported
  4260.             conversions:
  4261.  
  4262.                %X    like %x, but using upper-case letters
  4263.                %E    like %e, but using an upper-case "E"
  4264.                %G    like %g, but with an upper-case "E" (if applicable)
  4265.                %p    a pointer (outputs the Perl value's address in hexadecimal)
  4266.                %n    special: *stores* the number of characters output so far
  4267.                     into the next variable in the parameter list 
  4268.  
  4269.  
  4270.             Finally, for backward (and we do mean "backward")
  4271.             compatibility, Perl permits these unnecessary but
  4272.             widely-supported conversions:
  4273.  
  4274.                %i    a synonym for %d
  4275.                %D    a synonym for %ld
  4276.                %U    a synonym for %lu
  4277.                %O    a synonym for %lo
  4278.                %F    a synonym for %f
  4279.  
  4280.  
  4281.             Perl permits the following universally-known flags
  4282.             between the `%' and the conversion letter:
  4283.  
  4284.                space   prefix positive number with a space
  4285.                +       prefix positive number with a plus sign
  4286.                -       left-justify within the field
  4287.                0       use zeros, not spaces, to right-justify
  4288.                #       prefix non-zero octal with "0", non-zero hex with "0x"
  4289.                number  minimum field width
  4290.                .number "precision": digits after decimal point for
  4291.                        floating-point, max length for string, minimum length
  4292.                        for integer
  4293.                l       interpret integer as C type "long" or "unsigned long"
  4294.                h       interpret integer as C type "short" or "unsigned short"
  4295.  
  4296.  
  4297.             There is also one Perl-specific flag:
  4298.  
  4299.                V       interpret integer as Perl's standard integer type
  4300.  
  4301.  
  4302.             Where a number would appear in the flags, an asterisk
  4303.             ("`*'") may be used instead, in which case Perl uses the
  4304.             next item in the parameter list as the given number
  4305.             (that is, as the field width or precision). If a field
  4306.             width obtained through "`*'" is negative, it has the
  4307.             same effect as the "`-'" flag: left-justification.
  4308.  
  4309.             If `use locale' is in effect, the character used for the
  4310.             decimal point in formatted real numbers is affected by
  4311.             the LC_NUMERIC locale. See the perllocale manpage.
  4312.  
  4313.     sqrt EXPR
  4314.  
  4315.     sqrt    Return the square root of EXPR. If EXPR is omitted, returns
  4316.             square root of `$_'. Only works on non-negative
  4317.             operands, unless you've loaded the standard
  4318.             Math::Complex module.
  4319.  
  4320.                 use Math::Complex;
  4321.                 print sqrt(-2);    # prints 1.4142135623731i
  4322.  
  4323.  
  4324.     srand EXPR
  4325.  
  4326.     srand   Sets the random number seed for the `rand()' operator. If
  4327.             EXPR is omitted, uses a semi-random value supplied by
  4328.             the kernel (if it supports the /dev/urandom device) or
  4329.             based on the current time and process ID, among other
  4330.             things. In versions of Perl prior to 5.004 the default
  4331.             seed was just the current `time()'. This isn't a
  4332.             particularly good seed, so many old programs supply
  4333.             their own seed value (often `time ^ $$' or `time ^ ($$ +
  4334.             ($$ << 15))'), but that isn't necessary any more.
  4335.  
  4336.             In fact, it's usually not necessary to call `srand()' at
  4337.             all, because if it is not called explicitly, it is
  4338.             called implicitly at the first use of the `rand()'
  4339.             operator. However, this was not the case in version of
  4340.             Perl before 5.004, so if your script will run under
  4341.             older Perl versions, it should call `srand()'.
  4342.  
  4343.             Note that you need something much more random than the
  4344.             default seed for cryptographic purposes. Checksumming
  4345.             the compressed output of one or more rapidly changing
  4346.             operating system status programs is the usual method.
  4347.             For example:
  4348.  
  4349.                 srand (time ^ $$ ^ unpack "%L*", `ps axww | gzip`);
  4350.  
  4351.  
  4352.             If you're particularly concerned with this, see the
  4353.             `Math::TrulyRandom' module in CPAN.
  4354.  
  4355.             Do *not* call `srand()' multiple times in your program
  4356.             unless you know exactly what you're doing and why you're
  4357.             doing it. The point of the function is to "seed" the
  4358.             `rand()' function so that `rand()' can produce a
  4359.             different sequence each time you run your program. Just
  4360.             do it once at the top of your program, or you *won't*
  4361.             get random numbers out of `rand()'!
  4362.  
  4363.             Frequently called programs (like CGI scripts) that
  4364.             simply use
  4365.  
  4366.                 time ^ $$
  4367.  
  4368.  
  4369.             for a seed can fall prey to the mathematical property
  4370.             that
  4371.  
  4372.                 a^b == (a+1)^(b+1)
  4373.  
  4374.  
  4375.             one-third of the time. So don't do that.
  4376.  
  4377.     stat FILEHANDLE
  4378.  
  4379.     stat EXPR
  4380.  
  4381.     stat    Returns a 13-element list giving the status info for a file,
  4382.             either the file opened via FILEHANDLE, or named by EXPR.
  4383.             If EXPR is omitted, it stats `$_'. Returns a null list
  4384.             if the stat fails. Typically used as follows:
  4385.  
  4386.                 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
  4387.                    $atime,$mtime,$ctime,$blksize,$blocks)
  4388.                        = stat($filename);
  4389.  
  4390.  
  4391.             Not all fields are supported on all filesystem types.
  4392.             Here are the meaning of the fields:
  4393.  
  4394.               0 dev      device number of filesystem
  4395.               1 ino      inode number
  4396.               2 mode     file mode  (type and permissions)
  4397.               3 nlink    number of (hard) links to the file
  4398.               4 uid      numeric user ID of file's owner
  4399.               5 gid      numeric group ID of file's owner
  4400.               6 rdev     the device identifier (special files only)
  4401.               7 size     total size of file, in bytes
  4402.               8 atime    last access time since the epoch
  4403.               9 mtime    last modify time since the epoch
  4404.              10 ctime    inode change time (NOT creation time!) since the epoch
  4405.              11 blksize  preferred block size for file system I/O
  4406.              12 blocks   actual number of blocks allocated
  4407.  
  4408.  
  4409.             (The epoch was at 00:00 January 1, 1970 GMT.)
  4410.  
  4411.             If stat is passed the special filehandle consisting of
  4412.             an underline, no stat is done, but the current contents
  4413.             of the stat structure from the last stat or filetest are
  4414.             returned. Example:
  4415.  
  4416.                 if (-x $file && (($d) = stat(_)) && $d < 0) {
  4417.                 print "$file is executable NFS file\n";
  4418.                 }
  4419.  
  4420.  
  4421.             (This works on machines only for which the device number
  4422.             is negative under NFS.)
  4423.  
  4424.             Because the mode contains both the file type and its
  4425.             permissions, you should mask off the file type portion
  4426.             and (s)printf using a `"%o"' if you want to see the real
  4427.             permissions.
  4428.  
  4429.                 $mode = (stat($filename))[2];
  4430.                 printf "Permissions are %04o\n", $mode & 07777;
  4431.  
  4432.  
  4433.             In scalar context, `stat()' returns a boolean value
  4434.             indicating success or failure, and, if successful, sets
  4435.             the information associated with the special filehandle
  4436.             `_'.
  4437.  
  4438.             The File::stat module provides a convenient, by-name
  4439.             access mechanism:
  4440.  
  4441.                 use File::stat;
  4442.                 $sb = stat($filename);
  4443.                 printf "File is %s, size is %s, perm %04o, mtime %s\n", 
  4444.                 $filename, $sb->size, $sb->mode & 07777,
  4445.                 scalar localtime $sb->mtime;
  4446.  
  4447.  
  4448.     study SCALAR
  4449.  
  4450.     study   Takes extra time to study SCALAR (`$_' if unspecified) in
  4451.             anticipation of doing many pattern matches on the string
  4452.             before it is next modified. This may or may not save
  4453.             time, depending on the nature and number of patterns you
  4454.             are searching on, and on the distribution of character
  4455.             frequencies in the string to be searched -- you probably
  4456.             want to compare run times with and without it to see
  4457.             which runs faster. Those loops which scan for many short
  4458.             constant strings (including the constant parts of more
  4459.             complex patterns) will benefit most. You may have only
  4460.             one `study()' active at a time -- if you study a
  4461.             different scalar the first is "unstudied". (The way
  4462.             `study()' works is this: a linked list of every
  4463.             character in the string to be searched is made, so we
  4464.             know, for example, where all the `'k'' characters are.
  4465.             From each search string, the rarest character is
  4466.             selected, based on some static frequency tables
  4467.             constructed from some C programs and English text. Only
  4468.             those places that contain this "rarest" character are
  4469.             examined.)
  4470.  
  4471.             For example, here is a loop that inserts index producing
  4472.             entries before any line containing a certain pattern:
  4473.  
  4474.                 while (<>) {
  4475.                 study;
  4476.                 print ".IX foo\n"     if /\bfoo\b/;
  4477.                 print ".IX bar\n"     if /\bbar\b/;
  4478.                 print ".IX blurfl\n"     if /\bblurfl\b/;
  4479.                 # ...
  4480.                 print;
  4481.                 }
  4482.  
  4483.  
  4484.             In searching for `/\bfoo\b/', only those locations in
  4485.             `$_' that contain `"f"' will be looked at, because `"f"'
  4486.             is rarer than `"o"'. In general, this is a big win
  4487.             except in pathological cases. The only question is
  4488.             whether it saves you more time than it took to build the
  4489.             linked list in the first place.
  4490.  
  4491.             Note that if you have to look for strings that you don't
  4492.             know till runtime, you can build an entire loop as a
  4493.             string and `eval()' that to avoid recompiling all your
  4494.             patterns all the time. Together with undefining `$/' to
  4495.             input entire files as one record, this can be very fast,
  4496.             often faster than specialized programs like fgrep(1).
  4497.             The following scans a list of files (`@files') for a
  4498.             list of words (`@words'), and prints out the names of
  4499.             those files that contain a match:
  4500.  
  4501.                 $search = 'while (<>) { study;';
  4502.                 foreach $word (@words) {
  4503.                 $search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n";
  4504.                 }
  4505.                 $search .= "}";
  4506.                 @ARGV = @files;
  4507.                 undef $/;
  4508.                 eval $search;        # this screams
  4509.                 $/ = "\n";        # put back to normal input delimiter
  4510.                 foreach $file (sort keys(%seen)) {
  4511.                 print $file, "\n";
  4512.                 }
  4513.  
  4514.  
  4515.     sub BLOCK
  4516.  
  4517.     sub NAME
  4518.  
  4519.     sub NAME BLOCK
  4520.             This is subroutine definition, not a real function *per
  4521.             se*. With just a NAME (and possibly prototypes), it's
  4522.             just a forward declaration. Without a NAME, it's an
  4523.             anonymous function declaration, and does actually return
  4524.             a value: the CODE ref of the closure you just created.
  4525.             See the perlsub manpage and the perlref manpage for
  4526.             details.
  4527.  
  4528.     substr EXPR,OFFSET,LEN,REPLACEMENT
  4529.  
  4530.     substr EXPR,OFFSET,LEN
  4531.  
  4532.     substr EXPR,OFFSET
  4533.             Extracts a substring out of EXPR and returns it. First
  4534.             character is at offset `0', or whatever you've set `$['
  4535.             to (but don't do that). If OFFSET is negative (or more
  4536.             precisely, less than `$['), starts that far from the end
  4537.             of the string. If LEN is omitted, returns everything to
  4538.             the end of the string. If LEN is negative, leaves that
  4539.             many characters off the end of the string.
  4540.  
  4541.             If you specify a substring that is partly outside the
  4542.             string, the part within the string is returned. If the
  4543.             substring is totally outside the string a warning is
  4544.             produced.
  4545.  
  4546.             You can use the substr() function as an lvalue, in which
  4547.             case EXPR must itself be an lvalue. If you assign
  4548.             something shorter than LEN, the string will shrink, and
  4549.             if you assign something longer than LEN, the string will
  4550.             grow to accommodate it. To keep the string the same
  4551.             length you may need to pad or chop your value using
  4552.             `sprintf()'.
  4553.  
  4554.             An alternative to using substr() as an lvalue is to
  4555.             specify the replacement string as the 4th argument. This
  4556.             allows you to replace parts of the EXPR and return what
  4557.             was there before in one operation, just as you can with
  4558.             splice().
  4559.  
  4560.     symlink OLDFILE,NEWFILE
  4561.             Creates a new filename symbolically linked to the old
  4562.             filename. Returns `1' for success, `0' otherwise. On
  4563.             systems that don't support symbolic links, produces a
  4564.             fatal error at run time. To check for that, use eval:
  4565.  
  4566.                 $symlink_exists = eval { symlink("",""); 1 };
  4567.  
  4568.  
  4569.     syscall LIST
  4570.             Calls the system call specified as the first element of
  4571.             the list, passing the remaining elements as arguments to
  4572.             the system call. If unimplemented, produces a fatal
  4573.             error. The arguments are interpreted as follows: if a
  4574.             given argument is numeric, the argument is passed as an
  4575.             int. If not, the pointer to the string value is passed.
  4576.             You are responsible to make sure a string is pre-
  4577.             extended long enough to receive any result that might be
  4578.             written into a string. You can't use a string literal
  4579.             (or other read-only string) as an argument to
  4580.             `syscall()' because Perl has to assume that any string
  4581.             pointer might be written through. If your integer
  4582.             arguments are not literals and have never been
  4583.             interpreted in a numeric context, you may need to add
  4584.             `0' to them to force them to look like numbers. This
  4585.             emulates the `syswrite()' function (or vice versa):
  4586.  
  4587.                 require 'syscall.ph';        # may need to run h2ph
  4588.                 $s = "hi there\n";
  4589.                 syscall(&SYS_write, fileno(STDOUT), $s, length $s);
  4590.  
  4591.  
  4592.             Note that Perl supports passing of up to only 14
  4593.             arguments to your system call, which in practice should
  4594.             usually suffice.
  4595.  
  4596.             Syscall returns whatever value returned by the system
  4597.             call it calls. If the system call fails, `syscall()'
  4598.             returns `-1' and sets `$!' (errno). Note that some
  4599.             system calls can legitimately return `-1'. The proper
  4600.             way to handle such calls is to assign `$!=0;' before the
  4601.             call and check the value of `$!' if syscall returns `-
  4602.             1'.
  4603.  
  4604.             There's a problem with `syscall(&SYS_pipe)': it returns
  4605.             the file number of the read end of the pipe it creates.
  4606.             There is no way to retrieve the file number of the other
  4607.             end. You can avoid this problem by using `pipe()'
  4608.             instead.
  4609.  
  4610.     sysopen FILEHANDLE,FILENAME,MODE
  4611.  
  4612.     sysopen FILEHANDLE,FILENAME,MODE,PERMS
  4613.             Opens the file whose filename is given by FILENAME, and
  4614.             associates it with FILEHANDLE. If FILEHANDLE is an
  4615.             expression, its value is used as the name of the real
  4616.             filehandle wanted. This function calls the underlying
  4617.             operating system's `open()' function with the parameters
  4618.             FILENAME, MODE, PERMS.
  4619.  
  4620.             The possible values and flag bits of the MODE parameter
  4621.             are system-dependent; they are available via the
  4622.             standard module `Fcntl'. For historical reasons, some
  4623.             values work on almost every system supported by perl:
  4624.             zero means read-only, one means write-only, and two
  4625.             means read/write. We know that these values do *not*
  4626.             work under OS/390 & VM/ESA Unix and on the Macintosh;
  4627.             you probably don't want to use them in new code.
  4628.  
  4629.             If the file named by FILENAME does not exist and the
  4630.             `open()' call creates it (typically because MODE
  4631.             includes the `O_CREAT' flag), then the value of PERMS
  4632.             specifies the permissions of the newly created file. If
  4633.             you omit the PERMS argument to `sysopen()', Perl uses
  4634.             the octal value `0666'. These permission values need to
  4635.             be in octal, and are modified by your process's current
  4636.             `umask'.
  4637.  
  4638.             You should seldom if ever use `0644' as argument to
  4639.             `sysopen()', because that takes away the user's option
  4640.             to have a more permissive umask. Better to omit it. See
  4641.             the perlfunc(1) entry on `umask' for more on this.
  4642.  
  4643.             See the perlopentut manpage for a kinder, gentler
  4644.             explanation of opening files.
  4645.  
  4646.     sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
  4647.  
  4648.     sysread FILEHANDLE,SCALAR,LENGTH
  4649.             Attempts to read LENGTH bytes of data into variable
  4650.             SCALAR from the specified FILEHANDLE, using the system
  4651.             call read(2). It bypasses stdio, so mixing this with
  4652.             other kinds of reads, `print()', `write()', `seek()',
  4653.             `tell()', or `eof()' can cause confusion because stdio
  4654.             usually buffers data. Returns the number of bytes
  4655.             actually read, `0' at end of file, or undef if there was
  4656.             an error. SCALAR will be grown or shrunk so that the
  4657.             last byte actually read is the last byte of the scalar
  4658.             after the read.
  4659.  
  4660.             An OFFSET may be specified to place the read data at
  4661.             some place in the string other than the beginning. A
  4662.             negative OFFSET specifies placement at that many bytes
  4663.             counting backwards from the end of the string. A
  4664.             positive OFFSET greater than the length of SCALAR
  4665.             results in the string being padded to the required size
  4666.             with `"\0"' bytes before the result of the read is
  4667.             appended.
  4668.  
  4669.             There is no syseof() function, which is ok, since eof()
  4670.             doesn't work very well on device files (like ttys)
  4671.             anyway. Use sysread() and check for a return value for 0
  4672.             to decide whether you're done.
  4673.  
  4674.     sysseek FILEHANDLE,POSITION,WHENCE
  4675.             Sets FILEHANDLE's system position using the system call
  4676.             lseek(2). It bypasses stdio, so mixing this with reads
  4677.             (other than `sysread()'), `print()', `write()',
  4678.             `seek()', `tell()', or `eof()' may cause confusion.
  4679.             FILEHANDLE may be an expression whose value gives the
  4680.             name of the filehandle. The values for WHENCE are `0' to
  4681.             set the new position to POSITION, `1' to set the it to
  4682.             the current position plus POSITION, and `2' to set it to
  4683.             EOF plus POSITION (typically negative). For WHENCE, you
  4684.             may use the constants `SEEK_SET', `SEEK_CUR', and
  4685.             `SEEK_END' from either the `IO::Seekable' or the POSIX
  4686.             module.
  4687.  
  4688.             Returns the new position, or the undefined value on
  4689.             failure. A position of zero is returned as the string
  4690.             "`0' but true"; thus `sysseek()' returns TRUE on success
  4691.             and FALSE on failure, yet you can still easily determine
  4692.             the new position.
  4693.  
  4694.     system LIST
  4695.  
  4696.     system PROGRAM LIST
  4697.             Does exactly the same thing as "`exec LIST'", except
  4698.             that a fork is done first, and the parent process waits
  4699.             for the child process to complete. Note that argument
  4700.             processing varies depending on the number of arguments.
  4701.             If there is more than one argument in LIST, or if LIST
  4702.             is an array with more than one value, starts the program
  4703.             given by the first element of the list with arguments
  4704.             given by the rest of the list. If there is only one
  4705.             scalar argument, the argument is checked for shell
  4706.             metacharacters, and if there are any, the entire
  4707.             argument is passed to the system's command shell for
  4708.             parsing (this is `/bin/sh -c' on Unix platforms, but
  4709.             varies on other platforms). If there are no shell
  4710.             metacharacters in the argument, it is split into words
  4711.             and passed directly to `execvp()', which is more
  4712.             efficient.
  4713.  
  4714.             The return value is the exit status of the program as
  4715.             returned by the `wait()' call. To get the actual exit
  4716.             value divide by 256. See also the "exec" entry in this
  4717.             manpage. This is *NOT* what you want to use to capture
  4718.             the output from a command, for that you should use
  4719.             merely backticks or `qx//', as described in the section
  4720.             on "`STRING`" in the perlop manpage.
  4721.  
  4722.             Like `exec()', `system()' allows you to lie to a program
  4723.             about its name if you use the "`system PROGRAM LIST'"
  4724.             syntax. Again, see the "exec" entry in this manpage.
  4725.  
  4726.             Because `system()' and backticks block `SIGINT' and
  4727.             `SIGQUIT', killing the program they're running doesn't
  4728.             actually interrupt your program.
  4729.  
  4730.                 @args = ("command", "arg1", "arg2");
  4731.                 system(@args) == 0
  4732.                  or die "system @args failed: $?"
  4733.  
  4734.  
  4735.             You can check all the failure possibilities by
  4736.             inspecting `$?' like this:
  4737.  
  4738.                 $exit_value  = $? >> 8;
  4739.                 $signal_num  = $? & 127;
  4740.                 $dumped_core = $? & 128;
  4741.  
  4742.  
  4743.             When the arguments get executed via the system shell,
  4744.             results and return codes will be subject to its quirks
  4745.             and capabilities. See the section on "`STRING`" in the
  4746.             perlop manpage and the "exec" entry in this manpage for
  4747.             details.
  4748.  
  4749.     syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
  4750.  
  4751.     syswrite FILEHANDLE,SCALAR,LENGTH
  4752.  
  4753.     syswrite FILEHANDLE,SCALAR
  4754.             Attempts to write LENGTH bytes of data from variable
  4755.             SCALAR to the specified FILEHANDLE, using the system
  4756.             call write(2). If LENGTH is not specified, writes whole
  4757.             SCALAR. It bypasses stdio, so mixing this with reads
  4758.             (other than `sysread())', `print()', `write()',
  4759.             `seek()', `tell()', or `eof()' may cause confusion
  4760.             because stdio usually buffers data. Returns the number
  4761.             of bytes actually written, or `undef' if there was an
  4762.             error. If the LENGTH is greater than the available data
  4763.             in the SCALAR after the OFFSET, only as much data as is
  4764.             available will be written.
  4765.  
  4766.             An OFFSET may be specified to write the data from some
  4767.             part of the string other than the beginning. A negative
  4768.             OFFSET specifies writing that many bytes counting
  4769.             backwards from the end of the string. In the case the
  4770.             SCALAR is empty you can use OFFSET but only zero offset.
  4771.  
  4772.     tell FILEHANDLE
  4773.  
  4774.     tell    Returns the current position for FILEHANDLE. FILEHANDLE may
  4775.             be an expression whose value gives the name of the
  4776.             actual filehandle. If FILEHANDLE is omitted, assumes the
  4777.             file last read.
  4778.  
  4779.             There is no `systell()' function. Use `sysseek(FH, 0,
  4780.             1)' for that.
  4781.  
  4782.     telldir DIRHANDLE
  4783.             Returns the current position of the `readdir()' routines
  4784.             on DIRHANDLE. Value may be given to `seekdir()' to
  4785.             access a particular location in a directory. Has the
  4786.             same caveats about possible directory compaction as the
  4787.             corresponding system library routine.
  4788.  
  4789.     tie VARIABLE,CLASSNAME,LIST
  4790.             This function binds a variable to a package class that
  4791.             will provide the implementation for the variable.
  4792.             VARIABLE is the name of the variable to be enchanted.
  4793.             CLASSNAME is the name of a class implementing objects of
  4794.             correct type. Any additional arguments are passed to the
  4795.             "`new()'" method of the class (meaning `TIESCALAR',
  4796.             `TIEHANDLE', `TIEARRAY', or `TIEHASH'). Typically these
  4797.             are arguments such as might be passed to the
  4798.             `dbm_open()' function of C. The object returned by the
  4799.             "`new()'" method is also returned by the `tie()'
  4800.             function, which would be useful if you want to access
  4801.             other methods in CLASSNAME.
  4802.  
  4803.             Note that functions such as `keys()' and `values()' may
  4804.             return huge lists when used on large objects, like DBM
  4805.             files. You may prefer to use the `each()' function to
  4806.             iterate over such. Example:
  4807.  
  4808.                 # print out history file offsets
  4809.                 use NDBM_File;
  4810.                 tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
  4811.                 while (($key,$val) = each %HIST) {
  4812.                 print $key, ' = ', unpack('L',$val), "\n";
  4813.                 }
  4814.                 untie(%HIST);
  4815.  
  4816.  
  4817.             A class implementing a hash should have the following
  4818.             methods:
  4819.  
  4820.                 TIEHASH classname, LIST
  4821.                 FETCH this, key
  4822.                 STORE this, key, value
  4823.                 DELETE this, key
  4824.                 CLEAR this
  4825.                 EXISTS this, key
  4826.                 FIRSTKEY this
  4827.                 NEXTKEY this, lastkey
  4828.                 DESTROY this
  4829.  
  4830.  
  4831.             A class implementing an ordinary array should have the
  4832.             following methods:
  4833.  
  4834.                 TIEARRAY classname, LIST
  4835.                 FETCH this, key
  4836.                 STORE this, key, value
  4837.                 FETCHSIZE this
  4838.                 STORESIZE this, count
  4839.                 CLEAR this
  4840.                 PUSH this, LIST
  4841.                 POP this
  4842.                 SHIFT this
  4843.                 UNSHIFT this, LIST
  4844.                 SPLICE this, offset, length, LIST
  4845.                 EXTEND this, count
  4846.                 DESTROY this
  4847.  
  4848.  
  4849.             A class implementing a file handle should have the
  4850.             following methods:
  4851.  
  4852.                 TIEHANDLE classname, LIST
  4853.                 READ this, scalar, length, offset
  4854.                 READLINE this
  4855.                 GETC this
  4856.                 WRITE this, scalar, length, offset
  4857.                 PRINT this, LIST
  4858.                 PRINTF this, format, LIST
  4859.                 CLOSE this
  4860.                 DESTROY this
  4861.  
  4862.  
  4863.             A class implementing a scalar should have the following
  4864.             methods:
  4865.  
  4866.                 TIESCALAR classname, LIST
  4867.                 FETCH this,
  4868.                 STORE this, value
  4869.                 DESTROY this
  4870.  
  4871.  
  4872.             Not all methods indicated above need be implemented. See
  4873.             the perltie manpage, the Tie::Hash manpage, the
  4874.             Tie::Array manpage, the Tie::Scalar manpage, and the
  4875.             Tie::Handle manpage.
  4876.  
  4877.             Unlike `dbmopen()', the `tie()' function will not use or
  4878.             require a module for you--you need to do that explicitly
  4879.             yourself. See the DB_File manpage or the Config module
  4880.             for interesting `tie()' implementations.
  4881.  
  4882.             For further details see the perltie manpage, the section
  4883.             on "tied VARIABLE".
  4884.  
  4885.     tied VARIABLE
  4886.             Returns a reference to the object underlying VARIABLE
  4887.             (the same value that was originally returned by the
  4888.             `tie()' call that bound the variable to a package.)
  4889.             Returns the undefined value if VARIABLE isn't tied to a
  4890.             package.
  4891.  
  4892.     time    Returns the number of non-leap seconds since whatever time
  4893.             the system considers to be the epoch (that's 00:00:00,
  4894.             January 1, 1904 for MacOS, and 00:00:00 UTC, January 1,
  4895.             1970 for most other systems). Suitable for feeding to
  4896.             `gmtime()' and `localtime()'.
  4897.  
  4898.     times   Returns a four-element list giving the user and system
  4899.             times, in seconds, for this process and the children of
  4900.             this process.
  4901.  
  4902.                 ($user,$system,$cuser,$csystem) = times;
  4903.  
  4904.  
  4905.     tr///   The transliteration operator. Same as `y///'. See the perlop
  4906.             manpage.
  4907.  
  4908.     truncate FILEHANDLE,LENGTH
  4909.  
  4910.     truncate EXPR,LENGTH
  4911.             Truncates the file opened on FILEHANDLE, or named by
  4912.             EXPR, to the specified length. Produces a fatal error if
  4913.             truncate isn't implemented on your system. Returns TRUE
  4914.             if successful, the undefined value otherwise.
  4915.  
  4916.     uc EXPR
  4917.  
  4918.     uc      Returns an uppercased version of EXPR. This is the internal
  4919.             function implementing the `\U' escape in double-quoted
  4920.             strings. Respects current LC_CTYPE locale if `use
  4921.             locale' in force. See the perllocale manpage. (It does
  4922.             not attempt to do titlecase mapping on initial letters.
  4923.             See `ucfirst()' for that.)
  4924.  
  4925.             If EXPR is omitted, uses `$_'.
  4926.  
  4927.     ucfirst EXPR
  4928.  
  4929.     ucfirst Returns the value of EXPR with the first character in
  4930.             uppercase. This is the internal function implementing
  4931.             the `\u' escape in double-quoted strings. Respects
  4932.             current LC_CTYPE locale if `use locale' in force. See
  4933.             the perllocale manpage.
  4934.  
  4935.             If EXPR is omitted, uses `$_'.
  4936.  
  4937.     umask EXPR
  4938.  
  4939.     umask   Sets the umask for the process to EXPR and returns the
  4940.             previous value. If EXPR is omitted, merely returns the
  4941.             current umask.
  4942.  
  4943.             The Unix permission `rwxr-x---' is represented as three
  4944.             sets of three bits, or three octal digits: `0750' (the
  4945.             leading 0 indicates octal and isn't one of the digits).
  4946.             The `umask' value is such a number representing disabled
  4947.             permissions bits. The permission (or "mode") values you
  4948.             pass `mkdir' or `sysopen' are modified by your umask, so
  4949.             even if you tell `sysopen' to create a file with
  4950.             permissions `0777', if your umask is `0022' then the
  4951.             file will actually be created with permissions `0755'.
  4952.             If your `umask' were `0027' (group can't write; others
  4953.             can't read, write, or execute), then passing `sysopen()'
  4954.             `0666' would create a file with mode `0640' (`0666 &~
  4955.             027' is `0640').
  4956.  
  4957.             Here's some advice: supply a creation mode of `0666' for
  4958.             regular files (in `sysopen()') and one of `0777' for
  4959.             directories (in `mkdir()') and executable files. This
  4960.             gives users the freedom of choice: if they want
  4961.             protected files, they might choose process umasks of
  4962.             `022', `027', or even the particularly antisocial mask
  4963.             of `077'. Programs should rarely if ever make policy
  4964.             decisions better left to the user. The exception to this
  4965.             is when writing files that should be kept private: mail
  4966.             files, web browser cookies, *.rhosts* files, and so on.
  4967.  
  4968.             If umask(2) is not implemented on your system and you
  4969.             are trying to restrict access for *yourself* (i.e.,
  4970.             (EXPR & 0700) > 0), produces a fatal error at run time.
  4971.             If umask(2) is not implemented and you are not trying to
  4972.             restrict access for yourself, returns `undef'.
  4973.  
  4974.             Remember that a umask is a number, usually given in
  4975.             octal; it is *not* a string of octal digits. See also
  4976.             the "oct" entry in this manpage, if all you have is a
  4977.             string.
  4978.  
  4979.     undef EXPR
  4980.  
  4981.     undef   Undefines the value of EXPR, which must be an lvalue. Use
  4982.             only on a scalar value, an array (using "`@'"), a hash
  4983.             (using "`%'"), a subroutine (using "`&'"), or a typeglob
  4984.             (using "<*>"). (Saying `undef $hash{$key}' will probably
  4985.             not do what you expect on most predefined variables or
  4986.             DBM list values, so don't do that; see the delete
  4987.             manpage.) Always returns the undefined value. You can
  4988.             omit the EXPR, in which case nothing is undefined, but
  4989.             you still get an undefined value that you could, for
  4990.             instance, return from a subroutine, assign to a variable
  4991.             or pass as a parameter. Examples:
  4992.  
  4993.                 undef $foo;
  4994.                 undef $bar{'blurfl'};      # Compare to: delete $bar{'blurfl'};
  4995.                 undef @ary;
  4996.                 undef %hash;
  4997.                 undef &mysub;
  4998.                 undef *xyz;       # destroys $xyz, @xyz, %xyz, &xyz, etc.
  4999.                 return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
  5000.                 select undef, undef, undef, 0.25;
  5001.                 ($a, $b, undef, $c) = &foo;       # Ignore third value returned
  5002.  
  5003.  
  5004.             Note that this is a unary operator, not a list operator.
  5005.  
  5006.     unlink LIST
  5007.  
  5008.     unlink  Deletes a list of files. Returns the number of files
  5009.             successfully deleted.
  5010.  
  5011.                 $cnt = unlink 'a', 'b', 'c';
  5012.                 unlink @goners;
  5013.                 unlink <*.bak>;
  5014.  
  5015.  
  5016.             Note: `unlink()' will not delete directories unless you
  5017.             are superuser and the -U flag is supplied to Perl. Even
  5018.             if these conditions are met, be warned that unlinking a
  5019.             directory can inflict damage on your filesystem. Use
  5020.             `rmdir()' instead.
  5021.  
  5022.             If LIST is omitted, uses `$_'.
  5023.  
  5024.     unpack TEMPLATE,EXPR
  5025.             `Unpack()' does the reverse of `pack()': it takes a
  5026.             string representing a structure and expands it out into
  5027.             a list value, returning the array value. (In scalar
  5028.             context, it returns merely the first value produced.)
  5029.             The TEMPLATE has the same format as in the `pack()'
  5030.             function. Here's a subroutine that does substring:
  5031.  
  5032.                 sub substr {
  5033.                 my($what,$where,$howmuch) = @_;
  5034.                 unpack("x$where a$howmuch", $what);
  5035.                 }
  5036.  
  5037.  
  5038.             and then there's
  5039.  
  5040.                 sub ordinal { unpack("c",$_[0]); } # same as ord()
  5041.  
  5042.  
  5043.             In addition, you may prefix a field with a %<number> to
  5044.             indicate that you want a <number>-bit checksum of the
  5045.             items instead of the items themselves. Default is a 16-
  5046.             bit checksum. For example, the following computes the
  5047.             same number as the System V sum program:
  5048.  
  5049.                 while (<>) {
  5050.                 $checksum += unpack("%32C*", $_);
  5051.                 }
  5052.                 $checksum %= 65535;
  5053.  
  5054.  
  5055.             The following efficiently counts the number of set bits
  5056.             in a bit vector:
  5057.  
  5058.                 $setbits = unpack("%32b*", $selectmask);
  5059.  
  5060.  
  5061.             See the "pack" entry in this manpage for more examples.
  5062.  
  5063.     untie VARIABLE
  5064.             Breaks the binding between a variable and a package.
  5065.             (See `tie()'.)
  5066.  
  5067.     unshift ARRAY,LIST
  5068.             Does the opposite of a `shift()'. Or the opposite of a
  5069.             `push()', depending on how you look at it. Prepends list
  5070.             to the front of the array, and returns the new number of
  5071.             elements in the array.
  5072.  
  5073.                 unshift(ARGV, '-e') unless $ARGV[0] =~ /^-/;
  5074.  
  5075.  
  5076.             Note the LIST is prepended whole, not one element at a
  5077.             time, so the prepended elements stay in the same order.
  5078.             Use `reverse()' to do the reverse.
  5079.  
  5080.     use Module LIST
  5081.  
  5082.     use Module
  5083.  
  5084.     use Module VERSION LIST
  5085.  
  5086.     use VERSION
  5087.             Imports some semantics into the current package from the
  5088.             named module, generally by aliasing certain subroutine
  5089.             or variable names into your package. It is exactly
  5090.             equivalent to
  5091.  
  5092.                 BEGIN { require Module; import Module LIST; }
  5093.  
  5094.  
  5095.             except that Module *must* be a bareword.
  5096.  
  5097.             If the first argument to `use' is a number, it is
  5098.             treated as a version number instead of a module name. If
  5099.             the version of the Perl interpreter is less than
  5100.             VERSION, then an error message is printed and Perl exits
  5101.             immediately. This is often useful if you need to check
  5102.             the current Perl version before `use'ing library modules
  5103.             that have changed in incompatible ways from older
  5104.             versions of Perl. (We try not to do this more than we
  5105.             have to.)
  5106.  
  5107.             The `BEGIN' forces the `require' and `import()' to
  5108.             happen at compile time. The `require' makes sure the
  5109.             module is loaded into memory if it hasn't been yet. The
  5110.             `import()' is not a builtin--it's just an ordinary
  5111.             static method call into the "`Module'" package to tell
  5112.             the module to import the list of features back into the
  5113.             current package. The module can implement its `import()'
  5114.             method any way it likes, though most modules just choose
  5115.             to derive their `import()' method via inheritance from
  5116.             the `Exporter' class that is defined in the `Exporter'
  5117.             module. See the Exporter manpage. If no `import()'
  5118.             method can be found then the error is currently silently
  5119.             ignored. This may change to a fatal error in a future
  5120.             version.
  5121.  
  5122.             If you don't want your namespace altered, explicitly
  5123.             supply an empty list:
  5124.  
  5125.                 use Module ();
  5126.  
  5127.  
  5128.             That is exactly equivalent to
  5129.  
  5130.                 BEGIN { require Module }
  5131.  
  5132.  
  5133.             If the VERSION argument is present between Module and
  5134.             LIST, then the `use' will call the VERSION method in
  5135.             class Module with the given version as an argument. The
  5136.             default VERSION method, inherited from the Universal
  5137.             class, croaks if the given version is larger than the
  5138.             value of the variable `$Module::VERSION'. (Note that
  5139.             there is not a comma after VERSION!)
  5140.  
  5141.             Because this is a wide-open interface, pragmas (compiler
  5142.             directives) are also implemented this way. Currently
  5143.             implemented pragmas are:
  5144.  
  5145.                 use integer;
  5146.                 use diagnostics;
  5147.                 use sigtrap qw(SEGV BUS);
  5148.                 use strict  qw(subs vars refs);
  5149.                 use subs    qw(afunc blurfl);
  5150.  
  5151.  
  5152.             Some of these these pseudo-modules import semantics into
  5153.             the current block scope (like `strict' or `integer',
  5154.             unlike ordinary modules, which import symbols into the
  5155.             current package (which are effective through the end of
  5156.             the file).
  5157.  
  5158.             There's a corresponding "`no'" command that unimports
  5159.             meanings imported by `use', i.e., it calls `unimport
  5160.             Module LIST' instead of `import()'.
  5161.  
  5162.                 no integer;
  5163.                 no strict 'refs';
  5164.  
  5165.  
  5166.             If no `unimport()' method can be found the call fails
  5167.             with a fatal error.
  5168.  
  5169.             See the perlmod manpage for a list of standard modules
  5170.             and pragmas.
  5171.  
  5172.     utime LIST
  5173.             Changes the access and modification times on each file
  5174.             of a list of files. The first two elements of the list
  5175.             must be the NUMERICAL access and modification times, in
  5176.             that order. Returns the number of files successfully
  5177.             changed. The inode modification time of each file is set
  5178.             to the current time. This code has the same effect as
  5179.             the "`touch'" command if the files already exist:
  5180.  
  5181.                 #!/usr/bin/perl
  5182.                 $now = time;
  5183.                 utime $now, $now, @ARGV;
  5184.  
  5185.  
  5186.     values HASH
  5187.             Returns a list consisting of all the values of the named
  5188.             hash. (In a scalar context, returns the number of
  5189.             values.) The values are returned in an apparently random
  5190.             order. The actual random order is subject to change in
  5191.             future versions of perl, but it is guaranteed to be the
  5192.             same order as either the `keys()' or `each()' function
  5193.             would produce on the same (unmodified) hash.
  5194.  
  5195.             Note that you cannot modify the values of a hash this
  5196.             way, because the returned list is just a copy. You need
  5197.             to use a hash slice for that, since it's lvaluable in a
  5198.             way that values() is not.
  5199.  
  5200.                 for (values %hash)         { s/foo/bar/g }   # FAILS!
  5201.                 for (@hash{keys %hash}) { s/foo/bar/g }   # ok
  5202.  
  5203.  
  5204.             As a side effect, calling values() resets the HASH's
  5205.             internal iterator. See also `keys()', `each()', and
  5206.             `sort()'.
  5207.  
  5208.     vec EXPR,OFFSET,BITS
  5209.             Treats the string in EXPR as a vector of unsigned
  5210.             integers, and returns the value of the bit field
  5211.             specified by OFFSET. BITS specifies the number of bits
  5212.             that are reserved for each entry in the bit vector. This
  5213.             must be a power of two from 1 to 32. `vec()' may also be
  5214.             assigned to, in which case parentheses are needed to
  5215.             give the expression the correct precedence as in
  5216.  
  5217.                 vec($image, $max_x * $x + $y, 8) = 3;
  5218.  
  5219.  
  5220.             Vectors created with `vec()' can also be manipulated
  5221.             with the logical operators `|', `&', and `^', which will
  5222.             assume a bit vector operation is desired when both
  5223.             operands are strings. See the section on "Bitwise String
  5224.             Operators" in the perlop manpage.
  5225.  
  5226.             The following code will build up an ASCII string saying
  5227.             `'PerlPerlPerl''. The comments show the string after
  5228.             each step. Note that this code works in the same way on
  5229.             big-endian or little-endian machines.
  5230.  
  5231.                 my $foo = '';
  5232.                 vec($foo,  0, 32) = 0x5065726C;    # 'Perl'
  5233.                 vec($foo,  2, 16) = 0x5065;        # 'PerlPe'
  5234.                 vec($foo,  3, 16) = 0x726C;        # 'PerlPerl'
  5235.                 vec($foo,  8,  8) = 0x50;        # 'PerlPerlP'
  5236.                 vec($foo,  9,  8) = 0x65;        # 'PerlPerlPe'
  5237.                 vec($foo, 20,  4) = 2;        # 'PerlPerlPe'   . "\x02"
  5238.                 vec($foo, 21,  4) = 7;        # 'PerlPerlPer'
  5239.                                                     # 'r' is "\x72"
  5240.                 vec($foo, 45,  2) = 3;        # 'PerlPerlPer'  . "\x0c"
  5241.                 vec($foo, 93,  1) = 1;        # 'PerlPerlPer'  . "\x2c"
  5242.                 vec($foo, 94,  1) = 1;        # 'PerlPerlPerl'
  5243.                                                     # 'l' is "\x6c"
  5244.  
  5245.  
  5246.             To transform a bit vector into a string or array of 0's
  5247.             and 1's, use these:
  5248.  
  5249.                 $bits = unpack("b*", $vector);
  5250.                 @bits = split(//, unpack("b*", $vector));
  5251.  
  5252.  
  5253.             If you know the exact length in bits, it can be used in
  5254.             place of the `*'.
  5255.  
  5256.     wait    Behaves like the wait(2) system call on your system: it
  5257.             waits for a child process to terminate and returns the
  5258.             pid of the deceased process, or `-1' if there are no
  5259.             child processes. The status is rketurned in `$?'. Note
  5260.             that a return value of `-1' could mean that child
  5261.             processes are being automatically reaped, as described
  5262.             in the perlipc manpage.
  5263.  
  5264.     waitpid PID,FLAGS
  5265.             Waits for a particular child process to terminate and
  5266.             returns the pid of the deceased process, or `-1' if
  5267.             there is no such child process. On some systems, a value
  5268.             of 0 indicates that there are processes still running.
  5269.             The status is returned in `$?'. If you say
  5270.  
  5271.                 use POSIX ":sys_wait_h";
  5272.                 #...
  5273.                 do { 
  5274.                 $kid = waitpid(-1,&WNOHANG);
  5275.                 } until $kid == -1;
  5276.  
  5277.  
  5278.             then you can do a non-blocking wait for all pending
  5279.             zombie processes. Non-blocking wait is available on
  5280.             machines supporting either the waitpid(2) or wait4(2)
  5281.             system calls. However, waiting for a particular pid with
  5282.             FLAGS of `0' is implemented everywhere. (Perl emulates
  5283.             the system call by remembering the status values of
  5284.             processes that have exited but have not been harvested
  5285.             by the Perl script yet.)
  5286.  
  5287.             Note that on some systems, a return value of `-1' could
  5288.             mean that child processes are being automatically
  5289.             reaped. See the perlipc manpage for details, and for
  5290.             other examples.
  5291.  
  5292.     wantarray
  5293.             Returns TRUE if the context of the currently executing
  5294.             subroutine is looking for a list value. Returns FALSE if
  5295.             the context is looking for a scalar. Returns the
  5296.             undefined value if the context is looking for no value
  5297.             (void context).
  5298.  
  5299.                 return unless defined wantarray;    # don't bother doing more
  5300.                 my @a = complex_calculation();
  5301.                 return wantarray ? @a : "@a";
  5302.  
  5303.  
  5304.     warn LIST
  5305.             Produces a message on STDERR just like `die()', but
  5306.             doesn't exit or throw an exception.
  5307.  
  5308.             If LIST is empty and `$@' already contains a value
  5309.             (typically from a previous eval) that value is used
  5310.             after appending `"\t...caught"' to `$@'. This is useful
  5311.             for staying almost, but not entirely similar to `die()'.
  5312.  
  5313.             If `$@' is empty then the string `"Warning: Something's
  5314.             wrong"' is used.
  5315.  
  5316.             No message is printed if there is a `$SIG{__WARN__}'
  5317.             handler installed. It is the handler's responsibility to
  5318.             deal with the message as it sees fit (like, for
  5319.             instance, converting it into a `die()'). Most handlers
  5320.             must therefore make arrangements to actually display the
  5321.             warnings that they are not prepared to deal with, by
  5322.             calling `warn()' again in the handler. Note that this is
  5323.             quite safe and will not produce an endless loop, since
  5324.             `__WARN__' hooks are not called from inside one.
  5325.  
  5326.             You will find this behavior is slightly different from
  5327.             that of `$SIG{__DIE__}' handlers (which don't suppress
  5328.             the error text, but can instead call `die()' again to
  5329.             change it).
  5330.  
  5331.             Using a `__WARN__' handler provides a powerful way to
  5332.             silence all warnings (even the so-called mandatory
  5333.             ones). An example:
  5334.  
  5335.                 # wipe out *all* compile-time warnings
  5336.                 BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } }
  5337.                 my $foo = 10;
  5338.                 my $foo = 20;          # no warning about duplicate my $foo,
  5339.                                        # but hey, you asked for it!
  5340.                 # no compile-time or run-time warnings before here
  5341.                 $DOWARN = 1;
  5342.  
  5343.                 # run-time warnings enabled after here
  5344.                 warn "\$foo is alive and $foo!";     # does show up
  5345.  
  5346.  
  5347.             See the perlvar manpage for details on setting `%SIG'
  5348.             entries, and for more examples. See the Carp module for
  5349.             other kinds of warnings using its carp() and cluck()
  5350.             functions.
  5351.  
  5352.     write FILEHANDLE
  5353.  
  5354.     write EXPR
  5355.  
  5356.     write   Writes a formatted record (possibly multi-line) to the
  5357.             specified FILEHANDLE, using the format associated with
  5358.             that file. By default the format for a file is the one
  5359.             having the same name as the filehandle, but the format
  5360.             for the current output channel (see the `select()'
  5361.             function) may be set explicitly by assigning the name of
  5362.             the format to the `$~' variable.
  5363.  
  5364.             Top of form processing is handled automatically: if
  5365.             there is insufficient room on the current page for the
  5366.             formatted record, the page is advanced by writing a form
  5367.             feed, a special top-of-page format is used to format the
  5368.             new page header, and then the record is written. By
  5369.             default the top-of-page format is the name of the
  5370.             filehandle with "_TOP" appended, but it may be
  5371.             dynamically set to the format of your choice by
  5372.             assigning the name to the `$^' variable while the
  5373.             filehandle is selected. The number of lines remaining on
  5374.             the current page is in variable `$-', which can be set
  5375.             to `0' to force a new page.
  5376.  
  5377.             If FILEHANDLE is unspecified, output goes to the current
  5378.             default output channel, which starts out as STDOUT but
  5379.             may be changed by the `select()' operator. If the
  5380.             FILEHANDLE is an EXPR, then the expression is evaluated
  5381.             and the resulting string is used to look up the name of
  5382.             the FILEHANDLE at run time. For more on formats, see the
  5383.             perlform manpage.
  5384.  
  5385.             Note that write is *NOT* the opposite of `read()'.
  5386.             Unfortunately.
  5387.  
  5388.     y///    The transliteration operator. Same as `tr///'. See the
  5389.             perlop manpage.
  5390.  
  5391.