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