This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
e532ed2aa3018be043ae46ae84ff17ef3f1fde24
[perl5.git] / pod / perlfunc.pod
1 =head1 NAME
2
3 perlfunc - Perl builtin functions
4
5 =head1 DESCRIPTION
6
7 The functions in this section can serve as terms in an expression.
8 They fall into two major categories: list operators and named unary
9 operators.  These differ in their precedence relationship with a
10 following comma.  (See the precedence table in L<perlop>.)  List
11 operators take more than one argument, while unary operators can never
12 take more than one argument.  Thus, a comma terminates the argument of
13 a unary operator, but merely separates the arguments of a list
14 operator.  A unary operator generally provides a scalar context to its
15 argument, while a list operator may provide either scalar and list
16 contexts for its arguments.  If it does both, the scalar arguments will
17 be first, and the list argument will follow.  (Note that there can ever
18 be only one list argument.)  For instance, splice() has three scalar
19 arguments followed by a list.
20
21 In the syntax descriptions that follow, list operators that expect a
22 list (and provide list context for the elements of the list) are shown
23 with LIST as an argument.  Such a list may consist of any combination
24 of scalar arguments or list values; the list values will be included
25 in the list as if each individual element were interpolated at that
26 point in the list, forming a longer single-dimensional list value.
27 Elements of the LIST should be separated by commas.
28
29 Any function in the list below may be used either with or without
30 parentheses around its arguments.  (The syntax descriptions omit the
31 parentheses.)  If you use the parentheses, the simple (but occasionally
32 surprising) rule is this: It I<LOOKS> like a function, therefore it I<IS> a
33 function, and precedence doesn't matter.  Otherwise it's a list
34 operator or unary operator, and precedence does matter.  And whitespace
35 between the function and left parenthesis doesn't count--so you need to
36 be careful sometimes:
37
38     print 1+2+3;        # Prints 6.
39     print(1+2) + 3;     # Prints 3.
40     print (1+2)+3;      # Also prints 3!
41     print +(1+2)+3;     # Prints 6.
42     print ((1+2)+3);    # Prints 6.
43
44 If you run Perl with the B<-w> switch it can warn you about this.  For
45 example, the third line above produces:
46
47     print (...) interpreted as function at - line 1.
48     Useless use of integer addition in void context at - line 1.
49
50 For functions that can be used in either a scalar or list context,
51 non-abortive failure is generally indicated in a scalar context by
52 returning the undefined value, and in a list context by returning the
53 null list.
54
55 Remember the following rule:
56
57 =over 8
58
59 =item  I<THERE IS NO GENERAL RULE FOR CONVERTING A LIST INTO A SCALAR!>
60
61 =back
62
63 Each operator and function decides which sort of value it would be most
64 appropriate to return in a scalar context.  Some operators return the
65 length of the list that would have been returned in a list context.  Some
66 operators return the first value in the list.  Some operators return the
67 last value in the list.  Some operators return a count of successful
68 operations.  In general, they do what you want, unless you want
69 consistency.
70
71 =head2 Perl Functions by Category
72
73 Here are Perl's functions (including things that look like
74 functions, like some of the keywords and named operators)
75 arranged by category.  Some functions appear in more
76 than one place.
77
78 =over
79
80 =item Functions for SCALARs or strings
81
82 chomp, chop, chr, crypt, hex, index, lc, lcfirst, length,
83 oct, ord, pack, q/STRING/, qq/STRING/, reverse, rindex,
84 sprintf, substr, tr///, uc, ucfirst, y///
85
86 =item Regular expressions and pattern matching
87
88 m//, pos, quotemeta, s///, split, study
89
90 =item Numeric functions
91
92 abs, atan2, cos, exp, hex, int, log, oct, rand, sin, sqrt,
93 srand
94
95 =item Functions for real @ARRAYs
96
97 pop, push, shift, splice, unshift
98
99 =item Functions for list data
100
101 grep, join, map, qw/STRING/, reverse, sort, unpack
102
103 =item Functions for real %HASHes
104
105 delete, each, exists, keys, values
106
107 =item Input and output functions
108
109 binmode, close, closedir, dbmclose, dbmopen, die, eof,
110 fileno, flock, format, getc, print, printf, read, readdir,
111 rewinddir, seek, seekdir, select, syscall, sysread,
112 syswrite, tell, telldir, truncate, warn, write
113
114 =item Functions for fixed length data or records
115
116 pack, read, syscall, sysread, syswrite, unpack, vec
117
118 =item Functions for filehandles, files, or directories
119
120 I<-X>, chdir, chmod, chown, chroot, fcntl, glob, ioctl, link,
121 lstat, mkdir, open, opendir, readlink, rename, rmdir,
122 stat, symlink, umask, unlink, utime
123
124 =item Keywords related to the control flow of your perl program
125
126 caller, continue, die, do, dump, eval, exit, goto, last,
127 next, redo, return, sub, wantarray
128
129 =item Keywords related to scoping 
130
131 caller, import, local, my, package, use
132
133 =item Miscellaneous functions
134
135 defined, dump, eval, formline, local, my, reset, scalar,
136 undef, wantarray
137
138 =item Functions for processes and process groups
139
140 alarm, exec, fork, getpgrp, getppid, getpriority, kill,
141 pipe, qx/STRING/, setpgrp, setpriority, sleep, system,
142 times, wait, waitpid
143
144 =item Keywords related to perl modules
145
146 do, import, no, package, require, use
147
148 =item Keywords related to classes and object-orientedness
149
150 bless, dbmclose, dbmopen, package, ref, tie, tied, untie, use
151
152 =item Low-level socket functions
153
154 accept, bind, connect, getpeername, getsockname,
155 getsockopt, listen, recv, send, setsockopt, shutdown,
156 socket, socketpair
157
158 =item System V interprocess communication functions
159
160 msgctl, msgget, msgrcv, msgsnd, semctl, semget, semop,
161 shmctl, shmget, shmread, shmwrite
162
163 =item Fetching user and group info
164
165 endgrent, endhostent, endnetent, endpwent, getgrent,
166 getgrgid, getgrnam, getlogin, getpwent, getpwnam,
167 getpwuid, setgrent, setpwent
168
169 =item Fetching network info
170
171 endprotoent, endservent, gethostbyaddr, gethostbyname,
172 gethostent, getnetbyaddr, getnetbyname, getnetent,
173 getprotobyname, getprotobynumber, getprotoent,
174 getservbyname, getservbyport, getservent, sethostent,
175 setnetent, setprotoent, setservent
176
177 =item Time-related functions
178
179 gmtime, localtime, time, times
180
181 =item Functions new in perl5
182
183 abs, bless, chomp, chr, exists, formline, glob, import, lc,
184 lcfirst, map, my, no, prototype, qx, qw, readline, readpipe,
185 ref, sub*, sysopen, tie, tied, uc, ucfirst, untie, use
186
187 * - C<sub> was a keyword in perl4, but in perl5 it is an
188 operator which can be used in expressions.
189
190 =item Functions obsoleted in perl5
191
192 dbmclose, dbmopen
193
194
195 =back
196
197 =head2 Alphabetical Listing of Perl Functions
198
199
200 =over 8
201
202 =item -X FILEHANDLE
203
204 =item -X EXPR
205
206 =item -X
207
208 A file test, where X is one of the letters listed below.  This unary
209 operator takes one argument, either a filename or a filehandle, and
210 tests the associated file to see if something is true about it.  If the
211 argument is omitted, tests $_, except for C<-t>, which tests STDIN.
212 Unless otherwise documented, it returns C<1> for TRUE and C<''> for FALSE, or
213 the undefined value if the file doesn't exist.  Despite the funny
214 names, precedence is the same as any other named unary operator, and
215 the argument may be parenthesized like any other unary operator.  The
216 operator may be any of:
217
218     -r  File is readable by effective uid/gid.
219     -w  File is writable by effective uid/gid.
220     -x  File is executable by effective uid/gid.
221     -o  File is owned by effective uid.
222
223     -R  File is readable by real uid/gid.
224     -W  File is writable by real uid/gid.
225     -X  File is executable by real uid/gid.
226     -O  File is owned by real uid.
227
228     -e  File exists.
229     -z  File has zero size.
230     -s  File has non-zero size (returns size).
231
232     -f  File is a plain file.
233     -d  File is a directory.
234     -l  File is a symbolic link.
235     -p  File is a named pipe (FIFO).
236     -S  File is a socket.
237     -b  File is a block special file.
238     -c  File is a character special file.
239     -t  Filehandle is opened to a tty.
240
241     -u  File has setuid bit set.
242     -g  File has setgid bit set.
243     -k  File has sticky bit set.
244
245     -T  File is a text file.
246     -B  File is a binary file (opposite of -T).
247
248     -M  Age of file in days when script started.
249     -A  Same for access time.
250     -C  Same for inode change time.
251
252 The interpretation of the file permission operators C<-r>, C<-R>, C<-w>,
253 C<-W>, C<-x>, and C<-X> is based solely on the mode of the file and the
254 uids and gids of the user.  There may be other reasons you can't actually
255 read, write or execute the file.  Also note that, for the superuser,
256 C<-r>, C<-R>, C<-w>, and C<-W> always return 1, and C<-x> and C<-X> return
257 1 if any execute bit is set in the mode.  Scripts run by the superuser may
258 thus need to do a stat() to determine the actual mode of the
259 file, or temporarily set the uid to something else.
260
261 Example:
262
263     while (<>) {
264         chop;
265         next unless -f $_;      # ignore specials
266         ...
267     }
268
269 Note that C<-s/a/b/> does not do a negated substitution.  Saying
270 C<-exp($foo)> still works as expected, however--only single letters
271 following a minus are interpreted as file tests.
272
273 The C<-T> and C<-B> switches work as follows.  The first block or so of the
274 file is examined for odd characters such as strange control codes or
275 characters with the high bit set.  If too many odd characters (E<gt>30%)
276 are found, it's a C<-B> file, otherwise it's a C<-T> file.  Also, any file
277 containing null in the first block is considered a binary file.  If C<-T>
278 or C<-B> is used on a filehandle, the current stdio buffer is examined
279 rather than the first block.  Both C<-T> and C<-B> return TRUE on a null
280 file, or a file at EOF when testing a filehandle.  Because you have to 
281 read a file to do the C<-T> test, on most occasions you want to use a C<-f>
282 against the file first, as in C<next unless -f $file && -T $file>.
283
284 If any of the file tests (or either the stat() or lstat() operators) are given
285 the special filehandle consisting of a solitary underline, then the stat
286 structure of the previous file test (or stat operator) is used, saving
287 a system call.  (This doesn't work with C<-t>, and you need to remember
288 that lstat() and C<-l> will leave values in the stat structure for the
289 symbolic link, not the real file.)  Example:
290
291     print "Can do.\n" if -r $a || -w _ || -x _;
292
293     stat($filename);
294     print "Readable\n" if -r _;
295     print "Writable\n" if -w _;
296     print "Executable\n" if -x _;
297     print "Setuid\n" if -u _;
298     print "Setgid\n" if -g _;
299     print "Sticky\n" if -k _;
300     print "Text\n" if -T _;
301     print "Binary\n" if -B _;
302
303 =item abs VALUE
304
305 =item abs 
306
307 Returns the absolute value of its argument.
308 If VALUE is omitted, uses $_.
309
310 =item accept NEWSOCKET,GENERICSOCKET
311
312 Accepts an incoming socket connect, just as the accept(2) system call
313 does.  Returns the packed address if it succeeded, FALSE otherwise.
314 See example in L<perlipc/"Sockets: Client/Server Communication">.
315
316 =item alarm SECONDS
317
318 =item alarm 
319
320 Arranges to have a SIGALRM delivered to this process after the
321 specified number of seconds have elapsed.  If SECONDS is not specified,
322 the value stored in $_ is used. (On some machines,
323 unfortunately, the elapsed time may be up to one second less than you
324 specified because of how seconds are counted.)  Only one timer may be
325 counting at once.  Each call disables the previous timer, and an
326 argument of 0 may be supplied to cancel the previous timer without
327 starting a new one.  The returned value is the amount of time remaining
328 on the previous timer.
329
330 For delays of finer granularity than one second, you may use Perl's
331 syscall() interface to access setitimer(2) if your system supports it, 
332 or else see L</select()> below.  It is not advised to intermix alarm() 
333 and sleep() calls.
334
335 If you want to use alarm() to time out a system call you need to use an
336 eval/die pair. You can't rely on the alarm causing the system call to
337 fail with $! set to EINTR because Perl sets up signal handlers to
338 restart system calls on some systems.  Using eval/die always works.
339
340     eval {
341         local $SIG{ALRM} = sub { die "alarm\n" };       # NB \n required
342         alarm $timeout;
343         $nread = sysread SOCKET, $buffer, $size;
344         alarm 0;
345     };
346     die if $@ && $@ ne "alarm\n";       # propagate errors
347     if ($@) {
348         # timed out
349     }
350     else {
351         # didn't
352     }
353
354 =item atan2 Y,X
355
356 Returns the arctangent of Y/X in the range -PI to PI.
357
358 For the tangent operation, you may use the POSIX::tan()
359 function, or use the familiar relation:
360
361     sub tan { sin($_[0]) / cos($_[0])  }
362
363 =item bind SOCKET,NAME
364
365 Binds a network address to a socket, just as the bind system call
366 does.  Returns TRUE if it succeeded, FALSE otherwise.  NAME should be a
367 packed address of the appropriate type for the socket.  See the examples in
368 L<perlipc/"Sockets: Client/Server Communication">.
369
370 =item binmode FILEHANDLE
371
372 Arranges for the file to be read or written in "binary" mode in operating
373 systems that distinguish between binary and text files.  Files that are
374 not in binary mode have CR LF sequences translated to LF on input and LF
375 translated to CR LF on output.  Binmode has no effect under Unix; in DOS
376 and similarly archaic systems, it may be imperative--otherwise your
377 DOS-damaged C library may mangle your file.  The key distinction between
378 systems that need binmode and those that don't is their text file
379 formats.  Systems like Unix and Plan9 that delimit lines with a single
380 character, and that encode that character in C as '\n', do not need
381 C<binmode>.  The rest need it.  If FILEHANDLE is an expression, the value
382 is taken as the name of the filehandle.
383
384 =item bless REF,CLASSNAME
385
386 =item bless REF
387
388 This function tells the thingy referenced by REF that it is now
389 an object in the CLASSNAME package--or the current package if no CLASSNAME
390 is specified, which is often the case.  It returns the reference for
391 convenience, because a bless() is often the last thing in a constructor.
392 Always use the two-argument version if the function doing the blessing
393 might be inherited by a derived class.  See L<perlobj> for more about the
394 blessing (and blessings) of objects.
395
396 =item caller EXPR
397
398 =item caller
399
400 Returns the context of the current subroutine call.  In a scalar context,
401 returns the caller's package name if there is a caller, that is, if
402 we're in a subroutine or eval() or require(), and the undefined value
403 otherwise.  In a list context, returns
404
405     ($package, $filename, $line) = caller;
406
407 With EXPR, it returns some extra information that the debugger uses to
408 print a stack trace.  The value of EXPR indicates how many call frames
409 to go back before the current one.
410
411     ($package, $filename, $line, $subroutine, 
412      $hasargs, $wantarray, $evaltext, $is_require) = caller($i);
413
414 Here $subroutine may be C<"(eval)"> if the frame is not a subroutine
415 call, but C<L<eval>>. In such a case additional elements $evaltext and
416 $is_require are set: $is_require is true if the frame is created by
417 C<L<require>> or C<L<use>> statement, $evaltext contains the text of
418 C<L<eval EXPR>> statement. In particular, for C<L<eval BLOCK>>
419 statement $filename is C<"(eval)">, but $evaltext is undefined. (Note
420 also that C<L<use>> statement creates a C<L<require>> frame inside
421 an C<L<eval EXPR>>) frame.
422
423 Furthermore, when called from within the DB package, caller returns more
424 detailed information: it sets the list variable @DB::args to be the
425 arguments with which that subroutine was invoked.
426
427 =item chdir EXPR
428
429 Changes the working directory to EXPR, if possible.  If EXPR is
430 omitted, changes to home directory.  Returns TRUE upon success, FALSE
431 otherwise.  See example under die().
432
433 =item chmod LIST
434
435 Changes the permissions of a list of files.  The first element of the
436 list must be the numerical mode, which should probably be an octal
437 number.  Returns the number of files successfully changed.
438
439     $cnt = chmod 0755, 'foo', 'bar';
440     chmod 0755, @executables;
441
442 =item chomp VARIABLE
443
444 =item chomp LIST
445
446 =item chomp
447
448 This is a slightly safer version of chop (see below).  It removes any
449 line ending that corresponds to the current value of C<$/> (also known as
450 $INPUT_RECORD_SEPARATOR in the C<English> module).  It returns the total
451 number of characters removed from all its arguments.  It's often used to
452 remove the newline from the end of an input record when you're worried
453 that the final record may be missing its newline.  When in paragraph mode
454 (C<$/ = "">), it removes all trailing newlines from the string.  If
455 VARIABLE is omitted, it chomps $_.  Example:
456
457     while (<>) {
458         chomp;  # avoid \n on last field
459         @array = split(/:/);
460         ...
461     }
462
463 You can actually chomp anything that's an lvalue, including an assignment:
464
465     chomp($cwd = `pwd`);
466     chomp($answer = <STDIN>);
467
468 If you chomp a list, each element is chomped, and the total number of
469 characters removed is returned.
470
471 =item chop VARIABLE
472
473 =item chop LIST
474
475 =item chop
476
477 Chops off the last character of a string and returns the character
478 chopped.  It's used primarily to remove the newline from the end of an
479 input record, but is much more efficient than C<s/\n//> because it neither
480 scans nor copies the string.  If VARIABLE is omitted, chops $_.
481 Example:
482
483     while (<>) {
484         chop;   # avoid \n on last field
485         @array = split(/:/);
486         ...
487     }
488
489 You can actually chop anything that's an lvalue, including an assignment:
490
491     chop($cwd = `pwd`);
492     chop($answer = <STDIN>);
493
494 If you chop a list, each element is chopped.  Only the value of the
495 last chop is returned.
496
497 Note that chop returns the last character.  To return all but the last
498 character, use C<substr($string, 0, -1)>.
499
500 =item chown LIST
501
502 Changes the owner (and group) of a list of files.  The first two
503 elements of the list must be the I<NUMERICAL> uid and gid, in that order.
504 Returns the number of files successfully changed.
505
506     $cnt = chown $uid, $gid, 'foo', 'bar';
507     chown $uid, $gid, @filenames;
508
509 Here's an example that looks up non-numeric uids in the passwd file:
510
511     print "User: ";
512     chop($user = <STDIN>);
513     print "Files: "
514     chop($pattern = <STDIN>);
515
516     ($login,$pass,$uid,$gid) = getpwnam($user)
517         or die "$user not in passwd file";
518
519     @ary = <${pattern}>;        # expand filenames
520     chown $uid, $gid, @ary;
521
522 On most systems, you are not allowed to change the ownership of the 
523 file unless you're the superuser, although you should be able to change
524 the group to any of your secondary groups.  On insecure systems, these
525 restrictions may be relaxed, but this is not a portable assumption.
526
527 =item chr NUMBER
528
529 =item chr 
530
531 Returns the character represented by that NUMBER in the character set.
532 For example, C<chr(65)> is "A" in ASCII.
533
534 If NUMBER is omitted, uses $_.
535
536 =item chroot FILENAME
537
538 =item chroot 
539
540 This function works as the system call by the same name: it makes the
541 named directory the new root directory for all further pathnames that
542 begin with a "/" by your process and all of its children.  (It doesn't
543 change your current working directory, which is unaffected.)  For security
544 reasons, this call is restricted to the superuser.  If FILENAME is
545 omitted, does chroot to $_.
546
547 =item close FILEHANDLE
548
549 Closes the file or pipe associated with the file handle, returning TRUE
550 only if stdio successfully flushes buffers and closes the system file
551 descriptor.  You don't have to close FILEHANDLE if you are immediately
552 going to do another open() on it, because open() will close it for you.  (See
553 open().)  However, an explicit close on an input file resets the line
554 counter ($.), while the implicit close done by open() does not.  Also,
555 closing a pipe will wait for the process executing on the pipe to
556 complete, in case you want to look at the output of the pipe
557 afterwards.  Closing a pipe explicitly also puts the status value of
558 the command into C<$?>.  Example:
559
560     open(OUTPUT, '|sort >foo'); # pipe to sort
561     ...                         # print stuff to output
562     close OUTPUT;               # wait for sort to finish
563     open(INPUT, 'foo');         # get sort's results
564
565 FILEHANDLE may be an expression whose value gives the real filehandle name.
566
567 =item closedir DIRHANDLE
568
569 Closes a directory opened by opendir().
570
571 =item connect SOCKET,NAME
572
573 Attempts to connect to a remote socket, just as the connect system call
574 does.  Returns TRUE if it succeeded, FALSE otherwise.  NAME should be a
575 packed address of the appropriate type for the socket.  See the examples in
576 L<perlipc/"Sockets: Client/Server Communication">.
577
578 =item continue BLOCK
579
580 Actually a flow control statement rather than a function.  If there is a
581 C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
582 C<foreach>), it is always executed just before the conditional is about to
583 be evaluated again, just like the third part of a C<for> loop in C.  Thus
584 it can be used to increment a loop variable, even when the loop has been
585 continued via the C<next> statement (which is similar to the C C<continue>
586 statement).
587
588 =item cos EXPR
589
590 Returns the cosine of EXPR (expressed in radians).  If EXPR is omitted
591 takes cosine of $_.
592
593 For the inverse cosine operation, you may use the POSIX::acos()
594 function, or use this relation:
595
596     sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
597
598 =item crypt PLAINTEXT,SALT
599
600 Encrypts a string exactly like the crypt(3) function in the C library
601 (assuming that you actually have a version there that has not been
602 extirpated as a potential munition).  This can prove useful for checking
603 the password file for lousy passwords, amongst other things.  Only the
604 guys wearing white hats should do this.
605
606 Here's an example that makes sure that whoever runs this program knows
607 their own password:
608
609     $pwd = (getpwuid($<))[1];
610     $salt = substr($pwd, 0, 2);
611
612     system "stty -echo";
613     print "Password: ";
614     chop($word = <STDIN>);
615     print "\n";
616     system "stty echo";
617
618     if (crypt($word, $salt) ne $pwd) {
619         die "Sorry...\n";
620     } else {
621         print "ok\n";
622     } 
623
624 Of course, typing in your own password to whomever asks you 
625 for it is unwise.
626
627 =item dbmclose ASSOC_ARRAY
628
629 [This function has been superseded by the untie() function.]
630
631 Breaks the binding between a DBM file and an associative array.
632
633 =item dbmopen ASSOC,DBNAME,MODE
634
635 [This function has been superseded by the tie() function.]
636
637 This binds a dbm(3), ndbm(3), sdbm(3), gdbm(), or Berkeley DB file to an
638 associative array.  ASSOC is the name of the associative array.  (Unlike
639 normal open, the first argument is I<NOT> a filehandle, even though it
640 looks like one).  DBNAME is the name of the database (without the F<.dir>
641 or F<.pag> extension if any).  If the database does not exist, it is
642 created with protection specified by MODE (as modified by the umask()).
643 If your system supports only the older DBM functions, you may perform only
644 one dbmopen() in your program.  In older versions of Perl, if your system
645 had neither DBM nor ndbm, calling dbmopen() produced a fatal error; it now
646 falls back to sdbm(3).
647
648 If you don't have write access to the DBM file, you can only read
649 associative array variables, not set them.  If you want to test whether
650 you can write, either use file tests or try setting a dummy array entry
651 inside an eval(), which will trap the error.
652
653 Note that functions such as keys() and values() may return huge array
654 values when used on large DBM files.  You may prefer to use the each()
655 function to iterate over large DBM files.  Example:
656
657     # print out history file offsets
658     dbmopen(%HIST,'/usr/lib/news/history',0666);
659     while (($key,$val) = each %HIST) {
660         print $key, ' = ', unpack('L',$val), "\n";
661     }
662     dbmclose(%HIST);
663
664 See also L<AnyDBM_File> for a more general description of the pros and
665 cons of the various dbm approaches, as well as L<DB_File> for a particularly
666 rich implementation.
667
668 =item defined EXPR
669
670 =item defined 
671
672 Returns a boolean value saying whether EXPR has a real value
673 or not. If EXPR is not present, $_ will be checked. Many operations
674 return the undefined value under exceptional conditions, such as end of
675 file, uninitialized variable, system error and such.  This function
676 allows you to distinguish between an undefined
677 null scalar and a defined null scalar with operations that might return
678 a real null string, such as referencing elements of an array.  You may
679 also check to see if arrays or subroutines exist.  Use of defined on
680 predefined variables is not guaranteed to produce intuitive results.
681
682 When used on a hash array element, it tells you whether the value
683 is defined, not whether the key exists in the hash.  Use exists() for that.
684
685 Examples:
686
687     print if defined $switch{'D'};
688     print "$val\n" while defined($val = pop(@ary));
689     die "Can't readlink $sym: $!"
690         unless defined($value = readlink $sym);
691     eval '@foo = ()' if defined(@foo);
692     die "No XYZ package defined" unless defined %_XYZ;
693     sub foo { defined &$bar ? &$bar(@_) : die "No bar"; }
694
695 See also undef().
696
697 Note: many folks tend to overuse defined(), and then are surprised to
698 discover that the number 0 and the null string are, in fact, defined
699 concepts.  For example, if you say
700
701     "ab" =~ /a(.*)b/;
702
703 the pattern match succeeds, and $1 is defined, despite the fact that it
704 matched "nothing".  But it didn't really match nothing--rather, it
705 matched something that happened to be 0 characters long.  This is all
706 very above-board and honest.  When a function returns an undefined value,
707 it's an admission that it couldn't give you an honest answer.  So
708 you should use defined() only when you're questioning the integrity
709 of what you're trying to do.  At other times, a simple comparison to
710 0 or "" is what you want.
711
712 Another surprise is that using defined() on an entire array or 
713 hash reports whether memory for that aggregate has ever been
714 allocated.  So an array you set to the empty list appears undefined
715 initially, and one that once was full and that you then set to 
716 the empty list still appears defined.  You should instead use a 
717 simple test for size:
718
719     if (@an_array) { print "has array elements\n" }
720     if (%a_hash)   { print "has hash members\n"   }
721
722 Using undef() on these, however, does clear their memory and then report
723 them as not defined anymore, but you shoudln't do that unless you don't
724 plan to use them again, because it saves time when you load them up
725 again to have memory already ready to be filled.
726
727 This counter-intuitive behaviour of defined() on aggregates may be
728 changed, fixed, or broken in a future release of Perl.
729
730 =item delete EXPR
731
732 Deletes the specified key(s) and their associated values from a hash
733 array.  For each key, returns the deleted value associated with that key,
734 or the undefined value if there was no such key.  Deleting from C<$ENV{}>
735 modifies the environment.  Deleting from an array tied to a DBM file
736 deletes the entry from the DBM file.  (But deleting from a tie()d hash
737 doesn't necessarily return anything.)
738
739 The following deletes all the values of an associative array:
740
741     foreach $key (keys %HASH) {
742         delete $HASH{$key};
743     }
744
745 And so does this:
746
747     delete @HASH{keys %HASH}
748
749 (But both of these are slower than the undef() command.)  Note that the
750 EXPR can be arbitrarily complicated as long as the final operation is a
751 hash element lookup or hash slice:
752
753     delete $ref->[$x][$y]{$key};
754     delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};
755
756 =item die LIST
757
758 Outside of an eval(), prints the value of LIST to C<STDERR> and exits with
759 the current value of C<$!> (errno).  If C<$!> is 0, exits with the value of
760 C<($? E<gt>E<gt> 8)> (back-tick `command` status).  If C<($? E<gt>E<gt> 8)>
761 is 0, exits with 255.  Inside an eval(), the error message is stuffed into
762 C<$@>, and the eval() is terminated with the undefined value; this makes
763 die() the way to raise an exception.
764
765 Equivalent examples:
766
767     die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
768     chdir '/usr/spool/news' or die "Can't cd to spool: $!\n" 
769
770 If the value of EXPR does not end in a newline, the current script line
771 number and input line number (if any) are also printed, and a newline
772 is supplied.  Hint: sometimes appending ", stopped" to your message
773 will cause it to make better sense when the string "at foo line 123" is
774 appended.  Suppose you are running script "canasta".
775
776     die "/etc/games is no good";
777     die "/etc/games is no good, stopped";
778
779 produce, respectively
780
781     /etc/games is no good at canasta line 123.
782     /etc/games is no good, stopped at canasta line 123.
783
784 See also exit() and warn().
785
786 You can arrange for a callback to be called just before the die() does
787 its deed, by setting the C<$SIG{__DIE__}> hook.  The associated handler
788 will be called with the error text and can change the error message, if
789 it sees fit, by calling die() again.  See L<perlvar> for details on
790 setting C<%SIG> entries, and eval() for some examples.
791
792 =item do BLOCK
793
794 Not really a function.  Returns the value of the last command in the
795 sequence of commands indicated by BLOCK.  When modified by a loop
796 modifier, executes the BLOCK once before testing the loop condition.
797 (On other statements the loop modifiers test the conditional first.)
798
799 =item do SUBROUTINE(LIST)
800
801 A deprecated form of subroutine call.  See L<perlsub>.
802
803 =item do EXPR
804
805 Uses the value of EXPR as a filename and executes the contents of the
806 file as a Perl script.  Its primary use is to include subroutines
807 from a Perl subroutine library.
808
809     do 'stat.pl';
810
811 is just like
812
813     eval `cat stat.pl`;
814
815 except that it's more efficient, more concise, keeps track of the
816 current filename for error messages, and searches all the B<-I>
817 libraries if the file isn't in the current directory (see also the @INC
818 array in L<perlvar/Predefined Names>).  It's the same, however, in that it does
819 re-parse the file every time you call it, so you probably don't want to
820 do this inside a loop.
821
822 Note that inclusion of library modules is better done with the
823 use() and require() operators, which also do error checking
824 and raise an exception if there's a problem.
825
826 =item dump LABEL
827
828 This causes an immediate core dump.  Primarily this is so that you can
829 use the B<undump> program to turn your core dump into an executable binary
830 after having initialized all your variables at the beginning of the
831 program.  When the new binary is executed it will begin by executing a
832 C<goto LABEL> (with all the restrictions that C<goto> suffers).  Think of
833 it as a goto with an intervening core dump and reincarnation.  If LABEL
834 is omitted, restarts the program from the top.  WARNING: any files
835 opened at the time of the dump will NOT be open any more when the
836 program is reincarnated, with possible resulting confusion on the part
837 of Perl.  See also B<-u> option in L<perlrun>.
838
839 Example:
840
841     #!/usr/bin/perl
842     require 'getopt.pl';
843     require 'stat.pl';
844     %days = (
845         'Sun' => 1,
846         'Mon' => 2,
847         'Tue' => 3,
848         'Wed' => 4,
849         'Thu' => 5,
850         'Fri' => 6,
851         'Sat' => 7,
852     );
853
854     dump QUICKSTART if $ARGV[0] eq '-d';
855
856     QUICKSTART:
857     Getopt('f');
858
859 =item each ASSOC_ARRAY
860
861 When called in a list context, returns a 2-element array consisting
862 of the key and value for the next element of an associative array,
863 so that you can iterate over it.  When called in a scalar context,
864 returns the key for only the next element in the associative array.
865 Entries are returned in an apparently random order.  When the array is
866 entirely read, a null array is returned in list context (which when
867 assigned produces a FALSE (0) value), and C<undef> is returned in a
868 scalar context.  The next call to each() after that will start
869 iterating again.  The iterator can be reset only by reading all the
870 elements from the array.  You should not add elements to an array while
871 you're iterating over it.  There is a single iterator for each
872 associative array, shared by all each(), keys(), and values() function
873 calls in the program.  The following prints out your environment like
874 the printenv(1) program, only in a different order:
875
876     while (($key,$value) = each %ENV) {
877         print "$key=$value\n";
878     }
879
880 See also keys() and values().
881
882 =item eof FILEHANDLE
883
884 =item eof ()
885
886 =item eof
887
888 Returns 1 if the next read on FILEHANDLE will return end of file, or if
889 FILEHANDLE is not open.  FILEHANDLE may be an expression whose value
890 gives the real filehandle name.  (Note that this function actually
891 reads a character and then ungetc()s it, so it is not very useful in an
892 interactive context.)  Do not read from a terminal file (or call
893 C<eof(FILEHANDLE)> on it) after end-of-file is reached.  Filetypes such
894 as terminals may lose the end-of-file condition if you do.
895
896 An C<eof> without an argument uses the last file read as argument.
897 Empty parentheses () may be used to indicate
898 the pseudo file formed of the files listed on the command line, i.e.,
899 C<eof()> is reasonable to use inside a while (E<lt>E<gt>) loop to detect the end
900 of only the last file.  Use C<eof(ARGV)> or eof without the parentheses to
901 test I<EACH> file in a while (E<lt>E<gt>) loop.  Examples:
902
903     # reset line numbering on each input file
904     while (<>) {
905         print "$.\t$_";
906         close(ARGV) if (eof);   # Not eof().
907     }
908
909     # insert dashes just before last line of last file
910     while (<>) {
911         if (eof()) {
912             print "--------------\n";
913             close(ARGV);        # close or break; is needed if we
914                                 # are reading from the terminal
915         }
916         print;
917     }
918
919 Practical hint: you almost never need to use C<eof> in Perl, because the
920 input operators return undef when they run out of data.  
921
922 =item eval EXPR
923
924 =item eval BLOCK
925
926 EXPR is parsed and executed as if it were a little Perl program.  It
927 is executed in the context of the current Perl program, so that any
928 variable settings or subroutine and format definitions remain afterwards.
929 The value returned is the value of the last expression evaluated, or a
930 return statement may be used, just as with subroutines.  The last
931 expression is evaluated in scalar or array context, depending on the
932 context of the eval.
933
934 If there is a syntax error or runtime error, or a die() statement is
935 executed, an undefined value is returned by eval(), and C<$@> is set to the
936 error message.  If there was no error, C<$@> is guaranteed to be a null
937 string.  If EXPR is omitted, evaluates C<$_>.  The final semicolon, if
938 any, may be omitted from the expression.  Beware that using eval()
939 neither silences perl from printing warnings to STDERR, nor does it
940 stuff the text of warning messages into C<$@>.  To do either of those,
941 you have to use the C<$SIG{__WARN__}> facility.  See warn() and L<perlvar>.
942
943 Note that, because eval() traps otherwise-fatal errors, it is useful for
944 determining whether a particular feature (such as socket() or symlink())
945 is implemented.  It is also Perl's exception trapping mechanism, where
946 the die operator is used to raise exceptions.
947
948 If the code to be executed doesn't vary, you may use the eval-BLOCK
949 form to trap run-time errors without incurring the penalty of
950 recompiling each time.  The error, if any, is still returned in C<$@>.
951 Examples:
952
953     # make divide-by-zero non-fatal
954     eval { $answer = $a / $b; }; warn $@ if $@;
955
956     # same thing, but less efficient
957     eval '$answer = $a / $b'; warn $@ if $@;
958
959     # a compile-time error
960     eval { $answer = };
961
962     # a run-time error
963     eval '$answer =';   # sets $@
964
965 When using the eval{} form as an exception trap in libraries, you may
966 wish not to trigger any C<__DIE__> hooks that user code may have
967 installed.  You can use the C<local $SIG{__DIE__}> construct for this
968 purpose, as shown in this example:
969
970     # a very private exception trap for divide-by-zero
971     eval { local $SIG{'__DIE__'}; $answer = $a / $b; }; warn $@ if $@;
972
973 This is especially significant, given that C<__DIE__> hooks can call
974 die() again, which has the effect of changing their error messages:
975
976     # __DIE__ hooks may modify error messages
977     {
978        local $SIG{'__DIE__'} = sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
979        eval { die "foo foofs here" };
980        print $@ if $@;                # prints "bar barfs here"
981     }
982
983 With an eval(), you should be especially careful to remember what's 
984 being looked at when:
985
986     eval $x;            # CASE 1
987     eval "$x";          # CASE 2
988
989     eval '$x';          # CASE 3
990     eval { $x };        # CASE 4
991
992     eval "\$$x++"       # CASE 5
993     $$x++;              # CASE 6
994
995 Cases 1 and 2 above behave identically: they run the code contained in the
996 variable $x.  (Although case 2 has misleading double quotes making the
997 reader wonder what else might be happening (nothing is).) Cases 3 and 4
998 likewise behave in the same way: they run the code E<lt>$xE<gt>, which does
999 nothing at all.  (Case 4 is preferred for purely visual reasons.) Case 5
1000 is a place where normally you I<WOULD> like to use double quotes, except
1001 that in that particular situation, you can just use symbolic references
1002 instead, as in case 6.
1003
1004 =item exec LIST
1005
1006 The exec() function executes a system command I<AND NEVER RETURNS>,
1007 unless the command does not exist and is executed directly instead of
1008 via C</bin/sh -c> (see below).  Use system() instead of exec() if you
1009 want it to return.
1010
1011 If there is more than one argument in LIST, or if LIST is an array with
1012 more than one value, calls execvp(3) with the arguments in LIST.  If
1013 there is only one scalar argument, the argument is checked for shell
1014 metacharacters.  If there are any, the entire argument is passed to
1015 C</bin/sh -c> for parsing.  If there are none, the argument is split
1016 into words and passed directly to execvp(), which is more efficient.
1017 Note: exec() and system() do not flush your output buffer, so you may
1018 need to set C<$|> to avoid lost output.  Examples:
1019
1020     exec '/bin/echo', 'Your arguments are: ', @ARGV;
1021     exec "sort $outfile | uniq";
1022
1023 If you don't really want to execute the first argument, but want to lie
1024 to the program you are executing about its own name, you can specify
1025 the program you actually want to run as an "indirect object" (without a
1026 comma) in front of the LIST.  (This always forces interpretation of the
1027 LIST as a multi-valued list, even if there is only a single scalar in
1028 the list.)  Example:
1029
1030     $shell = '/bin/csh';
1031     exec $shell '-sh';          # pretend it's a login shell
1032
1033 or, more directly,
1034
1035     exec {'/bin/csh'} '-sh';    # pretend it's a login shell
1036
1037 =item exists EXPR
1038
1039 Returns TRUE if the specified hash key exists in its hash array, even
1040 if the corresponding value is undefined.
1041
1042     print "Exists\n" if exists $array{$key};
1043     print "Defined\n" if defined $array{$key};
1044     print "True\n" if $array{$key};
1045
1046 A hash element can be TRUE only if it's defined, and defined if
1047 it exists, but the reverse doesn't necessarily hold true.
1048
1049 Note that the EXPR can be arbitrarily complicated as long as the final
1050 operation is a hash key lookup:
1051
1052     if (exists $ref->[$x][$y]{$key}) { ... }
1053
1054 =item exit EXPR
1055
1056 Evaluates EXPR and exits immediately with that value.  (Actually, it
1057 calls any defined C<END> routines first, but the C<END> routines may not
1058 abort the exit.  Likewise any object destructors that need to be called
1059 are called before exit.)  Example:
1060
1061     $ans = <STDIN>;
1062     exit 0 if $ans =~ /^[Xx]/;
1063
1064 See also die().  If EXPR is omitted, exits with 0 status.
1065
1066 You shouldn't use exit() to abort a subroutine if there's any chance that
1067 someone might want to trap whatever error happened.  Use die() instead,
1068 which can be trapped by an eval().
1069
1070 =item exp EXPR
1071
1072 =item exp 
1073
1074 Returns I<e> (the natural logarithm base) to the power of EXPR.  
1075 If EXPR is omitted, gives C<exp($_)>.
1076
1077 =item fcntl FILEHANDLE,FUNCTION,SCALAR
1078
1079 Implements the fcntl(2) function.  You'll probably have to say
1080
1081     use Fcntl;
1082
1083 first to get the correct function definitions.  Argument processing and
1084 value return works just like ioctl() below.  Note that fcntl() will produce
1085 a fatal error if used on a machine that doesn't implement fcntl(2).
1086 For example:
1087
1088     use Fcntl;
1089     fcntl($filehandle, F_GETLK, $packed_return_buffer);
1090
1091 =item fileno FILEHANDLE
1092
1093 Returns the file descriptor for a filehandle.  This is useful for
1094 constructing bitmaps for select().  If FILEHANDLE is an expression, the
1095 value is taken as the name of the filehandle.
1096
1097 =item flock FILEHANDLE,OPERATION
1098
1099 Calls flock(2), or an emulation of it, on FILEHANDLE.  Returns TRUE for
1100 success, FALSE on failure.  Will produce a fatal error if used on a
1101 machine that doesn't implement flock(2), fcntl(2) locking, or lockf(3).
1102 flock() is Perl's portable file locking interface, although it will lock
1103 only entire files, not records.
1104
1105 OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with
1106 LOCK_NB.  These constants are traditionally valued 1, 2, 8 and 4, but
1107 you can use the symbolic names if you pull them in with an explicit
1108 request to the Fcntl module.  The names can be requested as a group with
1109 the :flock tag (or they can be requested individually, of course).
1110 LOCK_SH requests a shared lock, LOCK_EX requests an exclusive lock, and
1111 LOCK_UN releases a previously requested lock.  If LOCK_NB is added to
1112 LOCK_SH or LOCK_EX then flock() will return immediately rather than
1113 blocking waiting for the lock (check the return status to see if you got
1114 it).
1115
1116 Note that the emulation built with lockf(3) doesn't provide shared
1117 locks, and it requires that FILEHANDLE be open with write intent.  These
1118 are the semantics that lockf(3) implements.  Most (all?) systems
1119 implement lockf(3) in terms of fcntl(2) locking, though, so the
1120 differing semantics shouldn't bite too many people.
1121
1122 Note also that some versions of flock() cannot lock things over the
1123 network; you would need to use the more system-specific fcntl() for
1124 that.  If you like you can force Perl to ignore your system's flock(2)
1125 function, and so provide its own fcntl(2)-based emulation, by passing
1126 the switch C<-Ud_flock> to the F<Configure> program when you configure
1127 perl.
1128
1129 Here's a mailbox appender for BSD systems.
1130
1131     use Fcntl ':flock'; # import LOCK_* constants
1132
1133     sub lock {
1134         flock(MBOX,LOCK_EX);
1135         # and, in case someone appended
1136         # while we were waiting...
1137         seek(MBOX, 0, 2);
1138     }
1139
1140     sub unlock {
1141         flock(MBOX,LOCK_UN);
1142     }
1143
1144     open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
1145             or die "Can't open mailbox: $!";
1146
1147     lock();
1148     print MBOX $msg,"\n\n";
1149     unlock();
1150
1151 See also L<DB_File> for other flock() examples.
1152
1153 =item fork
1154
1155 Does a fork(2) system call.  Returns the child pid to the parent process
1156 and 0 to the child process, or C<undef> if the fork is unsuccessful.
1157 Note: unflushed buffers remain unflushed in both processes, which means
1158 you may need to set C<$|> ($AUTOFLUSH in English) or call the autoflush()
1159 method of IO::Handle to avoid duplicate output.
1160
1161 If you fork() without ever waiting on your children, you will accumulate
1162 zombies:
1163
1164     $SIG{CHLD} = sub { wait };
1165
1166 There's also the double-fork trick (error checking on 
1167 fork() returns omitted);
1168
1169     unless ($pid = fork) {
1170         unless (fork) {
1171             exec "what you really wanna do";
1172             die "no exec";
1173             # ... or ...
1174             ## (some_perl_code_here)
1175             exit 0;
1176         }
1177         exit 0;
1178     }
1179     waitpid($pid,0);
1180
1181 See also L<perlipc> for more examples of forking and reaping
1182 moribund children.
1183
1184 Note that if your forked child inherits system file descriptors like
1185 STDIN and STDOUT that are actually connected by a pipe or socket, even
1186 if you exit, the remote server (such as, say, httpd or rsh) won't think
1187 you're done.  You should reopen those to /dev/null if it's any issue.
1188
1189 =item format
1190
1191 Declare a picture format with use by the write() function.  For
1192 example:
1193
1194     format Something = 
1195         Test: @<<<<<<<< @||||| @>>>>>
1196               $str,     $%,    '$' . int($num)
1197     .
1198
1199     $str = "widget";
1200     $num = $cost/$quantity;
1201     $~ = 'Something';
1202     write;
1203
1204 See L<perlform> for many details and examples.
1205
1206
1207 =item formline PICTURE, LIST
1208
1209 This is an internal function used by C<format>s, though you may call it
1210 too.  It formats (see L<perlform>) a list of values according to the
1211 contents of PICTURE, placing the output into the format output
1212 accumulator, C<$^A> (or $ACCUMULATOR in English).
1213 Eventually, when a write() is done, the contents of
1214 C<$^A> are written to some filehandle, but you could also read C<$^A>
1215 yourself and then set C<$^A> back to "".  Note that a format typically
1216 does one formline() per line of form, but the formline() function itself
1217 doesn't care how many newlines are embedded in the PICTURE.  This means
1218 that the C<~> and C<~~> tokens will treat the entire PICTURE as a single line.
1219 You may therefore need to use multiple formlines to implement a single
1220 record format, just like the format compiler.
1221
1222 Be careful if you put double quotes around the picture, because an "C<@>"
1223 character may be taken to mean the beginning of an array name.
1224 formline() always returns TRUE.  See L<perlform> for other examples.
1225
1226 =item getc FILEHANDLE
1227
1228 =item getc
1229
1230 Returns the next character from the input file attached to FILEHANDLE,
1231 or a null string at end of file.  If FILEHANDLE is omitted, reads from STDIN.
1232 This is not particularly efficient.  It cannot be used to get unbuffered
1233 single-characters, however.  For that, try something more like:
1234
1235     if ($BSD_STYLE) {
1236         system "stty cbreak </dev/tty >/dev/tty 2>&1";
1237     }
1238     else {
1239         system "stty", '-icanon', 'eol', "\001"; 
1240     }
1241
1242     $key = getc(STDIN);
1243
1244     if ($BSD_STYLE) {
1245         system "stty -cbreak </dev/tty >/dev/tty 2>&1";
1246     }
1247     else {
1248         system "stty", 'icanon', 'eol', '^@'; # ASCII null
1249     }
1250     print "\n";
1251
1252 Determination of whether to whether $BSD_STYLE should be set 
1253 is left as an exercise to the reader.  
1254
1255 The POSIX::getattr() function can do this more portably on systems
1256 alleging POSIX compliance.
1257 See also the C<Term::ReadKey> module from your nearest CPAN site;
1258 details on CPAN can be found on L<perlmod/CPAN>.  
1259
1260 =item getlogin
1261
1262 Returns the current login from F</etc/utmp>, if any.  If null, use
1263 getpwuid().  
1264
1265     $login = getlogin || (getpwuid($<))[0] || "Kilroy";
1266
1267 Do not consider getlogin() for authentication: it is not as
1268 secure as getpwuid().
1269
1270 =item getpeername SOCKET
1271
1272 Returns the packed sockaddr address of other end of the SOCKET connection.
1273
1274     use Socket;
1275     $hersockaddr    = getpeername(SOCK);
1276     ($port, $iaddr) = unpack_sockaddr_in($hersockaddr);
1277     $herhostname    = gethostbyaddr($iaddr, AF_INET);
1278     $herstraddr     = inet_ntoa($iaddr);
1279
1280 =item getpgrp PID
1281
1282 Returns the current process group for the specified PID.  Use
1283 a PID of 0 to get the current process group for the
1284 current process.  Will raise an exception if used on a machine that
1285 doesn't implement getpgrp(2).  If PID is omitted, returns process
1286 group of current process.  Note that the POSIX version of getpgrp()
1287 does not accept a PID argument, so only PID==0 is truly portable.
1288
1289 =item getppid
1290
1291 Returns the process id of the parent process.
1292
1293 =item getpriority WHICH,WHO
1294
1295 Returns the current priority for a process, a process group, or a user.
1296 (See L<getpriority(2)>.)  Will raise a fatal exception if used on a
1297 machine that doesn't implement getpriority(2).
1298
1299 =item getpwnam NAME
1300
1301 =item getgrnam NAME
1302
1303 =item gethostbyname NAME
1304
1305 =item getnetbyname NAME
1306
1307 =item getprotobyname NAME
1308
1309 =item getpwuid UID
1310
1311 =item getgrgid GID
1312
1313 =item getservbyname NAME,PROTO
1314
1315 =item gethostbyaddr ADDR,ADDRTYPE
1316
1317 =item getnetbyaddr ADDR,ADDRTYPE
1318
1319 =item getprotobynumber NUMBER
1320
1321 =item getservbyport PORT,PROTO
1322
1323 =item getpwent
1324
1325 =item getgrent
1326
1327 =item gethostent
1328
1329 =item getnetent
1330
1331 =item getprotoent
1332
1333 =item getservent
1334
1335 =item setpwent
1336
1337 =item setgrent
1338
1339 =item sethostent STAYOPEN
1340
1341 =item setnetent STAYOPEN
1342
1343 =item setprotoent STAYOPEN
1344
1345 =item setservent STAYOPEN
1346
1347 =item endpwent
1348
1349 =item endgrent
1350
1351 =item endhostent
1352
1353 =item endnetent
1354
1355 =item endprotoent
1356
1357 =item endservent
1358
1359 These routines perform the same functions as their counterparts in the
1360 system library.  Within a list context, the return values from the
1361 various get routines are as follows:
1362
1363     ($name,$passwd,$uid,$gid,
1364        $quota,$comment,$gcos,$dir,$shell) = getpw*
1365     ($name,$passwd,$gid,$members) = getgr*
1366     ($name,$aliases,$addrtype,$length,@addrs) = gethost*
1367     ($name,$aliases,$addrtype,$net) = getnet*
1368     ($name,$aliases,$proto) = getproto*
1369     ($name,$aliases,$port,$proto) = getserv*
1370
1371 (If the entry doesn't exist you get a null list.)
1372
1373 Within a scalar context, you get the name, unless the function was a
1374 lookup by name, in which case you get the other thing, whatever it is.
1375 (If the entry doesn't exist you get the undefined value.)  For example:
1376
1377     $uid = getpwnam
1378     $name = getpwuid
1379     $name = getpwent
1380     $gid = getgrnam
1381     $name = getgrgid
1382     $name = getgrent
1383     etc.
1384
1385 The $members value returned by I<getgr*()> is a space separated list of
1386 the login names of the members of the group.
1387
1388 For the I<gethost*()> functions, if the C<h_errno> variable is supported in
1389 C, it will be returned to you via C<$?> if the function call fails.  The
1390 @addrs value returned by a successful call is a list of the raw
1391 addresses returned by the corresponding system library call.  In the
1392 Internet domain, each address is four bytes long and you can unpack it
1393 by saying something like:
1394
1395     ($a,$b,$c,$d) = unpack('C4',$addr[0]);
1396
1397 =item getsockname SOCKET
1398
1399 Returns the packed sockaddr address of this end of the SOCKET connection.
1400
1401     use Socket;
1402     $mysockaddr = getsockname(SOCK);
1403     ($port, $myaddr) = unpack_sockaddr_in($mysockaddr);
1404
1405 =item getsockopt SOCKET,LEVEL,OPTNAME
1406
1407 Returns the socket option requested, or undefined if there is an error.
1408
1409 =item glob EXPR
1410
1411 =item glob
1412
1413 Returns the value of EXPR with filename expansions such as a shell
1414 would do.  This is the internal function implementing the E<lt>*.*E<gt>
1415 operator, except it's easier to use.
1416 If EXPR is omitted, $_ is used.
1417
1418 =item gmtime EXPR
1419
1420 Converts a time as returned by the time function to a 9-element array
1421 with the time localized for the standard Greenwich time zone.  
1422 Typically used as follows:
1423
1424
1425     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
1426                                             gmtime(time);
1427
1428 All array elements are numeric, and come straight out of a struct tm.
1429 In particular this means that $mon has the range 0..11 and $wday has
1430 the range 0..6.  If EXPR is omitted, does C<gmtime(time())>.
1431
1432 In a scalar context, prints out the ctime(3) value:
1433
1434     $now_string = gmtime;  # e.g., "Thu Oct 13 04:54:34 1994"
1435
1436 Also see the F<timegm.pl> library, and the strftime(3) function available
1437 via the POSIX module.
1438
1439 =item goto LABEL
1440
1441 =item goto EXPR
1442
1443 =item goto &NAME
1444
1445 The goto-LABEL form finds the statement labeled with LABEL and resumes
1446 execution there.  It may not be used to go into any construct that
1447 requires initialization, such as a subroutine or a foreach loop.  It
1448 also can't be used to go into a construct that is optimized away,
1449 or to get out of a block or subroutine given to sort().
1450 It can be used to go almost anywhere else within the dynamic scope,
1451 including out of subroutines, but it's usually better to use some other
1452 construct such as last or die.  The author of Perl has never felt the
1453 need to use this form of goto (in Perl, that is--C is another matter).
1454
1455 The goto-EXPR form expects a label name, whose scope will be resolved
1456 dynamically.  This allows for computed gotos per FORTRAN, but isn't
1457 necessarily recommended if you're optimizing for maintainability:
1458
1459     goto ("FOO", "BAR", "GLARCH")[$i];
1460
1461 The goto-&NAME form is highly magical, and substitutes a call to the
1462 named subroutine for the currently running subroutine.  This is used by
1463 AUTOLOAD subroutines that wish to load another subroutine and then
1464 pretend that the other subroutine had been called in the first place
1465 (except that any modifications to @_ in the current subroutine are
1466 propagated to the other subroutine.)  After the goto, not even caller()
1467 will be able to tell that this routine was called first.
1468
1469 =item grep BLOCK LIST
1470
1471 =item grep EXPR,LIST
1472
1473 Evaluates the BLOCK or EXPR for each element of LIST (locally setting
1474 $_ to each element) and returns the list value consisting of those
1475 elements for which the expression evaluated to TRUE.  In a scalar
1476 context, returns the number of times the expression was TRUE.
1477
1478     @foo = grep(!/^#/, @bar);    # weed out comments
1479
1480 or equivalently,
1481
1482     @foo = grep {!/^#/} @bar;    # weed out comments
1483
1484 Note that, because $_ is a reference into the list value, it can be used
1485 to modify the elements of the array.  While this is useful and
1486 supported, it can cause bizarre results if the LIST is not a named
1487 array.
1488
1489 =item hex EXPR
1490
1491 =item hex 
1492
1493 Interprets EXPR as a hex string and returns the corresponding decimal
1494 value.  (To convert strings that might start with 0 or 0x see
1495 oct().)  If EXPR is omitted, uses $_.
1496
1497 =item import
1498
1499 There is no built-in import() function.  It is merely an ordinary
1500 method (subroutine) defined (or inherited) by modules that wish to export
1501 names to another module.  The use() function calls the import() method
1502 for the package used.  See also L</use>, L<perlmod>, and L<Exporter>.
1503
1504 =item index STR,SUBSTR,POSITION
1505
1506 =item index STR,SUBSTR
1507
1508 Returns the position of the first occurrence of SUBSTR in STR at or after
1509 POSITION.  If POSITION is omitted, starts searching from the beginning of
1510 the string.  The return value is based at 0 (or whatever you've set the C<$[>
1511 variable to--but don't do that).  If the substring is not found, returns
1512 one less than the base, ordinarily -1.
1513
1514 =item int EXPR
1515
1516 =item int 
1517
1518 Returns the integer portion of EXPR.  If EXPR is omitted, uses $_.
1519
1520 =item ioctl FILEHANDLE,FUNCTION,SCALAR
1521
1522 Implements the ioctl(2) function.  You'll probably have to say
1523
1524     require "ioctl.ph"; # probably in /usr/local/lib/perl/ioctl.ph
1525
1526 first to get the correct function definitions.  If F<ioctl.ph> doesn't
1527 exist or doesn't have the correct definitions you'll have to roll your
1528 own, based on your C header files such as F<E<lt>sys/ioctl.hE<gt>>.
1529 (There is a Perl script called B<h2ph> that comes with the Perl kit which
1530 may help you in this, but it's non-trivial.)  SCALAR will be read and/or
1531 written depending on the FUNCTION--a pointer to the string value of SCALAR
1532 will be passed as the third argument of the actual ioctl call.  (If SCALAR
1533 has no string value but does have a numeric value, that value will be
1534 passed rather than a pointer to the string value.  To guarantee this to be
1535 TRUE, add a 0 to the scalar before using it.)  The pack() and unpack()
1536 functions are useful for manipulating the values of structures used by
1537 ioctl().  The following example sets the erase character to DEL.
1538
1539     require 'ioctl.ph';
1540     $getp = &TIOCGETP;
1541     die "NO TIOCGETP" if $@ || !$getp;
1542     $sgttyb_t = "ccccs";                # 4 chars and a short
1543     if (ioctl(STDIN,$getp,$sgttyb)) {
1544         @ary = unpack($sgttyb_t,$sgttyb);
1545         $ary[2] = 127;
1546         $sgttyb = pack($sgttyb_t,@ary);
1547         ioctl(STDIN,&TIOCSETP,$sgttyb)
1548             || die "Can't ioctl: $!";
1549     }
1550
1551 The return value of ioctl (and fcntl) is as follows:
1552
1553         if OS returns:          then Perl returns:
1554             -1                    undefined value
1555              0                  string "0 but true"
1556         anything else               that number
1557
1558 Thus Perl returns TRUE on success and FALSE on failure, yet you can
1559 still easily determine the actual value returned by the operating
1560 system:
1561
1562     ($retval = ioctl(...)) || ($retval = -1);
1563     printf "System returned %d\n", $retval;
1564
1565 =item join EXPR,LIST
1566
1567 Joins the separate strings of LIST or ARRAY into a single string with
1568 fields separated by the value of EXPR, and returns the string.
1569 Example:
1570
1571     $_ = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
1572
1573 See L<perlfunc/split>.
1574
1575 =item keys ASSOC_ARRAY
1576
1577 Returns a normal array consisting of all the keys of the named
1578 associative array.  (In a scalar context, returns the number of keys.)
1579 The keys are returned in an apparently random order, but it is the same
1580 order as either the values() or each() function produces (given that
1581 the associative array has not been modified).  Here is yet another way
1582 to print your environment:
1583
1584     @keys = keys %ENV;
1585     @values = values %ENV;
1586     while ($#keys >= 0) {
1587         print pop(@keys), '=', pop(@values), "\n";
1588     }
1589
1590 or how about sorted by key:
1591
1592     foreach $key (sort(keys %ENV)) {
1593         print $key, '=', $ENV{$key}, "\n";
1594     }
1595
1596 To sort an array by value, you'll need to use a C<sort{}>
1597 function.  Here's a descending numeric sort of a hash by its values:
1598
1599     foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash)) {
1600         printf "%4d %s\n", $hash{$key}, $key;
1601     }
1602
1603 As an lvalue C<keys> allows you to increase the number of hash buckets
1604 allocated for the given associative array.  This can gain you a measure
1605 of efficiency if you know the hash is going to get big.  (This is
1606 similar to pre-extending an array by assigning a larger number to
1607 $#array.)  If you say
1608
1609     keys %hash = 200;
1610
1611 then C<%hash> will have at least 200 buckets allocated for it.  These
1612 buckets will be retained even if you do C<%hash = ()>, use C<undef
1613 %hash> if you want to free the storage while C<%hash> is still in scope.
1614 You can't shrink the number of buckets allocated for the hash using
1615 C<keys> in this way (but you needn't worry about doing this by accident,
1616 as trying has no effect).
1617
1618 =item kill LIST
1619
1620 Sends a signal to a list of processes.  The first element of 
1621 the list must be the signal to send.  Returns the number of 
1622 processes successfully signaled.
1623
1624     $cnt = kill 1, $child1, $child2;
1625     kill 9, @goners;
1626
1627 Unlike in the shell, in Perl if the I<SIGNAL> is negative, it kills
1628 process groups instead of processes.  (On System V, a negative I<PROCESS>
1629 number will also kill process groups, but that's not portable.)  That
1630 means you usually want to use positive not negative signals.  You may also
1631 use a signal name in quotes.  See L<perlipc/"Signals"> for details.
1632
1633 =item last LABEL
1634
1635 =item last
1636
1637 The C<last> command is like the C<break> statement in C (as used in
1638 loops); it immediately exits the loop in question.  If the LABEL is
1639 omitted, the command refers to the innermost enclosing loop.  The
1640 C<continue> block, if any, is not executed:
1641
1642     LINE: while (<STDIN>) {
1643         last LINE if /^$/;      # exit when done with header
1644         ...
1645     }
1646
1647 =item lc EXPR
1648
1649 =item lc 
1650
1651 Returns an lowercased version of EXPR.  This is the internal function
1652 implementing the \L escape in double-quoted strings.  
1653 Respects current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>.
1654
1655 If EXPR is omitted, uses $_.
1656
1657 =item lcfirst EXPR
1658
1659 =item lcfirst 
1660
1661 Returns the value of EXPR with the first character lowercased.  This is
1662 the internal function implementing the \l escape in double-quoted strings.
1663 Respects current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>.
1664
1665 If EXPR is omitted, uses $_.
1666
1667 =item length EXPR
1668
1669 =item length 
1670
1671 Returns the length in characters of the value of EXPR.  If EXPR is
1672 omitted, returns length of $_.
1673
1674 =item link OLDFILE,NEWFILE
1675
1676 Creates a new filename linked to the old filename.  Returns 1 for
1677 success, 0 otherwise.
1678
1679 =item listen SOCKET,QUEUESIZE
1680
1681 Does the same thing that the listen system call does.  Returns TRUE if
1682 it succeeded, FALSE otherwise.  See example in L<perlipc/"Sockets: Client/Server Communication">.
1683
1684 =item local EXPR
1685
1686 A local modifies the listed variables to be local to the enclosing block,
1687 subroutine, C<eval{}>, or C<do>.  If more than one value is listed, the
1688 list must be placed in parentheses.  See L<perlsub/"Temporary Values via
1689 local()"> for details.
1690
1691 But you really probably want to be using my() instead, because local() isn't
1692 what most people think of as "local").  See L<perlsub/"Private Variables
1693 via my()"> for details.
1694
1695 =item localtime EXPR
1696
1697 Converts a time as returned by the time function to a 9-element array
1698 with the time analyzed for the local time zone.  Typically used as
1699 follows:
1700
1701     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
1702                                                 localtime(time);
1703
1704 All array elements are numeric, and come straight out of a struct tm.
1705 In particular this means that $mon has the range 0..11 and $wday has
1706 the range 0..6 and $year is year-1900, that is, $year is 123 in year
1707 2023.  If EXPR is omitted, uses the current time ("localtime(time)").
1708
1709 In a scalar context, returns the ctime(3) value:
1710
1711     $now_string = localtime;  # e.g., "Thu Oct 13 04:54:34 1994"
1712
1713 Also see the Time::Local module, and the strftime(3) function available
1714 via the POSIX module.
1715
1716 =item log EXPR
1717
1718 =item log 
1719
1720 Returns logarithm (base I<e>) of EXPR.  If EXPR is omitted, returns log
1721 of $_.
1722
1723 =item lstat FILEHANDLE
1724
1725 =item lstat EXPR
1726
1727 =item lstat 
1728
1729 Does the same thing as the stat() function, but stats a symbolic link
1730 instead of the file the symbolic link points to.  If symbolic links are
1731 unimplemented on your system, a normal stat() is done.
1732
1733 If EXPR is omitted, stats $_.
1734
1735 =item m//
1736
1737 The match operator.  See L<perlop>.
1738
1739 =item map BLOCK LIST
1740
1741 =item map EXPR,LIST
1742
1743 Evaluates the BLOCK or EXPR for each element of LIST (locally setting $_ to each
1744 element) and returns the list value composed of the results of each such
1745 evaluation.  Evaluates BLOCK or EXPR in a list context, so each element of LIST
1746 may produce zero, one, or more elements in the returned value.
1747
1748     @chars = map(chr, @nums);
1749
1750 translates a list of numbers to the corresponding characters.  And
1751
1752     %hash = map { getkey($_) => $_ } @array;
1753
1754 is just a funny way to write
1755
1756     %hash = ();
1757     foreach $_ (@array) {
1758         $hash{getkey($_)} = $_;
1759     }
1760
1761 =item mkdir FILENAME,MODE
1762
1763 Creates the directory specified by FILENAME, with permissions specified
1764 by MODE (as modified by umask).  If it succeeds it returns 1, otherwise
1765 it returns 0 and sets C<$!> (errno).
1766
1767 =item msgctl ID,CMD,ARG
1768
1769 Calls the System V IPC function msgctl(2).  If CMD is &IPC_STAT, then ARG
1770 must be a variable which will hold the returned msqid_ds structure.
1771 Returns like ioctl: the undefined value for error, "0 but true" for
1772 zero, or the actual return value otherwise.
1773
1774 =item msgget KEY,FLAGS
1775
1776 Calls the System V IPC function msgget(2).  Returns the message queue id,
1777 or the undefined value if there is an error.
1778
1779 =item msgsnd ID,MSG,FLAGS
1780
1781 Calls the System V IPC function msgsnd to send the message MSG to the
1782 message queue ID.  MSG must begin with the long integer message type,
1783 which may be created with C<pack("l", $type)>.  Returns TRUE if
1784 successful, or FALSE if there is an error.
1785
1786 =item msgrcv ID,VAR,SIZE,TYPE,FLAGS
1787
1788 Calls the System V IPC function msgrcv to receive a message from
1789 message queue ID into variable VAR with a maximum message size of
1790 SIZE.  Note that if a message is received, the message type will be the
1791 first thing in VAR, and the maximum length of VAR is SIZE plus the size
1792 of the message type.  Returns TRUE if successful, or FALSE if there is
1793 an error.
1794
1795 =item my EXPR
1796
1797 A "my" declares the listed variables to be local (lexically) to the
1798 enclosing block, subroutine, C<eval>, or C<do/require/use>'d file.  If
1799 more than one value is listed, the list must be placed in parentheses.  See
1800 L<perlsub/"Private Variables via my()"> for details.
1801
1802 =item next LABEL
1803
1804 =item next
1805
1806 The C<next> command is like the C<continue> statement in C; it starts
1807 the next iteration of the loop:
1808
1809     LINE: while (<STDIN>) {
1810         next LINE if /^#/;      # discard comments
1811         ...
1812     }
1813
1814 Note that if there were a C<continue> block on the above, it would get
1815 executed even on discarded lines.  If the LABEL is omitted, the command
1816 refers to the innermost enclosing loop.
1817
1818 =item no Module LIST
1819
1820 See the "use" function, which "no" is the opposite of.
1821
1822 =item oct EXPR
1823
1824 =item oct 
1825
1826 Interprets EXPR as an octal string and returns the corresponding
1827 decimal value.  (If EXPR happens to start off with 0x, interprets it as
1828 a hex string instead.)  The following will handle decimal, octal, and
1829 hex in the standard Perl or C notation:
1830
1831     $val = oct($val) if $val =~ /^0/;
1832
1833 If EXPR is omitted, uses $_.
1834
1835 =item open FILEHANDLE,EXPR
1836
1837 =item open FILEHANDLE
1838
1839 Opens the file whose filename is given by EXPR, and associates it with
1840 FILEHANDLE.  If FILEHANDLE is an expression, its value is used as the
1841 name of the real filehandle wanted.  If EXPR is omitted, the scalar
1842 variable of the same name as the FILEHANDLE contains the filename.
1843 (Note that lexical variables--those declared with C<my>--will not work
1844 for this purpose; so if you're using C<my>, specify EXPR in your call
1845 to open.)
1846
1847 If the filename begins with '<' or nothing, the file is opened for input.
1848 If the filename begins with '>', the file is truncated and opened for
1849 output.  If the filename begins with '>>', the file is opened for
1850 appending.  You can put a '+' in front of the '>' or '<' to indicate that
1851 you want both read and write access to the file; thus '+<' is almost
1852 always preferred for read/write updates--the '+>' mode would clobber the
1853 file first.  The prefix and the filename may be separated with spaces.
1854 These various prefixes correspond to the fopen(3) modes of 'r', 'r+', 'w',
1855 'w+', 'a', and 'a+'.
1856
1857 If the filename begins with "|", the filename is interpreted as a command
1858 to which output is to be piped, and if the filename ends with a "|", the
1859 filename is interpreted See L<perlipc/"Using open() for IPC"> for more
1860 examples of this.  as command which pipes input to us.  (You may not have
1861 a raw open() to a command that pipes both in I<and> out, but see
1862 L<IPC::Open2>, L<IPC::Open3>, and L<perlipc/"Bidirectional Communication">
1863 for alternatives.)
1864
1865 Opening '-' opens STDIN and opening 'E<gt>-' opens STDOUT.  Open returns
1866 non-zero upon success, the undefined value otherwise.  If the open
1867 involved a pipe, the return value happens to be the pid of the
1868 subprocess.  
1869
1870 If you're unfortunate enough to be running Perl on a system that
1871 distinguishes between text files and binary files (modern operating
1872 systems don't care), then you should check out L</binmode> for tips for
1873 dealing with this.  The key distinction between systems that need binmode
1874 and those that don't is their text file formats.  Systems like Unix and
1875 Plan9 that delimit lines with a single character, and that encode that
1876 character in C as '\n', do not need C<binmode>.  The rest need it.
1877
1878 Examples:
1879
1880     $ARTICLE = 100;
1881     open ARTICLE or die "Can't find article $ARTICLE: $!\n";
1882     while (<ARTICLE>) {...
1883
1884     open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
1885
1886     open(DBASE, '+<dbase.mine');            # open for update
1887
1888     open(ARTICLE, "caesar <$article |");    # decrypt article
1889
1890     open(EXTRACT, "|sort >/tmp/Tmp$$");     # $$ is our process id
1891
1892     # process argument list of files along with any includes
1893
1894     foreach $file (@ARGV) {
1895         process($file, 'fh00');
1896     }
1897
1898     sub process {
1899         local($filename, $input) = @_;
1900         $input++;               # this is a string increment
1901         unless (open($input, $filename)) {
1902             print STDERR "Can't open $filename: $!\n";
1903             return;
1904         }
1905
1906         while (<$input>) {              # note use of indirection
1907             if (/^#include "(.*)"/) {
1908                 process($1, $input);
1909                 next;
1910             }
1911             ...         # whatever
1912         }
1913     }
1914
1915 You may also, in the Bourne shell tradition, specify an EXPR beginning
1916 with "E<gt>&", in which case the rest of the string is interpreted as the
1917 name of a filehandle (or file descriptor, if numeric) which is to be
1918 duped and opened.  You may use & after E<gt>, E<gt>E<gt>, E<lt>, +E<gt>,
1919 +E<gt>E<gt>, and +E<lt>.  The
1920 mode you specify should match the mode of the original filehandle.
1921 (Duping a filehandle does not take into account any existing contents of
1922 stdio buffers.)
1923 Here is a script that saves, redirects, and restores STDOUT and
1924 STDERR:
1925
1926     #!/usr/bin/perl
1927     open(SAVEOUT, ">&STDOUT");
1928     open(SAVEERR, ">&STDERR");
1929
1930     open(STDOUT, ">foo.out") || die "Can't redirect stdout";
1931     open(STDERR, ">&STDOUT") || die "Can't dup stdout";
1932
1933     select(STDERR); $| = 1;     # make unbuffered
1934     select(STDOUT); $| = 1;     # make unbuffered
1935
1936     print STDOUT "stdout 1\n";  # this works for
1937     print STDERR "stderr 1\n";  # subprocesses too
1938
1939     close(STDOUT);
1940     close(STDERR);
1941
1942     open(STDOUT, ">&SAVEOUT");
1943     open(STDERR, ">&SAVEERR");
1944
1945     print STDOUT "stdout 2\n";
1946     print STDERR "stderr 2\n";
1947
1948
1949 If you specify "E<lt>&=N", where N is a number, then Perl will do an
1950 equivalent of C's fdopen() of that file descriptor; this is more
1951 parsimonious of file descriptors.  For example:
1952
1953     open(FILEHANDLE, "<&=$fd")
1954
1955 If you open a pipe on the command "-", i.e., either "|-" or "-|", then
1956 there is an implicit fork done, and the return value of open is the pid
1957 of the child within the parent process, and 0 within the child
1958 process.  (Use C<defined($pid)> to determine whether the open was successful.)
1959 The filehandle behaves normally for the parent, but i/o to that
1960 filehandle is piped from/to the STDOUT/STDIN of the child process.
1961 In the child process the filehandle isn't opened--i/o happens from/to
1962 the new STDOUT or STDIN.  Typically this is used like the normal
1963 piped open when you want to exercise more control over just how the
1964 pipe command gets executed, such as when you are running setuid, and
1965 don't want to have to scan shell commands for metacharacters.  
1966 The following pairs are more or less equivalent:
1967
1968     open(FOO, "|tr '[a-z]' '[A-Z]'");
1969     open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]';
1970
1971     open(FOO, "cat -n '$file'|");
1972     open(FOO, "-|") || exec 'cat', '-n', $file;
1973
1974 See L<perlipc/"Safe Pipe Opens"> for more examples of this.
1975
1976 Explicitly closing any piped filehandle causes the parent process to
1977 wait for the child to finish, and returns the status value in C<$?>.
1978 Note: on any operation which may do a fork, unflushed buffers remain
1979 unflushed in both processes, which means you may need to set C<$|> to
1980 avoid duplicate output.
1981
1982 Using the constructor from the IO::Handle package (or one of its
1983 subclasses, such as IO::File or IO::Socket),
1984 you can generate anonymous filehandles which have the scope of whatever
1985 variables hold references to them, and automatically close whenever
1986 and however you leave that scope:
1987
1988     use IO::File;
1989     ...
1990     sub read_myfile_munged {
1991         my $ALL = shift;
1992         my $handle = new IO::File;
1993         open($handle, "myfile") or die "myfile: $!";
1994         $first = <$handle>
1995             or return ();     # Automatically closed here.
1996         mung $first or die "mung failed";       # Or here.
1997         return $first, <$handle> if $ALL;       # Or here.
1998         $first;                                 # Or here.
1999     }
2000
2001 The filename that is passed to open will have leading and trailing
2002 whitespace deleted.  To open a file with arbitrary weird
2003 characters in it, it's necessary to protect any leading and trailing
2004 whitespace thusly:
2005
2006     $file =~ s#^(\s)#./$1#;
2007     open(FOO, "< $file\0");
2008
2009 If you want a "real" C open() (see L<open(2)> on your system), then
2010 you should use the sysopen() function.  This is another way to
2011 protect your filenames from interpretation.  For example:
2012
2013     use IO::Handle;
2014     sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL, 0700)
2015         or die "sysopen $path: $!";
2016     HANDLE->autoflush(1);
2017     HANDLE->print("stuff $$\n");
2018     seek(HANDLE, 0, 0);
2019     print "File contains: ", <HANDLE>;
2020
2021 See L</seek()> for some details about mixing reading and writing.
2022
2023 =item opendir DIRHANDLE,EXPR
2024
2025 Opens a directory named EXPR for processing by readdir(), telldir(),
2026 seekdir(), rewinddir(), and closedir().  Returns TRUE if successful.
2027 DIRHANDLEs have their own namespace separate from FILEHANDLEs.
2028
2029 =item ord EXPR
2030
2031 =item ord 
2032
2033 Returns the numeric ascii value of the first character of EXPR.  If
2034 EXPR is omitted, uses $_.
2035
2036 =item pack TEMPLATE,LIST
2037
2038 Takes an array or list of values and packs it into a binary structure,
2039 returning the string containing the structure.  The TEMPLATE is a
2040 sequence of characters that give the order and type of values, as
2041 follows:
2042
2043     A   An ascii string, will be space padded.
2044     a   An ascii string, will be null padded.
2045     b   A bit string (ascending bit order, like vec()).
2046     B   A bit string (descending bit order).
2047     h   A hex string (low nybble first).
2048     H   A hex string (high nybble first).
2049
2050     c   A signed char value.
2051     C   An unsigned char value.
2052     s   A signed short value.
2053     S   An unsigned short value.
2054     i   A signed integer value.
2055     I   An unsigned integer value.
2056     l   A signed long value.
2057     L   An unsigned long value.
2058
2059     n   A short in "network" order.
2060     N   A long in "network" order.
2061     v   A short in "VAX" (little-endian) order.
2062     V   A long in "VAX" (little-endian) order.
2063
2064     f   A single-precision float in the native format.
2065     d   A double-precision float in the native format.
2066
2067     p   A pointer to a null-terminated string.
2068     P   A pointer to a structure (fixed-length string).
2069
2070     u   A uuencoded string.
2071
2072     w A BER compressed integer. Bytes give an unsigned integer base
2073       128, most significant digit first, with as few digits as
2074       possible, and with the bit 8 of each byte except the last set
2075       to "1."
2076
2077     x   A null byte.
2078     X   Back up a byte.
2079     @   Null fill to absolute position.
2080
2081 Each letter may optionally be followed by a number which gives a repeat
2082 count.  With all types except "a", "A", "b", "B", "h", "H", and "P" the
2083 pack function will gobble up that many values from the LIST.  A * for the
2084 repeat count means to use however many items are left.  The "a" and "A"
2085 types gobble just one value, but pack it as a string of length count,
2086 padding with nulls or spaces as necessary.  (When unpacking, "A" strips
2087 trailing spaces and nulls, but "a" does not.)  Likewise, the "b" and "B"
2088 fields pack a string that many bits long.  The "h" and "H" fields pack a
2089 string that many nybbles long.  The "P" packs a pointer to a structure of
2090 the size indicated by the length.  Real numbers (floats and doubles) are
2091 in the native machine format only; due to the multiplicity of floating
2092 formats around, and the lack of a standard "network" representation, no
2093 facility for interchange has been made.  This means that packed floating
2094 point data written on one machine may not be readable on another - even if
2095 both use IEEE floating point arithmetic (as the endian-ness of the memory
2096 representation is not part of the IEEE spec).  Note that Perl uses doubles
2097 internally for all numeric calculation, and converting from double into
2098 float and thence back to double again will lose precision (i.e.,
2099 C<unpack("f", pack("f", $foo)>) will not in general equal $foo).
2100
2101 Examples:
2102
2103     $foo = pack("cccc",65,66,67,68);
2104     # foo eq "ABCD"
2105     $foo = pack("c4",65,66,67,68);
2106     # same thing
2107
2108     $foo = pack("ccxxcc",65,66,67,68);
2109     # foo eq "AB\0\0CD"
2110
2111     $foo = pack("s2",1,2);
2112     # "\1\0\2\0" on little-endian
2113     # "\0\1\0\2" on big-endian
2114
2115     $foo = pack("a4","abcd","x","y","z");
2116     # "abcd"
2117
2118     $foo = pack("aaaa","abcd","x","y","z");
2119     # "axyz"
2120
2121     $foo = pack("a14","abcdefg");
2122     # "abcdefg\0\0\0\0\0\0\0"
2123
2124     $foo = pack("i9pl", gmtime);
2125     # a real struct tm (on my system anyway)
2126
2127     sub bintodec {
2128         unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
2129     }
2130
2131 The same template may generally also be used in the unpack function.
2132
2133 =item package NAMESPACE
2134
2135 Declares the compilation unit as being in the given namespace.  The scope
2136 of the package declaration is from the declaration itself through the end of
2137 the enclosing block (the same scope as the local() operator).  All further
2138 unqualified dynamic identifiers will be in this namespace.  A package
2139 statement affects only dynamic variables--including those you've used
2140 local() on--but I<not> lexical variables created with my().  Typically it
2141 would be the first declaration in a file to be included by the C<require>
2142 or C<use> operator.  You can switch into a package in more than one place;
2143 it influences merely which symbol table is used by the compiler for the
2144 rest of that block.  You can refer to variables and filehandles in other
2145 packages by prefixing the identifier with the package name and a double
2146 colon:  C<$Package::Variable>.  If the package name is null, the C<main>
2147 package as assumed.  That is, C<$::sail> is equivalent to C<$main::sail>.
2148
2149 See L<perlmod/"Packages"> for more information about packages, modules,
2150 and classes.  See L<perlsub> for other scoping issues.
2151
2152 =item pipe READHANDLE,WRITEHANDLE
2153
2154 Opens a pair of connected pipes like the corresponding system call.
2155 Note that if you set up a loop of piped processes, deadlock can occur
2156 unless you are very careful.  In addition, note that Perl's pipes use
2157 stdio buffering, so you may need to set C<$|> to flush your WRITEHANDLE
2158 after each command, depending on the application.
2159
2160 See L<IPC::Open2>, L<IPC::Open3>, and L<perlipc/"Bidirectional Communication">
2161 for examples of such things.
2162
2163 =item pop ARRAY
2164
2165 =item pop 
2166
2167 Pops and returns the last value of the array, shortening the array by
2168 1.  Has a similar effect to
2169
2170     $tmp = $ARRAY[$#ARRAY--];
2171
2172 If there are no elements in the array, returns the undefined value.
2173 If ARRAY is omitted, pops the
2174 @ARGV array in the main program, and the @_ array in subroutines, just
2175 like shift().
2176
2177 =item pos SCALAR
2178
2179 =item pos 
2180
2181 Returns the offset of where the last C<m//g> search left off for the variable
2182 is in question ($_ is used when the variable is not specified). May be
2183 modified to change that offset.  Such modification will also influence
2184 the C<\G> zero-width assertion in regular expressions.  See L<perlre> and
2185 L<perlop>.
2186
2187 =item print FILEHANDLE LIST
2188
2189 =item print LIST
2190
2191 =item print
2192
2193 Prints a string or a comma-separated list of strings.  Returns TRUE
2194 if successful.  FILEHANDLE may be a scalar variable name, in which case
2195 the variable contains the name of or a reference to the filehandle, thus introducing one
2196 level of indirection.  (NOTE: If FILEHANDLE is a variable and the next
2197 token is a term, it may be misinterpreted as an operator unless you
2198 interpose a + or put parentheses around the arguments.)  If FILEHANDLE is
2199 omitted, prints by default to standard output (or to the last selected
2200 output channel--see L</select>).  If LIST is also omitted, prints $_ to
2201 STDOUT.  To set the default output channel to something other than
2202 STDOUT use the select operation.  Note that, because print takes a
2203 LIST, anything in the LIST is evaluated in a list context, and any
2204 subroutine that you call will have one or more of its expressions
2205 evaluated in a list context.  Also be careful not to follow the print
2206 keyword with a left parenthesis unless you want the corresponding right
2207 parenthesis to terminate the arguments to the print--interpose a + or
2208 put parentheses around all the arguments.
2209
2210 Note that if you're storing FILEHANDLES in an array or other expression,
2211 you will have to use a block returning its value instead:
2212
2213     print { $files[$i] } "stuff\n";
2214     print { $OK ? STDOUT : STDERR } "stuff\n";
2215
2216 =item printf FILEHANDLE FORMAT, LIST
2217
2218 =item printf FORMAT, LIST
2219
2220 Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>.  The first argument
2221 of the list will be interpreted as the printf format.  If C<use locale> is
2222 in effect, the character used for the decimal point in formatted real numbers
2223 is affected by the LC_NUMERIC locale.  See L<perllocale>.
2224
2225 Don't fall into the trap of using a printf() when a simple
2226 print() would do.  The print() is more efficient, and less
2227 error prone.
2228
2229 =item prototype FUNCTION
2230
2231 Returns the prototype of a function as a string (or C<undef> if the
2232 function has no prototype).  FUNCTION is a reference to, or the name of,
2233 the function whose prototype you want to retrieve.
2234
2235 =item push ARRAY,LIST
2236
2237 Treats ARRAY as a stack, and pushes the values of LIST
2238 onto the end of ARRAY.  The length of ARRAY increases by the length of
2239 LIST.  Has the same effect as
2240
2241     for $value (LIST) {
2242         $ARRAY[++$#ARRAY] = $value;
2243     }
2244
2245 but is more efficient.  Returns the new number of elements in the array.
2246
2247 =item q/STRING/
2248
2249 =item qq/STRING/
2250
2251 =item qx/STRING/
2252
2253 =item qw/STRING/
2254
2255 Generalized quotes.  See L<perlop>.
2256
2257 =item quotemeta EXPR
2258
2259 =item quotemeta 
2260
2261 Returns the value of EXPR with with all non-alphanumeric
2262 characters backslashed.  (That is, all characters not matching
2263 C</[A-Za-z_0-9]/> will be preceded by a backslash in the
2264 returned string, regardless of any locale settings.)
2265 This is the internal function implementing
2266 the \Q escape in double-quoted strings.
2267
2268 If EXPR is omitted, uses $_.
2269
2270 =item rand EXPR
2271
2272 =item rand
2273
2274 Returns a random fractional number between 0 and the value of EXPR.
2275 (EXPR should be positive.)  If EXPR is omitted, returns a value between 
2276 0 and 1.  This function produces repeatable sequences unless srand() 
2277 is invoked.  See also srand().
2278
2279 (Note: if your rand function consistently returns numbers that are too
2280 large or too small, then your version of Perl was probably compiled
2281 with the wrong number of RANDBITS.  As a workaround, you can usually
2282 multiply EXPR by the correct power of 2 to get the range you want.
2283 This will make your script unportable, however.  It's better to recompile
2284 if you can.)
2285
2286 =item read FILEHANDLE,SCALAR,LENGTH,OFFSET
2287
2288 =item read FILEHANDLE,SCALAR,LENGTH
2289
2290 Attempts to read LENGTH bytes of data into variable SCALAR from the
2291 specified FILEHANDLE.  Returns the number of bytes actually read, or
2292 undef if there was an error.  SCALAR will be grown or shrunk to the
2293 length actually read.  An OFFSET may be specified to place the read
2294 data at some other place than the beginning of the string.  This call
2295 is actually implemented in terms of stdio's fread call.  To get a true
2296 read system call, see sysread().
2297
2298 =item readdir DIRHANDLE
2299
2300 Returns the next directory entry for a directory opened by opendir().
2301 If used in a list context, returns all the rest of the entries in the
2302 directory.  If there are no more entries, returns an undefined value in
2303 a scalar context or a null list in a list context.
2304
2305 If you're planning to filetest the return values out of a readdir(), you'd
2306 better prepend the directory in question.  Otherwise, because we didn't
2307 chdir() there, it would have been testing the wrong file.
2308
2309     opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!";
2310     @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
2311     closedir DIR;
2312
2313 =item readlink EXPR
2314
2315 =item readlink 
2316
2317 Returns the value of a symbolic link, if symbolic links are
2318 implemented.  If not, gives a fatal error.  If there is some system
2319 error, returns the undefined value and sets C<$!> (errno).  If EXPR is
2320 omitted, uses $_.
2321
2322 =item recv SOCKET,SCALAR,LEN,FLAGS
2323
2324 Receives a message on a socket.  Attempts to receive LENGTH bytes of
2325 data into variable SCALAR from the specified SOCKET filehandle.
2326 Actually does a C recvfrom(), so that it can returns the address of the
2327 sender.  Returns the undefined value if there's an error.  SCALAR will
2328 be grown or shrunk to the length actually read.  Takes the same flags
2329 as the system call of the same name.  
2330 See L<perlipc/"UDP: Message Passing"> for examples.
2331
2332 =item redo LABEL
2333
2334 =item redo
2335
2336 The C<redo> command restarts the loop block without evaluating the
2337 conditional again.  The C<continue> block, if any, is not executed.  If
2338 the LABEL is omitted, the command refers to the innermost enclosing
2339 loop.  This command is normally used by programs that want to lie to
2340 themselves about what was just input:
2341
2342     # a simpleminded Pascal comment stripper
2343     # (warning: assumes no { or } in strings)
2344     LINE: while (<STDIN>) {
2345         while (s|({.*}.*){.*}|$1 |) {}
2346         s|{.*}| |;
2347         if (s|{.*| |) {
2348             $front = $_;
2349             while (<STDIN>) {
2350                 if (/}/) {      # end of comment?
2351                     s|^|$front{|;
2352                     redo LINE;
2353                 }
2354             }
2355         }
2356         print;
2357     }
2358
2359 =item ref EXPR
2360
2361 =item ref 
2362
2363 Returns a TRUE value if EXPR is a reference, FALSE otherwise. If EXPR
2364 is not specified, $_ will be used. The value returned depends on the
2365 type of thing the reference is a reference to.
2366 Builtin types include:
2367
2368     REF
2369     SCALAR
2370     ARRAY
2371     HASH
2372     CODE
2373     GLOB
2374
2375 If the referenced object has been blessed into a package, then that package 
2376 name is returned instead.  You can think of ref() as a typeof() operator.
2377
2378     if (ref($r) eq "HASH") {
2379         print "r is a reference to an associative array.\n";
2380     } 
2381     if (!ref ($r) {
2382         print "r is not a reference at all.\n";
2383     } 
2384
2385 See also L<perlref>.
2386
2387 =item rename OLDNAME,NEWNAME
2388
2389 Changes the name of a file.  Returns 1 for success, 0 otherwise.  Will
2390 not work across file system boundaries.
2391
2392 =item require EXPR
2393
2394 =item require
2395
2396 Demands some semantics specified by EXPR, or by $_ if EXPR is not
2397 supplied.  If EXPR is numeric, demands that the current version of Perl
2398 (C<$]> or $PERL_VERSION) be equal or greater than EXPR.
2399
2400 Otherwise, demands that a library file be included if it hasn't already
2401 been included.  The file is included via the do-FILE mechanism, which is
2402 essentially just a variety of eval().  Has semantics similar to the following
2403 subroutine:
2404
2405     sub require {
2406         local($filename) = @_;
2407         return 1 if $INC{$filename};
2408         local($realfilename,$result);
2409         ITER: {
2410             foreach $prefix (@INC) {
2411                 $realfilename = "$prefix/$filename";
2412                 if (-f $realfilename) {
2413                     $result = do $realfilename;
2414                     last ITER;
2415                 }
2416             }
2417             die "Can't find $filename in \@INC";
2418         }
2419         die $@ if $@;
2420         die "$filename did not return true value" unless $result;
2421         $INC{$filename} = $realfilename;
2422         $result;
2423     }
2424
2425 Note that the file will not be included twice under the same specified
2426 name.  The file must return TRUE as the last statement to indicate
2427 successful execution of any initialization code, so it's customary to
2428 end such a file with "1;" unless you're sure it'll return TRUE
2429 otherwise.  But it's better just to put the "C<1;>", in case you add more
2430 statements.
2431
2432 If EXPR is a bare word, the require assumes a "F<.pm>" extension and
2433 replaces "F<::>" with "F</>" in the filename for you,
2434 to make it easy to load standard modules.  This form of loading of 
2435 modules does not risk altering your namespace.
2436
2437 For a yet-more-powerful import facility, see L</use> and 
2438 L<perlmod>.
2439
2440 =item reset EXPR
2441
2442 =item reset
2443
2444 Generally used in a C<continue> block at the end of a loop to clear
2445 variables and reset ?? searches so that they work again.  The
2446 expression is interpreted as a list of single characters (hyphens
2447 allowed for ranges).  All variables and arrays beginning with one of
2448 those letters are reset to their pristine state.  If the expression is
2449 omitted, one-match searches (?pattern?) are reset to match again.  Resets
2450 only variables or searches in the current package.  Always returns
2451 1.  Examples:
2452
2453     reset 'X';          # reset all X variables
2454     reset 'a-z';        # reset lower case variables
2455     reset;              # just reset ?? searches
2456
2457 Resetting "A-Z" is not recommended because you'll wipe out your
2458 ARGV and ENV arrays.  Resets only package variables--lexical variables
2459 are unaffected, but they clean themselves up on scope exit anyway,
2460 so you'll probably want to use them instead.  See L</my>.
2461
2462 =item return LIST
2463
2464 Returns from a subroutine or eval with the value specified.  (Note that
2465 in the absence of a return a subroutine or eval() will automatically
2466 return the value of the last expression evaluated.)
2467
2468 =item reverse LIST
2469
2470 In a list context, returns a list value consisting of the elements
2471 of LIST in the opposite order.  In a scalar context, returns a string
2472 value consisting of the bytes of the first element of LIST in the
2473 opposite order.   
2474
2475     print reverse <>;                   # line tac 
2476
2477     undef $/;
2478     print scalar reverse scalar <>;     # byte tac
2479
2480 =item rewinddir DIRHANDLE
2481
2482 Sets the current position to the beginning of the directory for the
2483 readdir() routine on DIRHANDLE.
2484
2485 =item rindex STR,SUBSTR,POSITION
2486
2487 =item rindex STR,SUBSTR
2488
2489 Works just like index except that it returns the position of the LAST
2490 occurrence of SUBSTR in STR.  If POSITION is specified, returns the
2491 last occurrence at or before that position.
2492
2493 =item rmdir FILENAME
2494
2495 =item rmdir 
2496
2497 Deletes the directory specified by FILENAME if it is empty.  If it
2498 succeeds it returns 1, otherwise it returns 0 and sets C<$!> (errno).  If
2499 FILENAME is omitted, uses $_.
2500
2501 =item s///
2502
2503 The substitution operator.  See L<perlop>.
2504
2505 =item scalar EXPR
2506
2507 Forces EXPR to be interpreted in a scalar context and returns the value
2508 of EXPR.  
2509
2510     @counts = ( scalar @a, scalar @b, scalar @c );
2511
2512 There is no equivalent operator to force an expression to 
2513 be interpolated in a list context because it's in practice never
2514 needed.  If you really wanted to do so, however, you could use
2515 the construction C<@{[ (some expression) ]}>, but usually a simple
2516 C<(some expression)> suffices.
2517
2518 =item seek FILEHANDLE,POSITION,WHENCE
2519
2520 Randomly positions the file pointer for FILEHANDLE, just like the fseek()
2521 call of stdio.  FILEHANDLE may be an expression whose value gives the name
2522 of the filehandle.  The values for WHENCE are 0 to set the file pointer to
2523 POSITION, 1 to set the it to current plus POSITION, and 2 to set it to EOF
2524 plus offset.  You may use the values SEEK_SET, SEEK_CUR, and SEEK_END for
2525 this from POSIX module.  Returns 1 upon success, 0 otherwise.
2526
2527 On some systems you have to do a seek whenever you switch between reading
2528 and writing.  Amongst other things, this may have the effect of calling
2529 stdio's clearerr(3).  A "whence" of 1 (SEEK_CUR) is useful for not moving
2530 the file pointer:
2531
2532     seek(TEST,0,1);
2533
2534 This is also useful for applications emulating C<tail -f>.  Once you hit
2535 EOF on your read, and then sleep for a while, you might have to stick in a
2536 seek() to reset things.  First the simple trick listed above to clear the
2537 filepointer.  The seek() doesn't change the current position, but it
2538 I<does> clear the end-of-file condition on the handle, so that the next
2539 C<E<lt>FILEE<gt>> makes Perl try again to read something.  We hope.
2540
2541 If that doesn't work (some stdios are particularly cantankerous), then
2542 you may need something more like this:
2543
2544     for (;;) {
2545         for ($curpos = tell(FILE); $_ = <FILE>; $curpos = tell(FILE)) {
2546             # search for some stuff and put it into files
2547         }
2548         sleep($for_a_while);
2549         seek(FILE, $curpos, 0);
2550     }
2551
2552 =item seekdir DIRHANDLE,POS
2553
2554 Sets the current position for the readdir() routine on DIRHANDLE.  POS
2555 must be a value returned by telldir().  Has the same caveats about
2556 possible directory compaction as the corresponding system library
2557 routine.
2558
2559 =item select FILEHANDLE
2560
2561 =item select
2562
2563 Returns the currently selected filehandle.  Sets the current default
2564 filehandle for output, if FILEHANDLE is supplied.  This has two
2565 effects: first, a C<write> or a C<print> without a filehandle will
2566 default to this FILEHANDLE.  Second, references to variables related to
2567 output will refer to this output channel.  For example, if you have to
2568 set the top of form format for more than one output channel, you might
2569 do the following:
2570
2571     select(REPORT1);
2572     $^ = 'report1_top';
2573     select(REPORT2);
2574     $^ = 'report2_top';
2575
2576 FILEHANDLE may be an expression whose value gives the name of the
2577 actual filehandle.  Thus:
2578
2579     $oldfh = select(STDERR); $| = 1; select($oldfh);
2580
2581 Some programmers may prefer to think of filehandles as objects with
2582 methods, preferring to write the last example as:
2583
2584     use IO::Handle;
2585     STDERR->autoflush(1);
2586
2587 =item select RBITS,WBITS,EBITS,TIMEOUT
2588
2589 This calls the select(2) system call with the bit masks specified, which
2590 can be constructed using fileno() and vec(), along these lines:
2591
2592     $rin = $win = $ein = '';
2593     vec($rin,fileno(STDIN),1) = 1;
2594     vec($win,fileno(STDOUT),1) = 1;
2595     $ein = $rin | $win;
2596
2597 If you want to select on many filehandles you might wish to write a
2598 subroutine:
2599
2600     sub fhbits {
2601         local(@fhlist) = split(' ',$_[0]);
2602         local($bits);
2603         for (@fhlist) {
2604             vec($bits,fileno($_),1) = 1;
2605         }
2606         $bits;
2607     }
2608     $rin = fhbits('STDIN TTY SOCK');
2609
2610 The usual idiom is:
2611
2612     ($nfound,$timeleft) =
2613       select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
2614
2615 or to block until something becomes ready just do this 
2616
2617     $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
2618
2619 Most systems do not bother to return anything useful in $timeleft, so
2620 calling select() in a scalar context just returns $nfound.
2621
2622 Any of the bit masks can also be undef.  The timeout, if specified, is
2623 in seconds, which may be fractional.  Note: not all implementations are
2624 capable of returning the $timeleft.  If not, they always return
2625 $timeleft equal to the supplied $timeout.
2626
2627 You can effect a sleep of 250 milliseconds this way:
2628
2629     select(undef, undef, undef, 0.25);
2630
2631 B<WARNING>: Do not attempt to mix buffered I/O (like read() or E<lt>FHE<gt>)
2632 with select().  You have to use sysread() instead.
2633
2634 =item semctl ID,SEMNUM,CMD,ARG
2635
2636 Calls the System V IPC function semctl.  If CMD is &IPC_STAT or
2637 &GETALL, then ARG must be a variable which will hold the returned
2638 semid_ds structure or semaphore value array.  Returns like ioctl: the
2639 undefined value for error, "0 but true" for zero, or the actual return
2640 value otherwise.
2641
2642 =item semget KEY,NSEMS,FLAGS
2643
2644 Calls the System V IPC function semget.  Returns the semaphore id, or
2645 the undefined value if there is an error.
2646
2647 =item semop KEY,OPSTRING
2648
2649 Calls the System V IPC function semop to perform semaphore operations
2650 such as signaling and waiting.  OPSTRING must be a packed array of
2651 semop structures.  Each semop structure can be generated with
2652 C<pack("sss", $semnum, $semop, $semflag)>.  The number of semaphore
2653 operations is implied by the length of OPSTRING.  Returns TRUE if
2654 successful, or FALSE if there is an error.  As an example, the
2655 following code waits on semaphore $semnum of semaphore id $semid:
2656
2657     $semop = pack("sss", $semnum, -1, 0);
2658     die "Semaphore trouble: $!\n" unless semop($semid, $semop);
2659
2660 To signal the semaphore, replace "-1" with "1".
2661
2662 =item send SOCKET,MSG,FLAGS,TO
2663
2664 =item send SOCKET,MSG,FLAGS
2665
2666 Sends a message on a socket.  Takes the same flags as the system call
2667 of the same name.  On unconnected sockets you must specify a
2668 destination to send TO, in which case it does a C sendto().  Returns
2669 the number of characters sent, or the undefined value if there is an
2670 error.
2671 See L<perlipc/"UDP: Message Passing"> for examples.
2672
2673 =item setpgrp PID,PGRP
2674
2675 Sets the current process group for the specified PID, 0 for the current
2676 process.  Will produce a fatal error if used on a machine that doesn't
2677 implement setpgrp(2).  If the arguments are omitted, it defaults to
2678 0,0.  Note that the POSIX version of setpgrp() does not accept any
2679 arguments, so only setpgrp 0,0 is portable.
2680
2681 =item setpriority WHICH,WHO,PRIORITY
2682
2683 Sets the current priority for a process, a process group, or a user.
2684 (See setpriority(2).)  Will produce a fatal error if used on a machine
2685 that doesn't implement setpriority(2).
2686
2687 =item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
2688
2689 Sets the socket option requested.  Returns undefined if there is an
2690 error.  OPTVAL may be specified as undef if you don't want to pass an
2691 argument.
2692
2693 =item shift ARRAY
2694
2695 =item shift
2696
2697 Shifts the first value of the array off and returns it, shortening the
2698 array by 1 and moving everything down.  If there are no elements in the
2699 array, returns the undefined value.  If ARRAY is omitted, shifts the
2700 @ARGV array in the main program, and the @_ array in subroutines.
2701 (This is determined lexically.)  See also unshift(), push(), and pop().
2702 Shift() and unshift() do the same thing to the left end of an array
2703 that push() and pop() do to the right end.
2704
2705 =item shmctl ID,CMD,ARG
2706
2707 Calls the System V IPC function shmctl.  If CMD is &IPC_STAT, then ARG
2708 must be a variable which will hold the returned shmid_ds structure.
2709 Returns like ioctl: the undefined value for error, "0 but true" for
2710 zero, or the actual return value otherwise.
2711
2712 =item shmget KEY,SIZE,FLAGS
2713
2714 Calls the System V IPC function shmget.  Returns the shared memory
2715 segment id, or the undefined value if there is an error.
2716
2717 =item shmread ID,VAR,POS,SIZE
2718
2719 =item shmwrite ID,STRING,POS,SIZE
2720
2721 Reads or writes the System V shared memory segment ID starting at
2722 position POS for size SIZE by attaching to it, copying in/out, and
2723 detaching from it.  When reading, VAR must be a variable which will
2724 hold the data read.  When writing, if STRING is too long, only SIZE
2725 bytes are used; if STRING is too short, nulls are written to fill out
2726 SIZE bytes.  Return TRUE if successful, or FALSE if there is an error.
2727
2728 =item shutdown SOCKET,HOW
2729
2730 Shuts down a socket connection in the manner indicated by HOW, which
2731 has the same interpretation as in the system call of the same name.
2732
2733 =item sin EXPR
2734
2735 =item sin 
2736
2737 Returns the sine of EXPR (expressed in radians).  If EXPR is omitted,
2738 returns sine of $_.
2739
2740 For the inverse sine operation, you may use the POSIX::sin()
2741 function, or use this relation:
2742
2743     sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
2744
2745 =item sleep EXPR
2746
2747 =item sleep
2748
2749 Causes the script to sleep for EXPR seconds, or forever if no EXPR.
2750 May be interrupted by sending the process a SIGALRM.  Returns the
2751 number of seconds actually slept.  You probably cannot mix alarm() and
2752 sleep() calls, because sleep() is often implemented using alarm().
2753
2754 On some older systems, it may sleep up to a full second less than what
2755 you requested, depending on how it counts seconds.  Most modern systems
2756 always sleep the full amount.
2757
2758 For delays of finer granularity than one second, you may use Perl's
2759 syscall() interface to access setitimer(2) if your system supports it, 
2760 or else see L</select()> below.  
2761
2762 See also the POSIX module's sigpause() function.
2763
2764 =item socket SOCKET,DOMAIN,TYPE,PROTOCOL
2765
2766 Opens a socket of the specified kind and attaches it to filehandle
2767 SOCKET.  DOMAIN, TYPE, and PROTOCOL are specified the same as for the
2768 system call of the same name.  You should "use Socket;" first to get
2769 the proper definitions imported.  See the example in L<perlipc/"Sockets: Client/Server Communication">.
2770
2771 =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
2772
2773 Creates an unnamed pair of sockets in the specified domain, of the
2774 specified type.  DOMAIN, TYPE, and PROTOCOL are specified the same as
2775 for the system call of the same name.  If unimplemented, yields a fatal
2776 error.  Returns TRUE if successful.
2777
2778 =item sort SUBNAME LIST
2779
2780 =item sort BLOCK LIST
2781
2782 =item sort LIST
2783
2784 Sorts the LIST and returns the sorted list value.  Nonexistent values
2785 of arrays are stripped out.  If SUBNAME or BLOCK is omitted, sorts
2786 in standard string comparison order.  If SUBNAME is specified, it
2787 gives the name of a subroutine that returns an integer less than, equal
2788 to, or greater than 0, depending on how the elements of the array are
2789 to be ordered.  (The E<lt>=E<gt> and cmp operators are extremely useful in such
2790 routines.)  SUBNAME may be a scalar variable name, in which case the
2791 value provides the name of the subroutine to use.  In place of a
2792 SUBNAME, you can provide a BLOCK as an anonymous, in-line sort
2793 subroutine.
2794
2795 In the interests of efficiency the normal calling code for subroutines is
2796 bypassed, with the following effects: the subroutine may not be a
2797 recursive subroutine, and the two elements to be compared are passed into
2798 the subroutine not via @_ but as the package global variables $a and
2799 $b (see example below).  They are passed by reference, so don't
2800 modify $a and $b.  And don't try to declare them as lexicals either.
2801
2802 You also cannot exit out of the sort block or subroutine using any of the
2803 loop control operators described in L<perlsyn> or with goto().
2804
2805 When C<use locale> is in effect, C<sort LIST> sorts LIST according to the
2806 current collation locale.  See L<perllocale>.
2807
2808 Examples:
2809
2810     # sort lexically
2811     @articles = sort @files;
2812
2813     # same thing, but with explicit sort routine
2814     @articles = sort {$a cmp $b} @files;
2815
2816     # now case-insensitively
2817     @articles = sort { uc($a) cmp uc($b)} @files;
2818
2819     # same thing in reversed order
2820     @articles = sort {$b cmp $a} @files;
2821
2822     # sort numerically ascending
2823     @articles = sort {$a <=> $b} @files;
2824
2825     # sort numerically descending
2826     @articles = sort {$b <=> $a} @files;
2827
2828     # sort using explicit subroutine name
2829     sub byage {
2830         $age{$a} <=> $age{$b};  # presuming integers
2831     }
2832     @sortedclass = sort byage @class;
2833
2834     # this sorts the %age associative arrays by value 
2835     # instead of key using an in-line function
2836     @eldest = sort { $age{$b} <=> $age{$a} } keys %age;
2837
2838     sub backwards { $b cmp $a; }
2839     @harry = ('dog','cat','x','Cain','Abel');
2840     @george = ('gone','chased','yz','Punished','Axed');
2841     print sort @harry;
2842             # prints AbelCaincatdogx
2843     print sort backwards @harry;
2844             # prints xdogcatCainAbel
2845     print sort @george, 'to', @harry;
2846             # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
2847
2848     # inefficiently sort by descending numeric compare using 
2849     # the first integer after the first = sign, or the 
2850     # whole record case-insensitively otherwise
2851
2852     @new = sort {
2853         ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
2854                             ||
2855                     uc($a)  cmp  uc($b)
2856     } @old;
2857
2858     # same thing, but much more efficiently;
2859     # we'll build auxiliary indices instead
2860     # for speed
2861     @nums = @caps = ();
2862     for (@old) { 
2863         push @nums, /=(\d+)/;
2864         push @caps, uc($_);
2865     } 
2866
2867     @new = @old[ sort {
2868                         $nums[$b] <=> $nums[$a]
2869                                  ||
2870                         $caps[$a] cmp $caps[$b]
2871                        } 0..$#old
2872                ];
2873
2874     # same thing using a Schwartzian Transform (no temps)
2875     @new = map { $_->[0] }
2876         sort { $b->[1] <=> $a->[1]
2877                         ||
2878                $a->[2] cmp $b->[2]
2879         } map { [$_, /=(\d+)/, uc($_)] } @old;
2880
2881 If you're using strict, you I<MUST NOT> declare $a
2882 and $b as lexicals.  They are package globals.  That means
2883 if you're in the C<main> package, it's
2884
2885     @articles = sort {$main::b <=> $main::a} @files;
2886
2887 or just
2888
2889     @articles = sort {$::b <=> $::a} @files;
2890
2891 but if you're in the C<FooPack> package, it's
2892
2893     @articles = sort {$FooPack::b <=> $FooPack::a} @files;
2894
2895 The comparison function is required to behave.  If it returns
2896 inconsistent results (sometimes saying $x[1] is less than $x[2] and
2897 sometimes saying the opposite, for example) the Perl interpreter will
2898 probably crash and dump core.  This is entirely due to and dependent
2899 upon your system's qsort(3) library routine; this routine often avoids
2900 sanity checks in the interest of speed.
2901
2902 =item splice ARRAY,OFFSET,LENGTH,LIST
2903
2904 =item splice ARRAY,OFFSET,LENGTH
2905
2906 =item splice ARRAY,OFFSET
2907
2908 Removes the elements designated by OFFSET and LENGTH from an array, and
2909 replaces them with the elements of LIST, if any.  Returns the elements
2910 removed from the array.  The array grows or shrinks as necessary.  If
2911 LENGTH is omitted, removes everything from OFFSET onward.  The
2912 following equivalences hold (assuming C<$[ == 0>):
2913
2914     push(@a,$x,$y)      splice(@a,$#a+1,0,$x,$y)
2915     pop(@a)             splice(@a,-1)
2916     shift(@a)           splice(@a,0,1)
2917     unshift(@a,$x,$y)   splice(@a,0,0,$x,$y)
2918     $a[$x] = $y         splice(@a,$x,1,$y);
2919
2920 Example, assuming array lengths are passed before arrays:
2921
2922     sub aeq {   # compare two list values
2923         local(@a) = splice(@_,0,shift);
2924         local(@b) = splice(@_,0,shift);
2925         return 0 unless @a == @b;       # same len?
2926         while (@a) {
2927             return 0 if pop(@a) ne pop(@b);
2928         }
2929         return 1;
2930     }
2931     if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
2932
2933 =item split /PATTERN/,EXPR,LIMIT
2934
2935 =item split /PATTERN/,EXPR
2936
2937 =item split /PATTERN/
2938
2939 =item split
2940
2941 Splits a string into an array of strings, and returns it.
2942
2943 If not in a list context, returns the number of fields found and splits into
2944 the @_ array.  (In a list context, you can force the split into @_ by
2945 using C<??> as the pattern delimiters, but it still returns the array
2946 value.)  The use of implicit split to @_ is deprecated, however.
2947
2948 If EXPR is omitted, splits the $_ string.  If PATTERN is also omitted,
2949 splits on whitespace (after skipping any leading whitespace).  Anything
2950 matching PATTERN is taken to be a delimiter separating the fields.  (Note
2951 that the delimiter may be longer than one character.)  If LIMIT is
2952 specified and is not negative, splits into no more than that many fields
2953 (though it may split into fewer).  If LIMIT is unspecified, trailing null
2954 fields are stripped (which potential users of pop() would do well to
2955 remember).  If LIMIT is negative, it is treated as if an arbitrarily large
2956 LIMIT had been specified.
2957
2958 A pattern matching the null string (not to be confused with
2959 a null pattern C<//>, which is just one member of the set of patterns
2960 matching a null string) will split the value of EXPR into separate
2961 characters at each point it matches that way.  For example:
2962
2963     print join(':', split(/ */, 'hi there'));
2964
2965 produces the output 'h:i:t:h:e:r:e'.
2966
2967 The LIMIT parameter can be used to split a line partially
2968
2969     ($login, $passwd, $remainder) = split(/:/, $_, 3);
2970
2971 When assigning to a list, if LIMIT is omitted, Perl supplies a LIMIT
2972 one larger than the number of variables in the list, to avoid
2973 unnecessary work.  For the list above LIMIT would have been 4 by
2974 default.  In time critical applications it behooves you not to split
2975 into more fields than you really need.
2976
2977 If the PATTERN contains parentheses, additional array elements are
2978 created from each matching substring in the delimiter.
2979
2980     split(/([,-])/, "1-10,20", 3);
2981
2982 produces the list value
2983
2984     (1, '-', 10, ',', 20)
2985
2986 If you had the entire header of a normal Unix email message in $header, 
2987 you could split it up into fields and their values this way:
2988
2989     $header =~ s/\n\s+/ /g;  # fix continuation lines
2990     %hdrs   =  (UNIX_FROM => split /^(.*?):\s*/m, $header);
2991
2992 The pattern C</PATTERN/> may be replaced with an expression to specify
2993 patterns that vary at runtime.  (To do runtime compilation only once,
2994 use C</$variable/o>.)
2995
2996 As a special case, specifying a PATTERN of space (C<' '>) will split on
2997 white space just as split with no arguments does.  Thus, split(' ') can
2998 be used to emulate B<awk>'s default behavior, whereas C<split(/ /)>
2999 will give you as many null initial fields as there are leading spaces.
3000 A split on /\s+/ is like a split(' ') except that any leading
3001 whitespace produces a null first field.  A split with no arguments
3002 really does a C<split(' ', $_)> internally.
3003
3004 Example:
3005
3006     open(passwd, '/etc/passwd');
3007     while (<passwd>) {
3008         ($login, $passwd, $uid, $gid, $gcos, 
3009             $home, $shell) = split(/:/);
3010         ...
3011     }
3012
3013 (Note that $shell above will still have a newline on it.  See L</chop>, 
3014 L</chomp>, and L</join>.)
3015
3016 =item sprintf FORMAT, LIST
3017
3018 Returns a string formatted by the usual printf conventions of the C
3019 language.  See L<sprintf(3)> or L<printf(3)> on your system for details.
3020 (The * character for an indirectly specified length is not
3021 supported, but you can get the same effect by interpolating a variable
3022 into the pattern.)  If C<use locale> is
3023 in effect, the character used for the decimal point in formatted real numbers
3024 is affected by the LC_NUMERIC locale.  See L<perllocale>.
3025 Some C libraries' implementations of sprintf() can
3026 dump core when fed ludicrous arguments.
3027
3028 =item sqrt EXPR
3029
3030 =item sqrt 
3031
3032 Return the square root of EXPR.  If EXPR is omitted, returns square
3033 root of $_.
3034
3035 =item srand EXPR
3036
3037 Sets the random number seed for the C<rand> operator.  If EXPR is omitted,
3038 uses a semi-random value based on the current time and process ID, among
3039 other things.  In versions of Perl prior to 5.004 the default seed was
3040 just the current time().  This isn't a particularly good seed, so many
3041 old programs supply their own seed value (often C<time ^ $$> or C<time ^
3042 ($$ + ($$ << 15))>), but that isn't necessary any more.
3043
3044 You need something much more random than the default seed for
3045 cryptographic purposes, though.  Checksumming the compressed output of
3046 one or more rapidly changing operating system status programs is the
3047 usual method. For example:
3048
3049     srand (time ^ $$ ^ unpack "%L*", `ps axww | gzip`);
3050
3051 If you're particularly concerned with this, see the Math::TrulyRandom
3052 module in CPAN.
3053
3054 Do I<not> call srand() multiple times in your program unless you know
3055 exactly what you're doing and why you're doing it.  The point of the
3056 function is to "seed" the rand() function so that rand() can produce
3057 a different sequence each time you run your program.  Just do it once at the
3058 top of your program, or you I<won't> get random numbers out of rand()!
3059
3060 Frequently called programs (like CGI scripts) that simply use 
3061
3062     time ^ $$
3063
3064 for a seed can fall prey to the mathematical property that 
3065
3066     a^b == (a+1)^(b+1)
3067
3068 one-third of the time.  So don't do that.
3069   
3070 =item stat FILEHANDLE
3071
3072 =item stat EXPR
3073
3074 =item stat 
3075
3076 Returns a 13-element array giving the status info for a file, either the
3077 file opened via FILEHANDLE, or named by EXPR. If EXPR is omitted, it
3078 stats $_.  Returns a null list if the stat fails.  Typically used as
3079 follows:
3080
3081
3082     ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
3083        $atime,$mtime,$ctime,$blksize,$blocks)
3084            = stat($filename);
3085
3086 Not all fields are supported on all filesystem types.  Here are the 
3087 meaning of the fields:
3088
3089   dev       device number of filesystem 
3090   ino       inode number 
3091   mode      file mode  (type and permissions)
3092   nlink     number of (hard) links to the file 
3093   uid       numeric user ID of file's owner 
3094   gid       numeric group ID of file's owner 
3095   rdev      the device identifier (special files only)
3096   size      total size of file, in bytes 
3097   atime     last access time since the epoch
3098   mtime     last modify time since the epoch
3099   ctime     inode change time (NOT creation time!) since the epoch
3100   blksize   preferred block size for file system I/O
3101   blocks    actual number of blocks allocated
3102
3103 (The epoch was at 00:00 January 1, 1970 GMT.)
3104
3105 If stat is passed the special filehandle consisting of an underline, no
3106 stat is done, but the current contents of the stat structure from the
3107 last stat or filetest are returned.  Example:
3108
3109     if (-x $file && (($d) = stat(_)) && $d < 0) {
3110         print "$file is executable NFS file\n";
3111     }
3112
3113 (This works on machines only for which the device number is negative under NFS.)
3114
3115 =item study SCALAR
3116
3117 =item study
3118
3119 Takes extra time to study SCALAR (C<$_> if unspecified) in anticipation of
3120 doing many pattern matches on the string before it is next modified.
3121 This may or may not save time, depending on the nature and number of
3122 patterns you are searching on, and on the distribution of character
3123 frequencies in the string to be searched--you probably want to compare
3124 run times with and without it to see which runs faster.  Those loops
3125 which scan for many short constant strings (including the constant
3126 parts of more complex patterns) will benefit most.  You may have only
3127 one study active at a time--if you study a different scalar the first
3128 is "unstudied".  (The way study works is this: a linked list of every
3129 character in the string to be searched is made, so we know, for
3130 example, where all the 'k' characters are.  From each search string,
3131 the rarest character is selected, based on some static frequency tables
3132 constructed from some C programs and English text.  Only those places
3133 that contain this "rarest" character are examined.)
3134
3135 For example, here is a loop which inserts index producing entries
3136 before any line containing a certain pattern:
3137
3138     while (<>) {
3139         study;
3140         print ".IX foo\n" if /\bfoo\b/;
3141         print ".IX bar\n" if /\bbar\b/;
3142         print ".IX blurfl\n" if /\bblurfl\b/;
3143         ...
3144         print;
3145     }
3146
3147 In searching for /\bfoo\b/, only those locations in $_ that contain "f"
3148 will be looked at, because "f" is rarer than "o".  In general, this is
3149 a big win except in pathological cases.  The only question is whether
3150 it saves you more time than it took to build the linked list in the
3151 first place.
3152
3153 Note that if you have to look for strings that you don't know till
3154 runtime, you can build an entire loop as a string and eval that to
3155 avoid recompiling all your patterns all the time.  Together with
3156 undefining $/ to input entire files as one record, this can be very
3157 fast, often faster than specialized programs like fgrep(1).  The following
3158 scans a list of files (C<@files>) for a list of words (C<@words>), and prints
3159 out the names of those files that contain a match:
3160
3161     $search = 'while (<>) { study;';
3162     foreach $word (@words) {
3163         $search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n";
3164     }
3165     $search .= "}";
3166     @ARGV = @files;
3167     undef $/;
3168     eval $search;               # this screams
3169     $/ = "\n";          # put back to normal input delimiter
3170     foreach $file (sort keys(%seen)) {
3171         print $file, "\n";
3172     }
3173
3174 =item sub BLOCK
3175
3176 =item sub NAME
3177
3178 =item sub NAME BLOCK
3179
3180 This is subroutine definition, not a real function I<per se>.  With just a
3181 NAME (and possibly prototypes), it's just a forward declaration.  Without
3182 a NAME, it's an anonymous function declaration, and does actually return a
3183 value: the CODE ref of the closure you just created. See L<perlsub> and
3184 L<perlref> for details.
3185
3186 =item substr EXPR,OFFSET,LEN
3187
3188 =item substr EXPR,OFFSET
3189
3190 Extracts a substring out of EXPR and returns it.  First character is at
3191 offset 0, or whatever you've set $[ to.  If OFFSET is negative, starts
3192 that far from the end of the string.  If LEN is omitted, returns
3193 everything to the end of the string.  If LEN is negative, leaves that
3194 many characters off the end of the string.
3195
3196 You can use the substr() function
3197 as an lvalue, in which case EXPR must be an lvalue.  If you assign
3198 something shorter than LEN, the string will shrink, and if you assign
3199 something longer than LEN, the string will grow to accommodate it.  To
3200 keep the string the same length you may need to pad or chop your value
3201 using sprintf().
3202
3203 =item symlink OLDFILE,NEWFILE
3204
3205 Creates a new filename symbolically linked to the old filename.
3206 Returns 1 for success, 0 otherwise.  On systems that don't support
3207 symbolic links, produces a fatal error at run time.  To check for that,
3208 use eval:
3209
3210     $symlink_exists = (eval 'symlink("","");', $@ eq '');
3211
3212 =item syscall LIST
3213
3214 Calls the system call specified as the first element of the list,
3215 passing the remaining elements as arguments to the system call.  If
3216 unimplemented, produces a fatal error.  The arguments are interpreted
3217 as follows: if a given argument is numeric, the argument is passed as
3218 an int.  If not, the pointer to the string value is passed.  You are
3219 responsible to make sure a string is pre-extended long enough to
3220 receive any result that might be written into a string.  If your
3221 integer arguments are not literals and have never been interpreted in a
3222 numeric context, you may need to add 0 to them to force them to look
3223 like numbers.
3224
3225     require 'syscall.ph';               # may need to run h2ph
3226     syscall(&SYS_write, fileno(STDOUT), "hi there\n", 9);
3227
3228 Note that Perl supports passing of up to only 14 arguments to your system call,
3229 which in practice should usually suffice.
3230
3231 =item sysopen FILEHANDLE,FILENAME,MODE
3232
3233 =item sysopen FILEHANDLE,FILENAME,MODE,PERMS
3234
3235 Opens the file whose filename is given by FILENAME, and associates it
3236 with FILEHANDLE.  If FILEHANDLE is an expression, its value is used as
3237 the name of the real filehandle wanted.  This function calls the
3238 underlying operating system's C<open> function with the parameters
3239 FILENAME, MODE, PERMS.
3240
3241 The possible values and flag bits of the MODE parameter are
3242 system-dependent; they are available via the standard module C<Fcntl>.
3243 However, for historical reasons, some values are universal: zero means
3244 read-only, one means write-only, and two means read/write.
3245
3246 If the file named by FILENAME does not exist and the C<open> call
3247 creates it (typically because MODE includes the O_CREAT flag), then
3248 the value of PERMS specifies the permissions of the newly created
3249 file.  If PERMS is omitted, the default value is 0666, which allows
3250 read and write for all.  This default is reasonable: see C<umask>.
3251
3252 The IO::File module provides a more object-oriented approach, if you're
3253 into that kind of thing.
3254
3255 =item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
3256
3257 =item sysread FILEHANDLE,SCALAR,LENGTH
3258
3259 Attempts to read LENGTH bytes of data into variable SCALAR from the
3260 specified FILEHANDLE, using the system call read(2).  It bypasses
3261 stdio, so mixing this with other kinds of reads may cause confusion.
3262 Returns the number of bytes actually read, or undef if there was an
3263 error.  SCALAR will be grown or shrunk so that the last byte actually
3264 read is the last byte of the scalar after the read.
3265
3266 An OFFSET may be specified to place the read data at some place in the
3267 string other than the beginning.  A negative OFFSET specifies
3268 placement at that many bytes counting backwards from the end of the
3269 string.  A positive OFFSET greater than the length of SCALAR results
3270 in the string being padded to the required size with "\0" bytes before
3271 the result of the read is appended.
3272
3273 =item system LIST
3274
3275 Does exactly the same thing as "exec LIST" except that a fork is done
3276 first, and the parent process waits for the child process to complete.
3277 Note that argument processing varies depending on the number of
3278 arguments.  The return value is the exit status of the program as
3279 returned by the wait() call.  To get the actual exit value divide by
3280 256.  See also L</exec>.  This is I<NOT> what you want to use to capture 
3281 the output from a command, for that you should use merely back-ticks or
3282 qx//, as described in L<perlop/"`STRING`">.
3283
3284 Because system() and back-ticks block SIGINT and SIGQUIT, killing the
3285 program they're running doesn't actually interrupt your program.
3286
3287     @args = ("command", "arg1", "arg2");
3288     system(@args) == 0 
3289          or die "system @args failed: $?" 
3290
3291 Here's a more elaborate example of analysing the return value from
3292 system() on a UNIX system to check for all possibilities, including for
3293 signals and coredumps.
3294
3295     $rc = 0xffff & system @args;
3296     printf "system(%s) returned %#04x: ", "@args", $rc;
3297     if ($rc == 0) {
3298         print "ran with normal exit\n";
3299     } 
3300     elsif ($rc == 0xff00) {
3301         print "command failed: $!\n";
3302     } 
3303     elsif ($rc > 0x80) {
3304         $rc >>= 8;
3305         print "ran with non-zero exit status $rc\n";
3306     } 
3307     else {
3308         print "ran with ";
3309         if ($rc &   0x80) {
3310             $rc &= ~0x80;
3311             print "coredump from ";
3312         } 
3313         print "signal $rc\n"
3314     } 
3315     $ok = ($rc != 0);
3316   
3317 =item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
3318
3319 =item syswrite FILEHANDLE,SCALAR,LENGTH
3320
3321 Attempts to write LENGTH bytes of data from variable SCALAR to the
3322 specified FILEHANDLE, using the system call write(2).  It bypasses
3323 stdio, so mixing this with prints may cause confusion.  Returns the
3324 number of bytes actually written, or undef if there was an error.
3325 If the length is greater than the available data, only as much data as
3326 is available will be written.
3327
3328 An OFFSET may be specified to write the data from some part of the
3329 string other than the beginning.  A negative OFFSET specifies writing
3330 from that many bytes counting backwards from the end of the string.
3331
3332 =item tell FILEHANDLE
3333
3334 =item tell
3335
3336 Returns the current file position for FILEHANDLE.  FILEHANDLE may be an
3337 expression whose value gives the name of the actual filehandle.  If
3338 FILEHANDLE is omitted, assumes the file last read.
3339
3340 =item telldir DIRHANDLE
3341
3342 Returns the current position of the readdir() routines on DIRHANDLE.
3343 Value may be given to seekdir() to access a particular location in a
3344 directory.  Has the same caveats about possible directory compaction as
3345 the corresponding system library routine.
3346
3347 =item tie VARIABLE,CLASSNAME,LIST
3348
3349 This function binds a variable to a package class that will provide the
3350 implementation for the variable.  VARIABLE is the name of the variable
3351 to be enchanted.  CLASSNAME is the name of a class implementing objects
3352 of correct type.  Any additional arguments are passed to the "new"
3353 method of the class (meaning TIESCALAR, TIEARRAY, or TIEHASH).
3354 Typically these are arguments such as might be passed to the dbm_open()
3355 function of C.  The object returned by the "new" method is also
3356 returned by the tie() function, which would be useful if you want to
3357 access other methods in CLASSNAME.
3358
3359 Note that functions such as keys() and values() may return huge array
3360 values when used on large objects, like DBM files.  You may prefer to
3361 use the each() function to iterate over such.  Example:
3362
3363     # print out history file offsets
3364     use NDBM_File;
3365     tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
3366     while (($key,$val) = each %HIST) {
3367         print $key, ' = ', unpack('L',$val), "\n";
3368     }
3369     untie(%HIST);
3370
3371 A class implementing an associative array should have the following
3372 methods:
3373
3374     TIEHASH classname, LIST
3375     DESTROY this
3376     FETCH this, key
3377     STORE this, key, value
3378     DELETE this, key
3379     EXISTS this, key
3380     FIRSTKEY this
3381     NEXTKEY this, lastkey
3382
3383 A class implementing an ordinary array should have the following methods:
3384
3385     TIEARRAY classname, LIST
3386     DESTROY this
3387     FETCH this, key
3388     STORE this, key, value
3389     [others TBD]
3390
3391 A class implementing a scalar should have the following methods:
3392
3393     TIESCALAR classname, LIST
3394     DESTROY this
3395     FETCH this, 
3396     STORE this, value
3397
3398 Unlike dbmopen(), the tie() function will not use or require a module
3399 for you--you need to do that explicitly yourself.  See L<DB_File>
3400 or the F<Config> module for interesting tie() implementations.
3401
3402 =item tied VARIABLE
3403
3404 Returns a reference to the object underlying VARIABLE (the same value
3405 that was originally returned by the tie() call which bound the variable
3406 to a package.)  Returns the undefined value if VARIABLE isn't tied to a
3407 package.
3408
3409 =item time
3410
3411 Returns the number of non-leap seconds since whatever time the system
3412 considers to be the epoch (that's 00:00:00, January 1, 1904 for MacOS,
3413 and 00:00:00 UTC, January 1, 1970 for most other systems).
3414 Suitable for feeding to gmtime() and localtime().
3415
3416 =item times
3417
3418 Returns a four-element array giving the user and system times, in
3419 seconds, for this process and the children of this process.
3420
3421     ($user,$system,$cuser,$csystem) = times;
3422
3423 =item tr///
3424
3425 The translation operator.  See L<perlop>.
3426
3427 =item truncate FILEHANDLE,LENGTH
3428
3429 =item truncate EXPR,LENGTH
3430
3431 Truncates the file opened on FILEHANDLE, or named by EXPR, to the
3432 specified length.  Produces a fatal error if truncate isn't implemented
3433 on your system.
3434
3435 =item uc EXPR
3436
3437 =item uc 
3438
3439 Returns an uppercased version of EXPR.  This is the internal function
3440 implementing the \U escape in double-quoted strings.
3441 Respects current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>.
3442
3443 If EXPR is omitted, uses $_.
3444
3445 =item ucfirst EXPR
3446
3447 =item ucfirst 
3448
3449 Returns the value of EXPR with the first character uppercased.  This is
3450 the internal function implementing the \u escape in double-quoted strings.
3451 Respects current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>.
3452
3453 If EXPR is omitted, uses $_.
3454
3455 =item umask EXPR
3456
3457 =item umask
3458
3459 Sets the umask for the process and returns the old one.  If EXPR is
3460 omitted, returns merely the current umask.
3461
3462 =item undef EXPR
3463
3464 =item undef
3465
3466 Undefines the value of EXPR, which must be an lvalue.  Use on only a
3467 scalar value, an entire array, or a subroutine name (using "&").  (Using undef()
3468 will probably not do what you expect on most predefined variables or
3469 DBM list values, so don't do that.)  Always returns the undefined value.  You can omit
3470 the EXPR, in which case nothing is undefined, but you still get an
3471 undefined value that you could, for instance, return from a
3472 subroutine.  Examples:
3473
3474     undef $foo;
3475     undef $bar{'blurfl'};
3476     undef @ary;
3477     undef %assoc;
3478     undef &mysub;
3479     return (wantarray ? () : undef) if $they_blew_it;
3480
3481 =item unlink LIST
3482
3483 =item unlink 
3484
3485 Deletes a list of files.  Returns the number of files successfully
3486 deleted.
3487
3488     $cnt = unlink 'a', 'b', 'c';
3489     unlink @goners;
3490     unlink <*.bak>;
3491
3492 Note: unlink will not delete directories unless you are superuser and
3493 the B<-U> flag is supplied to Perl.  Even if these conditions are
3494 met, be warned that unlinking a directory can inflict damage on your
3495 filesystem.  Use rmdir instead.
3496
3497 If LIST is omitted, uses $_.
3498
3499 =item unpack TEMPLATE,EXPR
3500
3501 Unpack does the reverse of pack: it takes a string representing a
3502 structure and expands it out into a list value, returning the array
3503 value.  (In a scalar context, it returns merely the first value
3504 produced.)  The TEMPLATE has the same format as in the pack function.
3505 Here's a subroutine that does substring:
3506
3507     sub substr {
3508         local($what,$where,$howmuch) = @_;
3509         unpack("x$where a$howmuch", $what);
3510     }
3511
3512 and then there's
3513
3514     sub ordinal { unpack("c",$_[0]); } # same as ord()
3515
3516 In addition, you may prefix a field with a %E<lt>numberE<gt> to indicate that
3517 you want a E<lt>numberE<gt>-bit checksum of the items instead of the items
3518 themselves.  Default is a 16-bit checksum.  For example, the following
3519 computes the same number as the System V sum program:
3520
3521     while (<>) {
3522         $checksum += unpack("%16C*", $_);
3523     }
3524     $checksum %= 65536;
3525
3526 The following efficiently counts the number of set bits in a bit vector:
3527
3528     $setbits = unpack("%32b*", $selectmask);
3529
3530 =item untie VARIABLE
3531
3532 Breaks the binding between a variable and a package.  (See tie().)
3533
3534 =item unshift ARRAY,LIST
3535
3536 Does the opposite of a C<shift>.  Or the opposite of a C<push>,
3537 depending on how you look at it.  Prepends list to the front of the
3538 array, and returns the new number of elements in the array.
3539
3540     unshift(ARGV, '-e') unless $ARGV[0] =~ /^-/;
3541
3542 Note the LIST is prepended whole, not one element at a time, so the
3543 prepended elements stay in the same order.  Use reverse to do the
3544 reverse.
3545
3546 =item use Module LIST
3547
3548 =item use Module
3549
3550 =item use Module VERSION LIST
3551
3552 =item use VERSION
3553
3554 Imports some semantics into the current package from the named module,
3555 generally by aliasing certain subroutine or variable names into your
3556 package.  It is exactly equivalent to
3557
3558     BEGIN { require Module; import Module LIST; }
3559
3560 except that Module I<must> be a bare word.
3561
3562 If the first argument to C<use> is a number, it is treated as a version
3563 number instead of a module name.  If the version of the Perl interpreter
3564 is less than VERSION, then an error message is printed and Perl exits
3565 immediately.  This is often useful if you need to check the current
3566 Perl version before C<use>ing library modules which have changed in
3567 incompatible ways from older versions of Perl.  (We try not to do
3568 this more than we have to.)
3569
3570 The BEGIN forces the require and import to happen at compile time.  The
3571 require makes sure the module is loaded into memory if it hasn't been
3572 yet.  The import is not a builtin--it's just an ordinary static method
3573 call into the "Module" package to tell the module to import the list of
3574 features back into the current package.  The module can implement its
3575 import method any way it likes, though most modules just choose to
3576 derive their import method via inheritance from the Exporter class that
3577 is defined in the Exporter module. See L<Exporter>.  If no import
3578 method can be found then the error is currently silently ignored. This
3579 may change to a fatal error in a future version.
3580
3581 If you don't want your namespace altered, explicitly supply an empty list:
3582
3583     use Module ();
3584
3585 That is exactly equivalent to
3586
3587     BEGIN { require Module; }
3588
3589 If the VERSION argument is present between Module and LIST, then the
3590 C<use> will call the VERSION method in class Module with the given
3591 version as an argument.  The default VERSION method, inherited from
3592 the Universal class, croaks if the given version is larger than the
3593 value of the variable $Module::VERSION.  (Note that there is not a
3594 comma after VERSION!)
3595
3596 Because this is a wide-open interface, pragmas (compiler directives)
3597 are also implemented this way.  Currently implemented pragmas are:
3598
3599     use integer;
3600     use diagnostics;
3601     use sigtrap qw(SEGV BUS);
3602     use strict  qw(subs vars refs);
3603     use subs    qw(afunc blurfl);
3604
3605 These pseudo-modules import semantics into the current block scope, unlike
3606 ordinary modules, which import symbols into the current package (which are
3607 effective through the end of the file).
3608
3609 There's a corresponding "no" command that unimports meanings imported
3610 by use, i.e., it calls C<unimport Module LIST> instead of C<import>.
3611
3612     no integer;
3613     no strict 'refs';
3614
3615 If no unimport method can be found the call fails with a fatal error.
3616
3617 See L<perlmod> for a list of standard modules and pragmas.
3618
3619 =item utime LIST
3620
3621 Changes the access and modification times on each file of a list of
3622 files.  The first two elements of the list must be the NUMERICAL access
3623 and modification times, in that order.  Returns the number of files
3624 successfully changed.  The inode modification time of each file is set
3625 to the current time.  Example of a "touch" command:
3626
3627     #!/usr/bin/perl
3628     $now = time;
3629     utime $now, $now, @ARGV;
3630
3631 =item values ASSOC_ARRAY
3632
3633 Returns a normal array consisting of all the values of the named
3634 associative array.  (In a scalar context, returns the number of
3635 values.)  The values are returned in an apparently random order, but it
3636 is the same order as either the keys() or each() function would produce
3637 on the same array.  See also keys(), each(), and sort().
3638
3639 =item vec EXPR,OFFSET,BITS
3640
3641 Treats the string in EXPR as a vector of unsigned integers, and
3642 returns the value of the bit field specified by OFFSET.  BITS specifies
3643 the number of bits that are reserved for each entry in the bit
3644 vector. This must be a power of two from 1 to 32. vec() may also be
3645 assigned to, in which case parentheses are needed to give the expression
3646 the correct precedence as in
3647
3648     vec($image, $max_x * $x + $y, 8) = 3;
3649
3650 Vectors created with vec() can also be manipulated with the logical
3651 operators |, &, and ^, which will assume a bit vector operation is
3652 desired when both operands are strings.
3653
3654 To transform a bit vector into a string or array of 0's and 1's, use these:
3655
3656     $bits = unpack("b*", $vector);
3657     @bits = split(//, unpack("b*", $vector));
3658
3659 If you know the exact length in bits, it can be used in place of the *.
3660
3661 =item wait
3662
3663 Waits for a child process to terminate and returns the pid of the
3664 deceased process, or -1 if there are no child processes.  The status is
3665 returned in C<$?>.
3666
3667 =item waitpid PID,FLAGS
3668
3669 Waits for a particular child process to terminate and returns the pid
3670 of the deceased process, or -1 if there is no such child process.  The
3671 status is returned in C<$?>.  If you say
3672
3673     use POSIX ":sys_wait_h";
3674     ...
3675     waitpid(-1,&WNOHANG);
3676
3677 then you can do a non-blocking wait for any process.  Non-blocking wait
3678 is available on machines supporting either the waitpid(2) or
3679 wait4(2) system calls.  However, waiting for a particular pid with
3680 FLAGS of 0 is implemented everywhere.  (Perl emulates the system call
3681 by remembering the status values of processes that have exited but have
3682 not been harvested by the Perl script yet.)
3683
3684 =item wantarray
3685
3686 Returns TRUE if the context of the currently executing subroutine is
3687 looking for a list value.  Returns FALSE if the context is looking
3688 for a scalar.
3689
3690     return wantarray ? () : undef;
3691
3692 =item warn LIST
3693
3694 Produces a message on STDERR just like die(), but doesn't exit or throw
3695 an exception.
3696
3697 No message is printed if there is a C<$SIG{__WARN__}> handler
3698 installed.  It is the handler's responsibility to deal with the message
3699 as it sees fit (like, for instance, converting it into a die()).  Most
3700 handlers must therefore make arrangements to actually display the
3701 warnings that they are not prepared to deal with, by calling warn()
3702 again in the handler.  Note that this is quite safe and will not
3703 produce an endless loop, since C<__WARN__> hooks are not called from
3704 inside one.
3705
3706 You will find this behavior is slightly different from that of
3707 C<$SIG{__DIE__}> handlers (which don't suppress the error text, but can
3708 instead call die() again to change it).
3709
3710 Using a C<__WARN__> handler provides a powerful way to silence all
3711 warnings (even the so-called mandatory ones).  An example:
3712
3713     # wipe out *all* compile-time warnings
3714     BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } }
3715     my $foo = 10;
3716     my $foo = 20;          # no warning about duplicate my $foo,
3717                            # but hey, you asked for it!
3718     # no compile-time or run-time warnings before here
3719     $DOWARN = 1;
3720
3721     # run-time warnings enabled after here
3722     warn "\$foo is alive and $foo!";     # does show up
3723
3724 See L<perlvar> for details on setting C<%SIG> entries, and for more
3725 examples.
3726
3727 =item write FILEHANDLE
3728
3729 =item write EXPR
3730
3731 =item write
3732
3733 Writes a formatted record (possibly multi-line) to the specified file,
3734 using the format associated with that file.  By default the format for
3735 a file is the one having the same name is the filehandle, but the
3736 format for the current output channel (see the select() function) may be set
3737 explicitly by assigning the name of the format to the C<$~> variable.
3738
3739 Top of form processing is handled automatically:  if there is
3740 insufficient room on the current page for the formatted record, the
3741 page is advanced by writing a form feed, a special top-of-page format
3742 is used to format the new page header, and then the record is written.
3743 By default the top-of-page format is the name of the filehandle with
3744 "_TOP" appended, but it may be dynamically set to the format of your
3745 choice by assigning the name to the C<$^> variable while the filehandle is
3746 selected.  The number of lines remaining on the current page is in
3747 variable C<$->, which can be set to 0 to force a new page.
3748
3749 If FILEHANDLE is unspecified, output goes to the current default output
3750 channel, which starts out as STDOUT but may be changed by the
3751 C<select> operator.  If the FILEHANDLE is an EXPR, then the expression
3752 is evaluated and the resulting string is used to look up the name of
3753 the FILEHANDLE at run time.  For more on formats, see L<perlform>.
3754
3755 Note that write is I<NOT> the opposite of read.  Unfortunately.
3756
3757 =item y///
3758
3759 The translation operator.  See L<perlop>.
3760
3761 =back