1 ''' Beginning of part 3
2 ''' $Header: perl.man.3,v 3.0.1.1 89/11/11 04:45:06 lwall Locked $
4 ''' $Log: perl.man.3,v $
5 ''' Revision 3.0.1.1 89/11/11 04:45:06 lwall
6 ''' patch2: made some line breaks depend on troff vs. nroff
8 ''' Revision 3.0 89/10/18 15:21:46 lwall
17 statement in C; it starts the next iteration of the loop:
21 line: while (<STDIN>) {
22 next line if /\|^#/; # discard comments
27 Note that if there were a
29 block on the above, it would get executed even on discarded lines.
30 If the LABEL is omitted, the command refers to the innermost enclosing loop.
33 Returns 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.)
35 The following will handle decimal, octal and hex in the standard notation:
38 $val = oct($val) if $val =~ /^0/;
41 If EXPR is omitted, uses $_.
42 .Ip "open(FILEHANDLE,EXPR)" 8 8
43 .Ip "open(FILEHANDLE)" 8
44 .Ip "open FILEHANDLE" 8
45 Opens the file whose filename is given by EXPR, and associates it with
47 If FILEHANDLE is an expression, its value is used as the name of the
48 real filehandle wanted.
49 If EXPR is omitted, the scalar variable of the same name as the FILEHANDLE
50 contains the filename.
51 If the filename begins with \*(L"<\*(R" or nothing, the file is opened for
53 If the filename begins with \*(L">\*(R", the file is opened for output.
54 If 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
56 want both read and write access to the file.)
57 If the filename begins with \*(L"|\*(R", the filename is interpreted
58 as a command to which output is to be piped, and if the filename ends
59 with a \*(L"|\*(R", the filename is interpreted as command which pipes
61 (You may not have a command that pipes both in and out.)
64 and opening \'>\-\' opens
66 Open returns non-zero upon success, the undefined value otherwise.
67 If the open involved a pipe, the return value happens to be the pid
74 open article || die "Can't find article $article: $!\en";
75 while (<article>) {\|.\|.\|.
78 open(LOG, \'>>/usr/spool/news/twitlog\'\|); # (log is reserved)
81 open(LOG, \'>>/usr/spool/news/twitlog\'\|);
86 open(article, "caesar <$article |"\|); # decrypt article
89 open(article, "caesar <$article |"\|);
94 open(extract, "|sort >/tmp/Tmp$$"\|); # $$ is our process#
97 open(extract, "|sort >/tmp/Tmp$$"\|);
102 # process argument list of files along with any includes
104 foreach $file (@ARGV) {
105 do process($file, \'fh00\'); # no pun intended
109 local($filename, $input) = @_;
110 $input++; # this is a string increment
111 unless (open($input, $filename)) {
112 print STDERR "Can't open $filename: $!\en";
116 while (<$input>) { # note the use of indirection
119 while (<$input>) { # note use of indirection
121 if (/^#include "(.*)"/) {
122 do process($1, $input);
130 You may also, in the Bourne shell tradition, specify an EXPR beginning
131 with \*(L">&\*(R", in which case the rest of the string
132 is interpreted as the name of a filehandle
133 (or file descriptor, if numeric) which is to be duped and opened.
134 You may use & after >, >>, <, +>, +>> and +<.
135 The mode you specify should match the mode of the original filehandle.
136 Here is a script that saves, redirects, and restores
144 open(SAVEOUT, ">&STDOUT");
145 open(SAVEERR, ">&STDERR");
147 open(STDOUT, ">foo.out") || die "Can't redirect stdout";
148 open(STDERR, ">&STDOUT") || die "Can't dup stdout";
150 select(STDERR); $| = 1; # make unbuffered
151 select(STDOUT); $| = 1; # make unbuffered
153 print STDOUT "stdout 1\en"; # this works for
154 print STDERR "stderr 1\en"; # subprocesses too
159 open(STDOUT, ">&SAVEOUT");
160 open(STDERR, ">&SAVEERR");
162 print STDOUT "stdout 2\en";
163 print STDERR "stderr 2\en";
166 If you open a pipe on the command \*(L"\-\*(R", i.e. either \*(L"|\-\*(R" or \*(L"\-|\*(R",
167 then there is an implicit fork done, and the return value of open
168 is the pid of the child within the parent process, and 0 within the child
170 (Use defined($pid) to determine if the open was successful.)
171 The filehandle behaves normally for the parent, but i/o to that
172 filehandle is piped from/to the
174 of the child process.
175 In the child process the filehandle isn't opened\*(--i/o happens from/to
180 Typically this is used like the normal piped open when you want to exercise
181 more control over just how the pipe command gets executed, such as when
182 you are running setuid, and don't want to have to scan shell commands
184 The following pairs are equivalent:
188 open(FOO, "|tr \'[a\-z]\' \'[A\-Z]\'");
189 open(FOO, "|\-") || exec \'tr\', \'[a\-z]\', \'[A\-Z]\';
191 open(FOO, "cat \-n $file|");
192 open(FOO, "\-|") || exec \'cat\', \'\-n\', $file;
195 Explicitly closing any piped filehandle causes the parent process to wait for the
196 child to finish, and returns the status value in $?.
197 .Ip "opendir(DIRHANDLE,EXPR)" 8 3
198 Opens a directory named EXPR for processing by readdir(), telldir(), seekdir(),
199 rewinddir() and closedir().
200 Returns true if successful.
201 DIRHANDLEs have their own namespace separate from FILEHANDLEs.
204 Returns the ascii value of the first character of EXPR.
205 If EXPR is omitted, uses $_.
206 .Ip "pack(TEMPLATE,LIST)" 8 4
207 Takes an array or list of values and packs it into a binary structure,
208 returning the string containing the structure.
209 The TEMPLATE is a sequence of characters that give the order and type
210 of values, as follows:
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.
229 Each letter may optionally be followed by a number which gives a repeat
231 With all types except "a" and "A" the pack function will gobble up that many values
233 The "a" and "A" types gobble just one value, but pack it as a string that long,
234 padding with nulls or spaces as necessary.
235 (When unpacking, "A" strips trailing spaces and nulls, but "a" does not.)
239 $foo = pack("cccc",65,66,67,68);
241 $foo = pack("c4",65,66,67,68);
244 $foo = pack("ccxxcc",65,66,67,68);
245 # foo eq "AB\e0\e0CD"
247 $foo = pack("s2",1,2);
248 # "\e1\e0\e2\e0" on little-endian
249 # "\e0\e1\e0\e2" on big-endian
251 $foo = pack("a4","abcd","x","y","z");
254 $foo = pack("aaaa","abcd","x","y","z");
257 $foo = pack("a14","abcdefg");
258 # "abcdefg\e0\e0\e0\e0\e0\e0\e0"
260 $foo = pack("i9pl", gmtime);
261 # a real struct tm (on my system anyway)
264 The same template may generally also be used in the unpack function.
267 Pops and returns the last value of the array, shortening the array by 1.
268 Has the same effect as
271 $tmp = $ARRAY[$#ARRAY\-\|\-];
274 If there are no elements in the array, returns the undefined value.
275 .Ip "print(FILEHANDLE LIST)" 8 10
277 .Ip "print FILEHANDLE LIST" 8
280 Prints a string or a comma-separated list of strings.
281 Returns non-zero if successful.
282 FILEHANDLE may be a scalar variable name, in which case the variable contains
283 the name of the filehandle, thus introducing one level of indirection.
284 If FILEHANDLE is omitted, prints by default to standard output (or to the
285 last selected output channel\*(--see select()).
286 If LIST is also omitted, prints $_ to
288 To set the default output channel to something other than
290 use the select operation.
291 .Ip "printf(FILEHANDLE LIST)" 8 10
293 .Ip "printf FILEHANDLE LIST" 8
295 Equivalent to a \*(L"print FILEHANDLE sprintf(LIST)\*(R".
296 .Ip "push(ARRAY,LIST)" 8 7
297 Treats ARRAY (@ is optional) as a stack, and pushes the values of LIST
298 onto the end of ARRAY.
299 The length of ARRAY increases by the length of LIST.
300 Has the same effect as
304 $ARRAY[++$#ARRAY] = $value;
308 but is more efficient.
311 These are not really functions, but simply syntactic sugar to let you
312 avoid putting too many backslashes into quoted strings.
313 The q operator is a generalized single quote, and the qq operator a
314 generalized double quote.
315 Any delimiter can be used in place of /, including newline.
316 If the delimiter is an opening bracket or parenthesis, the final delimiter
317 will be the corresponding closing bracket or parenthesis.
318 (Embedded occurrences of the closing bracket need to be backslashed as usual.)
323 $foo = q!I said, "You said, \'She said it.\'"!;
324 $bar = q(\'This is it.\');
326 *** The previous line contains the naughty word "$&".\en
327 if /(ibm|apple|awk)/; # :-)
333 Returns a random fractional number between 0 and the value of EXPR.
334 (EXPR should be positive.)
335 If EXPR is omitted, returns a value between 0 and 1.
337 .Ip "read(FILEHANDLE,SCALAR,LENGTH)" 8 5
338 Attempts to read LENGTH bytes of data into variable SCALAR from the specified
340 Returns the number of bytes actually read.
341 SCALAR will be grown or shrunk to the length actually read.
342 .Ip "readdir(DIRHANDLE)" 8 3
343 .Ip "readdir DIRHANDLE" 8
344 Returns the next directory entry for a directory opened by opendir().
345 If used in an array context, returns all the rest of the entries in the
347 If there are no more entries, returns an undefined value in a scalar context
348 or a null list in an array context.
349 .Ip "readlink(EXPR)" 8 6
350 .Ip "readlink EXPR" 8
351 Returns the value of a symbolic link, if symbolic links are implemented.
352 If not, gives a fatal error.
353 If there is some system error, returns the undefined value and sets $! (errno).
354 If EXPR is omitted, uses $_.
355 .Ip "recv(SOCKET,SCALAR,LEN,FLAGS)" 8 4
356 Receives a message on a socket.
357 Attempts to receive LENGTH bytes of data into variable SCALAR from the specified
359 Returns the address of the sender, or the undefined value if there's an error.
360 SCALAR will be grown or shrunk to the length actually read.
361 Takes the same flags as the system call of the same name.
366 command restarts the loop block without evaluating the conditional again.
369 block, if any, is not executed.
370 If the LABEL is omitted, the command refers to the innermost enclosing loop.
371 This command is normally used by programs that want to lie to themselves
372 about what was just input:
376 # a simpleminded Pascal comment stripper
377 # (warning: assumes no { or } in strings)
378 line: while (<STDIN>) {
379 while (s|\|({.*}.*\|){.*}|$1 \||) {}
384 if (\|/\|}/\|) { # end of comment?
394 .Ip "rename(OLDNAME,NEWNAME)" 8 2
395 Changes the name of a file.
396 Returns 1 for success, 0 otherwise.
397 Will not work across filesystem boundaries.
398 .Ip "reset(EXPR)" 8 6
403 block at the end of a loop to clear variables and reset ?? searches
404 so that they work again.
405 The expression is interpreted as a list of single characters (hyphens allowed
407 All variables and arrays beginning with one of those letters are reset to
408 their pristine state.
409 If the expression is omitted, one-match searches (?pattern?) are reset to
411 Only resets variables or searches in the current package.
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
422 Note: resetting \*(L"A\-Z\*(R" is not recommended since you'll wipe out your ARGV and ENV
425 The 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
427 you are sharing the dbm file.
428 Then again, maybe not.)
429 .Ip "return LIST" 8 3
430 Returns from a subroutine with the value specified.
431 (Note that a subroutine can automatically return
432 the value of the last expression evaluated.
433 That's the preferred method\*(--use of an explicit
436 .Ip "reverse(LIST)" 8 4
438 Returns an array value consisting of the elements of LIST in the opposite order.
439 .Ip "rewinddir(DIRHANDLE)" 8 5
440 .Ip "rewinddir DIRHANDLE" 8
441 Sets the current position to the beginning of the directory for the readdir() routine on DIRHANDLE.
442 .Ip "rindex(STR,SUBSTR)" 8 4
443 Works just like index except that it
444 returns the position of the LAST occurrence of SUBSTR in STR.
445 .Ip "rmdir(FILENAME)" 8 4
446 .Ip "rmdir FILENAME" 8
447 Deletes the directory specified by FILENAME if it is empty.
448 If it succeeds it returns 1, otherwise it returns 0 and sets $! (errno).
449 If FILENAME is omitted, uses $_.
450 .Ip "s/PATTERN/REPLACEMENT/gieo" 8 3
451 Searches a string for a pattern, and if found, replaces that pattern with the
452 replacement text and returns the number of substitutions made.
453 Otherwise it returns false (0).
454 The \*(L"g\*(R" is optional, and if present, indicates that all occurrences
455 of the pattern are to be replaced.
456 The \*(L"i\*(R" is also optional, and if present, indicates that matching
457 is to be done in a case-insensitive manner.
458 The \*(L"e\*(R" is likewise optional, and if present, indicates that
459 the replacement string is to be evaluated as an expression rather than just
460 as a double-quoted string.
461 Any delimiter may replace the slashes; if single quotes are used, no
462 interpretation is done on the replacement string (the e modifier overrides
464 If no string is specified via the =~ or !~ operator,
465 the $_ string is searched and modified.
466 (The string specified with =~ must be a scalar variable, an array element,
467 or an assignment to one of those, i.e. an lvalue.)
468 If the pattern contains a $ that looks like a variable rather than an
469 end-of-string test, the variable will be interpolated into the pattern at
471 If you only want the pattern compiled once the first time the variable is
472 interpolated, add an \*(L"o\*(R" at the end.
473 See also the section on regular expressions.
477 s/\|\e\|bgreen\e\|b/mauve/g; # don't change wintergreen
479 $path \|=~ \|s|\|/usr/bin|\|/usr/local/bin|;
481 s/Login: $foo/Login: $bar/; # run-time pattern
483 ($foo = $bar) =~ s/bar/foo/;
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'
490 s/\|([^ \|]*\|) *\|([^ \|]*\|)\|/\|$2 $1/; # reverse 1st two fields
493 (Note the use of $ instead of \|\e\| in the last example. See section
494 on regular expressions.)
495 .Ip "seek(FILEHANDLE,POSITION,WHENCE)" 8 3
496 Randomly positions the file pointer for FILEHANDLE, just like the fseek()
498 FILEHANDLE may be an expression whose value gives the name of the filehandle.
499 Returns 1 upon success, 0 otherwise.
500 .Ip "seekdir(DIRHANDLE,POS)" 8 3
501 Sets the current position for the readdir() routine on DIRHANDLE.
502 POS must be a value returned by seekdir().
503 Has the same caveats about possible directory compaction as the corresponding
504 system library routine.
505 .Ip "select(FILEHANDLE)" 8 3
507 Returns the currently selected filehandle.
508 Sets the current default filehandle for output, if FILEHANDLE is supplied.
509 This has two effects: first, a
513 without a filehandle will default to this FILEHANDLE.
514 Second, references to variables related to output will refer to this output
516 For example, if you have to set the top of form format for more than
517 one output channel, you might do the following:
522 $^ = \'report1_top\';
524 $^ = \'report2_top\';
527 FILEHANDLE may be an expression whose value gives the name of the actual filehandle.
531 $oldfh = select(STDERR); $| = 1; select($oldfh);
534 .Ip "select(RBITS,WBITS,EBITS,TIMEOUT)" 8 3
535 This calls the select system call with the bitmasks specified, which can
536 be constructed using fileno() and vec(), along these lines:
539 $rin = $win = $ein = '';
540 vec($rin,fileno(STDIN),1) = 1;
541 vec($win,fileno(STDOUT),1) = 1;
545 If you want to select on many filehandles you might wish to write a subroutine:
549 local(@fhlist) = split(' ',$_[0]);
552 vec($bits,fileno($_),1) = 1;
556 $rin = &fhbits('STDIN TTY SOCK');
562 ($nfound,$timeleft) =
563 select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
565 or to block until something becomes ready:
568 $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
571 $nfound = select($rout=$rin, $wout=$win,
576 Any of the bitmasks can also be undef.
577 The timeout, if specified, is in seconds, which may be fractional.
578 .Ip "setpgrp(PID,PGRP)" 8 4
579 Sets the current process group for the specified PID, 0 for the current
581 Will produce a fatal error if used on a machine that doesn't implement
583 .Ip "send(SOCKET,MSG,FLAGS,TO)" 8 4
584 .Ip "send(SOCKET,MSG,FLAGS)" 8
585 Sends a message on a socket.
586 Takes the same flags as the system call of the same name.
587 On unconnected sockets you must specify a destination to send TO.
588 Returns the number of characters sent, or the undefined value if
590 .Ip "setpriority(WHICH,WHO,PRIORITY)" 8 4
591 Sets the current priority for a process, a process group, or a user.
592 (See setpriority(2).)
593 Will produce a fatal error if used on a machine that doesn't implement
595 .Ip "setsockopt(SOCKET,LEVEL,OPTNAME,OPTVAL)" 8 3
596 Sets the socket option requested.
597 Returns undefined if there is an error.
598 OPTVAL may be specified as undef if you don't want to pass an argument.
599 .Ip "shift(ARRAY)" 8 6
602 Shifts the first value of the array off and returns it,
603 shortening the array by 1 and moving everything down.
604 If there are no elements in the array, returns the undefined value.
605 If ARRAY is omitted, shifts the @ARGV array in the main program, and the @_
606 array in subroutines.
607 See also unshift(), push() and pop().
608 Shift() and unshift() do the same thing to the left end of an array that push()
609 and pop() do to the right end.
610 .Ip "shutdown(SOCKET,HOW)" 8 3
611 Shuts down a socket connection in the manner indicated by HOW, which has
612 the same interpretation as in the system call of the same name.
615 Returns the sine of EXPR (expressed in radians).
616 If EXPR is omitted, returns sine of $_.
617 .Ip "sleep(EXPR)" 8 6
620 Causes the script to sleep for EXPR seconds, or forever if no EXPR.
621 May be interrupted by sending the process a SIGALARM.
622 Returns the number of seconds actually slept.
623 .Ip "socket(SOCKET,DOMAIN,TYPE,PROTOCOL)" 8 3
624 Opens a socket of the specified kind and attaches it to filehandle SOCKET.
625 DOMAIN, TYPE and PROTOCOL are specified the same as for the system call
627 You may need to run makelib on sys/socket.h to get the proper values handy
628 in a perl library file.
629 Return true if successful.
630 See the example in the section on Interprocess Communication.
631 .Ip "socketpair(SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL)" 8 3
632 Creates an unnamed pair of sockets in the specified domain, of the specified
634 DOMAIN, TYPE and PROTOCOL are specified the same as for the system call
636 If unimplemented, yields a fatal error.
637 Return true if successful.
638 .Ip "sort(SUBROUTINE LIST)" 8 9
640 .Ip "sort SUBROUTINE LIST" 8
642 Sorts the LIST and returns the sorted array value.
643 Nonexistent values of arrays are stripped out.
644 If SUBROUTINE is omitted, sorts in standard string comparison order.
645 If SUBROUTINE is specified, gives the name of a subroutine that returns
646 an integer less than, equal to, or greater than 0,
647 depending on how the elements of the array are to be ordered.
648 In the interests of efficiency the normal calling code for subroutines
649 is bypassed, with the following effects: the subroutine may not be a recursive
650 subroutine, and the two elements to be compared are passed into the subroutine
651 not via @_ but as $a and $b (see example below).
652 They are passed by reference so don't modify $a and $b.
653 SUBROUTINE may be a scalar variable name, in which case the value provides
654 the name of the subroutine to use.
660 $age{$a} - $age{$b}; # presuming integers
662 @sortedclass = sort byage @class;
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\');
669 # prints AbelCaincatdogx
670 print sort reverse @harry;
671 # prints xdogcatCainAbel
672 print sort @george, \'to\', @harry;
673 # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
676 .Ip "split(/PATTERN/,EXPR,LIMIT)" 8 8
677 .Ip "split(/PATTERN/,EXPR)" 8 8
678 .Ip "split(/PATTERN/)" 8
680 Splits 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
683 If EXPR is omitted, splits the $_ string.
684 If PATTERN is also omitted, splits on whitespace (/[\ \et\en]+/).
685 Anything matching PATTERN is taken to be a delimiter separating the fields.
686 (Note that the delimiter may be longer than one character.)
687 If LIMIT is specified, splits into no more than that many fields (though it
688 may split into fewer).
689 If LIMIT is unspecified, trailing null fields are stripped (which
690 potential users of pop() would do well to remember).
691 A pattern matching the null string (not to be confused with a null pattern,
692 which is one member of the set of patterns matching a null string)
693 will split the value of EXPR into separate characters at each point it
698 print join(\':\', split(/ */, \'hi there\'));
701 produces the output \*(L'h:i:t:h:e:r:e\*(R'.
703 The NUM parameter can be used to partially split a line
706 ($login, $passwd, $remainder) = split(\|/\|:\|/\|, $_, 3);
709 (When assigning to a list, if NUM is omitted, perl supplies a NUM one
710 larger than the number of variables in the list, to avoid unnecessary work.
711 For the list above NUM would have been 4 by default.
712 In time critical applications it behooves you not to split into
713 more fields than you really need.)
715 If the PATTERN contains parentheses, additional array elements are created
716 from each matching substring in the delimiter.
718 split(/([,-])/,"1-10,20");
720 produces the array value
724 The pattern /PATTERN/ may be replaced with an expression to specify patterns
725 that vary at runtime.
726 (To do runtime compilation only once, use /$variable/o.)
727 As a special case, specifying a space (\'\ \') will split on white space
728 just as split with no arguments does, but leading white space does NOT
729 produce a null first field.
730 Thus, split(\'\ \') can be used to emulate
732 default behavior, whereas
733 split(/\ /) will give you as many null initial fields as there are
740 open(passwd, \'/etc/passwd\');
743 ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(\|/\|:\|/\|);
746 ($login, $passwd, $uid, $gid, $gcos, $home, $shell)
747 = split(\|/\|:\|/\|);
753 (Note that $shell above will still have a newline on it. See chop().)
756 .Ip "sprintf(FORMAT,LIST)" 8 4
757 Returns a string formatted by the usual printf conventions.
758 The * character is not supported.
761 Return the square root of EXPR.
762 If EXPR is omitted, returns square root of $_.
763 .Ip "srand(EXPR)" 8 4
765 Sets the random number seed for the
768 If EXPR is omitted, does srand(time).
769 .Ip "stat(FILEHANDLE)" 8 8
770 .Ip "stat FILEHANDLE" 8
772 .Ip "stat SCALARVARIABLE" 8
773 Returns a 13-element array giving the statistics for a file, either the file
774 opened via FILEHANDLE, or named by EXPR.
775 Typically used as follows:
779 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
780 $atime,$mtime,$ctime,$blksize,$blocks)
784 If stat is passed the special filehandle consisting of an underline,
785 no stat is done, but the current contents of the stat structure from
786 the last stat or filetest are returned.
791 if (-x $file && (($d) = stat(_)) && $d < 0) {
792 print "$file is executable NFS file\en";
796 .Ip "study(SCALAR)" 8 6
799 Takes extra time to study SCALAR ($_ if unspecified) in anticipation of
800 doing many pattern matches on the string before it is next modified.
801 This may or may not save time, depending on the nature and number of patterns
802 you are searching on, and on the distribution of character frequencies in
803 the string to be searched\*(--you probably want to compare runtimes with and
804 without it to see which runs faster.
805 Those loops which scan for many short constant strings (including the constant
806 parts of more complex patterns) will benefit most.
807 You may have only one study active at a time\*(--if you study a different
808 scalar the first is \*(L"unstudied\*(R".
809 (The way study works is this: a linked list of every character in the string
810 to be searched is made, so we know, for example, where all the \*(L'k\*(R' characters
812 From each search string, the rarest character is selected, based on some
813 static frequency tables constructed from some C programs and English text.
814 Only those places that contain this \*(L"rarest\*(R" character are examined.)
816 For example, here is a loop which inserts index producing entries before any line
817 containing a certain pattern:
823 print ".IX foo\en" if /\ebfoo\eb/;
824 print ".IX bar\en" if /\ebbar\eb/;
825 print ".IX blurfl\en" if /\ebblurfl\eb/;
831 In searching for /\ebfoo\eb/, only those locations in $_ that contain \*(L'f\*(R'
832 will be looked at, because \*(L'f\*(R' is rarer than \*(L'o\*(R'.
833 In general, this is a big win except in pathological cases.
834 The only question is whether it saves you more time than it took to build
835 the linked list in the first place.
837 Note that if you have to look for strings that you don't know till runtime,
838 you can build an entire loop as a string and eval that to avoid recompiling
839 all your patterns all the time.
840 Together with setting $/ to input entire files as one record, this can
841 be very fast, often faster than specialized programs like fgrep.
842 The following scans a list of files (@files)
843 for a list of words (@words), and prints out the names of those files that
848 $search = \'while (<>) { study;\';
849 foreach $word (@words) {
850 $search .= "++\e$seen{\e$ARGV} if /\eb$word\eb/;\en";
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)) {
862 .Ip "substr(EXPR,OFFSET,LEN)" 8 2
863 Extracts a substring out of EXPR and returns it.
864 First character is at offset 0, or whatever you've set $[ to.
865 If OFFSET is negative, starts that far from the end of the string.
866 You can use the substr() function as an lvalue, in which case EXPR must
868 If you assign something shorter than LEN, the string will shrink, and
869 if you assign something longer than LEN, the string will grow to accommodate it.
870 To keep the string the same length you may need to pad or chop your value using
872 .Ip "syscall(LIST)" 8 6
874 Calls the system call specified as the first element of the list, passing
875 the remaining elements as arguments to the system call.
876 If unimplemented, produces a fatal error.
877 The arguments are interpreted as follows: if a given argument is numeric,
878 the argument is passed as an int.
879 If not, the pointer to the string value is passed.
880 You are responsible to make sure a string is pre-extended long enough
881 to receive any result that might be written into a string.
882 If your integer arguments are not literals and have never been interpreted
883 in a numeric context, you may need to add 0 to them to force them to look
887 do 'syscall.h'; # may need to run makelib
888 syscall(&SYS_write, fileno(STDOUT), "hi there\en", 9);
891 .Ip "system(LIST)" 8 6
893 Does exactly the same thing as \*(L"exec LIST\*(R" except that a fork
894 is done first, and the parent process waits for the child process to complete.
895 Note that argument processing varies depending on the number of arguments.
896 The return value is the exit status of the program as returned by the wait()
898 To get the actual exit value divide by 256.
901 .Ip "symlink(OLDFILE,NEWFILE)" 8 2
902 Creates a new filename symbolically linked to the old filename.
903 Returns 1 for success, 0 otherwise.
904 On systems that don't support symbolic links, produces a fatal error at
906 To check for that, use eval:
909 $symlink_exists = (eval \'symlink("","");\', $@ eq \'\');
912 .Ip "tell(FILEHANDLE)" 8 6
913 .Ip "tell FILEHANDLE" 8 6
915 Returns the current file position for FILEHANDLE.
916 FILEHANDLE may be an expression whose value gives the name of the actual
918 If FILEHANDLE is omitted, assumes the file last read.
919 .Ip "telldir(DIRHANDLE)" 8 5
920 .Ip "telldir DIRHANDLE" 8
921 Returns the current position of the readdir() routines on DIRHANDLE.
922 Value may be given to seekdir() to access a particular location in
924 Has the same caveats about possible directory compaction as the corresponding
925 system library routine.
927 Returns the number of non-leap seconds since January 1, 1970, UTC.
928 Suitable for feeding to gmtime() and localtime().
930 Returns a four-element array giving the user and system times, in seconds, for this
931 process and the children of this process.
933 ($user,$system,$cuser,$csystem) = times;
935 .Ip "tr/SEARCHLIST/REPLACEMENTLIST/" 8 5
936 .Ip "y/SEARCHLIST/REPLACEMENTLIST/" 8
937 Translates all occurrences of the characters found in the search list with
938 the corresponding character in the replacement list.
939 It returns the number of characters replaced.
940 If no string is specified via the =~ or !~ operator,
941 the $_ string is translated.
942 (The string specified with =~ must be a scalar variable, an array element,
943 or an assignment to one of those, i.e. an lvalue.)
948 is provided as a synonym for
953 $ARGV[1] \|=~ \|y/A\-Z/a\-z/; \h'|3i'# canonicalize to lower case
955 $cnt = tr/*/*/; \h'|3i'# count the stars in $_
957 ($HOST = $host) =~ tr/a\-z/A\-Z/;
959 y/\e001\-@[\-_{\-\e177/ /; \h'|3i'# change non-alphas to space
962 .Ip "umask(EXPR)" 8 4
965 Sets the umask for the process and returns the old one.
966 If EXPR is omitted, merely returns current umask.
967 .Ip "undef(EXPR)" 8 6
970 Undefines the value of EXPR, which must be an lvalue.
971 Use 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
974 Always returns the undefined value.
975 You can omit the EXPR, in which case nothing is undefined, but you still
976 get an undefined value that you could, for instance, return from a subroutine.
982 undef $bar{'blurfl'};
986 return (wantarray ? () : undef) if $they_blew_it;
989 .Ip "unlink(LIST)" 8 4
991 Deletes a list of files.
992 Returns the number of files successfully deleted.
996 $cnt = unlink \'a\', \'b\', \'c\';
1001 Note: unlink will not delete directories unless you are superuser and the
1005 Even if these conditions are met, be warned that unlinking a directory
1006 can inflict damage on your filesystem.
1008 .Ip "unpack(TEMPLATE,EXPR)" 8 4
1009 Unpack does the reverse of pack: it takes a string representing
1010 a structure and expands it out into an array value, returning the array
1012 The TEMPLATE has the same format as in the pack function.
1013 Here's a subroutine that does substring:
1018 local($what,$where,$howmuch) = @_;
1019 unpack("x$where a$howmuch", $what);
1025 sub ord { unpack("c",$_[0]); }
1028 .Ip "unshift(ARRAY,LIST)" 8 4
1029 Does the opposite of a
1031 Or the opposite of a
1033 depending on how you look at it.
1034 Prepends list to the front of the array, and returns the number of elements
1038 unshift(ARGV, \'\-e\') unless $ARGV[0] =~ /^\-/;
1041 .Ip "utime(LIST)" 8 2
1042 .Ip "utime LIST" 8 2
1043 Changes the access and modification times on each file of a list of files.
1044 The first two elements of the list must be the NUMERICAL access and
1045 modification times, in that order.
1046 Returns the number of files successfully changed.
1047 The inode modification time of each file is set to the current time.
1048 Example of a \*(L"touch\*(R" command:
1054 utime $now, $now, @ARGV;
1057 .Ip "values(ASSOC_ARRAY)" 8 6
1058 .Ip "values ASSOC_ARRAY" 8
1059 Returns a normal array consisting of all the values of the named associative
1061 The values are returned in an apparently random order, but it is the same order
1062 as either the keys() or each() function would produce on the same array.
1063 See also keys() and each().
1064 .Ip "vec(EXPR,OFFSET,BITS)" 8 2
1065 Treats a string as a vector of unsigned integers, and returns the value
1066 of the bitfield specified.
1067 May also be assigned to.
1068 BITS must be a power of two from 1 to 32.
1070 Vectors created with vec() can also be manipulated with the logical operators
1072 which will assume a bit vector operation is desired when both operands are
1074 This interpretation is not enabled unless there is at least one vec() in
1075 your program, to protect older programs.
1077 Waits for a child process to terminate and returns the pid of the deceased
1078 process, or -1 if there are no child processes.
1079 The status is returned in $?.
1080 If you expected a child and didn't find it, you probably had a call to
1081 system, a close on a pipe, or backticks between the fork and the wait.
1082 These constructs also do a wait and may have harvested your child process.
1084 Returns true if the context of the currently executing subroutine
1085 is looking for an array value.
1086 Returns false if the context is looking for a scalar.
1089 return wantarray ? () : undef;
1092 .Ip "warn(LIST)" 8 4
1094 Produces a message on STDERR just like \*(L"die\*(R", but doesn't exit.
1095 .Ip "write(FILEHANDLE)" 8 6
1098 Writes a formatted record (possibly multi-line) to the specified file,
1099 using the format associated with that file.
1100 By default the format for a file is the one having the same name is the
1101 filehandle, but the format for the current output channel (see
1103 may be set explicitly
1104 by assigning the name of the format to the $~ variable.
1106 Top of form processing is handled automatically:
1107 if there is insufficient room on the current page for the formatted
1108 record, the page is advanced, a special top-of-page format is used
1109 to format the new page header, and then the record is written.
1110 By default the top-of-page format is \*(L"top\*(R", but it
1112 format of your choice by assigning the name to the $^ variable.
1114 If FILEHANDLE is unspecified, output goes to the current default output channel,
1117 but may be changed by the
1120 If the FILEHANDLE is an EXPR, then the expression is evaluated and the
1121 resulting string is used to look up the name of the FILEHANDLE at run time.
1122 For more on formats, see the section on formats later on.
1124 Note that write is NOT the opposite of read.