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.3
1 ''' Beginning of part 3
2 ''' $Header: perl.man.3,v 3.0.1.1 89/11/11 04:45:06 lwall Locked $
3 '''
4 ''' $Log:       perl.man.3,v $
5 ''' Revision 3.0.1.1  89/11/11  04:45:06  lwall
6 ''' patch2: made some line breaks depend on troff vs. nroff
7 ''' 
8 ''' Revision 3.0  89/10/18  15:21:46  lwall
9 ''' 3.0 baseline
10 ''' 
11 .Ip "next LABEL" 8 8
12 .Ip "next" 8
13 The
14 .I next
15 command is like the
16 .I continue
17 statement in C; it starts the next iteration of the loop:
18 .nf
19
20 .ne 4
21         line: while (<STDIN>) {
22                 next line if /\|^#/;    # discard comments
23                 .\|.\|.
24         }
25
26 .fi
27 Note that if there were a
28 .I continue
29 block on the above, it would get executed even on discarded lines.
30 If the LABEL is omitted, the command refers to the innermost enclosing loop.
31 .Ip "oct(EXPR)" 8 4
32 .Ip "oct EXPR" 8
33 Returns the decimal value of EXPR interpreted as an octal string.
34 (If EXPR happens to start off with 0x, interprets it as a hex string instead.)
35 The following will handle decimal, octal and hex in the standard notation:
36 .nf
37
38         $val = oct($val) if $val =~ /^0/;
39
40 .fi
41 If EXPR is omitted, uses $_.
42 .Ip "open(FILEHANDLE,EXPR)" 8 8
43 .Ip "open(FILEHANDLE)" 8
44 .Ip "open FILEHANDLE" 8
45 Opens the file whose filename is given by EXPR, and associates it with
46 FILEHANDLE.
47 If FILEHANDLE is an expression, its value is used as the name of the
48 real filehandle wanted.
49 If EXPR is omitted, the scalar variable of the same name as the FILEHANDLE
50 contains the filename.
51 If the filename begins with \*(L"<\*(R" or nothing, the file is opened for
52 input.
53 If the filename begins with \*(L">\*(R", the file is opened for output.
54 If the filename begins with \*(L">>\*(R", the file is opened for appending.
55 (You can put a \'+\' in front of the \'>\' or \'<\' to indicate that you
56 want both read and write access to the file.)
57 If the filename begins with \*(L"|\*(R", the filename is interpreted
58 as a command to which output is to be piped, and if the filename ends
59 with a \*(L"|\*(R", the filename is interpreted as command which pipes
60 input to us.
61 (You may not have a command that pipes both in and out.)
62 Opening \'\-\' opens
63 .I STDIN
64 and opening \'>\-\' opens
65 .IR STDOUT .
66 Open returns non-zero upon success, the undefined value otherwise.
67 If the open involved a pipe, the return value happens to be the pid
68 of the subprocess.
69 Examples:
70 .nf
71     
72 .ne 3
73         $article = 100;
74         open article || die "Can't find article $article: $!\en";
75         while (<article>) {\|.\|.\|.
76
77 .ie t \{\
78         open(LOG, \'>>/usr/spool/news/twitlog\'\|);     # (log is reserved)
79 'br\}
80 .el \{\
81         open(LOG, \'>>/usr/spool/news/twitlog\'\|);
82                                         # (log is reserved)
83 'br\}
84
85 .ie t \{\
86         open(article, "caesar <$article |"\|);          # decrypt article
87 'br\}
88 .el \{\
89         open(article, "caesar <$article |"\|);
90                                         # decrypt article
91 'br\}
92
93 .ie t \{\
94         open(extract, "|sort >/tmp/Tmp$$"\|);           # $$ is our process#
95 'br\}
96 .el \{\
97         open(extract, "|sort >/tmp/Tmp$$"\|);
98                                         # $$ is our process#
99 'br\}
100
101 .ne 7
102         # process argument list of files along with any includes
103
104         foreach $file (@ARGV) {
105                 do process($file, \'fh00\');    # no pun intended
106         }
107
108         sub process {
109                 local($filename, $input) = @_;
110                 $input++;               # this is a string increment
111                 unless (open($input, $filename)) {
112                         print STDERR "Can't open $filename: $!\en";
113                         return;
114                 }
115 .ie t \{\
116                 while (<$input>) {              # note the use of indirection
117 'br\}
118 .el \{\
119                 while (<$input>) {              # note use of indirection
120 'br\}
121                         if (/^#include "(.*)"/) {
122                                 do process($1, $input);
123                                 next;
124                         }
125                         .\|.\|.         # whatever
126                 }
127         }
128
129 .fi
130 You may also, in the Bourne shell tradition, specify an EXPR beginning
131 with \*(L">&\*(R", in which case the rest of the string
132 is interpreted as the name of a filehandle
133 (or file descriptor, if numeric) which is to be duped and opened.
134 You may use & after >, >>, <, +>, +>> and +<.
135 The mode you specify should match the mode of the original filehandle.
136 Here is a script that saves, redirects, and restores
137 .I STDOUT
138 and
139 .IR STDERR :
140 .nf
141
142 .ne 21
143         #!/usr/bin/perl
144         open(SAVEOUT, ">&STDOUT");
145         open(SAVEERR, ">&STDERR");
146
147         open(STDOUT, ">foo.out") || die "Can't redirect stdout";
148         open(STDERR, ">&STDOUT") || die "Can't dup stdout";
149
150         select(STDERR); $| = 1;         # make unbuffered
151         select(STDOUT); $| = 1;         # make unbuffered
152
153         print STDOUT "stdout 1\en";     # this works for
154         print STDERR "stderr 1\en";     # subprocesses too
155
156         close(STDOUT);
157         close(STDERR);
158
159         open(STDOUT, ">&SAVEOUT");
160         open(STDERR, ">&SAVEERR");
161
162         print STDOUT "stdout 2\en";
163         print STDERR "stderr 2\en";
164
165 .fi
166 If you open a pipe on the command \*(L"\-\*(R", i.e. either \*(L"|\-\*(R" or \*(L"\-|\*(R",
167 then there is an implicit fork done, and the return value of open
168 is the pid of the child within the parent process, and 0 within the child
169 process.
170 (Use defined($pid) to determine if the open was successful.)
171 The filehandle behaves normally for the parent, but i/o to that
172 filehandle is piped from/to the
173 .IR STDOUT / STDIN
174 of the child process.
175 In the child process the filehandle isn't opened\*(--i/o happens from/to
176 the new
177 .I STDOUT
178 or
179 .IR STDIN .
180 Typically this is used like the normal piped open when you want to exercise
181 more control over just how the pipe command gets executed, such as when
182 you are running setuid, and don't want to have to scan shell commands
183 for metacharacters.
184 The following pairs are equivalent:
185 .nf
186
187 .ne 5
188         open(FOO, "|tr \'[a\-z]\' \'[A\-Z]\'");
189         open(FOO, "|\-") || exec \'tr\', \'[a\-z]\', \'[A\-Z]\';
190
191         open(FOO, "cat \-n $file|");
192         open(FOO, "\-|") || exec \'cat\', \'\-n\', $file;
193
194 .fi
195 Explicitly closing any piped filehandle causes the parent process to wait for the
196 child to finish, and returns the status value in $?.
197 .Ip "opendir(DIRHANDLE,EXPR)" 8 3
198 Opens a directory named EXPR for processing by readdir(), telldir(), seekdir(),
199 rewinddir() and closedir().
200 Returns true if successful.
201 DIRHANDLEs have their own namespace separate from FILEHANDLEs.
202 .Ip "ord(EXPR)" 8 4
203 .Ip "ord EXPR" 8
204 Returns the ascii value of the first character of EXPR.
205 If EXPR is omitted, uses $_.
206 .Ip "pack(TEMPLATE,LIST)" 8 4
207 Takes an array or list of values and packs it into a binary structure,
208 returning the string containing the structure.
209 The TEMPLATE is a sequence of characters that give the order and type
210 of values, as follows:
211 .nf
212
213         A       An ascii string, will be space padded.
214         a       An ascii string, will be null padded.
215         c       A native char value.
216         C       An unsigned char value.
217         s       A signed short value.
218         S       An unsigned short value.
219         i       A signed integer value.
220         I       An unsigned integer value.
221         l       A signed long value.
222         L       An unsigned long value.
223         n       A short in \*(L"network\*(R" order.
224         N       A long in \*(L"network\*(R" order.
225         p       A pointer to a string.
226         x       A null byte.
227
228 .fi
229 Each letter may optionally be followed by a number which gives a repeat
230 count.
231 With all types except "a" and "A" the pack function will gobble up that many values
232 from the LIST.
233 The "a" and "A" types gobble just one value, but pack it as a string that long,
234 padding with nulls or spaces as necessary.
235 (When unpacking, "A" strips trailing spaces and nulls, but "a" does not.)
236 Examples:
237 .nf
238
239         $foo = pack("cccc",65,66,67,68);
240         # foo eq "ABCD"
241         $foo = pack("c4",65,66,67,68);
242         # same thing
243
244         $foo = pack("ccxxcc",65,66,67,68);
245         # foo eq "AB\e0\e0CD"
246
247         $foo = pack("s2",1,2);
248         # "\e1\e0\e2\e0" on little-endian
249         # "\e0\e1\e0\e2" on big-endian
250
251         $foo = pack("a4","abcd","x","y","z");
252         # "abcd"
253
254         $foo = pack("aaaa","abcd","x","y","z");
255         # "axyz"
256
257         $foo = pack("a14","abcdefg");
258         # "abcdefg\e0\e0\e0\e0\e0\e0\e0"
259
260         $foo = pack("i9pl", gmtime);
261         # a real struct tm (on my system anyway)
262
263 .fi
264 The same template may generally also be used in the unpack function.
265 .Ip "pop(ARRAY)" 8
266 .Ip "pop ARRAY" 8 6
267 Pops and returns the last value of the array, shortening the array by 1.
268 Has the same effect as
269 .nf
270
271         $tmp = $ARRAY[$#ARRAY\-\|\-];
272
273 .fi
274 If there are no elements in the array, returns the undefined value.
275 .Ip "print(FILEHANDLE LIST)" 8 10
276 .Ip "print(LIST)" 8
277 .Ip "print FILEHANDLE LIST" 8
278 .Ip "print LIST" 8
279 .Ip "print" 8
280 Prints a string or a comma-separated list of strings.
281 Returns non-zero if successful.
282 FILEHANDLE may be a scalar variable name, in which case the variable contains
283 the name of the filehandle, thus introducing one level of indirection.
284 If FILEHANDLE is omitted, prints by default to standard output (or to the
285 last selected output channel\*(--see select()).
286 If LIST is also omitted, prints $_ to
287 .IR STDOUT .
288 To set the default output channel to something other than
289 .I STDOUT
290 use the select operation.
291 .Ip "printf(FILEHANDLE LIST)" 8 10
292 .Ip "printf(LIST)" 8
293 .Ip "printf FILEHANDLE LIST" 8
294 .Ip "printf LIST" 8
295 Equivalent to a \*(L"print FILEHANDLE sprintf(LIST)\*(R".
296 .Ip "push(ARRAY,LIST)" 8 7
297 Treats ARRAY (@ is optional) as a stack, and pushes the values of LIST
298 onto the end of ARRAY.
299 The length of ARRAY increases by the length of LIST.
300 Has the same effect as
301 .nf
302
303     for $value (LIST) {
304             $ARRAY[++$#ARRAY] = $value;
305     }
306
307 .fi
308 but is more efficient.
309 .Ip "q/STRING/" 8 5
310 .Ip "qq/STRING/" 8
311 These are not really functions, but simply syntactic sugar to let you
312 avoid putting too many backslashes into quoted strings.
313 The q operator is a generalized single quote, and the qq operator a
314 generalized double quote.
315 Any delimiter can be used in place of /, including newline.
316 If the delimiter is an opening bracket or parenthesis, the final delimiter
317 will be the corresponding closing bracket or parenthesis.
318 (Embedded occurrences of the closing bracket need to be backslashed as usual.)
319 Examples:
320 .nf
321
322 .ne 5
323         $foo = q!I said, "You said, \'She said it.\'"!;
324         $bar = q(\'This is it.\');
325         $_ .= qq
326 *** The previous line contains the naughty word "$&".\en
327                 if /(ibm|apple|awk)/;      # :-)
328
329 .fi
330 .Ip "rand(EXPR)" 8 8
331 .Ip "rand EXPR" 8
332 .Ip "rand" 8
333 Returns a random fractional number between 0 and the value of EXPR.
334 (EXPR should be positive.)
335 If EXPR is omitted, returns a value between 0 and 1.
336 See also srand().
337 .Ip "read(FILEHANDLE,SCALAR,LENGTH)" 8 5
338 Attempts to read LENGTH bytes of data into variable SCALAR from the specified
339 FILEHANDLE.
340 Returns the number of bytes actually read.
341 SCALAR will be grown or shrunk to the length actually read.
342 .Ip "readdir(DIRHANDLE)" 8 3
343 .Ip "readdir DIRHANDLE" 8
344 Returns the next directory entry for a directory opened by opendir().
345 If used in an array context, returns all the rest of the entries in the
346 directory.
347 If there are no more entries, returns an undefined value in a scalar context
348 or a null list in an array context.
349 .Ip "readlink(EXPR)" 8 6
350 .Ip "readlink EXPR" 8
351 Returns the value of a symbolic link, if symbolic links are implemented.
352 If not, gives a fatal error.
353 If there is some system error, returns the undefined value and sets $! (errno).
354 If EXPR is omitted, uses $_.
355 .Ip "recv(SOCKET,SCALAR,LEN,FLAGS)" 8 4
356 Receives a message on a socket.
357 Attempts to receive LENGTH bytes of data into variable SCALAR from the specified
358 SOCKET filehandle.
359 Returns the address of the sender, or the undefined value if there's an error.
360 SCALAR will be grown or shrunk to the length actually read.
361 Takes the same flags as the system call of the same name.
362 .Ip "redo LABEL" 8 8
363 .Ip "redo" 8
364 The
365 .I redo
366 command restarts the loop block without evaluating the conditional again.
367 The
368 .I continue
369 block, if any, is not executed.
370 If the LABEL is omitted, the command refers to the innermost enclosing loop.
371 This command is normally used by programs that want to lie to themselves
372 about what was just input:
373 .nf
374
375 .ne 16
376         # a simpleminded Pascal comment stripper
377         # (warning: assumes no { or } in strings)
378         line: while (<STDIN>) {
379                 while (s|\|({.*}.*\|){.*}|$1 \||) {}
380                 s|{.*}| \||;
381                 if (s|{.*| \||) {
382                         $front = $_;
383                         while (<STDIN>) {
384                                 if (\|/\|}/\|) {        # end of comment?
385                                         s|^|$front{|;
386                                         redo line;
387                                 }
388                         }
389                 }
390                 print;
391         }
392
393 .fi
394 .Ip "rename(OLDNAME,NEWNAME)" 8 2
395 Changes the name of a file.
396 Returns 1 for success, 0 otherwise.
397 Will not work across filesystem boundaries.
398 .Ip "reset(EXPR)" 8 6
399 .Ip "reset EXPR" 8
400 .Ip "reset" 8
401 Generally used in a
402 .I continue
403 block at the end of a loop to clear variables and reset ?? searches
404 so that they work again.
405 The expression is interpreted as a list of single characters (hyphens allowed
406 for ranges).
407 All variables and arrays beginning with one of those letters are reset to
408 their pristine state.
409 If the expression is omitted, one-match searches (?pattern?) are reset to
410 match again.
411 Only resets variables or searches in the current package.
412 Always returns 1.
413 Examples:
414 .nf
415
416 .ne 3
417     reset \'X\';        \h'|2i'# reset all X variables
418     reset \'a\-z\';\h'|2i'# reset lower case variables
419     reset;      \h'|2i'# just reset ?? searches
420
421 .fi
422 Note: resetting \*(L"A\-Z\*(R" is not recommended since you'll wipe out your ARGV and ENV
423 arrays.
424 .Sp
425 The use of reset on dbm associative arrays does not change the dbm file.
426 (It does, however, flush any entries cached by perl, which may be useful if
427 you are sharing the dbm file.
428 Then again, maybe not.)
429 .Ip "return LIST" 8 3
430 Returns from a subroutine with the value specified.
431 (Note that a subroutine can automatically return
432 the value of the last expression evaluated.
433 That's the preferred method\*(--use of an explicit
434 .I return
435 is a bit slower.)
436 .Ip "reverse(LIST)" 8 4
437 .Ip "reverse LIST" 8
438 Returns an array value consisting of the elements of LIST in the opposite order.
439 .Ip "rewinddir(DIRHANDLE)" 8 5
440 .Ip "rewinddir DIRHANDLE" 8
441 Sets the current position to the beginning of the directory for the readdir() routine on DIRHANDLE.
442 .Ip "rindex(STR,SUBSTR)" 8 4
443 Works just like index except that it
444 returns the position of the LAST occurrence of SUBSTR in STR.
445 .Ip "rmdir(FILENAME)" 8 4
446 .Ip "rmdir FILENAME" 8
447 Deletes the directory specified by FILENAME if it is empty.
448 If it succeeds it returns 1, otherwise it returns 0 and sets $! (errno).
449 If FILENAME is omitted, uses $_.
450 .Ip "s/PATTERN/REPLACEMENT/gieo" 8 3
451 Searches a string for a pattern, and if found, replaces that pattern with the
452 replacement text and returns the number of substitutions made.
453 Otherwise it returns false (0).
454 The \*(L"g\*(R" is optional, and if present, indicates that all occurrences
455 of the pattern are to be replaced.
456 The \*(L"i\*(R" is also optional, and if present, indicates that matching
457 is to be done in a case-insensitive manner.
458 The \*(L"e\*(R" is likewise optional, and if present, indicates that
459 the replacement string is to be evaluated as an expression rather than just
460 as a double-quoted string.
461 Any delimiter may replace the slashes; if single quotes are used, no
462 interpretation is done on the replacement string (the e modifier overrides
463 this, however).
464 If no string is specified via the =~ or !~ operator,
465 the $_ string is searched and modified.
466 (The string specified with =~ must be a scalar variable, an array element,
467 or an assignment to one of those, i.e. an lvalue.)
468 If the pattern contains a $ that looks like a variable rather than an
469 end-of-string test, the variable will be interpolated into the pattern at
470 run-time.
471 If you only want the pattern compiled once the first time the variable is
472 interpolated, add an \*(L"o\*(R" at the end.
473 See also the section on regular expressions.
474 Examples:
475 .nf
476
477     s/\|\e\|bgreen\e\|b/mauve/g;                # don't change wintergreen
478
479     $path \|=~ \|s|\|/usr/bin|\|/usr/local/bin|;
480
481     s/Login: $foo/Login: $bar/; # run-time pattern
482
483     ($foo = $bar) =~ s/bar/foo/;
484
485     $_ = \'abc123xyz\';
486     s/\ed+/$&*2/e;              # yields \*(L'abc246xyz\*(R'
487     s/\ed+/sprintf("%5d",$&)/e; # yields \*(L'abc  246xyz\*(R'
488     s/\ew/$& x 2/eg;            # yields \*(L'aabbcc  224466xxyyzz\*(R'
489
490     s/\|([^ \|]*\|) *\|([^ \|]*\|)\|/\|$2 $1/;  # reverse 1st two fields
491
492 .fi
493 (Note the use of $ instead of \|\e\| in the last example.  See section
494 on regular expressions.)
495 .Ip "seek(FILEHANDLE,POSITION,WHENCE)" 8 3
496 Randomly positions the file pointer for FILEHANDLE, just like the fseek()
497 call of stdio.
498 FILEHANDLE may be an expression whose value gives the name of the filehandle.
499 Returns 1 upon success, 0 otherwise.
500 .Ip "seekdir(DIRHANDLE,POS)" 8 3
501 Sets the current position for the readdir() routine on DIRHANDLE.
502 POS must be a value returned by seekdir().
503 Has the same caveats about possible directory compaction as the corresponding
504 system library routine.
505 .Ip "select(FILEHANDLE)" 8 3
506 .Ip "select" 8 3
507 Returns the currently selected filehandle.
508 Sets the current default filehandle for output, if FILEHANDLE is supplied.
509 This has two effects: first, a
510 .I write
511 or a
512 .I print
513 without a filehandle will default to this FILEHANDLE.
514 Second, references to variables related to output will refer to this output
515 channel.
516 For example, if you have to set the top of form format for more than
517 one output channel, you might do the following:
518 .nf
519
520 .ne 4
521         select(REPORT1);
522         $^ = \'report1_top\';
523         select(REPORT2);
524         $^ = \'report2_top\';
525
526 .fi
527 FILEHANDLE may be an expression whose value gives the name of the actual filehandle.
528 Thus:
529 .nf
530
531         $oldfh = select(STDERR); $| = 1; select($oldfh);
532
533 .fi
534 .Ip "select(RBITS,WBITS,EBITS,TIMEOUT)" 8 3
535 This calls the select system call with the bitmasks specified, which can
536 be constructed using fileno() and vec(), along these lines:
537 .nf
538
539         $rin = $win = $ein = '';
540         vec($rin,fileno(STDIN),1) = 1;
541         vec($win,fileno(STDOUT),1) = 1;
542         $ein = $rin | $win;
543
544 .fi
545 If you want to select on many filehandles you might wish to write a subroutine:
546 .nf
547
548         sub fhbits {
549             local(@fhlist) = split(' ',$_[0]);
550             local($bits);
551             for (@fhlist) {
552                 vec($bits,fileno($_),1) = 1;
553             }
554             $bits;
555         }
556         $rin = &fhbits('STDIN TTY SOCK');
557
558 .fi
559 The usual idiom is:
560 .nf
561
562         ($nfound,$timeleft) =
563           select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
564
565 or to block until something becomes ready:
566
567 .ie t \{\
568         $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
569 'br\}
570 .el \{\
571         $nfound = select($rout=$rin, $wout=$win,
572                                 $eout=$ein, undef);
573 'br\}
574
575 .fi
576 Any of the bitmasks can also be undef.
577 The timeout, if specified, is in seconds, which may be fractional.
578 .Ip "setpgrp(PID,PGRP)" 8 4
579 Sets the current process group for the specified PID, 0 for the current
580 process.
581 Will produce a fatal error if used on a machine that doesn't implement
582 setpgrp(2).
583 .Ip "send(SOCKET,MSG,FLAGS,TO)" 8 4
584 .Ip "send(SOCKET,MSG,FLAGS)" 8
585 Sends a message on a socket.
586 Takes the same flags as the system call of the same name.
587 On unconnected sockets you must specify a destination to send TO.
588 Returns the number of characters sent, or the undefined value if
589 there is an error.
590 .Ip "setpriority(WHICH,WHO,PRIORITY)" 8 4
591 Sets the current priority for a process, a process group, or a user.
592 (See setpriority(2).)
593 Will produce a fatal error if used on a machine that doesn't implement
594 setpriority(2).
595 .Ip "setsockopt(SOCKET,LEVEL,OPTNAME,OPTVAL)" 8 3
596 Sets the socket option requested.
597 Returns undefined if there is an error.
598 OPTVAL may be specified as undef if you don't want to pass an argument.
599 .Ip "shift(ARRAY)" 8 6
600 .Ip "shift ARRAY" 8
601 .Ip "shift" 8
602 Shifts the first value of the array off and returns it,
603 shortening the array by 1 and moving everything down.
604 If there are no elements in the array, returns the undefined value.
605 If ARRAY is omitted, shifts the @ARGV array in the main program, and the @_
606 array in subroutines.
607 See also unshift(), push() and pop().
608 Shift() and unshift() do the same thing to the left end of an array that push()
609 and pop() do to the right end.
610 .Ip "shutdown(SOCKET,HOW)" 8 3
611 Shuts down a socket connection in the manner indicated by HOW, which has
612 the same interpretation as in the system call of the same name.
613 .Ip "sin(EXPR)" 8 4
614 .Ip "sin EXPR" 8
615 Returns the sine of EXPR (expressed in radians).
616 If EXPR is omitted, returns sine of $_.
617 .Ip "sleep(EXPR)" 8 6
618 .Ip "sleep EXPR" 8
619 .Ip "sleep" 8
620 Causes the script to sleep for EXPR seconds, or forever if no EXPR.
621 May be interrupted by sending the process a SIGALARM.
622 Returns the number of seconds actually slept.
623 .Ip "socket(SOCKET,DOMAIN,TYPE,PROTOCOL)" 8 3
624 Opens a socket of the specified kind and attaches it to filehandle SOCKET.
625 DOMAIN, TYPE and PROTOCOL are specified the same as for the system call
626 of the same name.
627 You may need to run makelib on sys/socket.h to get the proper values handy
628 in a perl library file.
629 Return true if successful.
630 See the example in the section on Interprocess Communication.
631 .Ip "socketpair(SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL)" 8 3
632 Creates an unnamed pair of sockets in the specified domain, of the specified
633 type.
634 DOMAIN, TYPE and PROTOCOL are specified the same as for the system call
635 of the same name.
636 If unimplemented, yields a fatal error.
637 Return true if successful.
638 .Ip "sort(SUBROUTINE LIST)" 8 9
639 .Ip "sort(LIST)" 8
640 .Ip "sort SUBROUTINE LIST" 8
641 .Ip "sort LIST" 8
642 Sorts the LIST and returns the sorted array value.
643 Nonexistent values of arrays are stripped out.
644 If SUBROUTINE is omitted, sorts in standard string comparison order.
645 If SUBROUTINE is specified, gives the name of a subroutine that returns
646 an integer less than, equal to, or greater than 0,
647 depending on how the elements of the array are to be ordered.
648 In the interests of efficiency the normal calling code for subroutines
649 is bypassed, with the following effects: the subroutine may not be a recursive
650 subroutine, and the two elements to be compared are passed into the subroutine
651 not via @_ but as $a and $b (see example below).
652 They are passed by reference so don't modify $a and $b.
653 SUBROUTINE may be a scalar variable name, in which case the value provides
654 the name of the subroutine to use.
655 Examples:
656 .nf
657
658 .ne 4
659         sub byage {
660             $age{$a} - $age{$b};        # presuming integers
661         }
662         @sortedclass = sort byage @class;
663
664 .ne 9
665         sub reverse { $a lt $b ? 1 : $a gt $b ? \-1 : 0; }
666         @harry = (\'dog\',\'cat\',\'x\',\'Cain\',\'Abel\');
667         @george = (\'gone\',\'chased\',\'yz\',\'Punished\',\'Axed\');
668         print sort @harry;
669                 # prints AbelCaincatdogx
670         print sort reverse @harry;
671                 # prints xdogcatCainAbel
672         print sort @george, \'to\', @harry;
673                 # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
674
675 .fi
676 .Ip "split(/PATTERN/,EXPR,LIMIT)" 8 8
677 .Ip "split(/PATTERN/,EXPR)" 8 8
678 .Ip "split(/PATTERN/)" 8
679 .Ip "split" 8
680 Splits a string into an array of strings, and returns it.
681 (If not in an array context, returns the number of fields found and splits
682 into the @_ array.)
683 If EXPR is omitted, splits the $_ string.
684 If PATTERN is also omitted, splits on whitespace (/[\ \et\en]+/).
685 Anything matching PATTERN is taken to be a delimiter separating the fields.
686 (Note that the delimiter may be longer than one character.)
687 If LIMIT is specified, splits into no more than that many fields (though it
688 may split into fewer).
689 If LIMIT is unspecified, trailing null fields are stripped (which
690 potential users of pop() would do well to remember).
691 A pattern matching the null string (not to be confused with a null pattern,
692 which is one member of the set of patterns matching a null string)
693 will split the value of EXPR into separate characters at each point it
694 matches that way.
695 For example:
696 .nf
697
698         print join(\':\', split(/ */, \'hi there\'));
699
700 .fi
701 produces the output \*(L'h:i:t:h:e:r:e\*(R'.
702 .P
703 The NUM parameter can be used to partially split a line
704 .nf
705
706         ($login, $passwd, $remainder) = split(\|/\|:\|/\|, $_, 3);
707
708 .fi
709 (When assigning to a list, if NUM is omitted, perl supplies a NUM one
710 larger than the number of variables in the list, to avoid unnecessary work.
711 For the list above NUM would have been 4 by default.
712 In time critical applications it behooves you not to split into
713 more fields than you really need.)
714 .Sp
715 If the PATTERN contains parentheses, additional array elements are created
716 from each matching substring in the delimiter.
717 .Sp
718         split(/([,-])/,"1-10,20");
719 .Sp
720 produces the array value
721 .Sp
722         (1,'-',10,',',20)
723 .Sp
724 The pattern /PATTERN/ may be replaced with an expression to specify patterns
725 that vary at runtime.
726 (To do runtime compilation only once, use /$variable/o.)
727 As a special case, specifying a space (\'\ \') will split on white space
728 just as split with no arguments does, but leading white space does NOT
729 produce a null first field.
730 Thus, split(\'\ \') can be used to emulate
731 .IR awk 's
732 default behavior, whereas
733 split(/\ /) will give you as many null initial fields as there are
734 leading spaces.
735 .Sp
736 Example:
737 .nf
738
739 .ne 5
740         open(passwd, \'/etc/passwd\');
741         while (<passwd>) {
742 .ie t \{\
743                 ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(\|/\|:\|/\|);
744 'br\}
745 .el \{\
746                 ($login, $passwd, $uid, $gid, $gcos, $home, $shell)
747                         = split(\|/\|:\|/\|);
748 'br\}
749                 .\|.\|.
750         }
751
752 .fi
753 (Note that $shell above will still have a newline on it.  See chop().)
754 See also
755 .IR join .
756 .Ip "sprintf(FORMAT,LIST)" 8 4
757 Returns a string formatted by the usual printf conventions.
758 The * character is not supported.
759 .Ip "sqrt(EXPR)" 8 4
760 .Ip "sqrt EXPR" 8
761 Return the square root of EXPR.
762 If EXPR is omitted, returns square root of $_.
763 .Ip "srand(EXPR)" 8 4
764 .Ip "srand EXPR" 8
765 Sets the random number seed for the
766 .I rand
767 operator.
768 If EXPR is omitted, does srand(time).
769 .Ip "stat(FILEHANDLE)" 8 8
770 .Ip "stat FILEHANDLE" 8
771 .Ip "stat(EXPR)" 8
772 .Ip "stat SCALARVARIABLE" 8
773 Returns a 13-element array giving the statistics for a file, either the file
774 opened via FILEHANDLE, or named by EXPR.
775 Typically used as follows:
776 .nf
777
778 .ne 3
779     ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
780        $atime,$mtime,$ctime,$blksize,$blocks)
781            = stat($filename);
782
783 .fi
784 If stat is passed the special filehandle consisting of an underline,
785 no stat is done, but the current contents of the stat structure from
786 the last stat or filetest are returned.
787 Example:
788 .nf
789
790 .ne 3
791         if (-x $file && (($d) = stat(_)) && $d < 0) {
792                 print "$file is executable NFS file\en";
793         }
794
795 .fi
796 .Ip "study(SCALAR)" 8 6
797 .Ip "study SCALAR" 8
798 .Ip "study"
799 Takes extra time to study SCALAR ($_ if unspecified) in anticipation of
800 doing many pattern matches on the string before it is next modified.
801 This may or may not save time, depending on the nature and number of patterns
802 you are searching on, and on the distribution of character frequencies in
803 the string to be searched\*(--you probably want to compare runtimes with and
804 without it to see which runs faster.
805 Those loops which scan for many short constant strings (including the constant
806 parts of more complex patterns) will benefit most.
807 You may have only one study active at a time\*(--if you study a different
808 scalar the first is \*(L"unstudied\*(R".
809 (The way study works is this: a linked list of every character in the string
810 to be searched is made, so we know, for example, where all the \*(L'k\*(R' characters
811 are.
812 From each search string, the rarest character is selected, based on some
813 static frequency tables constructed from some C programs and English text.
814 Only those places that contain this \*(L"rarest\*(R" character are examined.)
815 .Sp
816 For example, here is a loop which inserts index producing entries before any line
817 containing a certain pattern:
818 .nf
819
820 .ne 8
821         while (<>) {
822                 study;
823                 print ".IX foo\en" if /\ebfoo\eb/;
824                 print ".IX bar\en" if /\ebbar\eb/;
825                 print ".IX blurfl\en" if /\ebblurfl\eb/;
826                 .\|.\|.
827                 print;
828         }
829
830 .fi
831 In searching for /\ebfoo\eb/, only those locations in $_ that contain \*(L'f\*(R'
832 will be looked at, because \*(L'f\*(R' is rarer than \*(L'o\*(R'.
833 In general, this is a big win except in pathological cases.
834 The only question is whether it saves you more time than it took to build
835 the linked list in the first place.
836 .Sp
837 Note that if you have to look for strings that you don't know till runtime,
838 you can build an entire loop as a string and eval that to avoid recompiling
839 all your patterns all the time.
840 Together with setting $/ to input entire files as one record, this can
841 be very fast, often faster than specialized programs like fgrep.
842 The following scans a list of files (@files)
843 for a list of words (@words), and prints out the names of those files that
844 contain a match:
845 .nf
846
847 .ne 12
848         $search = \'while (<>) { study;\';
849         foreach $word (@words) {
850             $search .= "++\e$seen{\e$ARGV} if /\eb$word\eb/;\en";
851         }
852         $search .= "}";
853         @ARGV = @files;
854         $/ = "\e177";           # something that doesn't occur
855         eval $search;           # this screams
856         $/ = "\en";             # put back to normal input delim
857         foreach $file (sort keys(%seen)) {
858             print $file, "\en";
859         }
860
861 .fi
862 .Ip "substr(EXPR,OFFSET,LEN)" 8 2
863 Extracts a substring out of EXPR and returns it.
864 First character is at offset 0, or whatever you've set $[ to.
865 If OFFSET is negative, starts that far from the end of the string.
866 You can use the substr() function as an lvalue, in which case EXPR must
867 be an lvalue.
868 If you assign something shorter than LEN, the string will shrink, and
869 if you assign something longer than LEN, the string will grow to accommodate it.
870 To keep the string the same length you may need to pad or chop your value using
871 sprintf().
872 .Ip "syscall(LIST)" 8 6
873 .Ip "syscall LIST" 8
874 Calls the system call specified as the first element of the list, passing
875 the remaining elements as arguments to the system call.
876 If unimplemented, produces a fatal error.
877 The arguments are interpreted as follows: if a given argument is numeric,
878 the argument is passed as an int.
879 If not, the pointer to the string value is passed.
880 You are responsible to make sure a string is pre-extended long enough
881 to receive any result that might be written into a string.
882 If your integer arguments are not literals and have never been interpreted
883 in a numeric context, you may need to add 0 to them to force them to look
884 like numbers.
885 .nf
886
887         do 'syscall.h';         # may need to run makelib
888         syscall(&SYS_write, fileno(STDOUT), "hi there\en", 9);
889
890 .fi
891 .Ip "system(LIST)" 8 6
892 .Ip "system LIST" 8
893 Does exactly the same thing as \*(L"exec LIST\*(R" except that a fork
894 is done first, and the parent process waits for the child process to complete.
895 Note that argument processing varies depending on the number of arguments.
896 The return value is the exit status of the program as returned by the wait()
897 call.
898 To get the actual exit value divide by 256.
899 See also
900 .IR exec .
901 .Ip "symlink(OLDFILE,NEWFILE)" 8 2
902 Creates a new filename symbolically linked to the old filename.
903 Returns 1 for success, 0 otherwise.
904 On systems that don't support symbolic links, produces a fatal error at
905 run time.
906 To check for that, use eval:
907 .nf
908
909         $symlink_exists = (eval \'symlink("","");\', $@ eq \'\');
910
911 .fi
912 .Ip "tell(FILEHANDLE)" 8 6
913 .Ip "tell FILEHANDLE" 8 6
914 .Ip "tell" 8
915 Returns the current file position for FILEHANDLE.
916 FILEHANDLE may be an expression whose value gives the name of the actual
917 filehandle.
918 If FILEHANDLE is omitted, assumes the file last read.
919 .Ip "telldir(DIRHANDLE)" 8 5
920 .Ip "telldir DIRHANDLE" 8
921 Returns the current position of the readdir() routines on DIRHANDLE.
922 Value may be given to seekdir() to access a particular location in
923 a directory.
924 Has the same caveats about possible directory compaction as the corresponding
925 system library routine.
926 .Ip "time" 8 4
927 Returns the number of non-leap seconds since January 1, 1970, UTC.
928 Suitable for feeding to gmtime() and localtime().
929 .Ip "times" 8 4
930 Returns a four-element array giving the user and system times, in seconds, for this
931 process and the children of this process.
932 .Sp
933     ($user,$system,$cuser,$csystem) = times;
934 .Sp
935 .Ip "tr/SEARCHLIST/REPLACEMENTLIST/" 8 5
936 .Ip "y/SEARCHLIST/REPLACEMENTLIST/" 8
937 Translates all occurrences of the characters found in the search list with
938 the corresponding character in the replacement list.
939 It returns the number of characters replaced.
940 If no string is specified via the =~ or !~ operator,
941 the $_ string is translated.
942 (The string specified with =~ must be a scalar variable, an array element,
943 or an assignment to one of those, i.e. an lvalue.)
944 For
945 .I sed
946 devotees,
947 .I y
948 is provided as a synonym for
949 .IR tr .
950 Examples:
951 .nf
952
953     $ARGV[1] \|=~ \|y/A\-Z/a\-z/;       \h'|3i'# canonicalize to lower case
954
955     $cnt = tr/*/*/;             \h'|3i'# count the stars in $_
956
957     ($HOST = $host) =~ tr/a\-z/A\-Z/;
958
959     y/\e001\-@[\-_{\-\e177/ /;  \h'|3i'# change non-alphas to space
960
961 .fi
962 .Ip "umask(EXPR)" 8 4
963 .Ip "umask EXPR" 8
964 .Ip "umask" 8
965 Sets the umask for the process and returns the old one.
966 If EXPR is omitted, merely returns current umask.
967 .Ip "undef(EXPR)" 8 6
968 .Ip "undef EXPR" 8
969 .Ip "undef" 8
970 Undefines the value of EXPR, which must be an lvalue.
971 Use only on a scalar value, an entire array, or a subroutine name (using &).
972 (Undef will probably not do what you expect on most predefined variables or
973 dbm array values.)
974 Always returns the undefined value.
975 You can omit the EXPR, in which case nothing is undefined, but you still
976 get an undefined value that you could, for instance, return from a subroutine.
977 Examples:
978 .nf
979
980 .ne 6
981         undef $foo;
982         undef $bar{'blurfl'};
983         undef @ary;
984         undef %assoc;
985         undef &mysub;
986         return (wantarray ? () : undef) if $they_blew_it;
987
988 .fi
989 .Ip "unlink(LIST)" 8 4
990 .Ip "unlink LIST" 8
991 Deletes a list of files.
992 Returns the number of files successfully deleted.
993 .nf
994
995 .ne 2
996         $cnt = unlink \'a\', \'b\', \'c\';
997         unlink @goners;
998         unlink <*.bak>;
999
1000 .fi
1001 Note: unlink will not delete directories unless you are superuser and the
1002 .B \-U
1003 flag is supplied to
1004 .IR perl .
1005 Even if these conditions are met, be warned that unlinking a directory
1006 can inflict damage on your filesystem.
1007 Use rmdir instead.
1008 .Ip "unpack(TEMPLATE,EXPR)" 8 4
1009 Unpack does the reverse of pack: it takes a string representing
1010 a structure and expands it out into an array value, returning the array
1011 value.
1012 The TEMPLATE has the same format as in the pack function.
1013 Here's a subroutine that does substring:
1014 .nf
1015
1016 .ne 4
1017         sub substr {
1018                 local($what,$where,$howmuch) = @_;
1019                 unpack("x$where a$howmuch", $what);
1020         }
1021
1022 .ne 3
1023 and then there's
1024
1025         sub ord { unpack("c",$_[0]); }
1026
1027 .fi
1028 .Ip "unshift(ARRAY,LIST)" 8 4
1029 Does the opposite of a
1030 .IR shift .
1031 Or the opposite of a
1032 .IR push ,
1033 depending on how you look at it.
1034 Prepends list to the front of the array, and returns the number of elements
1035 in the new array.
1036 .nf
1037
1038         unshift(ARGV, \'\-e\') unless $ARGV[0] =~ /^\-/;
1039
1040 .fi
1041 .Ip "utime(LIST)" 8 2
1042 .Ip "utime LIST" 8 2
1043 Changes the access and modification times on each file of a list of files.
1044 The first two elements of the list must be the NUMERICAL access and
1045 modification times, in that order.
1046 Returns the number of files successfully changed.
1047 The inode modification time of each file is set to the current time.
1048 Example of a \*(L"touch\*(R" command:
1049 .nf
1050
1051 .ne 3
1052         #!/usr/bin/perl
1053         $now = time;
1054         utime $now, $now, @ARGV;
1055
1056 .fi
1057 .Ip "values(ASSOC_ARRAY)" 8 6
1058 .Ip "values ASSOC_ARRAY" 8
1059 Returns a normal array consisting of all the values of the named associative
1060 array.
1061 The values are returned in an apparently random order, but it is the same order
1062 as either the keys() or each() function would produce on the same array.
1063 See also keys() and each().
1064 .Ip "vec(EXPR,OFFSET,BITS)" 8 2
1065 Treats a string as a vector of unsigned integers, and returns the value
1066 of the bitfield specified.
1067 May also be assigned to.
1068 BITS must be a power of two from 1 to 32.
1069 .Sp
1070 Vectors created with vec() can also be manipulated with the logical operators
1071 |, & and ^,
1072 which will assume a bit vector operation is desired when both operands are
1073 strings.
1074 This interpretation is not enabled unless there is at least one vec() in
1075 your program, to protect older programs.
1076 .Ip "wait" 8 6
1077 Waits for a child process to terminate and returns the pid of the deceased
1078 process, or -1 if there are no child processes.
1079 The status is returned in $?.
1080 If you expected a child and didn't find it, you probably had a call to
1081 system, a close on a pipe, or backticks between the fork and the wait.
1082 These constructs also do a wait and may have harvested your child process.
1083 .Ip "wantarray" 8 4
1084 Returns true if the context of the currently executing subroutine
1085 is looking for an array value.
1086 Returns false if the context is looking for a scalar.
1087 .nf
1088
1089         return wantarray ? () : undef;
1090
1091 .fi
1092 .Ip "warn(LIST)" 8 4
1093 .Ip "warn LIST" 8
1094 Produces a message on STDERR just like \*(L"die\*(R", but doesn't exit.
1095 .Ip "write(FILEHANDLE)" 8 6
1096 .Ip "write(EXPR)" 8
1097 .Ip "write" 8
1098 Writes a formatted record (possibly multi-line) to the specified file,
1099 using the format associated with that file.
1100 By default the format for a file is the one having the same name is the
1101 filehandle, but the format for the current output channel (see
1102 .IR select )
1103 may be set explicitly
1104 by assigning the name of the format to the $~ variable.
1105 .Sp
1106 Top of form processing is handled automatically:
1107 if there is insufficient room on the current page for the formatted 
1108 record, the page is advanced, a special top-of-page format is used
1109 to format the new page header, and then the record is written.
1110 By default the top-of-page format is \*(L"top\*(R", but it
1111 may be set to the
1112 format of your choice by assigning the name to the $^ variable.
1113 .Sp
1114 If FILEHANDLE is unspecified, output goes to the current default output channel,
1115 which starts out as
1116 .I STDOUT
1117 but may be changed by the
1118 .I select
1119 operator.
1120 If the FILEHANDLE is an EXPR, then the expression is evaluated and the
1121 resulting string is used to look up the name of the FILEHANDLE at run time.
1122 For more on formats, see the section on formats later on.
1123 .Sp
1124 Note that write is NOT the opposite of read.