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