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