diff options
Diffstat (limited to 'pod/perlfunc.pod')
| -rw-r--r-- | pod/perlfunc.pod | 2896 |
1 files changed, 2896 insertions, 0 deletions
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod new file mode 100644 index 0000000000..d5aa3aa0b3 --- /dev/null +++ b/pod/perlfunc.pod @@ -0,0 +1,2896 @@ +=head1 NAME + +perlfunc - Perl builtin functions + +=head1 DESCRIPTION + +The functions in this section can serve as terms in an expression. +They fall into two major categories: list operators and named unary +operators. These differ in their precedence relationship with a +following comma. (See the precedence table in L<perlop>.) List +operators take more than one argument, while unary operators can never +take more than one argument. Thus, a comma terminates the argument of +a unary operator, but merely separates the arguments of a list +operator. A unary operator generally provides a scalar context to its +argument, while a list operator may provide either scalar and list +contexts for its arguments. If it does both, the scalar arguments will +be first, and the list argument will follow. (Note that there can only +ever be one list argument.) For instance, splice() has three scalar +arguments followed by a list. + +In the syntax descriptions that follow, list operators that expect a +list (and provide list context for the elements of the list) are shown +with LIST as an argument. Such a list may consist of any combination +of scalar arguments or list values; the list values will be included +in the list as if each individual element were interpolated at that +point in the list, forming a longer single-dimensional list value. +Elements of the LIST should be separated by commas. + +Any function in the list below may be used either with or without +parentheses around its arguments. (The syntax descriptions omit the +parens.) If you use the parens, the simple (but occasionally +surprising) rule is this: It I<LOOKS> like a function, therefore it I<IS> a +function, and precedence doesn't matter. Otherwise it's a list +operator or unary operator, and precedence does matter. And whitespace +between the function and left parenthesis doesn't count--so you need to +be careful sometimes: + + print 1+2+3; # Prints 6. + print(1+2) + 3; # Prints 3. + print (1+2)+3; # Also prints 3! + print +(1+2)+3; # Prints 6. + print ((1+2)+3); # Prints 6. + +If you run Perl with the B<-w> switch it can warn you about this. For +example, the third line above produces: + + print (...) interpreted as function at - line 1. + Useless use of integer addition in void context at - line 1. + +For functions that can be used in either a scalar or list context, +non-abortive failure is generally indicated in a scalar context by +returning the undefined value, and in a list context by returning the +null list. + +Remember the following rule: + +=over 5 + +=item * + +I<THERE IS NO GENERAL RULE FOR CONVERTING A LIST INTO A SCALAR!> + +=back + +Each operator and function decides which sort of value it would be most +appropriate to return in a scalar context. Some operators return the +length of the list that would have been returned in a list context. Some +operators return the first value in the list. Some operators return the +last value in the list. Some operators return a count of successful +operations. In general, they do what you want, unless you want +consistency. + +=over 8 + +=item -X FILEHANDLE + +=item -X EXPR + +=item -X + +A file test, where X is one of the letters listed below. This unary +operator takes one argument, either a filename or a filehandle, and +tests the associated file to see if something is true about it. If the +argument is omitted, tests $_, except for C<-t>, which tests STDIN. +Unless otherwise documented, it returns C<1> for TRUE and C<''> for FALSE, or +the undefined value if the file doesn't exist. Despite the funny +names, precedence is the same as any other named unary operator, and +the argument may be parenthesized like any other unary operator. The +operator may be any of: + + -r File is readable by effective uid/gid. + -w File is writable by effective uid/gid. + -x File is executable by effective uid/gid. + -o File is owned by effective uid. + + -R File is readable by real uid/gid. + -W File is writable by real uid/gid. + -X File is executable by real uid/gid. + -O File is owned by real uid. + + -e File exists. + -z File has zero size. + -s File has non-zero size (returns size). + + -f File is a plain file. + -d File is a directory. + -l File is a symbolic link. + -p File is a named pipe (FIFO). + -S File is a socket. + -b File is a block special file. + -c File is a character special file. + -t Filehandle is opened to a tty. + + -u File has setuid bit set. + -g File has setgid bit set. + -k File has sticky bit set. + + -T File is a text file. + -B File is a binary file (opposite of -T). + + -M Age of file in days when script started. + -A Same for access time. + -C Same for inode change time. + +The interpretation of the file permission operators C<-r>, C<-R>, C<-w>, +C<-W>, C<-x> and C<-X> is based solely on the mode of the file and the +uids and gids of the user. There may be other reasons you can't actually +read, write or execute the file. Also note that, for the superuser, +C<-r>, C<-R>, C<-w> and C<-W> always return 1, and C<-x> and C<-X> return +1 if any execute bit is set in the mode. Scripts run by the superuser may +thus need to do a stat() in order to determine the actual mode of the +file, or temporarily set the uid to something else. + +Example: + + while (<>) { + chop; + next unless -f $_; # ignore specials + ... + } + +Note that C<-s/a/b/> does not do a negated substitution. Saying +C<-exp($foo)> still works as expected, however--only single letters +following a minus are interpreted as file tests. + +The C<-T> and C<-B> switches work as follows. The first block or so of the +file is examined for odd characters such as strange control codes or +characters with the high bit set. If too many odd characters (>30%) +are found, it's a C<-B> file, otherwise it's a C<-T> file. Also, any file +containing null in the first block is considered a binary file. If C<-T> +or C<-B> is used on a filehandle, the current stdio buffer is examined +rather than the first block. Both C<-T> and C<-B> return TRUE on a null +file, or a file at EOF when testing a filehandle. + +If any of the file tests (or either the stat() or lstat() operators) are given the +special filehandle consisting of a solitary underline, then the stat +structure of the previous file test (or stat operator) is used, saving +a system call. (This doesn't work with C<-t>, and you need to remember +that lstat() and C<-l> will leave values in the stat structure for the +symbolic link, not the real file.) Example: + + print "Can do.\n" if -r $a || -w _ || -x _; + + stat($filename); + print "Readable\n" if -r _; + print "Writable\n" if -w _; + print "Executable\n" if -x _; + print "Setuid\n" if -u _; + print "Setgid\n" if -g _; + print "Sticky\n" if -k _; + print "Text\n" if -T _; + print "Binary\n" if -B _; + +=item abs VALUE + +Returns the absolute value of its argument. + +=item accept NEWSOCKET,GENERICSOCKET + +Accepts an incoming socket connect, just as the accept(2) system call +does. Returns the packed address if it succeeded, FALSE otherwise. +See example in L<perlipc>. + +=item alarm SECONDS + +Arranges to have a SIGALRM delivered to this process after the +specified number of seconds have elapsed. (On some machines, +unfortunately, the elapsed time may be up to one second less than you +specified because of how seconds are counted.) Only one timer may be +counting at once. Each call disables the previous timer, and an +argument of 0 may be supplied to cancel the previous timer without +starting a new one. The returned value is the amount of time remaining +on the previous timer. + +For sleeps of finer granularity than one second, you may use Perl's +syscall() interface to access setitimer(2) if your system supports it, +or else see L</select()> below. + +=item atan2 Y,X + +Returns the arctangent of Y/X in the range -PI to PI. + +=item bind SOCKET,NAME + +Binds a network address to a socket, just as the bind system call +does. Returns TRUE if it succeeded, FALSE otherwise. NAME should be a +packed address of the appropriate type for the socket. See example in +L<perlipc>. + +=item binmode FILEHANDLE + +Arranges for the file to be read or written in "binary" mode in +operating systems that distinguish between binary and text files. +Files that are not in binary mode have CR LF sequences translated to LF +on input and LF translated to CR LF on output. Binmode has no effect +under Unix; in DOS, it may be imperative. If FILEHANDLE is an expression, +the value is taken as the name of the filehandle. + +=item bless REF,PACKAGE + +=item bless REF + +This function tells the referenced object (passed as REF) that it is now +an object in PACKAGE--or the current package if no PACKAGE is specified, +which is the usual case. It returns the reference for convenience, since +a bless() is often the last thing in a constructor. See L<perlobj> for +more about the blessing (and blessings) of objects. + +=item caller EXPR + +=item caller + +Returns the context of the current subroutine call. In a scalar context, +returns TRUE if there is a caller, that is, if we're in a subroutine or +eval() or require(), and FALSE otherwise. In a list context, returns + + ($package,$filename,$line) = caller; + +With EXPR, it returns some extra information that the debugger uses to +print a stack trace. The value of EXPR indicates how many call frames +to go back before the current one. + +=item chdir EXPR + +Changes the working directory to EXPR, if possible. If EXPR is +omitted, changes to home directory. Returns TRUE upon success, FALSE +otherwise. See example under die(). + +=item chmod LIST + +Changes the permissions of a list of files. The first element of the +list must be the numerical mode. Returns the number of files +successfully changed. + + $cnt = chmod 0755, 'foo', 'bar'; + chmod 0755, @executables; + +=item chomp VARIABLE + +=item chomp LIST + +=item chomp + +This is a slightly safer version of chop (see below). It removes any +line ending that corresponds to the current value of C<$/> (also known as +$INPUT_RECORD_SEPARATOR in the C<English> module). It returns the number +of characters removed. It's often used to remove the newline from the +end of an input record when you're worried that the final record may be +missing its newline. When in paragraph mode (C<$/ = "">), it removes all +trailing newlines from the string. If VARIABLE is omitted, it chomps +$_. Example: + + while (<>) { + chomp; # avoid \n on last field + @array = split(/:/); + ... + } + +You can actually chomp anything that's an lvalue, including an assignment: + + chomp($cwd = `pwd`); + chomp($answer = <STDIN>); + +If you chomp a list, each element is chomped, and the total number of +characters removed is returned. + +=item chop VARIABLE + +=item chop LIST + +=item chop + +Chops off the last character of a string and returns the character +chopped. It's used primarily to remove the newline from the end of an +input record, but is much more efficient than C<s/\n//> because it neither +scans nor copies the string. If VARIABLE is omitted, chops $_. +Example: + + while (<>) { + chop; # avoid \n on last field + @array = split(/:/); + ... + } + +You can actually chop anything that's an lvalue, including an assignment: + + chop($cwd = `pwd`); + chop($answer = <STDIN>); + +If you chop a list, each element is chopped. Only the value of the +last chop is returned. + +=item chown LIST + +Changes the owner (and group) of a list of files. The first two +elements of the list must be the I<NUMERICAL> uid and gid, in that order. +Returns the number of files successfully changed. + + $cnt = chown $uid, $gid, 'foo', 'bar'; + chown $uid, $gid, @filenames; + +Here's an example that looks up non-numeric uids in the passwd file: + + print "User: "; + chop($user = <STDIN>); + print "Files: " + chop($pattern = <STDIN>); + + ($login,$pass,$uid,$gid) = getpwnam($user) + or die "$user not in passwd file"; + + @ary = <${pattern}>; # expand filenames + chown $uid, $gid, @ary; + +=item chr NUMBER + +Returns the character represented by that NUMBER in the character set. +For example, C<chr(65)> is "A" in ASCII. + +=item chroot FILENAME + +Does the same as the system call of that name. If you don't know what +it does, don't worry about it. If FILENAME is omitted, does chroot to +$_. + +=item close FILEHANDLE + +Closes the file or pipe associated with the file handle, returning TRUE +only if stdio successfully flushes buffers and closes the system file +descriptor. You don't have to close FILEHANDLE if you are immediately +going to do another open on it, since open will close it for you. (See +open().) However, an explicit close on an input file resets the line +counter ($.), while the implicit close done by open() does not. Also, +closing a pipe will wait for the process executing on the pipe to +complete, in case you want to look at the output of the pipe +afterwards. Closing a pipe explicitly also puts the status value of +the command into C<$?>. Example: + + open(OUTPUT, '|sort >foo'); # pipe to sort + ... # print stuff to output + close OUTPUT; # wait for sort to finish + open(INPUT, 'foo'); # get sort's results + +FILEHANDLE may be an expression whose value gives the real filehandle name. + +=item closedir DIRHANDLE + +Closes a directory opened by opendir(). + +=item connect SOCKET,NAME + +Attempts to connect to a remote socket, just as the connect system call +does. Returns TRUE if it succeeded, FALSE otherwise. NAME should be a +package address of the appropriate type for the socket. See example in +L<perlipc>. + +=item cos EXPR + +Returns the cosine of EXPR (expressed in radians). If EXPR is omitted +takes cosine of $_. + +=item crypt PLAINTEXT,SALT + +Encrypts a string exactly like the crypt(3) function in the C library. +Useful for checking the password file for lousy passwords, amongst +other things. Only the guys wearing white hats should do this. + +Here's an example that makes sure that whoever runs this program knows +their own password: + + $pwd = (getpwuid($<))[1]; + $salt = substr($pwd, 0, 2); + + system "stty -echo"; + print "Password: "; + chop($word = <STDIN>); + print "\n"; + system "stty echo"; + + if (crypt($word, $salt) ne $pwd) { + die "Sorry...\n"; + } else { + print "ok\n"; + } + +Of course, typing in your own password to whoever asks you +for it is unwise at best. + +=item dbmclose ASSOC_ARRAY + +[This function has been superseded by the untie() function.] + +Breaks the binding between a DBM file and an associative array. + +=item dbmopen ASSOC,DBNAME,MODE + +[This function has been superseded by the tie() function.] + +This binds a dbm(3) or ndbm(3) file to an associative array. ASSOC is the +name of the associative array. (Unlike normal open, the first argument +is I<NOT> a filehandle, even though it looks like one). DBNAME is the +name of the database (without the F<.dir> or F<.pag> extension). If the +database does not exist, it is created with protection specified by +MODE (as modified by the umask()). If your system only supports the +older DBM functions, you may perform only one dbmopen() in your program. +If your system has neither DBM nor ndbm, calling dbmopen() produces a +fatal error. + +If you don't have write access to the DBM file, you can only read +associative array variables, not set them. If you want to test whether +you can write, either use file tests or try setting a dummy array entry +inside an eval(), which will trap the error. + +Note that functions such as keys() and values() may return huge array +values when used on large DBM files. You may prefer to use the each() +function to iterate over large DBM files. Example: + + # print out history file offsets + dbmopen(%HIST,'/usr/lib/news/history',0666); + while (($key,$val) = each %HIST) { + print $key, ' = ', unpack('L',$val), "\n"; + } + dbmclose(%HIST); + +=item defined EXPR + +Returns a boolean value saying whether the lvalue EXPR has a real value +or not. Many operations return the undefined value under exceptional +conditions, such as end of file, uninitialized variable, system error +and such. This function allows you to distinguish between an undefined +null scalar and a defined null scalar with operations that might return +a real null string, such as referencing elements of an array. You may +also check to see if arrays or subroutines exist. Use of defined on +predefined variables is not guaranteed to produce intuitive results. + +When used on a hash array element, it tells you whether the value +is defined, not whether the key exists in the hash. Use exists() for that. + +Examples: + + print if defined $switch{'D'}; + print "$val\n" while defined($val = pop(@ary)); + die "Can't readlink $sym: $!" + unless defined($value = readlink $sym); + eval '@foo = ()' if defined(@foo); + die "No XYZ package defined" unless defined %_XYZ; + sub foo { defined &$bar ? &$bar(@_) : die "No bar"; } + +See also undef(). + +=item delete EXPR + +Deletes the specified value from its hash array. Returns the deleted +value, or the undefined value if nothing was deleted. Deleting from +C<$ENV{}> modifies the environment. Deleting from an array tied to a DBM +file deletes the entry from the DBM file. (But deleting from a tie()d +hash doesn't necessarily return anything.) + +The following deletes all the values of an associative array: + + foreach $key (keys %ARRAY) { + delete $ARRAY{$key}; + } + +(But it would be faster to use the undef() command.) Note that the +EXPR can be arbitrarily complicated as long as the final operation is +a hash key lookup: + + delete $ref->[$x][$y]{$key}; + +=item die LIST + +Outside of an eval(), prints the value of LIST to C<STDERR> and exits with +the current value of $! (errno). If $! is 0, exits with the value of +C<($? E<gt>E<gt> 8)> (`command` status). If C<($? E<gt>E<gt> 8)> is 0, +exits with 255. Inside an eval(), the error message is stuffed into C<$@>. +and the eval() is terminated with the undefined value. + +Equivalent examples: + + die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news'; + chdir '/usr/spool/news' or die "Can't cd to spool: $!\n" + +If the value of EXPR does not end in a newline, the current script line +number and input line number (if any) are also printed, and a newline +is supplied. Hint: sometimes appending ", stopped" to your message +will cause it to make better sense when the string "at foo line 123" is +appended. Suppose you are running script "canasta". + + die "/etc/games is no good"; + die "/etc/games is no good, stopped"; + +produce, respectively + + /etc/games is no good at canasta line 123. + /etc/games is no good, stopped at canasta line 123. + +See also exit() and warn(). + +=item do BLOCK + +Not really a function. Returns the value of the last command in the +sequence of commands indicated by BLOCK. When modified by a loop +modifier, executes the BLOCK once before testing the loop condition. +(On other statements the loop modifiers test the conditional first.) + +=item do SUBROUTINE(LIST) + +A deprecated form of subroutine call. See L<perlsub>. + +=item do EXPR + +Uses the value of EXPR as a filename and executes the contents of the +file as a Perl script. Its primary use is to include subroutines +from a Perl subroutine library. + + do 'stat.pl'; + +is just like + + eval `cat stat.pl`; + +except that it's more efficient, more concise, keeps track of the +current filename for error messages, and searches all the B<-I> +libraries if the file isn't in the current directory (see also the @INC +array in L<perlvar/Predefined Names>). It's the same, however, in that it does +reparse the file every time you call it, so you probably don't want to +do this inside a loop. + +Note that inclusion of library modules is better done with the +use() and require() operators. + +=item dump LABEL + +This causes an immediate core dump. Primarily this is so that you can +use the B<undump> program to turn your core dump into an executable binary +after having initialized all your variables at the beginning of the +program. When the new binary is executed it will begin by executing a +C<goto LABEL> (with all the restrictions that C<goto> suffers). Think of +it as a goto with an intervening core dump and reincarnation. If LABEL +is omitted, restarts the program from the top. WARNING: any files +opened at the time of the dump will NOT be open any more when the +program is reincarnated, with possible resulting confusion on the part +of Perl. See also B<-u> option in L<perlrun>. + +Example: + + #!/usr/bin/perl + require 'getopt.pl'; + require 'stat.pl'; + %days = ( + 'Sun' => 1, + 'Mon' => 2, + 'Tue' => 3, + 'Wed' => 4, + 'Thu' => 5, + 'Fri' => 6, + 'Sat' => 7, + ); + + dump QUICKSTART if $ARGV[0] eq '-d'; + + QUICKSTART: + Getopt('f'); + +=item each ASSOC_ARRAY + +Returns a 2 element array consisting of the key and value for the next +value of an associative array, so that you can iterate over it. +Entries are returned in an apparently random order. When the array is +entirely read, a null array is returned (which when assigned produces a +FALSE (0) value). The next call to each() after that will start +iterating again. The iterator can be reset only by reading all the +elements from the array. You should not add elements to an array while +you're iterating over it. There is a single iterator for each +associative array, shared by all each(), keys() and values() function +calls in the program. The following prints out your environment like +the printenv(1) program, only in a different order: + + while (($key,$value) = each %ENV) { + print "$key=$value\n"; + } + +See also keys() and values(). + +=item eof FILEHANDLE + +=item eof + +Returns 1 if the next read on FILEHANDLE will return end of file, or if +FILEHANDLE is not open. FILEHANDLE may be an expression whose value +gives the real filehandle name. (Note that this function actually +reads a character and then ungetc()s it, so it is not very useful in an +interactive context.) An C<eof> without an argument returns the eof status +for the last file read. Empty parentheses () may be used to indicate +the pseudo file formed of the files listed on the command line, i.e. +C<eof()> is reasonable to use inside a while (<>) loop to detect the end +of only the last file. Use C<eof(ARGV)> or eof without the parentheses to +test I<EACH> file in a while (<>) loop. Examples: + + # insert dashes just before last line of last file + while (<>) { + if (eof()) { + print "--------------\n"; + } + print; + } + + # reset line numbering on each input file + while (<>) { + print "$.\t$_"; + if (eof) { # Not eof(). + close(ARGV); + } + } + +Practical hint: you almost never need to use C<eof> in Perl, because the +input operators return undef when they run out of data. + +=item eval EXPR + +=item eval BLOCK + +EXPR is parsed and executed as if it were a little Perl program. It +is executed in the context of the current Perl program, so that any +variable settings, subroutine or format definitions remain afterwards. +The value returned is the value of the last expression evaluated, or a +return statement may be used, just as with subroutines. + +If there is a syntax error or runtime error, or a die() statement is +executed, an undefined value is returned by eval(), and C<$@> is set to the +error message. If there was no error, C<$@> is guaranteed to be a null +string. If EXPR is omitted, evaluates $_. The final semicolon, if +any, may be omitted from the expression. + +Note that, since eval() traps otherwise-fatal errors, it is useful for +determining whether a particular feature (such as dbmopen() or symlink()) +is implemented. It is also Perl's exception trapping mechanism, where +the die operator is used to raise exceptions. + +If the code to be executed doesn't vary, you may use the eval-BLOCK +form to trap run-time errors without incurring the penalty of +recompiling each time. The error, if any, is still returned in C<$@>. +Examples: + + # make divide-by-zero non-fatal + eval { $answer = $a / $b; }; warn $@ if $@; + + # same thing, but less efficient + eval '$answer = $a / $b'; warn $@ if $@; + + # a compile-time error + eval { $answer = }; + + # a run-time error + eval '$answer ='; # sets $@ + +With an eval(), you should be especially careful to remember what's +being looked at when: + + eval $x; # CASE 1 + eval "$x"; # CASE 2 + + eval '$x'; # CASE 3 + eval { $x }; # CASE 4 + + eval "\$$x++" # CASE 5 + $$x++; # CASE 6 + +Cases 1 and 2 above behave identically: they run the code contained in the +variable $x. (Although case 2 has misleading double quotes making the +reader wonder what else might be happening (nothing is).) Cases 3 and 4 +likewise behave in the same way: they run the code <$x>, which does +nothing at all. (Case 4 is preferred for purely visual reasons.) Case 5 +is a place where normally you I<WOULD> like to use double quotes, except +that in particular situation, you can just use symbolic references +instead, as in case 6. + +=item exec LIST + +The exec() function executes a system command I<AND NEVER RETURNS>. Use +the system() function if you want it to return. + +If there is more than one argument in LIST, or if LIST is an array with +more than one value, calls execvp(3) with the arguments in LIST. If +there is only one scalar argument, the argument is checked for shell +metacharacters. If there are any, the entire argument is passed to +C</bin/sh -c> for parsing. If there are none, the argument is split +into words and passed directly to execvp(), which is more efficient. +Note: exec() (and system(0) do not flush your output buffer, so you may +need to set C<$|> to avoid lost output. Examples: + + exec '/bin/echo', 'Your arguments are: ', @ARGV; + exec "sort $outfile | uniq"; + +If you don't really want to execute the first argument, but want to lie +to the program you are executing about its own name, you can specify +the program you actually want to run as an "indirect object" (without a +comma) in front of the LIST. (This always forces interpretation of the +LIST as a multi-valued list, even if there is only a single scalar in +the list.) Example: + + $shell = '/bin/csh'; + exec $shell '-sh'; # pretend it's a login shell + +or, more directly, + + exec {'/bin/csh'} '-sh'; # pretend it's a login shell + +=item exists EXPR + +Returns TRUE if the specified hash key exists in its hash array, even +if the corresponding value is undefined. + + print "Exists\n" if exists $array{$key}; + print "Defined\n" if defined $array{$key}; + print "True\n" if $array{$key}; + +A hash element can only be TRUE if it's defined, and defined if +it exists, but the reverse doesn't necessarily hold true. + +Note that the EXPR can be arbitrarily complicated as long as the final +operation is a hash key lookup: + + if (exists $ref->[$x][$y]{$key}) { ... } + +=item exit EXPR + +Evaluates EXPR and exits immediately with that value. (Actually, it +calls any defined C<END> routines first, but the C<END> routines may not +abort the exit. Likewise any object destructors that need to be called +are called before exit.) Example: + + $ans = <STDIN>; + exit 0 if $ans =~ /^[Xx]/; + +See also die(). If EXPR is omitted, exits with 0 status. + +=item exp EXPR + +Returns I<e> (the natural logarithm base) to the power of EXPR. +If EXPR is omitted, gives C<exp($_)>. + +=item fcntl FILEHANDLE,FUNCTION,SCALAR + +Implements the fcntl(2) function. You'll probably have to say + + use Fcntl; + +first to get the correct function definitions. Argument processing and +value return works just like ioctl() below. Note that fcntl() will produce +a fatal error if used on a machine that doesn't implement fcntl(2). +For example: + + use Fcntl; + fcntl($filehandle, F_GETLK, $packed_return_buffer); + +=item fileno FILEHANDLE + +Returns the file descriptor for a filehandle. This is useful for +constructing bitmaps for select(). If FILEHANDLE is an expression, the +value is taken as the name of the filehandle. + +=item flock FILEHANDLE,OPERATION + +Calls flock(2) on FILEHANDLE. See L<flock(2)> for +definition of OPERATION. Returns TRUE for success, FALSE on failure. +Will produce a fatal error if used on a machine that doesn't implement +flock(2). Here's a mailbox appender for BSD systems. + + $LOCK_SH = 1; + $LOCK_EX = 2; + $LOCK_NB = 4; + $LOCK_UN = 8; + + sub lock { + flock(MBOX,$LOCK_EX); + # and, in case someone appended + # while we were waiting... + seek(MBOX, 0, 2); + } + + sub unlock { + flock(MBOX,$LOCK_UN); + } + + open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}") + or die "Can't open mailbox: $!"; + + lock(); + print MBOX $msg,"\n\n"; + unlock(); + +Note that flock() can't lock things over the network. You need to do +locking with fcntl() for that. + +=item fork + +Does a fork(2) system call. Returns the child pid to the parent process +and 0 to the child process, or undef if the fork is unsuccessful. +Note: unflushed buffers remain unflushed in both processes, which means +you may need to set C<$|> ($AUTOFLUSH in English) or call the +autoflush() FileHandle method to avoid duplicate output. + +If you fork() without ever waiting on your children, you will accumulate +zombies: + + $SIG{'CHLD'} = sub { wait }; + +There's also the double-fork trick (error checking on +fork() returns omitted); + + unless ($pid = fork) { + unless (fork) { + exec "what you really wanna do"; + die "no exec"; + # ... or ... + some_perl_code_here; + exit 0; + } + exit 0; + } + waitpid($pid,0); + + +=item formline PICTURE, LIST + +This is an internal function used by formats, though you may call it +too. It formats (see L<perlform>) a list of values according to the +contents of PICTURE, placing the output into the format output +accumulator, C<$^A>. Eventually, when a write() is done, the contents of +C<$^A> are written to some filehandle, but you could also read C<$^A> +yourself and then set C<$^A> back to "". Note that a format typically +does one formline() per line of form, but the formline() function itself +doesn't care how many newlines are embedded in the PICTURE. Be careful +if you put double quotes around the picture, since an "C<@>" character may +be taken to mean the beginning of an array name. formline() always +returns TRUE. + +=item getc FILEHANDLE + +=item getc + +Returns the next character from the input file attached to FILEHANDLE, +or a null string at end of file. If FILEHANDLE is omitted, reads from STDIN. + +=item getlogin + +Returns the current login from F</etc/utmp>, if any. If null, use +getpwuid(). + + $login = getlogin || (getpwuid($<))[0] || "Kilroy"; + +=item getpeername SOCKET + +Returns the packed sockaddr address of other end of the SOCKET connection. + + # An internet sockaddr + $sockaddr = 'S n a4 x8'; + $hersockaddr = getpeername(S); + ($family, $port, $heraddr) = unpack($sockaddr,$hersockaddr); + +=item getpgrp PID + +Returns 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 getpgrp(2). If PID is omitted, returns process +group of current process. + +=item getppid + +Returns the process id of the parent process. + +=item getpriority WHICH,WHO + +Returns the current priority for a process, a process group, or a +user. (See L<getpriority(2)>.) Will produce a fatal error if used on a +machine that doesn't implement getpriority(2). + +=item getpwnam NAME + +=item getgrnam NAME + +=item gethostbyname NAME + +=item getnetbyname NAME + +=item getprotobyname NAME + +=item getpwuid UID + +=item getgrgid GID + +=item getservbyname NAME,PROTO + +=item gethostbyaddr ADDR,ADDRTYPE + +=item getnetbyaddr ADDR,ADDRTYPE + +=item getprotobynumber NUMBER + +=item getservbyport PORT,PROTO + +=item getpwent + +=item getgrent + +=item gethostent + +=item getnetent + +=item getprotoent + +=item getservent + +=item setpwent + +=item setgrent + +=item sethostent STAYOPEN + +=item setnetent STAYOPEN + +=item setprotoent STAYOPEN + +=item setservent STAYOPEN + +=item endpwent + +=item endgrent + +=item endhostent + +=item endnetent + +=item endprotoent + +=item endservent + +These routines perform the same functions as their counterparts in the +system library. Within a list context, the return values from the +various get routines are as follows: + + ($name,$passwd,$uid,$gid, + $quota,$comment,$gcos,$dir,$shell) = getpw* + ($name,$passwd,$gid,$members) = getgr* + ($name,$aliases,$addrtype,$length,@addrs) = gethost* + ($name,$aliases,$addrtype,$net) = getnet* + ($name,$aliases,$proto) = getproto* + ($name,$aliases,$port,$proto) = getserv* + +(If the entry doesn't exist you get a null list.) + +Within a scalar context, you get the name, unless the function was a +lookup by name, in which case you get the other thing, whatever it is. +(If the entry doesn't exist you get the undefined value.) For example: + + $uid = getpwnam + $name = getpwuid + $name = getpwent + $gid = getgrnam + $name = getgrgid + $name = getgrent + etc. + +The $members value returned by I<getgr*()> is a space separated list of +the login names of the members of the group. + +For the I<gethost*()> functions, if the C<h_errno> variable is supported in +C, it will be returned to you via C<$?> if the function call fails. The +@addrs value returned by a successful call is a list of the raw +addresses returned by the corresponding system library call. In the +Internet domain, each address is four bytes long and you can unpack it +by saying something like: + + ($a,$b,$c,$d) = unpack('C4',$addr[0]); + +=item getsockname SOCKET + +Returns the packed sockaddr address of this end of the SOCKET connection. + + # An internet sockaddr + $sockaddr = 'S n a4 x8'; + $mysockaddr = getsockname(S); + ($family, $port, $myaddr) = + unpack($sockaddr,$mysockaddr); + +=item getsockopt SOCKET,LEVEL,OPTNAME + +Returns the socket option requested, or undefined if there is an error. + +=item glob EXPR + +Returns the value of EXPR with filename expansions such as a shell +would do. This is the internal function implementing the <*.*> +operator. + +=item gmtime EXPR + +Converts a time as returned by the time function to a 9-element array +with the time analyzed for the Greenwich timezone. Typically used as +follows: + + + ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = + gmtime(time); + +All array elements are numeric, and come straight out of a struct tm. +In particular this means that $mon has the range 0..11 and $wday has +the range 0..6. If EXPR is omitted, does C<gmtime(time())>. + +=item goto LABEL + +=item goto &NAME + +The goto-LABEL form finds the statement labeled with LABEL and resumes +execution there. It may not be used to go into any construct that +requires initialization, such as a subroutine or a foreach loop. It +also can't be used to go into a construct that is optimized away. It +can be used to go almost anywhere else within the dynamic scope, +including out of subroutines, but it's usually better to use some other +construct such as last or die. The author of Perl has never felt the +need to use this form of goto (in Perl, that is--C is another matter). + +The goto-&NAME form is highly magical, and substitutes a call to the +named subroutine for the currently running subroutine. This is used by +AUTOLOAD subroutines that wish to load another subroutine and then +pretend that the other subroutine had been called in the first place +(except that any modifications to @_ in the current subroutine are +propagated to the other subroutine.) After the goto, not even caller() +will be able to tell that this routine was called first. + +=item grep BLOCK LIST + +=item grep EXPR,LIST + +Evaluates the BLOCK or EXPR for each element of LIST (locally setting +$_ to each element) and returns the list value consisting of those +elements for which the expression evaluated to TRUE. In a scalar +context, returns the number of times the expression was TRUE. + + @foo = grep(!/^#/, @bar); # weed out comments + +or equivalently, + + @foo = grep {!/^#/} @bar; # weed out comments + +Note that, since $_ is a reference into the list value, it can be used +to modify the elements of the array. While this is useful and +supported, it can cause bizarre results if the LIST is not a named +array. + +=item hex EXPR + +Returns the decimal value of EXPR interpreted as an hex string. (To +interpret strings that might start with 0 or 0x see oct().) If EXPR is +omitted, uses $_. + +=item import + +There is no built-in import() function. It is merely an ordinary +method subroutine defined (or inherited) by modules that wish to export +names to another module. The use() function calls the import() method +for the package used. See also L</use> below and L<perlmod>. + +=item index STR,SUBSTR,POSITION + +=item index STR,SUBSTR + +Returns the position of the first occurrence of SUBSTR in STR at or +after POSITION. If POSITION is omitted, starts searching from the +beginning of the string. The return value is based at 0, or whatever +you've set the $[ variable to. If the substring is not found, returns +one less than the base, ordinarily -1. + +=item int EXPR + +Returns the integer portion of EXPR. If EXPR is omitted, uses $_. + +=item ioctl FILEHANDLE,FUNCTION,SCALAR + +Implements the ioctl(2) function. You'll probably have to say + + require "ioctl.ph"; # probably /usr/local/lib/perl/ioctl.ph + +first to get the correct function definitions. If ioctl.ph doesn't +exist or doesn't have the correct definitions you'll have to roll your +own, based on your C header files such as <sys/ioctl.h>. (There is a +Perl script called B<h2ph> that comes with the Perl kit which may help you +in this.) SCALAR will be read and/or written depending on the +FUNCTION--a pointer to the string value of SCALAR will be passed as the +third argument of the actual ioctl call. (If SCALAR has no string +value but does have a numeric value, that value will be passed rather +than a pointer to the string value. To guarantee this to be TRUE, add +a 0 to the scalar before using it.) The pack() and unpack() functions +are useful for manipulating the values of structures used by ioctl(). +The following example sets the erase character to DEL. + + require 'ioctl.ph'; + $sgttyb_t = "ccccs"; # 4 chars and a short + if (ioctl(STDIN,$TIOCGETP,$sgttyb)) { + @ary = unpack($sgttyb_t,$sgttyb); + $ary[2] = 127; + $sgttyb = pack($sgttyb_t,@ary); + ioctl(STDIN,$TIOCSETP,$sgttyb) + || die "Can't ioctl: $!"; + } + +The return value of ioctl (and fcntl) is as follows: + + if OS returns: then Perl returns: + -1 undefined value + 0 string "0 but true" + anything else that number + +Thus Perl returns TRUE on success and FALSE on failure, yet you can +still easily determine the actual value returned by the operating +system: + + ($retval = ioctl(...)) || ($retval = -1); + printf "System returned %d\n", $retval; + +=item join EXPR,LIST + +Joins the separate strings of LIST or ARRAY into a single string with +fields separated by the value of EXPR, and returns the string. +Example: + + $_ = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell); + +See L<perlfunc/split>. + +=item keys ASSOC_ARRAY + +Returns a normal array consisting of all the keys of the named +associative array. (In a scalar context, returns the number of keys.) +The keys are returned in an apparently random order, but it is the same +order as either the values() or each() function produces (given that +the associative array has not been modified). Here is yet another way +to print your environment: + + @keys = keys %ENV; + @values = values %ENV; + while ($#keys >= 0) { + print pop(@keys), '=', pop(@values), "\n"; + } + +or how about sorted by key: + + foreach $key (sort(keys %ENV)) { + print $key, '=', $ENV{$key}, "\n"; + } + +=item kill LIST + +Sends a signal to a list of processes. The first element of the list +must be the signal to send. Returns the number of processes +successfully signaled. + + $cnt = kill 1, $child1, $child2; + kill 9, @goners; + +Unlike in the shell, in Perl +if the I<SIGNAL> is negative, it kills process groups instead of processes. +(On System V, a negative I<PROCESS> number will also kill process +groups, but that's not portable.) That means you usually want to use +positive not negative signals. You may also use a signal name in quotes. + +=item last LABEL + +=item last + +The C<last> command is like the C<break> statement in C (as used in +loops); it immediately exits the loop in question. If the LABEL is +omitted, the command refers to the innermost enclosing loop. The +C<continue> block, if any, is not executed: + + line: while (<STDIN>) { + last line if /^$/; # exit when done with header + ... + } + +=item lc EXPR + +Returns an lowercased version of EXPR. This is the internal function +implementing the \L escape in double-quoted strings. + +=item lcfirst EXPR + +Returns the value of EXPR with the first character lowercased. This is +the internal function implementing the \l escape in double-quoted strings. + +=item length EXPR + +Returns the length in characters of the value of EXPR. If EXPR is +omitted, returns length of $_. + +=item link OLDFILE,NEWFILE + +Creates a new filename linked to the old filename. Returns 1 for +success, 0 otherwise. + +=item listen SOCKET,QUEUESIZE + +Does the same thing that the listen system call does. Returns TRUE if +it succeeded, FALSE otherwise. See example in L<perlipc>. + +=item local EXPR + +In general, you should be using "my" instead of "local", because it's +faster and safer. Format variables have to use "local" though, as +do any other variables whose local value must be visible to called +subroutines. This is known as dynamic scoping. Lexical scoping is +done with "my", which works more like C's auto declarations. + +A local modifies the listed variables to be local to the enclosing block, +subroutine, eval or "do". If more than one value is listed, the list +must be placed in parens. All the listed elements must be legal +lvalues. This operator works by saving the current values of those +variables in LIST on a hidden stack and restoring them upon exiting the +block, subroutine or eval. This means that called subroutines can also +reference the local variable, but not the global one. The LIST may be +assigned to if desired, which allows you to initialize your local +variables. (If no initializer is given for a particular variable, it +is created with an undefined value.) Commonly this is used to name the +parameters to a subroutine. Examples: + + sub RANGEVAL { + local($min, $max, $thunk) = @_; + local $result = ''; + local $i; + + # Presumably $thunk makes reference to $i + + for ($i = $min; $i < $max; $i++) { + $result .= eval $thunk; + } + + $result; + } + + + if ($sw eq '-v') { + # init local array with global array + local @ARGV = @ARGV; + unshift(@ARGV,'echo'); + system @ARGV; + } + # @ARGV restored + + + # temporarily add to digits associative array + if ($base12) { + # (NOTE: not claiming this is efficient!) + local(%digits) = (%digits,'t',10,'e',11); + parse_num(); + } + +Note that local() is a run-time command, and so gets executed every +time through a loop. In Perl 4 it used up more stack storage each +time until the loop was exited. Perl 5 reclaims the space each time +through, but it's still more efficient to declare your variables +outside the loop. + +When you assign to a localized EXPR, the local doesn't change whether +EXPR is viewed as a scalar or an array. So + + local($foo) = <STDIN>; + local @FOO = <STDIN>; + +both supply a list context to the righthand side, while + + local $foo = <STDIN>; + +supplies a scalar context. + +=item localtime EXPR + +Converts a time as returned by the time function to a 9-element array +with the time analyzed for the local timezone. Typically used as +follows: + + ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = + localtime(time); + +All array elements are numeric, and come straight out of a struct tm. +In particular this means that $mon has the range 0..11 and $wday has +the range 0..6. If EXPR is omitted, does localtime(time). + +In a scalar context, prints out the ctime(3) value: + + $now_string = localtime; # e.g. "Thu Oct 13 04:54:34 1994" + +See also L<perlmod/timelocal> and the strftime(3) function available +via the POSIX modulie. + +=item log EXPR + +Returns logarithm (base I<e>) of EXPR. If EXPR is omitted, returns log +of $_. + +=item lstat FILEHANDLE + +=item lstat EXPR + +Does the same thing as the stat() function, but stats a symbolic link +instead of the file the symbolic link points to. If symbolic links are +unimplemented on your system, a normal stat() is done. + +=item m// + +The match operator. See L<perlop>. + +=item map BLOCK LIST + +=item map EXPR,LIST + +Evaluates the BLOCK or EXPR for each element of LIST (locally setting $_ to each +element) and returns the list value composed of the results of each such +evaluation. Evaluates BLOCK or EXPR in a list context, so each element of LIST +may produce zero, one, or more elements in the returned value. + + @chars = map(chr, @nums); + +translates a list of numbers to the corresponding characters. And + + %hash = map {&key($_), $_} @array; + +is just a funny way to write + + %hash = (); + foreach $_ (@array) { + $hash{&key($_)} = $_; + } + +=item mkdir FILENAME,MODE + +Creates the directory specified by FILENAME, with permissions specified +by MODE (as modified by umask). If it succeeds it returns 1, otherwise +it returns 0 and sets $! (errno). + +=item msgctl ID,CMD,ARG + +Calls the System V IPC function msgctl. If CMD is &IPC_STAT, then ARG +must be a variable which will hold the returned msqid_ds structure. +Returns like ioctl: the undefined value for error, "0 but true" for +zero, or the actual return value otherwise. + +=item msgget KEY,FLAGS + +Calls the System V IPC function msgget. Returns the message queue id, +or the undefined value if there is an error. + +=item msgsnd ID,MSG,FLAGS + +Calls the System V IPC function msgsnd to send the message MSG to the +message queue ID. MSG must begin with the long integer message type, +which may be created with C<pack("L", $type)>. Returns TRUE if +successful, or FALSE if there is an error. + +=item msgrcv ID,VAR,SIZE,TYPE,FLAGS + +Calls the System V IPC function msgrcv to receive a message from +message queue ID into variable VAR with a maximum message size of +SIZE. Note that if a message is received, the message type will be the +first thing in VAR, and the maximum length of VAR is SIZE plus the size +of the message type. Returns TRUE if successful, or FALSE if there is +an error. + +=item my EXPR + +A "my" declares the listed variables to be local (lexically) to the +enclosing block, subroutine, eval or "do". If more than one value is +listed, the list must be placed in parens. All the listed elements +must be legal lvalues. Only alphanumeric identifiers may be lexically +scoped--magical builtins like $/ must be localized with "local" +instead. In particular, you're not allowed to say + + my $_; # Illegal. + +Unlike the "local" declaration, variables declared with "my" +are totally hidden from the outside world, including any called +subroutines (even if it's the same subroutine--every call gets its own +copy). + +(An eval(), however, can see the lexical variables of the scope it is +being evaluated in so long as the names aren't hidden by declarations within +the eval() itself. See L<perlref>.) + +The EXPR may be assigned to if desired, which allows you to initialize +your variables. (If no initializer is given for a particular +variable, it is created with an undefined value.) Commonly this is +used to name the parameters to a subroutine. Examples: + + sub RANGEVAL { + my($min, $max, $thunk) = @_; + my $result = ''; + my $i; + + # Presumably $thunk makes reference to $i + + for ($i = $min; $i < $max; $i++) { + $result .= eval $thunk; + } + + $result; + } + + + if ($sw eq '-v') { + # init my array with global array + my @ARGV = @ARGV; + unshift(@ARGV,'echo'); + system @ARGV; + } + # Outer @ARGV again visible + +When you assign to the EXPR, the "my" doesn't change whether +EXPR is viewed as a scalar or an array. So + + my($foo) = <STDIN>; + my @FOO = <STDIN>; + +both supply a list context to the righthand side, while + + my $foo = <STDIN>; + +supplies a scalar context. + +Some users may wish to encourage the use of lexically scoped variables. +As an aid to catching implicit references to package variables, +if you say + + use strict 'vars'; + +then any variable reference from there to the end of the enclosing +block must either refer to a lexical variable, or must be fully +qualified with the package name. A compilation error results +otherwise. An inner block may countermand this with S<"no strict 'vars'">. + +=item next LABEL + +=item next + +The C<next> command is like the C<continue> statement in C; it starts +the next iteration of the loop: + + line: while (<STDIN>) { + next line if /^#/; # discard comments + ... + } + +Note that if there were a C<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. + +=item no Module LIST + +See the "use" function, which "no" is the opposite of. + +=item oct EXPR + +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 Perl or C notation: + + $val = oct($val) if $val =~ /^0/; + +If EXPR is omitted, uses $_. + +=item open FILEHANDLE,EXPR + +=item open FILEHANDLE + +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 "<" or nothing, the file is opened for input. +If the filename begins with ">", the file is opened for output. If the +filename begins with ">>", 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 "|", +the filename is interpreted as a command to which output is to be +piped, and if the filename ends with a "|", 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 STDIN and opening '>-' +opens 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: + + $ARTICLE = 100; + open ARTICLE or die "Can't find article $ARTICLE: $!\n"; + while (<ARTICLE>) {... + + open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved) + + open(article, "caesar <$article |"); # decrypt article + + open(extract, "|sort >/tmp/Tmp$$"); # $$ is our process id + + # process argument list of files along with any includes + + foreach $file (@ARGV) { + process($file, 'fh00'); + } + + sub process { + local($filename, $input) = @_; + $input++; # this is a string increment + unless (open($input, $filename)) { + print STDERR "Can't open $filename: $!\n"; + return; + } + + while (<$input>) { # note use of indirection + if (/^#include "(.*)"/) { + process($1, $input); + next; + } + ... # whatever + } + } + +You may also, in the Bourne shell tradition, specify an EXPR beginning +with ">&", 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 STDOUT and +STDERR: + + #!/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\n"; # this works for + print STDERR "stderr 1\n"; # subprocesses too + + close(STDOUT); + close(STDERR); + + open(STDOUT, ">&SAVEOUT"); + open(STDERR, ">&SAVEERR"); + + print STDOUT "stdout 2\n"; + print STDERR "stderr 2\n"; + + +If you specify "<&=N", where N is a number, then Perl will do an +equivalent of C's fdopen() of that file descriptor. For example: + + open(FILEHANDLE, "<&=$fd") + +If you open a pipe on the command "-", i.e. either "|-" or "-|", 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 whether the open was successful.) +The filehandle behaves normally for the parent, but i/o to that +filehandle is piped from/to the STDOUT/STDIN of the child process. +In the child process the filehandle isn't opened--i/o happens from/to +the new STDOUT or 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: + + 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; + +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. + +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: + + $file =~ s#^(\s)#./$1#; + open(FOO, "< $file\0"); + +=item opendir DIRHANDLE,EXPR + +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. + +=item ord EXPR + +Returns the numeric ascii value of the first character of EXPR. If +EXPR is omitted, uses $_. + +=item pack TEMPLATE,LIST + +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: + + A An ascii string, will be space padded. + a An ascii string, will be null padded. + 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). + + 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 "network" order. + N A long in "network" order. + v A short in "VAX" (little-endian) order. + V A long in "VAX" (little-endian) order. + + f A single-precision float in the native format. + d A double-precision float in the native format. + + p A pointer to a null-terminated string. + P A pointer to a structure (fixed-length string). + + u A uuencoded string. + + x A null byte. + X Back up a byte. + @ Null fill to absolute position. + +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", and "P" 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. The "P" packs a pointer to a structure of +the size indicated by the length. 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 "network" 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 into +float and thence back to double again will lose precision (i.e. +C<unpack("f", pack("f", $foo)>) will not in general equal $foo). + +Examples: + + $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\0\0CD" + + $foo = pack("s2",1,2); + # "\1\0\2\0" on little-endian + # "\0\1\0\2" on big-endian + + $foo = pack("a4","abcd","x","y","z"); + # "abcd" + + $foo = pack("aaaa","abcd","x","y","z"); + # "axyz" + + $foo = pack("a14","abcdefg"); + # "abcdefg\0\0\0\0\0\0\0" + + $foo = pack("i9pl", gmtime); + # a real struct tm (on my system anyway) + + sub bintodec { + unpack("N", pack("B32", substr("0" x 32 . shift, -32))); + } + +The same template may generally also be used in the unpack function. + +=item pipe READHANDLE,WRITEHANDLE + +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. + +=item pop ARRAY + +Pops and returns the last value of the array, shortening the array by +1. Has a similar effect to + + $tmp = $ARRAY[$#ARRAY--]; + +If there are no elements in the array, returns the undefined value. + +=item pos SCALAR + +Returns the offset of where the last m//g search left off for the variable +in question. May be modified to change that offset. + +=item print FILEHANDLE LIST + +=item print LIST + +=item print + +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 +STDOUT. To set the default output channel to something other than +STDOUT use the select operation. Note that, because print takes a +LIST, anything in the LIST is evaluated in a list context, and any +subroutine that you call will have one or more of its expressions +evaluated in a list 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. + +=item printf FILEHANDLE LIST + +=item printf LIST + +Equivalent to a "print FILEHANDLE sprintf(LIST)". The first argument +of the list will be interpreted as the printf format. + +=item push ARRAY,LIST + +Treats ARRAY 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 + + for $value (LIST) { + $ARRAY[++$#ARRAY] = $value; + } + +but is more efficient. Returns the new number of elements in the array. + +=item q/STRING/ + +=item qq/STRING/ + +=item qx/STRING/ + +=item qw/STRING/ + +Generalized quotes. See L<perlop>. + +=item quotemeta EXPR + +Returns the value of EXPR with with all regular expression +metacharacters backslashed. This is the internal function implementing +the \Q escape in double-quoted strings. + +=item rand EXPR + +=item rand + +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. This function produces repeatable sequences unless srand() +is invoked. See also srand(). + +(Note: if your rand function consistently returns numbers that are too +large or too small, then your version of Perl was probably compiled +with the wrong number of RANDBITS. As a workaround, you can usually +multiply EXPR by the correct power of 2 to get the range you want. +This will make your script unportable, however. It's better to recompile +if you can.) + +=item read FILEHANDLE,SCALAR,LENGTH,OFFSET + +=item read FILEHANDLE,SCALAR,LENGTH + +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(). + +=item readdir DIRHANDLE + +Returns the next directory entry for a directory opened by opendir(). +If used in a list 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 a list context. + +=item readlink EXPR + +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 $_. + +=item recv SOCKET,SCALAR,LEN,FLAGS + +Receives a message on a socket. Attempts to receive LENGTH bytes of +data into variable SCALAR from the specified SOCKET filehandle. +Actually does a C recvfrom(), so that it can returns the address of the +sender. Returns 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. + +=item redo LABEL + +=item redo + +The C<redo> command restarts the loop block without evaluating the +conditional again. The C<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: + + # 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; + } + +=item ref EXPR + +Returns a TRUE value if EXPR is a reference, FALSE otherwise. The value +returned depends on the type of thing the reference is a reference to. +Builtin types include: + + REF + SCALAR + ARRAY + HASH + CODE + GLOB + +If the referenced object has been blessed into a package, then that package +name is returned instead. You can think of ref() as a typeof() operator. + + if (ref($r) eq "HASH") { + print "r is a reference to an associative array.\n"; + } + if (!ref ($r) { + print "r is not a reference at all.\n"; + } + +See also L<perlref>. + +=item rename OLDNAME,NEWNAME + +Changes the name of a file. Returns 1 for success, 0 otherwise. Will +not work across filesystem boundaries. + +=item require EXPR + +=item require + +Demands some semantics specified by EXPR, or by $_ if EXPR is not +supplied. If EXPR is numeric, demands that the current version of Perl +($] or $PERL_VERSION) be equal or greater than EXPR. + +Otherwise, demands that a library file be included if it hasn't already +been included. The file is included via the do-FILE mechanism, which is +essentially just a variety of eval(). Has semantics similar to the following +subroutine: + + 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 \@INC"; + } + die $@ if $@; + die "$filename did not return true value" unless $result; + $INC{$filename} = $realfilename; + $result; + } + +Note that the file will not be included twice under the same specified +name. The file must return TRUE as the last statement to indicate +successful execution of any initialization code, so it's customary to +end such a file with "1;" unless you're sure it'll return TRUE +otherwise. But it's better just to put the "C<1;>", in case you add more +statements. + +If EXPR is a bare word, the require assumes a "F<.pm>" extension for you, +to make it easy to load standard modules. This form of loading of +modules does not risk altering your namespace. + +For a yet more powerful import facility, see the L</use()> below, and +also L<perlmod>. + +=item reset EXPR + +=item reset + +Generally used in a C<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: + + reset 'X'; # reset all X variables + reset 'a-z'; # reset lower case variables + reset; # just reset ?? searches + +Resetting "A-Z" is not recommended since you'll wipe out your +ARGV and ENV arrays. Only resets package variables--lexical variables +are unaffected, but they clean themselves up on scope exit anyway, +so anymore you probably want to use them instead. See L</my>. + +=item return LIST + +Returns from a subroutine or eval with the value specified. (Note that +in the absence of a return a subroutine or eval will automatically +return the value of the last expression evaluated.) + +=item reverse LIST + +In a list context, returns a list 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. + +=item rewinddir DIRHANDLE + +Sets the current position to the beginning of the directory for the +readdir() routine on DIRHANDLE. + +=item rindex STR,SUBSTR,POSITION + +=item rindex STR,SUBSTR + +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. + +=item rmdir FILENAME + +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 $_. + +=item s/// + +The substitution operator. See L<perlop>. + +=item scalar EXPR + +Forces EXPR to be interpreted in a scalar context and returns the value +of EXPR. + +=item seek FILEHANDLE,POSITION,WHENCE + +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. The values for WHENCE are 0 to set the file pointer to +POSITION, 1 to set the it to current plus POSITION, and 2 to set it to EOF +plus offset. You may use the values SEEK_SET, SEEK_CUR, and SEEK_END for +this is usin the POSIX module. Returns 1 upon success, 0 otherwise. + +=item seekdir DIRHANDLE,POS + +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. + +=item select FILEHANDLE + +=item select + +Returns the currently selected filehandle. Sets the current default +filehandle for output, if FILEHANDLE is supplied. This has two +effects: first, a C<write> or a C<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: + + select(REPORT1); + $^ = 'report1_top'; + select(REPORT2); + $^ = 'report2_top'; + +FILEHANDLE may be an expression whose value gives the name of the +actual filehandle. Thus: + + $oldfh = select(STDERR); $| = 1; select($oldfh); + +With Perl 5, filehandles are objects with methods, and the last example +is preferably written + + use FileHandle; + STDERR->autoflush(1); + +=item select RBITS,WBITS,EBITS,TIMEOUT + +This calls the select system(2) call with the bitmasks specified, which +can be constructed using fileno() and vec(), along these lines: + + $rin = $win = $ein = ''; + vec($rin,fileno(STDIN),1) = 1; + vec($win,fileno(STDOUT),1) = 1; + $ein = $rin | $win; + +If you want to select on many filehandles you might wish to write a +subroutine: + + sub fhbits { + local(@fhlist) = split(' ',$_[0]); + local($bits); + for (@fhlist) { + vec($bits,fileno($_),1) = 1; + } + $bits; + } + $rin = &fhbits('STDIN TTY SOCK'); + +The usual idiom is: + + ($nfound,$timeleft) = + select($rout=$rin, $wout=$win, $eout=$ein, $timeout); + +or to block until something becomes ready: + + $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef); + +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. + +You can effect a 250 microsecond sleep this way: + + select(undef, undef, undef, 0.25); + + +=item semctl ID,SEMNUM,CMD,ARG + +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. + +=item semget KEY,NSEMS,FLAGS + +Calls the System V IPC function semget. Returns the semaphore id, or +the undefined value if there is an error. + +=item semop KEY,OPSTRING + +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 +C<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: + + $semop = pack("sss", $semnum, -1, 0); + die "Semaphore trouble: $!\n" unless semop($semid, $semop); + +To signal the semaphore, replace "-1" with "1". + +=item send SOCKET,MSG,FLAGS,TO + +=item send SOCKET,MSG,FLAGS + +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, in which case it does a C sendto(). Returns +the number of characters sent, or the undefined value if there is an +error. + +=item setpgrp PID,PGRP + +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). + +=item setpriority WHICH,WHO,PRIORITY + +Sets the current priority for a process, a process group, or a user. +(See Lsetpriority(2)>.) Will produce a fatal error if used on a machine +that doesn't implement setpriority(2). + +=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL + +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. + +=item shift ARRAY + +=item shift + +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. + +=item shmctl ID,CMD,ARG + +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. + +=item shmget KEY,SIZE,FLAGS + +Calls the System V IPC function shmget. Returns the shared memory +segment id, or the undefined value if there is an error. + +=item shmread ID,VAR,POS,SIZE + +=item shmwrite ID,STRING,POS,SIZE + +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. + +=item shutdown SOCKET,HOW + +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. + +=item sin EXPR + +Returns the sine of EXPR (expressed in radians). If EXPR is omitted, +returns sine of $_. + +=item sleep EXPR + +=item sleep + +Causes the script to sleep for EXPR seconds, or forever if no EXPR. +May be interrupted by sending the process a SIGALRM. Returns the +number of seconds actually slept. You probably cannot mix alarm() and +sleep() calls, since sleep() is often implemented using alarm(). + +On some older systems, it may sleep up to a full second less than what +you requested, depending on how it counts seconds. Most modern systems +always sleep the full amount. + +=item socket SOCKET,DOMAIN,TYPE,PROTOCOL + +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 should "use Socket;" first to get +the proper definitions imported. See the example in L<perlipc>. + +=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL + +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. Returns TRUE if successful. + +=item sort SUBNAME LIST + +=item sort BLOCK LIST + +=item sort LIST + +Sorts the LIST and returns the sorted list value. Nonexistent values +of arrays are stripped out. If SUBNAME or BLOCK is omitted, sorts +in standard string comparison order. If SUBNAME is specified, it +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. (The <=> and cmp operators are extremely useful in such +routines.) SUBNAME may be a scalar variable name, in which case the +value provides the name of the subroutine to use. In place of a +SUBNAME, you can provide a BLOCK as an anonymous, in-line sort +subroutine. + +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. + +Examples: + + # sort lexically + @articles = sort @files; + + # same thing, but with explicit sort routine + @articles = sort {$a cmp $b} @files; + + # same thing in reversed order + @articles = sort {$b cmp $a} @files; + + # sort numerically ascending + @articles = sort {$a <=> $b} @files; + + # sort numerically descending + @articles = sort {$b <=> $a} @files; + + # sort using explicit subroutine name + sub byage { + $age{$a} <=> $age{$b}; # presuming integers + } + @sortedclass = sort byage @class; + + sub backwards { $b cmp $a; } + @harry = ('dog','cat','x','Cain','Abel'); + @george = ('gone','chased','yz','Punished','Axed'); + print sort @harry; + # prints AbelCaincatdogx + print sort backwards @harry; + # prints xdogcatCainAbel + print sort @george, 'to', @harry; + # prints AbelAxedCainPunishedcatchaseddoggonetoxyz + +=item splice ARRAY,OFFSET,LENGTH,LIST + +=item splice ARRAY,OFFSET,LENGTH + +=item splice ARRAY,OFFSET + +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): + + push(@a,$x,$y) splice(@a,$#a+1,0,$x,$y) + pop(@a) splice(@a,-1) + shift(@a) splice(@a,0,1) + unshift(@a,$x,$y) splice(@a,0,0,$x,$y) + $a[$x] = $y splice(@a,$x,1,$y); + +Example, assuming array lengths are passed before arrays: + + sub aeq { # compare two list 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)) { ... } + +=item split /PATTERN/,EXPR,LIMIT + +=item split /PATTERN/,EXPR + +=item split /PATTERN/ + +=item split + +Splits a string into an array of strings, and returns it. + +If not in a list context, returns the number of fields found and splits into +the @_ array. (In a list context, you can force the split into @_ by +using C<??> as the pattern delimiters, but it still returns the array +value.) The use of implicit split to @_ is deprecated, however. + +If EXPR is omitted, splits the $_ string. If PATTERN is also omitted, +splits on whitespace (C</[ \t\n]+/>). 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 and is not +negative, 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). +If LIMIT is negative, it is treated as if an arbitrarily large LIMIT +had been specified. + +A pattern matching the null string (not to be confused with +a null pattern C<//., 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: + + print join(':', split(/ */, 'hi there')); + +produces the output 'h:i:t:h:e:r:e'. + +The LIMIT parameter can be used to partially split a line + + ($login, $passwd, $remainder) = split(/:/, $_, 3); + +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. + +If the PATTERN contains parentheses, additional array elements are +created from each matching substring in the delimiter. + + split(/([,-])/, "1-10,20"); + +produces the list value + + (1, '-', 10, ',', 20) + +The pattern C</PATTERN/> may be replaced with an expression to specify +patterns that vary at runtime. (To do runtime compilation only once, +use C</$variable/o>.) As a special case, specifying a space S<(' ')> will +split on white space just as split with no arguments does, but leading +white space does I<NOT> produce a null first field. Thus, split(' ') can +be used to emulate B<awk>'s default behavior, whereas C<split(/ /)> will +give you as many null initial fields as there are leading spaces. + +Example: + + open(passwd, '/etc/passwd'); + while (<passwd>) { + ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(/:/); + ... + } + +(Note that $shell above will still have a newline on it. See L</chop>, +L</chomp>, and L</join>.) + +=item sprintf FORMAT,LIST + +Returns a string formatted by the usual printf conventions of the C +language. (The * character for an indirectly specified length is not +supported, but you can get the same effect by interpolating a variable +into the pattern.) + +=item sqrt EXPR + +Return the square root of EXPR. If EXPR is omitted, returns square +root of $_. + +=item srand EXPR + +Sets the random number seed for the C<rand> operator. If EXPR is +omitted, does C<srand(time)>. Of course, you'd need something much more +random than that for cryptographic purposes, since it's easy to guess +the current time. Checksumming the compressed output of rapidly +changing operating system status programs is the usual method. +Examples are posted regularly to comp.security.unix. + +=item stat FILEHANDLE + +=item stat EXPR + +Returns a 13-element array giving the status info for a file, either the +file opened via FILEHANDLE, or named by EXPR. Returns a null list if +the stat fails. Typically used as follows: + + ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size, + $atime,$mtime,$ctime,$blksize,$blocks) + = stat($filename); + +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: + + if (-x $file && (($d) = stat(_)) && $d < 0) { + print "$file is executable NFS file\n"; + } + +(This only works on machines for which the device number is negative under NFS.) + +=item study SCALAR + +=item 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 "unstudied". (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 'k' 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 "rarest" character are examined.) + +For example, here is a loop which inserts index producing entries +before any line containing a certain pattern: + + while (<>) { + study; + print ".IX foo\n" if /\bfoo\b/; + print ".IX bar\n" if /\bbar\b/; + print ".IX blurfl\n" if /\bblurfl\b/; + ... + print; + } + +In searching for /\bfoo\b/, only those locations in $_ that contain "f" +will be looked at, because "f" is rarer than "o". 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. + +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 +undefining $/ to input entire files as one record, this can be very +fast, often faster than specialized programs like fgrep(1). 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: + + $search = 'while (<>) { study;'; + foreach $word (@words) { + $search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n"; + } + $search .= "}"; + @ARGV = @files; + undef $/; + eval $search; # this screams + $/ = "\n"; # put back to normal input delim + foreach $file (sort keys(%seen)) { + print $file, "\n"; + } + +=item substr EXPR,OFFSET,LEN + +=item substr EXPR,OFFSET + +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(). + +=item symlink OLDFILE,NEWFILE + +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: + + $symlink_exists = (eval 'symlink("","");', $@ eq ''); + +=item syscall LIST + +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. + + require 'syscall.ph'; # may need to run h2ph + syscall(&SYS_write, fileno(STDOUT), "hi there\n", 9); + +Note that Perl only supports passing of up to 14 arguments to your system call, +which in practice should usually suffice. + +=item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET + +=item sysread FILEHANDLE,SCALAR,LENGTH + +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. + +=item system LIST + +Does exactly the same thing as "exec LIST" 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 L</exec>. + +=item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET + +=item syswrite FILEHANDLE,SCALAR,LENGTH + +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. + +=item tell FILEHANDLE + +=item tell + +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. + +=item telldir DIRHANDLE + +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. + +=item tie VARIABLE,PACKAGENAME,LIST + +This function binds a variable to a package that will provide the +implementation for the variable. VARIABLE is the name of the variable +to be enchanted. PACKAGENAME is the name of a package implementing +objects of correct type. Any additional arguments are passed to the +"new" method of the package. Typically these are arguments such as +might be passed to the dbm_open() function of C. + +Note that functions such as keys() and values() may return huge array +values when used on large DBM files. You may prefer to use the each() +function to iterate over large DBM files. Example: + + # print out history file offsets + tie(%HIST, NDBM_File, '/usr/lib/news/history', 1, 0); + while (($key,$val) = each %HIST) { + print $key, ' = ', unpack('L',$val), "\n"; + } + untie(%HIST); + +A package implementing an associative array should have the following +methods: + + TIEHASH objectname, LIST + DESTROY this + FETCH this, key + STORE this, key, value + DELETE this, key + EXISTS this, key + FIRSTKEY this + NEXTKEY this, lastkey + +A package implementing an ordinary array should have the following methods: + + TIEARRAY objectname, LIST + DESTROY this + FETCH this, key + STORE this, key, value + [others TBD] + +A package implementing a scalar should have the following methods: + + TIESCALAR objectname, LIST + DESTROY this + FETCH this, + STORE this, value + +=item time + +Returns the number of non-leap seconds since 00:00:00 UTC, January 1, +1970. Suitable for feeding to gmtime() and localtime(). + +=item times + +Returns a four-element array giving the user and system times, in +seconds, for this process and the children of this process. + + ($user,$system,$cuser,$csystem) = times; + +=item tr/// + +The translation operator. See L<perlop>. + +=item truncate FILEHANDLE,LENGTH + +=item truncate EXPR,LENGTH + +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. + +=item uc EXPR + +Returns an uppercased version of EXPR. This is the internal function +implementing the \U escape in double-quoted strings. + +=item ucfirst EXPR + +Returns the value of EXPR with the first character uppercased. This is +the internal function implementing the \u escape in double-quoted strings. + +=item umask EXPR + +=item umask + +Sets the umask for the process and returns the old one. If EXPR is +omitted, merely returns current umask. + +=item undef EXPR + +=item undef + +Undefines the value of EXPR, which must be an lvalue. Use only on a +scalar value, an entire array, or a subroutine name (using "&"). (Using undef() +will probably not do what you expect on most predefined variables or +DBM list values, so don't do that.) 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: + + undef $foo; + undef $bar{'blurfl'}; + undef @ary; + undef %assoc; + undef &mysub; + return (wantarray ? () : undef) if $they_blew_it; + +=item unlink LIST + +Deletes a list of files. Returns the number of files successfully +deleted. + + $cnt = unlink 'a', 'b', 'c'; + unlink @goners; + unlink <*.bak>; + +Note: unlink will not delete directories unless you are superuser and +the B<-U> flag is supplied to Perl. Even if these conditions are +met, be warned that unlinking a directory can inflict damage on your +filesystem. Use rmdir instead. + +=item unpack TEMPLATE,EXPR + +Unpack does the reverse of pack: it takes a string representing a +structure and expands it out into a list 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: + + sub substr { + local($what,$where,$howmuch) = @_; + unpack("x$where a$howmuch", $what); + } + +and then there's + + sub ordinal { unpack("c",$_[0]); } # same as ord() + +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: + + while (<>) { + $checksum += unpack("%16C*", $_); + } + $checksum %= 65536; + +The following efficiently counts the number of set bits in a bit vector: + + $setbits = unpack("%32b*", $selectmask); + +=item untie VARIABLE + +Breaks the binding between a variable and a package. (See tie().) + +=item unshift ARRAY,LIST + +Does the opposite of a C<shift>. Or the opposite of a C<push>, +depending on how you look at it. Prepends list to the front of the +array, and returns the new number of elements in the array. + + unshift(ARGV, '-e') unless $ARGV[0] =~ /^-/; + +Note the LIST is prepended whole, not one element at a time, so the +prepended elements stay in the same order. Use reverse to do the +reverse. + +=item use Module LIST + +=item use Module + +Imports some semantics into the current package from the named module, +generally by aliasing certain subroutine or variable names into your +package. It is exactly equivalent to + + BEGIN { require Module; import Module LIST; } + +If you don't want your namespace altered, use require instead. + +The BEGIN forces the require and import to happen at compile time. The +require makes sure the module is loaded into memory if it hasn't been +yet. The import is not a builtin--it's just an ordinary static method +call into the "Module" package to tell the module to import the list of +features back into the current package. The module can implement its +import method any way it likes, though most modules just choose to +derive their import method via inheritance from the Exporter class that +is defined in the Exporter module. + +Because this is a wide-open interface, pragmas (compiler directives) +are also implemented this way. Currently implemented pragmas are: + + use integer; + use sigtrap qw(SEGV BUS); + use strict qw(subs vars refs); + use subs qw(afunc blurfl); + +These pseudomodules import semantics into the current block scope, unlike +ordinary modules, which import symbols into the current package (which are +effective through the end of the file). + +There's a corresponding "no" command that unimports meanings imported +by use. + + no integer; + no strict 'refs'; + +See L<perlmod> for a list of standard modules and pragmas. + +=item utime LIST + +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 "touch" command: + + #!/usr/bin/perl + $now = time; + utime $now, $now, @ARGV; + +=item values ASSOC_ARRAY + +Returns a normal array consisting of all the values of the named +associative array. (In a scalar context, returns the number of +values.) 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(). + +=item vec EXPR,OFFSET,BITS + +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. + +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. + +To transform a bit vector into a string or array of 0's and 1's, use these: + + $bits = unpack("b*", $vector); + @bits = split(//, unpack("b*", $vector)); + +If you know the exact length in bits, it can be used in place of the *. + +=item wait + +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 $?. + +=item waitpid PID,FLAGS + +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 + + use POSIX "wait_h"; + ... + waitpid(-1,&WNOHANG); + +then you can do a non-blocking wait for any process. Non-blocking wait +is only available on machines supporting either the waitpid(2) or +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.) + +=item wantarray + +Returns TRUE if the context of the currently executing subroutine is +looking for a list value. Returns FALSE if the context is looking +for a scalar. + + return wantarray ? () : undef; + +=item warn LIST + +Produces a message on STDERR just like die(), but doesn't exit or +throw an exception. + +=item write FILEHANDLE + +=item write EXPR + +=item write + +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 the select() function) may be set +explicitly by assigning the name of the format to the $~ variable. + +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 the name of the filehandle with +"_TOP" appended, but it may be dynamically set to the format of your +choice by assigning the name to the $^ variable while the filehandle is +selected. The number of lines remaining on the current page is in +variable $-, which can be set to 0 to force a new page. + +If FILEHANDLE is unspecified, output goes to the current default output +channel, which starts out as STDOUT but may be changed by the +C<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 L<perlform>. + +Note that write is I<NOT> the opposite of read. Unfortunately. + +=item y/// + +The translation operator. See L<perlop/tr///>. + +=back |