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