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