''' Beginning of part 3 ''' $Header: perl.man.3,v 3.0.1.5 90/03/12 16:52:21 lwall Locked $ ''' ''' $Log: perl.man.3,v $ ''' Revision 3.0.1.5 90/03/12 16:52:21 lwall ''' patch13: documented that print $filehandle &foo is ambiguous ''' patch13: added splice operator: @oldelems = splice(@array,$offset,$len,LIST) ''' ''' Revision 3.0.1.4 90/02/28 18:00:09 lwall ''' patch9: added pipe function ''' patch9: documented how to handle arbitrary weird characters in filenames ''' patch9: documented the unflushed buffers problem on piped opens ''' patch9: documented how to force top of page ''' ''' Revision 3.0.1.3 89/12/21 20:10:12 lwall ''' patch7: documented that s`pat`repl` does command substitution on replacement ''' patch7: documented that $timeleft from select() is likely not implemented ''' ''' Revision 3.0.1.2 89/11/17 15:31:05 lwall ''' patch5: fixed some manual typos and indent problems ''' patch5: added warning about print making an array context ''' ''' Revision 3.0.1.1 89/11/11 04:45:06 lwall ''' patch2: made some line breaks depend on troff vs. nroff ''' ''' Revision 3.0 89/10/18 15:21:46 lwall ''' 3.0 baseline ''' .Ip "next LABEL" 8 8 .Ip "next" 8 The .I next command is like the .I continue statement in C; it starts the next iteration of the loop: .nf .ne 4 line: while () { next line if /\|^#/; # discard comments .\|.\|. } .fi Note that if there were a .I continue block on the above, it would get executed even on discarded lines. If the LABEL is omitted, the command refers to the innermost enclosing loop. .Ip "oct(EXPR)" 8 4 .Ip "oct EXPR" 8 Returns the decimal value of EXPR interpreted as an octal string. (If EXPR happens to start off with 0x, interprets it as a hex string instead.) The following will handle decimal, octal and hex in the standard notation: .nf $val = oct($val) if $val =~ /^0/; .fi If EXPR is omitted, uses $_. .Ip "open(FILEHANDLE,EXPR)" 8 8 .Ip "open(FILEHANDLE)" 8 .Ip "open FILEHANDLE" 8 Opens the file whose filename is given by EXPR, and associates it with FILEHANDLE. If FILEHANDLE is an expression, its value is used as the name of the real filehandle wanted. If EXPR is omitted, the scalar variable of the same name as the FILEHANDLE contains the filename. If the filename begins with \*(L"<\*(R" or nothing, the file is opened for input. If the filename begins with \*(L">\*(R", the file is opened for output. If the filename begins with \*(L">>\*(R", the file is opened for appending. (You can put a \'+\' in front of the \'>\' or \'<\' to indicate that you want both read and write access to the file.) If the filename begins with \*(L"|\*(R", the filename is interpreted as a command to which output is to be piped, and if the filename ends with a \*(L"|\*(R", the filename is interpreted as command which pipes input to us. (You may not have a command that pipes both in and out.) Opening \'\-\' opens .I STDIN and opening \'>\-\' opens .IR STDOUT . Open returns non-zero upon success, the undefined value otherwise. If the open involved a pipe, the return value happens to be the pid of the subprocess. Examples: .nf .ne 3 $article = 100; open article || die "Can't find article $article: $!\en"; while (
) {\|.\|.\|. .ie t \{\ open(LOG, \'>>/usr/spool/news/twitlog\'\|); # (log is reserved) 'br\} .el \{\ open(LOG, \'>>/usr/spool/news/twitlog\'\|); # (log is reserved) 'br\} .ie t \{\ open(article, "caesar <$article |"\|); # decrypt article 'br\} .el \{\ open(article, "caesar <$article |"\|); # decrypt article 'br\} .ie t \{\ open(extract, "|sort >/tmp/Tmp$$"\|); # $$ is our process# 'br\} .el \{\ open(extract, "|sort >/tmp/Tmp$$"\|); # $$ is our process# 'br\} .ne 7 # process argument list of files along with any includes foreach $file (@ARGV) { do process($file, \'fh00\'); # no pun intended } sub process { local($filename, $input) = @_; $input++; # this is a string increment unless (open($input, $filename)) { print STDERR "Can't open $filename: $!\en"; return; } .ie t \{\ while (<$input>) { # note the use of indirection 'br\} .el \{\ while (<$input>) { # note use of indirection 'br\} if (/^#include "(.*)"/) { do process($1, $input); next; } .\|.\|. # whatever } } .fi You may also, in the Bourne shell tradition, specify an EXPR beginning with \*(L">&\*(R", in which case the rest of the string is interpreted as the name of a filehandle (or file descriptor, if numeric) which is to be duped and opened. You may use & after >, >>, <, +>, +>> and +<. The mode you specify should match the mode of the original filehandle. Here is a script that saves, redirects, and restores .I STDOUT and .IR STDERR : .nf .ne 21 #!/usr/bin/perl open(SAVEOUT, ">&STDOUT"); open(SAVEERR, ">&STDERR"); open(STDOUT, ">foo.out") || die "Can't redirect stdout"; open(STDERR, ">&STDOUT") || die "Can't dup stdout"; select(STDERR); $| = 1; # make unbuffered select(STDOUT); $| = 1; # make unbuffered print STDOUT "stdout 1\en"; # this works for print STDERR "stderr 1\en"; # subprocesses too close(STDOUT); close(STDERR); open(STDOUT, ">&SAVEOUT"); open(STDERR, ">&SAVEERR"); print STDOUT "stdout 2\en"; print STDERR "stderr 2\en"; .fi If you open a pipe on the command \*(L"\-\*(R", i.e. either \*(L"|\-\*(R" or \*(L"\-|\*(R", then there is an implicit fork done, and the return value of open is the pid of the child within the parent process, and 0 within the child process. (Use defined($pid) to determine if the open was successful.) The filehandle behaves normally for the parent, but i/o to that filehandle is piped from/to the .IR STDOUT / STDIN of the child process. In the child process the filehandle isn't opened\*(--i/o happens from/to the new .I STDOUT or .IR STDIN . Typically this is used like the normal piped open when you want to exercise more control over just how the pipe command gets executed, such as when you are running setuid, and don't want to have to scan shell commands for metacharacters. The following pairs are equivalent: .nf .ne 5 open(FOO, "|tr \'[a\-z]\' \'[A\-Z]\'"); open(FOO, "|\-") || exec \'tr\', \'[a\-z]\', \'[A\-Z]\'; open(FOO, "cat \-n $file|"); open(FOO, "\-|") || exec \'cat\', \'\-n\', $file; .fi Explicitly closing any piped filehandle causes the parent process to wait for the child to finish, and returns the status value in $?. Note: on any operation which may do a fork, unflushed buffers remain unflushed in both processes, which means you may need to set $| to avoid duplicate output. .Sp The filename that is passed to open will have leading and trailing whitespace deleted. In order to open a file with arbitrary weird characters in it, it's necessary to protect any leading and trailing whitespace thusly: .nf .ne 2 $file =~ s#^(\es)#./$1#; open(FOO, "< $file\e0"); .fi .Ip "opendir(DIRHANDLE,EXPR)" 8 3 Opens a directory named EXPR for processing by readdir(), telldir(), seekdir(), rewinddir() and closedir(). Returns true if successful. DIRHANDLEs have their own namespace separate from FILEHANDLEs. .Ip "ord(EXPR)" 8 4 .Ip "ord EXPR" 8 Returns the ascii value of the first character of EXPR. If EXPR is omitted, uses $_. .Ip "pack(TEMPLATE,LIST)" 8 4 Takes an array or list of values and packs it into a binary structure, returning the string containing the structure. The TEMPLATE is a sequence of characters that give the order and type of values, as follows: .nf A An ascii string, will be space padded. a An ascii string, will be null padded. c A native char value. C An unsigned char value. s A signed short value. S An unsigned short value. i A signed integer value. I An unsigned integer value. l A signed long value. L An unsigned long value. n A short in \*(L"network\*(R" order. N A long in \*(L"network\*(R" order. p A pointer to a string. x A null byte. .fi Each letter may optionally be followed by a number which gives a repeat count. With all types except "a" and "A" the pack function will gobble up that many values from the LIST. The "a" and "A" types gobble just one value, but pack it as a string that long, padding with nulls or spaces as necessary. (When unpacking, "A" strips trailing spaces and nulls, but "a" does not.) Examples: .nf $foo = pack("cccc",65,66,67,68); # foo eq "ABCD" $foo = pack("c4",65,66,67,68); # same thing $foo = pack("ccxxcc",65,66,67,68); # foo eq "AB\e0\e0CD" $foo = pack("s2",1,2); # "\e1\e0\e2\e0" on little-endian # "\e0\e1\e0\e2" on big-endian $foo = pack("a4","abcd","x","y","z"); # "abcd" $foo = pack("aaaa","abcd","x","y","z"); # "axyz" $foo = pack("a14","abcdefg"); # "abcdefg\e0\e0\e0\e0\e0\e0\e0" $foo = pack("i9pl", gmtime); # a real struct tm (on my system anyway) .fi The same template may generally also be used in the unpack function. .Ip "pipe(READHANDLE,WRITEHANDLE)" 8 3 Opens a pair of connected pipes like the corresponding system call. Note that if you set up a loop of piped processes, deadlock can occur unless you are very careful. In addition, note that perl's pipes use stdio buffering, so you may need to set $| to flush your WRITEHANDLE after each command, depending on the application. [Requires version 3.0 patchlevel 9.] .Ip "pop(ARRAY)" 8 .Ip "pop ARRAY" 8 6 Pops and returns the last value of the array, shortening the array by 1. Has the same effect as .nf $tmp = $ARRAY[$#ARRAY\-\|\-]; .fi If there are no elements in the array, returns the undefined value. .Ip "print(FILEHANDLE LIST)" 8 10 .Ip "print(LIST)" 8 .Ip "print FILEHANDLE LIST" 8 .Ip "print LIST" 8 .Ip "print" 8 Prints a string or a comma-separated list of strings. Returns non-zero if successful. FILEHANDLE may be a scalar variable name, in which case the variable contains the name of the filehandle, thus introducing one level of indirection. (NOTE: If FILEHANDLE is a variable and the next token is a term, it may be misinterpreted as an operator unless you interpose a + or put parens around the arguments.) If FILEHANDLE is omitted, prints by default to standard output (or to the last selected output channel\*(--see select()). If LIST is also omitted, prints $_ to .IR STDOUT . To set the default output channel to something other than .I STDOUT use the select operation. Note that, because print takes a LIST, anything in the LIST is evaluated in an array context, and any subroutine that you call will have one or more of its expressions evaluated in an array context. Also be careful not to follow the print keyword with a left parenthesis unless you want the corresponding right parenthesis to terminate the arguments to the print--interpose a + or put parens around all the arguments. .Ip "printf(FILEHANDLE LIST)" 8 10 .Ip "printf(LIST)" 8 .Ip "printf FILEHANDLE LIST" 8 .Ip "printf LIST" 8 Equivalent to a \*(L"print FILEHANDLE sprintf(LIST)\*(R". .Ip "push(ARRAY,LIST)" 8 7 Treats ARRAY (@ is optional) as a stack, and pushes the values of LIST onto the end of ARRAY. The length of ARRAY increases by the length of LIST. Has the same effect as .nf for $value (LIST) { $ARRAY[++$#ARRAY] = $value; } .fi but is more efficient. .Ip "q/STRING/" 8 5 .Ip "qq/STRING/" 8 These are not really functions, but simply syntactic sugar to let you avoid putting too many backslashes into quoted strings. The q operator is a generalized single quote, and the qq operator a generalized double quote. Any delimiter can be used in place of /, including newline. If the delimiter is an opening bracket or parenthesis, the final delimiter will be the corresponding closing bracket or parenthesis. (Embedded occurrences of the closing bracket need to be backslashed as usual.) Examples: .nf .ne 5 $foo = q!I said, "You said, \'She said it.\'"!; $bar = q(\'This is it.\'); $_ .= qq *** The previous line contains the naughty word "$&".\en if /(ibm|apple|awk)/; # :-) .fi .Ip "rand(EXPR)" 8 8 .Ip "rand EXPR" 8 .Ip "rand" 8 Returns a random fractional number between 0 and the value of EXPR. (EXPR should be positive.) If EXPR is omitted, returns a value between 0 and 1. See also srand(). .Ip "read(FILEHANDLE,SCALAR,LENGTH)" 8 5 Attempts to read LENGTH bytes of data into variable SCALAR from the specified FILEHANDLE. Returns the number of bytes actually read. SCALAR will be grown or shrunk to the length actually read. .Ip "readdir(DIRHANDLE)" 8 3 .Ip "readdir DIRHANDLE" 8 Returns the next directory entry for a directory opened by opendir(). If used in an array context, returns all the rest of the entries in the directory. If there are no more entries, returns an undefined value in a scalar context or a null list in an array context. .Ip "readlink(EXPR)" 8 6 .Ip "readlink EXPR" 8 Returns the value of a symbolic link, if symbolic links are implemented. If not, gives a fatal error. If there is some system error, returns the undefined value and sets $! (errno). If EXPR is omitted, uses $_. .Ip "recv(SOCKET,SCALAR,LEN,FLAGS)" 8 4 Receives a message on a socket. Attempts to receive LENGTH bytes of data into variable SCALAR from the specified SOCKET filehandle. Returns the address of the sender, or the undefined value if there's an error. SCALAR will be grown or shrunk to the length actually read. Takes the same flags as the system call of the same name. .Ip "redo LABEL" 8 8 .Ip "redo" 8 The .I redo command restarts the loop block without evaluating the conditional again. The .I continue block, if any, is not executed. If the LABEL is omitted, the command refers to the innermost enclosing loop. This command is normally used by programs that want to lie to themselves about what was just input: .nf .ne 16 # a simpleminded Pascal comment stripper # (warning: assumes no { or } in strings) line: while () { while (s|\|({.*}.*\|){.*}|$1 \||) {} s|{.*}| \||; if (s|{.*| \||) { $front = $_; while () { if (\|/\|}/\|) { # end of comment? s|^|$front{|; redo line; } } } print; } .fi .Ip "rename(OLDNAME,NEWNAME)" 8 2 Changes the name of a file. Returns 1 for success, 0 otherwise. Will not work across filesystem boundaries. .Ip "reset(EXPR)" 8 6 .Ip "reset EXPR" 8 .Ip "reset" 8 Generally used in a .I continue block at the end of a loop to clear variables and reset ?? searches so that they work again. The expression is interpreted as a list of single characters (hyphens allowed for ranges). All variables and arrays beginning with one of those letters are reset to their pristine state. If the expression is omitted, one-match searches (?pattern?) are reset to match again. Only resets variables or searches in the current package. Always returns 1. Examples: .nf .ne 3 reset \'X\'; \h'|2i'# reset all X variables reset \'a\-z\';\h'|2i'# reset lower case variables reset; \h'|2i'# just reset ?? searches .fi Note: resetting \*(L"A\-Z\*(R" is not recommended since you'll wipe out your ARGV and ENV arrays. .Sp The use of reset on dbm associative arrays does not change the dbm file. (It does, however, flush any entries cached by perl, which may be useful if you are sharing the dbm file. Then again, maybe not.) .Ip "return LIST" 8 3 Returns from a subroutine with the value specified. (Note that a subroutine can automatically return the value of the last expression evaluated. That's the preferred method\*(--use of an explicit .I return is a bit slower.) .Ip "reverse(LIST)" 8 4 .Ip "reverse LIST" 8 Returns an array value consisting of the elements of LIST in the opposite order. .Ip "rewinddir(DIRHANDLE)" 8 5 .Ip "rewinddir DIRHANDLE" 8 Sets the current position to the beginning of the directory for the readdir() routine on DIRHANDLE. .Ip "rindex(STR,SUBSTR)" 8 4 Works just like index except that it returns the position of the LAST occurrence of SUBSTR in STR. .Ip "rmdir(FILENAME)" 8 4 .Ip "rmdir FILENAME" 8 Deletes the directory specified by FILENAME if it is empty. If it succeeds it returns 1, otherwise it returns 0 and sets $! (errno). If FILENAME is omitted, uses $_. .Ip "s/PATTERN/REPLACEMENT/gieo" 8 3 Searches a string for a pattern, and if found, replaces that pattern with the replacement text and returns the number of substitutions made. Otherwise it returns false (0). The \*(L"g\*(R" is optional, and if present, indicates that all occurrences of the pattern are to be replaced. The \*(L"i\*(R" is also optional, and if present, indicates that matching is to be done in a case-insensitive manner. The \*(L"e\*(R" is likewise optional, and if present, indicates that the replacement string is to be evaluated as an expression rather than just as a double-quoted string. Any delimiter may replace the slashes; if single quotes are used, no interpretation is done on the replacement string (the e modifier overrides this, however); if backquotes are used, the replacement string is a command to execute whose output will be used as the actual replacement text. If no string is specified via the =~ or !~ operator, the $_ string is searched and modified. (The string specified with =~ must be a scalar variable, an array element, or an assignment to one of those, i.e. an lvalue.) If the pattern contains a $ that looks like a variable rather than an end-of-string test, the variable will be interpolated into the pattern at run-time. If you only want the pattern compiled once the first time the variable is interpolated, add an \*(L"o\*(R" at the end. See also the section on regular expressions. Examples: .nf s/\|\e\|bgreen\e\|b/mauve/g; # don't change wintergreen $path \|=~ \|s|\|/usr/bin|\|/usr/local/bin|; s/Login: $foo/Login: $bar/; # run-time pattern ($foo = $bar) =~ s/bar/foo/; $_ = \'abc123xyz\'; s/\ed+/$&*2/e; # yields \*(L'abc246xyz\*(R' s/\ed+/sprintf("%5d",$&)/e; # yields \*(L'abc 246xyz\*(R' s/\ew/$& x 2/eg; # yields \*(L'aabbcc 224466xxyyzz\*(R' s/\|([^ \|]*\|) *\|([^ \|]*\|)\|/\|$2 $1/; # reverse 1st two fields .fi (Note the use of $ instead of \|\e\| in the last example. See section on regular expressions.) .Ip "seek(FILEHANDLE,POSITION,WHENCE)" 8 3 Randomly positions the file pointer for FILEHANDLE, just like the fseek() call of stdio. FILEHANDLE may be an expression whose value gives the name of the filehandle. Returns 1 upon success, 0 otherwise. .Ip "seekdir(DIRHANDLE,POS)" 8 3 Sets the current position for the readdir() routine on DIRHANDLE. POS must be a value returned by seekdir(). Has the same caveats about possible directory compaction as the corresponding system library routine. .Ip "select(FILEHANDLE)" 8 3 .Ip "select" 8 3 Returns the currently selected filehandle. Sets the current default filehandle for output, if FILEHANDLE is supplied. This has two effects: first, a .I write or a .I print without a filehandle will default to this FILEHANDLE. Second, references to variables related to output will refer to this output channel. For example, if you have to set the top of form format for more than one output channel, you might do the following: .nf .ne 4 select(REPORT1); $^ = \'report1_top\'; select(REPORT2); $^ = \'report2_top\'; .fi FILEHANDLE may be an expression whose value gives the name of the actual filehandle. Thus: .nf $oldfh = select(STDERR); $| = 1; select($oldfh); .fi .Ip "select(RBITS,WBITS,EBITS,TIMEOUT)" 8 3 This calls the select system call with the bitmasks specified, which can be constructed using fileno() and vec(), along these lines: .nf $rin = $win = $ein = ''; vec($rin,fileno(STDIN),1) = 1; vec($win,fileno(STDOUT),1) = 1; $ein = $rin | $win; .fi If you want to select on many filehandles you might wish to write a subroutine: .nf sub fhbits { local(@fhlist) = split(' ',$_[0]); local($bits); for (@fhlist) { vec($bits,fileno($_),1) = 1; } $bits; } $rin = &fhbits('STDIN TTY SOCK'); .fi The usual idiom is: .nf ($nfound,$timeleft) = select($rout=$rin, $wout=$win, $eout=$ein, $timeout); or to block until something becomes ready: .ie t \{\ $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef); 'br\} .el \{\ $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef); 'br\} .fi Any of the bitmasks can also be undef. The timeout, if specified, is in seconds, which may be fractional. NOTE: not all implementations are capable of returning the $timeleft. If not, they always return $timeleft equal to the supplied $timeout. .Ip "setpgrp(PID,PGRP)" 8 4 Sets the current process group for the specified PID, 0 for the current process. Will produce a fatal error if used on a machine that doesn't implement setpgrp(2). .Ip "send(SOCKET,MSG,FLAGS,TO)" 8 4 .Ip "send(SOCKET,MSG,FLAGS)" 8 Sends a message on a socket. Takes the same flags as the system call of the same name. On unconnected sockets you must specify a destination to send TO. Returns the number of characters sent, or the undefined value if there is an error. .Ip "setpriority(WHICH,WHO,PRIORITY)" 8 4 Sets the current priority for a process, a process group, or a user. (See setpriority(2).) Will produce a fatal error if used on a machine that doesn't implement setpriority(2). .Ip "setsockopt(SOCKET,LEVEL,OPTNAME,OPTVAL)" 8 3 Sets the socket option requested. Returns undefined if there is an error. OPTVAL may be specified as undef if you don't want to pass an argument. .Ip "shift(ARRAY)" 8 6 .Ip "shift ARRAY" 8 .Ip "shift" 8 Shifts the first value of the array off and returns it, shortening the array by 1 and moving everything down. If there are no elements in the array, returns the undefined value. If ARRAY is omitted, shifts the @ARGV array in the main program, and the @_ array in subroutines. See also unshift(), push() and pop(). Shift() and unshift() do the same thing to the left end of an array that push() and pop() do to the right end. .Ip "shutdown(SOCKET,HOW)" 8 3 Shuts down a socket connection in the manner indicated by HOW, which has the same interpretation as in the system call of the same name. .Ip "sin(EXPR)" 8 4 .Ip "sin EXPR" 8 Returns the sine of EXPR (expressed in radians). If EXPR is omitted, returns sine of $_. .Ip "sleep(EXPR)" 8 6 .Ip "sleep EXPR" 8 .Ip "sleep" 8 Causes the script to sleep for EXPR seconds, or forever if no EXPR. May be interrupted by sending the process a SIGALARM. Returns the number of seconds actually slept. .Ip "socket(SOCKET,DOMAIN,TYPE,PROTOCOL)" 8 3 Opens a socket of the specified kind and attaches it to filehandle SOCKET. DOMAIN, TYPE and PROTOCOL are specified the same as for the system call of the same name. You may need to run makelib on sys/socket.h to get the proper values handy in a perl library file. Return true if successful. See the example in the section on Interprocess Communication. .Ip "socketpair(SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL)" 8 3 Creates an unnamed pair of sockets in the specified domain, of the specified type. DOMAIN, TYPE and PROTOCOL are specified the same as for the system call of the same name. If unimplemented, yields a fatal error. Return true if successful. .Ip "sort(SUBROUTINE LIST)" 8 9 .Ip "sort(LIST)" 8 .Ip "sort SUBROUTINE LIST" 8 .Ip "sort LIST" 8 Sorts the LIST and returns the sorted array value. Nonexistent values of arrays are stripped out. If SUBROUTINE is omitted, sorts in standard string comparison order. If SUBROUTINE is specified, gives the name of a subroutine that returns an integer less than, equal to, or greater than 0, depending on how the elements of the array are to be ordered. In the interests of efficiency the normal calling code for subroutines is bypassed, with the following effects: the subroutine may not be a recursive subroutine, and the two elements to be compared are passed into the subroutine not via @_ but as $a and $b (see example below). They are passed by reference so don't modify $a and $b. SUBROUTINE may be a scalar variable name, in which case the value provides the name of the subroutine to use. Examples: .nf .ne 4 sub byage { $age{$a} - $age{$b}; # presuming integers } @sortedclass = sort byage @class; .ne 9 sub reverse { $a lt $b ? 1 : $a gt $b ? \-1 : 0; } @harry = (\'dog\',\'cat\',\'x\',\'Cain\',\'Abel\'); @george = (\'gone\',\'chased\',\'yz\',\'Punished\',\'Axed\'); print sort @harry; # prints AbelCaincatdogx print sort reverse @harry; # prints xdogcatCainAbel print sort @george, \'to\', @harry; # prints AbelAxedCainPunishedcatchaseddoggonetoxyz .fi .Ip "splice(ARRAY,OFFSET,LENGTH,LIST)" 8 8 .Ip "splice(ARRAY,OFFSET,LENGTH)" 8 .Ip "splice(ARRAY,OFFSET)" 8 Removes the elements designated by OFFSET and LENGTH from an array, and replaces them with the elements of LIST, if any. Returns the elements removed from the array. The array grows or shrinks as necessary. If LENGTH is omitted, removes everything from OFFSET onward. The following equivalencies hold (assuming $[ == 0): .nf push(@a,$x,$y)\h'|3.5i'splice(@a,$#x+1,0,$x,$y) pop(@a)\h'|3.5i'splice(@a,-1) shift(@a)\h'|3.5i'splice(@a,0,1) unshift(@a,$x,$y)\h'|3.5i'splice(@a,0,0,$x,$y) $a[$x] = $y\h'|3.5i'splice(@a,$x,1,$y); Example, assuming array lengths are passed before arrays: sub aeq { # compare two array values local(@a) = splice(@_,0,shift); local(@b) = splice(@_,0,shift); return 0 unless @a == @b; # same len? while (@a) { return 0 if pop(@a) ne pop(@b); } return 1; } if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... } .fi .Ip "split(/PATTERN/,EXPR,LIMIT)" 8 8 .Ip "split(/PATTERN/,EXPR)" 8 8 .Ip "split(/PATTERN/)" 8 .Ip "split" 8 Splits a string into an array of strings, and returns it. (If not in an array context, returns the number of fields found and splits into the @_ array. (In an array context, you can force the split into @_ by using ?? as the pattern delimiters, but it still returns the array value.)) If EXPR is omitted, splits the $_ string. If PATTERN is also omitted, splits on whitespace (/[\ \et\en]+/). Anything matching PATTERN is taken to be a delimiter separating the fields. (Note that the delimiter may be longer than one character.) If LIMIT is specified, splits into no more than that many fields (though it may split into fewer). If LIMIT is unspecified, trailing null fields are stripped (which potential users of pop() would do well to remember). A pattern matching the null string (not to be confused with a null pattern, which is one member of the set of patterns matching a null string) will split the value of EXPR into separate characters at each point it matches that way. For example: .nf print join(\':\', split(/ */, \'hi there\')); .fi produces the output \*(L'h:i:t:h:e:r:e\*(R'. .Sp The LIMIT parameter can be used to partially split a line .nf ($login, $passwd, $remainder) = split(\|/\|:\|/\|, $_, 3); .fi (When assigning to a list, if LIMIT is omitted, perl supplies a LIMIT one larger than the number of variables in the list, to avoid unnecessary work. For the list above LIMIT would have been 4 by default. In time critical applications it behooves you not to split into more fields than you really need.) .Sp If the PATTERN contains parentheses, additional array elements are created from each matching substring in the delimiter. .Sp split(/([,-])/,"1-10,20"); .Sp produces the array value .Sp (1,'-',10,',',20) .Sp The pattern /PATTERN/ may be replaced with an expression to specify patterns that vary at runtime. (To do runtime compilation only once, use /$variable/o.) As a special case, specifying a space (\'\ \') will split on white space just as split with no arguments does, but leading white space does NOT produce a null first field. Thus, split(\'\ \') can be used to emulate .IR awk 's default behavior, whereas split(/\ /) will give you as many null initial fields as there are leading spaces. .Sp Example: .nf .ne 5 open(passwd, \'/etc/passwd\'); while () { .ie t \{\ ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(\|/\|:\|/\|); 'br\} .el \{\ ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(\|/\|:\|/\|); 'br\} .\|.\|. } .fi (Note that $shell above will still have a newline on it. See chop().) See also .IR join . .Ip "sprintf(FORMAT,LIST)" 8 4 Returns a string formatted by the usual printf conventions. The * character is not supported. .Ip "sqrt(EXPR)" 8 4 .Ip "sqrt EXPR" 8 Return the square root of EXPR. If EXPR is omitted, returns square root of $_. .Ip "srand(EXPR)" 8 4 .Ip "srand EXPR" 8 Sets the random number seed for the .I rand operator. If EXPR is omitted, does srand(time). .Ip "stat(FILEHANDLE)" 8 8 .Ip "stat FILEHANDLE" 8 .Ip "stat(EXPR)" 8 .Ip "stat SCALARVARIABLE" 8 Returns a 13-element array giving the statistics for a file, either the file opened via FILEHANDLE, or named by EXPR. Typically used as follows: .nf .ne 3 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size, $atime,$mtime,$ctime,$blksize,$blocks) = stat($filename); .fi If stat is passed the special filehandle consisting of an underline, no stat is done, but the current contents of the stat structure from the last stat or filetest are returned. Example: .nf .ne 3 if (-x $file && (($d) = stat(_)) && $d < 0) { print "$file is executable NFS file\en"; } .fi .Ip "study(SCALAR)" 8 6 .Ip "study SCALAR" 8 .Ip "study" Takes extra time to study SCALAR ($_ if unspecified) in anticipation of doing many pattern matches on the string before it is next modified. This may or may not save time, depending on the nature and number of patterns you are searching on, and on the distribution of character frequencies in the string to be searched\*(--you probably want to compare runtimes with and without it to see which runs faster. Those loops which scan for many short constant strings (including the constant parts of more complex patterns) will benefit most. You may have only one study active at a time\*(--if you study a different scalar the first is \*(L"unstudied\*(R". (The way study works is this: a linked list of every character in the string to be searched is made, so we know, for example, where all the \*(L'k\*(R' characters are. From each search string, the rarest character is selected, based on some static frequency tables constructed from some C programs and English text. Only those places that contain this \*(L"rarest\*(R" character are examined.) .Sp For example, here is a loop which inserts index producing entries before any line containing a certain pattern: .nf .ne 8 while (<>) { study; print ".IX foo\en" if /\ebfoo\eb/; print ".IX bar\en" if /\ebbar\eb/; print ".IX blurfl\en" if /\ebblurfl\eb/; .\|.\|. print; } .fi In searching for /\ebfoo\eb/, only those locations in $_ that contain \*(L'f\*(R' will be looked at, because \*(L'f\*(R' is rarer than \*(L'o\*(R'. In general, this is a big win except in pathological cases. The only question is whether it saves you more time than it took to build the linked list in the first place. .Sp Note that if you have to look for strings that you don't know till runtime, you can build an entire loop as a string and eval that to avoid recompiling all your patterns all the time. Together with setting $/ to input entire files as one record, this can be very fast, often faster than specialized programs like fgrep. The following scans a list of files (@files) for a list of words (@words), and prints out the names of those files that contain a match: .nf .ne 12 $search = \'while (<>) { study;\'; foreach $word (@words) { $search .= "++\e$seen{\e$ARGV} if /\eb$word\eb/;\en"; } $search .= "}"; @ARGV = @files; $/ = "\e177"; # something that doesn't occur eval $search; # this screams $/ = "\en"; # put back to normal input delim foreach $file (sort keys(%seen)) { print $file, "\en"; } .fi .Ip "substr(EXPR,OFFSET,LEN)" 8 2 Extracts a substring out of EXPR and returns it. First character is at offset 0, or whatever you've set $[ to. If OFFSET is negative, starts that far from the end of the string. You can use the substr() function as an lvalue, in which case EXPR must be an lvalue. If you assign something shorter than LEN, the string will shrink, and if you assign something longer than LEN, the string will grow to accommodate it. To keep the string the same length you may need to pad or chop your value using sprintf(). .Ip "syscall(LIST)" 8 6 .Ip "syscall LIST" 8 Calls the system call specified as the first element of the list, passing the remaining elements as arguments to the system call. If unimplemented, produces a fatal error. The arguments are interpreted as follows: if a given argument is numeric, the argument is passed as an int. If not, the pointer to the string value is passed. You are responsible to make sure a string is pre-extended long enough to receive any result that might be written into a string. If your integer arguments are not literals and have never been interpreted in a numeric context, you may need to add 0 to them to force them to look like numbers. .nf do 'syscall.h'; # may need to run makelib syscall(&SYS_write, fileno(STDOUT), "hi there\en", 9); .fi .Ip "system(LIST)" 8 6 .Ip "system LIST" 8 Does exactly the same thing as \*(L"exec LIST\*(R" except that a fork is done first, and the parent process waits for the child process to complete. Note that argument processing varies depending on the number of arguments. The return value is the exit status of the program as returned by the wait() call. To get the actual exit value divide by 256. See also .IR exec . .Ip "symlink(OLDFILE,NEWFILE)" 8 2 Creates a new filename symbolically linked to the old filename. Returns 1 for success, 0 otherwise. On systems that don't support symbolic links, produces a fatal error at run time. To check for that, use eval: .nf $symlink_exists = (eval \'symlink("","");\', $@ eq \'\'); .fi .Ip "tell(FILEHANDLE)" 8 6 .Ip "tell FILEHANDLE" 8 6 .Ip "tell" 8 Returns the current file position for FILEHANDLE. FILEHANDLE may be an expression whose value gives the name of the actual filehandle. If FILEHANDLE is omitted, assumes the file last read. .Ip "telldir(DIRHANDLE)" 8 5 .Ip "telldir DIRHANDLE" 8 Returns the current position of the readdir() routines on DIRHANDLE. Value may be given to seekdir() to access a particular location in a directory. Has the same caveats about possible directory compaction as the corresponding system library routine. .Ip "time" 8 4 Returns the number of non-leap seconds since January 1, 1970, UTC. Suitable for feeding to gmtime() and localtime(). .Ip "times" 8 4 Returns a four-element array giving the user and system times, in seconds, for this process and the children of this process. .Sp ($user,$system,$cuser,$csystem) = times; .Sp .Ip "tr/SEARCHLIST/REPLACEMENTLIST/" 8 5 .Ip "y/SEARCHLIST/REPLACEMENTLIST/" 8 Translates all occurrences of the characters found in the search list with the corresponding character in the replacement list. It returns the number of characters replaced. If no string is specified via the =~ or !~ operator, the $_ string is translated. (The string specified with =~ must be a scalar variable, an array element, or an assignment to one of those, i.e. an lvalue.) For .I sed devotees, .I y is provided as a synonym for .IR tr . Examples: .nf $ARGV[1] \|=~ \|y/A\-Z/a\-z/; \h'|3i'# canonicalize to lower case $cnt = tr/*/*/; \h'|3i'# count the stars in $_ ($HOST = $host) =~ tr/a\-z/A\-Z/; y/\e001\-@[\-_{\-\e177/ /; \h'|3i'# change non-alphas to space .fi .Ip "umask(EXPR)" 8 4 .Ip "umask EXPR" 8 .Ip "umask" 8 Sets the umask for the process and returns the old one. If EXPR is omitted, merely returns current umask. .Ip "undef(EXPR)" 8 6 .Ip "undef EXPR" 8 .Ip "undef" 8 Undefines the value of EXPR, which must be an lvalue. Use only on a scalar value, an entire array, or a subroutine name (using &). (Undef will probably not do what you expect on most predefined variables or dbm array values.) Always returns the undefined value. You can omit the EXPR, in which case nothing is undefined, but you still get an undefined value that you could, for instance, return from a subroutine. Examples: .nf .ne 6 undef $foo; undef $bar{'blurfl'}; undef @ary; undef %assoc; undef &mysub; return (wantarray ? () : undef) if $they_blew_it; .fi .Ip "unlink(LIST)" 8 4 .Ip "unlink LIST" 8 Deletes a list of files. Returns the number of files successfully deleted. .nf .ne 2 $cnt = unlink \'a\', \'b\', \'c\'; unlink @goners; unlink <*.bak>; .fi Note: unlink will not delete directories unless you are superuser and the .B \-U flag is supplied to .IR perl . Even if these conditions are met, be warned that unlinking a directory can inflict damage on your filesystem. Use rmdir instead. .Ip "unpack(TEMPLATE,EXPR)" 8 4 Unpack does the reverse of pack: it takes a string representing a structure and expands it out into an array value, returning the array value. The TEMPLATE has the same format as in the pack function. Here's a subroutine that does substring: .nf .ne 4 sub substr { local($what,$where,$howmuch) = @_; unpack("x$where a$howmuch", $what); } .ne 3 and then there's sub ord { unpack("c",$_[0]); } .fi .Ip "unshift(ARRAY,LIST)" 8 4 Does the opposite of a .IR shift . Or the opposite of a .IR push , depending on how you look at it. Prepends list to the front of the array, and returns the number of elements in the new array. .nf unshift(ARGV, \'\-e\') unless $ARGV[0] =~ /^\-/; .fi .Ip "utime(LIST)" 8 2 .Ip "utime LIST" 8 2 Changes the access and modification times on each file of a list of files. The first two elements of the list must be the NUMERICAL access and modification times, in that order. Returns the number of files successfully changed. The inode modification time of each file is set to the current time. Example of a \*(L"touch\*(R" command: .nf .ne 3 #!/usr/bin/perl $now = time; utime $now, $now, @ARGV; .fi .Ip "values(ASSOC_ARRAY)" 8 6 .Ip "values ASSOC_ARRAY" 8 Returns a normal array consisting of all the values of the named associative array. The values are returned in an apparently random order, but it is the same order as either the keys() or each() function would produce on the same array. See also keys() and each(). .Ip "vec(EXPR,OFFSET,BITS)" 8 2 Treats a string as a vector of unsigned integers, and returns the value of the bitfield specified. May also be assigned to. BITS must be a power of two from 1 to 32. .Sp Vectors created with vec() can also be manipulated with the logical operators |, & and ^, which will assume a bit vector operation is desired when both operands are strings. This interpretation is not enabled unless there is at least one vec() in your program, to protect older programs. .Ip "wait" 8 6 Waits for a child process to terminate and returns the pid of the deceased process, or -1 if there are no child processes. The status is returned in $?. If you expected a child and didn't find it, you probably had a call to system, a close on a pipe, or backticks between the fork and the wait. These constructs also do a wait and may have harvested your child process. .Ip "wantarray" 8 4 Returns true if the context of the currently executing subroutine is looking for an array value. Returns false if the context is looking for a scalar. .nf return wantarray ? () : undef; .fi .Ip "warn(LIST)" 8 4 .Ip "warn LIST" 8 Produces a message on STDERR just like \*(L"die\*(R", but doesn't exit. .Ip "write(FILEHANDLE)" 8 6 .Ip "write(EXPR)" 8 .Ip "write" 8 Writes a formatted record (possibly multi-line) to the specified file, using the format associated with that file. By default the format for a file is the one having the same name is the filehandle, but the format for the current output channel (see .IR select ) may be set explicitly by assigning the name of the format to the $~ variable. .Sp Top of form processing is handled automatically: if there is insufficient room on the current page for the formatted record, the page is advanced by writing a form feed, a special top-of-page format is used to format the new page header, and then the record is written. By default the top-of-page format is \*(L"top\*(R", but it may be set to the format of your choice by assigning the name to the $^ variable. The number of lines remaining on the current page is in variable $-, which can be set to 0 to force a new page. .Sp If FILEHANDLE is unspecified, output goes to the current default output channel, which starts out as .I STDOUT but may be changed by the .I select operator. If the FILEHANDLE is an EXPR, then the expression is evaluated and the resulting string is used to look up the name of the FILEHANDLE at run time. For more on formats, see the section on formats later on. .Sp Note that write is NOT the opposite of read.