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