[ Index ]

PHP Cross Reference of Unnamed Project

title

Body

[close]

/se3-unattended/var/se3/unattended/install/linuxaux/opt/perl/lib/5.10.0/pod/ -> perlfunc.pod (source)

   1  =head1 NAME
   2  X<function>
   3  
   4  perlfunc - Perl builtin functions
   5  
   6  =head1 DESCRIPTION
   7  
   8  The functions in this section can serve as terms in an expression.
   9  They fall into two major categories: list operators and named unary
  10  operators.  These differ in their precedence relationship with a
  11  following comma.  (See the precedence table in L<perlop>.)  List
  12  operators take more than one argument, while unary operators can never
  13  take more than one argument.  Thus, a comma terminates the argument of
  14  a unary operator, but merely separates the arguments of a list
  15  operator.  A unary operator generally provides a scalar context to its
  16  argument, while a list operator may provide either scalar or list
  17  contexts for its arguments.  If it does both, the scalar arguments will
  18  be first, and the list argument will follow.  (Note that there can ever
  19  be only one such list argument.)  For instance, splice() has three scalar
  20  arguments followed by a list, whereas gethostbyname() has four scalar
  21  arguments.
  22  
  23  In the syntax descriptions that follow, list operators that expect a
  24  list (and provide list context for the elements of the list) are shown
  25  with LIST as an argument.  Such a list may consist of any combination
  26  of scalar arguments or list values; the list values will be included
  27  in the list as if each individual element were interpolated at that
  28  point in the list, forming a longer single-dimensional list value.
  29  Commas should separate elements of the LIST.
  30  
  31  Any function in the list below may be used either with or without
  32  parentheses around its arguments.  (The syntax descriptions omit the
  33  parentheses.)  If you use the parentheses, the simple (but occasionally
  34  surprising) rule is this: It I<looks> like a function, therefore it I<is> a
  35  function, and precedence doesn't matter.  Otherwise it's a list
  36  operator or unary operator, and precedence does matter.  And whitespace
  37  between the function and left parenthesis doesn't count--so you need to
  38  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  If you run Perl with the B<-w> switch it can warn you about this.  For
  47  example, the third line above produces:
  48  
  49      print (...) interpreted as function at - line 1.
  50      Useless use of integer addition in void context at - line 1.
  51  
  52  A few functions take no arguments at all, and therefore work as neither
  53  unary nor list operators.  These include such functions as C<time>
  54  and C<endpwent>.  For example, C<time+86_400> always means
  55  C<time() + 86_400>.
  56  
  57  For functions that can be used in either a scalar or list context,
  58  nonabortive failure is generally indicated in a scalar context by
  59  returning the undefined value, and in a list context by returning the
  60  null list.
  61  
  62  Remember the following important rule: There is B<no rule> that relates
  63  the behavior of an expression in list context to its behavior in scalar
  64  context, or vice versa.  It might do two totally different things.
  65  Each operator and function decides which sort of value it would be most
  66  appropriate to return in scalar context.  Some operators return the
  67  length of the list that would have been returned in list context.  Some
  68  operators return the first value in the list.  Some operators return the
  69  last value in the list.  Some operators return a count of successful
  70  operations.  In general, they do what you want, unless you want
  71  consistency.
  72  X<context>
  73  
  74  A named array in scalar context is quite different from what would at
  75  first glance appear to be a list in scalar context.  You can't get a list
  76  like C<(1,2,3)> into being in scalar context, because the compiler knows
  77  the context at compile time.  It would generate the scalar comma operator
  78  there, not the list construction version of the comma.  That means it
  79  was never a list to start with.
  80  
  81  In general, functions in Perl that serve as wrappers for system calls
  82  of the same name (like chown(2), fork(2), closedir(2), etc.) all return
  83  true when they succeed and C<undef> otherwise, as is usually mentioned
  84  in the descriptions below.  This is different from the C interfaces,
  85  which return C<-1> on failure.  Exceptions to this rule are C<wait>,
  86  C<waitpid>, and C<syscall>.  System calls also set the special C<$!>
  87  variable on failure.  Other functions do not, except accidentally.
  88  
  89  =head2 Perl Functions by Category
  90  X<function>
  91  
  92  Here are Perl's functions (including things that look like
  93  functions, like some keywords and named operators)
  94  arranged by category.  Some functions appear in more
  95  than one place.
  96  
  97  =over 4
  98  
  99  =item Functions for SCALARs or strings
 100  X<scalar> X<string> X<character>
 101  
 102  C<chomp>, C<chop>, C<chr>, C<crypt>, C<hex>, C<index>, C<lc>, C<lcfirst>,
 103  C<length>, C<oct>, C<ord>, C<pack>, C<q//>, C<qq//>, C<reverse>,
 104  C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y///>
 105  
 106  =item Regular expressions and pattern matching
 107  X<regular expression> X<regex> X<regexp>
 108  
 109  C<m//>, C<pos>, C<quotemeta>, C<s///>, C<split>, C<study>, C<qr//>
 110  
 111  =item Numeric functions
 112  X<numeric> X<number> X<trigonometric> X<trigonometry>
 113  
 114  C<abs>, C<atan2>, C<cos>, C<exp>, C<hex>, C<int>, C<log>, C<oct>, C<rand>,
 115  C<sin>, C<sqrt>, C<srand>
 116  
 117  =item Functions for real @ARRAYs
 118  X<array>
 119  
 120  C<pop>, C<push>, C<shift>, C<splice>, C<unshift>
 121  
 122  =item Functions for list data
 123  X<list>
 124  
 125  C<grep>, C<join>, C<map>, C<qw//>, C<reverse>, C<sort>, C<unpack>
 126  
 127  =item Functions for real %HASHes
 128  X<hash>
 129  
 130  C<delete>, C<each>, C<exists>, C<keys>, C<values>
 131  
 132  =item Input and output functions
 133  X<I/O> X<input> X<output> X<dbm>
 134  
 135  C<binmode>, C<close>, C<closedir>, C<dbmclose>, C<dbmopen>, C<die>, C<eof>,
 136  C<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>,
 137  C<readdir>, C<rewinddir>, C<say>, C<seek>, C<seekdir>, C<select>, C<syscall>,
 138  C<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>, C<truncate>,
 139  C<warn>, C<write>
 140  
 141  =item Functions for fixed length data or records
 142  
 143  C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec>
 144  
 145  =item Functions for filehandles, files, or directories
 146  X<file> X<filehandle> X<directory> X<pipe> X<link> X<symlink>
 147  
 148  C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
 149  C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
 150  C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<sysopen>,
 151  C<umask>, C<unlink>, C<utime>
 152  
 153  =item Keywords related to the control flow of your Perl program
 154  X<control flow>
 155  
 156  C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>,
 157  C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>
 158  
 159  =item Keywords related to switch
 160  
 161  C<break>, C<continue>, C<given>, C<when>, C<default>
 162  
 163  (These are only available if you enable the "switch" feature.
 164  See L<feature> and L<perlsyn/"Switch statements">.)
 165  
 166  =item Keywords related to scoping
 167  
 168  C<caller>, C<import>, C<local>, C<my>, C<our>, C<state>, C<package>,
 169  C<use>
 170  
 171  (C<state> is only available if the "state" feature is enabled. See
 172  L<feature>.)
 173  
 174  =item Miscellaneous functions
 175  
 176  C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>,
 177  C<reset>, C<scalar>, C<state>, C<undef>, C<wantarray>
 178  
 179  =item Functions for processes and process groups
 180  X<process> X<pid> X<process id>
 181  
 182  C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>,
 183  C<pipe>, C<qx//>, C<setpgrp>, C<setpriority>, C<sleep>, C<system>,
 184  C<times>, C<wait>, C<waitpid>
 185  
 186  =item Keywords related to perl modules
 187  X<module>
 188  
 189  C<do>, C<import>, C<no>, C<package>, C<require>, C<use>
 190  
 191  =item Keywords related to classes and object-orientation
 192  X<object> X<class> X<package>
 193  
 194  C<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>,
 195  C<untie>, C<use>
 196  
 197  =item Low-level socket functions
 198  X<socket> X<sock>
 199  
 200  C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
 201  C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
 202  C<socket>, C<socketpair>
 203  
 204  =item System V interprocess communication functions
 205  X<IPC> X<System V> X<semaphore> X<shared memory> X<memory> X<message>
 206  
 207  C<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<semctl>, C<semget>, C<semop>,
 208  C<shmctl>, C<shmget>, C<shmread>, C<shmwrite>
 209  
 210  =item Fetching user and group info
 211  X<user> X<group> X<password> X<uid> X<gid>  X<passwd> X</etc/passwd>
 212  
 213  C<endgrent>, C<endhostent>, C<endnetent>, C<endpwent>, C<getgrent>,
 214  C<getgrgid>, C<getgrnam>, C<getlogin>, C<getpwent>, C<getpwnam>,
 215  C<getpwuid>, C<setgrent>, C<setpwent>
 216  
 217  =item Fetching network info
 218  X<network> X<protocol> X<host> X<hostname> X<IP> X<address> X<service>
 219  
 220  C<endprotoent>, C<endservent>, C<gethostbyaddr>, C<gethostbyname>,
 221  C<gethostent>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
 222  C<getprotobyname>, C<getprotobynumber>, C<getprotoent>,
 223  C<getservbyname>, C<getservbyport>, C<getservent>, C<sethostent>,
 224  C<setnetent>, C<setprotoent>, C<setservent>
 225  
 226  =item Time-related functions
 227  X<time> X<date>
 228  
 229  C<gmtime>, C<localtime>, C<time>, C<times>
 230  
 231  =item Functions new in perl5
 232  X<perl5>
 233  
 234  C<abs>, C<bless>, C<break>, C<chomp>, C<chr>, C<continue>, C<default>, 
 235  C<exists>, C<formline>, C<given>, C<glob>, C<import>, C<lc>, C<lcfirst>,
 236  C<lock>, C<map>, C<my>, C<no>, C<our>, C<prototype>, C<qr//>, C<qw//>, C<qx//>,
 237  C<readline>, C<readpipe>, C<ref>, C<sub>*, C<sysopen>, C<tie>, C<tied>, C<uc>,
 238  C<ucfirst>, C<untie>, C<use>, C<when>
 239  
 240  * - C<sub> was a keyword in perl4, but in perl5 it is an
 241  operator, which can be used in expressions.
 242  
 243  =item Functions obsoleted in perl5
 244  
 245  C<dbmclose>, C<dbmopen>
 246  
 247  =back
 248  
 249  =head2 Portability
 250  X<portability> X<Unix> X<portable>
 251  
 252  Perl was born in Unix and can therefore access all common Unix
 253  system calls.  In non-Unix environments, the functionality of some
 254  Unix system calls may not be available, or details of the available
 255  functionality may differ slightly.  The Perl functions affected
 256  by this are:
 257  
 258  C<-X>, C<binmode>, C<chmod>, C<chown>, C<chroot>, C<crypt>,
 259  C<dbmclose>, C<dbmopen>, C<dump>, C<endgrent>, C<endhostent>,
 260  C<endnetent>, C<endprotoent>, C<endpwent>, C<endservent>, C<exec>,
 261  C<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostbyname>,
 262  C<gethostent>, C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
 263  C<getppid>, C<getpgrp>, C<getpriority>, C<getprotobynumber>,
 264  C<getprotoent>, C<getpwent>, C<getpwnam>, C<getpwuid>,
 265  C<getservbyport>, C<getservent>, C<getsockopt>, C<glob>, C<ioctl>,
 266  C<kill>, C<link>, C<lstat>, C<msgctl>, C<msgget>, C<msgrcv>,
 267  C<msgsnd>, C<open>, C<pipe>, C<readlink>, C<rename>, C<select>, C<semctl>,
 268  C<semget>, C<semop>, C<setgrent>, C<sethostent>, C<setnetent>,
 269  C<setpgrp>, C<setpriority>, C<setprotoent>, C<setpwent>,
 270  C<setservent>, C<setsockopt>, C<shmctl>, C<shmget>, C<shmread>,
 271  C<shmwrite>, C<socket>, C<socketpair>,
 272  C<stat>, C<symlink>, C<syscall>, C<sysopen>, C<system>,
 273  C<times>, C<truncate>, C<umask>, C<unlink>,
 274  C<utime>, C<wait>, C<waitpid>
 275  
 276  For more information about the portability of these functions, see
 277  L<perlport> and other available platform-specific documentation.
 278  
 279  =head2 Alphabetical Listing of Perl Functions
 280  
 281  =over 8
 282  
 283  =item -X FILEHANDLE
 284  X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p>
 285  X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
 286  
 287  =item -X EXPR
 288  
 289  =item -X DIRHANDLE
 290  
 291  =item -X
 292  
 293  A file test, where X is one of the letters listed below.  This unary
 294  operator takes one argument, either a filename, a filehandle, or a dirhandle, 
 295  and tests the associated file to see if something is true about it.  If the
 296  argument is omitted, tests C<$_>, except for C<-t>, which tests STDIN.
 297  Unless otherwise documented, it returns C<1> for true and C<''> for false, or
 298  the undefined value if the file doesn't exist.  Despite the funny
 299  names, precedence is the same as any other named unary operator.  The
 300  operator may be any of:
 301  
 302      -r    File is readable by effective uid/gid.
 303      -w    File is writable by effective uid/gid.
 304      -x    File is executable by effective uid/gid.
 305      -o    File is owned by effective uid.
 306  
 307      -R    File is readable by real uid/gid.
 308      -W    File is writable by real uid/gid.
 309      -X    File is executable by real uid/gid.
 310      -O    File is owned by real uid.
 311  
 312      -e    File exists.
 313      -z    File has zero size (is empty).
 314      -s    File has nonzero size (returns size in bytes).
 315  
 316      -f    File is a plain file.
 317      -d    File is a directory.
 318      -l    File is a symbolic link.
 319      -p    File is a named pipe (FIFO), or Filehandle is a pipe.
 320      -S    File is a socket.
 321      -b    File is a block special file.
 322      -c    File is a character special file.
 323      -t    Filehandle is opened to a tty.
 324  
 325      -u    File has setuid bit set.
 326      -g    File has setgid bit set.
 327      -k    File has sticky bit set.
 328  
 329      -T    File is an ASCII text file (heuristic guess).
 330      -B    File is a "binary" file (opposite of -T).
 331  
 332      -M    Script start time minus file modification time, in days.
 333      -A    Same for access time.
 334      -C    Same for inode change time (Unix, may differ for other platforms)
 335  
 336  Example:
 337  
 338      while (<>) {
 339      chomp;
 340      next unless -f $_;    # ignore specials
 341      #...
 342      }
 343  
 344  The interpretation of the file permission operators C<-r>, C<-R>,
 345  C<-w>, C<-W>, C<-x>, and C<-X> is by default based solely on the mode
 346  of the file and the uids and gids of the user.  There may be other
 347  reasons you can't actually read, write, or execute the file: for
 348  example network filesystem access controls, ACLs (access control lists),
 349  read-only filesystems, and unrecognized executable formats.  Note
 350  that the use of these six specific operators to verify if some operation
 351  is possible is usually a mistake, because it may be open to race
 352  conditions.
 353  
 354  Also note that, for the superuser on the local filesystems, the C<-r>,
 355  C<-R>, C<-w>, and C<-W> tests always return 1, and C<-x> and C<-X> return 1
 356  if any execute bit is set in the mode.  Scripts run by the superuser
 357  may thus need to do a stat() to determine the actual mode of the file,
 358  or temporarily set their effective uid to something else.
 359  
 360  If you are using ACLs, there is a pragma called C<filetest> that may
 361  produce more accurate results than the bare stat() mode bits.
 362  When under the C<use filetest 'access'> the above-mentioned filetests
 363  will test whether the permission can (not) be granted using the
 364  access() family of system calls.  Also note that the C<-x> and C<-X> may
 365  under this pragma return true even if there are no execute permission
 366  bits set (nor any extra execute permission ACLs).  This strangeness is
 367  due to the underlying system calls' definitions. Note also that, due to
 368  the implementation of C<use filetest 'access'>, the C<_> special
 369  filehandle won't cache the results of the file tests when this pragma is
 370  in effect.  Read the documentation for the C<filetest> pragma for more
 371  information.
 372  
 373  Note that C<-s/a/b/> does not do a negated substitution.  Saying
 374  C<-exp($foo)> still works as expected, however--only single letters
 375  following a minus are interpreted as file tests.
 376  
 377  The C<-T> and C<-B> switches work as follows.  The first block or so of the
 378  file is examined for odd characters such as strange control codes or
 379  characters with the high bit set.  If too many strange characters (>30%)
 380  are found, it's a C<-B> file; otherwise it's a C<-T> file.  Also, any file
 381  containing null in the first block is considered a binary file.  If C<-T>
 382  or C<-B> is used on a filehandle, the current IO buffer is examined
 383  rather than the first block.  Both C<-T> and C<-B> return true on a null
 384  file, or a file at EOF when testing a filehandle.  Because you have to
 385  read a file to do the C<-T> test, on most occasions you want to use a C<-f>
 386  against the file first, as in C<next unless -f $file && -T $file>.
 387  
 388  If any of the file tests (or either the C<stat> or C<lstat> operators) are given
 389  the special filehandle consisting of a solitary underline, then the stat
 390  structure of the previous file test (or stat operator) is used, saving
 391  a system call.  (This doesn't work with C<-t>, and you need to remember
 392  that lstat() and C<-l> will leave values in the stat structure for the
 393  symbolic link, not the real file.)  (Also, if the stat buffer was filled by
 394  an C<lstat> call, C<-T> and C<-B> will reset it with the results of C<stat _>).
 395  Example:
 396  
 397      print "Can do.\n" if -r $a || -w _ || -x _;
 398  
 399      stat($filename);
 400      print "Readable\n" if -r _;
 401      print "Writable\n" if -w _;
 402      print "Executable\n" if -x _;
 403      print "Setuid\n" if -u _;
 404      print "Setgid\n" if -g _;
 405      print "Sticky\n" if -k _;
 406      print "Text\n" if -T _;
 407      print "Binary\n" if -B _;
 408  
 409  As of Perl 5.9.1, as a form of purely syntactic sugar, you can stack file
 410  test operators, in a way that C<-f -w -x $file> is equivalent to
 411  C<-x $file && -w _ && -f _>. (This is only syntax fancy: if you use
 412  the return value of C<-f $file> as an argument to another filetest
 413  operator, no special magic will happen.)
 414  
 415  =item abs VALUE
 416  X<abs> X<absolute>
 417  
 418  =item abs
 419  
 420  Returns the absolute value of its argument.
 421  If VALUE is omitted, uses C<$_>.
 422  
 423  =item accept NEWSOCKET,GENERICSOCKET
 424  X<accept>
 425  
 426  Accepts an incoming socket connect, just as the accept(2) system call
 427  does.  Returns the packed address if it succeeded, false otherwise.
 428  See the example in L<perlipc/"Sockets: Client/Server Communication">.
 429  
 430  On systems that support a close-on-exec flag on files, the flag will
 431  be set for the newly opened file descriptor, as determined by the
 432  value of $^F.  See L<perlvar/$^F>.
 433  
 434  =item alarm SECONDS
 435  X<alarm>
 436  X<SIGALRM>
 437  X<timer>
 438  
 439  =item alarm
 440  
 441  Arranges to have a SIGALRM delivered to this process after the
 442  specified number of wallclock seconds has elapsed.  If SECONDS is not
 443  specified, the value stored in C<$_> is used. (On some machines,
 444  unfortunately, the elapsed time may be up to one second less or more
 445  than you specified because of how seconds are counted, and process
 446  scheduling may delay the delivery of the signal even further.)
 447  
 448  Only one timer may be counting at once.  Each call disables the
 449  previous timer, and an argument of C<0> may be supplied to cancel the
 450  previous timer without starting a new one.  The returned value is the
 451  amount of time remaining on the previous timer.
 452  
 453  For delays of finer granularity than one second, the Time::HiRes module
 454  (from CPAN, and starting from Perl 5.8 part of the standard
 455  distribution) provides ualarm().  You may also use Perl's four-argument
 456  version of select() leaving the first three arguments undefined, or you
 457  might be able to use the C<syscall> interface to access setitimer(2) if
 458  your system supports it. See L<perlfaq8> for details.
 459  
 460  It is usually a mistake to intermix C<alarm> and C<sleep> calls.
 461  (C<sleep> may be internally implemented in your system with C<alarm>)
 462  
 463  If you want to use C<alarm> to time out a system call you need to use an
 464  C<eval>/C<die> pair.  You can't rely on the alarm causing the system call to
 465  fail with C<$!> set to C<EINTR> because Perl sets up signal handlers to
 466  restart system calls on some systems.  Using C<eval>/C<die> always works,
 467  modulo the caveats given in L<perlipc/"Signals">.
 468  
 469      eval {
 470      local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
 471      alarm $timeout;
 472      $nread = sysread SOCKET, $buffer, $size;
 473      alarm 0;
 474      };
 475      if ($@) {
 476      die unless $@ eq "alarm\n";   # propagate unexpected errors
 477          # timed out
 478      }
 479      else {
 480          # didn't
 481      }
 482  
 483  For more information see L<perlipc>.
 484  
 485  =item atan2 Y,X
 486  X<atan2> X<arctangent> X<tan> X<tangent>
 487  
 488  Returns the arctangent of Y/X in the range -PI to PI.
 489  
 490  For the tangent operation, you may use the C<Math::Trig::tan>
 491  function, or use the familiar relation:
 492  
 493      sub tan { sin($_[0]) / cos($_[0])  }
 494  
 495  Note that atan2(0, 0) is not well-defined.
 496  
 497  =item bind SOCKET,NAME
 498  X<bind>
 499  
 500  Binds a network address to a socket, just as the bind system call
 501  does.  Returns true if it succeeded, false otherwise.  NAME should be a
 502  packed address of the appropriate type for the socket.  See the examples in
 503  L<perlipc/"Sockets: Client/Server Communication">.
 504  
 505  =item binmode FILEHANDLE, LAYER
 506  X<binmode> X<binary> X<text> X<DOS> X<Windows>
 507  
 508  =item binmode FILEHANDLE
 509  
 510  Arranges for FILEHANDLE to be read or written in "binary" or "text"
 511  mode on systems where the run-time libraries distinguish between
 512  binary and text files.  If FILEHANDLE is an expression, the value is
 513  taken as the name of the filehandle.  Returns true on success,
 514  otherwise it returns C<undef> and sets C<$!> (errno).
 515  
 516  On some systems (in general, DOS and Windows-based systems) binmode()
 517  is necessary when you're not working with a text file.  For the sake
 518  of portability it is a good idea to always use it when appropriate,
 519  and to never use it when it isn't appropriate.  Also, people can
 520  set their I/O to be by default UTF-8 encoded Unicode, not bytes.
 521  
 522  In other words: regardless of platform, use binmode() on binary data,
 523  like for example images.
 524  
 525  If LAYER is present it is a single string, but may contain multiple
 526  directives. The directives alter the behaviour of the file handle.
 527  When LAYER is present using binmode on text file makes sense.
 528  
 529  If LAYER is omitted or specified as C<:raw> the filehandle is made
 530  suitable for passing binary data. This includes turning off possible CRLF
 531  translation and marking it as bytes (as opposed to Unicode characters).
 532  Note that, despite what may be implied in I<"Programming Perl"> (the
 533  Camel) or elsewhere, C<:raw> is I<not> simply the inverse of C<:crlf>
 534  -- other layers which would affect the binary nature of the stream are
 535  I<also> disabled. See L<PerlIO>, L<perlrun> and the discussion about the
 536  PERLIO environment variable.
 537  
 538  The C<:bytes>, C<:crlf>, and C<:utf8>, and any other directives of the
 539  form C<:...>, are called I/O I<layers>.  The C<open> pragma can be used to
 540  establish default I/O layers.  See L<open>.
 541  
 542  I<The LAYER parameter of the binmode() function is described as "DISCIPLINE"
 543  in "Programming Perl, 3rd Edition".  However, since the publishing of this
 544  book, by many known as "Camel III", the consensus of the naming of this
 545  functionality has moved from "discipline" to "layer".  All documentation
 546  of this version of Perl therefore refers to "layers" rather than to
 547  "disciplines".  Now back to the regularly scheduled documentation...>
 548  
 549  To mark FILEHANDLE as UTF-8, use C<:utf8> or C<:encoding(utf8)>.
 550  C<:utf8> just marks the data as UTF-8 without further checking,
 551  while C<:encoding(utf8)> checks the data for actually being valid
 552  UTF-8. More details can be found in L<PerlIO::encoding>.
 553  
 554  In general, binmode() should be called after open() but before any I/O
 555  is done on the filehandle.  Calling binmode() will normally flush any
 556  pending buffered output data (and perhaps pending input data) on the
 557  handle.  An exception to this is the C<:encoding> layer that
 558  changes the default character encoding of the handle, see L<open>.
 559  The C<:encoding> layer sometimes needs to be called in
 560  mid-stream, and it doesn't flush the stream.  The C<:encoding>
 561  also implicitly pushes on top of itself the C<:utf8> layer because
 562  internally Perl will operate on UTF-8 encoded Unicode characters.
 563  
 564  The operating system, device drivers, C libraries, and Perl run-time
 565  system all work together to let the programmer treat a single
 566  character (C<\n>) as the line terminator, irrespective of the external
 567  representation.  On many operating systems, the native text file
 568  representation matches the internal representation, but on some
 569  platforms the external representation of C<\n> is made up of more than
 570  one character.
 571  
 572  Mac OS, all variants of Unix, and Stream_LF files on VMS use a single
 573  character to end each line in the external representation of text (even
 574  though that single character is CARRIAGE RETURN on Mac OS and LINE FEED
 575  on Unix and most VMS files). In other systems like OS/2, DOS and the
 576  various flavors of MS-Windows your program sees a C<\n> as a simple C<\cJ>,
 577  but what's stored in text files are the two characters C<\cM\cJ>.  That
 578  means that, if you don't use binmode() on these systems, C<\cM\cJ>
 579  sequences on disk will be converted to C<\n> on input, and any C<\n> in
 580  your program will be converted back to C<\cM\cJ> on output.  This is what
 581  you want for text files, but it can be disastrous for binary files.
 582  
 583  Another consequence of using binmode() (on some systems) is that
 584  special end-of-file markers will be seen as part of the data stream.
 585  For systems from the Microsoft family this means that if your binary
 586  data contains C<\cZ>, the I/O subsystem will regard it as the end of
 587  the file, unless you use binmode().
 588  
 589  binmode() is not only important for readline() and print() operations,
 590  but also when using read(), seek(), sysread(), syswrite() and tell()
 591  (see L<perlport> for more details).  See the C<$/> and C<$\> variables
 592  in L<perlvar> for how to manually set your input and output
 593  line-termination sequences.
 594  
 595  =item bless REF,CLASSNAME
 596  X<bless>
 597  
 598  =item bless REF
 599  
 600  This function tells the thingy referenced by REF that it is now an object
 601  in the CLASSNAME package.  If CLASSNAME is omitted, the current package
 602  is used.  Because a C<bless> is often the last thing in a constructor,
 603  it returns the reference for convenience.  Always use the two-argument
 604  version if a derived class might inherit the function doing the blessing.
 605  See L<perltoot> and L<perlobj> for more about the blessing (and blessings)
 606  of objects.
 607  
 608  Consider always blessing objects in CLASSNAMEs that are mixed case.
 609  Namespaces with all lowercase names are considered reserved for
 610  Perl pragmata.  Builtin types have all uppercase names. To prevent
 611  confusion, you may wish to avoid such package names as well.  Make sure
 612  that CLASSNAME is a true value.
 613  
 614  See L<perlmod/"Perl Modules">.
 615  
 616  =item break
 617  
 618  Break out of a C<given()> block.
 619  
 620  This keyword is enabled by the "switch" feature: see L<feature>
 621  for more information.
 622  
 623  =item caller EXPR
 624  X<caller> X<call stack> X<stack> X<stack trace>
 625  
 626  =item caller
 627  
 628  Returns the context of the current subroutine call.  In scalar context,
 629  returns the caller's package name if there is a caller, that is, if
 630  we're in a subroutine or C<eval> or C<require>, and the undefined value
 631  otherwise.  In list context, returns
 632  
 633      # 0         1          2
 634      ($package, $filename, $line) = caller;
 635  
 636  With EXPR, it returns some extra information that the debugger uses to
 637  print a stack trace.  The value of EXPR indicates how many call frames
 638  to go back before the current one.
 639  
 640      #  0         1          2      3            4
 641      ($package, $filename, $line, $subroutine, $hasargs,
 642  
 643      #  5          6          7            8       9         10
 644      $wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
 645       = caller($i);
 646  
 647  Here $subroutine may be C<(eval)> if the frame is not a subroutine
 648  call, but an C<eval>.  In such a case additional elements $evaltext and
 649  C<$is_require> are set: C<$is_require> is true if the frame is created by a
 650  C<require> or C<use> statement, $evaltext contains the text of the
 651  C<eval EXPR> statement.  In particular, for an C<eval BLOCK> statement,
 652  $subroutine is C<(eval)>, but $evaltext is undefined.  (Note also that
 653  each C<use> statement creates a C<require> frame inside an C<eval EXPR>
 654  frame.)  $subroutine may also be C<(unknown)> if this particular
 655  subroutine happens to have been deleted from the symbol table.
 656  C<$hasargs> is true if a new instance of C<@_> was set up for the frame.
 657  C<$hints> and C<$bitmask> contain pragmatic hints that the caller was
 658  compiled with.  The C<$hints> and C<$bitmask> values are subject to change
 659  between versions of Perl, and are not meant for external use.
 660  
 661  C<$hinthash> is a reference to a hash containing the value of C<%^H> when the
 662  caller was compiled, or C<undef> if C<%^H> was empty. Do not modify the values
 663  of this hash, as they are the actual values stored in the optree.
 664  
 665  Furthermore, when called from within the DB package, caller returns more
 666  detailed information: it sets the list variable C<@DB::args> to be the
 667  arguments with which the subroutine was invoked.
 668  
 669  Be aware that the optimizer might have optimized call frames away before
 670  C<caller> had a chance to get the information.  That means that C<caller(N)>
 671  might not return information about the call frame you expect it do, for
 672  C<< N > 1 >>.  In particular, C<@DB::args> might have information from the
 673  previous time C<caller> was called.
 674  
 675  =item chdir EXPR
 676  X<chdir>
 677  X<cd>
 678  X<directory, change>
 679  
 680  =item chdir FILEHANDLE
 681  
 682  =item chdir DIRHANDLE
 683  
 684  =item chdir
 685  
 686  Changes the working directory to EXPR, if possible. If EXPR is omitted,
 687  changes to the directory specified by C<$ENV{HOME}>, if set; if not,
 688  changes to the directory specified by C<$ENV{LOGDIR}>. (Under VMS, the
 689  variable C<$ENV{SYS$LOGIN}> is also checked, and used if it is set.) If
 690  neither is set, C<chdir> does nothing. It returns true upon success,
 691  false otherwise. See the example under C<die>.
 692  
 693  On systems that support fchdir, you might pass a file handle or
 694  directory handle as argument.  On systems that don't support fchdir,
 695  passing handles produces a fatal error at run time.
 696  
 697  =item chmod LIST
 698  X<chmod> X<permission> X<mode>
 699  
 700  Changes the permissions of a list of files.  The first element of the
 701  list must be the numerical mode, which should probably be an octal
 702  number, and which definitely should I<not> be a string of octal digits:
 703  C<0644> is okay, C<'0644'> is not.  Returns the number of files
 704  successfully changed.  See also L</oct>, if all you have is a string.
 705  
 706      $cnt = chmod 0755, 'foo', 'bar';
 707      chmod 0755, @executables;
 708      $mode = '0644'; chmod $mode, 'foo';      # !!! sets mode to
 709                                               # --w----r-T
 710      $mode = '0644'; chmod oct($mode), 'foo'; # this is better
 711      $mode = 0644;   chmod $mode, 'foo';      # this is best
 712  
 713  On systems that support fchmod, you might pass file handles among the
 714  files.  On systems that don't support fchmod, passing file handles
 715  produces a fatal error at run time.   The file handles must be passed
 716  as globs or references to be recognized.  Barewords are considered
 717  file names.
 718  
 719      open(my $fh, "<", "foo");
 720      my $perm = (stat $fh)[2] & 07777;
 721      chmod($perm | 0600, $fh);
 722  
 723  You can also import the symbolic C<S_I*> constants from the Fcntl
 724  module:
 725  
 726      use Fcntl ':mode';
 727  
 728      chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
 729      # This is identical to the chmod 0755 of the above example.
 730  
 731  =item chomp VARIABLE
 732  X<chomp> X<INPUT_RECORD_SEPARATOR> X<$/> X<newline> X<eol>
 733  
 734  =item chomp( LIST )
 735  
 736  =item chomp
 737  
 738  This safer version of L</chop> removes any trailing string
 739  that corresponds to the current value of C<$/> (also known as
 740  $INPUT_RECORD_SEPARATOR in the C<English> module).  It returns the total
 741  number of characters removed from all its arguments.  It's often used to
 742  remove the newline from the end of an input record when you're worried
 743  that the final record may be missing its newline.  When in paragraph
 744  mode (C<$/ = "">), it removes all trailing newlines from the string.
 745  When in slurp mode (C<$/ = undef>) or fixed-length record mode (C<$/> is
 746  a reference to an integer or the like, see L<perlvar>) chomp() won't
 747  remove anything.
 748  If VARIABLE is omitted, it chomps C<$_>.  Example:
 749  
 750      while (<>) {
 751      chomp;    # avoid \n on last field
 752      @array = split(/:/);
 753      # ...
 754      }
 755  
 756  If VARIABLE is a hash, it chomps the hash's values, but not its keys.
 757  
 758  You can actually chomp anything that's an lvalue, including an assignment:
 759  
 760      chomp($cwd = `pwd`);
 761      chomp($answer = <STDIN>);
 762  
 763  If you chomp a list, each element is chomped, and the total number of
 764  characters removed is returned.
 765  
 766  Note that parentheses are necessary when you're chomping anything
 767  that is not a simple variable.  This is because C<chomp $cwd = `pwd`;>
 768  is interpreted as C<(chomp $cwd) = `pwd`;>, rather than as
 769  C<chomp( $cwd = `pwd` )> which you might expect.  Similarly,
 770  C<chomp $a, $b> is interpreted as C<chomp($a), $b> rather than
 771  as C<chomp($a, $b)>.
 772  
 773  =item chop VARIABLE
 774  X<chop>
 775  
 776  =item chop( LIST )
 777  
 778  =item chop
 779  
 780  Chops off the last character of a string and returns the character
 781  chopped.  It is much more efficient than C<s/.$//s> because it neither
 782  scans nor copies the string.  If VARIABLE is omitted, chops C<$_>.
 783  If VARIABLE is a hash, it chops the hash's values, but not its keys.
 784  
 785  You can actually chop anything that's an lvalue, including an assignment.
 786  
 787  If you chop a list, each element is chopped.  Only the value of the
 788  last C<chop> is returned.
 789  
 790  Note that C<chop> returns the last character.  To return all but the last
 791  character, use C<substr($string, 0, -1)>.
 792  
 793  See also L</chomp>.
 794  
 795  =item chown LIST
 796  X<chown> X<owner> X<user> X<group>
 797  
 798  Changes the owner (and group) of a list of files.  The first two
 799  elements of the list must be the I<numeric> uid and gid, in that
 800  order.  A value of -1 in either position is interpreted by most
 801  systems to leave that value unchanged.  Returns the number of files
 802  successfully changed.
 803  
 804      $cnt = chown $uid, $gid, 'foo', 'bar';
 805      chown $uid, $gid, @filenames;
 806  
 807  On systems that support fchown, you might pass file handles among the
 808  files.  On systems that don't support fchown, passing file handles
 809  produces a fatal error at run time.  The file handles must be passed
 810  as globs or references to be recognized.  Barewords are considered
 811  file names.
 812  
 813  Here's an example that looks up nonnumeric uids in the passwd file:
 814  
 815      print "User: ";
 816      chomp($user = <STDIN>);
 817      print "Files: ";
 818      chomp($pattern = <STDIN>);
 819  
 820      ($login,$pass,$uid,$gid) = getpwnam($user)
 821      or die "$user not in passwd file";
 822  
 823      @ary = glob($pattern);    # expand filenames
 824      chown $uid, $gid, @ary;
 825  
 826  On most systems, you are not allowed to change the ownership of the
 827  file unless you're the superuser, although you should be able to change
 828  the group to any of your secondary groups.  On insecure systems, these
 829  restrictions may be relaxed, but this is not a portable assumption.
 830  On POSIX systems, you can detect this condition this way:
 831  
 832      use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
 833      $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
 834  
 835  =item chr NUMBER
 836  X<chr> X<character> X<ASCII> X<Unicode>
 837  
 838  =item chr
 839  
 840  Returns the character represented by that NUMBER in the character set.
 841  For example, C<chr(65)> is C<"A"> in either ASCII or Unicode, and
 842  chr(0x263a) is a Unicode smiley face.  
 843  
 844  Negative values give the Unicode replacement character (chr(0xfffd)),
 845  except under the L<bytes> pragma, where low eight bits of the value
 846  (truncated to an integer) are used.
 847  
 848  If NUMBER is omitted, uses C<$_>.
 849  
 850  For the reverse, use L</ord>.
 851  
 852  Note that characters from 128 to 255 (inclusive) are by default
 853  internally not encoded as UTF-8 for backward compatibility reasons.
 854  
 855  See L<perlunicode> for more about Unicode.
 856  
 857  =item chroot FILENAME
 858  X<chroot> X<root>
 859  
 860  =item chroot
 861  
 862  This function works like the system call by the same name: it makes the
 863  named directory the new root directory for all further pathnames that
 864  begin with a C</> by your process and all its children.  (It doesn't
 865  change your current working directory, which is unaffected.)  For security
 866  reasons, this call is restricted to the superuser.  If FILENAME is
 867  omitted, does a C<chroot> to C<$_>.
 868  
 869  =item close FILEHANDLE
 870  X<close>
 871  
 872  =item close
 873  
 874  Closes the file or pipe associated with the file handle, flushes the IO
 875  buffers, and closes the system file descriptor.  Returns true if those
 876  operations have succeeded and if no error was reported by any PerlIO
 877  layer.  Closes the currently selected filehandle if the argument is
 878  omitted.
 879  
 880  You don't have to close FILEHANDLE if you are immediately going to do
 881  another C<open> on it, because C<open> will close it for you.  (See
 882  C<open>.)  However, an explicit C<close> on an input file resets the line
 883  counter (C<$.>), while the implicit close done by C<open> does not.
 884  
 885  If the file handle came from a piped open, C<close> will additionally
 886  return false if one of the other system calls involved fails, or if the
 887  program exits with non-zero status.  (If the only problem was that the
 888  program exited non-zero, C<$!> will be set to C<0>.)  Closing a pipe
 889  also waits for the process executing on the pipe to complete, in case you
 890  want to look at the output of the pipe afterwards, and
 891  implicitly puts the exit status value of that command into C<$?> and
 892  C<${^CHILD_ERROR_NATIVE}>.
 893  
 894  Prematurely closing the read end of a pipe (i.e. before the process
 895  writing to it at the other end has closed it) will result in a
 896  SIGPIPE being delivered to the writer.  If the other end can't
 897  handle that, be sure to read all the data before closing the pipe.
 898  
 899  Example:
 900  
 901      open(OUTPUT, '|sort >foo')  # pipe to sort
 902          or die "Can't start sort: $!";
 903      #...            # print stuff to output
 904      close OUTPUT        # wait for sort to finish
 905          or warn $! ? "Error closing sort pipe: $!"
 906                     : "Exit status $? from sort";
 907      open(INPUT, 'foo')        # get sort's results
 908          or die "Can't open 'foo' for input: $!";
 909  
 910  FILEHANDLE may be an expression whose value can be used as an indirect
 911  filehandle, usually the real filehandle name.
 912  
 913  =item closedir DIRHANDLE
 914  X<closedir>
 915  
 916  Closes a directory opened by C<opendir> and returns the success of that
 917  system call.
 918  
 919  =item connect SOCKET,NAME
 920  X<connect>
 921  
 922  Attempts to connect to a remote socket, just as the connect system call
 923  does.  Returns true if it succeeded, false otherwise.  NAME should be a
 924  packed address of the appropriate type for the socket.  See the examples in
 925  L<perlipc/"Sockets: Client/Server Communication">.
 926  
 927  =item continue BLOCK
 928  X<continue>
 929  
 930  =item continue
 931  
 932  C<continue> is actually a flow control statement rather than a function.  If
 933  there is a C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
 934  C<foreach>), it is always executed just before the conditional is about to
 935  be evaluated again, just like the third part of a C<for> loop in C.  Thus
 936  it can be used to increment a loop variable, even when the loop has been
 937  continued via the C<next> statement (which is similar to the C C<continue>
 938  statement).
 939  
 940  C<last>, C<next>, or C<redo> may appear within a C<continue>
 941  block.  C<last> and C<redo> will behave as if they had been executed within
 942  the main block.  So will C<next>, but since it will execute a C<continue>
 943  block, it may be more entertaining.
 944  
 945      while (EXPR) {
 946      ### redo always comes here
 947      do_something;
 948      } continue {
 949      ### next always comes here
 950      do_something_else;
 951      # then back the top to re-check EXPR
 952      }
 953      ### last always comes here
 954  
 955  Omitting the C<continue> section is semantically equivalent to using an
 956  empty one, logically enough.  In that case, C<next> goes directly back
 957  to check the condition at the top of the loop.
 958  
 959  If the "switch" feature is enabled, C<continue> is also a
 960  function that will break out of the current C<when> or C<default>
 961  block, and fall through to the next case. See L<feature> and
 962  L<perlsyn/"Switch statements"> for more information.
 963  
 964  
 965  =item cos EXPR
 966  X<cos> X<cosine> X<acos> X<arccosine>
 967  
 968  =item cos
 969  
 970  Returns the cosine of EXPR (expressed in radians).  If EXPR is omitted,
 971  takes cosine of C<$_>.
 972  
 973  For the inverse cosine operation, you may use the C<Math::Trig::acos()>
 974  function, or use this relation:
 975  
 976      sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
 977  
 978  =item crypt PLAINTEXT,SALT
 979  X<crypt> X<digest> X<hash> X<salt> X<plaintext> X<password>
 980  X<decrypt> X<cryptography> X<passwd> X<encrypt>
 981  
 982  Creates a digest string exactly like the crypt(3) function in the C
 983  library (assuming that you actually have a version there that has not
 984  been extirpated as a potential munitions).
 985  
 986  crypt() is a one-way hash function.  The PLAINTEXT and SALT is turned
 987  into a short string, called a digest, which is returned.  The same
 988  PLAINTEXT and SALT will always return the same string, but there is no
 989  (known) way to get the original PLAINTEXT from the hash.  Small
 990  changes in the PLAINTEXT or SALT will result in large changes in the
 991  digest.
 992  
 993  There is no decrypt function.  This function isn't all that useful for
 994  cryptography (for that, look for F<Crypt> modules on your nearby CPAN
 995  mirror) and the name "crypt" is a bit of a misnomer.  Instead it is
 996  primarily used to check if two pieces of text are the same without
 997  having to transmit or store the text itself.  An example is checking
 998  if a correct password is given.  The digest of the password is stored,
 999  not the password itself.  The user types in a password that is
1000  crypt()'d with the same salt as the stored digest.  If the two digests
1001  match the password is correct.
1002  
1003  When verifying an existing digest string you should use the digest as
1004  the salt (like C<crypt($plain, $digest) eq $digest>).  The SALT used
1005  to create the digest is visible as part of the digest.  This ensures
1006  crypt() will hash the new string with the same salt as the digest.
1007  This allows your code to work with the standard L<crypt|/crypt> and
1008  with more exotic implementations.  In other words, do not assume
1009  anything about the returned string itself, or how many bytes in the
1010  digest matter.
1011  
1012  Traditionally the result is a string of 13 bytes: two first bytes of
1013  the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only
1014  the first eight bytes of the digest string mattered, but alternative
1015  hashing schemes (like MD5), higher level security schemes (like C2),
1016  and implementations on non-UNIX platforms may produce different
1017  strings.
1018  
1019  When choosing a new salt create a random two character string whose
1020  characters come from the set C<[./0-9A-Za-z]> (like C<join '', ('.',
1021  '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>).  This set of
1022  characters is just a recommendation; the characters allowed in
1023  the salt depend solely on your system's crypt library, and Perl can't
1024  restrict what salts C<crypt()> accepts.
1025  
1026  Here's an example that makes sure that whoever runs this program knows
1027  their password:
1028  
1029      $pwd = (getpwuid($<))[1];
1030  
1031      system "stty -echo";
1032      print "Password: ";
1033      chomp($word = <STDIN>);
1034      print "\n";
1035      system "stty echo";
1036  
1037      if (crypt($word, $pwd) ne $pwd) {
1038      die "Sorry...\n";
1039      } else {
1040      print "ok\n";
1041      }
1042  
1043  Of course, typing in your own password to whoever asks you
1044  for it is unwise.
1045  
1046  The L<crypt|/crypt> function is unsuitable for hashing large quantities
1047  of data, not least of all because you can't get the information
1048  back.  Look at the L<Digest> module for more robust algorithms.
1049  
1050  If using crypt() on a Unicode string (which I<potentially> has
1051  characters with codepoints above 255), Perl tries to make sense
1052  of the situation by trying to downgrade (a copy of the string)
1053  the string back to an eight-bit byte string before calling crypt()
1054  (on that copy).  If that works, good.  If not, crypt() dies with
1055  C<Wide character in crypt>.
1056  
1057  =item dbmclose HASH
1058  X<dbmclose>
1059  
1060  [This function has been largely superseded by the C<untie> function.]
1061  
1062  Breaks the binding between a DBM file and a hash.
1063  
1064  =item dbmopen HASH,DBNAME,MASK
1065  X<dbmopen> X<dbm> X<ndbm> X<sdbm> X<gdbm>
1066  
1067  [This function has been largely superseded by the C<tie> function.]
1068  
1069  This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file to a
1070  hash.  HASH is the name of the hash.  (Unlike normal C<open>, the first
1071  argument is I<not> a filehandle, even though it looks like one).  DBNAME
1072  is the name of the database (without the F<.dir> or F<.pag> extension if
1073  any).  If the database does not exist, it is created with protection
1074  specified by MASK (as modified by the C<umask>).  If your system supports
1075  only the older DBM functions, you may perform only one C<dbmopen> in your
1076  program.  In older versions of Perl, if your system had neither DBM nor
1077  ndbm, calling C<dbmopen> produced a fatal error; it now falls back to
1078  sdbm(3).
1079  
1080  If you don't have write access to the DBM file, you can only read hash
1081  variables, not set them.  If you want to test whether you can write,
1082  either use file tests or try setting a dummy hash entry inside an C<eval>,
1083  which will trap the error.
1084  
1085  Note that functions such as C<keys> and C<values> may return huge lists
1086  when used on large DBM files.  You may prefer to use the C<each>
1087  function to iterate over large DBM files.  Example:
1088  
1089      # print out history file offsets
1090      dbmopen(%HIST,'/usr/lib/news/history',0666);
1091      while (($key,$val) = each %HIST) {
1092      print $key, ' = ', unpack('L',$val), "\n";
1093      }
1094      dbmclose(%HIST);
1095  
1096  See also L<AnyDBM_File> for a more general description of the pros and
1097  cons of the various dbm approaches, as well as L<DB_File> for a particularly
1098  rich implementation.
1099  
1100  You can control which DBM library you use by loading that library
1101  before you call dbmopen():
1102  
1103      use DB_File;
1104      dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db")
1105      or die "Can't open netscape history file: $!";
1106  
1107  =item defined EXPR
1108  X<defined> X<undef> X<undefined>
1109  
1110  =item defined
1111  
1112  Returns a Boolean value telling whether EXPR has a value other than
1113  the undefined value C<undef>.  If EXPR is not present, C<$_> will be
1114  checked.
1115  
1116  Many operations return C<undef> to indicate failure, end of file,
1117  system error, uninitialized variable, and other exceptional
1118  conditions.  This function allows you to distinguish C<undef> from
1119  other values.  (A simple Boolean test will not distinguish among
1120  C<undef>, zero, the empty string, and C<"0">, which are all equally
1121  false.)  Note that since C<undef> is a valid scalar, its presence
1122  doesn't I<necessarily> indicate an exceptional condition: C<pop>
1123  returns C<undef> when its argument is an empty array, I<or> when the
1124  element to return happens to be C<undef>.
1125  
1126  You may also use C<defined(&func)> to check whether subroutine C<&func>
1127  has ever been defined.  The return value is unaffected by any forward
1128  declarations of C<&func>.  Note that a subroutine which is not defined
1129  may still be callable: its package may have an C<AUTOLOAD> method that
1130  makes it spring into existence the first time that it is called -- see
1131  L<perlsub>.
1132  
1133  Use of C<defined> on aggregates (hashes and arrays) is deprecated.  It
1134  used to report whether memory for that aggregate has ever been
1135  allocated.  This behavior may disappear in future versions of Perl.
1136  You should instead use a simple test for size:
1137  
1138      if (@an_array) { print "has array elements\n" }
1139      if (%a_hash)   { print "has hash members\n"   }
1140  
1141  When used on a hash element, it tells you whether the value is defined,
1142  not whether the key exists in the hash.  Use L</exists> for the latter
1143  purpose.
1144  
1145  Examples:
1146  
1147      print if defined $switch{'D'};
1148      print "$val\n" while defined($val = pop(@ary));
1149      die "Can't readlink $sym: $!"
1150      unless defined($value = readlink $sym);
1151      sub foo { defined &$bar ? &$bar(@_) : die "No bar"; }
1152      $debugging = 0 unless defined $debugging;
1153  
1154  Note:  Many folks tend to overuse C<defined>, and then are surprised to
1155  discover that the number C<0> and C<""> (the zero-length string) are, in fact,
1156  defined values.  For example, if you say
1157  
1158      "ab" =~ /a(.*)b/;
1159  
1160  The pattern match succeeds, and C<$1> is defined, despite the fact that it
1161  matched "nothing".  It didn't really fail to match anything.  Rather, it
1162  matched something that happened to be zero characters long.  This is all
1163  very above-board and honest.  When a function returns an undefined value,
1164  it's an admission that it couldn't give you an honest answer.  So you
1165  should use C<defined> only when you're questioning the integrity of what
1166  you're trying to do.  At other times, a simple comparison to C<0> or C<""> is
1167  what you want.
1168  
1169  See also L</undef>, L</exists>, L</ref>.
1170  
1171  =item delete EXPR
1172  X<delete>
1173  
1174  Given an expression that specifies a hash element, array element, hash slice,
1175  or array slice, deletes the specified element(s) from the hash or array.
1176  In the case of an array, if the array elements happen to be at the end,
1177  the size of the array will shrink to the highest element that tests
1178  true for exists() (or 0 if no such element exists).
1179  
1180  Returns a list with the same number of elements as the number of elements
1181  for which deletion was attempted.  Each element of that list consists of
1182  either the value of the element deleted, or the undefined value.  In scalar
1183  context, this means that you get the value of the last element deleted (or
1184  the undefined value if that element did not exist).
1185  
1186      %hash = (foo => 11, bar => 22, baz => 33);
1187      $scalar = delete $hash{foo};             # $scalar is 11
1188      $scalar = delete @hash{qw(foo bar)};     # $scalar is 22
1189      @array  = delete @hash{qw(foo bar baz)}; # @array  is (undef,undef,33)
1190  
1191  Deleting from C<%ENV> modifies the environment.  Deleting from
1192  a hash tied to a DBM file deletes the entry from the DBM file.  Deleting
1193  from a C<tie>d hash or array may not necessarily return anything.
1194  
1195  Deleting an array element effectively returns that position of the array
1196  to its initial, uninitialized state.  Subsequently testing for the same
1197  element with exists() will return false.  Also, deleting array elements
1198  in the middle of an array will not shift the index of the elements
1199  after them down.  Use splice() for that.  See L</exists>.
1200  
1201  The following (inefficiently) deletes all the values of %HASH and @ARRAY:
1202  
1203      foreach $key (keys %HASH) {
1204      delete $HASH{$key};
1205      }
1206  
1207      foreach $index (0 .. $#ARRAY) {
1208      delete $ARRAY[$index];
1209      }
1210  
1211  And so do these:
1212  
1213      delete @HASH{keys %HASH};
1214  
1215      delete @ARRAY[0 .. $#ARRAY];
1216  
1217  But both of these are slower than just assigning the empty list
1218  or undefining %HASH or @ARRAY:
1219  
1220      %HASH = ();        # completely empty %HASH
1221      undef %HASH;    # forget %HASH ever existed
1222  
1223      @ARRAY = ();    # completely empty @ARRAY
1224      undef @ARRAY;    # forget @ARRAY ever existed
1225  
1226  Note that the EXPR can be arbitrarily complicated as long as the final
1227  operation is a hash element, array element,  hash slice, or array slice
1228  lookup:
1229  
1230      delete $ref->[$x][$y]{$key};
1231      delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};
1232  
1233      delete $ref->[$x][$y][$index];
1234      delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
1235  
1236  =item die LIST
1237  X<die> X<throw> X<exception> X<raise> X<$@> X<abort>
1238  
1239  Outside an C<eval>, prints the value of LIST to C<STDERR> and
1240  exits with the current value of C<$!> (errno).  If C<$!> is C<0>,
1241  exits with the value of C<<< ($? >> 8) >>> (backtick `command`
1242  status).  If C<<< ($? >> 8) >>> is C<0>, exits with C<255>.  Inside
1243  an C<eval(),> the error message is stuffed into C<$@> and the
1244  C<eval> is terminated with the undefined value.  This makes
1245  C<die> the way to raise an exception.
1246  
1247  Equivalent examples:
1248  
1249      die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
1250      chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
1251  
1252  If the last element of LIST does not end in a newline, the current
1253  script line number and input line number (if any) are also printed,
1254  and a newline is supplied.  Note that the "input line number" (also
1255  known as "chunk") is subject to whatever notion of "line" happens to
1256  be currently in effect, and is also available as the special variable
1257  C<$.>.  See L<perlvar/"$/"> and L<perlvar/"$.">.
1258  
1259  Hint: sometimes appending C<", stopped"> to your message will cause it
1260  to make better sense when the string C<"at foo line 123"> is appended.
1261  Suppose you are running script "canasta".
1262  
1263      die "/etc/games is no good";
1264      die "/etc/games is no good, stopped";
1265  
1266  produce, respectively
1267  
1268      /etc/games is no good at canasta line 123.
1269      /etc/games is no good, stopped at canasta line 123.
1270  
1271  See also exit(), warn(), and the Carp module.
1272  
1273  If LIST is empty and C<$@> already contains a value (typically from a
1274  previous eval) that value is reused after appending C<"\t...propagated">.
1275  This is useful for propagating exceptions:
1276  
1277      eval { ... };
1278      die unless $@ =~ /Expected exception/;
1279  
1280  If LIST is empty and C<$@> contains an object reference that has a
1281  C<PROPAGATE> method, that method will be called with additional file
1282  and line number parameters.  The return value replaces the value in
1283  C<$@>.  i.e. as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >>
1284  were called.
1285  
1286  If C<$@> is empty then the string C<"Died"> is used.
1287  
1288  die() can also be called with a reference argument.  If this happens to be
1289  trapped within an eval(), $@ contains the reference.  This behavior permits
1290  a more elaborate exception handling implementation using objects that
1291  maintain arbitrary state about the nature of the exception.  Such a scheme
1292  is sometimes preferable to matching particular string values of $@ using
1293  regular expressions.  Because $@ is a global variable, and eval() may be
1294  used within object implementations, care must be taken that analyzing the
1295  error object doesn't replace the reference in the global variable.  The
1296  easiest solution is to make a local copy of the reference before doing
1297  other manipulations.  Here's an example:
1298  
1299      use Scalar::Util 'blessed';
1300  
1301      eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
1302      if (my $ev_err = $@) {
1303          if (blessed($ev_err) && $ev_err->isa("Some::Module::Exception")) {
1304              # handle Some::Module::Exception
1305          }
1306          else {
1307              # handle all other possible exceptions
1308          }
1309      }
1310  
1311  Because perl will stringify uncaught exception messages before displaying
1312  them, you may want to overload stringification operations on such custom
1313  exception objects.  See L<overload> for details about that.
1314  
1315  You can arrange for a callback to be run just before the C<die>
1316  does its deed, by setting the C<$SIG{__DIE__}> hook.  The associated
1317  handler will be called with the error text and can change the error
1318  message, if it sees fit, by calling C<die> again.  See
1319  L<perlvar/$SIG{expr}> for details on setting C<%SIG> entries, and
1320  L<"eval BLOCK"> for some examples.  Although this feature was 
1321  to be run only right before your program was to exit, this is not
1322  currently the case--the C<$SIG{__DIE__}> hook is currently called
1323  even inside eval()ed blocks/strings!  If one wants the hook to do
1324  nothing in such situations, put
1325  
1326      die @_ if $^S;
1327  
1328  as the first line of the handler (see L<perlvar/$^S>).  Because
1329  this promotes strange action at a distance, this counterintuitive
1330  behavior may be fixed in a future release.
1331  
1332  =item do BLOCK
1333  X<do> X<block>
1334  
1335  Not really a function.  Returns the value of the last command in the
1336  sequence of commands indicated by BLOCK.  When modified by the C<while> or
1337  C<until> loop modifier, executes the BLOCK once before testing the loop
1338  condition. (On other statements the loop modifiers test the conditional
1339  first.)
1340  
1341  C<do BLOCK> does I<not> count as a loop, so the loop control statements
1342  C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
1343  See L<perlsyn> for alternative strategies.
1344  
1345  =item do SUBROUTINE(LIST)
1346  X<do>
1347  
1348  This form of subroutine call is deprecated.  See L<perlsub>.
1349  
1350  =item do EXPR
1351  X<do>
1352  
1353  Uses the value of EXPR as a filename and executes the contents of the
1354  file as a Perl script.
1355  
1356      do 'stat.pl';
1357  
1358  is just like
1359  
1360      eval `cat stat.pl`;
1361  
1362  except that it's more efficient and concise, keeps track of the current
1363  filename for error messages, searches the @INC directories, and updates
1364  C<%INC> if the file is found.  See L<perlvar/Predefined Names> for these
1365  variables.  It also differs in that code evaluated with C<do FILENAME>
1366  cannot see lexicals in the enclosing scope; C<eval STRING> does.  It's the
1367  same, however, in that it does reparse the file every time you call it,
1368  so you probably don't want to do this inside a loop.
1369  
1370  If C<do> cannot read the file, it returns undef and sets C<$!> to the
1371  error.  If C<do> can read the file but cannot compile it, it
1372  returns undef and sets an error message in C<$@>.   If the file is
1373  successfully compiled, C<do> returns the value of the last expression
1374  evaluated.
1375  
1376  Note that inclusion of library modules is better done with the
1377  C<use> and C<require> operators, which also do automatic error checking
1378  and raise an exception if there's a problem.
1379  
1380  You might like to use C<do> to read in a program configuration
1381  file.  Manual error checking can be done this way:
1382  
1383      # read in config files: system first, then user
1384      for $file ("/share/prog/defaults.rc",
1385                 "$ENV{HOME}/.someprogrc")
1386     {
1387      unless ($return = do $file) {
1388          warn "couldn't parse $file: $@" if $@;
1389          warn "couldn't do $file: $!"    unless defined $return;
1390          warn "couldn't run $file"       unless $return;
1391      }
1392      }
1393  
1394  =item dump LABEL
1395  X<dump> X<core> X<undump>
1396  
1397  =item dump
1398  
1399  This function causes an immediate core dump.  See also the B<-u>
1400  command-line switch in L<perlrun>, which does the same thing.
1401  Primarily this is so that you can use the B<undump> program (not
1402  supplied) to turn your core dump into an executable binary after
1403  having initialized all your variables at the beginning of the
1404  program.  When the new binary is executed it will begin by executing
1405  a C<goto LABEL> (with all the restrictions that C<goto> suffers).
1406  Think of it as a goto with an intervening core dump and reincarnation.
1407  If C<LABEL> is omitted, restarts the program from the top.
1408  
1409  B<WARNING>: Any files opened at the time of the dump will I<not>
1410  be open any more when the program is reincarnated, with possible
1411  resulting confusion on the part of Perl.
1412  
1413  This function is now largely obsolete, mostly because it's very hard to
1414  convert a core file into an executable. That's why you should now invoke
1415  it as C<CORE::dump()>, if you don't want to be warned against a possible
1416  typo.
1417  
1418  =item each HASH
1419  X<each> X<hash, iterator>
1420  
1421  When called in list context, returns a 2-element list consisting of the
1422  key and value for the next element of a hash, so that you can iterate over
1423  it.  When called in scalar context, returns only the key for the next
1424  element in the hash.
1425  
1426  Entries are returned in an apparently random order.  The actual random
1427  order is subject to change in future versions of perl, but it is
1428  guaranteed to be in the same order as either the C<keys> or C<values>
1429  function would produce on the same (unmodified) hash.  Since Perl
1430  5.8.1 the ordering is different even between different runs of Perl
1431  for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
1432  
1433  When the hash is entirely read, a null array is returned in list context
1434  (which when assigned produces a false (C<0>) value), and C<undef> in
1435  scalar context.  The next call to C<each> after that will start iterating
1436  again.  There is a single iterator for each hash, shared by all C<each>,
1437  C<keys>, and C<values> function calls in the program; it can be reset by
1438  reading all the elements from the hash, or by evaluating C<keys HASH> or
1439  C<values HASH>.  If you add or delete elements of a hash while you're
1440  iterating over it, you may get entries skipped or duplicated, so
1441  don't.  Exception: It is always safe to delete the item most recently
1442  returned by C<each()>, which means that the following code will work:
1443  
1444          while (($key, $value) = each %hash) {
1445            print $key, "\n";
1446            delete $hash{$key};   # This is safe
1447          }
1448  
1449  The following prints out your environment like the printenv(1) program,
1450  only in a different order:
1451  
1452      while (($key,$value) = each %ENV) {
1453      print "$key=$value\n";
1454      }
1455  
1456  See also C<keys>, C<values> and C<sort>.
1457  
1458  =item eof FILEHANDLE
1459  X<eof>
1460  X<end of file>
1461  X<end-of-file>
1462  
1463  =item eof ()
1464  
1465  =item eof
1466  
1467  Returns 1 if the next read on FILEHANDLE will return end of file, or if
1468  FILEHANDLE is not open.  FILEHANDLE may be an expression whose value
1469  gives the real filehandle.  (Note that this function actually
1470  reads a character and then C<ungetc>s it, so isn't very useful in an
1471  interactive context.)  Do not read from a terminal file (or call
1472  C<eof(FILEHANDLE)> on it) after end-of-file is reached.  File types such
1473  as terminals may lose the end-of-file condition if you do.
1474  
1475  An C<eof> without an argument uses the last file read.  Using C<eof()>
1476  with empty parentheses is very different.  It refers to the pseudo file
1477  formed from the files listed on the command line and accessed via the
1478  C<< <> >> operator.  Since C<< <> >> isn't explicitly opened,
1479  as a normal filehandle is, an C<eof()> before C<< <> >> has been
1480  used will cause C<@ARGV> to be examined to determine if input is
1481  available.   Similarly, an C<eof()> after C<< <> >> has returned
1482  end-of-file will assume you are processing another C<@ARGV> list,
1483  and if you haven't set C<@ARGV>, will read input from C<STDIN>;
1484  see L<perlop/"I/O Operators">.
1485  
1486  In a C<< while (<>) >> loop, C<eof> or C<eof(ARGV)> can be used to
1487  detect the end of each file, C<eof()> will only detect the end of the
1488  last file.  Examples:
1489  
1490      # reset line numbering on each input file
1491      while (<>) {
1492      next if /^\s*#/;    # skip comments
1493      print "$.\t$_";
1494      } continue {
1495      close ARGV  if eof;    # Not eof()!
1496      }
1497  
1498      # insert dashes just before last line of last file
1499      while (<>) {
1500      if (eof()) {        # check for end of last file
1501          print "--------------\n";
1502      }
1503      print;
1504      last if eof();          # needed if we're reading from a terminal
1505      }
1506  
1507  Practical hint: you almost never need to use C<eof> in Perl, because the
1508  input operators typically return C<undef> when they run out of data, or if
1509  there was an error.
1510  
1511  =item eval EXPR
1512  X<eval> X<try> X<catch> X<evaluate> X<parse> X<execute>
1513  X<error, handling> X<exception, handling>
1514  
1515  =item eval BLOCK
1516  
1517  =item eval
1518  
1519  In the first form, the return value of EXPR is parsed and executed as if it
1520  were a little Perl program.  The value of the expression (which is itself
1521  determined within scalar context) is first parsed, and if there weren't any
1522  errors, executed in the lexical context of the current Perl program, so
1523  that any variable settings or subroutine and format definitions remain
1524  afterwards.  Note that the value is parsed every time the C<eval> executes.
1525  If EXPR is omitted, evaluates C<$_>.  This form is typically used to
1526  delay parsing and subsequent execution of the text of EXPR until run time.
1527  
1528  In the second form, the code within the BLOCK is parsed only once--at the
1529  same time the code surrounding the C<eval> itself was parsed--and executed
1530  within the context of the current Perl program.  This form is typically
1531  used to trap exceptions more efficiently than the first (see below), while
1532  also providing the benefit of checking the code within BLOCK at compile
1533  time.
1534  
1535  The final semicolon, if any, may be omitted from the value of EXPR or within
1536  the BLOCK.
1537  
1538  In both forms, the value returned is the value of the last expression
1539  evaluated inside the mini-program; a return statement may be also used, just
1540  as with subroutines.  The expression providing the return value is evaluated
1541  in void, scalar, or list context, depending on the context of the C<eval> 
1542  itself.  See L</wantarray> for more on how the evaluation context can be 
1543  determined.
1544  
1545  If there is a syntax error or runtime error, or a C<die> statement is
1546  executed, an undefined value is returned by C<eval>, and C<$@> is set to the
1547  error message.  If there was no error, C<$@> is guaranteed to be a null
1548  string.  Beware that using C<eval> neither silences perl from printing
1549  warnings to STDERR, nor does it stuff the text of warning messages into C<$@>.
1550  To do either of those, you have to use the C<$SIG{__WARN__}> facility, or
1551  turn off warnings inside the BLOCK or EXPR using S<C<no warnings 'all'>>.
1552  See L</warn>, L<perlvar>, L<warnings> and L<perllexwarn>.
1553  
1554  Note that, because C<eval> traps otherwise-fatal errors, it is useful for
1555  determining whether a particular feature (such as C<socket> or C<symlink>)
1556  is implemented.  It is also Perl's exception trapping mechanism, where
1557  the die operator is used to raise exceptions.
1558  
1559  If the code to be executed doesn't vary, you may use the eval-BLOCK
1560  form to trap run-time errors without incurring the penalty of
1561  recompiling each time.  The error, if any, is still returned in C<$@>.
1562  Examples:
1563  
1564      # make divide-by-zero nonfatal
1565      eval { $answer = $a / $b; }; warn $@ if $@;
1566  
1567      # same thing, but less efficient
1568      eval '$answer = $a / $b'; warn $@ if $@;
1569  
1570      # a compile-time error
1571      eval { $answer = };            # WRONG
1572  
1573      # a run-time error
1574      eval '$answer =';    # sets $@
1575  
1576  Using the C<eval{}> form as an exception trap in libraries does have some
1577  issues.  Due to the current arguably broken state of C<__DIE__> hooks, you
1578  may wish not to trigger any C<__DIE__> hooks that user code may have installed.
1579  You can use the C<local $SIG{__DIE__}> construct for this purpose,
1580  as shown in this example:
1581  
1582      # a very private exception trap for divide-by-zero
1583      eval { local $SIG{'__DIE__'}; $answer = $a / $b; };
1584      warn $@ if $@;
1585  
1586  This is especially significant, given that C<__DIE__> hooks can call
1587  C<die> again, which has the effect of changing their error messages:
1588  
1589      # __DIE__ hooks may modify error messages
1590      {
1591         local $SIG{'__DIE__'} =
1592                sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
1593         eval { die "foo lives here" };
1594         print $@ if $@;                # prints "bar lives here"
1595      }
1596  
1597  Because this promotes action at a distance, this counterintuitive behavior
1598  may be fixed in a future release.
1599  
1600  With an C<eval>, you should be especially careful to remember what's
1601  being looked at when:
1602  
1603      eval $x;        # CASE 1
1604      eval "$x";        # CASE 2
1605  
1606      eval '$x';        # CASE 3
1607      eval { $x };    # CASE 4
1608  
1609      eval "\$$x++";    # CASE 5
1610      $$x++;        # CASE 6
1611  
1612  Cases 1 and 2 above behave identically: they run the code contained in
1613  the variable $x.  (Although case 2 has misleading double quotes making
1614  the reader wonder what else might be happening (nothing is).)  Cases 3
1615  and 4 likewise behave in the same way: they run the code C<'$x'>, which
1616  does nothing but return the value of $x.  (Case 4 is preferred for
1617  purely visual reasons, but it also has the advantage of compiling at
1618  compile-time instead of at run-time.)  Case 5 is a place where
1619  normally you I<would> like to use double quotes, except that in this
1620  particular situation, you can just use symbolic references instead, as
1621  in case 6.
1622  
1623  C<eval BLOCK> does I<not> count as a loop, so the loop control statements
1624  C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
1625  
1626  Note that as a very special case, an C<eval ''> executed within the C<DB>
1627  package doesn't see the usual surrounding lexical scope, but rather the
1628  scope of the first non-DB piece of code that called it. You don't normally
1629  need to worry about this unless you are writing a Perl debugger.
1630  
1631  =item exec LIST
1632  X<exec> X<execute>
1633  
1634  =item exec PROGRAM LIST
1635  
1636  The C<exec> function executes a system command I<and never returns>--
1637  use C<system> instead of C<exec> if you want it to return.  It fails and
1638  returns false only if the command does not exist I<and> it is executed
1639  directly instead of via your system's command shell (see below).
1640  
1641  Since it's a common mistake to use C<exec> instead of C<system>, Perl
1642  warns you if there is a following statement which isn't C<die>, C<warn>,
1643  or C<exit> (if C<-w> is set  -  but you always do that).   If you
1644  I<really> want to follow an C<exec> with some other statement, you
1645  can use one of these styles to avoid the warning:
1646  
1647      exec ('foo')   or print STDERR "couldn't exec foo: $!";
1648      { exec ('foo') }; print STDERR "couldn't exec foo: $!";
1649  
1650  If there is more than one argument in LIST, or if LIST is an array
1651  with more than one value, calls execvp(3) with the arguments in LIST.
1652  If there is only one scalar argument or an array with one element in it,
1653  the argument is checked for shell metacharacters, and if there are any,
1654  the entire argument is passed to the system's command shell for parsing
1655  (this is C</bin/sh -c> on Unix platforms, but varies on other platforms).
1656  If there are no shell metacharacters in the argument, it is split into
1657  words and passed directly to C<execvp>, which is more efficient.
1658  Examples:
1659  
1660      exec '/bin/echo', 'Your arguments are: ', @ARGV;
1661      exec "sort $outfile | uniq";
1662  
1663  If you don't really want to execute the first argument, but want to lie
1664  to the program you are executing about its own name, you can specify
1665  the program you actually want to run as an "indirect object" (without a
1666  comma) in front of the LIST.  (This always forces interpretation of the
1667  LIST as a multivalued list, even if there is only a single scalar in
1668  the list.)  Example:
1669  
1670      $shell = '/bin/csh';
1671      exec $shell '-sh';        # pretend it's a login shell
1672  
1673  or, more directly,
1674  
1675      exec {'/bin/csh'} '-sh';    # pretend it's a login shell
1676  
1677  When the arguments get executed via the system shell, results will
1678  be subject to its quirks and capabilities.  See L<perlop/"`STRING`">
1679  for details.
1680  
1681  Using an indirect object with C<exec> or C<system> is also more
1682  secure.  This usage (which also works fine with system()) forces
1683  interpretation of the arguments as a multivalued list, even if the
1684  list had just one argument.  That way you're safe from the shell
1685  expanding wildcards or splitting up words with whitespace in them.
1686  
1687      @args = ( "echo surprise" );
1688  
1689      exec @args;               # subject to shell escapes
1690                                  # if @args == 1
1691      exec { $args[0] } @args;  # safe even with one-arg list
1692  
1693  The first version, the one without the indirect object, ran the I<echo>
1694  program, passing it C<"surprise"> an argument.  The second version
1695  didn't--it tried to run a program literally called I<"echo surprise">,
1696  didn't find it, and set C<$?> to a non-zero value indicating failure.
1697  
1698  Beginning with v5.6.0, Perl will attempt to flush all files opened for
1699  output before the exec, but this may not be supported on some platforms
1700  (see L<perlport>).  To be safe, you may need to set C<$|> ($AUTOFLUSH
1701  in English) or call the C<autoflush()> method of C<IO::Handle> on any
1702  open handles in order to avoid lost output.
1703  
1704  Note that C<exec> will not call your C<END> blocks, nor will it call
1705  any C<DESTROY> methods in your objects.
1706  
1707  =item exists EXPR
1708  X<exists> X<autovivification>
1709  
1710  Given an expression that specifies a hash element or array element,
1711  returns true if the specified element in the hash or array has ever
1712  been initialized, even if the corresponding value is undefined.  The
1713  element is not autovivified if it doesn't exist.
1714  
1715      print "Exists\n"     if exists $hash{$key};
1716      print "Defined\n"     if defined $hash{$key};
1717      print "True\n"      if $hash{$key};
1718  
1719      print "Exists\n"     if exists $array[$index];
1720      print "Defined\n"     if defined $array[$index];
1721      print "True\n"      if $array[$index];
1722  
1723  A hash or array element can be true only if it's defined, and defined if
1724  it exists, but the reverse doesn't necessarily hold true.
1725  
1726  Given an expression that specifies the name of a subroutine,
1727  returns true if the specified subroutine has ever been declared, even
1728  if it is undefined.  Mentioning a subroutine name for exists or defined
1729  does not count as declaring it.  Note that a subroutine which does not
1730  exist may still be callable: its package may have an C<AUTOLOAD>
1731  method that makes it spring into existence the first time that it is
1732  called -- see L<perlsub>.
1733  
1734      print "Exists\n"     if exists &subroutine;
1735      print "Defined\n"     if defined &subroutine;
1736  
1737  Note that the EXPR can be arbitrarily complicated as long as the final
1738  operation is a hash or array key lookup or subroutine name:
1739  
1740      if (exists $ref->{A}->{B}->{$key})     { }
1741      if (exists $hash{A}{B}{$key})     { }
1742  
1743      if (exists $ref->{A}->{B}->[$ix])     { }
1744      if (exists $hash{A}{B}[$ix])     { }
1745  
1746      if (exists &{$ref->{A}{B}{$key}})   { }
1747  
1748  Although the deepest nested array or hash will not spring into existence
1749  just because its existence was tested, any intervening ones will.
1750  Thus C<< $ref->{"A"} >> and C<< $ref->{"A"}->{"B"} >> will spring
1751  into existence due to the existence test for the $key element above.
1752  This happens anywhere the arrow operator is used, including even:
1753  
1754      undef $ref;
1755      if (exists $ref->{"Some key"})    { }
1756      print $ref;         # prints HASH(0x80d3d5c)
1757  
1758  This surprising autovivification in what does not at first--or even
1759  second--glance appear to be an lvalue context may be fixed in a future
1760  release.
1761  
1762  Use of a subroutine call, rather than a subroutine name, as an argument
1763  to exists() is an error.
1764  
1765      exists &sub;    # OK
1766      exists &sub();    # Error
1767  
1768  =item exit EXPR
1769  X<exit> X<terminate> X<abort>
1770  
1771  =item exit
1772  
1773  Evaluates EXPR and exits immediately with that value.    Example:
1774  
1775      $ans = <STDIN>;
1776      exit 0 if $ans =~ /^[Xx]/;
1777  
1778  See also C<die>.  If EXPR is omitted, exits with C<0> status.  The only
1779  universally recognized values for EXPR are C<0> for success and C<1>
1780  for error; other values are subject to interpretation depending on the
1781  environment in which the Perl program is running.  For example, exiting
1782  69 (EX_UNAVAILABLE) from a I<sendmail> incoming-mail filter will cause
1783  the mailer to return the item undelivered, but that's not true everywhere.
1784  
1785  Don't use C<exit> to abort a subroutine if there's any chance that
1786  someone might want to trap whatever error happened.  Use C<die> instead,
1787  which can be trapped by an C<eval>.
1788  
1789  The exit() function does not always exit immediately.  It calls any
1790  defined C<END> routines first, but these C<END> routines may not
1791  themselves abort the exit.  Likewise any object destructors that need to
1792  be called are called before the real exit.  If this is a problem, you
1793  can call C<POSIX:_exit($status)> to avoid END and destructor processing.
1794  See L<perlmod> for details.
1795  
1796  =item exp EXPR
1797  X<exp> X<exponential> X<antilog> X<antilogarithm> X<e>
1798  
1799  =item exp
1800  
1801  Returns I<e> (the natural logarithm base) to the power of EXPR.
1802  If EXPR is omitted, gives C<exp($_)>.
1803  
1804  =item fcntl FILEHANDLE,FUNCTION,SCALAR
1805  X<fcntl>
1806  
1807  Implements the fcntl(2) function.  You'll probably have to say
1808  
1809      use Fcntl;
1810  
1811  first to get the correct constant definitions.  Argument processing and
1812  value return works just like C<ioctl> below.
1813  For example:
1814  
1815      use Fcntl;
1816      fcntl($filehandle, F_GETFL, $packed_return_buffer)
1817      or die "can't fcntl F_GETFL: $!";
1818  
1819  You don't have to check for C<defined> on the return from C<fcntl>.
1820  Like C<ioctl>, it maps a C<0> return from the system call into
1821  C<"0 but true"> in Perl.  This string is true in boolean context and C<0>
1822  in numeric context.  It is also exempt from the normal B<-w> warnings
1823  on improper numeric conversions.
1824  
1825  Note that C<fcntl> will produce a fatal error if used on a machine that
1826  doesn't implement fcntl(2).  See the Fcntl module or your fcntl(2)
1827  manpage to learn what functions are available on your system.
1828  
1829  Here's an example of setting a filehandle named C<REMOTE> to be
1830  non-blocking at the system level.  You'll have to negotiate C<$|>
1831  on your own, though.
1832  
1833      use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
1834  
1835      $flags = fcntl(REMOTE, F_GETFL, 0)
1836                  or die "Can't get flags for the socket: $!\n";
1837  
1838      $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK)
1839                  or die "Can't set flags for the socket: $!\n";
1840  
1841  =item fileno FILEHANDLE
1842  X<fileno>
1843  
1844  Returns the file descriptor for a filehandle, or undefined if the
1845  filehandle is not open.  This is mainly useful for constructing
1846  bitmaps for C<select> and low-level POSIX tty-handling operations.
1847  If FILEHANDLE is an expression, the value is taken as an indirect
1848  filehandle, generally its name.
1849  
1850  You can use this to find out whether two handles refer to the
1851  same underlying descriptor:
1852  
1853      if (fileno(THIS) == fileno(THAT)) {
1854      print "THIS and THAT are dups\n";
1855      }
1856  
1857  (Filehandles connected to memory objects via new features of C<open> may
1858  return undefined even though they are open.)
1859  
1860  
1861  =item flock FILEHANDLE,OPERATION
1862  X<flock> X<lock> X<locking>
1863  
1864  Calls flock(2), or an emulation of it, on FILEHANDLE.  Returns true
1865  for success, false on failure.  Produces a fatal error if used on a
1866  machine that doesn't implement flock(2), fcntl(2) locking, or lockf(3).
1867  C<flock> is Perl's portable file locking interface, although it locks
1868  only entire files, not records.
1869  
1870  Two potentially non-obvious but traditional C<flock> semantics are
1871  that it waits indefinitely until the lock is granted, and that its locks
1872  B<merely advisory>.  Such discretionary locks are more flexible, but offer
1873  fewer guarantees.  This means that programs that do not also use C<flock>
1874  may modify files locked with C<flock>.  See L<perlport>, 
1875  your port's specific documentation, or your system-specific local manpages
1876  for details.  It's best to assume traditional behavior if you're writing
1877  portable programs.  (But if you're not, you should as always feel perfectly
1878  free to write for your own system's idiosyncrasies (sometimes called
1879  "features").  Slavish adherence to portability concerns shouldn't get
1880  in the way of your getting your job done.)
1881  
1882  OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with
1883  LOCK_NB.  These constants are traditionally valued 1, 2, 8 and 4, but
1884  you can use the symbolic names if you import them from the Fcntl module,
1885  either individually, or as a group using the ':flock' tag.  LOCK_SH
1886  requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN
1887  releases a previously requested lock.  If LOCK_NB is bitwise-or'ed with
1888  LOCK_SH or LOCK_EX then C<flock> will return immediately rather than blocking
1889  waiting for the lock (check the return status to see if you got it).
1890  
1891  To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE
1892  before locking or unlocking it.
1893  
1894  Note that the emulation built with lockf(3) doesn't provide shared
1895  locks, and it requires that FILEHANDLE be open with write intent.  These
1896  are the semantics that lockf(3) implements.  Most if not all systems
1897  implement lockf(3) in terms of fcntl(2) locking, though, so the
1898  differing semantics shouldn't bite too many people.
1899  
1900  Note that the fcntl(2) emulation of flock(3) requires that FILEHANDLE
1901  be open with read intent to use LOCK_SH and requires that it be open
1902  with write intent to use LOCK_EX.
1903  
1904  Note also that some versions of C<flock> cannot lock things over the
1905  network; you would need to use the more system-specific C<fcntl> for
1906  that.  If you like you can force Perl to ignore your system's flock(2)
1907  function, and so provide its own fcntl(2)-based emulation, by passing
1908  the switch C<-Ud_flock> to the F<Configure> program when you configure
1909  perl.
1910  
1911  Here's a mailbox appender for BSD systems.
1912  
1913      use Fcntl ':flock'; # import LOCK_* constants
1914  
1915      sub lock {
1916      flock(MBOX,LOCK_EX);
1917      # and, in case someone appended
1918      # while we were waiting...
1919      seek(MBOX, 0, 2);
1920      }
1921  
1922      sub unlock {
1923      flock(MBOX,LOCK_UN);
1924      }
1925  
1926      open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
1927          or die "Can't open mailbox: $!";
1928  
1929      lock();
1930      print MBOX $msg,"\n\n";
1931      unlock();
1932  
1933  On systems that support a real flock(), locks are inherited across fork()
1934  calls, whereas those that must resort to the more capricious fcntl()
1935  function lose the locks, making it harder to write servers.
1936  
1937  See also L<DB_File> for other flock() examples.
1938  
1939  =item fork
1940  X<fork> X<child> X<parent>
1941  
1942  Does a fork(2) system call to create a new process running the
1943  same program at the same point.  It returns the child pid to the
1944  parent process, C<0> to the child process, or C<undef> if the fork is
1945  unsuccessful.  File descriptors (and sometimes locks on those descriptors)
1946  are shared, while everything else is copied.  On most systems supporting
1947  fork(), great care has gone into making it extremely efficient (for
1948  example, using copy-on-write technology on data pages), making it the
1949  dominant paradigm for multitasking over the last few decades.
1950  
1951  Beginning with v5.6.0, Perl will attempt to flush all files opened for
1952  output before forking the child process, but this may not be supported
1953  on some platforms (see L<perlport>).  To be safe, you may need to set
1954  C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
1955  C<IO::Handle> on any open handles in order to avoid duplicate output.
1956  
1957  If you C<fork> without ever waiting on your children, you will
1958  accumulate zombies.  On some systems, you can avoid this by setting
1959  C<$SIG{CHLD}> to C<"IGNORE">.  See also L<perlipc> for more examples of
1960  forking and reaping moribund children.
1961  
1962  Note that if your forked child inherits system file descriptors like
1963  STDIN and STDOUT that are actually connected by a pipe or socket, even
1964  if you exit, then the remote server (such as, say, a CGI script or a
1965  backgrounded job launched from a remote shell) won't think you're done.
1966  You should reopen those to F</dev/null> if it's any issue.
1967  
1968  =item format
1969  X<format>
1970  
1971  Declare a picture format for use by the C<write> function.  For
1972  example:
1973  
1974      format Something =
1975      Test: @<<<<<<<< @||||| @>>>>>
1976            $str,     $%,    '$' . int($num)
1977      .
1978  
1979      $str = "widget";
1980      $num = $cost/$quantity;
1981      $~ = 'Something';
1982      write;
1983  
1984  See L<perlform> for many details and examples.
1985  
1986  =item formline PICTURE,LIST
1987  X<formline>
1988  
1989  This is an internal function used by C<format>s, though you may call it,
1990  too.  It formats (see L<perlform>) a list of values according to the
1991  contents of PICTURE, placing the output into the format output
1992  accumulator, C<$^A> (or C<$ACCUMULATOR> in English).
1993  Eventually, when a C<write> is done, the contents of
1994  C<$^A> are written to some filehandle.  You could also read C<$^A>
1995  and then set C<$^A> back to C<"">.  Note that a format typically
1996  does one C<formline> per line of form, but the C<formline> function itself
1997  doesn't care how many newlines are embedded in the PICTURE.  This means
1998  that the C<~> and C<~~> tokens will treat the entire PICTURE as a single line.
1999  You may therefore need to use multiple formlines to implement a single
2000  record format, just like the format compiler.
2001  
2002  Be careful if you put double quotes around the picture, because an C<@>
2003  character may be taken to mean the beginning of an array name.
2004  C<formline> always returns true.  See L<perlform> for other examples.
2005  
2006  =item getc FILEHANDLE
2007  X<getc> X<getchar> X<character> X<file, read>
2008  
2009  =item getc
2010  
2011  Returns the next character from the input file attached to FILEHANDLE,
2012  or the undefined value at end of file, or if there was an error (in
2013  the latter case C<$!> is set).  If FILEHANDLE is omitted, reads from
2014  STDIN.  This is not particularly efficient.  However, it cannot be
2015  used by itself to fetch single characters without waiting for the user
2016  to hit enter.  For that, try something more like:
2017  
2018      if ($BSD_STYLE) {
2019      system "stty cbreak </dev/tty >/dev/tty 2>&1";
2020      }
2021      else {
2022      system "stty", '-icanon', 'eol', "\001";
2023      }
2024  
2025      $key = getc(STDIN);
2026  
2027      if ($BSD_STYLE) {
2028      system "stty -cbreak </dev/tty >/dev/tty 2>&1";
2029      }
2030      else {
2031      system "stty", 'icanon', 'eol', '^@'; # ASCII null
2032      }
2033      print "\n";
2034  
2035  Determination of whether $BSD_STYLE should be set
2036  is left as an exercise to the reader.
2037  
2038  The C<POSIX::getattr> function can do this more portably on
2039  systems purporting POSIX compliance.  See also the C<Term::ReadKey>
2040  module from your nearest CPAN site; details on CPAN can be found on
2041  L<perlmodlib/CPAN>.
2042  
2043  =item getlogin
2044  X<getlogin> X<login>
2045  
2046  This implements the C library function of the same name, which on most
2047  systems returns the current login from F</etc/utmp>, if any.  If null,
2048  use C<getpwuid>.
2049  
2050      $login = getlogin || getpwuid($<) || "Kilroy";
2051  
2052  Do not consider C<getlogin> for authentication: it is not as
2053  secure as C<getpwuid>.
2054  
2055  =item getpeername SOCKET
2056  X<getpeername> X<peer>
2057  
2058  Returns the packed sockaddr address of other end of the SOCKET connection.
2059  
2060      use Socket;
2061      $hersockaddr    = getpeername(SOCK);
2062      ($port, $iaddr) = sockaddr_in($hersockaddr);
2063      $herhostname    = gethostbyaddr($iaddr, AF_INET);
2064      $herstraddr     = inet_ntoa($iaddr);
2065  
2066  =item getpgrp PID
2067  X<getpgrp> X<group>
2068  
2069  Returns the current process group for the specified PID.  Use
2070  a PID of C<0> to get the current process group for the
2071  current process.  Will raise an exception if used on a machine that
2072  doesn't implement getpgrp(2).  If PID is omitted, returns process
2073  group of current process.  Note that the POSIX version of C<getpgrp>
2074  does not accept a PID argument, so only C<PID==0> is truly portable.
2075  
2076  =item getppid
2077  X<getppid> X<parent> X<pid>
2078  
2079  Returns the process id of the parent process.
2080  
2081  Note for Linux users: on Linux, the C functions C<getpid()> and
2082  C<getppid()> return different values from different threads. In order to
2083  be portable, this behavior is not reflected by the perl-level function
2084  C<getppid()>, that returns a consistent value across threads. If you want
2085  to call the underlying C<getppid()>, you may use the CPAN module
2086  C<Linux::Pid>.
2087  
2088  =item getpriority WHICH,WHO
2089  X<getpriority> X<priority> X<nice>
2090  
2091  Returns the current priority for a process, a process group, or a user.
2092  (See L<getpriority(2)>.)  Will raise a fatal exception if used on a
2093  machine that doesn't implement getpriority(2).
2094  
2095  =item getpwnam NAME
2096  X<getpwnam> X<getgrnam> X<gethostbyname> X<getnetbyname> X<getprotobyname>
2097  X<getpwuid> X<getgrgid> X<getservbyname> X<gethostbyaddr> X<getnetbyaddr>
2098  X<getprotobynumber> X<getservbyport> X<getpwent> X<getgrent> X<gethostent>
2099  X<getnetent> X<getprotoent> X<getservent> X<setpwent> X<setgrent> X<sethostent>
2100  X<setnetent> X<setprotoent> X<setservent> X<endpwent> X<endgrent> X<endhostent>
2101  X<endnetent> X<endprotoent> X<endservent> 
2102  
2103  =item getgrnam NAME
2104  
2105  =item gethostbyname NAME
2106  
2107  =item getnetbyname NAME
2108  
2109  =item getprotobyname NAME
2110  
2111  =item getpwuid UID
2112  
2113  =item getgrgid GID
2114  
2115  =item getservbyname NAME,PROTO
2116  
2117  =item gethostbyaddr ADDR,ADDRTYPE
2118  
2119  =item getnetbyaddr ADDR,ADDRTYPE
2120  
2121  =item getprotobynumber NUMBER
2122  
2123  =item getservbyport PORT,PROTO
2124  
2125  =item getpwent
2126  
2127  =item getgrent
2128  
2129  =item gethostent
2130  
2131  =item getnetent
2132  
2133  =item getprotoent
2134  
2135  =item getservent
2136  
2137  =item setpwent
2138  
2139  =item setgrent
2140  
2141  =item sethostent STAYOPEN
2142  
2143  =item setnetent STAYOPEN
2144  
2145  =item setprotoent STAYOPEN
2146  
2147  =item setservent STAYOPEN
2148  
2149  =item endpwent
2150  
2151  =item endgrent
2152  
2153  =item endhostent
2154  
2155  =item endnetent
2156  
2157  =item endprotoent
2158  
2159  =item endservent
2160  
2161  These routines perform the same functions as their counterparts in the
2162  system library.  In list context, the return values from the
2163  various get routines are as follows:
2164  
2165      ($name,$passwd,$uid,$gid,
2166         $quota,$comment,$gcos,$dir,$shell,$expire) = getpw*
2167      ($name,$passwd,$gid,$members) = getgr*
2168      ($name,$aliases,$addrtype,$length,@addrs) = gethost*
2169      ($name,$aliases,$addrtype,$net) = getnet*
2170      ($name,$aliases,$proto) = getproto*
2171      ($name,$aliases,$port,$proto) = getserv*
2172  
2173  (If the entry doesn't exist you get a null list.)
2174  
2175  The exact meaning of the $gcos field varies but it usually contains
2176  the real name of the user (as opposed to the login name) and other
2177  information pertaining to the user.  Beware, however, that in many
2178  system users are able to change this information and therefore it
2179  cannot be trusted and therefore the $gcos is tainted (see
2180  L<perlsec>).  The $passwd and $shell, user's encrypted password and
2181  login shell, are also tainted, because of the same reason.
2182  
2183  In scalar context, you get the name, unless the function was a
2184  lookup by name, in which case you get the other thing, whatever it is.
2185  (If the entry doesn't exist you get the undefined value.)  For example:
2186  
2187      $uid   = getpwnam($name);
2188      $name  = getpwuid($num);
2189      $name  = getpwent();
2190      $gid   = getgrnam($name);
2191      $name  = getgrgid($num);
2192      $name  = getgrent();
2193      #etc.
2194  
2195  In I<getpw*()> the fields $quota, $comment, and $expire are special
2196  cases in the sense that in many systems they are unsupported.  If the
2197  $quota is unsupported, it is an empty scalar.  If it is supported, it
2198  usually encodes the disk quota.  If the $comment field is unsupported,
2199  it is an empty scalar.  If it is supported it usually encodes some
2200  administrative comment about the user.  In some systems the $quota
2201  field may be $change or $age, fields that have to do with password
2202  aging.  In some systems the $comment field may be $class.  The $expire
2203  field, if present, encodes the expiration period of the account or the
2204  password.  For the availability and the exact meaning of these fields
2205  in your system, please consult your getpwnam(3) documentation and your
2206  F<pwd.h> file.  You can also find out from within Perl what your
2207  $quota and $comment fields mean and whether you have the $expire field
2208  by using the C<Config> module and the values C<d_pwquota>, C<d_pwage>,
2209  C<d_pwchange>, C<d_pwcomment>, and C<d_pwexpire>.  Shadow password
2210  files are only supported if your vendor has implemented them in the
2211  intuitive fashion that calling the regular C library routines gets the
2212  shadow versions if you're running under privilege or if there exists
2213  the shadow(3) functions as found in System V (this includes Solaris
2214  and Linux.)  Those systems that implement a proprietary shadow password
2215  facility are unlikely to be supported.
2216  
2217  The $members value returned by I<getgr*()> is a space separated list of
2218  the login names of the members of the group.
2219  
2220  For the I<gethost*()> functions, if the C<h_errno> variable is supported in
2221  C, it will be returned to you via C<$?> if the function call fails.  The
2222  C<@addrs> value returned by a successful call is a list of the raw
2223  addresses returned by the corresponding system library call.  In the
2224  Internet domain, each address is four bytes long and you can unpack it
2225  by saying something like:
2226  
2227      ($a,$b,$c,$d) = unpack('W4',$addr[0]);
2228  
2229  The Socket library makes this slightly easier:
2230  
2231      use Socket;
2232      $iaddr = inet_aton("127.1"); # or whatever address
2233      $name  = gethostbyaddr($iaddr, AF_INET);
2234  
2235      # or going the other way
2236      $straddr = inet_ntoa($iaddr);
2237  
2238  In the opposite way, to resolve a hostname to the IP address
2239  you can write this:
2240  
2241      use Socket;
2242      $packed_ip = gethostbyname("www.perl.org");
2243      if (defined $packed_ip) {
2244          $ip_address = inet_ntoa($packed_ip);
2245      }
2246  
2247  Make sure <gethostbyname()> is called in SCALAR context and that
2248  its return value is checked for definedness.
2249  
2250  If you get tired of remembering which element of the return list
2251  contains which return value, by-name interfaces are provided
2252  in standard modules: C<File::stat>, C<Net::hostent>, C<Net::netent>,
2253  C<Net::protoent>, C<Net::servent>, C<Time::gmtime>, C<Time::localtime>,
2254  and C<User::grent>.  These override the normal built-ins, supplying
2255  versions that return objects with the appropriate names
2256  for each field.  For example:
2257  
2258     use File::stat;
2259     use User::pwent;
2260     $is_his = (stat($filename)->uid == pwent($whoever)->uid);
2261  
2262  Even though it looks like they're the same method calls (uid),
2263  they aren't, because a C<File::stat> object is different from
2264  a C<User::pwent> object.
2265  
2266  =item getsockname SOCKET
2267  X<getsockname>
2268  
2269  Returns the packed sockaddr address of this end of the SOCKET connection,
2270  in case you don't know the address because you have several different
2271  IPs that the connection might have come in on.
2272  
2273      use Socket;
2274      $mysockaddr = getsockname(SOCK);
2275      ($port, $myaddr) = sockaddr_in($mysockaddr);
2276      printf "Connect to %s [%s]\n",
2277         scalar gethostbyaddr($myaddr, AF_INET),
2278         inet_ntoa($myaddr);
2279  
2280  =item getsockopt SOCKET,LEVEL,OPTNAME
2281  X<getsockopt>
2282  
2283  Queries the option named OPTNAME associated with SOCKET at a given LEVEL.
2284  Options may exist at multiple protocol levels depending on the socket
2285  type, but at least the uppermost socket level SOL_SOCKET (defined in the
2286  C<Socket> module) will exist. To query options at another level the
2287  protocol number of the appropriate protocol controlling the option
2288  should be supplied. For example, to indicate that an option is to be
2289  interpreted by the TCP protocol, LEVEL should be set to the protocol
2290  number of TCP, which you can get using getprotobyname.
2291  
2292  The call returns a packed string representing the requested socket option,
2293  or C<undef> if there is an error (the error reason will be in $!). What
2294  exactly is in the packed string depends in the LEVEL and OPTNAME, consult
2295  your system documentation for details. A very common case however is that
2296  the option is an integer, in which case the result will be a packed
2297  integer which you can decode using unpack with the C<i> (or C<I>) format.
2298  
2299  An example testing if Nagle's algorithm is turned on on a socket:
2300  
2301      use Socket qw(:all);
2302  
2303      defined(my $tcp = getprotobyname("tcp"))
2304      or die "Could not determine the protocol number for tcp";
2305      # my $tcp = IPPROTO_TCP; # Alternative
2306      my $packed = getsockopt($socket, $tcp, TCP_NODELAY)
2307      or die "Could not query TCP_NODELAY socket option: $!";
2308      my $nodelay = unpack("I", $packed);
2309      print "Nagle's algorithm is turned ", $nodelay ? "off\n" : "on\n";
2310  
2311  
2312  =item glob EXPR
2313  X<glob> X<wildcard> X<filename, expansion> X<expand>
2314  
2315  =item glob
2316  
2317  In list context, returns a (possibly empty) list of filename expansions on
2318  the value of EXPR such as the standard Unix shell F</bin/csh> would do. In
2319  scalar context, glob iterates through such filename expansions, returning
2320  undef when the list is exhausted. This is the internal function
2321  implementing the C<< <*.c> >> operator, but you can use it directly. If
2322  EXPR is omitted, C<$_> is used.  The C<< <*.c> >> operator is discussed in
2323  more detail in L<perlop/"I/O Operators">.
2324  
2325  Beginning with v5.6.0, this operator is implemented using the standard
2326  C<File::Glob> extension.  See L<File::Glob> for details.
2327  
2328  =item gmtime EXPR
2329  X<gmtime> X<UTC> X<Greenwich>
2330  
2331  =item gmtime
2332  
2333  Works just like L<localtime> but the returned values are
2334  localized for the standard Greenwich time zone.
2335  
2336  Note: when called in list context, $isdst, the last value
2337  returned by gmtime is always C<0>.  There is no
2338  Daylight Saving Time in GMT.
2339  
2340  See L<perlport/gmtime> for portability concerns.
2341  
2342  =item goto LABEL
2343  X<goto> X<jump> X<jmp>
2344  
2345  =item goto EXPR
2346  
2347  =item goto &NAME
2348  
2349  The C<goto-LABEL> form finds the statement labeled with LABEL and resumes
2350  execution there.  It may not be used to go into any construct that
2351  requires initialization, such as a subroutine or a C<foreach> loop.  It
2352  also can't be used to go into a construct that is optimized away,
2353  or to get out of a block or subroutine given to C<sort>.
2354  It can be used to go almost anywhere else within the dynamic scope,
2355  including out of subroutines, but it's usually better to use some other
2356  construct such as C<last> or C<die>.  The author of Perl has never felt the
2357  need to use this form of C<goto> (in Perl, that is--C is another matter).
2358  (The difference being that C does not offer named loops combined with
2359  loop control.  Perl does, and this replaces most structured uses of C<goto>
2360  in other languages.)
2361  
2362  The C<goto-EXPR> form expects a label name, whose scope will be resolved
2363  dynamically.  This allows for computed C<goto>s per FORTRAN, but isn't
2364  necessarily recommended if you're optimizing for maintainability:
2365  
2366      goto ("FOO", "BAR", "GLARCH")[$i];
2367  
2368  The C<goto-&NAME> form is quite different from the other forms of
2369  C<goto>.  In fact, it isn't a goto in the normal sense at all, and
2370  doesn't have the stigma associated with other gotos.  Instead, it
2371  exits the current subroutine (losing any changes set by local()) and
2372  immediately calls in its place the named subroutine using the current
2373  value of @_.  This is used by C<AUTOLOAD> subroutines that wish to
2374  load another subroutine and then pretend that the other subroutine had
2375  been called in the first place (except that any modifications to C<@_>
2376  in the current subroutine are propagated to the other subroutine.)
2377  After the C<goto>, not even C<caller> will be able to tell that this
2378  routine was called first.
2379  
2380  NAME needn't be the name of a subroutine; it can be a scalar variable
2381  containing a code reference, or a block that evaluates to a code
2382  reference.
2383  
2384  =item grep BLOCK LIST
2385  X<grep>
2386  
2387  =item grep EXPR,LIST
2388  
2389  This is similar in spirit to, but not the same as, grep(1) and its
2390  relatives.  In particular, it is not limited to using regular expressions.
2391  
2392  Evaluates the BLOCK or EXPR for each element of LIST (locally setting
2393  C<$_> to each element) and returns the list value consisting of those
2394  elements for which the expression evaluated to true.  In scalar
2395  context, returns the number of times the expression was true.
2396  
2397      @foo = grep(!/^#/, @bar);    # weed out comments
2398  
2399  or equivalently,
2400  
2401      @foo = grep {!/^#/} @bar;    # weed out comments
2402  
2403  Note that C<$_> is an alias to the list value, so it can be used to
2404  modify the elements of the LIST.  While this is useful and supported,
2405  it can cause bizarre results if the elements of LIST are not variables.
2406  Similarly, grep returns aliases into the original list, much as a for
2407  loop's index variable aliases the list elements.  That is, modifying an
2408  element of a list returned by grep (for example, in a C<foreach>, C<map>
2409  or another C<grep>) actually modifies the element in the original list.
2410  This is usually something to be avoided when writing clear code.
2411  
2412  If C<$_> is lexical in the scope where the C<grep> appears (because it has
2413  been declared with C<my $_>) then, in addition to being locally aliased to
2414  the list elements, C<$_> keeps being lexical inside the block; i.e. it
2415  can't be seen from the outside, avoiding any potential side-effects.
2416  
2417  See also L</map> for a list composed of the results of the BLOCK or EXPR.
2418  
2419  =item hex EXPR
2420  X<hex> X<hexadecimal>
2421  
2422  =item hex
2423  
2424  Interprets EXPR as a hex string and returns the corresponding value.
2425  (To convert strings that might start with either C<0>, C<0x>, or C<0b>, see
2426  L</oct>.)  If EXPR is omitted, uses C<$_>.
2427  
2428      print hex '0xAf'; # prints '175'
2429      print hex 'aF';   # same
2430  
2431  Hex strings may only represent integers.  Strings that would cause
2432  integer overflow trigger a warning.  Leading whitespace is not stripped,
2433  unlike oct(). To present something as hex, look into L</printf>,
2434  L</sprintf>, or L</unpack>.
2435  
2436  =item import LIST
2437  X<import>
2438  
2439  There is no builtin C<import> function.  It is just an ordinary
2440  method (subroutine) defined (or inherited) by modules that wish to export
2441  names to another module.  The C<use> function calls the C<import> method
2442  for the package used.  See also L</use>, L<perlmod>, and L<Exporter>.
2443  
2444  =item index STR,SUBSTR,POSITION
2445  X<index> X<indexOf> X<InStr>
2446  
2447  =item index STR,SUBSTR
2448  
2449  The index function searches for one string within another, but without
2450  the wildcard-like behavior of a full regular-expression pattern match.
2451  It returns the position of the first occurrence of SUBSTR in STR at
2452  or after POSITION.  If POSITION is omitted, starts searching from the
2453  beginning of the string.  POSITION before the beginning of the string
2454  or after its end is treated as if it were the beginning or the end,
2455  respectively.  POSITION and the return value are based at C<0> (or whatever
2456  you've set the C<$[> variable to--but don't do that).  If the substring
2457  is not found, C<index> returns one less than the base, ordinarily C<-1>.
2458  
2459  =item int EXPR
2460  X<int> X<integer> X<truncate> X<trunc> X<floor>
2461  
2462  =item int
2463  
2464  Returns the integer portion of EXPR.  If EXPR is omitted, uses C<$_>.
2465  You should not use this function for rounding: one because it truncates
2466  towards C<0>, and two because machine representations of floating point
2467  numbers can sometimes produce counterintuitive results.  For example,
2468  C<int(-6.725/0.025)> produces -268 rather than the correct -269; that's
2469  because it's really more like -268.99999999999994315658 instead.  Usually,
2470  the C<sprintf>, C<printf>, or the C<POSIX::floor> and C<POSIX::ceil>
2471  functions will serve you better than will int().
2472  
2473  =item ioctl FILEHANDLE,FUNCTION,SCALAR
2474  X<ioctl>
2475  
2476  Implements the ioctl(2) function.  You'll probably first have to say
2477  
2478      require "sys/ioctl.ph";    # probably in $Config{archlib}/sys/ioctl.ph
2479  
2480  to get the correct function definitions.  If F<sys/ioctl.ph> doesn't
2481  exist or doesn't have the correct definitions you'll have to roll your
2482  own, based on your C header files such as F<< <sys/ioctl.h> >>.
2483  (There is a Perl script called B<h2ph> that comes with the Perl kit that
2484  may help you in this, but it's nontrivial.)  SCALAR will be read and/or
2485  written depending on the FUNCTION--a pointer to the string value of SCALAR
2486  will be passed as the third argument of the actual C<ioctl> call.  (If SCALAR
2487  has no string value but does have a numeric value, that value will be
2488  passed rather than a pointer to the string value.  To guarantee this to be
2489  true, add a C<0> to the scalar before using it.)  The C<pack> and C<unpack>
2490  functions may be needed to manipulate the values of structures used by
2491  C<ioctl>.
2492  
2493  The return value of C<ioctl> (and C<fcntl>) is as follows:
2494  
2495      if OS returns:        then Perl returns:
2496          -1                undefined value
2497           0             string "0 but true"
2498      anything else            that number
2499  
2500  Thus Perl returns true on success and false on failure, yet you can
2501  still easily determine the actual value returned by the operating
2502  system:
2503  
2504      $retval = ioctl(...) || -1;
2505      printf "System returned %d\n", $retval;
2506  
2507  The special string C<"0 but true"> is exempt from B<-w> complaints
2508  about improper numeric conversions.
2509  
2510  =item join EXPR,LIST
2511  X<join>
2512  
2513  Joins the separate strings of LIST into a single string with fields
2514  separated by the value of EXPR, and returns that new string.  Example:
2515  
2516      $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
2517  
2518  Beware that unlike C<split>, C<join> doesn't take a pattern as its
2519  first argument.  Compare L</split>.
2520  
2521  =item keys HASH
2522  X<keys> X<key>
2523  
2524  Returns a list consisting of all the keys of the named hash.
2525  (In scalar context, returns the number of keys.)
2526  
2527  The keys are returned in an apparently random order.  The actual
2528  random order is subject to change in future versions of perl, but it
2529  is guaranteed to be the same order as either the C<values> or C<each>
2530  function produces (given that the hash has not been modified).  Since
2531  Perl 5.8.1 the ordering is different even between different runs of
2532  Perl for security reasons (see L<perlsec/"Algorithmic Complexity
2533  Attacks">).
2534  
2535  As a side effect, calling keys() resets the HASH's internal iterator
2536  (see L</each>).  In particular, calling keys() in void context resets
2537  the iterator with no other overhead.
2538  
2539  Here is yet another way to print your environment:
2540  
2541      @keys = keys %ENV;
2542      @values = values %ENV;
2543      while (@keys) {
2544      print pop(@keys), '=', pop(@values), "\n";
2545      }
2546  
2547  or how about sorted by key:
2548  
2549      foreach $key (sort(keys %ENV)) {
2550      print $key, '=', $ENV{$key}, "\n";
2551      }
2552  
2553  The returned values are copies of the original keys in the hash, so
2554  modifying them will not affect the original hash.  Compare L</values>.
2555  
2556  To sort a hash by value, you'll need to use a C<sort> function.
2557  Here's a descending numeric sort of a hash by its values:
2558  
2559      foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
2560      printf "%4d %s\n", $hash{$key}, $key;
2561      }
2562  
2563  As an lvalue C<keys> allows you to increase the number of hash buckets
2564  allocated for the given hash.  This can gain you a measure of efficiency if
2565  you know the hash is going to get big.  (This is similar to pre-extending
2566  an array by assigning a larger number to $#array.)  If you say
2567  
2568      keys %hash = 200;
2569  
2570  then C<%hash> will have at least 200 buckets allocated for it--256 of them,
2571  in fact, since it rounds up to the next power of two.  These
2572  buckets will be retained even if you do C<%hash = ()>, use C<undef
2573  %hash> if you want to free the storage while C<%hash> is still in scope.
2574  You can't shrink the number of buckets allocated for the hash using
2575  C<keys> in this way (but you needn't worry about doing this by accident,
2576  as trying has no effect).
2577  
2578  See also C<each>, C<values> and C<sort>.
2579  
2580  =item kill SIGNAL, LIST
2581  X<kill> X<signal>
2582  
2583  Sends a signal to a list of processes.  Returns the number of
2584  processes successfully signaled (which is not necessarily the
2585  same as the number actually killed).
2586  
2587      $cnt = kill 1, $child1, $child2;
2588      kill 9, @goners;
2589  
2590  If SIGNAL is zero, no signal is sent to the process, but the kill(2)
2591  system call will check whether it's possible to send a signal to it (that
2592  means, to be brief, that the process is owned by the same user, or we are
2593  the super-user).  This is a useful way to check that a child process is
2594  alive (even if only as a zombie) and hasn't changed its UID.  See
2595  L<perlport> for notes on the portability of this construct.
2596  
2597  Unlike in the shell, if SIGNAL is negative, it kills
2598  process groups instead of processes.  (On System V, a negative I<PROCESS>
2599  number will also kill process groups, but that's not portable.)  That
2600  means you usually want to use positive not negative signals.  You may also
2601  use a signal name in quotes.
2602  
2603  See L<perlipc/"Signals"> for more details.
2604  
2605  =item last LABEL
2606  X<last> X<break>
2607  
2608  =item last
2609  
2610  The C<last> command is like the C<break> statement in C (as used in
2611  loops); it immediately exits the loop in question.  If the LABEL is
2612  omitted, the command refers to the innermost enclosing loop.  The
2613  C<continue> block, if any, is not executed:
2614  
2615      LINE: while (<STDIN>) {
2616      last LINE if /^$/;    # exit when done with header
2617      #...
2618      }
2619  
2620  C<last> cannot be used to exit a block which returns a value such as
2621  C<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit
2622  a grep() or map() operation.
2623  
2624  Note that a block by itself is semantically identical to a loop
2625  that executes once.  Thus C<last> can be used to effect an early
2626  exit out of such a block.
2627  
2628  See also L</continue> for an illustration of how C<last>, C<next>, and
2629  C<redo> work.
2630  
2631  =item lc EXPR
2632  X<lc> X<lowercase>
2633  
2634  =item lc
2635  
2636  Returns a lowercased version of EXPR.  This is the internal function
2637  implementing the C<\L> escape in double-quoted strings.  Respects
2638  current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>
2639  and L<perlunicode> for more details about locale and Unicode support.
2640  
2641  If EXPR is omitted, uses C<$_>.
2642  
2643  =item lcfirst EXPR
2644  X<lcfirst> X<lowercase>
2645  
2646  =item lcfirst
2647  
2648  Returns the value of EXPR with the first character lowercased.  This
2649  is the internal function implementing the C<\l> escape in
2650  double-quoted strings.  Respects current LC_CTYPE locale if C<use
2651  locale> in force.  See L<perllocale> and L<perlunicode> for more
2652  details about locale and Unicode support.
2653  
2654  If EXPR is omitted, uses C<$_>.
2655  
2656  =item length EXPR
2657  X<length> X<size>
2658  
2659  =item length
2660  
2661  Returns the length in I<characters> of the value of EXPR.  If EXPR is
2662  omitted, returns length of C<$_>.  Note that this cannot be used on
2663  an entire array or hash to find out how many elements these have.
2664  For that, use C<scalar @array> and C<scalar keys %hash> respectively.
2665  
2666  Note the I<characters>: if the EXPR is in Unicode, you will get the
2667  number of characters, not the number of bytes.  To get the length
2668  of the internal string in bytes, use C<bytes::length(EXPR)>, see
2669  L<bytes>.  Note that the internal encoding is variable, and the number
2670  of bytes usually meaningless.  To get the number of bytes that the
2671  string would have when encoded as UTF-8, use
2672  C<length(Encoding::encode_utf8(EXPR))>.
2673  
2674  =item link OLDFILE,NEWFILE
2675  X<link>
2676  
2677  Creates a new filename linked to the old filename.  Returns true for
2678  success, false otherwise.
2679  
2680  =item listen SOCKET,QUEUESIZE
2681  X<listen>
2682  
2683  Does the same thing that the listen system call does.  Returns true if
2684  it succeeded, false otherwise.  See the example in
2685  L<perlipc/"Sockets: Client/Server Communication">.
2686  
2687  =item local EXPR
2688  X<local>
2689  
2690  You really probably want to be using C<my> instead, because C<local> isn't
2691  what most people think of as "local".  See
2692  L<perlsub/"Private Variables via my()"> for details.
2693  
2694  A local modifies the listed variables to be local to the enclosing
2695  block, file, or eval.  If more than one value is listed, the list must
2696  be placed in parentheses.  See L<perlsub/"Temporary Values via local()">
2697  for details, including issues with tied arrays and hashes.
2698  
2699  =item localtime EXPR
2700  X<localtime> X<ctime>
2701  
2702  =item localtime
2703  
2704  Converts a time as returned by the time function to a 9-element list
2705  with the time analyzed for the local time zone.  Typically used as
2706  follows:
2707  
2708      #  0    1    2     3     4    5     6     7     8
2709      ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
2710                                                  localtime(time);
2711  
2712  All list elements are numeric, and come straight out of the C `struct
2713  tm'.  C<$sec>, C<$min>, and C<$hour> are the seconds, minutes, and hours
2714  of the specified time.
2715  
2716  C<$mday> is the day of the month, and C<$mon> is the month itself, in
2717  the range C<0..11> with 0 indicating January and 11 indicating December.
2718  This makes it easy to get a month name from a list:
2719  
2720      my @abbr = qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec );
2721      print "$abbr[$mon] $mday";
2722      # $mon=9, $mday=18 gives "Oct 18"
2723  
2724  C<$year> is the number of years since 1900, not just the last two digits
2725  of the year.  That is, C<$year> is C<123> in year 2023.  The proper way
2726  to get a complete 4-digit year is simply:
2727  
2728      $year += 1900;
2729  
2730  Otherwise you create non-Y2K-compliant programs--and you wouldn't want
2731  to do that, would you?
2732  
2733  To get the last two digits of the year (e.g., '01' in 2001) do:
2734  
2735      $year = sprintf("%02d", $year % 100);
2736  
2737  C<$wday> is the day of the week, with 0 indicating Sunday and 3 indicating
2738  Wednesday.  C<$yday> is the day of the year, in the range C<0..364>
2739  (or C<0..365> in leap years.)
2740  
2741  C<$isdst> is true if the specified time occurs during Daylight Saving
2742  Time, false otherwise.
2743  
2744  If EXPR is omitted, C<localtime()> uses the current time (C<localtime(time)>).
2745  
2746  In scalar context, C<localtime()> returns the ctime(3) value:
2747  
2748      $now_string = localtime;  # e.g., "Thu Oct 13 04:54:34 1994"
2749  
2750  This scalar value is B<not> locale dependent but is a Perl builtin. For GMT
2751  instead of local time use the L</gmtime> builtin. See also the
2752  C<Time::Local> module (to convert the second, minutes, hours, ... back to
2753  the integer value returned by time()), and the L<POSIX> module's strftime(3)
2754  and mktime(3) functions.
2755  
2756  To get somewhat similar but locale dependent date strings, set up your
2757  locale environment variables appropriately (please see L<perllocale>) and
2758  try for example:
2759  
2760      use POSIX qw(strftime);
2761      $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
2762      # or for GMT formatted appropriately for your locale:
2763      $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
2764  
2765  Note that the C<%a> and C<%b>, the short forms of the day of the week
2766  and the month of the year, may not necessarily be three characters wide.
2767  
2768  See L<perlport/localtime> for portability concerns.
2769  
2770  The L<Time::gmtime> and L<Time::localtime> modules provides a convenient,
2771  by-name access mechanism to the gmtime() and localtime() functions,
2772  respectively.
2773  
2774  For a comprehensive date and time representation look at the
2775  L<DateTime> module on CPAN.
2776  
2777  =item lock THING
2778  X<lock>
2779  
2780  This function places an advisory lock on a shared variable, or referenced
2781  object contained in I<THING> until the lock goes out of scope.
2782  
2783  lock() is a "weak keyword" : this means that if you've defined a function
2784  by this name (before any calls to it), that function will be called
2785  instead. (However, if you've said C<use threads>, lock() is always a
2786  keyword.) See L<threads>.
2787  
2788  =item log EXPR
2789  X<log> X<logarithm> X<e> X<ln> X<base>
2790  
2791  =item log
2792  
2793  Returns the natural logarithm (base I<e>) of EXPR.  If EXPR is omitted,
2794  returns log of C<$_>.  To get the log of another base, use basic algebra:
2795  The base-N log of a number is equal to the natural log of that number
2796  divided by the natural log of N.  For example:
2797  
2798      sub log10 {
2799      my $n = shift;
2800      return log($n)/log(10);
2801      }
2802  
2803  See also L</exp> for the inverse operation.
2804  
2805  =item lstat EXPR
2806  X<lstat>
2807  
2808  =item lstat
2809  
2810  Does the same thing as the C<stat> function (including setting the
2811  special C<_> filehandle) but stats a symbolic link instead of the file
2812  the symbolic link points to.  If symbolic links are unimplemented on
2813  your system, a normal C<stat> is done.  For much more detailed
2814  information, please see the documentation for C<stat>.
2815  
2816  If EXPR is omitted, stats C<$_>.
2817  
2818  =item m//
2819  
2820  The match operator.  See L<perlop>.
2821  
2822  =item map BLOCK LIST
2823  X<map>
2824  
2825  =item map EXPR,LIST
2826  
2827  Evaluates the BLOCK or EXPR for each element of LIST (locally setting
2828  C<$_> to each element) and returns the list value composed of the
2829  results of each such evaluation.  In scalar context, returns the
2830  total number of elements so generated.  Evaluates BLOCK or EXPR in
2831  list context, so each element of LIST may produce zero, one, or
2832  more elements in the returned value.
2833  
2834      @chars = map(chr, @nums);
2835  
2836  translates a list of numbers to the corresponding characters.  And
2837  
2838      %hash = map { get_a_key_for($_) => $_ } @array;
2839  
2840  is just a funny way to write
2841  
2842      %hash = ();
2843      foreach (@array) {
2844      $hash{get_a_key_for($_)} = $_;
2845      }
2846  
2847  Note that C<$_> is an alias to the list value, so it can be used to
2848  modify the elements of the LIST.  While this is useful and supported,
2849  it can cause bizarre results if the elements of LIST are not variables.
2850  Using a regular C<foreach> loop for this purpose would be clearer in
2851  most cases.  See also L</grep> for an array composed of those items of
2852  the original list for which the BLOCK or EXPR evaluates to true.
2853  
2854  If C<$_> is lexical in the scope where the C<map> appears (because it has
2855  been declared with C<my $_>), then, in addition to being locally aliased to
2856  the list elements, C<$_> keeps being lexical inside the block; that is, it
2857  can't be seen from the outside, avoiding any potential side-effects.
2858  
2859  C<{> starts both hash references and blocks, so C<map { ...> could be either
2860  the start of map BLOCK LIST or map EXPR, LIST. Because perl doesn't look
2861  ahead for the closing C<}> it has to take a guess at which its dealing with
2862  based what it finds just after the C<{>. Usually it gets it right, but if it
2863  doesn't it won't realize something is wrong until it gets to the C<}> and
2864  encounters the missing (or unexpected) comma. The syntax error will be
2865  reported close to the C<}> but you'll need to change something near the C<{>
2866  such as using a unary C<+> to give perl some help:
2867  
2868      %hash = map {  "\L$_", 1  } @array  # perl guesses EXPR.  wrong
2869      %hash = map { +"\L$_", 1  } @array  # perl guesses BLOCK. right
2870      %hash = map { ("\L$_", 1) } @array  # this also works
2871      %hash = map {  lc($_), 1  } @array  # as does this.
2872      %hash = map +( lc($_), 1 ), @array  # this is EXPR and works!
2873  
2874      %hash = map  ( lc($_), 1 ), @array  # evaluates to (1, @array)
2875  
2876  or to force an anon hash constructor use C<+{>:
2877  
2878     @hashes = map +{ lc($_), 1 }, @array # EXPR, so needs , at end
2879  
2880  and you get list of anonymous hashes each with only 1 entry.
2881  
2882  =item mkdir FILENAME,MASK
2883  X<mkdir> X<md> X<directory, create>
2884  
2885  =item mkdir FILENAME
2886  
2887  =item mkdir
2888  
2889  Creates the directory specified by FILENAME, with permissions
2890  specified by MASK (as modified by C<umask>).  If it succeeds it
2891  returns true, otherwise it returns false and sets C<$!> (errno).
2892  If omitted, MASK defaults to 0777. If omitted, FILENAME defaults
2893  to C<$_>.
2894  
2895  In general, it is better to create directories with permissive MASK,
2896  and let the user modify that with their C<umask>, than it is to supply
2897  a restrictive MASK and give the user no way to be more permissive.
2898  The exceptions to this rule are when the file or directory should be
2899  kept private (mail files, for instance).  The perlfunc(1) entry on
2900  C<umask> discusses the choice of MASK in more detail.
2901  
2902  Note that according to the POSIX 1003.1-1996 the FILENAME may have any
2903  number of trailing slashes.  Some operating and filesystems do not get
2904  this right, so Perl automatically removes all trailing slashes to keep
2905  everyone happy.
2906  
2907  In order to recursively create a directory structure look at
2908  the C<mkpath> function of the L<File::Path> module.
2909  
2910  =item msgctl ID,CMD,ARG
2911  X<msgctl>
2912  
2913  Calls the System V IPC function msgctl(2).  You'll probably have to say
2914  
2915      use IPC::SysV;
2916  
2917  first to get the correct constant definitions.  If CMD is C<IPC_STAT>,
2918  then ARG must be a variable that will hold the returned C<msqid_ds>
2919  structure.  Returns like C<ioctl>: the undefined value for error,
2920  C<"0 but true"> for zero, or the actual return value otherwise.  See also
2921  L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::Semaphore> documentation.
2922  
2923  =item msgget KEY,FLAGS
2924  X<msgget>
2925  
2926  Calls the System V IPC function msgget(2).  Returns the message queue
2927  id, or the undefined value if there is an error.  See also
2928  L<perlipc/"SysV IPC"> and C<IPC::SysV> and C<IPC::Msg> documentation.
2929  
2930  =item msgrcv ID,VAR,SIZE,TYPE,FLAGS
2931  X<msgrcv>
2932  
2933  Calls the System V IPC function msgrcv to receive a message from
2934  message queue ID into variable VAR with a maximum message size of
2935  SIZE.  Note that when a message is received, the message type as a
2936  native long integer will be the first thing in VAR, followed by the
2937  actual message.  This packing may be opened with C<unpack("l! a*")>.
2938  Taints the variable.  Returns true if successful, or false if there is
2939  an error.  See also L<perlipc/"SysV IPC">, C<IPC::SysV>, and
2940  C<IPC::SysV::Msg> documentation.
2941  
2942  =item msgsnd ID,MSG,FLAGS
2943  X<msgsnd>
2944  
2945  Calls the System V IPC function msgsnd to send the message MSG to the
2946  message queue ID.  MSG must begin with the native long integer message
2947  type, and be followed by the length of the actual message, and finally
2948  the message itself.  This kind of packing can be achieved with
2949  C<pack("l! a*", $type, $message)>.  Returns true if successful,
2950  or false if there is an error.  See also C<IPC::SysV>
2951  and C<IPC::SysV::Msg> documentation.
2952  
2953  =item my EXPR
2954  X<my>
2955  
2956  =item my TYPE EXPR
2957  
2958  =item my EXPR : ATTRS
2959  
2960  =item my TYPE EXPR : ATTRS
2961  
2962  A C<my> declares the listed variables to be local (lexically) to the
2963  enclosing block, file, or C<eval>.  If more than one value is listed,
2964  the list must be placed in parentheses.
2965  
2966  The exact semantics and interface of TYPE and ATTRS are still
2967  evolving.  TYPE is currently bound to the use of C<fields> pragma,
2968  and attributes are handled using the C<attributes> pragma, or starting
2969  from Perl 5.8.0 also via the C<Attribute::Handlers> module.  See
2970  L<perlsub/"Private Variables via my()"> for details, and L<fields>,
2971  L<attributes>, and L<Attribute::Handlers>.
2972  
2973  =item next LABEL
2974  X<next> X<continue>
2975  
2976  =item next
2977  
2978  The C<next> command is like the C<continue> statement in C; it starts
2979  the next iteration of the loop:
2980  
2981      LINE: while (<STDIN>) {
2982      next LINE if /^#/;    # discard comments
2983      #...
2984      }
2985  
2986  Note that if there were a C<continue> block on the above, it would get
2987  executed even on discarded lines.  If the LABEL is omitted, the command
2988  refers to the innermost enclosing loop.
2989  
2990  C<next> cannot be used to exit a block which returns a value such as
2991  C<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit
2992  a grep() or map() operation.
2993  
2994  Note that a block by itself is semantically identical to a loop
2995  that executes once.  Thus C<next> will exit such a block early.
2996  
2997  See also L</continue> for an illustration of how C<last>, C<next>, and
2998  C<redo> work.
2999  
3000  =item no Module VERSION LIST
3001  X<no>
3002  
3003  =item no Module VERSION
3004  
3005  =item no Module LIST
3006  
3007  =item no Module
3008  
3009  =item no VERSION
3010  
3011  See the C<use> function, of which C<no> is the opposite.
3012  
3013  =item oct EXPR
3014  X<oct> X<octal> X<hex> X<hexadecimal> X<binary> X<bin>
3015  
3016  =item oct
3017  
3018  Interprets EXPR as an octal string and returns the corresponding
3019  value.  (If EXPR happens to start off with C<0x>, interprets it as a
3020  hex string.  If EXPR starts off with C<0b>, it is interpreted as a
3021  binary string.  Leading whitespace is ignored in all three cases.)
3022  The following will handle decimal, binary, octal, and hex in the standard
3023  Perl or C notation:
3024  
3025      $val = oct($val) if $val =~ /^0/;
3026  
3027  If EXPR is omitted, uses C<$_>.   To go the other way (produce a number
3028  in octal), use sprintf() or printf():
3029  
3030      $perms = (stat("filename"))[2] & 07777;
3031      $oct_perms = sprintf "%lo", $perms;
3032  
3033  The oct() function is commonly used when a string such as C<644> needs
3034  to be converted into a file mode, for example. (Although perl will
3035  automatically convert strings into numbers as needed, this automatic
3036  conversion assumes base 10.)
3037  
3038  =item open FILEHANDLE,EXPR
3039  X<open> X<pipe> X<file, open> X<fopen>
3040  
3041  =item open FILEHANDLE,MODE,EXPR
3042  
3043  =item open FILEHANDLE,MODE,EXPR,LIST
3044  
3045  =item open FILEHANDLE,MODE,REFERENCE
3046  
3047  =item open FILEHANDLE
3048  
3049  Opens the file whose filename is given by EXPR, and associates it with
3050  FILEHANDLE.
3051  
3052  (The following is a comprehensive reference to open(): for a gentler
3053  introduction you may consider L<perlopentut>.)
3054  
3055  If FILEHANDLE is an undefined scalar variable (or array or hash element)
3056  the variable is assigned a reference to a new anonymous filehandle,
3057  otherwise if FILEHANDLE is an expression, its value is used as the name of
3058  the real filehandle wanted.  (This is considered a symbolic reference, so
3059  C<use strict 'refs'> should I<not> be in effect.)
3060  
3061  If EXPR is omitted, the scalar variable of the same name as the
3062  FILEHANDLE contains the filename.  (Note that lexical variables--those
3063  declared with C<my>--will not work for this purpose; so if you're
3064  using C<my>, specify EXPR in your call to open.)
3065  
3066  If three or more arguments are specified then the mode of opening and
3067  the file name are separate. If MODE is C<< '<' >> or nothing, the file
3068  is opened for input.  If MODE is C<< '>' >>, the file is truncated and
3069  opened for output, being created if necessary.  If MODE is C<<< '>>' >>>,
3070  the file is opened for appending, again being created if necessary.
3071  
3072  You can put a C<'+'> in front of the C<< '>' >> or C<< '<' >> to
3073  indicate that you want both read and write access to the file; thus
3074  C<< '+<' >> is almost always preferred for read/write updates--the C<<
3075  '+>' >> mode would clobber the file first.  You can't usually use
3076  either read-write mode for updating textfiles, since they have
3077  variable length records.  See the B<-i> switch in L<perlrun> for a
3078  better approach.  The file is created with permissions of C<0666>
3079  modified by the process' C<umask> value.
3080  
3081  These various prefixes correspond to the fopen(3) modes of C<'r'>,
3082  C<'r+'>, C<'w'>, C<'w+'>, C<'a'>, and C<'a+'>.
3083  
3084  In the 2-arguments (and 1-argument) form of the call the mode and
3085  filename should be concatenated (in this order), possibly separated by
3086  spaces.  It is possible to omit the mode in these forms if the mode is
3087  C<< '<' >>.
3088  
3089  If the filename begins with C<'|'>, the filename is interpreted as a
3090  command to which output is to be piped, and if the filename ends with a
3091  C<'|'>, the filename is interpreted as a command which pipes output to
3092  us.  See L<perlipc/"Using open() for IPC">
3093  for more examples of this.  (You are not allowed to C<open> to a command
3094  that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>,
3095  and L<perlipc/"Bidirectional Communication with Another Process">
3096  for alternatives.)
3097  
3098  For three or more arguments if MODE is C<'|-'>, the filename is
3099  interpreted as a command to which output is to be piped, and if MODE
3100  is C<'-|'>, the filename is interpreted as a command which pipes
3101  output to us.  In the 2-arguments (and 1-argument) form one should
3102  replace dash (C<'-'>) with the command.
3103  See L<perlipc/"Using open() for IPC"> for more examples of this.
3104  (You are not allowed to C<open> to a command that pipes both in I<and>
3105  out, but see L<IPC::Open2>, L<IPC::Open3>, and
3106  L<perlipc/"Bidirectional Communication"> for alternatives.)
3107  
3108  In the three-or-more argument form of pipe opens, if LIST is specified
3109  (extra arguments after the command name) then LIST becomes arguments
3110  to the command invoked if the platform supports it.  The meaning of
3111  C<open> with more than three arguments for non-pipe modes is not yet
3112  specified. Experimental "layers" may give extra LIST arguments
3113  meaning.
3114  
3115  In the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN
3116  and opening C<< '>-' >> opens STDOUT.
3117  
3118  You may use the three-argument form of open to specify IO "layers"
3119  (sometimes also referred to as "disciplines") to be applied to the handle
3120  that affect how the input and output are processed (see L<open> and
3121  L<PerlIO> for more details). For example
3122  
3123    open(FH, "<:encoding(UTF-8)", "file")
3124  
3125  will open the UTF-8 encoded file containing Unicode characters,
3126  see L<perluniintro>. Note that if layers are specified in the
3127  three-arg form then default layers stored in ${^OPEN} (see L<perlvar>;
3128  usually set by the B<open> pragma or the switch B<-CioD>) are ignored.
3129  
3130  Open returns nonzero upon success, the undefined value otherwise.  If
3131  the C<open> involved a pipe, the return value happens to be the pid of
3132  the subprocess.
3133  
3134  If you're running Perl on a system that distinguishes between text
3135  files and binary files, then you should check out L</binmode> for tips
3136  for dealing with this.  The key distinction between systems that need
3137  C<binmode> and those that don't is their text file formats.  Systems
3138  like Unix, Mac OS, and Plan 9, which delimit lines with a single
3139  character, and which encode that character in C as C<"\n">, do not
3140  need C<binmode>.  The rest need it.
3141  
3142  When opening a file, it's usually a bad idea to continue normal execution
3143  if the request failed, so C<open> is frequently used in connection with
3144  C<die>.  Even if C<die> won't do what you want (say, in a CGI script,
3145  where you want to make a nicely formatted error message (but there are
3146  modules that can help with that problem)) you should always check
3147  the return value from opening a file.  The infrequent exception is when
3148  working with an unopened filehandle is actually what you want to do.
3149  
3150  As a special case the 3-arg form with a read/write mode and the third
3151  argument being C<undef>:
3152  
3153      open(TMP, "+>", undef) or die ...
3154  
3155  opens a filehandle to an anonymous temporary file.  Also using "+<"
3156  works for symmetry, but you really should consider writing something
3157  to the temporary file first.  You will need to seek() to do the
3158  reading.
3159  
3160  Since v5.8.0, perl has built using PerlIO by default.  Unless you've
3161  changed this (i.e. Configure -Uuseperlio), you can open file handles to
3162  "in memory" files held in Perl scalars via:
3163  
3164      open($fh, '>', \$variable) || ..
3165  
3166  Though if you try to re-open C<STDOUT> or C<STDERR> as an "in memory"
3167  file, you have to close it first:
3168  
3169      close STDOUT;
3170      open STDOUT, '>', \$variable or die "Can't open STDOUT: $!";
3171  
3172  Examples:
3173  
3174      $ARTICLE = 100;
3175      open ARTICLE or die "Can't find article $ARTICLE: $!\n";
3176      while (<ARTICLE>) {...
3177  
3178      open(LOG, '>>/usr/spool/news/twitlog');    # (log is reserved)
3179      # if the open fails, output is discarded
3180  
3181      open(DBASE, '+<', 'dbase.mine')        # open for update
3182      or die "Can't open 'dbase.mine' for update: $!";
3183  
3184      open(DBASE, '+<dbase.mine')            # ditto
3185      or die "Can't open 'dbase.mine' for update: $!";
3186  
3187      open(ARTICLE, '-|', "caesar <$article")     # decrypt article
3188      or die "Can't start caesar: $!";
3189  
3190      open(ARTICLE, "caesar <$article |")        # ditto
3191      or die "Can't start caesar: $!";
3192  
3193      open(EXTRACT, "|sort >Tmp$$")        # $$ is our process id
3194      or die "Can't start sort: $!";
3195  
3196      # in memory files
3197      open(MEMORY,'>', \$var)
3198      or die "Can't open memory file: $!";
3199      print MEMORY "foo!\n";            # output will end up in $var
3200  
3201      # process argument list of files along with any includes
3202  
3203      foreach $file (@ARGV) {
3204      process($file, 'fh00');
3205      }
3206  
3207      sub process {
3208      my($filename, $input) = @_;
3209      $input++;        # this is a string increment
3210      unless (open($input, $filename)) {
3211          print STDERR "Can't open $filename: $!\n";
3212          return;
3213      }
3214  
3215      local $_;
3216      while (<$input>) {        # note use of indirection
3217          if (/^#include "(.*)"/) {
3218          process($1, $input);
3219          next;
3220          }
3221          #...        # whatever
3222      }
3223      }
3224  
3225  See L<perliol> for detailed info on PerlIO.
3226  
3227  You may also, in the Bourne shell tradition, specify an EXPR beginning
3228  with C<< '>&' >>, in which case the rest of the string is interpreted
3229  as the name of a filehandle (or file descriptor, if numeric) to be
3230  duped (as L<dup(2)>) and opened.  You may use C<&> after C<< > >>,
3231  C<<< >> >>>, C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>.
3232  The mode you specify should match the mode of the original filehandle.
3233  (Duping a filehandle does not take into account any existing contents
3234  of IO buffers.) If you use the 3-arg form then you can pass either a
3235  number, the name of a filehandle or the normal "reference to a glob".
3236  
3237  Here is a script that saves, redirects, and restores C<STDOUT> and
3238  C<STDERR> using various methods:
3239  
3240      #!/usr/bin/perl
3241      open my $oldout, ">&STDOUT"     or die "Can't dup STDOUT: $!";
3242      open OLDERR,     ">&", \*STDERR or die "Can't dup STDERR: $!";
3243  
3244      open STDOUT, '>', "foo.out" or die "Can't redirect STDOUT: $!";
3245      open STDERR, ">&STDOUT"     or die "Can't dup STDOUT: $!";
3246  
3247      select STDERR; $| = 1;    # make unbuffered
3248      select STDOUT; $| = 1;    # make unbuffered
3249  
3250      print STDOUT "stdout 1\n";    # this works for
3251      print STDERR "stderr 1\n";     # subprocesses too
3252  
3253      open STDOUT, ">&", $oldout or die "Can't dup \$oldout: $!";
3254      open STDERR, ">&OLDERR"    or die "Can't dup OLDERR: $!";
3255  
3256      print STDOUT "stdout 2\n";
3257      print STDERR "stderr 2\n";
3258  
3259  If you specify C<< '<&=X' >>, where C<X> is a file descriptor number
3260  or a filehandle, then Perl will do an equivalent of C's C<fdopen> of
3261  that file descriptor (and not call L<dup(2)>); this is more
3262  parsimonious of file descriptors.  For example:
3263  
3264      # open for input, reusing the fileno of $fd
3265      open(FILEHANDLE, "<&=$fd")
3266  
3267  or
3268  
3269      open(FILEHANDLE, "<&=", $fd)
3270  
3271  or
3272  
3273      # open for append, using the fileno of OLDFH
3274      open(FH, ">>&=", OLDFH)
3275  
3276  or
3277  
3278      open(FH, ">>&=OLDFH")
3279  
3280  Being parsimonious on filehandles is also useful (besides being
3281  parsimonious) for example when something is dependent on file
3282  descriptors, like for example locking using flock().  If you do just
3283  C<< open(A, '>>&B') >>, the filehandle A will not have the same file
3284  descriptor as B, and therefore flock(A) will not flock(B), and vice
3285  versa.  But with C<< open(A, '>>&=B') >> the filehandles will share
3286  the same file descriptor.
3287  
3288  Note that if you are using Perls older than 5.8.0, Perl will be using
3289  the standard C libraries' fdopen() to implement the "=" functionality.
3290  On many UNIX systems fdopen() fails when file descriptors exceed a
3291  certain value, typically 255.  For Perls 5.8.0 and later, PerlIO is
3292  most often the default.
3293  
3294  You can see whether Perl has been compiled with PerlIO or not by
3295  running C<perl -V> and looking for C<useperlio=> line.  If C<useperlio>
3296  is C<define>, you have PerlIO, otherwise you don't.
3297  
3298  If you open a pipe on the command C<'-'>, i.e., either C<'|-'> or C<'-|'>
3299  with 2-arguments (or 1-argument) form of open(), then
3300  there is an implicit fork done, and the return value of open is the pid
3301  of the child within the parent process, and C<0> within the child
3302  process.  (Use C<defined($pid)> to determine whether the open was successful.)
3303  The filehandle behaves normally for the parent, but i/o to that
3304  filehandle is piped from/to the STDOUT/STDIN of the child process.
3305  In the child process the filehandle isn't opened--i/o happens from/to
3306  the new STDOUT or STDIN.  Typically this is used like the normal
3307  piped open when you want to exercise more control over just how the
3308  pipe command gets executed, such as when you are running setuid, and
3309  don't want to have to scan shell commands for metacharacters.
3310  The following triples are more or less equivalent:
3311  
3312      open(FOO, "|tr '[a-z]' '[A-Z]'");
3313      open(FOO, '|-', "tr '[a-z]' '[A-Z]'");
3314      open(FOO, '|-') || exec 'tr', '[a-z]', '[A-Z]';
3315      open(FOO, '|-', "tr", '[a-z]', '[A-Z]');
3316  
3317      open(FOO, "cat -n '$file'|");
3318      open(FOO, '-|', "cat -n '$file'");
3319      open(FOO, '-|') || exec 'cat', '-n', $file;
3320      open(FOO, '-|', "cat", '-n', $file);
3321  
3322  The last example in each block shows the pipe as "list form", which is
3323  not yet supported on all platforms.  A good rule of thumb is that if
3324  your platform has true C<fork()> (in other words, if your platform is
3325  UNIX) you can use the list form.
3326  
3327  See L<perlipc/"Safe Pipe Opens"> for more examples of this.
3328  
3329  Beginning with v5.6.0, Perl will attempt to flush all files opened for
3330  output before any operation that may do a fork, but this may not be
3331  supported on some platforms (see L<perlport>).  To be safe, you may need
3332  to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
3333  of C<IO::Handle> on any open handles.
3334  
3335  On systems that support a close-on-exec flag on files, the flag will
3336  be set for the newly opened file descriptor as determined by the value
3337  of $^F.  See L<perlvar/$^F>.
3338  
3339  Closing any piped filehandle causes the parent process to wait for the
3340  child to finish, and returns the status value in C<$?> and
3341  C<${^CHILD_ERROR_NATIVE}>.
3342  
3343  The filename passed to 2-argument (or 1-argument) form of open() will
3344  have leading and trailing whitespace deleted, and the normal
3345  redirection characters honored.  This property, known as "magic open",
3346  can often be used to good effect.  A user could specify a filename of
3347  F<"rsh cat file |">, or you could change certain filenames as needed:
3348  
3349      $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
3350      open(FH, $filename) or die "Can't open $filename: $!";
3351  
3352  Use 3-argument form to open a file with arbitrary weird characters in it,
3353  
3354      open(FOO, '<', $file);
3355  
3356  otherwise it's necessary to protect any leading and trailing whitespace:
3357  
3358      $file =~ s#^(\s)#./$1#;
3359      open(FOO, "< $file\0");
3360  
3361  (this may not work on some bizarre filesystems).  One should
3362  conscientiously choose between the I<magic> and 3-arguments form
3363  of open():
3364  
3365      open IN, $ARGV[0];
3366  
3367  will allow the user to specify an argument of the form C<"rsh cat file |">,
3368  but will not work on a filename which happens to have a trailing space, while
3369  
3370      open IN, '<', $ARGV[0];
3371  
3372  will have exactly the opposite restrictions.
3373  
3374  If you want a "real" C C<open> (see L<open(2)> on your system), then you
3375  should use the C<sysopen> function, which involves no such magic (but
3376  may use subtly different filemodes than Perl open(), which is mapped
3377  to C fopen()).  This is
3378  another way to protect your filenames from interpretation.  For example:
3379  
3380      use IO::Handle;
3381      sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL)
3382      or die "sysopen $path: $!";
3383      $oldfh = select(HANDLE); $| = 1; select($oldfh);
3384      print HANDLE "stuff $$\n";
3385      seek(HANDLE, 0, 0);
3386      print "File contains: ", <HANDLE>;
3387  
3388  Using the constructor from the C<IO::Handle> package (or one of its
3389  subclasses, such as C<IO::File> or C<IO::Socket>), you can generate anonymous
3390  filehandles that have the scope of whatever variables hold references to
3391  them, and automatically close whenever and however you leave that scope:
3392  
3393      use IO::File;
3394      #...
3395      sub read_myfile_munged {
3396      my $ALL = shift;
3397      my $handle = new IO::File;
3398      open($handle, "myfile") or die "myfile: $!";
3399      $first = <$handle>
3400          or return ();     # Automatically closed here.
3401      mung $first or die "mung failed";    # Or here.
3402      return $first, <$handle> if $ALL;    # Or here.
3403      $first;                    # Or here.
3404      }
3405  
3406  See L</seek> for some details about mixing reading and writing.
3407  
3408  =item opendir DIRHANDLE,EXPR
3409  X<opendir>
3410  
3411  Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
3412  C<seekdir>, C<rewinddir>, and C<closedir>.  Returns true if successful.
3413  DIRHANDLE may be an expression whose value can be used as an indirect
3414  dirhandle, usually the real dirhandle name.  If DIRHANDLE is an undefined
3415  scalar variable (or array or hash element), the variable is assigned a
3416  reference to a new anonymous dirhandle.
3417  DIRHANDLEs have their own namespace separate from FILEHANDLEs.
3418  
3419  =item ord EXPR
3420  X<ord> X<encoding>
3421  
3422  =item ord
3423  
3424  Returns the numeric (the native 8-bit encoding, like ASCII or EBCDIC,
3425  or Unicode) value of the first character of EXPR.  If EXPR is omitted,
3426  uses C<$_>.
3427  
3428  For the reverse, see L</chr>.
3429  See L<perlunicode> for more about Unicode.
3430  
3431  =item our EXPR
3432  X<our> X<global>
3433  
3434  =item our TYPE EXPR
3435  
3436  =item our EXPR : ATTRS
3437  
3438  =item our TYPE EXPR : ATTRS
3439  
3440  C<our> associates a simple name with a package variable in the current
3441  package for use within the current scope.  When C<use strict 'vars'> is in
3442  effect, C<our> lets you use declared global variables without qualifying
3443  them with package names, within the lexical scope of the C<our> declaration.
3444  In this way C<our> differs from C<use vars>, which is package scoped.
3445  
3446  Unlike C<my>, which both allocates storage for a variable and associates
3447  a simple name with that storage for use within the current scope, C<our>
3448  associates a simple name with a package variable in the current package,
3449  for use within the current scope.  In other words, C<our> has the same
3450  scoping rules as C<my>, but does not necessarily create a
3451  variable.
3452  
3453  If more than one value is listed, the list must be placed
3454  in parentheses.
3455  
3456      our $foo;
3457      our($bar, $baz);
3458  
3459  An C<our> declaration declares a global variable that will be visible
3460  across its entire lexical scope, even across package boundaries.  The
3461  package in which the variable is entered is determined at the point
3462  of the declaration, not at the point of use.  This means the following
3463  behavior holds:
3464  
3465      package Foo;
3466      our $bar;        # declares $Foo::bar for rest of lexical scope
3467      $bar = 20;
3468  
3469      package Bar;
3470      print $bar;        # prints 20, as it refers to $Foo::bar
3471  
3472  Multiple C<our> declarations with the same name in the same lexical
3473  scope are allowed if they are in different packages.  If they happen
3474  to be in the same package, Perl will emit warnings if you have asked
3475  for them, just like multiple C<my> declarations.  Unlike a second
3476  C<my> declaration, which will bind the name to a fresh variable, a
3477  second C<our> declaration in the same package, in the same scope, is
3478  merely redundant.
3479  
3480      use warnings;
3481      package Foo;
3482      our $bar;        # declares $Foo::bar for rest of lexical scope
3483      $bar = 20;
3484  
3485      package Bar;
3486      our $bar = 30;    # declares $Bar::bar for rest of lexical scope
3487      print $bar;        # prints 30
3488  
3489      our $bar;        # emits warning but has no other effect
3490      print $bar;        # still prints 30
3491  
3492  An C<our> declaration may also have a list of attributes associated
3493  with it.
3494  
3495  The exact semantics and interface of TYPE and ATTRS are still
3496  evolving.  TYPE is currently bound to the use of C<fields> pragma,
3497  and attributes are handled using the C<attributes> pragma, or starting
3498  from Perl 5.8.0 also via the C<Attribute::Handlers> module.  See
3499  L<perlsub/"Private Variables via my()"> for details, and L<fields>,
3500  L<attributes>, and L<Attribute::Handlers>.
3501  
3502  =item pack TEMPLATE,LIST
3503  X<pack>
3504  
3505  Takes a LIST of values and converts it into a string using the rules
3506  given by the TEMPLATE.  The resulting string is the concatenation of
3507  the converted values.  Typically, each converted value looks
3508  like its machine-level representation.  For example, on 32-bit machines
3509  an integer may be represented by a sequence of 4 bytes that will be 
3510  converted to a sequence of 4 characters.
3511  
3512  The TEMPLATE is a sequence of characters that give the order and type
3513  of values, as follows:
3514  
3515      a    A string with arbitrary binary data, will be null padded.
3516      A    A text (ASCII) string, will be space padded.
3517      Z    A null terminated (ASCIZ) string, will be null padded.
3518  
3519      b    A bit string (ascending bit order inside each byte, like vec()).
3520      B    A bit string (descending bit order inside each byte).
3521      h    A hex string (low nybble first).
3522      H    A hex string (high nybble first).
3523  
3524      c    A signed char (8-bit) value.
3525      C    An unsigned char (octet) value.
3526      W   An unsigned char value (can be greater than 255).
3527  
3528      s    A signed short (16-bit) value.
3529      S    An unsigned short value.
3530  
3531      l    A signed long (32-bit) value.
3532      L    An unsigned long value.
3533  
3534      q    A signed quad (64-bit) value.
3535      Q    An unsigned quad value.
3536        (Quads are available only if your system supports 64-bit
3537         integer values _and_ if Perl has been compiled to support those.
3538             Causes a fatal error otherwise.)
3539  
3540      i    A signed integer value.
3541      I    A unsigned integer value.
3542        (This 'integer' is _at_least_ 32 bits wide.  Its exact
3543             size depends on what a local C compiler calls 'int'.)
3544  
3545      n    An unsigned short (16-bit) in "network" (big-endian) order.
3546      N    An unsigned long (32-bit) in "network" (big-endian) order.
3547      v    An unsigned short (16-bit) in "VAX" (little-endian) order.
3548      V    An unsigned long (32-bit) in "VAX" (little-endian) order.
3549  
3550      j   A Perl internal signed integer value (IV).
3551      J   A Perl internal unsigned integer value (UV).
3552  
3553      f    A single-precision float in the native format.
3554      d    A double-precision float in the native format.
3555  
3556      F    A Perl internal floating point value (NV) in the native format
3557      D    A long double-precision float in the native format.
3558        (Long doubles are available only if your system supports long
3559         double values _and_ if Perl has been compiled to support those.
3560             Causes a fatal error otherwise.)
3561  
3562      p    A pointer to a null-terminated string.
3563      P    A pointer to a structure (fixed-length string).
3564  
3565      u    A uuencoded string.
3566      U    A Unicode character number.  Encodes to a character in character mode
3567          and UTF-8 (or UTF-EBCDIC in EBCDIC platforms) in byte mode.
3568  
3569      w    A BER compressed integer (not an ASN.1 BER, see perlpacktut for
3570      details).  Its bytes represent an unsigned integer in base 128,
3571      most significant digit first, with as few digits as possible.  Bit
3572      eight (the high bit) is set on each byte except the last.
3573  
3574      x    A null byte.
3575      X    Back up a byte.
3576      @    Null fill or truncate to absolute position, counted from the
3577          start of the innermost ()-group.
3578      .   Null fill or truncate to absolute position specified by value.
3579      (    Start of a ()-group.
3580  
3581  One or more of the modifiers below may optionally follow some letters in the
3582  TEMPLATE (the second column lists the letters for which the modifier is
3583  valid):
3584  
3585      !   sSlLiI     Forces native (short, long, int) sizes instead
3586                     of fixed (16-/32-bit) sizes.
3587  
3588          xX         Make x and X act as alignment commands.
3589  
3590          nNvV       Treat integers as signed instead of unsigned.
3591  
3592          @.         Specify position as byte offset in the internal
3593                     representation of the packed string. Efficient but
3594                     dangerous.
3595  
3596      >   sSiIlLqQ   Force big-endian byte-order on the type.
3597          jJfFdDpP   (The "big end" touches the construct.)
3598  
3599      <   sSiIlLqQ   Force little-endian byte-order on the type.
3600          jJfFdDpP   (The "little end" touches the construct.)
3601  
3602  The C<E<gt>> and C<E<lt>> modifiers can also be used on C<()>-groups,
3603  in which case they force a certain byte-order on all components of
3604  that group, including subgroups.
3605  
3606  The following rules apply:
3607  
3608  =over 8
3609  
3610  =item *
3611  
3612  Each letter may optionally be followed by a number giving a repeat
3613  count.  With all types except C<a>, C<A>, C<Z>, C<b>, C<B>, C<h>,
3614  C<H>, C<@>, C<.>, C<x>, C<X> and C<P> the pack function will gobble up
3615  that many values from the LIST.  A C<*> for the repeat count means to
3616  use however many items are left, except for C<@>, C<x>, C<X>, where it
3617  is equivalent to C<0>, for <.> where it means relative to string start
3618  and C<u>, where it is equivalent to 1 (or 45, which is the same).
3619  A numeric repeat count may optionally be enclosed in brackets, as in
3620  C<pack 'C[80]', @arr>.
3621  
3622  One can replace the numeric repeat count by a template enclosed in brackets;
3623  then the packed length of this template in bytes is used as a count.
3624  For example, C<x[L]> skips a long (it skips the number of bytes in a long);
3625  the template C<$t X[$t] $t> unpack()s twice what $t unpacks.
3626  If the template in brackets contains alignment commands (such as C<x![d]>),
3627  its packed length is calculated as if the start of the template has the maximal
3628  possible alignment.
3629  
3630  When used with C<Z>, C<*> results in the addition of a trailing null
3631  byte (so the packed result will be one longer than the byte C<length>
3632  of the item).
3633  
3634  When used with C<@>, the repeat count represents an offset from the start
3635  of the innermost () group.
3636  
3637  When used with C<.>, the repeat count is used to determine the starting
3638  position from where the value offset is calculated. If the repeat count
3639  is 0, it's relative to the current position. If the repeat count is C<*>,
3640  the offset is relative to the start of the packed string. And if its an
3641  integer C<n> the offset is relative to the start of the n-th innermost
3642  () group (or the start of the string if C<n> is bigger then the group
3643  level).
3644  
3645  The repeat count for C<u> is interpreted as the maximal number of bytes
3646  to encode per line of output, with 0, 1 and 2 replaced by 45. The repeat 
3647  count should not be more than 65.
3648  
3649  =item *
3650  
3651  The C<a>, C<A>, and C<Z> types gobble just one value, but pack it as a
3652  string of length count, padding with nulls or spaces as necessary.  When
3653  unpacking, C<A> strips trailing whitespace and nulls, C<Z> strips everything
3654  after the first null, and C<a> returns data verbatim.
3655  
3656  If the value-to-pack is too long, it is truncated.  If too long and an
3657  explicit count is provided, C<Z> packs only C<$count-1> bytes, followed
3658  by a null byte.  Thus C<Z> always packs a trailing null (except when the
3659  count is 0).
3660  
3661  =item *
3662  
3663  Likewise, the C<b> and C<B> fields pack a string that many bits long.
3664  Each character of the input field of pack() generates 1 bit of the result.
3665  Each result bit is based on the least-significant bit of the corresponding
3666  input character, i.e., on C<ord($char)%2>.  In particular, characters C<"0">
3667  and C<"1"> generate bits 0 and 1, as do characters C<"\0"> and C<"\1">.
3668  
3669  Starting from the beginning of the input string of pack(), each 8-tuple
3670  of characters is converted to 1 character of output.  With format C<b>
3671  the first character of the 8-tuple determines the least-significant bit of a
3672  character, and with format C<B> it determines the most-significant bit of
3673  a character.
3674  
3675  If the length of the input string is not exactly divisible by 8, the
3676  remainder is packed as if the input string were padded by null characters
3677  at the end.  Similarly, during unpack()ing the "extra" bits are ignored.
3678  
3679  If the input string of pack() is longer than needed, extra characters are 
3680  ignored. A C<*> for the repeat count of pack() means to use all the 
3681  characters of the input field.  On unpack()ing the bits are converted to a 
3682  string of C<"0">s and C<"1">s.
3683  
3684  =item *
3685  
3686  The C<h> and C<H> fields pack a string that many nybbles (4-bit groups,
3687  representable as hexadecimal digits, 0-9a-f) long.
3688  
3689  Each character of the input field of pack() generates 4 bits of the result.
3690  For non-alphabetical characters the result is based on the 4 least-significant
3691  bits of the input character, i.e., on C<ord($char)%16>.  In particular,
3692  characters C<"0"> and C<"1"> generate nybbles 0 and 1, as do bytes
3693  C<"\0"> and C<"\1">.  For characters C<"a".."f"> and C<"A".."F"> the result
3694  is compatible with the usual hexadecimal digits, so that C<"a"> and
3695  C<"A"> both generate the nybble C<0xa==10>.  The result for characters
3696  C<"g".."z"> and C<"G".."Z"> is not well-defined.
3697  
3698  Starting from the beginning of the input string of pack(), each pair
3699  of characters is converted to 1 character of output.  With format C<h> the
3700  first character of the pair determines the least-significant nybble of the
3701  output character, and with format C<H> it determines the most-significant
3702  nybble.
3703  
3704  If the length of the input string is not even, it behaves as if padded
3705  by a null character at the end.  Similarly, during unpack()ing the "extra"
3706  nybbles are ignored.
3707  
3708  If the input string of pack() is longer than needed, extra characters are
3709  ignored.
3710  A C<*> for the repeat count of pack() means to use all the characters of
3711  the input field.  On unpack()ing the nybbles are converted to a string
3712  of hexadecimal digits.
3713  
3714  =item *
3715  
3716  The C<p> type packs a pointer to a null-terminated string.  You are
3717  responsible for ensuring the string is not a temporary value (which can
3718  potentially get deallocated before you get around to using the packed result).
3719  The C<P> type packs a pointer to a structure of the size indicated by the
3720  length.  A NULL pointer is created if the corresponding value for C<p> or
3721  C<P> is C<undef>, similarly for unpack().
3722  
3723  If your system has a strange pointer size (i.e. a pointer is neither as
3724  big as an int nor as big as a long), it may not be possible to pack or
3725  unpack pointers in big- or little-endian byte order.  Attempting to do
3726  so will result in a fatal error.
3727  
3728  =item *
3729  
3730  The C</> template character allows packing and unpacking of a sequence of
3731  items where the packed structure contains a packed item count followed by 
3732  the packed items themselves.
3733  
3734  For C<pack> you write I<length-item>C</>I<sequence-item> and the
3735  I<length-item> describes how the length value is packed. The ones likely
3736  to be of most use are integer-packing ones like C<n> (for Java strings),
3737  C<w> (for ASN.1 or SNMP) and C<N> (for Sun XDR).
3738  
3739  For C<pack>, the I<sequence-item> may have a repeat count, in which case
3740  the minimum of that and the number of available items is used as argument
3741  for the I<length-item>. If it has no repeat count or uses a '*', the number
3742  of available items is used.
3743  
3744  For C<unpack> an internal stack of integer arguments unpacked so far is
3745  used. You write C</>I<sequence-item> and the repeat count is obtained by
3746  popping off the last element from the stack. The I<sequence-item> must not
3747  have a repeat count.
3748  
3749  If the I<sequence-item> refers to a string type (C<"A">, C<"a"> or C<"Z">),
3750  the I<length-item> is a string length, not a number of strings. If there is
3751  an explicit repeat count for pack, the packed string will be adjusted to that
3752  given length.
3753  
3754      unpack 'W/a', "\04Gurusamy";            gives ('Guru')
3755      unpack 'a3/A A*', '007 Bond  J ';       gives (' Bond', 'J')
3756      unpack 'a3 x2 /A A*', '007: Bond, J.';  gives ('Bond, J', '.')
3757      pack 'n/a* w/a','hello,','world';       gives "\000\006hello,\005world"
3758      pack 'a/W2', ord('a') .. ord('z');      gives '2ab'
3759  
3760  The I<length-item> is not returned explicitly from C<unpack>.
3761  
3762  Adding a count to the I<length-item> letter is unlikely to do anything
3763  useful, unless that letter is C<A>, C<a> or C<Z>.  Packing with a
3764  I<length-item> of C<a> or C<Z> may introduce C<"\000"> characters,
3765  which Perl does not regard as legal in numeric strings.
3766  
3767  =item *
3768  
3769  The integer types C<s>, C<S>, C<l>, and C<L> may be
3770  followed by a C<!> modifier to signify native shorts or
3771  longs--as you can see from above for example a bare C<l> does mean
3772  exactly 32 bits, the native C<long> (as seen by the local C compiler)
3773  may be larger.  This is an issue mainly in 64-bit platforms.  You can
3774  see whether using C<!> makes any difference by
3775  
3776      print length(pack("s")), " ", length(pack("s!")), "\n";
3777      print length(pack("l")), " ", length(pack("l!")), "\n";
3778  
3779  C<i!> and C<I!> also work but only because of completeness;
3780  they are identical to C<i> and C<I>.
3781  
3782  The actual sizes (in bytes) of native shorts, ints, longs, and long
3783  longs on the platform where Perl was built are also available via
3784  L<Config>:
3785  
3786         use Config;
3787         print $Config{shortsize},    "\n";
3788         print $Config{intsize},      "\n";
3789         print $Config{longsize},     "\n";
3790         print $Config{longlongsize}, "\n";
3791  
3792  (The C<$Config{longlongsize}> will be undefined if your system does
3793  not support long longs.)
3794  
3795  =item *
3796  
3797  The integer formats C<s>, C<S>, C<i>, C<I>, C<l>, C<L>, C<j>, and C<J>
3798  are inherently non-portable between processors and operating systems
3799  because they obey the native byteorder and endianness.  For example a
3800  4-byte integer 0x12345678 (305419896 decimal) would be ordered natively
3801  (arranged in and handled by the CPU registers) into bytes as
3802  
3803       0x12 0x34 0x56 0x78    # big-endian
3804       0x78 0x56 0x34 0x12    # little-endian
3805  
3806  Basically, the Intel and VAX CPUs are little-endian, while everybody
3807  else, for example Motorola m68k/88k, PPC, Sparc, HP PA, Power, and
3808  Cray are big-endian.  Alpha and MIPS can be either: Digital/Compaq
3809  used/uses them in little-endian mode; SGI/Cray uses them in big-endian
3810  mode.
3811  
3812  The names `big-endian' and `little-endian' are comic references to
3813  the classic "Gulliver's Travels" (via the paper "On Holy Wars and a
3814  Plea for Peace" by Danny Cohen, USC/ISI IEN 137, April 1, 1980) and
3815  the egg-eating habits of the Lilliputians.
3816  
3817  Some systems may have even weirder byte orders such as
3818  
3819       0x56 0x78 0x12 0x34
3820       0x34 0x12 0x78 0x56
3821  
3822  You can see your system's preference with
3823  
3824       print join(" ", map { sprintf "%#02x", $_ }
3825                              unpack("W*",pack("L",0x12345678))), "\n";
3826  
3827  The byteorder on the platform where Perl was built is also available
3828  via L<Config>:
3829  
3830      use Config;
3831      print $Config{byteorder}, "\n";
3832  
3833  Byteorders C<'1234'> and C<'12345678'> are little-endian, C<'4321'>
3834  and C<'87654321'> are big-endian.
3835  
3836  If you want portable packed integers you can either use the formats
3837  C<n>, C<N>, C<v>, and C<V>, or you can use the C<E<gt>> and C<E<lt>>
3838  modifiers.  These modifiers are only available as of perl 5.9.2.
3839  See also L<perlport>.
3840  
3841  =item *
3842  
3843  All integer and floating point formats as well as C<p> and C<P> and
3844  C<()>-groups may be followed by the C<E<gt>> or C<E<lt>> modifiers
3845  to force big- or little- endian byte-order, respectively.
3846  This is especially useful, since C<n>, C<N>, C<v> and C<V> don't cover
3847  signed integers, 64-bit integers and floating point values.  However,
3848  there are some things to keep in mind.
3849  
3850  Exchanging signed integers between different platforms only works
3851  if all platforms store them in the same format.  Most platforms store
3852  signed integers in two's complement, so usually this is not an issue.
3853  
3854  The C<E<gt>> or C<E<lt>> modifiers can only be used on floating point
3855  formats on big- or little-endian machines.  Otherwise, attempting to
3856  do so will result in a fatal error.
3857  
3858  Forcing big- or little-endian byte-order on floating point values for
3859  data exchange can only work if all platforms are using the same
3860  binary representation (e.g. IEEE floating point format).  Even if all
3861  platforms are using IEEE, there may be subtle differences.  Being able
3862  to use C<E<gt>> or C<E<lt>> on floating point values can be very useful,
3863  but also very dangerous if you don't know exactly what you're doing.
3864  It is definitely not a general way to portably store floating point
3865  values.
3866  
3867  When using C<E<gt>> or C<E<lt>> on an C<()>-group, this will affect
3868  all types inside the group that accept the byte-order modifiers,
3869  including all subgroups.  It will silently be ignored for all other
3870  types.  You are not allowed to override the byte-order within a group
3871  that already has a byte-order modifier suffix.
3872  
3873  =item *
3874  
3875  Real numbers (floats and doubles) are in the native machine format only;
3876  due to the multiplicity of floating formats around, and the lack of a
3877  standard "network" representation, no facility for interchange has been
3878  made.  This means that packed floating point data written on one machine
3879  may not be readable on another - even if both use IEEE floating point
3880  arithmetic (as the endian-ness of the memory representation is not part
3881  of the IEEE spec).  See also L<perlport>.
3882  
3883  If you know exactly what you're doing, you can use the C<E<gt>> or C<E<lt>>
3884  modifiers to force big- or little-endian byte-order on floating point values.
3885  
3886  Note that Perl uses doubles (or long doubles, if configured) internally for
3887  all numeric calculation, and converting from double into float and thence back
3888  to double again will lose precision (i.e., C<unpack("f", pack("f", $foo)>)
3889  will not in general equal $foo).
3890  
3891  =item *
3892  
3893  Pack and unpack can operate in two modes, character mode (C<C0> mode) where
3894  the packed string is processed per character and UTF-8 mode (C<U0> mode)
3895  where the packed string is processed in its UTF-8-encoded Unicode form on
3896  a byte by byte basis. Character mode is the default unless the format string 
3897  starts with an C<U>. You can switch mode at any moment with an explicit 
3898  C<C0> or C<U0> in the format. A mode is in effect until the next mode switch 
3899  or until the end of the ()-group in which it was entered.
3900  
3901  =item *
3902  
3903  You must yourself do any alignment or padding by inserting for example
3904  enough C<'x'>es while packing.  There is no way to pack() and unpack()
3905  could know where the characters are going to or coming from.  Therefore
3906  C<pack> (and C<unpack>) handle their output and input as flat
3907  sequences of characters.
3908  
3909  =item *
3910  
3911  A ()-group is a sub-TEMPLATE enclosed in parentheses.  A group may
3912  take a repeat count, both as postfix, and for unpack() also via the C</>
3913  template character. Within each repetition of a group, positioning with
3914  C<@> starts again at 0. Therefore, the result of
3915  
3916      pack( '@1A((@2A)@3A)', 'a', 'b', 'c' )
3917  
3918  is the string "\0a\0\0bc".
3919  
3920  =item *
3921  
3922  C<x> and C<X> accept C<!> modifier.  In this case they act as
3923  alignment commands: they jump forward/back to the closest position
3924  aligned at a multiple of C<count> characters. For example, to pack() or
3925  unpack() C's C<struct {char c; double d; char cc[2]}> one may need to
3926  use the template C<W x![d] d W[2]>; this assumes that doubles must be
3927  aligned on the double's size.
3928  
3929  For alignment commands C<count> of 0 is equivalent to C<count> of 1;
3930  both result in no-ops.
3931  
3932  =item *
3933  
3934  C<n>, C<N>, C<v> and C<V> accept the C<!> modifier. In this case they
3935  will represent signed 16-/32-bit integers in big-/little-endian order.
3936  This is only portable if all platforms sharing the packed data use the
3937  same binary representation for signed integers (e.g. all platforms are
3938  using two's complement representation).
3939  
3940  =item *
3941  
3942  A comment in a TEMPLATE starts with C<#> and goes to the end of line.
3943  White space may be used to separate pack codes from each other, but
3944  modifiers and a repeat count must follow immediately.
3945  
3946  =item *
3947  
3948  If TEMPLATE requires more arguments to pack() than actually given, pack()
3949  assumes additional C<""> arguments.  If TEMPLATE requires fewer arguments
3950  to pack() than actually given, extra arguments are ignored.
3951  
3952  =back
3953  
3954  Examples:
3955  
3956      $foo = pack("WWWW",65,66,67,68);
3957      # foo eq "ABCD"
3958      $foo = pack("W4",65,66,67,68);
3959      # same thing
3960      $foo = pack("W4",0x24b6,0x24b7,0x24b8,0x24b9);
3961      # same thing with Unicode circled letters.
3962      $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9);
3963      # same thing with Unicode circled letters. You don't get the UTF-8
3964      # bytes because the U at the start of the format caused a switch to
3965      # U0-mode, so the UTF-8 bytes get joined into characters
3966      $foo = pack("C0U4",0x24b6,0x24b7,0x24b8,0x24b9);
3967      # foo eq "\xe2\x92\xb6\xe2\x92\xb7\xe2\x92\xb8\xe2\x92\xb9"
3968      # This is the UTF-8 encoding of the string in the previous example
3969  
3970      $foo = pack("ccxxcc",65,66,67,68);
3971      # foo eq "AB\0\0CD"
3972  
3973      # note: the above examples featuring "W" and "c" are true
3974      # only on ASCII and ASCII-derived systems such as ISO Latin 1
3975      # and UTF-8.  In EBCDIC the first example would be
3976      # $foo = pack("WWWW",193,194,195,196);
3977  
3978      $foo = pack("s2",1,2);
3979      # "\1\0\2\0" on little-endian
3980      # "\0\1\0\2" on big-endian
3981  
3982      $foo = pack("a4","abcd","x","y","z");
3983      # "abcd"
3984  
3985      $foo = pack("aaaa","abcd","x","y","z");
3986      # "axyz"
3987  
3988      $foo = pack("a14","abcdefg");
3989      # "abcdefg\0\0\0\0\0\0\0"
3990  
3991      $foo = pack("i9pl", gmtime);
3992      # a real struct tm (on my system anyway)
3993  
3994      $utmp_template = "Z8 Z8 Z16 L";
3995      $utmp = pack($utmp_template, @utmp1);
3996      # a struct utmp (BSDish)
3997  
3998      @utmp2 = unpack($utmp_template, $utmp);
3999      # "@utmp1" eq "@utmp2"
4000  
4001      sub bintodec {
4002      unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
4003      }
4004  
4005      $foo = pack('sx2l', 12, 34);
4006      # short 12, two zero bytes padding, long 34
4007      $bar = pack('s@4l', 12, 34);
4008      # short 12, zero fill to position 4, long 34
4009      # $foo eq $bar
4010      $baz = pack('s.l', 12, 4, 34);
4011      # short 12, zero fill to position 4, long 34
4012  
4013      $foo = pack('nN', 42, 4711);
4014      # pack big-endian 16- and 32-bit unsigned integers
4015      $foo = pack('S>L>', 42, 4711);
4016      # exactly the same
4017      $foo = pack('s<l<', -42, 4711);
4018      # pack little-endian 16- and 32-bit signed integers
4019      $foo = pack('(sl)<', -42, 4711);
4020      # exactly the same
4021  
4022  The same template may generally also be used in unpack().
4023  
4024  =item package NAMESPACE
4025  X<package> X<module> X<namespace>
4026  
4027  =item package
4028  
4029  Declares the compilation unit as being in the given namespace.  The scope
4030  of the package declaration is from the declaration itself through the end
4031  of the enclosing block, file, or eval (the same as the C<my> operator).
4032  All further unqualified dynamic identifiers will be in this namespace.
4033  A package statement affects only dynamic variables--including those
4034  you've used C<local> on--but I<not> lexical variables, which are created
4035  with C<my>.  Typically it would be the first declaration in a file to
4036  be included by the C<require> or C<use> operator.  You can switch into a
4037  package in more than one place; it merely influences which symbol table
4038  is used by the compiler for the rest of that block.  You can refer to
4039  variables and filehandles in other packages by prefixing the identifier
4040  with the package name and a double colon:  C<$Package::Variable>.
4041  If the package name is null, the C<main> package as assumed.  That is,
4042  C<$::sail> is equivalent to C<$main::sail> (as well as to C<$main'sail>,
4043  still seen in older code).
4044  
4045  If NAMESPACE is omitted, then there is no current package, and all
4046  identifiers must be fully qualified or lexicals.  However, you are
4047  strongly advised not to make use of this feature. Its use can cause
4048  unexpected behaviour, even crashing some versions of Perl. It is
4049  deprecated, and will be removed from a future release.
4050  
4051  See L<perlmod/"Packages"> for more information about packages, modules,
4052  and classes.  See L<perlsub> for other scoping issues.
4053  
4054  =item pipe READHANDLE,WRITEHANDLE
4055  X<pipe>
4056  
4057  Opens a pair of connected pipes like the corresponding system call.
4058  Note that if you set up a loop of piped processes, deadlock can occur
4059  unless you are very careful.  In addition, note that Perl's pipes use
4060  IO buffering, so you may need to set C<$|> to flush your WRITEHANDLE
4061  after each command, depending on the application.
4062  
4063  See L<IPC::Open2>, L<IPC::Open3>, and L<perlipc/"Bidirectional Communication">
4064  for examples of such things.
4065  
4066  On systems that support a close-on-exec flag on files, the flag will be set
4067  for the newly opened file descriptors as determined by the value of $^F.
4068  See L<perlvar/$^F>.
4069  
4070  =item pop ARRAY
4071  X<pop> X<stack>
4072  
4073  =item pop
4074  
4075  Pops and returns the last value of the array, shortening the array by
4076  one element.
4077  
4078  If there are no elements in the array, returns the undefined value
4079  (although this may happen at other times as well).  If ARRAY is
4080  omitted, pops the C<@ARGV> array in the main program, and the C<@_>
4081  array in subroutines, just like C<shift>.
4082  
4083  =item pos SCALAR
4084  X<pos> X<match, position>
4085  
4086  =item pos
4087  
4088  Returns the offset of where the last C<m//g> search left off for the variable
4089  in question (C<$_> is used when the variable is not specified).  Note that
4090  0 is a valid match offset.  C<undef> indicates that the search position
4091  is reset (usually due to match failure, but can also be because no match has
4092  yet been performed on the scalar). C<pos> directly accesses the location used
4093  by the regexp engine to store the offset, so assigning to C<pos> will change
4094  that offset, and so will also influence the C<\G> zero-width assertion in
4095  regular expressions. Because a failed C<m//gc> match doesn't reset the offset,
4096  the return from C<pos> won't change either in this case.  See L<perlre> and
4097  L<perlop>.
4098  
4099  =item print FILEHANDLE LIST
4100  X<print>
4101  
4102  =item print LIST
4103  
4104  =item print
4105  
4106  Prints a string or a list of strings.  Returns true if successful.
4107  FILEHANDLE may be a scalar variable name, in which case the variable
4108  contains the name of or a reference to the filehandle, thus introducing
4109  one level of indirection.  (NOTE: If FILEHANDLE is a variable and
4110  the next token is a term, it may be misinterpreted as an operator
4111  unless you interpose a C<+> or put parentheses around the arguments.)
4112  If FILEHANDLE is omitted, prints by default to standard output (or
4113  to the last selected output channel--see L</select>).  If LIST is
4114  also omitted, prints C<$_> to the currently selected output channel.
4115  To set the default output channel to something other than STDOUT
4116  use the select operation.  The current value of C<$,> (if any) is
4117  printed between each LIST item.  The current value of C<$\> (if
4118  any) is printed after the entire LIST has been printed.  Because
4119  print takes a LIST, anything in the LIST is evaluated in list
4120  context, and any subroutine that you call will have one or more of
4121  its expressions evaluated in list context.  Also be careful not to
4122  follow the print keyword with a left parenthesis unless you want
4123  the corresponding right parenthesis to terminate the arguments to
4124  the print--interpose a C<+> or put parentheses around all the
4125  arguments.
4126  
4127  Note that if you're storing FILEHANDLEs in an array, or if you're using
4128  any other expression more complex than a scalar variable to retrieve it,
4129  you will have to use a block returning the filehandle value instead:
4130  
4131      print { $files[$i] } "stuff\n";
4132      print { $OK ? STDOUT : STDERR } "stuff\n";
4133  
4134  =item printf FILEHANDLE FORMAT, LIST
4135  X<printf>
4136  
4137  =item printf FORMAT, LIST
4138  
4139  Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that C<$\>
4140  (the output record separator) is not appended.  The first argument
4141  of the list will be interpreted as the C<printf> format. See C<sprintf>
4142  for an explanation of the format argument.  If C<use locale> is in effect,
4143  and POSIX::setlocale() has been called, the character used for the decimal
4144  separator in formatted floating point numbers is affected by the LC_NUMERIC
4145  locale.  See L<perllocale> and L<POSIX>.
4146  
4147  Don't fall into the trap of using a C<printf> when a simple
4148  C<print> would do.  The C<print> is more efficient and less
4149  error prone.
4150  
4151  =item prototype FUNCTION
4152  X<prototype>
4153  
4154  Returns the prototype of a function as a string (or C<undef> if the
4155  function has no prototype).  FUNCTION is a reference to, or the name of,
4156  the function whose prototype you want to retrieve.
4157  
4158  If FUNCTION is a string starting with C<CORE::>, the rest is taken as a
4159  name for Perl builtin.  If the builtin is not I<overridable> (such as
4160  C<qw//>) or if its arguments cannot be adequately expressed by a prototype
4161  (such as C<system>), prototype() returns C<undef>, because the builtin
4162  does not really behave like a Perl function.  Otherwise, the string
4163  describing the equivalent prototype is returned.
4164  
4165  =item push ARRAY,LIST
4166  X<push> X<stack>
4167  
4168  Treats ARRAY as a stack, and pushes the values of LIST
4169  onto the end of ARRAY.  The length of ARRAY increases by the length of
4170  LIST.  Has the same effect as
4171  
4172      for $value (LIST) {
4173      $ARRAY[++$#ARRAY] = $value;
4174      }
4175  
4176  but is more efficient.  Returns the number of elements in the array following
4177  the completed C<push>.
4178  
4179  =item q/STRING/
4180  
4181  =item qq/STRING/
4182  
4183  =item qr/STRING/
4184  
4185  =item qx/STRING/
4186  
4187  =item qw/STRING/
4188  
4189  Generalized quotes.  See L<perlop/"Regexp Quote-Like Operators">.
4190  
4191  =item quotemeta EXPR
4192  X<quotemeta> X<metacharacter>
4193  
4194  =item quotemeta
4195  
4196  Returns the value of EXPR with all non-"word"
4197  characters backslashed.  (That is, all characters not matching
4198  C</[A-Za-z_0-9]/> will be preceded by a backslash in the
4199  returned string, regardless of any locale settings.)
4200  This is the internal function implementing
4201  the C<\Q> escape in double-quoted strings.
4202  
4203  If EXPR is omitted, uses C<$_>.
4204  
4205  =item rand EXPR
4206  X<rand> X<random>
4207  
4208  =item rand
4209  
4210  Returns a random fractional number greater than or equal to C<0> and less
4211  than the value of EXPR.  (EXPR should be positive.)  If EXPR is
4212  omitted, the value C<1> is used.  Currently EXPR with the value C<0> is
4213  also special-cased as C<1> - this has not been documented before perl 5.8.0
4214  and is subject to change in future versions of perl.  Automatically calls
4215  C<srand> unless C<srand> has already been called.  See also C<srand>.
4216  
4217  Apply C<int()> to the value returned by C<rand()> if you want random
4218  integers instead of random fractional numbers.  For example,
4219  
4220      int(rand(10))
4221  
4222  returns a random integer between C<0> and C<9>, inclusive.
4223  
4224  (Note: If your rand function consistently returns numbers that are too
4225  large or too small, then your version of Perl was probably compiled
4226  with the wrong number of RANDBITS.)
4227  
4228  =item read FILEHANDLE,SCALAR,LENGTH,OFFSET
4229  X<read> X<file, read>
4230  
4231  =item read FILEHANDLE,SCALAR,LENGTH
4232  
4233  Attempts to read LENGTH I<characters> of data into variable SCALAR
4234  from the specified FILEHANDLE.  Returns the number of characters
4235  actually read, C<0> at end of file, or undef if there was an error (in
4236  the latter case C<$!> is also set).  SCALAR will be grown or shrunk 
4237  so that the last character actually read is the last character of the
4238  scalar after the read.
4239  
4240  An OFFSET may be specified to place the read data at some place in the
4241  string other than the beginning.  A negative OFFSET specifies
4242  placement at that many characters counting backwards from the end of
4243  the string.  A positive OFFSET greater than the length of SCALAR
4244  results in the string being padded to the required size with C<"\0">
4245  bytes before the result of the read is appended.
4246  
4247  The call is actually implemented in terms of either Perl's or system's
4248  fread() call.  To get a true read(2) system call, see C<sysread>.
4249  
4250  Note the I<characters>: depending on the status of the filehandle,
4251  either (8-bit) bytes or characters are read.  By default all
4252  filehandles operate on bytes, but for example if the filehandle has
4253  been opened with the C<:utf8> I/O layer (see L</open>, and the C<open>
4254  pragma, L<open>), the I/O will operate on UTF-8 encoded Unicode
4255  characters, not bytes.  Similarly for the C<:encoding> pragma:
4256  in that case pretty much any characters can be read.
4257  
4258  =item readdir DIRHANDLE
4259  X<readdir>
4260  
4261  Returns the next directory entry for a directory opened by C<opendir>.
4262  If used in list context, returns all the rest of the entries in the
4263  directory.  If there are no more entries, returns an undefined value in
4264  scalar context or a null list in list context.
4265  
4266  If you're planning to filetest the return values out of a C<readdir>, you'd
4267  better prepend the directory in question.  Otherwise, because we didn't
4268  C<chdir> there, it would have been testing the wrong file.
4269  
4270      opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!";
4271      @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
4272      closedir DIR;
4273  
4274  =item readline EXPR
4275  
4276  =item readline
4277  X<readline> X<gets> X<fgets>
4278  
4279  Reads from the filehandle whose typeglob is contained in EXPR (or from
4280  *ARGV if EXPR is not provided).  In scalar context, each call reads and
4281  returns the next line, until end-of-file is reached, whereupon the
4282  subsequent call returns undef.  In list context, reads until end-of-file
4283  is reached and returns a list of lines.  Note that the notion of "line"
4284  used here is however you may have defined it with C<$/> or
4285  C<$INPUT_RECORD_SEPARATOR>).  See L<perlvar/"$/">.
4286  
4287  When C<$/> is set to C<undef>, when readline() is in scalar
4288  context (i.e. file slurp mode), and when an empty file is read, it
4289  returns C<''> the first time, followed by C<undef> subsequently.
4290  
4291  This is the internal function implementing the C<< <EXPR> >>
4292  operator, but you can use it directly.  The C<< <EXPR> >>
4293  operator is discussed in more detail in L<perlop/"I/O Operators">.
4294  
4295      $line = <STDIN>;
4296      $line = readline(*STDIN);        # same thing
4297  
4298  If readline encounters an operating system error, C<$!> will be set with the
4299  corresponding error message.  It can be helpful to check C<$!> when you are
4300  reading from filehandles you don't trust, such as a tty or a socket.  The
4301  following example uses the operator form of C<readline>, and takes the necessary
4302  steps to ensure that C<readline> was successful.
4303  
4304      for (;;) {
4305          undef $!;
4306          unless (defined( $line = <> )) {
4307              die $! if $!;
4308              last; # reached EOF
4309          }
4310          # ...
4311      }
4312  
4313  =item readlink EXPR
4314  X<readlink>
4315  
4316  =item readlink
4317  
4318  Returns the value of a symbolic link, if symbolic links are
4319  implemented.  If not, gives a fatal error.  If there is some system
4320  error, returns the undefined value and sets C<$!> (errno).  If EXPR is
4321  omitted, uses C<$_>.
4322  
4323  =item readpipe EXPR
4324  
4325  =item readpipe
4326  X<readpipe>
4327  
4328  EXPR is executed as a system command.
4329  The collected standard output of the command is returned.
4330  In scalar context, it comes back as a single (potentially
4331  multi-line) string.  In list context, returns a list of lines
4332  (however you've defined lines with C<$/> or C<$INPUT_RECORD_SEPARATOR>).
4333  This is the internal function implementing the C<qx/EXPR/>
4334  operator, but you can use it directly.  The C<qx/EXPR/>
4335  operator is discussed in more detail in L<perlop/"I/O Operators">.
4336  If EXPR is omitted, uses C<$_>.
4337  
4338  =item recv SOCKET,SCALAR,LENGTH,FLAGS
4339  X<recv>
4340  
4341  Receives a message on a socket.  Attempts to receive LENGTH characters
4342  of data into variable SCALAR from the specified SOCKET filehandle.
4343  SCALAR will be grown or shrunk to the length actually read.  Takes the
4344  same flags as the system call of the same name.  Returns the address
4345  of the sender if SOCKET's protocol supports this; returns an empty
4346  string otherwise.  If there's an error, returns the undefined value.
4347  This call is actually implemented in terms of recvfrom(2) system call.
4348  See L<perlipc/"UDP: Message Passing"> for examples.
4349  
4350  Note the I<characters>: depending on the status of the socket, either
4351  (8-bit) bytes or characters are received.  By default all sockets
4352  operate on bytes, but for example if the socket has been changed using
4353  binmode() to operate with the C<:encoding(utf8)> I/O layer (see the
4354  C<open> pragma, L<open>), the I/O will operate on UTF-8 encoded Unicode
4355  characters, not bytes.  Similarly for the C<:encoding> pragma: in that
4356  case pretty much any characters can be read.
4357  
4358  =item redo LABEL
4359  X<redo>
4360  
4361  =item redo
4362  
4363  The C<redo> command restarts the loop block without evaluating the
4364  conditional again.  The C<continue> block, if any, is not executed.  If
4365  the LABEL is omitted, the command refers to the innermost enclosing
4366  loop.  Programs that want to lie to themselves about what was just input 
4367  normally use this command:
4368  
4369      # a simpleminded Pascal comment stripper
4370      # (warning: assumes no { or } in strings)
4371      LINE: while (<STDIN>) {
4372      while (s|({.*}.*){.*}|$1 |) {}
4373      s|{.*}| |;
4374      if (s|{.*| |) {
4375          $front = $_;
4376          while (<STDIN>) {
4377          if (/}/) {    # end of comment?
4378              s|^|$front\{|;
4379              redo LINE;
4380          }
4381          }
4382      }
4383      print;
4384      }
4385  
4386  C<redo> cannot be used to retry a block which returns a value such as
4387  C<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit
4388  a grep() or map() operation.
4389  
4390  Note that a block by itself is semantically identical to a loop
4391  that executes once.  Thus C<redo> inside such a block will effectively
4392  turn it into a looping construct.
4393  
4394  See also L</continue> for an illustration of how C<last>, C<next>, and
4395  C<redo> work.
4396  
4397  =item ref EXPR
4398  X<ref> X<reference>
4399  
4400  =item ref
4401  
4402  Returns a non-empty string if EXPR is a reference, the empty
4403  string otherwise. If EXPR
4404  is not specified, C<$_> will be used.  The value returned depends on the
4405  type of thing the reference is a reference to.
4406  Builtin types include:
4407  
4408      SCALAR
4409      ARRAY
4410      HASH
4411      CODE
4412      REF
4413      GLOB
4414      LVALUE
4415      FORMAT
4416      IO
4417      VSTRING
4418      Regexp
4419  
4420  If the referenced object has been blessed into a package, then that package
4421  name is returned instead.  You can think of C<ref> as a C<typeof> operator.
4422  
4423      if (ref($r) eq "HASH") {
4424      print "r is a reference to a hash.\n";
4425      }
4426      unless (ref($r)) {
4427      print "r is not a reference at all.\n";
4428      }
4429  
4430  The return value C<LVALUE> indicates a reference to an lvalue that is not
4431  a variable. You get this from taking the reference of function calls like
4432  C<pos()> or C<substr()>. C<VSTRING> is returned if the reference points
4433  to a L<version string|perldata/"Version Strings">.
4434  
4435  The result C<Regexp> indicates that the argument is a regular expression
4436  resulting from C<qr//>.
4437  
4438  See also L<perlref>.
4439  
4440  =item rename OLDNAME,NEWNAME
4441  X<rename> X<move> X<mv> X<ren>
4442  
4443  Changes the name of a file; an existing file NEWNAME will be
4444  clobbered.  Returns true for success, false otherwise.
4445  
4446  Behavior of this function varies wildly depending on your system
4447  implementation.  For example, it will usually not work across file system
4448  boundaries, even though the system I<mv> command sometimes compensates
4449  for this.  Other restrictions include whether it works on directories,
4450  open files, or pre-existing files.  Check L<perlport> and either the
4451  rename(2) manpage or equivalent system documentation for details.
4452  
4453  For a platform independent C<move> function look at the L<File::Copy>
4454  module.
4455  
4456  =item require VERSION
4457  X<require>
4458  
4459  =item require EXPR
4460  
4461  =item require
4462  
4463  Demands a version of Perl specified by VERSION, or demands some semantics
4464  specified by EXPR or by C<$_> if EXPR is not supplied.
4465  
4466  VERSION may be either a numeric argument such as 5.006, which will be
4467  compared to C<$]>, or a literal of the form v5.6.1, which will be compared
4468  to C<$^V> (aka $PERL_VERSION).  A fatal error is produced at run time if
4469  VERSION is greater than the version of the current Perl interpreter.
4470  Compare with L</use>, which can do a similar check at compile time.
4471  
4472  Specifying VERSION as a literal of the form v5.6.1 should generally be
4473  avoided, because it leads to misleading error messages under earlier
4474  versions of Perl that do not support this syntax.  The equivalent numeric
4475  version should be used instead.
4476  
4477      require v5.6.1;    # run time version check
4478      require 5.6.1;    # ditto
4479      require 5.006_001;    # ditto; preferred for backwards compatibility
4480  
4481  Otherwise, C<require> demands that a library file be included if it
4482  hasn't already been included.  The file is included via the do-FILE
4483  mechanism, which is essentially just a variety of C<eval> with the
4484  caveat that lexical variables in the invoking script will be invisible
4485  to the included code.  Has semantics similar to the following subroutine:
4486  
4487      sub require {
4488         my ($filename) = @_;
4489         if (exists $INC{$filename}) {
4490             return 1 if $INC{$filename};
4491             die "Compilation failed in require";
4492         }
4493         my ($realfilename,$result);
4494         ITER: {
4495             foreach $prefix (@INC) {
4496                 $realfilename = "$prefix/$filename";
4497                 if (-f $realfilename) {
4498                     $INC{$filename} = $realfilename;
4499                     $result = do $realfilename;
4500                     last ITER;
4501                 }
4502             }
4503             die "Can't find $filename in \@INC";
4504         }
4505         if ($@) {
4506             $INC{$filename} = undef;
4507             die $@;
4508         } elsif (!$result) {
4509             delete $INC{$filename};
4510             die "$filename did not return true value";
4511         } else {
4512             return $result;
4513         }
4514      }
4515  
4516  Note that the file will not be included twice under the same specified
4517  name.
4518  
4519  The file must return true as the last statement to indicate
4520  successful execution of any initialization code, so it's customary to
4521  end such a file with C<1;> unless you're sure it'll return true
4522  otherwise.  But it's better just to put the C<1;>, in case you add more
4523  statements.
4524  
4525  If EXPR is a bareword, the require assumes a "F<.pm>" extension and
4526  replaces "F<::>" with "F</>" in the filename for you,
4527  to make it easy to load standard modules.  This form of loading of
4528  modules does not risk altering your namespace.
4529  
4530  In other words, if you try this:
4531  
4532          require Foo::Bar;    # a splendid bareword
4533  
4534  The require function will actually look for the "F<Foo/Bar.pm>" file in the
4535  directories specified in the C<@INC> array.
4536  
4537  But if you try this:
4538  
4539          $class = 'Foo::Bar';
4540          require $class;         # $class is not a bareword
4541      #or
4542          require "Foo::Bar";  # not a bareword because of the ""
4543  
4544  The require function will look for the "F<Foo::Bar>" file in the @INC array and
4545  will complain about not finding "F<Foo::Bar>" there.  In this case you can do:
4546  
4547          eval "require $class";
4548  
4549  Now that you understand how C<require> looks for files in the case of a
4550  bareword argument, there is a little extra functionality going on behind
4551  the scenes.  Before C<require> looks for a "F<.pm>" extension, it will
4552  first look for a similar filename with a "F<.pmc>" extension. If this file
4553  is found, it will be loaded in place of any file ending in a "F<.pm>"
4554  extension.
4555  
4556  You can also insert hooks into the import facility, by putting directly
4557  Perl code into the @INC array.  There are three forms of hooks: subroutine
4558  references, array references and blessed objects.
4559  
4560  Subroutine references are the simplest case.  When the inclusion system
4561  walks through @INC and encounters a subroutine, this subroutine gets
4562  called with two parameters, the first being a reference to itself, and the
4563  second the name of the file to be included (e.g. "F<Foo/Bar.pm>").  The
4564  subroutine should return nothing, or a list of up to three values in the
4565  following order:
4566  
4567  =over
4568  
4569  =item 1
4570  
4571  A filehandle, from which the file will be read.  
4572  
4573  =item 2
4574  
4575  A reference to a subroutine. If there is no filehandle (previous item),
4576  then this subroutine is expected to generate one line of source code per
4577  call, writing the line into C<$_> and returning 1, then returning 0 at
4578  "end of file". If there is a filehandle, then the subroutine will be
4579  called to act a simple source filter, with the line as read in C<$_>.
4580  Again, return 1 for each valid line, and 0 after all lines have been
4581  returned.
4582  
4583  =item 3
4584  
4585  Optional state for the subroutine. The state is passed in as C<$_[1]>. A
4586  reference to the subroutine itself is passed in as C<$_[0]>.
4587  
4588  =back
4589  
4590  If an empty list, C<undef>, or nothing that matches the first 3 values above
4591  is returned then C<require> will look at the remaining elements of @INC.
4592  Note that this file handle must be a real file handle (strictly a typeglob,
4593  or reference to a typeglob, blessed or unblessed) - tied file handles will be
4594  ignored and return value processing will stop there.
4595  
4596  If the hook is an array reference, its first element must be a subroutine
4597  reference.  This subroutine is called as above, but the first parameter is
4598  the array reference.  This enables to pass indirectly some arguments to
4599  the subroutine.
4600  
4601  In other words, you can write:
4602  
4603      push @INC, \&my_sub;
4604      sub my_sub {
4605      my ($coderef, $filename) = @_;    # $coderef is \&my_sub
4606      ...
4607      }
4608  
4609  or:
4610  
4611      push @INC, [ \&my_sub, $x, $y, ... ];
4612      sub my_sub {
4613      my ($arrayref, $filename) = @_;
4614      # Retrieve $x, $y, ...
4615      my @parameters = @$arrayref[1..$#$arrayref];
4616      ...
4617      }
4618  
4619  If the hook is an object, it must provide an INC method that will be
4620  called as above, the first parameter being the object itself.  (Note that
4621  you must fully qualify the sub's name, as unqualified C<INC> is always forced
4622  into package C<main>.)  Here is a typical code layout:
4623  
4624      # In Foo.pm
4625      package Foo;
4626      sub new { ... }
4627      sub Foo::INC {
4628      my ($self, $filename) = @_;
4629      ...
4630      }
4631  
4632      # In the main program
4633      push @INC, new Foo(...);
4634  
4635  Note that these hooks are also permitted to set the %INC entry
4636  corresponding to the files they have loaded. See L<perlvar/%INC>.
4637  
4638  For a yet-more-powerful import facility, see L</use> and L<perlmod>.
4639  
4640  =item reset EXPR
4641  X<reset>
4642  
4643  =item reset
4644  
4645  Generally used in a C<continue> block at the end of a loop to clear
4646  variables and reset C<??> searches so that they work again.  The
4647  expression is interpreted as a list of single characters (hyphens
4648  allowed for ranges).  All variables and arrays beginning with one of
4649  those letters are reset to their pristine state.  If the expression is
4650  omitted, one-match searches (C<?pattern?>) are reset to match again.  Resets
4651  only variables or searches in the current package.  Always returns
4652  1.  Examples:
4653  
4654      reset 'X';        # reset all X variables
4655      reset 'a-z';    # reset lower case variables
4656      reset;        # just reset ?one-time? searches
4657  
4658  Resetting C<"A-Z"> is not recommended because you'll wipe out your
4659  C<@ARGV> and C<@INC> arrays and your C<%ENV> hash.  Resets only package
4660  variables--lexical variables are unaffected, but they clean themselves
4661  up on scope exit anyway, so you'll probably want to use them instead.
4662  See L</my>.
4663  
4664  =item return EXPR
4665  X<return>
4666  
4667  =item return
4668  
4669  Returns from a subroutine, C<eval>, or C<do FILE> with the value
4670  given in EXPR.  Evaluation of EXPR may be in list, scalar, or void
4671  context, depending on how the return value will be used, and the context
4672  may vary from one execution to the next (see C<wantarray>).  If no EXPR
4673  is given, returns an empty list in list context, the undefined value in
4674  scalar context, and (of course) nothing at all in a void context.
4675  
4676  (Note that in the absence of an explicit C<return>, a subroutine, eval,
4677  or do FILE will automatically return the value of the last expression
4678  evaluated.)
4679  
4680  =item reverse LIST
4681  X<reverse> X<rev> X<invert>
4682  
4683  In list context, returns a list value consisting of the elements
4684  of LIST in the opposite order.  In scalar context, concatenates the
4685  elements of LIST and returns a string value with all characters
4686  in the opposite order.
4687  
4688      print reverse <>;        # line tac, last line first
4689  
4690      undef $/;            # for efficiency of <>
4691      print scalar reverse <>;    # character tac, last line tsrif
4692  
4693  Used without arguments in scalar context, reverse() reverses C<$_>.
4694  
4695  This operator is also handy for inverting a hash, although there are some
4696  caveats.  If a value is duplicated in the original hash, only one of those
4697  can be represented as a key in the inverted hash.  Also, this has to
4698  unwind one hash and build a whole new one, which may take some time
4699  on a large hash, such as from a DBM file.
4700  
4701      %by_name = reverse %by_address;    # Invert the hash
4702  
4703  =item rewinddir DIRHANDLE
4704  X<rewinddir>
4705  
4706  Sets the current position to the beginning of the directory for the
4707  C<readdir> routine on DIRHANDLE.
4708  
4709  =item rindex STR,SUBSTR,POSITION
4710  X<rindex>
4711  
4712  =item rindex STR,SUBSTR
4713  
4714  Works just like index() except that it returns the position of the I<last>
4715  occurrence of SUBSTR in STR.  If POSITION is specified, returns the
4716  last occurrence beginning at or before that position.
4717  
4718  =item rmdir FILENAME
4719  X<rmdir> X<rd> X<directory, remove>
4720  
4721  =item rmdir
4722  
4723  Deletes the directory specified by FILENAME if that directory is
4724  empty.  If it succeeds it returns true, otherwise it returns false and
4725  sets C<$!> (errno).  If FILENAME is omitted, uses C<$_>.
4726  
4727  To remove a directory tree recursively (C<rm -rf> on unix) look at
4728  the C<rmtree> function of the L<File::Path> module.
4729  
4730  =item s///
4731  
4732  The substitution operator.  See L<perlop>.
4733  
4734  =item say FILEHANDLE LIST
4735  X<say>
4736  
4737  =item say LIST
4738  
4739  =item say
4740  
4741  Just like C<print>, but implicitly appends a newline.
4742  C<say LIST> is simply an abbreviation for C<{ local $\ = "\n"; print
4743  LIST }>.
4744  
4745  This keyword is only available when the "say" feature is
4746  enabled: see L<feature>.
4747  
4748  =item scalar EXPR
4749  X<scalar> X<context>
4750  
4751  Forces EXPR to be interpreted in scalar context and returns the value
4752  of EXPR.
4753  
4754      @counts = ( scalar @a, scalar @b, scalar @c );
4755  
4756  There is no equivalent operator to force an expression to
4757  be interpolated in list context because in practice, this is never
4758  needed.  If you really wanted to do so, however, you could use
4759  the construction C<@{[ (some expression) ]}>, but usually a simple
4760  C<(some expression)> suffices.
4761  
4762  Because C<scalar> is unary operator, if you accidentally use for EXPR a
4763  parenthesized list, this behaves as a scalar comma expression, evaluating
4764  all but the last element in void context and returning the final element
4765  evaluated in scalar context.  This is seldom what you want.
4766  
4767  The following single statement:
4768  
4769      print uc(scalar(&foo,$bar)),$baz;
4770  
4771  is the moral equivalent of these two:
4772  
4773      &foo;
4774      print(uc($bar),$baz);
4775  
4776  See L<perlop> for more details on unary operators and the comma operator.
4777  
4778  =item seek FILEHANDLE,POSITION,WHENCE
4779  X<seek> X<fseek> X<filehandle, position>
4780  
4781  Sets FILEHANDLE's position, just like the C<fseek> call of C<stdio>.
4782  FILEHANDLE may be an expression whose value gives the name of the
4783  filehandle.  The values for WHENCE are C<0> to set the new position
4784  I<in bytes> to POSITION, C<1> to set it to the current position plus
4785  POSITION, and C<2> to set it to EOF plus POSITION (typically
4786  negative).  For WHENCE you may use the constants C<SEEK_SET>,
4787  C<SEEK_CUR>, and C<SEEK_END> (start of the file, current position, end
4788  of the file) from the Fcntl module.  Returns C<1> upon success, C<0>
4789  otherwise.
4790  
4791  Note the I<in bytes>: even if the filehandle has been set to
4792  operate on characters (for example by using the C<:encoding(utf8)> open
4793  layer), tell() will return byte offsets, not character offsets
4794  (because implementing that would render seek() and tell() rather slow).
4795  
4796  If you want to position file for C<sysread> or C<syswrite>, don't use
4797  C<seek>--buffering makes its effect on the file's system position
4798  unpredictable and non-portable.  Use C<sysseek> instead.
4799  
4800  Due to the rules and rigors of ANSI C, on some systems you have to do a
4801  seek whenever you switch between reading and writing.  Amongst other
4802  things, this may have the effect of calling stdio's clearerr(3).
4803  A WHENCE of C<1> (C<SEEK_CUR>) is useful for not moving the file position:
4804  
4805      seek(TEST,0,1);
4806  
4807  This is also useful for applications emulating C<tail -f>.  Once you hit
4808  EOF on your read, and then sleep for a while, you might have to stick in a
4809  seek() to reset things.  The C<seek> doesn't change the current position,
4810  but it I<does> clear the end-of-file condition on the handle, so that the
4811  next C<< <FILE> >> makes Perl try again to read something.  We hope.
4812  
4813  If that doesn't work (some IO implementations are particularly
4814  cantankerous), then you may need something more like this:
4815  
4816      for (;;) {
4817      for ($curpos = tell(FILE); $_ = <FILE>;
4818               $curpos = tell(FILE)) {
4819          # search for some stuff and put it into files
4820      }
4821      sleep($for_a_while);
4822      seek(FILE, $curpos, 0);
4823      }
4824  
4825  =item seekdir DIRHANDLE,POS
4826  X<seekdir>
4827  
4828  Sets the current position for the C<readdir> routine on DIRHANDLE.  POS
4829  must be a value returned by C<telldir>.  C<seekdir> also has the same caveats
4830  about possible directory compaction as the corresponding system library
4831  routine.
4832  
4833  =item select FILEHANDLE
4834  X<select> X<filehandle, default>
4835  
4836  =item select
4837  
4838  Returns the currently selected filehandle.  If FILEHANDLE is supplied,
4839  sets the new current default filehandle for output.  This has two
4840  effects: first, a C<write> or a C<print> without a filehandle will
4841  default to this FILEHANDLE.  Second, references to variables related to
4842  output will refer to this output channel.  For example, if you have to
4843  set the top of form format for more than one output channel, you might
4844  do the following:
4845  
4846      select(REPORT1);
4847      $^ = 'report1_top';
4848      select(REPORT2);
4849      $^ = 'report2_top';
4850  
4851  FILEHANDLE may be an expression whose value gives the name of the
4852  actual filehandle.  Thus:
4853  
4854      $oldfh = select(STDERR); $| = 1; select($oldfh);
4855  
4856  Some programmers may prefer to think of filehandles as objects with
4857  methods, preferring to write the last example as:
4858  
4859      use IO::Handle;
4860      STDERR->autoflush(1);
4861  
4862  =item select RBITS,WBITS,EBITS,TIMEOUT
4863  X<select>
4864  
4865  This calls the select(2) system call with the bit masks specified, which
4866  can be constructed using C<fileno> and C<vec>, along these lines:
4867  
4868      $rin = $win = $ein = '';
4869      vec($rin,fileno(STDIN),1) = 1;
4870      vec($win,fileno(STDOUT),1) = 1;
4871      $ein = $rin | $win;
4872  
4873  If you want to select on many filehandles you might wish to write a
4874  subroutine:
4875  
4876      sub fhbits {
4877      my(@fhlist) = split(' ',$_[0]);
4878      my($bits);
4879      for (@fhlist) {
4880          vec($bits,fileno($_),1) = 1;
4881      }
4882      $bits;
4883      }
4884      $rin = fhbits('STDIN TTY SOCK');
4885  
4886  The usual idiom is:
4887  
4888      ($nfound,$timeleft) =
4889        select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
4890  
4891  or to block until something becomes ready just do this
4892  
4893      $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
4894  
4895  Most systems do not bother to return anything useful in $timeleft, so
4896  calling select() in scalar context just returns $nfound.
4897  
4898  Any of the bit masks can also be undef.  The timeout, if specified, is
4899  in seconds, which may be fractional.  Note: not all implementations are
4900  capable of returning the $timeleft.  If not, they always return
4901  $timeleft equal to the supplied $timeout.
4902  
4903  You can effect a sleep of 250 milliseconds this way:
4904  
4905      select(undef, undef, undef, 0.25);
4906  
4907  Note that whether C<select> gets restarted after signals (say, SIGALRM)
4908  is implementation-dependent.  See also L<perlport> for notes on the
4909  portability of C<select>.
4910  
4911  On error, C<select> behaves like the select(2) system call : it returns
4912  -1 and sets C<$!>.
4913  
4914  Note: on some Unixes, the select(2) system call may report a socket file
4915  descriptor as "ready for reading", when actually no data is available,
4916  thus a subsequent read blocks. It can be avoided using always the
4917  O_NONBLOCK flag on the socket. See select(2) and fcntl(2) for further
4918  details.
4919  
4920  B<WARNING>: One should not attempt to mix buffered I/O (like C<read>
4921  or <FH>) with C<select>, except as permitted by POSIX, and even
4922  then only on POSIX systems.  You have to use C<sysread> instead.
4923  
4924  =item semctl ID,SEMNUM,CMD,ARG
4925  X<semctl>
4926  
4927  Calls the System V IPC function C<semctl>.  You'll probably have to say
4928  
4929      use IPC::SysV;
4930  
4931  first to get the correct constant definitions.  If CMD is IPC_STAT or
4932  GETALL, then ARG must be a variable that will hold the returned
4933  semid_ds structure or semaphore value array.  Returns like C<ioctl>:
4934  the undefined value for error, "C<0 but true>" for zero, or the actual
4935  return value otherwise.  The ARG must consist of a vector of native
4936  short integers, which may be created with C<pack("s!",(0)x$nsem)>.
4937  See also L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::Semaphore>
4938  documentation.
4939  
4940  =item semget KEY,NSEMS,FLAGS
4941  X<semget>
4942  
4943  Calls the System V IPC function semget.  Returns the semaphore id, or
4944  the undefined value if there is an error.  See also
4945  L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::SysV::Semaphore>
4946  documentation.
4947  
4948  =item semop KEY,OPSTRING
4949  X<semop>
4950  
4951  Calls the System V IPC function semop to perform semaphore operations
4952  such as signalling and waiting.  OPSTRING must be a packed array of
4953  semop structures.  Each semop structure can be generated with
4954  C<pack("s!3", $semnum, $semop, $semflag)>.  The length of OPSTRING 
4955  implies the number of semaphore operations.  Returns true if
4956  successful, or false if there is an error.  As an example, the
4957  following code waits on semaphore $semnum of semaphore id $semid:
4958  
4959      $semop = pack("s!3", $semnum, -1, 0);
4960      die "Semaphore trouble: $!\n" unless semop($semid, $semop);
4961  
4962  To signal the semaphore, replace C<-1> with C<1>.  See also
4963  L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::SysV::Semaphore>
4964  documentation.
4965  
4966  =item send SOCKET,MSG,FLAGS,TO
4967  X<send>
4968  
4969  =item send SOCKET,MSG,FLAGS
4970  
4971  Sends a message on a socket.  Attempts to send the scalar MSG to the
4972  SOCKET filehandle.  Takes the same flags as the system call of the
4973  same name.  On unconnected sockets you must specify a destination to
4974  send TO, in which case it does a C C<sendto>.  Returns the number of
4975  characters sent, or the undefined value if there is an error.  The C
4976  system call sendmsg(2) is currently unimplemented.  See
4977  L<perlipc/"UDP: Message Passing"> for examples.
4978  
4979  Note the I<characters>: depending on the status of the socket, either
4980  (8-bit) bytes or characters are sent.  By default all sockets operate
4981  on bytes, but for example if the socket has been changed using
4982  binmode() to operate with the C<:encoding(utf8)> I/O layer (see
4983  L</open>, or the C<open> pragma, L<open>), the I/O will operate on UTF-8
4984  encoded Unicode characters, not bytes.  Similarly for the C<:encoding>
4985  pragma: in that case pretty much any characters can be sent.
4986  
4987  =item setpgrp PID,PGRP
4988  X<setpgrp> X<group>
4989  
4990  Sets the current process group for the specified PID, C<0> for the current
4991  process.  Will produce a fatal error if used on a machine that doesn't
4992  implement POSIX setpgid(2) or BSD setpgrp(2).  If the arguments are omitted,
4993  it defaults to C<0,0>.  Note that the BSD 4.2 version of C<setpgrp> does not
4994  accept any arguments, so only C<setpgrp(0,0)> is portable.  See also
4995  C<POSIX::setsid()>.
4996  
4997  =item setpriority WHICH,WHO,PRIORITY
4998  X<setpriority> X<priority> X<nice> X<renice>
4999  
5000  Sets the current priority for a process, a process group, or a user.
5001  (See setpriority(2).)  Will produce a fatal error if used on a machine
5002  that doesn't implement setpriority(2).
5003  
5004  =item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
5005  X<setsockopt>
5006  
5007  Sets the socket option requested.  Returns undefined if there is an
5008  error.  Use integer constants provided by the C<Socket> module for
5009  LEVEL and OPNAME.  Values for LEVEL can also be obtained from
5010  getprotobyname.  OPTVAL might either be a packed string or an integer.
5011  An integer OPTVAL is shorthand for pack("i", OPTVAL).
5012  
5013  An example disabling the Nagle's algorithm for a socket:
5014  
5015      use Socket qw(IPPROTO_TCP TCP_NODELAY);
5016      setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
5017  
5018  =item shift ARRAY
5019  X<shift>
5020  
5021  =item shift
5022  
5023  Shifts the first value of the array off and returns it, shortening the
5024  array by 1 and moving everything down.  If there are no elements in the
5025  array, returns the undefined value.  If ARRAY is omitted, shifts the
5026  C<@_> array within the lexical scope of subroutines and formats, and the
5027  C<@ARGV> array outside of a subroutine and also within the lexical scopes
5028  established by the C<eval STRING>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>,
5029  C<UNITCHECK {}> and C<END {}> constructs.
5030  
5031  See also C<unshift>, C<push>, and C<pop>.  C<shift> and C<unshift> do the
5032  same thing to the left end of an array that C<pop> and C<push> do to the
5033  right end.
5034  
5035  =item shmctl ID,CMD,ARG
5036  X<shmctl>
5037  
5038  Calls the System V IPC function shmctl.  You'll probably have to say
5039  
5040      use IPC::SysV;
5041  
5042  first to get the correct constant definitions.  If CMD is C<IPC_STAT>,
5043  then ARG must be a variable that will hold the returned C<shmid_ds>
5044  structure.  Returns like ioctl: the undefined value for error, "C<0> but
5045  true" for zero, or the actual return value otherwise.
5046  See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
5047  
5048  =item shmget KEY,SIZE,FLAGS
5049  X<shmget>
5050  
5051  Calls the System V IPC function shmget.  Returns the shared memory
5052  segment id, or the undefined value if there is an error.
5053  See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
5054  
5055  =item shmread ID,VAR,POS,SIZE
5056  X<shmread>
5057  X<shmwrite>
5058  
5059  =item shmwrite ID,STRING,POS,SIZE
5060  
5061  Reads or writes the System V shared memory segment ID starting at
5062  position POS for size SIZE by attaching to it, copying in/out, and
5063  detaching from it.  When reading, VAR must be a variable that will
5064  hold the data read.  When writing, if STRING is too long, only SIZE
5065  bytes are used; if STRING is too short, nulls are written to fill out
5066  SIZE bytes.  Return true if successful, or false if there is an error.
5067  shmread() taints the variable. See also L<perlipc/"SysV IPC">,
5068  C<IPC::SysV> documentation, and the C<IPC::Shareable> module from CPAN.
5069  
5070  =item shutdown SOCKET,HOW
5071  X<shutdown>
5072  
5073  Shuts down a socket connection in the manner indicated by HOW, which
5074  has the same interpretation as in the system call of the same name.
5075  
5076      shutdown(SOCKET, 0);    # I/we have stopped reading data
5077      shutdown(SOCKET, 1);    # I/we have stopped writing data
5078      shutdown(SOCKET, 2);    # I/we have stopped using this socket
5079  
5080  This is useful with sockets when you want to tell the other
5081  side you're done writing but not done reading, or vice versa.
5082  It's also a more insistent form of close because it also
5083  disables the file descriptor in any forked copies in other
5084  processes.
5085  
5086  =item sin EXPR
5087  X<sin> X<sine> X<asin> X<arcsine>
5088  
5089  =item sin
5090  
5091  Returns the sine of EXPR (expressed in radians).  If EXPR is omitted,
5092  returns sine of C<$_>.
5093  
5094  For the inverse sine operation, you may use the C<Math::Trig::asin>
5095  function, or use this relation:
5096  
5097      sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
5098  
5099  =item sleep EXPR
5100  X<sleep> X<pause>
5101  
5102  =item sleep
5103  
5104  Causes the script to sleep for EXPR seconds, or forever if no EXPR.
5105  May be interrupted if the process receives a signal such as C<SIGALRM>.
5106  Returns the number of seconds actually slept.  You probably cannot
5107  mix C<alarm> and C<sleep> calls, because C<sleep> is often implemented
5108  using C<alarm>.
5109  
5110  On some older systems, it may sleep up to a full second less than what
5111  you requested, depending on how it counts seconds.  Most modern systems
5112  always sleep the full amount.  They may appear to sleep longer than that,
5113  however, because your process might not be scheduled right away in a
5114  busy multitasking system.
5115  
5116  For delays of finer granularity than one second, the Time::HiRes module
5117  (from CPAN, and starting from Perl 5.8 part of the standard
5118  distribution) provides usleep().  You may also use Perl's four-argument
5119  version of select() leaving the first three arguments undefined, or you
5120  might be able to use the C<syscall> interface to access setitimer(2) if
5121  your system supports it. See L<perlfaq8> for details.
5122  
5123  See also the POSIX module's C<pause> function.
5124  
5125  =item socket SOCKET,DOMAIN,TYPE,PROTOCOL
5126  X<socket>
5127  
5128  Opens a socket of the specified kind and attaches it to filehandle
5129  SOCKET.  DOMAIN, TYPE, and PROTOCOL are specified the same as for
5130  the system call of the same name.  You should C<use Socket> first
5131  to get the proper definitions imported.  See the examples in
5132  L<perlipc/"Sockets: Client/Server Communication">.
5133  
5134  On systems that support a close-on-exec flag on files, the flag will
5135  be set for the newly opened file descriptor, as determined by the
5136  value of $^F.  See L<perlvar/$^F>.
5137  
5138  =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
5139  X<socketpair>
5140  
5141  Creates an unnamed pair of sockets in the specified domain, of the
5142  specified type.  DOMAIN, TYPE, and PROTOCOL are specified the same as
5143  for the system call of the same name.  If unimplemented, yields a fatal
5144  error.  Returns true if successful.
5145  
5146  On systems that support a close-on-exec flag on files, the flag will
5147  be set for the newly opened file descriptors, as determined by the value
5148  of $^F.  See L<perlvar/$^F>.
5149  
5150  Some systems defined C<pipe> in terms of C<socketpair>, in which a call
5151  to C<pipe(Rdr, Wtr)> is essentially:
5152  
5153      use Socket;
5154      socketpair(Rdr, Wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC);
5155      shutdown(Rdr, 1);        # no more writing for reader
5156      shutdown(Wtr, 0);        # no more reading for writer
5157  
5158  See L<perlipc> for an example of socketpair use.  Perl 5.8 and later will
5159  emulate socketpair using IP sockets to localhost if your system implements
5160  sockets but not socketpair.
5161  
5162  =item sort SUBNAME LIST
5163  X<sort> X<qsort> X<quicksort> X<mergesort>
5164  
5165  =item sort BLOCK LIST
5166  
5167  =item sort LIST
5168  
5169  In list context, this sorts the LIST and returns the sorted list value.
5170  In scalar context, the behaviour of C<sort()> is undefined.
5171  
5172  If SUBNAME or BLOCK is omitted, C<sort>s in standard string comparison
5173  order.  If SUBNAME is specified, it gives the name of a subroutine
5174  that returns an integer less than, equal to, or greater than C<0>,
5175  depending on how the elements of the list are to be ordered.  (The C<<
5176  <=> >> and C<cmp> operators are extremely useful in such routines.)
5177  SUBNAME may be a scalar variable name (unsubscripted), in which case
5178  the value provides the name of (or a reference to) the actual
5179  subroutine to use.  In place of a SUBNAME, you can provide a BLOCK as
5180  an anonymous, in-line sort subroutine.
5181  
5182  If the subroutine's prototype is C<($$)>, the elements to be compared
5183  are passed by reference in C<@_>, as for a normal subroutine.  This is
5184  slower than unprototyped subroutines, where the elements to be
5185  compared are passed into the subroutine
5186  as the package global variables $a and $b (see example below).  Note that
5187  in the latter case, it is usually counter-productive to declare $a and
5188  $b as lexicals.
5189  
5190  The values to be compared are always passed by reference and should not
5191  be modified.
5192  
5193  You also cannot exit out of the sort block or subroutine using any of the
5194  loop control operators described in L<perlsyn> or with C<goto>.
5195  
5196  When C<use locale> is in effect, C<sort LIST> sorts LIST according to the
5197  current collation locale.  See L<perllocale>.
5198  
5199  sort() returns aliases into the original list, much as a for loop's index
5200  variable aliases the list elements.  That is, modifying an element of a
5201  list returned by sort() (for example, in a C<foreach>, C<map> or C<grep>)
5202  actually modifies the element in the original list.  This is usually
5203  something to be avoided when writing clear code.
5204  
5205  Perl 5.6 and earlier used a quicksort algorithm to implement sort.
5206  That algorithm was not stable, and I<could> go quadratic.  (A I<stable> sort
5207  preserves the input order of elements that compare equal.  Although
5208  quicksort's run time is O(NlogN) when averaged over all arrays of
5209  length N, the time can be O(N**2), I<quadratic> behavior, for some
5210  inputs.)  In 5.7, the quicksort implementation was replaced with
5211  a stable mergesort algorithm whose worst-case behavior is O(NlogN).
5212  But benchmarks indicated that for some inputs, on some platforms,
5213  the original quicksort was faster.  5.8 has a sort pragma for
5214  limited control of the sort.  Its rather blunt control of the
5215  underlying algorithm may not persist into future Perls, but the
5216  ability to characterize the input or output in implementation
5217  independent ways quite probably will.  See L<sort>.
5218  
5219  Examples:
5220  
5221      # sort lexically
5222      @articles = sort @files;
5223  
5224      # same thing, but with explicit sort routine
5225      @articles = sort {$a cmp $b} @files;
5226  
5227      # now case-insensitively
5228      @articles = sort {uc($a) cmp uc($b)} @files;
5229  
5230      # same thing in reversed order
5231      @articles = sort {$b cmp $a} @files;
5232  
5233      # sort numerically ascending
5234      @articles = sort {$a <=> $b} @files;
5235  
5236      # sort numerically descending
5237      @articles = sort {$b <=> $a} @files;
5238  
5239      # this sorts the %age hash by value instead of key
5240      # using an in-line function
5241      @eldest = sort { $age{$b} <=> $age{$a} } keys %age;
5242  
5243      # sort using explicit subroutine name
5244      sub byage {
5245      $age{$a} <=> $age{$b};    # presuming numeric
5246      }
5247      @sortedclass = sort byage @class;
5248  
5249      sub backwards { $b cmp $a }
5250      @harry  = qw(dog cat x Cain Abel);
5251      @george = qw(gone chased yz Punished Axed);
5252      print sort @harry;
5253          # prints AbelCaincatdogx
5254      print sort backwards @harry;
5255          # prints xdogcatCainAbel
5256      print sort @george, 'to', @harry;
5257          # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
5258  
5259      # inefficiently sort by descending numeric compare using
5260      # the first integer after the first = sign, or the
5261      # whole record case-insensitively otherwise
5262  
5263      @new = sort {
5264      ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
5265                  ||
5266                  uc($a)  cmp  uc($b)
5267      } @old;
5268  
5269      # same thing, but much more efficiently;
5270      # we'll build auxiliary indices instead
5271      # for speed
5272      @nums = @caps = ();
5273      for (@old) {
5274      push @nums, /=(\d+)/;
5275      push @caps, uc($_);
5276      }
5277  
5278      @new = @old[ sort {
5279              $nums[$b] <=> $nums[$a]
5280                   ||
5281              $caps[$a] cmp $caps[$b]
5282                 } 0..$#old
5283             ];
5284  
5285      # same thing, but without any temps
5286      @new = map { $_->[0] }
5287             sort { $b->[1] <=> $a->[1]
5288                             ||
5289                    $a->[2] cmp $b->[2]
5290             } map { [$_, /=(\d+)/, uc($_)] } @old;
5291  
5292      # using a prototype allows you to use any comparison subroutine
5293      # as a sort subroutine (including other package's subroutines)
5294      package other;
5295      sub backwards ($$) { $_[1] cmp $_[0]; }    # $a and $b are not set here
5296  
5297      package main;
5298      @new = sort other::backwards @old;
5299  
5300      # guarantee stability, regardless of algorithm
5301      use sort 'stable';
5302      @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
5303  
5304      # force use of mergesort (not portable outside Perl 5.8)
5305      use sort '_mergesort';  # note discouraging _
5306      @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
5307  
5308  If you're using strict, you I<must not> declare $a
5309  and $b as lexicals.  They are package globals.  That means
5310  if you're in the C<main> package and type
5311  
5312      @articles = sort {$b <=> $a} @files;
5313  
5314  then C<$a> and C<$b> are C<$main::a> and C<$main::b> (or C<$::a> and C<$::b>),
5315  but if you're in the C<FooPack> package, it's the same as typing
5316  
5317      @articles = sort {$FooPack::b <=> $FooPack::a} @files;
5318  
5319  The comparison function is required to behave.  If it returns
5320  inconsistent results (sometimes saying C<$x[1]> is less than C<$x[2]> and
5321  sometimes saying the opposite, for example) the results are not
5322  well-defined.
5323  
5324  Because C<< <=> >> returns C<undef> when either operand is C<NaN>
5325  (not-a-number), and because C<sort> will trigger a fatal error unless the
5326  result of a comparison is defined, when sorting with a comparison function
5327  like C<< $a <=> $b >>, be careful about lists that might contain a C<NaN>.
5328  The following example takes advantage of the fact that C<NaN != NaN> to
5329  eliminate any C<NaN>s from the input.
5330  
5331      @result = sort { $a <=> $b } grep { $_ == $_ } @input;
5332  
5333  =item splice ARRAY,OFFSET,LENGTH,LIST
5334  X<splice>
5335  
5336  =item splice ARRAY,OFFSET,LENGTH
5337  
5338  =item splice ARRAY,OFFSET
5339  
5340  =item splice ARRAY
5341  
5342  Removes the elements designated by OFFSET and LENGTH from an array, and
5343  replaces them with the elements of LIST, if any.  In list context,
5344  returns the elements removed from the array.  In scalar context,
5345  returns the last element removed, or C<undef> if no elements are
5346  removed.  The array grows or shrinks as necessary.
5347  If OFFSET is negative then it starts that far from the end of the array.
5348  If LENGTH is omitted, removes everything from OFFSET onward.
5349  If LENGTH is negative, removes the elements from OFFSET onward
5350  except for -LENGTH elements at the end of the array.
5351  If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is
5352  past the end of the array, perl issues a warning, and splices at the
5353  end of the array.
5354  
5355  The following equivalences hold (assuming C<< $[ == 0 and $#a >= $i >> )
5356  
5357      push(@a,$x,$y)    splice(@a,@a,0,$x,$y)
5358      pop(@a)        splice(@a,-1)
5359      shift(@a)        splice(@a,0,1)
5360      unshift(@a,$x,$y)    splice(@a,0,0,$x,$y)
5361      $a[$i] = $y        splice(@a,$i,1,$y)
5362  
5363  Example, assuming array lengths are passed before arrays:
5364  
5365      sub aeq {    # compare two list values
5366      my(@a) = splice(@_,0,shift);
5367      my(@b) = splice(@_,0,shift);
5368      return 0 unless @a == @b;    # same len?
5369      while (@a) {
5370          return 0 if pop(@a) ne pop(@b);
5371      }
5372      return 1;
5373      }
5374      if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
5375  
5376  =item split /PATTERN/,EXPR,LIMIT
5377  X<split>
5378  
5379  =item split /PATTERN/,EXPR
5380  
5381  =item split /PATTERN/
5382  
5383  =item split
5384  
5385  Splits the string EXPR into a list of strings and returns that list.  By
5386  default, empty leading fields are preserved, and empty trailing ones are
5387  deleted.  (If all fields are empty, they are considered to be trailing.)
5388  
5389  In scalar context, returns the number of fields found and splits into
5390  the C<@_> array.  Use of split in scalar context is deprecated, however,
5391  because it clobbers your subroutine arguments.
5392  
5393  If EXPR is omitted, splits the C<$_> string.  If PATTERN is also omitted,
5394  splits on whitespace (after skipping any leading whitespace).  Anything
5395  matching PATTERN is taken to be a delimiter separating the fields.  (Note
5396  that the delimiter may be longer than one character.)
5397  
5398  If LIMIT is specified and positive, it represents the maximum number
5399  of fields the EXPR will be split into, though the actual number of
5400  fields returned depends on the number of times PATTERN matches within
5401  EXPR.  If LIMIT is unspecified or zero, trailing null fields are
5402  stripped (which potential users of C<pop> would do well to remember).
5403  If LIMIT is negative, it is treated as if an arbitrarily large LIMIT
5404  had been specified.  Note that splitting an EXPR that evaluates to the
5405  empty string always returns the empty list, regardless of the LIMIT
5406  specified.
5407  
5408  A pattern matching the null string (not to be confused with
5409  a null pattern C<//>, which is just one member of the set of patterns
5410  matching a null string) will split the value of EXPR into separate
5411  characters at each point it matches that way.  For example:
5412  
5413      print join(':', split(/ */, 'hi there'));
5414  
5415  produces the output 'h:i:t:h:e:r:e'.
5416  
5417  As a special case for C<split>, using the empty pattern C<//> specifically
5418  matches only the null string, and is not be confused with the regular use
5419  of C<//> to mean "the last successful pattern match".  So, for C<split>,
5420  the following:
5421  
5422      print join(':', split(//, 'hi there'));
5423  
5424  produces the output 'h:i: :t:h:e:r:e'.
5425  
5426  Empty leading fields are produced when there are positive-width matches at
5427  the beginning of the string; a zero-width match at the beginning of
5428  the string does not produce an empty field. For example:
5429  
5430     print join(':', split(/(?=\w)/, 'hi there!'));
5431  
5432  produces the output 'h:i :t:h:e:r:e!'. Empty trailing fields, on the other
5433  hand, are produced when there is a match at the end of the string (and
5434  when LIMIT is given and is not 0), regardless of the length of the match.
5435  For example:
5436  
5437     print join(':', split(//,   'hi there!', -1));
5438     print join(':', split(/\W/, 'hi there!', -1));
5439  
5440  produce the output 'h:i: :t:h:e:r:e:!:' and 'hi:there:', respectively,
5441  both with an empty trailing field.
5442  
5443  The LIMIT parameter can be used to split a line partially
5444  
5445      ($login, $passwd, $remainder) = split(/:/, $_, 3);
5446  
5447  When assigning to a list, if LIMIT is omitted, or zero, Perl supplies
5448  a LIMIT one larger than the number of variables in the list, to avoid
5449  unnecessary work.  For the list above LIMIT would have been 4 by
5450  default.  In time critical applications it behooves you not to split
5451  into more fields than you really need.
5452  
5453  If the PATTERN contains parentheses, additional list elements are
5454  created from each matching substring in the delimiter.
5455  
5456      split(/([,-])/, "1-10,20", 3);
5457  
5458  produces the list value
5459  
5460      (1, '-', 10, ',', 20)
5461  
5462  If you had the entire header of a normal Unix email message in $header,
5463  you could split it up into fields and their values this way:
5464  
5465      $header =~ s/\n\s+/ /g;  # fix continuation lines
5466      %hdrs   =  (UNIX_FROM => split /^(\S*?):\s*/m, $header);
5467  
5468  The pattern C</PATTERN/> may be replaced with an expression to specify
5469  patterns that vary at runtime.  (To do runtime compilation only once,
5470  use C</$variable/o>.)
5471  
5472  As a special case, specifying a PATTERN of space (S<C<' '>>) will split on
5473  white space just as C<split> with no arguments does.  Thus, S<C<split(' ')>> can
5474  be used to emulate B<awk>'s default behavior, whereas S<C<split(/ /)>>
5475  will give you as many null initial fields as there are leading spaces.
5476  A C<split> on C</\s+/> is like a S<C<split(' ')>> except that any leading
5477  whitespace produces a null first field.  A C<split> with no arguments
5478  really does a S<C<split(' ', $_)>> internally.
5479  
5480  A PATTERN of C</^/> is treated as if it were C</^/m>, since it isn't
5481  much use otherwise.
5482  
5483  Example:
5484  
5485      open(PASSWD, '/etc/passwd');
5486      while (<PASSWD>) {
5487          chomp;
5488          ($login, $passwd, $uid, $gid,
5489           $gcos, $home, $shell) = split(/:/);
5490      #...
5491      }
5492  
5493  As with regular pattern matching, any capturing parentheses that are not
5494  matched in a C<split()> will be set to C<undef> when returned:
5495  
5496      @fields = split /(A)|B/, "1A2B3";
5497      # @fields is (1, 'A', 2, undef, 3)
5498  
5499  =item sprintf FORMAT, LIST
5500  X<sprintf>
5501  
5502  Returns a string formatted by the usual C<printf> conventions of the C
5503  library function C<sprintf>.  See below for more details
5504  and see L<sprintf(3)> or L<printf(3)> on your system for an explanation of
5505  the general principles.
5506  
5507  For example:
5508  
5509          # Format number with up to 8 leading zeroes
5510          $result = sprintf("%08d", $number);
5511  
5512          # Round number to 3 digits after decimal point
5513          $rounded = sprintf("%.3f", $number);
5514  
5515  Perl does its own C<sprintf> formatting--it emulates the C
5516  function C<sprintf>, but it doesn't use it (except for floating-point
5517  numbers, and even then only the standard modifiers are allowed).  As a
5518  result, any non-standard extensions in your local C<sprintf> are not
5519  available from Perl.
5520  
5521  Unlike C<printf>, C<sprintf> does not do what you probably mean when you
5522  pass it an array as your first argument. The array is given scalar context,
5523  and instead of using the 0th element of the array as the format, Perl will
5524  use the count of elements in the array as the format, which is almost never
5525  useful.
5526  
5527  Perl's C<sprintf> permits the following universally-known conversions:
5528  
5529     %%    a percent sign
5530     %c    a character with the given number
5531     %s    a string
5532     %d    a signed integer, in decimal
5533     %u    an unsigned integer, in decimal
5534     %o    an unsigned integer, in octal
5535     %x    an unsigned integer, in hexadecimal
5536     %e    a floating-point number, in scientific notation
5537     %f    a floating-point number, in fixed decimal notation
5538     %g    a floating-point number, in %e or %f notation
5539  
5540  In addition, Perl permits the following widely-supported conversions:
5541  
5542     %X    like %x, but using upper-case letters
5543     %E    like %e, but using an upper-case "E"
5544     %G    like %g, but with an upper-case "E" (if applicable)
5545     %b    an unsigned integer, in binary
5546     %B    like %b, but using an upper-case "B" with the # flag
5547     %p    a pointer (outputs the Perl value's address in hexadecimal)
5548     %n    special: *stores* the number of characters output so far
5549          into the next variable in the parameter list
5550  
5551  Finally, for backward (and we do mean "backward") compatibility, Perl
5552  permits these unnecessary but widely-supported conversions:
5553  
5554     %i    a synonym for %d
5555     %D    a synonym for %ld
5556     %U    a synonym for %lu
5557     %O    a synonym for %lo
5558     %F    a synonym for %f
5559  
5560  Note that the number of exponent digits in the scientific notation produced
5561  by C<%e>, C<%E>, C<%g> and C<%G> for numbers with the modulus of the
5562  exponent less than 100 is system-dependent: it may be three or less
5563  (zero-padded as necessary).  In other words, 1.23 times ten to the
5564  99th may be either "1.23e99" or "1.23e099".
5565  
5566  Between the C<%> and the format letter, you may specify a number of
5567  additional attributes controlling the interpretation of the format.
5568  In order, these are:
5569  
5570  =over 4
5571  
5572  =item format parameter index
5573  
5574  An explicit format parameter index, such as C<2$>. By default sprintf
5575  will format the next unused argument in the list, but this allows you
5576  to take the arguments out of order, e.g.:
5577  
5578    printf '%2$d %1$d', 12, 34;      # prints "34 12"
5579    printf '%3$d %d %1$d', 1, 2, 3;  # prints "3 1 1"
5580  
5581  =item flags
5582  
5583  one or more of:
5584  
5585     space   prefix positive number with a space
5586     +       prefix positive number with a plus sign
5587     -       left-justify within the field
5588     0       use zeros, not spaces, to right-justify
5589     #       ensure the leading "0" for any octal,
5590             prefix non-zero hexadecimal with "0x" or "0X",
5591             prefix non-zero binary with "0b" or "0B"
5592  
5593  For example:
5594  
5595    printf '<% d>',  12;   # prints "< 12>"
5596    printf '<%+d>',  12;   # prints "<+12>"
5597    printf '<%6s>',  12;   # prints "<    12>"
5598    printf '<%-6s>', 12;   # prints "<12    >"
5599    printf '<%06s>', 12;   # prints "<000012>"
5600    printf '<%#o>',  12;   # prints "<014>"
5601    printf '<%#x>',  12;   # prints "<0xc>"
5602    printf '<%#X>',  12;   # prints "<0XC>"
5603    printf '<%#b>',  12;   # prints "<0b1100>"
5604    printf '<%#B>',  12;   # prints "<0B1100>"
5605  
5606  When a space and a plus sign are given as the flags at once,
5607  a plus sign is used to prefix a positive number.
5608  
5609    printf '<%+ d>', 12;   # prints "<+12>"
5610    printf '<% +d>', 12;   # prints "<+12>"
5611  
5612  When the # flag and a precision are given in the %o conversion,
5613  the precision is incremented if it's necessary for the leading "0".
5614  
5615    printf '<%#.5o>', 012;      # prints "<00012>"
5616    printf '<%#.5o>', 012345;   # prints "<012345>"
5617    printf '<%#.0o>', 0;        # prints "<0>"
5618  
5619  =item vector flag
5620  
5621  This flag tells perl to interpret the supplied string as a vector of
5622  integers, one for each character in the string. Perl applies the format to
5623  each integer in turn, then joins the resulting strings with a separator (a
5624  dot C<.> by default). This can be useful for displaying ordinal values of
5625  characters in arbitrary strings:
5626  
5627    printf "%vd", "AB\x{100}";           # prints "65.66.256"
5628    printf "version is v%vd\n", $^V;     # Perl's version
5629  
5630  Put an asterisk C<*> before the C<v> to override the string to
5631  use to separate the numbers:
5632  
5633    printf "address is %*vX\n", ":", $addr;   # IPv6 address
5634    printf "bits are %0*v8b\n", " ", $bits;   # random bitstring
5635  
5636  You can also explicitly specify the argument number to use for
5637  the join string using e.g. C<*2$v>:
5638  
5639    printf '%*4$vX %*4$vX %*4$vX', @addr[1..3], ":";   # 3 IPv6 addresses
5640  
5641  =item (minimum) width
5642  
5643  Arguments are usually formatted to be only as wide as required to
5644  display the given value. You can override the width by putting
5645  a number here, or get the width from the next argument (with C<*>)
5646  or from a specified argument (with e.g. C<*2$>):
5647  
5648    printf '<%s>', "a";       # prints "<a>"
5649    printf '<%6s>', "a";      # prints "<     a>"
5650    printf '<%*s>', 6, "a";   # prints "<     a>"
5651    printf '<%*2$s>', "a", 6; # prints "<     a>"
5652    printf '<%2s>', "long";   # prints "<long>" (does not truncate)
5653  
5654  If a field width obtained through C<*> is negative, it has the same
5655  effect as the C<-> flag: left-justification.
5656  
5657  =item precision, or maximum width
5658  X<precision>
5659  
5660  You can specify a precision (for numeric conversions) or a maximum
5661  width (for string conversions) by specifying a C<.> followed by a number.
5662  For floating point formats, with the exception of 'g' and 'G', this specifies
5663  the number of decimal places to show (the default being 6), e.g.:
5664  
5665    # these examples are subject to system-specific variation
5666    printf '<%f>', 1;    # prints "<1.000000>"
5667    printf '<%.1f>', 1;  # prints "<1.0>"
5668    printf '<%.0f>', 1;  # prints "<1>"
5669    printf '<%e>', 10;   # prints "<1.000000e+01>"
5670    printf '<%.1e>', 10; # prints "<1.0e+01>"
5671  
5672  For 'g' and 'G', this specifies the maximum number of digits to show,
5673  including prior to the decimal point as well as after it, e.g.:
5674  
5675    # these examples are subject to system-specific variation
5676    printf '<%g>', 1;        # prints "<1>"
5677    printf '<%.10g>', 1;     # prints "<1>"
5678    printf '<%g>', 100;      # prints "<100>"
5679    printf '<%.1g>', 100;    # prints "<1e+02>"
5680    printf '<%.2g>', 100.01; # prints "<1e+02>"
5681    printf '<%.5g>', 100.01; # prints "<100.01>"
5682    printf '<%.4g>', 100.01; # prints "<100>"
5683  
5684  For integer conversions, specifying a precision implies that the
5685  output of the number itself should be zero-padded to this width,
5686  where the 0 flag is ignored:
5687  
5688    printf '<%.6d>', 1;      # prints "<000001>"
5689    printf '<%+.6d>', 1;     # prints "<+000001>"
5690    printf '<%-10.6d>', 1;   # prints "<000001    >"
5691    printf '<%10.6d>', 1;    # prints "<    000001>"
5692    printf '<%010.6d>', 1;   # prints "<    000001>"
5693    printf '<%+10.6d>', 1;   # prints "<   +000001>"
5694  
5695    printf '<%.6x>', 1;      # prints "<000001>"
5696    printf '<%#.6x>', 1;     # prints "<0x000001>"
5697    printf '<%-10.6x>', 1;   # prints "<000001    >"
5698    printf '<%10.6x>', 1;    # prints "<    000001>"
5699    printf '<%010.6x>', 1;   # prints "<    000001>"
5700    printf '<%#10.6x>', 1;   # prints "<  0x000001>"
5701  
5702  For string conversions, specifying a precision truncates the string
5703  to fit in the specified width:
5704  
5705    printf '<%.5s>', "truncated";   # prints "<trunc>"
5706    printf '<%10.5s>', "truncated"; # prints "<     trunc>"
5707  
5708  You can also get the precision from the next argument using C<.*>:
5709  
5710    printf '<%.6x>', 1;       # prints "<000001>"
5711    printf '<%.*x>', 6, 1;    # prints "<000001>"
5712  
5713  If a precision obtained through C<*> is negative, it has the same
5714  effect as no precision.
5715  
5716    printf '<%.*s>',  7, "string";   # prints "<string>"
5717    printf '<%.*s>',  3, "string";   # prints "<str>"
5718    printf '<%.*s>',  0, "string";   # prints "<>"
5719    printf '<%.*s>', -1, "string";   # prints "<string>"
5720  
5721    printf '<%.*d>',  1, 0;   # prints "<0>"
5722    printf '<%.*d>',  0, 0;   # prints "<>"
5723    printf '<%.*d>', -1, 0;   # prints "<0>"
5724  
5725  You cannot currently get the precision from a specified number,
5726  but it is intended that this will be possible in the future using
5727  e.g. C<.*2$>:
5728  
5729    printf '<%.*2$x>', 1, 6;   # INVALID, but in future will print "<000001>"
5730  
5731  =item size
5732  
5733  For numeric conversions, you can specify the size to interpret the
5734  number as using C<l>, C<h>, C<V>, C<q>, C<L>, or C<ll>. For integer
5735  conversions (C<d u o x X b i D U O>), numbers are usually assumed to be
5736  whatever the default integer size is on your platform (usually 32 or 64
5737  bits), but you can override this to use instead one of the standard C types,
5738  as supported by the compiler used to build Perl:
5739  
5740     l           interpret integer as C type "long" or "unsigned long"
5741     h           interpret integer as C type "short" or "unsigned short"
5742     q, L or ll  interpret integer as C type "long long", "unsigned long long".
5743                 or "quads" (typically 64-bit integers)
5744  
5745  The last will produce errors if Perl does not understand "quads" in your
5746  installation. (This requires that either the platform natively supports quads
5747  or Perl was specifically compiled to support quads.) You can find out
5748  whether your Perl supports quads via L<Config>:
5749  
5750      use Config;
5751      ($Config{use64bitint} eq 'define' || $Config{longsize} >= 8) &&
5752          print "quads\n";
5753  
5754  For floating point conversions (C<e f g E F G>), numbers are usually assumed
5755  to be the default floating point size on your platform (double or long double),
5756  but you can force 'long double' with C<q>, C<L>, or C<ll> if your
5757  platform supports them. You can find out whether your Perl supports long
5758  doubles via L<Config>:
5759  
5760      use Config;
5761      $Config{d_longdbl} eq 'define' && print "long doubles\n";
5762  
5763  You can find out whether Perl considers 'long double' to be the default
5764  floating point size to use on your platform via L<Config>:
5765  
5766          use Config;
5767          ($Config{uselongdouble} eq 'define') &&
5768                  print "long doubles by default\n";
5769  
5770  It can also be the case that long doubles and doubles are the same thing:
5771  
5772          use Config;
5773          ($Config{doublesize} == $Config{longdblsize}) &&
5774                  print "doubles are long doubles\n";
5775  
5776  The size specifier C<V> has no effect for Perl code, but it is supported
5777  for compatibility with XS code; it means 'use the standard size for
5778  a Perl integer (or floating-point number)', which is already the
5779  default for Perl code.
5780  
5781  =item order of arguments
5782  
5783  Normally, sprintf takes the next unused argument as the value to
5784  format for each format specification. If the format specification
5785  uses C<*> to require additional arguments, these are consumed from
5786  the argument list in the order in which they appear in the format
5787  specification I<before> the value to format. Where an argument is
5788  specified using an explicit index, this does not affect the normal
5789  order for the arguments (even when the explicitly specified index
5790  would have been the next argument in any case).
5791  
5792  So:
5793  
5794    printf '<%*.*s>', $a, $b, $c;
5795  
5796  would use C<$a> for the width, C<$b> for the precision and C<$c>
5797  as the value to format, while:
5798  
5799    printf '<%*1$.*s>', $a, $b;
5800  
5801  would use C<$a> for the width and the precision, and C<$b> as the
5802  value to format.
5803  
5804  Here are some more examples - beware that when using an explicit
5805  index, the C<$> may need to be escaped:
5806  
5807    printf "%2\$d %d\n",    12, 34;        # will print "34 12\n"
5808    printf "%2\$d %d %d\n", 12, 34;        # will print "34 12 34\n"
5809    printf "%3\$d %d %d\n", 12, 34, 56;        # will print "56 12 34\n"
5810    printf "%2\$*3\$d %d\n", 12, 34, 3;        # will print " 34 12\n"
5811  
5812  =back
5813  
5814  If C<use locale> is in effect, and POSIX::setlocale() has been called,
5815  the character used for the decimal separator in formatted floating
5816  point numbers is affected by the LC_NUMERIC locale.  See L<perllocale>
5817  and L<POSIX>.
5818  
5819  =item sqrt EXPR
5820  X<sqrt> X<root> X<square root>
5821  
5822  =item sqrt
5823  
5824  Return the square root of EXPR.  If EXPR is omitted, returns square
5825  root of C<$_>.  Only works on non-negative operands, unless you've
5826  loaded the standard Math::Complex module.
5827  
5828      use Math::Complex;
5829      print sqrt(-2);    # prints 1.4142135623731i
5830  
5831  =item srand EXPR
5832  X<srand> X<seed> X<randseed>
5833  
5834  =item srand
5835  
5836  Sets the random number seed for the C<rand> operator.
5837  
5838  The point of the function is to "seed" the C<rand> function so that
5839  C<rand> can produce a different sequence each time you run your
5840  program.
5841  
5842  If srand() is not called explicitly, it is called implicitly at the
5843  first use of the C<rand> operator.  However, this was not the case in
5844  versions of Perl before 5.004, so if your script will run under older
5845  Perl versions, it should call C<srand>.
5846  
5847  Most programs won't even call srand() at all, except those that
5848  need a cryptographically-strong starting point rather than the
5849  generally acceptable default, which is based on time of day,
5850  process ID, and memory allocation, or the F</dev/urandom> device,
5851  if available.
5852  
5853  You can call srand($seed) with the same $seed to reproduce the
5854  I<same> sequence from rand(), but this is usually reserved for
5855  generating predictable results for testing or debugging.
5856  Otherwise, don't call srand() more than once in your program.
5857  
5858  Do B<not> call srand() (i.e. without an argument) more than once in
5859  a script.  The internal state of the random number generator should
5860  contain more entropy than can be provided by any seed, so calling
5861  srand() again actually I<loses> randomness.
5862  
5863  Most implementations of C<srand> take an integer and will silently
5864  truncate decimal numbers.  This means C<srand(42)> will usually
5865  produce the same results as C<srand(42.1)>.  To be safe, always pass
5866  C<srand> an integer.
5867  
5868  In versions of Perl prior to 5.004 the default seed was just the
5869  current C<time>.  This isn't a particularly good seed, so many old
5870  programs supply their own seed value (often C<time ^ $$> or C<time ^
5871  ($$ + ($$ << 15))>), but that isn't necessary any more.
5872  
5873  For cryptographic purposes, however, you need something much more random 
5874  than the default seed.  Checksumming the compressed output of one or more
5875  rapidly changing operating system status programs is the usual method.  For
5876  example:
5877  
5878      srand (time ^ $$ ^ unpack "%L*", `ps axww | gzip -f`);
5879  
5880  If you're particularly concerned with this, see the C<Math::TrulyRandom>
5881  module in CPAN.
5882  
5883  Frequently called programs (like CGI scripts) that simply use
5884  
5885      time ^ $$
5886  
5887  for a seed can fall prey to the mathematical property that
5888  
5889      a^b == (a+1)^(b+1)
5890  
5891  one-third of the time.  So don't do that.
5892  
5893  =item stat FILEHANDLE
5894  X<stat> X<file, status> X<ctime>
5895  
5896  =item stat EXPR
5897  
5898  =item stat DIRHANDLE
5899  
5900  =item stat
5901  
5902  Returns a 13-element list giving the status info for a file, either
5903  the file opened via FILEHANDLE or DIRHANDLE, or named by EXPR.  If EXPR is 
5904  omitted, it stats C<$_>.  Returns a null list if the stat fails.  Typically
5905  used as follows:
5906  
5907      ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
5908         $atime,$mtime,$ctime,$blksize,$blocks)
5909             = stat($filename);
5910  
5911  Not all fields are supported on all filesystem types.  Here are the
5912  meanings of the fields:
5913  
5914    0 dev      device number of filesystem
5915    1 ino      inode number
5916    2 mode     file mode  (type and permissions)
5917    3 nlink    number of (hard) links to the file
5918    4 uid      numeric user ID of file's owner
5919    5 gid      numeric group ID of file's owner
5920    6 rdev     the device identifier (special files only)
5921    7 size     total size of file, in bytes
5922    8 atime    last access time in seconds since the epoch
5923    9 mtime    last modify time in seconds since the epoch
5924   10 ctime    inode change time in seconds since the epoch (*)
5925   11 blksize  preferred block size for file system I/O
5926   12 blocks   actual number of blocks allocated
5927  
5928  (The epoch was at 00:00 January 1, 1970 GMT.)
5929  
5930  (*) Not all fields are supported on all filesystem types. Notably, the
5931  ctime field is non-portable.  In particular, you cannot expect it to be a
5932  "creation time", see L<perlport/"Files and Filesystems"> for details.
5933  
5934  If C<stat> is passed the special filehandle consisting of an underline, no
5935  stat is done, but the current contents of the stat structure from the
5936  last C<stat>, C<lstat>, or filetest are returned.  Example:
5937  
5938      if (-x $file && (($d) = stat(_)) && $d < 0) {
5939      print "$file is executable NFS file\n";
5940      }
5941  
5942  (This works on machines only for which the device number is negative
5943  under NFS.)
5944  
5945  Because the mode contains both the file type and its permissions, you
5946  should mask off the file type portion and (s)printf using a C<"%o">
5947  if you want to see the real permissions.
5948  
5949      $mode = (stat($filename))[2];
5950      printf "Permissions are %04o\n", $mode & 07777;
5951  
5952  In scalar context, C<stat> returns a boolean value indicating success
5953  or failure, and, if successful, sets the information associated with
5954  the special filehandle C<_>.
5955  
5956  The L<File::stat> module provides a convenient, by-name access mechanism:
5957  
5958      use File::stat;
5959      $sb = stat($filename);
5960      printf "File is %s, size is %s, perm %04o, mtime %s\n",
5961      $filename, $sb->size, $sb->mode & 07777,
5962      scalar localtime $sb->mtime;
5963  
5964  You can import symbolic mode constants (C<S_IF*>) and functions
5965  (C<S_IS*>) from the Fcntl module:
5966  
5967      use Fcntl ':mode';
5968  
5969      $mode = (stat($filename))[2];
5970  
5971      $user_rwx      = ($mode & S_IRWXU) >> 6;
5972      $group_read    = ($mode & S_IRGRP) >> 3;
5973      $other_execute =  $mode & S_IXOTH;
5974  
5975      printf "Permissions are %04o\n", S_IMODE($mode), "\n";
5976  
5977      $is_setuid     =  $mode & S_ISUID;
5978      $is_directory  =  S_ISDIR($mode);
5979  
5980  You could write the last two using the C<-u> and C<-d> operators.
5981  The commonly available C<S_IF*> constants are
5982  
5983      # Permissions: read, write, execute, for user, group, others.
5984  
5985      S_IRWXU S_IRUSR S_IWUSR S_IXUSR
5986      S_IRWXG S_IRGRP S_IWGRP S_IXGRP
5987      S_IRWXO S_IROTH S_IWOTH S_IXOTH
5988  
5989      # Setuid/Setgid/Stickiness/SaveText.
5990      # Note that the exact meaning of these is system dependent.
5991  
5992      S_ISUID S_ISGID S_ISVTX S_ISTXT
5993  
5994      # File types.  Not necessarily all are available on your system.
5995  
5996      S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
5997  
5998      # The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.
5999  
6000      S_IREAD S_IWRITE S_IEXEC
6001  
6002  and the C<S_IF*> functions are
6003  
6004      S_IMODE($mode)    the part of $mode containing the permission bits
6005              and the setuid/setgid/sticky bits
6006  
6007      S_IFMT($mode)    the part of $mode containing the file type
6008              which can be bit-anded with e.g. S_IFREG
6009                          or with the following functions
6010  
6011      # The operators -f, -d, -l, -b, -c, -p, and -S.
6012  
6013      S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)
6014      S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)
6015  
6016      # No direct -X operator counterpart, but for the first one
6017      # the -g operator is often equivalent.  The ENFMT stands for
6018      # record flocking enforcement, a platform-dependent feature.
6019  
6020      S_ISENFMT($mode) S_ISWHT($mode)
6021  
6022  See your native chmod(2) and stat(2) documentation for more details
6023  about the C<S_*> constants.  To get status info for a symbolic link
6024  instead of the target file behind the link, use the C<lstat> function.
6025  
6026  =item state EXPR
6027  X<state>
6028  
6029  =item state TYPE EXPR
6030  
6031  =item state EXPR : ATTRS
6032  
6033  =item state TYPE EXPR : ATTRS
6034  
6035  C<state> declares a lexically scoped variable, just like C<my> does.
6036  However, those variables will never be reinitialized, contrary to
6037  lexical variables that are reinitialized each time their enclosing block
6038  is entered.
6039  
6040  C<state> variables are only enabled when the C<feature 'state'> pragma is
6041  in effect.  See L<feature>.
6042  
6043  =item study SCALAR
6044  X<study>
6045  
6046  =item study
6047  
6048  Takes extra time to study SCALAR (C<$_> if unspecified) in anticipation of
6049  doing many pattern matches on the string before it is next modified.
6050  This may or may not save time, depending on the nature and number of
6051  patterns you are searching on, and on the distribution of character
6052  frequencies in the string to be searched--you probably want to compare
6053  run times with and without it to see which runs faster.  Those loops
6054  that scan for many short constant strings (including the constant
6055  parts of more complex patterns) will benefit most.  You may have only
6056  one C<study> active at a time--if you study a different scalar the first
6057  is "unstudied".  (The way C<study> works is this: a linked list of every
6058  character in the string to be searched is made, so we know, for
6059  example, where all the C<'k'> characters are.  From each search string,
6060  the rarest character is selected, based on some static frequency tables
6061  constructed from some C programs and English text.  Only those places
6062  that contain this "rarest" character are examined.)
6063  
6064  For example, here is a loop that inserts index producing entries
6065  before any line containing a certain pattern:
6066  
6067      while (<>) {
6068      study;
6069      print ".IX foo\n"     if /\bfoo\b/;
6070      print ".IX bar\n"     if /\bbar\b/;
6071      print ".IX blurfl\n"     if /\bblurfl\b/;
6072      # ...
6073      print;
6074      }
6075  
6076  In searching for C</\bfoo\b/>, only those locations in C<$_> that contain C<f>
6077  will be looked at, because C<f> is rarer than C<o>.  In general, this is
6078  a big win except in pathological cases.  The only question is whether
6079  it saves you more time than it took to build the linked list in the
6080  first place.
6081  
6082  Note that if you have to look for strings that you don't know till
6083  runtime, you can build an entire loop as a string and C<eval> that to
6084  avoid recompiling all your patterns all the time.  Together with
6085  undefining C<$/> to input entire files as one record, this can be very
6086  fast, often faster than specialized programs like fgrep(1).  The following
6087  scans a list of files (C<@files>) for a list of words (C<@words>), and prints
6088  out the names of those files that contain a match:
6089  
6090      $search = 'while (<>) { study;';
6091      foreach $word (@words) {
6092      $search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n";
6093      }
6094      $search .= "}";
6095      @ARGV = @files;
6096      undef $/;
6097      eval $search;        # this screams
6098      $/ = "\n";        # put back to normal input delimiter
6099      foreach $file (sort keys(%seen)) {
6100      print $file, "\n";
6101      }
6102  
6103  =item sub NAME BLOCK
6104  X<sub>
6105  
6106  =item sub NAME (PROTO) BLOCK
6107  
6108  =item sub NAME : ATTRS BLOCK
6109  
6110  =item sub NAME (PROTO) : ATTRS BLOCK
6111  
6112  This is subroutine definition, not a real function I<per se>.
6113  Without a BLOCK it's just a forward declaration.  Without a NAME,
6114  it's an anonymous function declaration, and does actually return
6115  a value: the CODE ref of the closure you just created.
6116  
6117  See L<perlsub> and L<perlref> for details about subroutines and
6118  references, and L<attributes> and L<Attribute::Handlers> for more
6119  information about attributes.
6120  
6121  =item substr EXPR,OFFSET,LENGTH,REPLACEMENT
6122  X<substr> X<substring> X<mid> X<left> X<right>
6123  
6124  =item substr EXPR,OFFSET,LENGTH
6125  
6126  =item substr EXPR,OFFSET
6127  
6128  Extracts a substring out of EXPR and returns it.  First character is at
6129  offset C<0>, or whatever you've set C<$[> to (but don't do that).
6130  If OFFSET is negative (or more precisely, less than C<$[>), starts
6131  that far from the end of the string.  If LENGTH is omitted, returns
6132  everything to the end of the string.  If LENGTH is negative, leaves that
6133  many characters off the end of the string.
6134  
6135      my $s = "The black cat climbed the green tree";
6136      my $color  = substr $s, 4, 5;    # black
6137      my $middle = substr $s, 4, -11;    # black cat climbed the
6138      my $end    = substr $s, 14;        # climbed the green tree
6139      my $tail   = substr $s, -4;        # tree
6140      my $z      = substr $s, -4, 2;    # tr
6141  
6142  You can use the substr() function as an lvalue, in which case EXPR
6143  must itself be an lvalue.  If you assign something shorter than LENGTH,
6144  the string will shrink, and if you assign something longer than LENGTH,
6145  the string will grow to accommodate it.  To keep the string the same
6146  length you may need to pad or chop your value using C<sprintf>.
6147  
6148  If OFFSET and LENGTH specify a substring that is partly outside the
6149  string, only the part within the string is returned.  If the substring
6150  is beyond either end of the string, substr() returns the undefined
6151  value and produces a warning.  When used as an lvalue, specifying a
6152  substring that is entirely outside the string is a fatal error.
6153  Here's an example showing the behavior for boundary cases:
6154  
6155      my $name = 'fred';
6156      substr($name, 4) = 'dy';        # $name is now 'freddy'
6157      my $null = substr $name, 6, 2;    # returns '' (no warning)
6158      my $oops = substr $name, 7;        # returns undef, with warning
6159      substr($name, 7) = 'gap';        # fatal error
6160  
6161  An alternative to using substr() as an lvalue is to specify the
6162  replacement string as the 4th argument.  This allows you to replace
6163  parts of the EXPR and return what was there before in one operation,
6164  just as you can with splice().
6165  
6166      my $s = "The black cat climbed the green tree";
6167      my $z = substr $s, 14, 7, "jumped from";    # climbed
6168      # $s is now "The black cat jumped from the green tree"
6169  
6170  Note that the lvalue returned by the 3-arg version of substr() acts as
6171  a 'magic bullet'; each time it is assigned to, it remembers which part
6172  of the original string is being modified; for example:
6173  
6174      $x = '1234';
6175      for (substr($x,1,2)) {
6176          $_ = 'a';   print $x,"\n";    # prints 1a4
6177          $_ = 'xyz'; print $x,"\n";    # prints 1xyz4
6178          $x = '56789';
6179          $_ = 'pq';  print $x,"\n";    # prints 5pq9
6180      }
6181  
6182  Prior to Perl version 5.9.1, the result of using an lvalue multiple times was
6183  unspecified.
6184  
6185  =item symlink OLDFILE,NEWFILE
6186  X<symlink> X<link> X<symbolic link> X<link, symbolic>
6187  
6188  Creates a new filename symbolically linked to the old filename.
6189  Returns C<1> for success, C<0> otherwise.  On systems that don't support
6190  symbolic links, produces a fatal error at run time.  To check for that,
6191  use eval:
6192  
6193      $symlink_exists = eval { symlink("",""); 1 };
6194  
6195  =item syscall NUMBER, LIST
6196  X<syscall> X<system call>
6197  
6198  Calls the system call specified as the first element of the list,
6199  passing the remaining elements as arguments to the system call.  If
6200  unimplemented, produces a fatal error.  The arguments are interpreted
6201  as follows: if a given argument is numeric, the argument is passed as
6202  an int.  If not, the pointer to the string value is passed.  You are
6203  responsible to make sure a string is pre-extended long enough to
6204  receive any result that might be written into a string.  You can't use a
6205  string literal (or other read-only string) as an argument to C<syscall>
6206  because Perl has to assume that any string pointer might be written
6207  through.  If your
6208  integer arguments are not literals and have never been interpreted in a
6209  numeric context, you may need to add C<0> to them to force them to look
6210  like numbers.  This emulates the C<syswrite> function (or vice versa):
6211  
6212      require 'syscall.ph';        # may need to run h2ph
6213      $s = "hi there\n";
6214      syscall(&SYS_write, fileno(STDOUT), $s, length $s);
6215  
6216  Note that Perl supports passing of up to only 14 arguments to your system call,
6217  which in practice should usually suffice.
6218  
6219  Syscall returns whatever value returned by the system call it calls.
6220  If the system call fails, C<syscall> returns C<-1> and sets C<$!> (errno).
6221  Note that some system calls can legitimately return C<-1>.  The proper
6222  way to handle such calls is to assign C<$!=0;> before the call and
6223  check the value of C<$!> if syscall returns C<-1>.
6224  
6225  There's a problem with C<syscall(&SYS_pipe)>: it returns the file
6226  number of the read end of the pipe it creates.  There is no way
6227  to retrieve the file number of the other end.  You can avoid this
6228  problem by using C<pipe> instead.
6229  
6230  =item sysopen FILEHANDLE,FILENAME,MODE
6231  X<sysopen>
6232  
6233  =item sysopen FILEHANDLE,FILENAME,MODE,PERMS
6234  
6235  Opens the file whose filename is given by FILENAME, and associates it
6236  with FILEHANDLE.  If FILEHANDLE is an expression, its value is used as
6237  the name of the real filehandle wanted.  This function calls the
6238  underlying operating system's C<open> function with the parameters
6239  FILENAME, MODE, PERMS.
6240  
6241  The possible values and flag bits of the MODE parameter are
6242  system-dependent; they are available via the standard module C<Fcntl>.
6243  See the documentation of your operating system's C<open> to see which
6244  values and flag bits are available.  You may combine several flags
6245  using the C<|>-operator.
6246  
6247  Some of the most common values are C<O_RDONLY> for opening the file in
6248  read-only mode, C<O_WRONLY> for opening the file in write-only mode,
6249  and C<O_RDWR> for opening the file in read-write mode.
6250  X<O_RDONLY> X<O_RDWR> X<O_WRONLY>
6251  
6252  For historical reasons, some values work on almost every system
6253  supported by perl: zero means read-only, one means write-only, and two
6254  means read/write.  We know that these values do I<not> work under
6255  OS/390 & VM/ESA Unix and on the Macintosh; you probably don't want to
6256  use them in new code.
6257  
6258  If the file named by FILENAME does not exist and the C<open> call creates
6259  it (typically because MODE includes the C<O_CREAT> flag), then the value of
6260  PERMS specifies the permissions of the newly created file.  If you omit
6261  the PERMS argument to C<sysopen>, Perl uses the octal value C<0666>.
6262  These permission values need to be in octal, and are modified by your
6263  process's current C<umask>.
6264  X<O_CREAT>
6265  
6266  In many systems the C<O_EXCL> flag is available for opening files in
6267  exclusive mode.  This is B<not> locking: exclusiveness means here that
6268  if the file already exists, sysopen() fails.  C<O_EXCL> may not work
6269  on network filesystems, and has no effect unless the C<O_CREAT> flag
6270  is set as well.  Setting C<O_CREAT|O_EXCL> prevents the file from
6271  being opened if it is a symbolic link.  It does not protect against
6272  symbolic links in the file's path.
6273  X<O_EXCL>
6274  
6275  Sometimes you may want to truncate an already-existing file.  This
6276  can be done using the C<O_TRUNC> flag.  The behavior of
6277  C<O_TRUNC> with C<O_RDONLY> is undefined.
6278  X<O_TRUNC>
6279  
6280  You should seldom if ever use C<0644> as argument to C<sysopen>, because
6281  that takes away the user's option to have a more permissive umask.
6282  Better to omit it.  See the perlfunc(1) entry on C<umask> for more
6283  on this.
6284  
6285  Note that C<sysopen> depends on the fdopen() C library function.
6286  On many UNIX systems, fdopen() is known to fail when file descriptors
6287  exceed a certain value, typically 255. If you need more file
6288  descriptors than that, consider rebuilding Perl to use the C<sfio>
6289  library, or perhaps using the POSIX::open() function.
6290  
6291  See L<perlopentut> for a kinder, gentler explanation of opening files.
6292  
6293  =item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
6294  X<sysread>
6295  
6296  =item sysread FILEHANDLE,SCALAR,LENGTH
6297  
6298  Attempts to read LENGTH bytes of data into variable SCALAR from the
6299  specified FILEHANDLE, using the system call read(2).  It bypasses
6300  buffered IO, so mixing this with other kinds of reads, C<print>,
6301  C<write>, C<seek>, C<tell>, or C<eof> can cause confusion because the
6302  perlio or stdio layers usually buffers data.  Returns the number of
6303  bytes actually read, C<0> at end of file, or undef if there was an
6304  error (in the latter case C<$!> is also set).  SCALAR will be grown or
6305  shrunk so that the last byte actually read is the last byte of the
6306  scalar after the read.
6307  
6308  An OFFSET may be specified to place the read data at some place in the
6309  string other than the beginning.  A negative OFFSET specifies
6310  placement at that many characters counting backwards from the end of
6311  the string.  A positive OFFSET greater than the length of SCALAR
6312  results in the string being padded to the required size with C<"\0">
6313  bytes before the result of the read is appended.
6314  
6315  There is no syseof() function, which is ok, since eof() doesn't work
6316  very well on device files (like ttys) anyway.  Use sysread() and check
6317  for a return value for 0 to decide whether you're done.
6318  
6319  Note that if the filehandle has been marked as C<:utf8> Unicode
6320  characters are read instead of bytes (the LENGTH, OFFSET, and the
6321  return value of sysread() are in Unicode characters).
6322  The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
6323  See L</binmode>, L</open>, and the C<open> pragma, L<open>.
6324  
6325  =item sysseek FILEHANDLE,POSITION,WHENCE
6326  X<sysseek> X<lseek>
6327  
6328  Sets FILEHANDLE's system position in bytes using the system call
6329  lseek(2).  FILEHANDLE may be an expression whose value gives the name
6330  of the filehandle.  The values for WHENCE are C<0> to set the new
6331  position to POSITION, C<1> to set the it to the current position plus
6332  POSITION, and C<2> to set it to EOF plus POSITION (typically
6333  negative).
6334  
6335  Note the I<in bytes>: even if the filehandle has been set to operate
6336  on characters (for example by using the C<:encoding(utf8)> I/O layer),
6337  tell() will return byte offsets, not character offsets (because
6338  implementing that would render sysseek() very slow).
6339  
6340  sysseek() bypasses normal buffered IO, so mixing this with reads (other
6341  than C<sysread>, for example C<< <> >> or read()) C<print>, C<write>,
6342  C<seek>, C<tell>, or C<eof> may cause confusion.
6343  
6344  For WHENCE, you may also use the constants C<SEEK_SET>, C<SEEK_CUR>,
6345  and C<SEEK_END> (start of the file, current position, end of the file)
6346  from the Fcntl module.  Use of the constants is also more portable
6347  than relying on 0, 1, and 2.  For example to define a "systell" function:
6348  
6349      use Fcntl 'SEEK_CUR';
6350      sub systell { sysseek($_[0], 0, SEEK_CUR) }
6351  
6352  Returns the new position, or the undefined value on failure.  A position
6353  of zero is returned as the string C<"0 but true">; thus C<sysseek> returns
6354  true on success and false on failure, yet you can still easily determine
6355  the new position.
6356  
6357  =item system LIST
6358  X<system> X<shell>
6359  
6360  =item system PROGRAM LIST
6361  
6362  Does exactly the same thing as C<exec LIST>, except that a fork is
6363  done first, and the parent process waits for the child process to
6364  complete.  Note that argument processing varies depending on the
6365  number of arguments.  If there is more than one argument in LIST,
6366  or if LIST is an array with more than one value, starts the program
6367  given by the first element of the list with arguments given by the
6368  rest of the list.  If there is only one scalar argument, the argument
6369  is checked for shell metacharacters, and if there are any, the
6370  entire argument is passed to the system's command shell for parsing
6371  (this is C</bin/sh -c> on Unix platforms, but varies on other
6372  platforms).  If there are no shell metacharacters in the argument,
6373  it is split into words and passed directly to C<execvp>, which is
6374  more efficient.
6375  
6376  Beginning with v5.6.0, Perl will attempt to flush all files opened for
6377  output before any operation that may do a fork, but this may not be
6378  supported on some platforms (see L<perlport>).  To be safe, you may need
6379  to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
6380  of C<IO::Handle> on any open handles.
6381  
6382  The return value is the exit status of the program as returned by the
6383  C<wait> call.  To get the actual exit value, shift right by eight (see
6384  below). See also L</exec>.  This is I<not> what you want to use to capture
6385  the output from a command, for that you should use merely backticks or
6386  C<qx//>, as described in L<perlop/"`STRING`">.  Return value of -1
6387  indicates a failure to start the program or an error of the wait(2) system
6388  call (inspect $! for the reason).
6389  
6390  Like C<exec>, C<system> allows you to lie to a program about its name if
6391  you use the C<system PROGRAM LIST> syntax.  Again, see L</exec>.
6392  
6393  Since C<SIGINT> and C<SIGQUIT> are ignored during the execution of
6394  C<system>, if you expect your program to terminate on receipt of these
6395  signals you will need to arrange to do so yourself based on the return
6396  value.
6397  
6398      @args = ("command", "arg1", "arg2");
6399      system(@args) == 0
6400       or die "system @args failed: $?"
6401  
6402  You can check all the failure possibilities by inspecting
6403  C<$?> like this:
6404  
6405      if ($? == -1) {
6406      print "failed to execute: $!\n";
6407      }
6408      elsif ($? & 127) {
6409      printf "child died with signal %d, %s coredump\n",
6410          ($? & 127),  ($? & 128) ? 'with' : 'without';
6411      }
6412      else {
6413      printf "child exited with value %d\n", $? >> 8;
6414      }
6415  
6416  Alternatively you might inspect the value of C<${^CHILD_ERROR_NATIVE}>
6417  with the W*() calls of the POSIX extension.
6418  
6419  When the arguments get executed via the system shell, results
6420  and return codes will be subject to its quirks and capabilities.
6421  See L<perlop/"`STRING`"> and L</exec> for details.
6422  
6423  =item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
6424  X<syswrite>
6425  
6426  =item syswrite FILEHANDLE,SCALAR,LENGTH
6427  
6428  =item syswrite FILEHANDLE,SCALAR
6429  
6430  Attempts to write LENGTH bytes of data from variable SCALAR to the
6431  specified FILEHANDLE, using the system call write(2).  If LENGTH is
6432  not specified, writes whole SCALAR.  It bypasses buffered IO, so
6433  mixing this with reads (other than C<sysread())>, C<print>, C<write>,
6434  C<seek>, C<tell>, or C<eof> may cause confusion because the perlio and
6435  stdio layers usually buffers data.  Returns the number of bytes
6436  actually written, or C<undef> if there was an error (in this case the
6437  errno variable C<$!> is also set).  If the LENGTH is greater than the
6438  available data in the SCALAR after the OFFSET, only as much data as is
6439  available will be written.
6440  
6441  An OFFSET may be specified to write the data from some part of the
6442  string other than the beginning.  A negative OFFSET specifies writing
6443  that many characters counting backwards from the end of the string.
6444  In the case the SCALAR is empty you can use OFFSET but only zero offset.
6445  
6446  Note that if the filehandle has been marked as C<:utf8>, Unicode
6447  characters are written instead of bytes (the LENGTH, OFFSET, and the
6448  return value of syswrite() are in UTF-8 encoded Unicode characters).
6449  The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
6450  See L</binmode>, L</open>, and the C<open> pragma, L<open>.
6451  
6452  =item tell FILEHANDLE
6453  X<tell>
6454  
6455  =item tell
6456  
6457  Returns the current position I<in bytes> for FILEHANDLE, or -1 on
6458  error.  FILEHANDLE may be an expression whose value gives the name of
6459  the actual filehandle.  If FILEHANDLE is omitted, assumes the file
6460  last read.
6461  
6462  Note the I<in bytes>: even if the filehandle has been set to
6463  operate on characters (for example by using the C<:encoding(utf8)> open
6464  layer), tell() will return byte offsets, not character offsets (because
6465  that would render seek() and tell() rather slow).
6466  
6467  The return value of tell() for the standard streams like the STDIN
6468  depends on the operating system: it may return -1 or something else.
6469  tell() on pipes, fifos, and sockets usually returns -1.
6470  
6471  There is no C<systell> function.  Use C<sysseek(FH, 0, 1)> for that.
6472  
6473  Do not use tell() (or other buffered I/O operations) on a file handle
6474  that has been manipulated by sysread(), syswrite() or sysseek().
6475  Those functions ignore the buffering, while tell() does not.
6476  
6477  =item telldir DIRHANDLE
6478  X<telldir>
6479  
6480  Returns the current position of the C<readdir> routines on DIRHANDLE.
6481  Value may be given to C<seekdir> to access a particular location in a
6482  directory.  C<telldir> has the same caveats about possible directory
6483  compaction as the corresponding system library routine.
6484  
6485  =item tie VARIABLE,CLASSNAME,LIST
6486  X<tie>
6487  
6488  This function binds a variable to a package class that will provide the
6489  implementation for the variable.  VARIABLE is the name of the variable
6490  to be enchanted.  CLASSNAME is the name of a class implementing objects
6491  of correct type.  Any additional arguments are passed to the C<new>
6492  method of the class (meaning C<TIESCALAR>, C<TIEHANDLE>, C<TIEARRAY>,
6493  or C<TIEHASH>).  Typically these are arguments such as might be passed
6494  to the C<dbm_open()> function of C.  The object returned by the C<new>
6495  method is also returned by the C<tie> function, which would be useful
6496  if you want to access other methods in CLASSNAME.
6497  
6498  Note that functions such as C<keys> and C<values> may return huge lists
6499  when used on large objects, like DBM files.  You may prefer to use the
6500  C<each> function to iterate over such.  Example:
6501  
6502      # print out history file offsets
6503      use NDBM_File;
6504      tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
6505      while (($key,$val) = each %HIST) {
6506      print $key, ' = ', unpack('L',$val), "\n";
6507      }
6508      untie(%HIST);
6509  
6510  A class implementing a hash should have the following methods:
6511  
6512      TIEHASH classname, LIST
6513      FETCH this, key
6514      STORE this, key, value
6515      DELETE this, key
6516      CLEAR this
6517      EXISTS this, key
6518      FIRSTKEY this
6519      NEXTKEY this, lastkey
6520      SCALAR this
6521      DESTROY this
6522      UNTIE this
6523  
6524  A class implementing an ordinary array should have the following methods:
6525  
6526      TIEARRAY classname, LIST
6527      FETCH this, key
6528      STORE this, key, value
6529      FETCHSIZE this
6530      STORESIZE this, count
6531      CLEAR this
6532      PUSH this, LIST
6533      POP this
6534      SHIFT this
6535      UNSHIFT this, LIST
6536      SPLICE this, offset, length, LIST
6537      EXTEND this, count
6538      DESTROY this
6539      UNTIE this
6540  
6541  A class implementing a file handle should have the following methods:
6542  
6543      TIEHANDLE classname, LIST
6544      READ this, scalar, length, offset
6545      READLINE this
6546      GETC this
6547      WRITE this, scalar, length, offset
6548      PRINT this, LIST
6549      PRINTF this, format, LIST
6550      BINMODE this
6551      EOF this
6552      FILENO this
6553      SEEK this, position, whence
6554      TELL this
6555      OPEN this, mode, LIST
6556      CLOSE this
6557      DESTROY this
6558      UNTIE this
6559  
6560  A class implementing a scalar should have the following methods:
6561  
6562      TIESCALAR classname, LIST
6563      FETCH this,
6564      STORE this, value
6565      DESTROY this
6566      UNTIE this
6567  
6568  Not all methods indicated above need be implemented.  See L<perltie>,
6569  L<Tie::Hash>, L<Tie::Array>, L<Tie::Scalar>, and L<Tie::Handle>.
6570  
6571  Unlike C<dbmopen>, the C<tie> function will not use or require a module
6572  for you--you need to do that explicitly yourself.  See L<DB_File>
6573  or the F<Config> module for interesting C<tie> implementations.
6574  
6575  For further details see L<perltie>, L<"tied VARIABLE">.
6576  
6577  =item tied VARIABLE
6578  X<tied>
6579  
6580  Returns a reference to the object underlying VARIABLE (the same value
6581  that was originally returned by the C<tie> call that bound the variable
6582  to a package.)  Returns the undefined value if VARIABLE isn't tied to a
6583  package.
6584  
6585  =item time
6586  X<time> X<epoch>
6587  
6588  Returns the number of non-leap seconds since whatever time the system
6589  considers to be the epoch, suitable for feeding to C<gmtime> and
6590  C<localtime>. On most systems the epoch is 00:00:00 UTC, January 1, 1970;
6591  a prominent exception being Mac OS Classic which uses 00:00:00, January 1,
6592  1904 in the current local time zone for its epoch.
6593  
6594  For measuring time in better granularity than one second,
6595  you may use either the L<Time::HiRes> module (from CPAN, and starting from
6596  Perl 5.8 part of the standard distribution), or if you have
6597  gettimeofday(2), you may be able to use the C<syscall> interface of Perl.
6598  See L<perlfaq8> for details.
6599  
6600  For date and time processing look at the many related modules on CPAN.
6601  For a comprehensive date and time representation look at the
6602  L<DateTime> module.
6603  
6604  =item times
6605  X<times>
6606  
6607  Returns a four-element list giving the user and system times, in
6608  seconds, for this process and the children of this process.
6609  
6610      ($user,$system,$cuser,$csystem) = times;
6611  
6612  In scalar context, C<times> returns C<$user>.
6613  
6614  Note that times for children are included only after they terminate.
6615  
6616  =item tr///
6617  
6618  The transliteration operator.  Same as C<y///>.  See L<perlop>.
6619  
6620  =item truncate FILEHANDLE,LENGTH
6621  X<truncate>
6622  
6623  =item truncate EXPR,LENGTH
6624  
6625  Truncates the file opened on FILEHANDLE, or named by EXPR, to the
6626  specified length.  Produces a fatal error if truncate isn't implemented
6627  on your system.  Returns true if successful, the undefined value
6628  otherwise.
6629  
6630  The behavior is undefined if LENGTH is greater than the length of the
6631  file.
6632  
6633  The position in the file of FILEHANDLE is left unchanged.  You may want to
6634  call L<seek> before writing to the file.
6635  
6636  =item uc EXPR
6637  X<uc> X<uppercase> X<toupper>
6638  
6639  =item uc
6640  
6641  Returns an uppercased version of EXPR.  This is the internal function
6642  implementing the C<\U> escape in double-quoted strings.  Respects
6643  current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>
6644  and L<perlunicode> for more details about locale and Unicode support.
6645  It does not attempt to do titlecase mapping on initial letters.  See
6646  C<ucfirst> for that.
6647  
6648  If EXPR is omitted, uses C<$_>.
6649  
6650  =item ucfirst EXPR
6651  X<ucfirst> X<uppercase>
6652  
6653  =item ucfirst
6654  
6655  Returns the value of EXPR with the first character in uppercase
6656  (titlecase in Unicode).  This is the internal function implementing
6657  the C<\u> escape in double-quoted strings.  Respects current LC_CTYPE
6658  locale if C<use locale> in force.  See L<perllocale> and L<perlunicode>
6659  for more details about locale and Unicode support.
6660  
6661  If EXPR is omitted, uses C<$_>.
6662  
6663  =item umask EXPR
6664  X<umask>
6665  
6666  =item umask
6667  
6668  Sets the umask for the process to EXPR and returns the previous value.
6669  If EXPR is omitted, merely returns the current umask.
6670  
6671  The Unix permission C<rwxr-x---> is represented as three sets of three
6672  bits, or three octal digits: C<0750> (the leading 0 indicates octal
6673  and isn't one of the digits).  The C<umask> value is such a number
6674  representing disabled permissions bits.  The permission (or "mode")
6675  values you pass C<mkdir> or C<sysopen> are modified by your umask, so
6676  even if you tell C<sysopen> to create a file with permissions C<0777>,
6677  if your umask is C<0022> then the file will actually be created with
6678  permissions C<0755>.  If your C<umask> were C<0027> (group can't
6679  write; others can't read, write, or execute), then passing
6680  C<sysopen> C<0666> would create a file with mode C<0640> (C<0666 &~
6681  027> is C<0640>).
6682  
6683  Here's some advice: supply a creation mode of C<0666> for regular
6684  files (in C<sysopen>) and one of C<0777> for directories (in
6685  C<mkdir>) and executable files.  This gives users the freedom of
6686  choice: if they want protected files, they might choose process umasks
6687  of C<022>, C<027>, or even the particularly antisocial mask of C<077>.
6688  Programs should rarely if ever make policy decisions better left to
6689  the user.  The exception to this is when writing files that should be
6690  kept private: mail files, web browser cookies, I<.rhosts> files, and
6691  so on.
6692  
6693  If umask(2) is not implemented on your system and you are trying to
6694  restrict access for I<yourself> (i.e., (EXPR & 0700) > 0), produces a
6695  fatal error at run time.  If umask(2) is not implemented and you are
6696  not trying to restrict access for yourself, returns C<undef>.
6697  
6698  Remember that a umask is a number, usually given in octal; it is I<not> a
6699  string of octal digits.  See also L</oct>, if all you have is a string.
6700  
6701  =item undef EXPR
6702  X<undef> X<undefine>
6703  
6704  =item undef
6705  
6706  Undefines the value of EXPR, which must be an lvalue.  Use only on a
6707  scalar value, an array (using C<@>), a hash (using C<%>), a subroutine
6708  (using C<&>), or a typeglob (using C<*>).  (Saying C<undef $hash{$key}>
6709  will probably not do what you expect on most predefined variables or
6710  DBM list values, so don't do that; see L<delete>.)  Always returns the
6711  undefined value.  You can omit the EXPR, in which case nothing is
6712  undefined, but you still get an undefined value that you could, for
6713  instance, return from a subroutine, assign to a variable or pass as a
6714  parameter.  Examples:
6715  
6716      undef $foo;
6717      undef $bar{'blurfl'};      # Compare to: delete $bar{'blurfl'};
6718      undef @ary;
6719      undef %hash;
6720      undef &mysub;
6721      undef *xyz;       # destroys $xyz, @xyz, %xyz, &xyz, etc.
6722      return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
6723      select undef, undef, undef, 0.25;
6724      ($a, $b, undef, $c) = &foo;       # Ignore third value returned
6725  
6726  Note that this is a unary operator, not a list operator.
6727  
6728  =item unlink LIST
6729  X<unlink> X<delete> X<remove> X<rm> X<del>
6730  
6731  =item unlink
6732  
6733  Deletes a list of files.  Returns the number of files successfully
6734  deleted.
6735  
6736      $cnt = unlink 'a', 'b', 'c';
6737      unlink @goners;
6738      unlink <*.bak>;
6739  
6740  Note: C<unlink> will not attempt to delete directories unless you are superuser
6741  and the B<-U> flag is supplied to Perl.  Even if these conditions are
6742  met, be warned that unlinking a directory can inflict damage on your
6743  filesystem.  Finally, using C<unlink> on directories is not supported on 
6744  many operating systems.  Use C<rmdir> instead.
6745  
6746  If LIST is omitted, uses C<$_>.
6747  
6748  =item unpack TEMPLATE,EXPR
6749  X<unpack>
6750  
6751  =item unpack TEMPLATE
6752  
6753  C<unpack> does the reverse of C<pack>: it takes a string
6754  and expands it out into a list of values.
6755  (In scalar context, it returns merely the first value produced.)
6756  
6757  If EXPR is omitted, unpacks the C<$_> string.
6758  
6759  The string is broken into chunks described by the TEMPLATE.  Each chunk
6760  is converted separately to a value.  Typically, either the string is a result
6761  of C<pack>, or the characters of the string represent a C structure of some
6762  kind.
6763  
6764  The TEMPLATE has the same format as in the C<pack> function.
6765  Here's a subroutine that does substring:
6766  
6767      sub substr {
6768      my($what,$where,$howmuch) = @_;
6769      unpack("x$where a$howmuch", $what);
6770      }
6771  
6772  and then there's
6773  
6774      sub ordinal { unpack("W",$_[0]); } # same as ord()
6775  
6776  In addition to fields allowed in pack(), you may prefix a field with
6777  a %<number> to indicate that
6778  you want a <number>-bit checksum of the items instead of the items
6779  themselves.  Default is a 16-bit checksum.  Checksum is calculated by
6780  summing numeric values of expanded values (for string fields the sum of
6781  C<ord($char)> is taken, for bit fields the sum of zeroes and ones).
6782  
6783  For example, the following
6784  computes the same number as the System V sum program:
6785  
6786      $checksum = do {
6787      local $/;  # slurp!
6788      unpack("%32W*",<>) % 65535;
6789      };
6790  
6791  The following efficiently counts the number of set bits in a bit vector:
6792  
6793      $setbits = unpack("%32b*", $selectmask);
6794  
6795  The C<p> and C<P> formats should be used with care.  Since Perl
6796  has no way of checking whether the value passed to C<unpack()>
6797  corresponds to a valid memory location, passing a pointer value that's
6798  not known to be valid is likely to have disastrous consequences.
6799  
6800  If there are more pack codes or if the repeat count of a field or a group
6801  is larger than what the remainder of the input string allows, the result
6802  is not well defined: in some cases, the repeat count is decreased, or
6803  C<unpack()> will produce null strings or zeroes, or terminate with an
6804  error. If the input string is longer than one described by the TEMPLATE,
6805  the rest is ignored.
6806  
6807  See L</pack> for more examples and notes.
6808  
6809  =item untie VARIABLE
6810  X<untie>
6811  
6812  Breaks the binding between a variable and a package.  (See C<tie>.)
6813  Has no effect if the variable is not tied.
6814  
6815  =item unshift ARRAY,LIST
6816  X<unshift>
6817  
6818  Does the opposite of a C<shift>.  Or the opposite of a C<push>,
6819  depending on how you look at it.  Prepends list to the front of the
6820  array, and returns the new number of elements in the array.
6821  
6822      unshift(@ARGV, '-e') unless $ARGV[0] =~ /^-/;
6823  
6824  Note the LIST is prepended whole, not one element at a time, so the
6825  prepended elements stay in the same order.  Use C<reverse> to do the
6826  reverse.
6827  
6828  =item use Module VERSION LIST
6829  X<use> X<module> X<import>
6830  
6831  =item use Module VERSION
6832  
6833  =item use Module LIST
6834  
6835  =item use Module
6836  
6837  =item use VERSION
6838  
6839  Imports some semantics into the current package from the named module,
6840  generally by aliasing certain subroutine or variable names into your
6841  package.  It is exactly equivalent to
6842  
6843      BEGIN { require Module; Module->import( LIST ); }
6844  
6845  except that Module I<must> be a bareword.
6846  
6847  In the peculiar C<use VERSION> form, VERSION may be either a numeric
6848  argument such as 5.006, which will be compared to C<$]>, or a literal of
6849  the form v5.6.1, which will be compared to C<$^V> (aka $PERL_VERSION).  A
6850  fatal error is produced if VERSION is greater than the version of the
6851  current Perl interpreter; Perl will not attempt to parse the rest of the
6852  file.  Compare with L</require>, which can do a similar check at run time.
6853  Symmetrically, C<no VERSION> allows you to specify that you want a version
6854  of perl older than the specified one.
6855  
6856  Specifying VERSION as a literal of the form v5.6.1 should generally be
6857  avoided, because it leads to misleading error messages under earlier
6858  versions of Perl that do not support this syntax.  The equivalent numeric
6859  version should be used instead.
6860  
6861  Alternatively, you can use a numeric version C<use 5.006> followed by a
6862  v-string version like C<use v5.10.1>, to avoid the unintuitive C<use
6863  5.010_001>. (older perl versions fail gracefully at the first C<use>,
6864  later perl versions understand the v-string syntax in the second).
6865  
6866      use v5.6.1;        # compile time version check
6867      use 5.6.1;        # ditto
6868      use 5.006_001;    # ditto; preferred for backwards compatibility
6869      use 5.006; use 5.6.1;    # ditto, for compatibility and readability
6870  
6871  This is often useful if you need to check the current Perl version before
6872  C<use>ing library modules that have changed in incompatible ways from
6873  older versions of Perl.  (We try not to do this more than we have to.)
6874  
6875  Also, if the specified perl version is greater than or equal to 5.9.5,
6876  C<use VERSION> will also load the C<feature> pragma and enable all
6877  features available in the requested version.  See L<feature>.
6878  
6879  The C<BEGIN> forces the C<require> and C<import> to happen at compile time.  The
6880  C<require> makes sure the module is loaded into memory if it hasn't been
6881  yet.  The C<import> is not a builtin--it's just an ordinary static method
6882  call into the C<Module> package to tell the module to import the list of
6883  features back into the current package.  The module can implement its
6884  C<import> method any way it likes, though most modules just choose to
6885  derive their C<import> method via inheritance from the C<Exporter> class that
6886  is defined in the C<Exporter> module.  See L<Exporter>.  If no C<import>
6887  method can be found then the call is skipped, even if there is an AUTOLOAD
6888  method.
6889  
6890  If you do not want to call the package's C<import> method (for instance,
6891  to stop your namespace from being altered), explicitly supply the empty list:
6892  
6893      use Module ();
6894  
6895  That is exactly equivalent to
6896  
6897      BEGIN { require Module }
6898  
6899  If the VERSION argument is present between Module and LIST, then the
6900  C<use> will call the VERSION method in class Module with the given
6901  version as an argument.  The default VERSION method, inherited from
6902  the UNIVERSAL class, croaks if the given version is larger than the
6903  value of the variable C<$Module::VERSION>.
6904  
6905  Again, there is a distinction between omitting LIST (C<import> called
6906  with no arguments) and an explicit empty LIST C<()> (C<import> not
6907  called).  Note that there is no comma after VERSION!
6908  
6909  Because this is a wide-open interface, pragmas (compiler directives)
6910  are also implemented this way.  Currently implemented pragmas are:
6911  
6912      use constant;
6913      use diagnostics;
6914      use integer;
6915      use sigtrap  qw(SEGV BUS);
6916      use strict   qw(subs vars refs);
6917      use subs     qw(afunc blurfl);
6918      use warnings qw(all);
6919      use sort     qw(stable _quicksort _mergesort);
6920  
6921  Some of these pseudo-modules import semantics into the current
6922  block scope (like C<strict> or C<integer>, unlike ordinary modules,
6923  which import symbols into the current package (which are effective
6924  through the end of the file).
6925  
6926  There's a corresponding C<no> command that unimports meanings imported
6927  by C<use>, i.e., it calls C<unimport Module LIST> instead of C<import>.
6928  It behaves exactly as C<import> does with respect to VERSION, an
6929  omitted LIST, empty LIST, or no unimport method being found.
6930  
6931      no integer;
6932      no strict 'refs';
6933      no warnings;
6934  
6935  See L<perlmodlib> for a list of standard modules and pragmas.  See L<perlrun>
6936  for the C<-M> and C<-m> command-line options to perl that give C<use>
6937  functionality from the command-line.
6938  
6939  =item utime LIST
6940  X<utime>
6941  
6942  Changes the access and modification times on each file of a list of
6943  files.  The first two elements of the list must be the NUMERICAL access
6944  and modification times, in that order.  Returns the number of files
6945  successfully changed.  The inode change time of each file is set
6946  to the current time.  For example, this code has the same effect as the
6947  Unix touch(1) command when the files I<already exist> and belong to
6948  the user running the program:
6949  
6950      #!/usr/bin/perl
6951      $atime = $mtime = time;
6952      utime $atime, $mtime, @ARGV;
6953  
6954  Since perl 5.7.2, if the first two elements of the list are C<undef>, then
6955  the utime(2) function in the C library will be called with a null second
6956  argument. On most systems, this will set the file's access and
6957  modification times to the current time (i.e. equivalent to the example
6958  above) and will even work on other users' files where you have write
6959  permission:
6960  
6961      utime undef, undef, @ARGV;
6962  
6963  Under NFS this will use the time of the NFS server, not the time of
6964  the local machine.  If there is a time synchronization problem, the
6965  NFS server and local machine will have different times.  The Unix
6966  touch(1) command will in fact normally use this form instead of the
6967  one shown in the first example.
6968  
6969  Note that only passing one of the first two elements as C<undef> will
6970  be equivalent of passing it as 0 and will not have the same effect as
6971  described when they are both C<undef>.  This case will also trigger an
6972  uninitialized warning.
6973  
6974  On systems that support futimes, you might pass file handles among the
6975  files.  On systems that don't support futimes, passing file handles
6976  produces a fatal error at run time.  The file handles must be passed
6977  as globs or references to be recognized.  Barewords are considered
6978  file names.
6979  
6980  =item values HASH
6981  X<values>
6982  
6983  Returns a list consisting of all the values of the named hash.
6984  (In a scalar context, returns the number of values.)
6985  
6986  The values are returned in an apparently random order.  The actual
6987  random order is subject to change in future versions of perl, but it
6988  is guaranteed to be the same order as either the C<keys> or C<each>
6989  function would produce on the same (unmodified) hash.  Since Perl
6990  5.8.1 the ordering is different even between different runs of Perl
6991  for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
6992  
6993  As a side effect, calling values() resets the HASH's internal iterator,
6994  see L</each>. (In particular, calling values() in void context resets
6995  the iterator with no other overhead.)
6996  
6997  Note that the values are not copied, which means modifying them will
6998  modify the contents of the hash:
6999  
7000      for (values %hash)         { s/foo/bar/g }   # modifies %hash values
7001      for (@hash{keys %hash}) { s/foo/bar/g }   # same
7002  
7003  See also C<keys>, C<each>, and C<sort>.
7004  
7005  =item vec EXPR,OFFSET,BITS
7006  X<vec> X<bit> X<bit vector>
7007  
7008  Treats the string in EXPR as a bit vector made up of elements of
7009  width BITS, and returns the value of the element specified by OFFSET
7010  as an unsigned integer.  BITS therefore specifies the number of bits
7011  that are reserved for each element in the bit vector.  This must
7012  be a power of two from 1 to 32 (or 64, if your platform supports
7013  that).
7014  
7015  If BITS is 8, "elements" coincide with bytes of the input string.
7016  
7017  If BITS is 16 or more, bytes of the input string are grouped into chunks
7018  of size BITS/8, and each group is converted to a number as with
7019  pack()/unpack() with big-endian formats C<n>/C<N> (and analogously
7020  for BITS==64).  See L<"pack"> for details.
7021  
7022  If bits is 4 or less, the string is broken into bytes, then the bits
7023  of each byte are broken into 8/BITS groups.  Bits of a byte are
7024  numbered in a little-endian-ish way, as in C<0x01>, C<0x02>,
7025  C<0x04>, C<0x08>, C<0x10>, C<0x20>, C<0x40>, C<0x80>.  For example,
7026  breaking the single input byte C<chr(0x36)> into two groups gives a list
7027  C<(0x6, 0x3)>; breaking it into 4 groups gives C<(0x2, 0x1, 0x3, 0x0)>.
7028  
7029  C<vec> may also be assigned to, in which case parentheses are needed
7030  to give the expression the correct precedence as in
7031  
7032      vec($image, $max_x * $x + $y, 8) = 3;
7033  
7034  If the selected element is outside the string, the value 0 is returned.
7035  If an element off the end of the string is written to, Perl will first
7036  extend the string with sufficiently many zero bytes.   It is an error
7037  to try to write off the beginning of the string (i.e. negative OFFSET).
7038  
7039  If the string happens to be encoded as UTF-8 internally (and thus has
7040  the UTF8 flag set), this is ignored by C<vec>, and it operates on the
7041  internal byte string, not the conceptual character string, even if you
7042  only have characters with values less than 256. 
7043  
7044  Strings created with C<vec> can also be manipulated with the logical
7045  operators C<|>, C<&>, C<^>, and C<~>.  These operators will assume a bit
7046  vector operation is desired when both operands are strings.
7047  See L<perlop/"Bitwise String Operators">.
7048  
7049  The following code will build up an ASCII string saying C<'PerlPerlPerl'>.
7050  The comments show the string after each step.  Note that this code works
7051  in the same way on big-endian or little-endian machines.
7052  
7053      my $foo = '';
7054      vec($foo,  0, 32) = 0x5065726C;    # 'Perl'
7055  
7056      # $foo eq "Perl" eq "\x50\x65\x72\x6C", 32 bits
7057      print vec($foo, 0, 8);        # prints 80 == 0x50 == ord('P')
7058  
7059      vec($foo,  2, 16) = 0x5065;        # 'PerlPe'
7060      vec($foo,  3, 16) = 0x726C;        # 'PerlPerl'
7061      vec($foo,  8,  8) = 0x50;        # 'PerlPerlP'
7062      vec($foo,  9,  8) = 0x65;        # 'PerlPerlPe'
7063      vec($foo, 20,  4) = 2;        # 'PerlPerlPe'   . "\x02"
7064      vec($foo, 21,  4) = 7;        # 'PerlPerlPer'
7065                                          # 'r' is "\x72"
7066      vec($foo, 45,  2) = 3;        # 'PerlPerlPer'  . "\x0c"
7067      vec($foo, 93,  1) = 1;        # 'PerlPerlPer'  . "\x2c"
7068      vec($foo, 94,  1) = 1;        # 'PerlPerlPerl'
7069                                          # 'l' is "\x6c"
7070  
7071  To transform a bit vector into a string or list of 0's and 1's, use these:
7072  
7073      $bits = unpack("b*", $vector);
7074      @bits = split(//, unpack("b*", $vector));
7075  
7076  If you know the exact length in bits, it can be used in place of the C<*>.
7077  
7078  Here is an example to illustrate how the bits actually fall in place:
7079  
7080      #!/usr/bin/perl -wl
7081  
7082      print <<'EOT';
7083                                        0         1         2         3
7084                         unpack("V",$_) 01234567890123456789012345678901
7085      ------------------------------------------------------------------
7086      EOT
7087  
7088      for $w (0..3) {
7089          $width = 2**$w;
7090          for ($shift=0; $shift < $width; ++$shift) {
7091              for ($off=0; $off < 32/$width; ++$off) {
7092                  $str = pack("B*", "0"x32);
7093                  $bits = (1<<$shift);
7094                  vec($str, $off, $width) = $bits;
7095                  $res = unpack("b*",$str);
7096                  $val = unpack("V", $str);
7097                  write;
7098              }
7099          }
7100      }
7101  
7102      format STDOUT =
7103      vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
7104      $off, $width, $bits, $val, $res
7105      .
7106      __END__
7107  
7108  Regardless of the machine architecture on which it is run, the above
7109  example should print the following table:
7110  
7111                                        0         1         2         3
7112                         unpack("V",$_) 01234567890123456789012345678901
7113      ------------------------------------------------------------------
7114      vec($_, 0, 1) = 1   ==          1 10000000000000000000000000000000
7115      vec($_, 1, 1) = 1   ==          2 01000000000000000000000000000000
7116      vec($_, 2, 1) = 1   ==          4 00100000000000000000000000000000
7117      vec($_, 3, 1) = 1   ==          8 00010000000000000000000000000000
7118      vec($_, 4, 1) = 1   ==         16 00001000000000000000000000000000
7119      vec($_, 5, 1) = 1   ==         32 00000100000000000000000000000000
7120      vec($_, 6, 1) = 1   ==         64 00000010000000000000000000000000
7121      vec($_, 7, 1) = 1   ==        128 00000001000000000000000000000000
7122      vec($_, 8, 1) = 1   ==        256 00000000100000000000000000000000
7123      vec($_, 9, 1) = 1   ==        512 00000000010000000000000000000000
7124      vec($_,10, 1) = 1   ==       1024 00000000001000000000000000000000
7125      vec($_,11, 1) = 1   ==       2048 00000000000100000000000000000000
7126      vec($_,12, 1) = 1   ==       4096 00000000000010000000000000000000
7127      vec($_,13, 1) = 1   ==       8192 00000000000001000000000000000000
7128      vec($_,14, 1) = 1   ==      16384 00000000000000100000000000000000
7129      vec($_,15, 1) = 1   ==      32768 00000000000000010000000000000000
7130      vec($_,16, 1) = 1   ==      65536 00000000000000001000000000000000
7131      vec($_,17, 1) = 1   ==     131072 00000000000000000100000000000000
7132      vec($_,18, 1) = 1   ==     262144 00000000000000000010000000000000
7133      vec($_,19, 1) = 1   ==     524288 00000000000000000001000000000000
7134      vec($_,20, 1) = 1   ==    1048576 00000000000000000000100000000000
7135      vec($_,21, 1) = 1   ==    2097152 00000000000000000000010000000000
7136      vec($_,22, 1) = 1   ==    4194304 00000000000000000000001000000000
7137      vec($_,23, 1) = 1   ==    8388608 00000000000000000000000100000000
7138      vec($_,24, 1) = 1   ==   16777216 00000000000000000000000010000000
7139      vec($_,25, 1) = 1   ==   33554432 00000000000000000000000001000000
7140      vec($_,26, 1) = 1   ==   67108864 00000000000000000000000000100000
7141      vec($_,27, 1) = 1   ==  134217728 00000000000000000000000000010000
7142      vec($_,28, 1) = 1   ==  268435456 00000000000000000000000000001000
7143      vec($_,29, 1) = 1   ==  536870912 00000000000000000000000000000100
7144      vec($_,30, 1) = 1   == 1073741824 00000000000000000000000000000010
7145      vec($_,31, 1) = 1   == 2147483648 00000000000000000000000000000001
7146      vec($_, 0, 2) = 1   ==          1 10000000000000000000000000000000
7147      vec($_, 1, 2) = 1   ==          4 00100000000000000000000000000000
7148      vec($_, 2, 2) = 1   ==         16 00001000000000000000000000000000
7149      vec($_, 3, 2) = 1   ==         64 00000010000000000000000000000000
7150      vec($_, 4, 2) = 1   ==        256 00000000100000000000000000000000
7151      vec($_, 5, 2) = 1   ==       1024 00000000001000000000000000000000
7152      vec($_, 6, 2) = 1   ==       4096 00000000000010000000000000000000
7153      vec($_, 7, 2) = 1   ==      16384 00000000000000100000000000000000
7154      vec($_, 8, 2) = 1   ==      65536 00000000000000001000000000000000
7155      vec($_, 9, 2) = 1   ==     262144 00000000000000000010000000000000
7156      vec($_,10, 2) = 1   ==    1048576 00000000000000000000100000000000
7157      vec($_,11, 2) = 1   ==    4194304 00000000000000000000001000000000
7158      vec($_,12, 2) = 1   ==   16777216 00000000000000000000000010000000
7159      vec($_,13, 2) = 1   ==   67108864 00000000000000000000000000100000
7160      vec($_,14, 2) = 1   ==  268435456 00000000000000000000000000001000
7161      vec($_,15, 2) = 1   == 1073741824 00000000000000000000000000000010
7162      vec($_, 0, 2) = 2   ==          2 01000000000000000000000000000000
7163      vec($_, 1, 2) = 2   ==          8 00010000000000000000000000000000
7164      vec($_, 2, 2) = 2   ==         32 00000100000000000000000000000000
7165      vec($_, 3, 2) = 2   ==        128 00000001000000000000000000000000
7166      vec($_, 4, 2) = 2   ==        512 00000000010000000000000000000000
7167      vec($_, 5, 2) = 2   ==       2048 00000000000100000000000000000000
7168      vec($_, 6, 2) = 2   ==       8192 00000000000001000000000000000000
7169      vec($_, 7, 2) = 2   ==      32768 00000000000000010000000000000000
7170      vec($_, 8, 2) = 2   ==     131072 00000000000000000100000000000000
7171      vec($_, 9, 2) = 2   ==     524288 00000000000000000001000000000000
7172      vec($_,10, 2) = 2   ==    2097152 00000000000000000000010000000000
7173      vec($_,11, 2) = 2   ==    8388608 00000000000000000000000100000000
7174      vec($_,12, 2) = 2   ==   33554432 00000000000000000000000001000000
7175      vec($_,13, 2) = 2   ==  134217728 00000000000000000000000000010000
7176      vec($_,14, 2) = 2   ==  536870912 00000000000000000000000000000100
7177      vec($_,15, 2) = 2   == 2147483648 00000000000000000000000000000001
7178      vec($_, 0, 4) = 1   ==          1 10000000000000000000000000000000
7179      vec($_, 1, 4) = 1   ==         16 00001000000000000000000000000000
7180      vec($_, 2, 4) = 1   ==        256 00000000100000000000000000000000
7181      vec($_, 3, 4) = 1   ==       4096 00000000000010000000000000000000
7182      vec($_, 4, 4) = 1   ==      65536 00000000000000001000000000000000
7183      vec($_, 5, 4) = 1   ==    1048576 00000000000000000000100000000000
7184      vec($_, 6, 4) = 1   ==   16777216 00000000000000000000000010000000
7185      vec($_, 7, 4) = 1   ==  268435456 00000000000000000000000000001000
7186      vec($_, 0, 4) = 2   ==          2 01000000000000000000000000000000
7187      vec($_, 1, 4) = 2   ==         32 00000100000000000000000000000000
7188      vec($_, 2, 4) = 2   ==        512 00000000010000000000000000000000
7189      vec($_, 3, 4) = 2   ==       8192 00000000000001000000000000000000
7190      vec($_, 4, 4) = 2   ==     131072 00000000000000000100000000000000
7191      vec($_, 5, 4) = 2   ==    2097152 00000000000000000000010000000000
7192      vec($_, 6, 4) = 2   ==   33554432 00000000000000000000000001000000
7193      vec($_, 7, 4) = 2   ==  536870912 00000000000000000000000000000100
7194      vec($_, 0, 4) = 4   ==          4 00100000000000000000000000000000
7195      vec($_, 1, 4) = 4   ==         64 00000010000000000000000000000000
7196      vec($_, 2, 4) = 4   ==       1024 00000000001000000000000000000000
7197      vec($_, 3, 4) = 4   ==      16384 00000000000000100000000000000000
7198      vec($_, 4, 4) = 4   ==     262144 00000000000000000010000000000000
7199      vec($_, 5, 4) = 4   ==    4194304 00000000000000000000001000000000
7200      vec($_, 6, 4) = 4   ==   67108864 00000000000000000000000000100000
7201      vec($_, 7, 4) = 4   == 1073741824 00000000000000000000000000000010
7202      vec($_, 0, 4) = 8   ==          8 00010000000000000000000000000000
7203      vec($_, 1, 4) = 8   ==        128 00000001000000000000000000000000
7204      vec($_, 2, 4) = 8   ==       2048 00000000000100000000000000000000
7205      vec($_, 3, 4) = 8   ==      32768 00000000000000010000000000000000
7206      vec($_, 4, 4) = 8   ==     524288 00000000000000000001000000000000
7207      vec($_, 5, 4) = 8   ==    8388608 00000000000000000000000100000000
7208      vec($_, 6, 4) = 8   ==  134217728 00000000000000000000000000010000
7209      vec($_, 7, 4) = 8   == 2147483648 00000000000000000000000000000001
7210      vec($_, 0, 8) = 1   ==          1 10000000000000000000000000000000
7211      vec($_, 1, 8) = 1   ==        256 00000000100000000000000000000000
7212      vec($_, 2, 8) = 1   ==      65536 00000000000000001000000000000000
7213      vec($_, 3, 8) = 1   ==   16777216 00000000000000000000000010000000
7214      vec($_, 0, 8) = 2   ==          2 01000000000000000000000000000000
7215      vec($_, 1, 8) = 2   ==        512 00000000010000000000000000000000
7216      vec($_, 2, 8) = 2   ==     131072 00000000000000000100000000000000
7217      vec($_, 3, 8) = 2   ==   33554432 00000000000000000000000001000000
7218      vec($_, 0, 8) = 4   ==          4 00100000000000000000000000000000
7219      vec($_, 1, 8) = 4   ==       1024 00000000001000000000000000000000
7220      vec($_, 2, 8) = 4   ==     262144 00000000000000000010000000000000
7221      vec($_, 3, 8) = 4   ==   67108864 00000000000000000000000000100000
7222      vec($_, 0, 8) = 8   ==          8 00010000000000000000000000000000
7223      vec($_, 1, 8) = 8   ==       2048 00000000000100000000000000000000
7224      vec($_, 2, 8) = 8   ==     524288 00000000000000000001000000000000
7225      vec($_, 3, 8) = 8   ==  134217728 00000000000000000000000000010000
7226      vec($_, 0, 8) = 16  ==         16 00001000000000000000000000000000
7227      vec($_, 1, 8) = 16  ==       4096 00000000000010000000000000000000
7228      vec($_, 2, 8) = 16  ==    1048576 00000000000000000000100000000000
7229      vec($_, 3, 8) = 16  ==  268435456 00000000000000000000000000001000
7230      vec($_, 0, 8) = 32  ==         32 00000100000000000000000000000000
7231      vec($_, 1, 8) = 32  ==       8192 00000000000001000000000000000000
7232      vec($_, 2, 8) = 32  ==    2097152 00000000000000000000010000000000
7233      vec($_, 3, 8) = 32  ==  536870912 00000000000000000000000000000100
7234      vec($_, 0, 8) = 64  ==         64 00000010000000000000000000000000
7235      vec($_, 1, 8) = 64  ==      16384 00000000000000100000000000000000
7236      vec($_, 2, 8) = 64  ==    4194304 00000000000000000000001000000000
7237      vec($_, 3, 8) = 64  == 1073741824 00000000000000000000000000000010
7238      vec($_, 0, 8) = 128 ==        128 00000001000000000000000000000000
7239      vec($_, 1, 8) = 128 ==      32768 00000000000000010000000000000000
7240      vec($_, 2, 8) = 128 ==    8388608 00000000000000000000000100000000
7241      vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
7242  
7243  =item wait
7244  X<wait>
7245  
7246  Behaves like the wait(2) system call on your system: it waits for a child
7247  process to terminate and returns the pid of the deceased process, or
7248  C<-1> if there are no child processes.  The status is returned in C<$?>
7249  and C<{^CHILD_ERROR_NATIVE}>.
7250  Note that a return value of C<-1> could mean that child processes are
7251  being automatically reaped, as described in L<perlipc>.
7252  
7253  =item waitpid PID,FLAGS
7254  X<waitpid>
7255  
7256  Waits for a particular child process to terminate and returns the pid of
7257  the deceased process, or C<-1> if there is no such child process.  On some
7258  systems, a value of 0 indicates that there are processes still running.
7259  The status is returned in C<$?> and C<{^CHILD_ERROR_NATIVE}>.  If you say
7260  
7261      use POSIX ":sys_wait_h";
7262      #...
7263      do {
7264      $kid = waitpid(-1, WNOHANG);
7265      } while $kid > 0;
7266  
7267  then you can do a non-blocking wait for all pending zombie processes.
7268  Non-blocking wait is available on machines supporting either the
7269  waitpid(2) or wait4(2) system calls.  However, waiting for a particular
7270  pid with FLAGS of C<0> is implemented everywhere.  (Perl emulates the
7271  system call by remembering the status values of processes that have
7272  exited but have not been harvested by the Perl script yet.)
7273  
7274  Note that on some systems, a return value of C<-1> could mean that child
7275  processes are being automatically reaped.  See L<perlipc> for details,
7276  and for other examples.
7277  
7278  =item wantarray
7279  X<wantarray> X<context>
7280  
7281  Returns true if the context of the currently executing subroutine or
7282  C<eval> is looking for a list value.  Returns false if the context is
7283  looking for a scalar.  Returns the undefined value if the context is
7284  looking for no value (void context).
7285  
7286      return unless defined wantarray;    # don't bother doing more
7287      my @a = complex_calculation();
7288      return wantarray ? @a : "@a";
7289  
7290  C<wantarray()>'s result is unspecified in the top level of a file,
7291  in a C<BEGIN>, C<UNITCHECK>, C<CHECK>, C<INIT> or C<END> block, or
7292  in a C<DESTROY> method.
7293  
7294  This function should have been named wantlist() instead.
7295  
7296  =item warn LIST
7297  X<warn> X<warning> X<STDERR>
7298  
7299  Prints the value of LIST to STDERR.  If the last element of LIST does
7300  not end in a newline, it appends the same file/line number text as C<die>
7301  does.
7302  
7303  If LIST is empty and C<$@> already contains a value (typically from a
7304  previous eval) that value is used after appending C<"\t...caught">
7305  to C<$@>.  This is useful for staying almost, but not entirely similar to
7306  C<die>.
7307  
7308  If C<$@> is empty then the string C<"Warning: Something's wrong"> is used.
7309  
7310  No message is printed if there is a C<$SIG{__WARN__}> handler
7311  installed.  It is the handler's responsibility to deal with the message
7312  as it sees fit (like, for instance, converting it into a C<die>).  Most
7313  handlers must therefore make arrangements to actually display the
7314  warnings that they are not prepared to deal with, by calling C<warn>
7315  again in the handler.  Note that this is quite safe and will not
7316  produce an endless loop, since C<__WARN__> hooks are not called from
7317  inside one.
7318  
7319  You will find this behavior is slightly different from that of
7320  C<$SIG{__DIE__}> handlers (which don't suppress the error text, but can
7321  instead call C<die> again to change it).
7322  
7323  Using a C<__WARN__> handler provides a powerful way to silence all
7324  warnings (even the so-called mandatory ones).  An example:
7325  
7326      # wipe out *all* compile-time warnings
7327      BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } }
7328      my $foo = 10;
7329      my $foo = 20;          # no warning about duplicate my $foo,
7330                             # but hey, you asked for it!
7331      # no compile-time or run-time warnings before here
7332      $DOWARN = 1;
7333  
7334      # run-time warnings enabled after here
7335      warn "\$foo is alive and $foo!";     # does show up
7336  
7337  See L<perlvar> for details on setting C<%SIG> entries, and for more
7338  examples.  See the Carp module for other kinds of warnings using its
7339  carp() and cluck() functions.
7340  
7341  =item write FILEHANDLE
7342  X<write>
7343  
7344  =item write EXPR
7345  
7346  =item write
7347  
7348  Writes a formatted record (possibly multi-line) to the specified FILEHANDLE,
7349  using the format associated with that file.  By default the format for
7350  a file is the one having the same name as the filehandle, but the
7351  format for the current output channel (see the C<select> function) may be set
7352  explicitly by assigning the name of the format to the C<$~> variable.
7353  
7354  Top of form processing is handled automatically:  if there is
7355  insufficient room on the current page for the formatted record, the
7356  page is advanced by writing a form feed, a special top-of-page format
7357  is used to format the new page header, and then the record is written.
7358  By default the top-of-page format is the name of the filehandle with
7359  "_TOP" appended, but it may be dynamically set to the format of your
7360  choice by assigning the name to the C<$^> variable while the filehandle is
7361  selected.  The number of lines remaining on the current page is in
7362  variable C<$->, which can be set to C<0> to force a new page.
7363  
7364  If FILEHANDLE is unspecified, output goes to the current default output
7365  channel, which starts out as STDOUT but may be changed by the
7366  C<select> operator.  If the FILEHANDLE is an EXPR, then the expression
7367  is evaluated and the resulting string is used to look up the name of
7368  the FILEHANDLE at run time.  For more on formats, see L<perlform>.
7369  
7370  Note that write is I<not> the opposite of C<read>.  Unfortunately.
7371  
7372  =item y///
7373  
7374  The transliteration operator.  Same as C<tr///>.  See L<perlop>.
7375  
7376  =back


Generated: Tue Mar 17 22:47:18 2015 Cross-referenced by PHPXref 0.7.1