perl 3.0 patch #42 (combined patch)
[perl.git] / perl.man.2
1 ''' Beginning of part 2
2 ''' $Header: perl_man.2,v 3.0.1.10 90/11/10 01:46:29 lwall Locked $
3 '''
4 ''' $Log:       perl.man.2,v $
5 ''' Revision 3.0.1.10  90/11/10  01:46:29  lwall
6 ''' patch38: random cleanup
7 ''' patch38: added alarm function
8 ''' 
9 ''' Revision 3.0.1.9  90/10/15  18:17:37  lwall
10 ''' patch29: added caller
11 ''' patch29: index and substr now have optional 3rd args
12 ''' patch29: added SysV IPC
13 ''' 
14 ''' Revision 3.0.1.8  90/08/13  22:21:00  lwall
15 ''' patch28: documented that you can't interpolate $) or $| in pattern
16 ''' 
17 ''' Revision 3.0.1.7  90/08/09  04:27:04  lwall
18 ''' patch19: added require operator
19 ''' 
20 ''' Revision 3.0.1.6  90/08/03  11:15:29  lwall
21 ''' patch19: Intermediate diffs for Randal
22 ''' 
23 ''' Revision 3.0.1.5  90/03/27  16:15:17  lwall
24 ''' patch16: MSDOS support
25 ''' 
26 ''' Revision 3.0.1.4  90/03/12  16:46:02  lwall
27 ''' patch13: documented behavior of @array = /noparens/
28 ''' 
29 ''' Revision 3.0.1.3  90/02/28  17:55:58  lwall
30 ''' patch9: grep now returns number of items matched in scalar context
31 ''' patch9: documented in-place modification capabilites of grep
32 ''' 
33 ''' Revision 3.0.1.2  89/11/17  15:30:16  lwall
34 ''' patch5: fixed some manual typos and indent problems
35 ''' 
36 ''' Revision 3.0.1.1  89/11/11  04:43:10  lwall
37 ''' patch2: made some line breaks depend on troff vs. nroff
38 ''' patch2: example of unshift had args backwards
39 ''' 
40 ''' Revision 3.0  89/10/18  15:21:37  lwall
41 ''' 3.0 baseline
42 ''' 
43 '''
44 .PP
45 Along with the literals and variables mentioned earlier,
46 the operations in the following section can serve as terms in an expression.
47 Some of these operations take a LIST as an argument.
48 Such a list can consist of any combination of scalar arguments or array values;
49 the array values will be included in the list as if each individual element were
50 interpolated at that point in the list, forming a longer single-dimensional
51 array value.
52 Elements of the LIST should be separated by commas.
53 If an operation is listed both with and without parentheses around its
54 arguments, it means you can either use it as a unary operator or
55 as a function call.
56 To use it as a function call, the next token on the same line must
57 be a left parenthesis.
58 (There may be intervening white space.)
59 Such a function then has highest precedence, as you would expect from
60 a function.
61 If any token other than a left parenthesis follows, then it is a
62 unary operator, with a precedence depending only on whether it is a LIST
63 operator or not.
64 LIST operators have lowest precedence.
65 All other unary operators have a precedence greater than relational operators
66 but less than arithmetic operators.
67 See the section on Precedence.
68 .Ip "/PATTERN/" 8 4
69 See m/PATTERN/.
70 .Ip "?PATTERN?" 8 4
71 This is just like the /pattern/ search, except that it matches only once between
72 calls to the
73 .I reset
74 operator.
75 This is a useful optimization when you only want to see the first occurrence of
76 something in each file of a set of files, for instance.
77 Only ?? patterns local to the current package are reset.
78 .Ip "accept(NEWSOCKET,GENERICSOCKET)" 8 2
79 Does the same thing that the accept system call does.
80 Returns true if it succeeded, false otherwise.
81 See example in section on Interprocess Communication.
82 .Ip "alarm(SECONDS)" 8 4
83 .Ip "alarm SECONDS" 8
84 Arranges to have a SIGALRM delivered to this process after the specified number
85 of seconds (minus 1, actually) have elapsed.  Thus, alarm(15) will cause
86 a SIGALRM at some point more than 14 seconds in the future.
87 Only one timer may be counting at once.  Each call disables the previous
88 timer, and an argument of 0 may be supplied to cancel the previous timer
89 without starting a new one.
90 The returned value is the amount of time remaining on the previous timer.
91 .Ip "atan2(X,Y)" 8 2
92 Returns the arctangent of X/Y in the range
93 .if t \-\(*p to \(*p.
94 .if n \-PI to PI.
95 .Ip "bind(SOCKET,NAME)" 8 2
96 Does the same thing that the bind system call does.
97 Returns true if it succeeded, false otherwise.
98 NAME should be a packed address of the proper type for the socket.
99 See example in section on Interprocess Communication.
100 .Ip "binmode(FILEHANDLE)" 8 4
101 .Ip "binmode FILEHANDLE" 8 4
102 Arranges for the file to be read in \*(L"binary\*(R" mode in operating systems
103 that distinguish between binary and text files.
104 Files that are not read in binary mode have CR LF sequences translated
105 to LF on input and LF translated to CR LF on output.
106 Binmode has no effect under Unix.
107 If FILEHANDLE is an expression, the value is taken as the name of
108 the filehandle.
109 .Ip "caller(EXPR)"
110 .Ip "caller"
111 Returns the context of the current subroutine call:
112 .nf
113
114         ($package,$filename,$line) = caller;
115
116 .fi
117 With EXPR, returns some extra information that the debugger uses to print
118 a stack trace.  The value of EXPR indicates how many call frames to go
119 back before the current one.
120 .Ip "chdir(EXPR)" 8 2
121 .Ip "chdir EXPR" 8 2
122 Changes the working directory to EXPR, if possible.
123 If EXPR is omitted, changes to home directory.
124 Returns 1 upon success, 0 otherwise.
125 See example under
126 .IR die .
127 .Ip "chmod(LIST)" 8 2
128 .Ip "chmod LIST" 8 2
129 Changes the permissions of a list of files.
130 The first element of the list must be the numerical mode.
131 Returns the number of files successfully changed.
132 .nf
133
134 .ne 2
135         $cnt = chmod 0755, \'foo\', \'bar\';
136         chmod 0755, @executables;
137
138 .fi
139 .Ip "chop(LIST)" 8 7
140 .Ip "chop(VARIABLE)" 8
141 .Ip "chop VARIABLE" 8
142 .Ip "chop" 8
143 Chops off the last character of a string and returns the character chopped.
144 It's used primarily to remove the newline from the end of an input record,
145 but is much more efficient than s/\en// because it neither scans nor copies
146 the string.
147 If VARIABLE is omitted, chops $_.
148 Example:
149 .nf
150
151 .ne 5
152         while (<>) {
153                 chop;   # avoid \en on last field
154                 @array = split(/:/);
155                 .\|.\|.
156         }
157
158 .fi
159 You can actually chop anything that's an lvalue, including an assignment:
160 .nf
161
162         chop($cwd = \`pwd\`);
163         chop($answer = <STDIN>);
164
165 .fi
166 If you chop a list, each element is chopped.
167 Only the value of the last chop is returned.
168 .Ip "chown(LIST)" 8 2
169 .Ip "chown LIST" 8 2
170 Changes the owner (and group) of a list of files.
171 The first two elements of the list must be the NUMERICAL uid and gid,
172 in that order.
173 Returns the number of files successfully changed.
174 .nf
175
176 .ne 2
177         $cnt = chown $uid, $gid, \'foo\', \'bar\';
178         chown $uid, $gid, @filenames;
179
180 .fi
181 .ne 23
182 Here's an example of looking up non-numeric uids:
183 .nf
184
185         print "User: ";
186         $user = <STDIN>;
187         chop($user);
188         print "Files: "
189         $pattern = <STDIN>;
190         chop($pattern);
191 .ie t \{\
192         open(pass, \'/etc/passwd\') || die "Can't open passwd: $!\en";
193 'br\}
194 .el \{\
195         open(pass, \'/etc/passwd\')
196                 || die "Can't open passwd: $!\en";
197 'br\}
198         while (<pass>) {
199                 ($login,$pass,$uid,$gid) = split(/:/);
200                 $uid{$login} = $uid;
201                 $gid{$login} = $gid;
202         }
203         @ary = <${pattern}>;    # get filenames
204         if ($uid{$user} eq \'\') {
205                 die "$user not in passwd file";
206         }
207         else {
208                 chown $uid{$user}, $gid{$user}, @ary;
209         }
210
211 .fi
212 .Ip "chroot(FILENAME)" 8 5
213 .Ip "chroot FILENAME" 8
214 Does the same as the system call of that name.
215 If you don't know what it does, don't worry about it.
216 If FILENAME is omitted, does chroot to $_.
217 .Ip "close(FILEHANDLE)" 8 5
218 .Ip "close FILEHANDLE" 8
219 Closes the file or pipe associated with the file handle.
220 You don't have to close FILEHANDLE if you are immediately going to
221 do another open on it, since open will close it for you.
222 (See
223 .IR open .)
224 However, an explicit close on an input file resets the line counter ($.), while
225 the implicit close done by
226 .I open
227 does not.
228 Also, closing a pipe will wait for the process executing on the pipe to complete,
229 in case you want to look at the output of the pipe afterwards.
230 Closing a pipe explicitly also puts the status value of the command into $?.
231 Example:
232 .nf
233
234 .ne 4
235         open(OUTPUT, \'|sort >foo\');   # pipe to sort
236         .\|.\|. # print stuff to output
237         close OUTPUT;           # wait for sort to finish
238         open(INPUT, \'foo\');   # get sort's results
239
240 .fi
241 FILEHANDLE may be an expression whose value gives the real filehandle name.
242 .Ip "closedir(DIRHANDLE)" 8 5
243 .Ip "closedir DIRHANDLE" 8
244 Closes a directory opened by opendir().
245 .Ip "connect(SOCKET,NAME)" 8 2
246 Does the same thing that the connect system call does.
247 Returns true if it succeeded, false otherwise.
248 NAME should be a package address of the proper type for the socket.
249 See example in section on Interprocess Communication.
250 .Ip "cos(EXPR)" 8 6
251 .Ip "cos EXPR" 8 6
252 Returns the cosine of EXPR (expressed in radians).
253 If EXPR is omitted takes cosine of $_.
254 .Ip "crypt(PLAINTEXT,SALT)" 8 6
255 Encrypts a string exactly like the crypt() function in the C library.
256 Useful for checking the password file for lousy passwords.
257 Only the guys wearing white hats should do this.
258 .Ip "dbmclose(ASSOC_ARRAY)" 8 6
259 .Ip "dbmclose ASSOC_ARRAY" 8
260 Breaks the binding between a dbm file and an associative array.
261 The values remaining in the associative array are meaningless unless
262 you happen to want to know what was in the cache for the dbm file.
263 This function is only useful if you have ndbm.
264 .Ip "dbmopen(ASSOC,DBNAME,MODE)" 8 6
265 This binds a dbm or ndbm file to an associative array.
266 ASSOC is the name of the associative array.
267 (Unlike normal open, the first argument is NOT a filehandle, even though
268 it looks like one).
269 DBNAME is the name of the database (without the .dir or .pag extension).
270 If the database does not exist, it is created with protection specified
271 by MODE (as modified by the umask).
272 If your system only supports the older dbm functions, you may only have one
273 dbmopen in your program.
274 If your system has neither dbm nor ndbm, calling dbmopen produces a fatal
275 error.
276 .Sp
277 Values assigned to the associative array prior to the dbmopen are lost.
278 A certain number of values from the dbm file are cached in memory.
279 By default this number is 64, but you can increase it by preallocating
280 that number of garbage entries in the associative array before the dbmopen.
281 You can flush the cache if necessary with the reset command.
282 .Sp
283 If you don't have write access to the dbm file, you can only read
284 associative array variables, not set them.
285 If you want to test whether you can write, either use file tests or
286 try setting a dummy array entry inside an eval, which will trap the error.
287 .Sp
288 Note that functions such as keys() and values() may return huge array values
289 when used on large dbm files.
290 You may prefer to use the each() function to iterate over large dbm files.
291 Example:
292 .nf
293
294 .ne 6
295         # print out history file offsets
296         dbmopen(HIST,'/usr/lib/news/history',0666);
297         while (($key,$val) = each %HIST) {
298                 print $key, ' = ', unpack('L',$val), "\en";
299         }
300         dbmclose(HIST);
301
302 .fi
303 .Ip "defined(EXPR)" 8 6
304 .Ip "defined EXPR" 8
305 Returns a boolean value saying whether the lvalue EXPR has a real value
306 or not.
307 Many operations return the undefined value under exceptional conditions,
308 such as end of file, uninitialized variable, system error and such.
309 This function allows you to distinguish between an undefined null string
310 and a defined null string with operations that might return a real null
311 string, in particular referencing elements of an array.
312 You may also check to see if arrays or subroutines exist.
313 Use on predefined variables is not guaranteed to produce intuitive results.
314 Examples:
315 .nf
316
317 .ne 7
318         print if defined $switch{'D'};
319         print "$val\en" while defined($val = pop(@ary));
320         die "Can't readlink $sym: $!"
321                 unless defined($value = readlink $sym);
322         eval '@foo = ()' if defined(@foo);
323         die "No XYZ package defined" unless defined %_XYZ;
324         sub foo { defined &bar ? &bar(@_) : die "No bar"; }
325
326 .fi
327 See also undef.
328 .Ip "delete $ASSOC{KEY}" 8 6
329 Deletes the specified value from the specified associative array.
330 Returns the deleted value, or the undefined value if nothing was deleted.
331 Deleting from $ENV{} modifies the environment.
332 Deleting from an array bound to a dbm file deletes the entry from the dbm
333 file.
334 .Sp
335 The following deletes all the values of an associative array:
336 .nf
337
338 .ne 3
339         foreach $key (keys %ARRAY) {
340                 delete $ARRAY{$key};
341         }
342
343 .fi
344 (But it would be faster to use the
345 .I reset
346 command.
347 Saying undef %ARRAY is faster yet.)
348 .Ip "die(LIST)" 8
349 .Ip "die LIST" 8
350 Outside of an eval, prints the value of LIST to
351 .I STDERR
352 and exits with the current value of $!
353 (errno).
354 If $! is 0, exits with the value of ($? >> 8) (\`command\` status).
355 If ($? >> 8) is 0, exits with 255.
356 Inside an eval, the error message is stuffed into $@ and the eval is terminated
357 with the undefined value.
358 .Sp
359 Equivalent examples:
360 .nf
361
362 .ne 3
363 .ie t \{\
364         die "Can't cd to spool: $!\en" unless chdir \'/usr/spool/news\';
365 'br\}
366 .el \{\
367         die "Can't cd to spool: $!\en"
368                 unless chdir \'/usr/spool/news\';
369 'br\}
370
371         chdir \'/usr/spool/news\' || die "Can't cd to spool: $!\en" 
372
373 .fi
374 .Sp
375 If the value of EXPR does not end in a newline, the current script line
376 number and input line number (if any) are also printed, and a newline is
377 supplied.
378 Hint: sometimes appending \*(L", stopped\*(R" to your message will cause it to make
379 better sense when the string \*(L"at foo line 123\*(R" is appended.
380 Suppose you are running script \*(L"canasta\*(R".
381 .nf
382
383 .ne 7
384         die "/etc/games is no good";
385         die "/etc/games is no good, stopped";
386
387 produce, respectively
388
389         /etc/games is no good at canasta line 123.
390         /etc/games is no good, stopped at canasta line 123.
391
392 .fi
393 See also
394 .IR exit .
395 .Ip "do BLOCK" 8 4
396 Returns the value of the last command in the sequence of commands indicated
397 by BLOCK.
398 When modified by a loop modifier, executes the BLOCK once before testing the
399 loop condition.
400 (On other statements the loop modifiers test the conditional first.)
401 .Ip "do SUBROUTINE (LIST)" 8 3
402 Executes a SUBROUTINE declared by a
403 .I sub
404 declaration, and returns the value
405 of the last expression evaluated in SUBROUTINE.
406 If there is no subroutine by that name, produces a fatal error.
407 (You may use the \*(L"defined\*(R" operator to determine if a subroutine
408 exists.)
409 If you pass arrays as part of LIST you may wish to pass the length
410 of the array in front of each array.
411 (See the section on subroutines later on.)
412 SUBROUTINE may be a scalar variable, in which case the variable contains
413 the name of the subroutine to execute.
414 The parentheses are required to avoid confusion with the \*(L"do EXPR\*(R"
415 form.
416 .Sp
417 As an alternate form, you may call a subroutine by prefixing the name with
418 an ampersand: &foo(@args).
419 If you aren't passing any arguments, you don't have to use parentheses.
420 If you omit the parentheses, no @_ array is passed to the subroutine.
421 The & form is also used to specify subroutines to the defined and undef
422 operators.
423 .Ip "do EXPR" 8 3
424 Uses the value of EXPR as a filename and executes the contents of the file
425 as a
426 .I perl
427 script.
428 Its primary use is to include subroutines from a
429 .I perl
430 subroutine library.
431 .nf
432
433         do \'stat.pl\';
434
435 is just like
436
437         eval \`cat stat.pl\`;
438
439 .fi
440 except that it's more efficient, more concise, keeps track of the current
441 filename for error messages, and searches all the
442 .B \-I
443 libraries if the file
444 isn't in the current directory (see also the @INC array in Predefined Names).
445 It's the same, however, in that it does reparse the file every time you
446 call it, so if you are going to use the file inside a loop you might prefer
447 to use \-P and #include, at the expense of a little more startup time.
448 (The main problem with #include is that cpp doesn't grok # comments\*(--a
449 workaround is to use \*(L";#\*(R" for standalone comments.)
450 Note that the following are NOT equivalent:
451 .nf
452
453 .ne 2
454         do $foo;        # eval a file
455         do $foo();      # call a subroutine
456
457 .fi
458 Note that inclusion of library routines is better done with
459 the \*(L"require\*(R" operator.
460 .Ip "dump LABEL" 8 6
461 This causes an immediate core dump.
462 Primarily this is so that you can use the undump program to turn your
463 core dump into an executable binary after having initialized all your
464 variables at the beginning of the program.
465 When the new binary is executed it will begin by executing a "goto LABEL"
466 (with all the restrictions that goto suffers).
467 Think of it as a goto with an intervening core dump and reincarnation.
468 If LABEL is omitted, restarts the program from the top.
469 WARNING: any files opened at the time of the dump will NOT be open any more
470 when the program is reincarnated, with possible resulting confusion on the part
471 of perl.
472 See also \-u.
473 .Sp
474 Example:
475 .nf
476
477 .ne 16
478         #!/usr/bin/perl
479         require 'getopt.pl';
480         require 'stat.pl';
481         %days = (
482             'Sun',1,
483             'Mon',2,
484             'Tue',3,
485             'Wed',4,
486             'Thu',5,
487             'Fri',6,
488             'Sat',7);
489
490         dump QUICKSTART if $ARGV[0] eq '-d';
491
492     QUICKSTART:
493         do Getopt('f');
494
495 .fi
496 .Ip "each(ASSOC_ARRAY)" 8 6
497 .Ip "each ASSOC_ARRAY" 8
498 Returns a 2 element array consisting of the key and value for the next
499 value of an associative array, so that you can iterate over it.
500 Entries are returned in an apparently random order.
501 When the array is entirely read, a null array is returned (which when
502 assigned produces a FALSE (0) value).
503 The next call to each() after that will start iterating again.
504 The iterator can be reset only by reading all the elements from the array.
505 You must not modify the array while iterating over it.
506 There is a single iterator for each associative array, shared by all
507 each(), keys() and values() function calls in the program.
508 The following prints out your environment like the printenv program, only
509 in a different order:
510 .nf
511
512 .ne 3
513         while (($key,$value) = each %ENV) {
514                 print "$key=$value\en";
515         }
516
517 .fi
518 See also keys() and values().
519 .Ip "eof(FILEHANDLE)" 8 8
520 .Ip "eof()" 8
521 .Ip "eof" 8
522 Returns 1 if the next read on FILEHANDLE will return end of file, or if
523 FILEHANDLE is not open.
524 FILEHANDLE may be an expression whose value gives the real filehandle name.
525 (Note that this function actually reads a character and then ungetc's it,
526 so it is not very useful in an interactive context.)
527 An eof without an argument returns the eof status for the last file read.
528 Empty parentheses () may be used to indicate the pseudo file formed of the
529 files listed on the command line, i.e. eof() is reasonable to use inside
530 a while (<>) loop to detect the end of only the last file.
531 Use eof(ARGV) or eof without the parentheses to test EACH file in a while (<>) loop.
532 Examples:
533 .nf
534
535 .ne 7
536         # insert dashes just before last line of last file
537         while (<>) {
538                 if (eof()) {
539                         print "\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\en";
540                 }
541                 print;
542         }
543
544 .ne 7
545         # reset line numbering on each input file
546         while (<>) {
547                 print "$.\et$_";
548                 if (eof) {      # Not eof().
549                         close(ARGV);
550                 }
551         }
552
553 .fi
554 .Ip "eval(EXPR)" 8 6
555 .Ip "eval EXPR" 8 6
556 EXPR is parsed and executed as if it were a little
557 .I perl
558 program.
559 It is executed in the context of the current
560 .I perl
561 program, so that
562 any variable settings, subroutine or format definitions remain afterwards.
563 The value returned is the value of the last expression evaluated, just
564 as with subroutines.
565 If there is a syntax error or runtime error, or a die statement is
566 executed, an undefined value is returned by
567 eval, and $@ is set to the error message.
568 If there was no error, $@ is guaranteed to be a null string.
569 If EXPR is omitted, evaluates $_.
570 The final semicolon, if any, may be omitted from the expression.
571 .Sp
572 Note that, since eval traps otherwise-fatal errors, it is useful for
573 determining whether a particular feature
574 (such as dbmopen or symlink) is implemented.
575 It is also Perl's exception trapping mechanism, where the die operator is
576 used to raise exceptions.
577 .Ip "exec(LIST)" 8 8
578 .Ip "exec LIST" 8 6
579 If there is more than one argument in LIST, or if LIST is an array with
580 more than one value,
581 calls execvp() with the arguments in LIST.
582 If there is only one scalar argument, the argument is checked for shell metacharacters.
583 If there are any, the entire argument is passed to \*(L"/bin/sh \-c\*(R" for parsing.
584 If there are none, the argument is split into words and passed directly to
585 execvp(), which is more efficient.
586 Note: exec (and system) do not flush your output buffer, so you may need to
587 set $| to avoid lost output.
588 Examples:
589 .nf
590
591         exec \'/bin/echo\', \'Your arguments are: \', @ARGV;
592         exec "sort $outfile | uniq";
593
594 .fi
595 .Sp
596 If you don't really want to execute the first argument, but want to lie
597 to the program you are executing about its own name, you can specify
598 the program you actually want to run by assigning that to a variable and
599 putting the name of the variable in front of the LIST without a comma.
600 (This always forces interpretation of the LIST as a multi-valued list, even
601 if there is only a single scalar in the list.)
602 Example:
603 .nf
604
605 .ne 2
606         $shell = '/bin/csh';
607         exec $shell '-sh';              # pretend it's a login shell
608
609 .fi
610 .Ip "exit(EXPR)" 8 6
611 .Ip "exit EXPR" 8
612 Evaluates EXPR and exits immediately with that value.
613 Example:
614 .nf
615
616 .ne 2
617         $ans = <STDIN>;
618         exit 0 \|if \|$ans \|=~ \|/\|^[Xx]\|/\|;
619
620 .fi
621 See also
622 .IR die .
623 If EXPR is omitted, exits with 0 status.
624 .Ip "exp(EXPR)" 8 3
625 .Ip "exp EXPR" 8
626 Returns
627 .I e
628 to the power of EXPR.
629 If EXPR is omitted, gives exp($_).
630 .Ip "fcntl(FILEHANDLE,FUNCTION,SCALAR)" 8 4
631 Implements the fcntl(2) function.
632 You'll probably have to say
633 .nf
634
635         require "fcntl.ph";     # probably /usr/local/lib/perl/fcntl.ph
636
637 .fi
638 first to get the correct function definitions.
639 If fcntl.ph doesn't exist or doesn't have the correct definitions
640 you'll have to roll
641 your own, based on your C header files such as <sys/fcntl.h>.
642 (There is a perl script called h2ph that comes with the perl kit
643 which may help you in this.)
644 Argument processing and value return works just like ioctl below.
645 Note that fcntl will produce a fatal error if used on a machine that doesn't implement
646 fcntl(2).
647 .Ip "fileno(FILEHANDLE)" 8 4
648 .Ip "fileno FILEHANDLE" 8 4
649 Returns the file descriptor for a filehandle.
650 Useful for constructing bitmaps for select().
651 If FILEHANDLE is an expression, the value is taken as the name of
652 the filehandle.
653 .Ip "flock(FILEHANDLE,OPERATION)" 8 4
654 Calls flock(2) on FILEHANDLE.
655 See manual page for flock(2) for definition of OPERATION.
656 Will produce a fatal error if used on a machine that doesn't implement
657 flock(2).
658 Here's a mailbox appender for BSD systems.
659 .nf
660
661 .ne 20
662         $LOCK_SH = 1;
663         $LOCK_EX = 2;
664         $LOCK_NB = 4;
665         $LOCK_UN = 8;
666
667         sub lock {
668             flock(MBOX,$LOCK_EX);
669             # and, in case someone appended
670             # while we were waiting...
671             seek(MBOX, 0, 2);
672         }
673
674         sub unlock {
675             flock(MBOX,$LOCK_UN);
676         }
677
678         open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
679                 || die "Can't open mailbox: $!";
680
681         do lock();
682         print MBOX $msg,"\en\en";
683         do unlock();
684
685 .fi
686 .Ip "fork" 8 4
687 Does a fork() call.
688 Returns the child pid to the parent process and 0 to the child process.
689 Note: unflushed buffers remain unflushed in both processes, which means
690 you may need to set $| to avoid duplicate output.
691 .Ip "getc(FILEHANDLE)" 8 4
692 .Ip "getc FILEHANDLE" 8
693 .Ip "getc" 8
694 Returns the next character from the input file attached to FILEHANDLE, or
695 a null string at EOF.
696 If FILEHANDLE is omitted, reads from STDIN.
697 .Ip "getlogin" 8 3
698 Returns the current login from /etc/utmp, if any.
699 If null, use getpwuid.
700
701         $login = getlogin || (getpwuid($<))[0] || "Somebody";
702
703 .Ip "getpeername(SOCKET)" 8 3
704 Returns the packed sockaddr address of other end of the SOCKET connection.
705 .nf
706
707 .ne 4
708         # An internet sockaddr
709         $sockaddr = 'S n a4 x8';
710         $hersockaddr = getpeername(S);
711 .ie t \{\
712         ($family, $port, $heraddr) = unpack($sockaddr,$hersockaddr);
713 'br\}
714 .el \{\
715         ($family, $port, $heraddr) =
716                         unpack($sockaddr,$hersockaddr);
717 'br\}
718
719 .fi
720 .Ip "getpgrp(PID)" 8 4
721 .Ip "getpgrp PID" 8
722 Returns the current process group for the specified PID, 0 for the current
723 process.
724 Will produce a fatal error if used on a machine that doesn't implement
725 getpgrp(2).
726 If EXPR is omitted, returns process group of current process.
727 .Ip "getppid" 8 4
728 Returns the process id of the parent process.
729 .Ip "getpriority(WHICH,WHO)" 8 4
730 Returns the current priority for a process, a process group, or a user.
731 (See getpriority(2).)
732 Will produce a fatal error if used on a machine that doesn't implement
733 getpriority(2).
734 .Ip "getpwnam(NAME)" 8
735 .Ip "getgrnam(NAME)" 8
736 .Ip "gethostbyname(NAME)" 8
737 .Ip "getnetbyname(NAME)" 8
738 .Ip "getprotobyname(NAME)" 8
739 .Ip "getpwuid(UID)" 8
740 .Ip "getgrgid(GID)" 8
741 .Ip "getservbyname(NAME,PROTO)" 8
742 .Ip "gethostbyaddr(ADDR,ADDRTYPE)" 8
743 .Ip "getnetbyaddr(ADDR,ADDRTYPE)" 8
744 .Ip "getprotobynumber(NUMBER)" 8
745 .Ip "getservbyport(PORT,PROTO)" 8
746 .Ip "getpwent" 8
747 .Ip "getgrent" 8
748 .Ip "gethostent" 8
749 .Ip "getnetent" 8
750 .Ip "getprotoent" 8
751 .Ip "getservent" 8
752 .Ip "setpwent" 8
753 .Ip "setgrent" 8
754 .Ip "sethostent(STAYOPEN)" 8
755 .Ip "setnetent(STAYOPEN)" 8
756 .Ip "setprotoent(STAYOPEN)" 8
757 .Ip "setservent(STAYOPEN)" 8
758 .Ip "endpwent" 8
759 .Ip "endgrent" 8
760 .Ip "endhostent" 8
761 .Ip "endnetent" 8
762 .Ip "endprotoent" 8
763 .Ip "endservent" 8
764 These routines perform the same functions as their counterparts in the
765 system library.
766 The return values from the various get routines are as follows:
767 .nf
768
769         ($name,$passwd,$uid,$gid,
770            $quota,$comment,$gcos,$dir,$shell) = getpw.\|.\|.
771         ($name,$passwd,$gid,$members) = getgr.\|.\|.
772         ($name,$aliases,$addrtype,$length,@addrs) = gethost.\|.\|.
773         ($name,$aliases,$addrtype,$net) = getnet.\|.\|.
774         ($name,$aliases,$proto) = getproto.\|.\|.
775         ($name,$aliases,$port,$proto) = getserv.\|.\|.
776
777 .fi
778 The $members value returned by getgr.\|.\|. is a space separated list
779 of the login names of the members of the group.
780 .Sp
781 The @addrs value returned by the gethost.\|.\|. functions is a list of the
782 raw addresses returned by the corresponding system library call.
783 In the Internet domain, each address is four bytes long and you can unpack
784 it by saying something like:
785 .nf
786
787         ($a,$b,$c,$d) = unpack('C4',$addr[0]);
788
789 .fi
790 .Ip "getsockname(SOCKET)" 8 3
791 Returns the packed sockaddr address of this end of the SOCKET connection.
792 .nf
793
794 .ne 4
795         # An internet sockaddr
796         $sockaddr = 'S n a4 x8';
797         $mysockaddr = getsockname(S);
798 .ie t \{\
799         ($family, $port, $myaddr) = unpack($sockaddr,$mysockaddr);
800 'br\}
801 .el \{\
802         ($family, $port, $myaddr) =
803                         unpack($sockaddr,$mysockaddr);
804 'br\}
805
806 .fi
807 .Ip "getsockopt(SOCKET,LEVEL,OPTNAME)" 8 3
808 Returns the socket option requested, or undefined if there is an error.
809 .Ip "gmtime(EXPR)" 8 4
810 .Ip "gmtime EXPR" 8
811 Converts a time as returned by the time function to a 9-element array with
812 the time analyzed for the Greenwich timezone.
813 Typically used as follows:
814 .nf
815
816 .ne 3
817 .ie t \{\
818     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = gmtime(time);
819 'br\}
820 .el \{\
821     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
822                                                 gmtime(time);
823 'br\}
824
825 .fi
826 All array elements are numeric, and come straight out of a struct tm.
827 In particular this means that $mon has the range 0.\|.11 and $wday has the
828 range 0.\|.6.
829 If EXPR is omitted, does gmtime(time).
830 .Ip "goto LABEL" 8 6
831 Finds the statement labeled with LABEL and resumes execution there.
832 Currently you may only go to statements in the main body of the program
833 that are not nested inside a do {} construct.
834 This statement is not implemented very efficiently, and is here only to make
835 the
836 .IR sed -to- perl
837 translator easier.
838 I may change its semantics at any time, consistent with support for translated
839 .I sed
840 scripts.
841 Use it at your own risk.
842 Better yet, don't use it at all.
843 .Ip "grep(EXPR,LIST)" 8 4
844 Evaluates EXPR for each element of LIST (locally setting $_ to each element)
845 and returns the array value consisting of those elements for which the
846 expression evaluated to true.
847 In a scalar context, returns the number of times the expression was true.
848 .nf
849
850         @foo = grep(!/^#/, @bar);    # weed out comments
851
852 .fi
853 Note that, since $_ is a reference into the array value, it can be
854 used to modify the elements of the array.
855 While this is useful and supported, it can cause bizarre results if
856 the LIST is not a named array.
857 .Ip "hex(EXPR)" 8 4
858 .Ip "hex EXPR" 8
859 Returns the decimal value of EXPR interpreted as an hex string.
860 (To interpret strings that might start with 0 or 0x see oct().)
861 If EXPR is omitted, uses $_.
862 .Ip "index(STR,SUBSTR,POSITION)" 8 4
863 .Ip "index(STR,SUBSTR)" 8 4
864 Returns the position of the first occurrence of SUBSTR in STR at or after
865 POSITION.
866 If POSITION is omitted, starts searching from the beginning of the string.
867 The return value is based at 0, or whatever you've
868 set the $[ variable to.
869 If the substring is not found, returns one less than the base, ordinarily \-1.
870 .Ip "int(EXPR)" 8 4
871 .Ip "int EXPR" 8
872 Returns the integer portion of EXPR.
873 If EXPR is omitted, uses $_.
874 .Ip "ioctl(FILEHANDLE,FUNCTION,SCALAR)" 8 4
875 Implements the ioctl(2) function.
876 You'll probably have to say
877 .nf
878
879         require "ioctl.ph";     # probably /usr/local/lib/perl/ioctl.ph
880
881 .fi
882 first to get the correct function definitions.
883 If ioctl.ph doesn't exist or doesn't have the correct definitions
884 you'll have to roll
885 your own, based on your C header files such as <sys/ioctl.h>.
886 (There is a perl script called h2ph that comes with the perl kit
887 which may help you in this.)
888 SCALAR will be read and/or written depending on the FUNCTION\*(--a pointer
889 to the string value of SCALAR will be passed as the third argument of
890 the actual ioctl call.
891 (If SCALAR has no string value but does have a numeric value, that value
892 will be passed rather than a pointer to the string value.
893 To guarantee this to be true, add a 0 to the scalar before using it.)
894 The pack() and unpack() functions are useful for manipulating the values
895 of structures used by ioctl().
896 The following example sets the erase character to DEL.
897 .nf
898
899 .ne 9
900         require 'ioctl.ph';
901         $sgttyb_t = "ccccs";            # 4 chars and a short
902         if (ioctl(STDIN,$TIOCGETP,$sgttyb)) {
903                 @ary = unpack($sgttyb_t,$sgttyb);
904                 $ary[2] = 127;
905                 $sgttyb = pack($sgttyb_t,@ary);
906                 ioctl(STDIN,$TIOCSETP,$sgttyb)
907                         || die "Can't ioctl: $!";
908         }
909
910 .fi
911 The return value of ioctl (and fcntl) is as follows:
912 .nf
913
914 .ne 4
915         if OS returns:\h'|3i'perl returns:
916           -1\h'|3i'  undefined value
917           0\h'|3i'  string "0 but true"
918           anything else\h'|3i'  that number
919
920 .fi
921 Thus perl returns true on success and false on failure, yet you can still
922 easily determine the actual value returned by the operating system:
923 .nf
924
925         ($retval = ioctl(...)) || ($retval = -1);
926         printf "System returned %d\en", $retval;
927 .fi
928 .Ip "join(EXPR,LIST)" 8 8
929 .Ip "join(EXPR,ARRAY)" 8
930 Joins the separate strings of LIST or ARRAY into a single string with fields
931 separated by the value of EXPR, and returns the string.
932 Example:
933 .nf
934     
935 .ie t \{\
936     $_ = join(\|\':\', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
937 'br\}
938 .el \{\
939     $_ = join(\|\':\',
940                 $login,$passwd,$uid,$gid,$gcos,$home,$shell);
941 'br\}
942
943 .fi
944 See
945 .IR split .
946 .Ip "keys(ASSOC_ARRAY)" 8 6
947 .Ip "keys ASSOC_ARRAY" 8
948 Returns a normal array consisting of all the keys of the named associative
949 array.
950 The keys are returned in an apparently random order, but it is the same order
951 as either the values() or each() function produces (given that the associative array
952 has not been modified).
953 Here is yet another way to print your environment:
954 .nf
955
956 .ne 5
957         @keys = keys %ENV;
958         @values = values %ENV;
959         while ($#keys >= 0) {
960                 print pop(keys), \'=\', pop(values), "\en";
961         }
962
963 or how about sorted by key:
964
965 .ne 3
966         foreach $key (sort(keys %ENV)) {
967                 print $key, \'=\', $ENV{$key}, "\en";
968         }
969
970 .fi
971 .Ip "kill(LIST)" 8 8
972 .Ip "kill LIST" 8 2
973 Sends a signal to a list of processes.
974 The first element of the list must be the signal to send.
975 Returns the number of processes successfully signaled.
976 .nf
977
978         $cnt = kill 1, $child1, $child2;
979         kill 9, @goners;
980
981 .fi
982 If the signal is negative, kills process groups instead of processes.
983 (On System V, a negative \fIprocess\fR number will also kill process groups,
984 but that's not portable.)
985 You may use a signal name in quotes.
986 .Ip "last LABEL" 8 8
987 .Ip "last" 8
988 The
989 .I last
990 command is like the
991 .I break
992 statement in C (as used in loops); it immediately exits the loop in question.
993 If the LABEL is omitted, the command refers to the innermost enclosing loop.
994 The
995 .I continue
996 block, if any, is not executed:
997 .nf
998
999 .ne 4
1000         line: while (<STDIN>) {
1001                 last line if /\|^$/;    # exit when done with header
1002                 .\|.\|.
1003         }
1004
1005 .fi
1006 .Ip "length(EXPR)" 8 4
1007 .Ip "length EXPR" 8
1008 Returns the length in characters of the value of EXPR.
1009 If EXPR is omitted, returns length of $_.
1010 .Ip "link(OLDFILE,NEWFILE)" 8 2
1011 Creates a new filename linked to the old filename.
1012 Returns 1 for success, 0 otherwise.
1013 .Ip "listen(SOCKET,QUEUESIZE)" 8 2
1014 Does the same thing that the listen system call does.
1015 Returns true if it succeeded, false otherwise.
1016 See example in section on Interprocess Communication.
1017 .Ip "local(LIST)" 8 4
1018 Declares the listed variables to be local to the enclosing block,
1019 subroutine, eval or \*(L"do\*(R".
1020 All the listed elements must be legal lvalues.
1021 This operator works by saving the current values of those variables in LIST
1022 on a hidden stack and restoring them upon exiting the block, subroutine or eval.
1023 This means that called subroutines can also reference the local variable,
1024 but not the global one.
1025 The LIST may be assigned to if desired, which allows you to initialize
1026 your local variables.
1027 (If no initializer is given for a particular variable, it is created with
1028 an undefined value.)
1029 Commonly this is used to name the parameters to a subroutine.
1030 Examples:
1031 .nf
1032
1033 .ne 13
1034         sub RANGEVAL {
1035                 local($min, $max, $thunk) = @_;
1036                 local($result) = \'\';
1037                 local($i);
1038
1039                 # Presumably $thunk makes reference to $i
1040
1041                 for ($i = $min; $i < $max; $i++) {
1042                         $result .= eval $thunk;
1043                 }
1044
1045                 $result;
1046         }
1047
1048 .ne 6
1049         if ($sw eq \'-v\') {
1050             # init local array with global array
1051             local(@ARGV) = @ARGV;
1052             unshift(@ARGV,\'echo\');
1053             system @ARGV;
1054         }
1055         # @ARGV restored
1056
1057 .ne 6
1058         # temporarily add to digits associative array
1059         if ($base12) {
1060                 # (NOTE: not claiming this is efficient!)
1061                 local(%digits) = (%digits,'t',10,'e',11);
1062                 do parse_num();
1063         }
1064
1065 .fi
1066 Note that local() is a run-time command, and so gets executed every time
1067 through a loop, using up more stack storage each time until it's all
1068 released at once when the loop is exited.
1069 .Ip "localtime(EXPR)" 8 4
1070 .Ip "localtime EXPR" 8
1071 Converts a time as returned by the time function to a 9-element array with
1072 the time analyzed for the local timezone.
1073 Typically used as follows:
1074 .nf
1075
1076 .ne 3
1077 .ie t \{\
1078     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time);
1079 'br\}
1080 .el \{\
1081     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
1082                                                 localtime(time);
1083 'br\}
1084
1085 .fi
1086 All array elements are numeric, and come straight out of a struct tm.
1087 In particular this means that $mon has the range 0.\|.11 and $wday has the
1088 range 0.\|.6.
1089 If EXPR is omitted, does localtime(time).
1090 .Ip "log(EXPR)" 8 4
1091 .Ip "log EXPR" 8
1092 Returns logarithm (base
1093 .IR e )
1094 of EXPR.
1095 If EXPR is omitted, returns log of $_.
1096 .Ip "lstat(FILEHANDLE)" 8 6
1097 .Ip "lstat FILEHANDLE" 8
1098 .Ip "lstat(EXPR)" 8
1099 .Ip "lstat SCALARVARIABLE" 8
1100 Does the same thing as the stat() function, but stats a symbolic link
1101 instead of the file the symbolic link points to.
1102 If symbolic links are unimplemented on your system, a normal stat is done.
1103 .Ip "m/PATTERN/io" 8 4
1104 .Ip "/PATTERN/io" 8
1105 Searches a string for a pattern match, and returns true (1) or false (\'\').
1106 If no string is specified via the =~ or !~ operator,
1107 the $_ string is searched.
1108 (The string specified with =~ need not be an lvalue\*(--it may be the result of an expression evaluation, but remember the =~ binds rather tightly.)
1109 See also the section on regular expressions.
1110 .Sp
1111 If / is the delimiter then the initial \*(L'm\*(R' is optional.
1112 With the \*(L'm\*(R' you can use any pair of non-alphanumeric characters
1113 as delimiters.
1114 This is particularly useful for matching Unix path names that contain \*(L'/\*(R'.
1115 If the final delimiter is followed by the optional letter \*(L'i\*(R', the matching is
1116 done in a case-insensitive manner.
1117 PATTERN may contain references to scalar variables, which will be interpolated
1118 (and the pattern recompiled) every time the pattern search is evaluated.
1119 (Note that $) and $| may not be interpolated because they look like end-of-string tests.)
1120 If you want such a pattern to be compiled only once, add an \*(L"o\*(R" after
1121 the trailing delimiter.
1122 This avoids expensive run-time recompilations, and
1123 is useful when the value you are interpolating won't change over the
1124 life of the script.
1125 .Sp
1126 If used in a context that requires an array value, a pattern match returns an
1127 array consisting of the subexpressions matched by the parentheses in the
1128 pattern,
1129 i.e. ($1, $2, $3.\|.\|.).
1130 It does NOT actually set $1, $2, etc. in this case, nor does it set $+, $`, $&
1131 or $'.
1132 If the match fails, a null array is returned.
1133 If the match succeeds, but there were no parentheses, an array value of (1)
1134 is returned.
1135 .Sp
1136 Examples:
1137 .nf
1138
1139 .ne 4
1140     open(tty, \'/dev/tty\');
1141     <tty> \|=~ \|/\|^y\|/i \|&& \|do foo(\|);   # do foo if desired
1142
1143     if (/Version: \|*\|([0\-9.]*\|)\|/\|) { $version = $1; }
1144
1145     next if m#^/usr/spool/uucp#;
1146
1147 .ne 5
1148     # poor man's grep
1149     $arg = shift;
1150     while (<>) {
1151             print if /$arg/o;   # compile only once
1152     }
1153
1154     if (($F1, $F2, $Etc) = ($foo =~ /^(\eS+)\es+(\eS+)\es*(.*)/))
1155
1156 .fi
1157 This last example splits $foo into the first two words and the remainder
1158 of the line, and assigns those three fields to $F1, $F2 and $Etc.
1159 The conditional is true if any variables were assigned, i.e. if the pattern
1160 matched.
1161 .Ip "mkdir(FILENAME,MODE)" 8 3
1162 Creates the directory specified by FILENAME, with permissions specified by
1163 MODE (as modified by umask).
1164 If it succeeds it returns 1, otherwise it returns 0 and sets $! (errno).
1165 .Ip "msgctl(ID,CMD,ARG)" 8 4
1166 Calls the System V IPC function msgctl.  If CMD is &IPC_STAT, then ARG
1167 must be a variable which will hold the returned msqid_ds structure.
1168 Returns like ioctl: the undefined value for error, "0 but true" for
1169 zero, or the actual return value otherwise.
1170 .Ip "msgget(KEY,FLAGS)" 8 4
1171 Calls the System V IPC function msgget.  Returns the message queue id,
1172 or the undefined value if there is an error.
1173 .Ip "msgsnd(ID,MSG,FLAGS)" 8 4
1174 Calls the System V IPC function msgsnd to send the message MSG to the
1175 message queue ID.  MSG must begin with the long integer message type,
1176 which may be created with pack("L", $type).  Returns true if
1177 successful, or false if there is an error.
1178 .Ip "msgrcv(ID,VAR,SIZE,TYPE,FLAGS)" 8 4
1179 Calls the System V IPC function msgrcv to receive a message from
1180 message queue ID into variable VAR with a maximum message size of
1181 SIZE.  Note that if a message is received, the message type will be
1182 the first thing in VAR, and the maximum length of VAR is SIZE plus the
1183 size of the message type.  Returns true if successful, or false if
1184 there is an error.