1 ''' Beginning of part 3
2 ''' $Header: perl.man.3,v 3.0.1.2 89/11/17 15:31:05 lwall Locked $
4 ''' $Log: perl.man.3,v $
5 ''' Revision 3.0.1.2 89/11/17 15:31:05 lwall
6 ''' patch5: fixed some manual typos and indent problems
7 ''' patch5: added warning about print making an array context
9 ''' Revision 3.0.1.1 89/11/11 04:45:06 lwall
10 ''' patch2: made some line breaks depend on troff vs. nroff
12 ''' Revision 3.0 89/10/18 15:21:46 lwall
21 statement in C; it starts the next iteration of the loop:
25 line: while (<STDIN>) {
26 next line if /\|^#/; # discard comments
31 Note that if there were a
33 block on the above, it would get executed even on discarded lines.
34 If the LABEL is omitted, the command refers to the innermost enclosing loop.
37 Returns the decimal value of EXPR interpreted as an octal string.
38 (If EXPR happens to start off with 0x, interprets it as a hex string instead.)
39 The following will handle decimal, octal and hex in the standard notation:
42 $val = oct($val) if $val =~ /^0/;
45 If EXPR is omitted, uses $_.
46 .Ip "open(FILEHANDLE,EXPR)" 8 8
47 .Ip "open(FILEHANDLE)" 8
48 .Ip "open FILEHANDLE" 8
49 Opens the file whose filename is given by EXPR, and associates it with
51 If FILEHANDLE is an expression, its value is used as the name of the
52 real filehandle wanted.
53 If EXPR is omitted, the scalar variable of the same name as the FILEHANDLE
54 contains the filename.
55 If the filename begins with \*(L"<\*(R" or nothing, the file is opened for
57 If the filename begins with \*(L">\*(R", the file is opened for output.
58 If the filename begins with \*(L">>\*(R", the file is opened for appending.
59 (You can put a \'+\' in front of the \'>\' or \'<\' to indicate that you
60 want both read and write access to the file.)
61 If the filename begins with \*(L"|\*(R", the filename is interpreted
62 as a command to which output is to be piped, and if the filename ends
63 with a \*(L"|\*(R", the filename is interpreted as command which pipes
65 (You may not have a command that pipes both in and out.)
68 and opening \'>\-\' opens
70 Open returns non-zero upon success, the undefined value otherwise.
71 If the open involved a pipe, the return value happens to be the pid
78 open article || die "Can't find article $article: $!\en";
79 while (<article>) {\|.\|.\|.
82 open(LOG, \'>>/usr/spool/news/twitlog\'\|); # (log is reserved)
85 open(LOG, \'>>/usr/spool/news/twitlog\'\|);
90 open(article, "caesar <$article |"\|); # decrypt article
93 open(article, "caesar <$article |"\|);
98 open(extract, "|sort >/tmp/Tmp$$"\|); # $$ is our process#
101 open(extract, "|sort >/tmp/Tmp$$"\|);
106 # process argument list of files along with any includes
108 foreach $file (@ARGV) {
109 do process($file, \'fh00\'); # no pun intended
113 local($filename, $input) = @_;
114 $input++; # this is a string increment
115 unless (open($input, $filename)) {
116 print STDERR "Can't open $filename: $!\en";
120 while (<$input>) { # note the use of indirection
123 while (<$input>) { # note use of indirection
125 if (/^#include "(.*)"/) {
126 do process($1, $input);
134 You may also, in the Bourne shell tradition, specify an EXPR beginning
135 with \*(L">&\*(R", in which case the rest of the string
136 is interpreted as the name of a filehandle
137 (or file descriptor, if numeric) which is to be duped and opened.
138 You may use & after >, >>, <, +>, +>> and +<.
139 The mode you specify should match the mode of the original filehandle.
140 Here is a script that saves, redirects, and restores
148 open(SAVEOUT, ">&STDOUT");
149 open(SAVEERR, ">&STDERR");
151 open(STDOUT, ">foo.out") || die "Can't redirect stdout";
152 open(STDERR, ">&STDOUT") || die "Can't dup stdout";
154 select(STDERR); $| = 1; # make unbuffered
155 select(STDOUT); $| = 1; # make unbuffered
157 print STDOUT "stdout 1\en"; # this works for
158 print STDERR "stderr 1\en"; # subprocesses too
163 open(STDOUT, ">&SAVEOUT");
164 open(STDERR, ">&SAVEERR");
166 print STDOUT "stdout 2\en";
167 print STDERR "stderr 2\en";
170 If you open a pipe on the command \*(L"\-\*(R", i.e. either \*(L"|\-\*(R" or \*(L"\-|\*(R",
171 then there is an implicit fork done, and the return value of open
172 is the pid of the child within the parent process, and 0 within the child
174 (Use defined($pid) to determine if the open was successful.)
175 The filehandle behaves normally for the parent, but i/o to that
176 filehandle is piped from/to the
178 of the child process.
179 In the child process the filehandle isn't opened\*(--i/o happens from/to
184 Typically this is used like the normal piped open when you want to exercise
185 more control over just how the pipe command gets executed, such as when
186 you are running setuid, and don't want to have to scan shell commands
188 The following pairs are equivalent:
192 open(FOO, "|tr \'[a\-z]\' \'[A\-Z]\'");
193 open(FOO, "|\-") || exec \'tr\', \'[a\-z]\', \'[A\-Z]\';
195 open(FOO, "cat \-n $file|");
196 open(FOO, "\-|") || exec \'cat\', \'\-n\', $file;
199 Explicitly closing any piped filehandle causes the parent process to wait for the
200 child to finish, and returns the status value in $?.
201 .Ip "opendir(DIRHANDLE,EXPR)" 8 3
202 Opens a directory named EXPR for processing by readdir(), telldir(), seekdir(),
203 rewinddir() and closedir().
204 Returns true if successful.
205 DIRHANDLEs have their own namespace separate from FILEHANDLEs.
208 Returns the ascii value of the first character of EXPR.
209 If EXPR is omitted, uses $_.
210 .Ip "pack(TEMPLATE,LIST)" 8 4
211 Takes an array or list of values and packs it into a binary structure,
212 returning the string containing the structure.
213 The TEMPLATE is a sequence of characters that give the order and type
214 of values, as follows:
217 A An ascii string, will be space padded.
218 a An ascii string, will be null padded.
219 c A native char value.
220 C An unsigned char value.
221 s A signed short value.
222 S An unsigned short value.
223 i A signed integer value.
224 I An unsigned integer value.
225 l A signed long value.
226 L An unsigned long value.
227 n A short in \*(L"network\*(R" order.
228 N A long in \*(L"network\*(R" order.
229 p A pointer to a string.
233 Each letter may optionally be followed by a number which gives a repeat
235 With all types except "a" and "A" the pack function will gobble up that many values
237 The "a" and "A" types gobble just one value, but pack it as a string that long,
238 padding with nulls or spaces as necessary.
239 (When unpacking, "A" strips trailing spaces and nulls, but "a" does not.)
243 $foo = pack("cccc",65,66,67,68);
245 $foo = pack("c4",65,66,67,68);
248 $foo = pack("ccxxcc",65,66,67,68);
249 # foo eq "AB\e0\e0CD"
251 $foo = pack("s2",1,2);
252 # "\e1\e0\e2\e0" on little-endian
253 # "\e0\e1\e0\e2" on big-endian
255 $foo = pack("a4","abcd","x","y","z");
258 $foo = pack("aaaa","abcd","x","y","z");
261 $foo = pack("a14","abcdefg");
262 # "abcdefg\e0\e0\e0\e0\e0\e0\e0"
264 $foo = pack("i9pl", gmtime);
265 # a real struct tm (on my system anyway)
268 The same template may generally also be used in the unpack function.
271 Pops and returns the last value of the array, shortening the array by 1.
272 Has the same effect as
275 $tmp = $ARRAY[$#ARRAY\-\|\-];
278 If there are no elements in the array, returns the undefined value.
279 .Ip "print(FILEHANDLE LIST)" 8 10
281 .Ip "print FILEHANDLE LIST" 8
284 Prints a string or a comma-separated list of strings.
285 Returns non-zero if successful.
286 FILEHANDLE may be a scalar variable name, in which case the variable contains
287 the name of the filehandle, thus introducing one level of indirection.
288 If FILEHANDLE is omitted, prints by default to standard output (or to the
289 last selected output channel\*(--see select()).
290 If LIST is also omitted, prints $_ to
292 To set the default output channel to something other than
294 use the select operation.
295 Note that, because print takes a LIST, anything in the LIST is evaluated
296 in an array context, and any subroutine that you call will have one or more
297 of its expressions evaluated in an array context.
298 .Ip "printf(FILEHANDLE LIST)" 8 10
300 .Ip "printf FILEHANDLE LIST" 8
302 Equivalent to a \*(L"print FILEHANDLE sprintf(LIST)\*(R".
303 .Ip "push(ARRAY,LIST)" 8 7
304 Treats ARRAY (@ is optional) as a stack, and pushes the values of LIST
305 onto the end of ARRAY.
306 The length of ARRAY increases by the length of LIST.
307 Has the same effect as
311 $ARRAY[++$#ARRAY] = $value;
315 but is more efficient.
318 These are not really functions, but simply syntactic sugar to let you
319 avoid putting too many backslashes into quoted strings.
320 The q operator is a generalized single quote, and the qq operator a
321 generalized double quote.
322 Any delimiter can be used in place of /, including newline.
323 If the delimiter is an opening bracket or parenthesis, the final delimiter
324 will be the corresponding closing bracket or parenthesis.
325 (Embedded occurrences of the closing bracket need to be backslashed as usual.)
330 $foo = q!I said, "You said, \'She said it.\'"!;
331 $bar = q(\'This is it.\');
333 *** The previous line contains the naughty word "$&".\en
334 if /(ibm|apple|awk)/; # :-)
340 Returns a random fractional number between 0 and the value of EXPR.
341 (EXPR should be positive.)
342 If EXPR is omitted, returns a value between 0 and 1.
344 .Ip "read(FILEHANDLE,SCALAR,LENGTH)" 8 5
345 Attempts to read LENGTH bytes of data into variable SCALAR from the specified
347 Returns the number of bytes actually read.
348 SCALAR will be grown or shrunk to the length actually read.
349 .Ip "readdir(DIRHANDLE)" 8 3
350 .Ip "readdir DIRHANDLE" 8
351 Returns the next directory entry for a directory opened by opendir().
352 If used in an array context, returns all the rest of the entries in the
354 If there are no more entries, returns an undefined value in a scalar context
355 or a null list in an array context.
356 .Ip "readlink(EXPR)" 8 6
357 .Ip "readlink EXPR" 8
358 Returns the value of a symbolic link, if symbolic links are implemented.
359 If not, gives a fatal error.
360 If there is some system error, returns the undefined value and sets $! (errno).
361 If EXPR is omitted, uses $_.
362 .Ip "recv(SOCKET,SCALAR,LEN,FLAGS)" 8 4
363 Receives a message on a socket.
364 Attempts to receive LENGTH bytes of data into variable SCALAR from the specified
366 Returns the address of the sender, or the undefined value if there's an error.
367 SCALAR will be grown or shrunk to the length actually read.
368 Takes the same flags as the system call of the same name.
373 command restarts the loop block without evaluating the conditional again.
376 block, if any, is not executed.
377 If the LABEL is omitted, the command refers to the innermost enclosing loop.
378 This command is normally used by programs that want to lie to themselves
379 about what was just input:
383 # a simpleminded Pascal comment stripper
384 # (warning: assumes no { or } in strings)
385 line: while (<STDIN>) {
386 while (s|\|({.*}.*\|){.*}|$1 \||) {}
391 if (\|/\|}/\|) { # end of comment?
401 .Ip "rename(OLDNAME,NEWNAME)" 8 2
402 Changes the name of a file.
403 Returns 1 for success, 0 otherwise.
404 Will not work across filesystem boundaries.
405 .Ip "reset(EXPR)" 8 6
410 block at the end of a loop to clear variables and reset ?? searches
411 so that they work again.
412 The expression is interpreted as a list of single characters (hyphens allowed
414 All variables and arrays beginning with one of those letters are reset to
415 their pristine state.
416 If the expression is omitted, one-match searches (?pattern?) are reset to
418 Only resets variables or searches in the current package.
424 reset \'X\'; \h'|2i'# reset all X variables
425 reset \'a\-z\';\h'|2i'# reset lower case variables
426 reset; \h'|2i'# just reset ?? searches
429 Note: resetting \*(L"A\-Z\*(R" is not recommended since you'll wipe out your ARGV and ENV
432 The use of reset on dbm associative arrays does not change the dbm file.
433 (It does, however, flush any entries cached by perl, which may be useful if
434 you are sharing the dbm file.
435 Then again, maybe not.)
436 .Ip "return LIST" 8 3
437 Returns from a subroutine with the value specified.
438 (Note that a subroutine can automatically return
439 the value of the last expression evaluated.
440 That's the preferred method\*(--use of an explicit
443 .Ip "reverse(LIST)" 8 4
445 Returns an array value consisting of the elements of LIST in the opposite order.
446 .Ip "rewinddir(DIRHANDLE)" 8 5
447 .Ip "rewinddir DIRHANDLE" 8
448 Sets the current position to the beginning of the directory for the readdir() routine on DIRHANDLE.
449 .Ip "rindex(STR,SUBSTR)" 8 4
450 Works just like index except that it
451 returns the position of the LAST occurrence of SUBSTR in STR.
452 .Ip "rmdir(FILENAME)" 8 4
453 .Ip "rmdir FILENAME" 8
454 Deletes the directory specified by FILENAME if it is empty.
455 If it succeeds it returns 1, otherwise it returns 0 and sets $! (errno).
456 If FILENAME is omitted, uses $_.
457 .Ip "s/PATTERN/REPLACEMENT/gieo" 8 3
458 Searches a string for a pattern, and if found, replaces that pattern with the
459 replacement text and returns the number of substitutions made.
460 Otherwise it returns false (0).
461 The \*(L"g\*(R" is optional, and if present, indicates that all occurrences
462 of the pattern are to be replaced.
463 The \*(L"i\*(R" is also optional, and if present, indicates that matching
464 is to be done in a case-insensitive manner.
465 The \*(L"e\*(R" is likewise optional, and if present, indicates that
466 the replacement string is to be evaluated as an expression rather than just
467 as a double-quoted string.
468 Any delimiter may replace the slashes; if single quotes are used, no
469 interpretation is done on the replacement string (the e modifier overrides
471 If no string is specified via the =~ or !~ operator,
472 the $_ string is searched and modified.
473 (The string specified with =~ must be a scalar variable, an array element,
474 or an assignment to one of those, i.e. an lvalue.)
475 If the pattern contains a $ that looks like a variable rather than an
476 end-of-string test, the variable will be interpolated into the pattern at
478 If you only want the pattern compiled once the first time the variable is
479 interpolated, add an \*(L"o\*(R" at the end.
480 See also the section on regular expressions.
484 s/\|\e\|bgreen\e\|b/mauve/g; # don't change wintergreen
486 $path \|=~ \|s|\|/usr/bin|\|/usr/local/bin|;
488 s/Login: $foo/Login: $bar/; # run-time pattern
490 ($foo = $bar) =~ s/bar/foo/;
493 s/\ed+/$&*2/e; # yields \*(L'abc246xyz\*(R'
494 s/\ed+/sprintf("%5d",$&)/e; # yields \*(L'abc 246xyz\*(R'
495 s/\ew/$& x 2/eg; # yields \*(L'aabbcc 224466xxyyzz\*(R'
497 s/\|([^ \|]*\|) *\|([^ \|]*\|)\|/\|$2 $1/; # reverse 1st two fields
500 (Note the use of $ instead of \|\e\| in the last example. See section
501 on regular expressions.)
502 .Ip "seek(FILEHANDLE,POSITION,WHENCE)" 8 3
503 Randomly positions the file pointer for FILEHANDLE, just like the fseek()
505 FILEHANDLE may be an expression whose value gives the name of the filehandle.
506 Returns 1 upon success, 0 otherwise.
507 .Ip "seekdir(DIRHANDLE,POS)" 8 3
508 Sets the current position for the readdir() routine on DIRHANDLE.
509 POS must be a value returned by seekdir().
510 Has the same caveats about possible directory compaction as the corresponding
511 system library routine.
512 .Ip "select(FILEHANDLE)" 8 3
514 Returns the currently selected filehandle.
515 Sets the current default filehandle for output, if FILEHANDLE is supplied.
516 This has two effects: first, a
520 without a filehandle will default to this FILEHANDLE.
521 Second, references to variables related to output will refer to this output
523 For example, if you have to set the top of form format for more than
524 one output channel, you might do the following:
529 $^ = \'report1_top\';
531 $^ = \'report2_top\';
534 FILEHANDLE may be an expression whose value gives the name of the actual filehandle.
538 $oldfh = select(STDERR); $| = 1; select($oldfh);
541 .Ip "select(RBITS,WBITS,EBITS,TIMEOUT)" 8 3
542 This calls the select system call with the bitmasks specified, which can
543 be constructed using fileno() and vec(), along these lines:
546 $rin = $win = $ein = '';
547 vec($rin,fileno(STDIN),1) = 1;
548 vec($win,fileno(STDOUT),1) = 1;
552 If you want to select on many filehandles you might wish to write a subroutine:
556 local(@fhlist) = split(' ',$_[0]);
559 vec($bits,fileno($_),1) = 1;
563 $rin = &fhbits('STDIN TTY SOCK');
569 ($nfound,$timeleft) =
570 select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
572 or to block until something becomes ready:
575 $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
578 $nfound = select($rout=$rin, $wout=$win,
583 Any of the bitmasks can also be undef.
584 The timeout, if specified, is in seconds, which may be fractional.
585 .Ip "setpgrp(PID,PGRP)" 8 4
586 Sets the current process group for the specified PID, 0 for the current
588 Will produce a fatal error if used on a machine that doesn't implement
590 .Ip "send(SOCKET,MSG,FLAGS,TO)" 8 4
591 .Ip "send(SOCKET,MSG,FLAGS)" 8
592 Sends a message on a socket.
593 Takes the same flags as the system call of the same name.
594 On unconnected sockets you must specify a destination to send TO.
595 Returns the number of characters sent, or the undefined value if
597 .Ip "setpriority(WHICH,WHO,PRIORITY)" 8 4
598 Sets the current priority for a process, a process group, or a user.
599 (See setpriority(2).)
600 Will produce a fatal error if used on a machine that doesn't implement
602 .Ip "setsockopt(SOCKET,LEVEL,OPTNAME,OPTVAL)" 8 3
603 Sets the socket option requested.
604 Returns undefined if there is an error.
605 OPTVAL may be specified as undef if you don't want to pass an argument.
606 .Ip "shift(ARRAY)" 8 6
609 Shifts the first value of the array off and returns it,
610 shortening the array by 1 and moving everything down.
611 If there are no elements in the array, returns the undefined value.
612 If ARRAY is omitted, shifts the @ARGV array in the main program, and the @_
613 array in subroutines.
614 See also unshift(), push() and pop().
615 Shift() and unshift() do the same thing to the left end of an array that push()
616 and pop() do to the right end.
617 .Ip "shutdown(SOCKET,HOW)" 8 3
618 Shuts down a socket connection in the manner indicated by HOW, which has
619 the same interpretation as in the system call of the same name.
622 Returns the sine of EXPR (expressed in radians).
623 If EXPR is omitted, returns sine of $_.
624 .Ip "sleep(EXPR)" 8 6
627 Causes the script to sleep for EXPR seconds, or forever if no EXPR.
628 May be interrupted by sending the process a SIGALARM.
629 Returns the number of seconds actually slept.
630 .Ip "socket(SOCKET,DOMAIN,TYPE,PROTOCOL)" 8 3
631 Opens a socket of the specified kind and attaches it to filehandle SOCKET.
632 DOMAIN, TYPE and PROTOCOL are specified the same as for the system call
634 You may need to run makelib on sys/socket.h to get the proper values handy
635 in a perl library file.
636 Return true if successful.
637 See the example in the section on Interprocess Communication.
638 .Ip "socketpair(SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL)" 8 3
639 Creates an unnamed pair of sockets in the specified domain, of the specified
641 DOMAIN, TYPE and PROTOCOL are specified the same as for the system call
643 If unimplemented, yields a fatal error.
644 Return true if successful.
645 .Ip "sort(SUBROUTINE LIST)" 8 9
647 .Ip "sort SUBROUTINE LIST" 8
649 Sorts the LIST and returns the sorted array value.
650 Nonexistent values of arrays are stripped out.
651 If SUBROUTINE is omitted, sorts in standard string comparison order.
652 If SUBROUTINE is specified, gives the name of a subroutine that returns
653 an integer less than, equal to, or greater than 0,
654 depending on how the elements of the array are to be ordered.
655 In the interests of efficiency the normal calling code for subroutines
656 is bypassed, with the following effects: the subroutine may not be a recursive
657 subroutine, and the two elements to be compared are passed into the subroutine
658 not via @_ but as $a and $b (see example below).
659 They are passed by reference so don't modify $a and $b.
660 SUBROUTINE may be a scalar variable name, in which case the value provides
661 the name of the subroutine to use.
667 $age{$a} - $age{$b}; # presuming integers
669 @sortedclass = sort byage @class;
672 sub reverse { $a lt $b ? 1 : $a gt $b ? \-1 : 0; }
673 @harry = (\'dog\',\'cat\',\'x\',\'Cain\',\'Abel\');
674 @george = (\'gone\',\'chased\',\'yz\',\'Punished\',\'Axed\');
676 # prints AbelCaincatdogx
677 print sort reverse @harry;
678 # prints xdogcatCainAbel
679 print sort @george, \'to\', @harry;
680 # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
683 .Ip "split(/PATTERN/,EXPR,LIMIT)" 8 8
684 .Ip "split(/PATTERN/,EXPR)" 8 8
685 .Ip "split(/PATTERN/)" 8
687 Splits a string into an array of strings, and returns it.
688 (If not in an array context, returns the number of fields found and splits
690 If EXPR is omitted, splits the $_ string.
691 If PATTERN is also omitted, splits on whitespace (/[\ \et\en]+/).
692 Anything matching PATTERN is taken to be a delimiter separating the fields.
693 (Note that the delimiter may be longer than one character.)
694 If LIMIT is specified, splits into no more than that many fields (though it
695 may split into fewer).
696 If LIMIT is unspecified, trailing null fields are stripped (which
697 potential users of pop() would do well to remember).
698 A pattern matching the null string (not to be confused with a null pattern,
699 which is one member of the set of patterns matching a null string)
700 will split the value of EXPR into separate characters at each point it
705 print join(\':\', split(/ */, \'hi there\'));
708 produces the output \*(L'h:i:t:h:e:r:e\*(R'.
710 The NUM parameter can be used to partially split a line
713 ($login, $passwd, $remainder) = split(\|/\|:\|/\|, $_, 3);
716 (When assigning to a list, if NUM is omitted, perl supplies a NUM one
717 larger than the number of variables in the list, to avoid unnecessary work.
718 For the list above NUM would have been 4 by default.
719 In time critical applications it behooves you not to split into
720 more fields than you really need.)
722 If the PATTERN contains parentheses, additional array elements are created
723 from each matching substring in the delimiter.
725 split(/([,-])/,"1-10,20");
727 produces the array value
731 The pattern /PATTERN/ may be replaced with an expression to specify patterns
732 that vary at runtime.
733 (To do runtime compilation only once, use /$variable/o.)
734 As a special case, specifying a space (\'\ \') will split on white space
735 just as split with no arguments does, but leading white space does NOT
736 produce a null first field.
737 Thus, split(\'\ \') can be used to emulate
739 default behavior, whereas
740 split(/\ /) will give you as many null initial fields as there are
747 open(passwd, \'/etc/passwd\');
750 ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(\|/\|:\|/\|);
753 ($login, $passwd, $uid, $gid, $gcos, $home, $shell)
754 = split(\|/\|:\|/\|);
760 (Note that $shell above will still have a newline on it. See chop().)
763 .Ip "sprintf(FORMAT,LIST)" 8 4
764 Returns a string formatted by the usual printf conventions.
765 The * character is not supported.
768 Return the square root of EXPR.
769 If EXPR is omitted, returns square root of $_.
770 .Ip "srand(EXPR)" 8 4
772 Sets the random number seed for the
775 If EXPR is omitted, does srand(time).
776 .Ip "stat(FILEHANDLE)" 8 8
777 .Ip "stat FILEHANDLE" 8
779 .Ip "stat SCALARVARIABLE" 8
780 Returns a 13-element array giving the statistics for a file, either the file
781 opened via FILEHANDLE, or named by EXPR.
782 Typically used as follows:
786 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
787 $atime,$mtime,$ctime,$blksize,$blocks)
791 If stat is passed the special filehandle consisting of an underline,
792 no stat is done, but the current contents of the stat structure from
793 the last stat or filetest are returned.
798 if (-x $file && (($d) = stat(_)) && $d < 0) {
799 print "$file is executable NFS file\en";
803 .Ip "study(SCALAR)" 8 6
806 Takes extra time to study SCALAR ($_ if unspecified) in anticipation of
807 doing many pattern matches on the string before it is next modified.
808 This may or may not save time, depending on the nature and number of patterns
809 you are searching on, and on the distribution of character frequencies in
810 the string to be searched\*(--you probably want to compare runtimes with and
811 without it to see which runs faster.
812 Those loops which scan for many short constant strings (including the constant
813 parts of more complex patterns) will benefit most.
814 You may have only one study active at a time\*(--if you study a different
815 scalar the first is \*(L"unstudied\*(R".
816 (The way study works is this: a linked list of every character in the string
817 to be searched is made, so we know, for example, where all the \*(L'k\*(R' characters
819 From each search string, the rarest character is selected, based on some
820 static frequency tables constructed from some C programs and English text.
821 Only those places that contain this \*(L"rarest\*(R" character are examined.)
823 For example, here is a loop which inserts index producing entries before any line
824 containing a certain pattern:
830 print ".IX foo\en" if /\ebfoo\eb/;
831 print ".IX bar\en" if /\ebbar\eb/;
832 print ".IX blurfl\en" if /\ebblurfl\eb/;
838 In searching for /\ebfoo\eb/, only those locations in $_ that contain \*(L'f\*(R'
839 will be looked at, because \*(L'f\*(R' is rarer than \*(L'o\*(R'.
840 In general, this is a big win except in pathological cases.
841 The only question is whether it saves you more time than it took to build
842 the linked list in the first place.
844 Note that if you have to look for strings that you don't know till runtime,
845 you can build an entire loop as a string and eval that to avoid recompiling
846 all your patterns all the time.
847 Together with setting $/ to input entire files as one record, this can
848 be very fast, often faster than specialized programs like fgrep.
849 The following scans a list of files (@files)
850 for a list of words (@words), and prints out the names of those files that
855 $search = \'while (<>) { study;\';
856 foreach $word (@words) {
857 $search .= "++\e$seen{\e$ARGV} if /\eb$word\eb/;\en";
861 $/ = "\e177"; # something that doesn't occur
862 eval $search; # this screams
863 $/ = "\en"; # put back to normal input delim
864 foreach $file (sort keys(%seen)) {
869 .Ip "substr(EXPR,OFFSET,LEN)" 8 2
870 Extracts a substring out of EXPR and returns it.
871 First character is at offset 0, or whatever you've set $[ to.
872 If OFFSET is negative, starts that far from the end of the string.
873 You can use the substr() function as an lvalue, in which case EXPR must
875 If you assign something shorter than LEN, the string will shrink, and
876 if you assign something longer than LEN, the string will grow to accommodate it.
877 To keep the string the same length you may need to pad or chop your value using
879 .Ip "syscall(LIST)" 8 6
881 Calls the system call specified as the first element of the list, passing
882 the remaining elements as arguments to the system call.
883 If unimplemented, produces a fatal error.
884 The arguments are interpreted as follows: if a given argument is numeric,
885 the argument is passed as an int.
886 If not, the pointer to the string value is passed.
887 You are responsible to make sure a string is pre-extended long enough
888 to receive any result that might be written into a string.
889 If your integer arguments are not literals and have never been interpreted
890 in a numeric context, you may need to add 0 to them to force them to look
894 do 'syscall.h'; # may need to run makelib
895 syscall(&SYS_write, fileno(STDOUT), "hi there\en", 9);
898 .Ip "system(LIST)" 8 6
900 Does exactly the same thing as \*(L"exec LIST\*(R" except that a fork
901 is done first, and the parent process waits for the child process to complete.
902 Note that argument processing varies depending on the number of arguments.
903 The return value is the exit status of the program as returned by the wait()
905 To get the actual exit value divide by 256.
908 .Ip "symlink(OLDFILE,NEWFILE)" 8 2
909 Creates a new filename symbolically linked to the old filename.
910 Returns 1 for success, 0 otherwise.
911 On systems that don't support symbolic links, produces a fatal error at
913 To check for that, use eval:
916 $symlink_exists = (eval \'symlink("","");\', $@ eq \'\');
919 .Ip "tell(FILEHANDLE)" 8 6
920 .Ip "tell FILEHANDLE" 8 6
922 Returns the current file position for FILEHANDLE.
923 FILEHANDLE may be an expression whose value gives the name of the actual
925 If FILEHANDLE is omitted, assumes the file last read.
926 .Ip "telldir(DIRHANDLE)" 8 5
927 .Ip "telldir DIRHANDLE" 8
928 Returns the current position of the readdir() routines on DIRHANDLE.
929 Value may be given to seekdir() to access a particular location in
931 Has the same caveats about possible directory compaction as the corresponding
932 system library routine.
934 Returns the number of non-leap seconds since January 1, 1970, UTC.
935 Suitable for feeding to gmtime() and localtime().
937 Returns a four-element array giving the user and system times, in seconds, for this
938 process and the children of this process.
940 ($user,$system,$cuser,$csystem) = times;
942 .Ip "tr/SEARCHLIST/REPLACEMENTLIST/" 8 5
943 .Ip "y/SEARCHLIST/REPLACEMENTLIST/" 8
944 Translates all occurrences of the characters found in the search list with
945 the corresponding character in the replacement list.
946 It returns the number of characters replaced.
947 If no string is specified via the =~ or !~ operator,
948 the $_ string is translated.
949 (The string specified with =~ must be a scalar variable, an array element,
950 or an assignment to one of those, i.e. an lvalue.)
955 is provided as a synonym for
960 $ARGV[1] \|=~ \|y/A\-Z/a\-z/; \h'|3i'# canonicalize to lower case
962 $cnt = tr/*/*/; \h'|3i'# count the stars in $_
964 ($HOST = $host) =~ tr/a\-z/A\-Z/;
966 y/\e001\-@[\-_{\-\e177/ /; \h'|3i'# change non-alphas to space
969 .Ip "umask(EXPR)" 8 4
972 Sets the umask for the process and returns the old one.
973 If EXPR is omitted, merely returns current umask.
974 .Ip "undef(EXPR)" 8 6
977 Undefines the value of EXPR, which must be an lvalue.
978 Use only on a scalar value, an entire array, or a subroutine name (using &).
979 (Undef will probably not do what you expect on most predefined variables or
981 Always returns the undefined value.
982 You can omit the EXPR, in which case nothing is undefined, but you still
983 get an undefined value that you could, for instance, return from a subroutine.
989 undef $bar{'blurfl'};
993 return (wantarray ? () : undef) if $they_blew_it;
996 .Ip "unlink(LIST)" 8 4
998 Deletes a list of files.
999 Returns the number of files successfully deleted.
1003 $cnt = unlink \'a\', \'b\', \'c\';
1008 Note: unlink will not delete directories unless you are superuser and the
1012 Even if these conditions are met, be warned that unlinking a directory
1013 can inflict damage on your filesystem.
1015 .Ip "unpack(TEMPLATE,EXPR)" 8 4
1016 Unpack does the reverse of pack: it takes a string representing
1017 a structure and expands it out into an array value, returning the array
1019 The TEMPLATE has the same format as in the pack function.
1020 Here's a subroutine that does substring:
1025 local($what,$where,$howmuch) = @_;
1026 unpack("x$where a$howmuch", $what);
1032 sub ord { unpack("c",$_[0]); }
1035 .Ip "unshift(ARRAY,LIST)" 8 4
1036 Does the opposite of a
1038 Or the opposite of a
1040 depending on how you look at it.
1041 Prepends list to the front of the array, and returns the number of elements
1045 unshift(ARGV, \'\-e\') unless $ARGV[0] =~ /^\-/;
1048 .Ip "utime(LIST)" 8 2
1049 .Ip "utime LIST" 8 2
1050 Changes the access and modification times on each file of a list of files.
1051 The first two elements of the list must be the NUMERICAL access and
1052 modification times, in that order.
1053 Returns the number of files successfully changed.
1054 The inode modification time of each file is set to the current time.
1055 Example of a \*(L"touch\*(R" command:
1061 utime $now, $now, @ARGV;
1064 .Ip "values(ASSOC_ARRAY)" 8 6
1065 .Ip "values ASSOC_ARRAY" 8
1066 Returns a normal array consisting of all the values of the named associative
1068 The values are returned in an apparently random order, but it is the same order
1069 as either the keys() or each() function would produce on the same array.
1070 See also keys() and each().
1071 .Ip "vec(EXPR,OFFSET,BITS)" 8 2
1072 Treats a string as a vector of unsigned integers, and returns the value
1073 of the bitfield specified.
1074 May also be assigned to.
1075 BITS must be a power of two from 1 to 32.
1077 Vectors created with vec() can also be manipulated with the logical operators
1079 which will assume a bit vector operation is desired when both operands are
1081 This interpretation is not enabled unless there is at least one vec() in
1082 your program, to protect older programs.
1084 Waits for a child process to terminate and returns the pid of the deceased
1085 process, or -1 if there are no child processes.
1086 The status is returned in $?.
1087 If you expected a child and didn't find it, you probably had a call to
1088 system, a close on a pipe, or backticks between the fork and the wait.
1089 These constructs also do a wait and may have harvested your child process.
1091 Returns true if the context of the currently executing subroutine
1092 is looking for an array value.
1093 Returns false if the context is looking for a scalar.
1096 return wantarray ? () : undef;
1099 .Ip "warn(LIST)" 8 4
1101 Produces a message on STDERR just like \*(L"die\*(R", but doesn't exit.
1102 .Ip "write(FILEHANDLE)" 8 6
1105 Writes a formatted record (possibly multi-line) to the specified file,
1106 using the format associated with that file.
1107 By default the format for a file is the one having the same name is the
1108 filehandle, but the format for the current output channel (see
1110 may be set explicitly
1111 by assigning the name of the format to the $~ variable.
1113 Top of form processing is handled automatically:
1114 if there is insufficient room on the current page for the formatted
1115 record, the page is advanced, a special top-of-page format is used
1116 to format the new page header, and then the record is written.
1117 By default the top-of-page format is \*(L"top\*(R", but it
1119 format of your choice by assigning the name to the $^ variable.
1121 If FILEHANDLE is unspecified, output goes to the current default output channel,
1124 but may be changed by the
1127 If the FILEHANDLE is an EXPR, then the expression is evaluated and the
1128 resulting string is used to look up the name of the FILEHANDLE at run time.
1129 For more on formats, see the section on formats later on.
1131 Note that write is NOT the opposite of read.