diff options
Diffstat (limited to 'perl.man.3')
| -rw-r--r-- | perl.man.3 | 1453 |
1 files changed, 0 insertions, 1453 deletions
diff --git a/perl.man.3 b/perl.man.3 deleted file mode 100644 index d4574ebd69..0000000000 --- a/perl.man.3 +++ /dev/null @@ -1,1453 +0,0 @@ -''' Beginning of part 3 -''' $Header: perl_man.3,v 3.0.1.12 91/01/11 18:18:15 lwall Locked $ -''' -''' $Log: perl.man.3,v $ -''' Revision 3.0.1.12 91/01/11 18:18:15 lwall -''' patch42: added binary and hex pack/unpack options -''' -''' Revision 3.0.1.11 90/11/10 01:48:21 lwall -''' patch38: random cleanup -''' patch38: documented tr///cds -''' -''' Revision 3.0.1.10 90/10/20 02:15:17 lwall -''' patch37: patch37: fixed various typos in man page -''' -''' Revision 3.0.1.9 90/10/16 10:02:43 lwall -''' patch29: you can now read into the middle string -''' patch29: index and substr now have optional 3rd args -''' patch29: added scalar reverse -''' patch29: added scalar -''' patch29: added SysV IPC -''' patch29: added waitpid -''' patch29: added sysread and syswrite -''' -''' Revision 3.0.1.8 90/08/09 04:39:04 lwall -''' patch19: added require operator -''' patch19: added truncate operator -''' patch19: unpack can do checksumming -''' -''' Revision 3.0.1.7 90/08/03 11:15:42 lwall -''' patch19: Intermediate diffs for Randal -''' -''' Revision 3.0.1.6 90/03/27 16:17:56 lwall -''' patch16: MSDOS support -''' -''' 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 (<STDIN>) { - 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 (<article>) {\|.\|.\|. - -.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 more or less 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 numeric ascii value of the first character of EXPR. -If EXPR is omitted, uses $_. -''' Comments on f & d by gnb@melba.bby.oz.au 22/11/89 -.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 signed 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. - f A single-precision float in the native format. - d A double-precision float in the native format. - p A pointer to a string. - x A null byte. - X Back up a byte. - @ Null fill to absolute position. - u A uuencoded string. - b A bit string (ascending bit order, like vec()). - B A bit string (descending bit order). - h A hex string (low nybble first). - H A hex string (high nybble first). - -.fi -Each letter may optionally be followed by a number which gives a repeat -count. -With all types except "a", "A", "b", "B", "h" and "H", -the pack function will gobble up that many values -from the LIST. -A * for the repeat count means to use however many items are left. -The "a" and "A" types gobble just one value, but pack it as a string of length -count, -padding with nulls or spaces as necessary. -(When unpacking, "A" strips trailing spaces and nulls, but "a" does not.) -Likewise, the "b" and "B" fields pack a string that many bits long. -The "h" and "H" fields pack a string that many nybbles long. -Real numbers (floats and doubles) are in the native machine format -only; due to the multiplicity of floating formats around, and the lack -of a standard \*(L"network\*(R" representation, no facility for -interchange has been made. -This means that packed floating point data -written on one machine may not be readable on another - even if both -use IEEE floating point arithmetic (as the endian-ness of the memory -representation is not part of the IEEE spec). -Note that perl uses -doubles internally for all numeric calculation, and converting from -double -> float -> double will lose precision (i.e. unpack("f", -pack("f", $foo)) will not in general equal $foo). -.br -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) - - sub bintodec { - unpack("N", pack("B32", substr("0" x 32 . shift, -32))); - } -.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 non-alphanumeric 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,OFFSET)" 8 5 -.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, or undef if there was an error. -SCALAR will be grown or shrunk to the length actually read. -An OFFSET may be specified to place the read data at some other place -than the beginning of the string. -This call is actually implemented in terms of stdio's fread call. To get -a true read system call, see sysread. -.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 (<STDIN>) { - while (s|\|({.*}.*\|){.*}|$1 \||) {} - s|{.*}| \||; - if (s|{.*| \||) { - $front = $_; - while (<STDIN>) { - 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 "require(EXPR)" 8 6 -.Ip "require EXPR" 8 -.Ip "require" 8 -Includes the library file specified by EXPR, or by $_ if EXPR is not supplied. -Has semantics similar to the following subroutine: -.nf - - sub require { - local($filename) = @_; - return 1 if $INC{$filename}; - local($realfilename,$result); - ITER: { - foreach $prefix (@INC) { - $realfilename = "$prefix/$filename"; - if (-f $realfilename) { - $result = do $realfilename; - last ITER; - } - } - die "Can't find $filename in \e@INC"; - } - die $@ if $@; - die "$filename did not return true value" unless $result; - $INC{$filename} = $realfilename; - $result; - } - -.fi -Note that the file will not be included twice under the same specified name. -.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 -In an array context, returns an array value consisting of the elements -of LIST in the opposite order. -In a scalar context, returns a string value consisting of the bytes of -the first element 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,POSITION)" 8 6 -.Ip "rindex(STR,SUBSTR)" 8 4 -Works just like index except that it -returns the position of the LAST occurrence of SUBSTR in STR. -If POSITION is specified, returns the last occurrence at or before that -position. -.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 non-alphanumeric 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 "scalar(EXPR)" 8 3 -Forces EXPR to be interpreted in a scalar context and returns the value -of EXPR. -.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 telldir(). -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 "semctl(ID,SEMNUM,CMD,ARG)" 8 4 -Calls the System V IPC function semctl. If CMD is &IPC_STAT or -&GETALL, then ARG must be a variable which will hold the returned -semid_ds structure or semaphore value array. Returns like ioctl: the -undefined value for error, "0 but true" for zero, or the actual return -value otherwise. -.Ip "semget(KEY,NSEMS,SIZE,FLAGS)" 8 4 -Calls the System V IPC function semget. Returns the semaphore id, or -the undefined value if there is an error. -.Ip "semop(KEY,OPSTRING)" 8 4 -Calls the System V IPC function semop to perform semaphore operations -such as signaling and waiting. OPSTRING must be a packed array of -semop structures. Each semop structure can be generated with -\&'pack("sss", $semnum, $semop, $semflag)'. The number of semaphore -operations is implied by the length of OPSTRING. Returns true if -successful, or false if there is an error. As an example, the -following code waits on semaphore $semnum of semaphore id $semid: -.nf - - $semop = pack("sss", $semnum, -1, 0); - die "Semaphore trouble: $!\en" unless semop($semid, $semop); - -.fi -To signal the semaphore, replace "-1" with "1". -.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 "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 "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. -(This is determined lexically.) -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 "shmctl(ID,CMD,ARG)" 8 4 -Calls the System V IPC function shmctl. If CMD is &IPC_STAT, then ARG -must be a variable which will hold the returned shmid_ds structure. -Returns like ioctl: the undefined value for error, "0 but true" for -zero, or the actual return value otherwise. -.Ip "shmget(KEY,SIZE,FLAGS)" 8 4 -Calls the System V IPC function shmget. Returns the shared memory -segment id, or the undefined value if there is an error. -.Ip "shmread(ID,VAR,POS,SIZE)" 8 4 -.Ip "shmwrite(ID,STRING,POS,SIZE)" 8 -Reads or writes the System V shared memory segment ID starting at -position POS for size SIZE by attaching to it, copying in/out, and -detaching from it. When reading, VAR must be a variable which -will hold the data read. When writing, if STRING is too long, -only SIZE bytes are used; if STRING is too short, nulls are -written to fill out SIZE bytes. Return true if successful, or -false if there is an error. -.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 h2ph 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,$#a+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 just 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 (<passwd>) { -.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 -.Ip "substr(EXPR,OFFSET)" 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. -If LEN is omitted, returns everything to 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 "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 "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 - - require 'syscall.ph'; # may need to run h2ph - syscall(&SYS_write, fileno(STDOUT), "hi there\en", 9); - -.fi -.Ip "sysread(FILEHANDLE,SCALAR,LENGTH,OFFSET)" 8 5 -.Ip "sysread(FILEHANDLE,SCALAR,LENGTH)" 8 5 -Attempts to read LENGTH bytes of data into variable SCALAR from the specified -FILEHANDLE, using the system call read(2). -It bypasses stdio, so mixing this with other kinds of reads may cause -confusion. -Returns the number of bytes actually read, or undef if there was an error. -SCALAR will be grown or shrunk to the length actually read. -An OFFSET may be specified to place the read data at some other place -than the beginning of the string. -.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 "syswrite(FILEHANDLE,SCALAR,LENGTH,OFFSET)" 8 5 -.Ip "syswrite(FILEHANDLE,SCALAR,LENGTH)" 8 5 -Attempts to write LENGTH bytes of data from variable SCALAR to the specified -FILEHANDLE, using the system call write(2). -It bypasses stdio, so mixing this with prints may cause -confusion. -Returns the number of bytes actually written, or undef if there was an error. -An OFFSET may be specified to place the read data at some other place -than the beginning of the string. -.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 00:00:00 UTC, January 1, 1970. -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/cds" 8 5 -.Ip "y/SEARCHLIST/REPLACEMENTLIST/cds" 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 or deleted. -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 . -.Sp -If the c modifier is specified, the SEARCHLIST character set is complemented. -If the d modifier is specified, any characters specified by SEARCHLIST that -are not found in REPLACEMENTLIST are deleted. -(Note that this is slightly more flexible than the behavior of some -.I tr -programs, which delete anything they find in the SEARCHLIST, period.) -If the s modifier is specified, sequences of characters that were translated -to the same character are squashed down to 1 instance of the character. -.Sp -If the d modifier was used, the REPLACEMENTLIST is always interpreted exactly -as specified. -Otherwise, if the REPLACEMENTLIST is shorter than the SEARCHLIST, -the final character is replicated till it is long enough. -If the REPLACEMENTLIST is null, the SEARCHLIST is replicated. -This latter is useful for counting characters in a class, or for squashing -character sequences in a class. -.Sp -Examples: -.nf - - $ARGV[1] \|=~ \|y/A\-Z/a\-z/; \h'|3i'# canonicalize to lower case - - $cnt = tr/*/*/; \h'|3i'# count the stars in $_ - - $cnt = tr/0\-9//; \h'|3i'# count the digits in $_ - - tr/a\-zA\-Z//s; \h'|3i'# bookkeeper \-> bokeper - - ($HOST = $host) =~ tr/a\-z/A\-Z/; - - y/a\-zA\-Z/ /cs; \h'|3i'# change non-alphas to single space - - tr/\e200\-\e377/\e0\-\e177/;\h'|3i'# delete 8th bit - -.fi -.Ip "truncate(FILEHANDLE,LENGTH)" 8 4 -.Ip "truncate(EXPR,LENGTH)" 8 -Truncates the file opened on FILEHANDLE, or named by EXPR, to the specified -length. -Produces a fatal error if truncate isn't implemented on your system. -.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. -(In a scalar context, it merely returns the first value produced.) -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 -In addition, you may prefix a field with a %<number> to indicate that -you want a <number>-bit checksum of the items instead of the items themselves. -Default is a 16-bit checksum. -For example, the following computes the same number as the System V sum program: -.nf - -.ne 4 - while (<>) { - $checksum += unpack("%16C*", $_); - } - $checksum %= 65536; - -.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. -.Sp -To transform a bit vector into a string or array of 0's and 1's, use these: -.nf - - $bits = unpack("b*", $vector); - @bits = split(//, unpack("b*", $vector)); - -.fi -If you know the exact length in bits, it can be used in place of the *. -.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 $?. -.Ip "waitpid(PID,FLAGS)" 8 6 -Waits for a particular child process to terminate and returns the pid of the deceased -process, or -1 if there is no such child process. -The status is returned in $?. -If you say -.nf - - require "sys/wait.h"; - .\|.\|. - waitpid(-1,&WNOHANG); - -.fi -then you can do a non-blocking wait for any process. Non-blocking wait -is only available on machines supporting either the -.I waitpid (2) -or -.I wait4 (2) -system calls. -However, waiting for a particular pid with FLAGS of 0 is implemented -everywhere. (Perl emulates the system call by remembering the status -values of processes that have exited but have not been harvested by the -Perl script yet.) -.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. |