 |
Chapter 3 Functions |
 |
3.2 Perl Functions in Alphabetical Order
/PATTERN/
/PATTERN/ m/PATTERN/
The match operator. See "Regular Expressions" in Chapter 2, The Gory Details.
?PATTERN?
?PATTERN?
This is just like the /PATTERN/ search, except that it matches only once between calls to reset, so it finds only the first occurrence of something rather than all occurrences. (In other words, the operator works repeatedly until it actually matches something, then it turns itself off until you explicitly turn it back on with reset.) This may be useful (and efficient) if you want to see only the first occurrence of the pattern in each file of a set of files. Note that m?? is equivalent to ??.
The reset operator will only reset instances of ?? that were compiled in the same package that it was.
accept
accept NEWSOCKET, GENERICSOCKET
This function does the same thing as the accept system call--see accept (2). It is used by server processes that wish to accept socket connections from clients. Execution is suspended until a connection is made, at which time the NEWSOCKET filehandle is opened and attached to the newly made connection. The function returns the connected address if the call succeeded, false otherwise (and puts the error code into $!). GENERICSOCKET must be a filehandle already opened via the socket operator and bound to one of the server's network addresses. For example:
unless ($peer = accept NS, S) {
die "Can't accept a connection: $!\n";
}
See also the example in the section "Sockets" in Chapter 6, Social Engineering.
alarm
alarm EXPR
This function sends a SIGALRM signal to the executing Perl program after EXPR seconds. On some older systems, alarms go off at the "top of the second," so, for instance, an alarm 1 may go off anywhere between 0 to 1 second from now, depending on when in the current second it is. An alarm 2 may go off anywhere from 1 to 2 seconds from now. And so on. For better resolution, you may be able to use syscall to call the itimer routines that some UNIX systems support. Or you can use the timeout feature of the select function.
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 return value is the number of seconds remaining on the previous timer.
atan2
atan2 Y, X
This function returns the arctangent of Y/X in the range -pi to pi. A quick way to get an approximate value of pi is to say:
$pi = atan2(1,1) * 4;
For the tangent operation, you may use the POSIX::tan() function, or use the familiar relation:
sub tan { sin($_[0]) / cos($_[0]) }
bind
bind SOCKET, NAME
This function does the same thing as the bind system call--see bind (2). It attaches an address (a name) to an already opened socket specified by the SOCKET filehandle. The function returns true if it succeeded, false otherwise (and puts the error code into $!). NAME should be a packed address of the proper type for the socket.
bind S, $sockaddr or die "Can't bind address: $!\n";
See also the example in the section "Sockets" in Chapter 6, Social Engineering.
binmode
binmode FILEHANDLE
This function arranges for the file to be treated in binary mode on operating systems that distinguish between binary and text files. It should be called after the open but before any I/O is done on the filehandle. The only way to reset binary mode on a filehandle is to reopen the file.
On systems that distinguish binary mode from text mode, files that are read in text mode have \r\n sequences translated to \n on input and \n translated to \r\n on output. binmode has no effect under UNIX or Plan9. If FILEHANDLE is an expression, the value is taken as the name of the filehandle. The following example shows how a Perl script might prepare to read a word processor file with embedded control codes:
open WP, "$file.wp" or die "Can't open $file.wp: $!\n";
binmode WP;
while (read WP, $buf, 1024) {...}
bless
bless REF, CLASSNAME bless REF
This function looks up the item pointed to by reference REF and tells the item that it is now an object in the CLASSNAME package--or the current package if no CLASSNAME is specified, which is often the case. It returns the reference for convenience, since a bless is often the last thing in a constructor function. (Always use the two-argument version if the constructor doing the blessing might be inherited by a derived class. In such cases, the class you want to bless your object into will normally be found as the first argument to the constructor in question.) See "Objects" in Chapter 5, Packages, Modules, and Object Classes for more about the blessing (and blessings) of objects.
caller
caller EXPR caller
This function returns information about the stack of current subroutine calls. Without an argument it returns the package name, filename, and line number that the currently executing subroutine was called from:
($package, $filename, $line) = caller;
With an argument it evaluates EXPR as the number of stack frames to go back before the current one. It also reports some additional information.
$i = 0;
while (($pack, $file, $line, $subname, $hasargs, $wantarray) = caller($i++)) {
...
}
Furthermore, when called from within the DB package, caller returns more detailed information: it sets the list variable @DB::args to be the arguments passed in the given stack frame.
chdir
chdir EXPR
This function changes the working directory to EXPR, if possible. If EXPR is omitted, it changes to the home directory. The function returns 1 upon success, 0 otherwise (and puts the error code into $!).
chdir "$prefix/lib" or die "Can't cd to $prefix/lib: $!\n";
The following code can be used to move to the user's home directory, one way or another:
$ok = chdir($ENV{"HOME"} || $ENV{"LOGDIR"} || (getpwuid($<))[7]);
Alternately, taking advantage of the default, you could say this:
$ok = chdir() || chdir((getpwuid($<))[7]);
See also the Cwd module, described in Chapter 7, The Standard Perl Library, which lets you keep track of your current directory.
chmod
chmod LIST
This function changes the permissions of a list of files. The first element of the list must be the numerical mode, as in chmod (2). (When using nonliteral mode data, you may need to convert an octal string to a decimal number using the oct function.) The function returns the number of files successfully changed. For example:
$cnt = chmod 0755, 'file1', 'file2';
will set $cnt to 0, 1, or 2, depending on how many files got changed (in the sense that the operation succeeded, not in the sense that the bits were different afterward). Here's a more typical usage:
chmod 0755, @executables;
If you need to know which files didn't allow the change, use something like this:
@cannot = grep {not chmod 0755, $_} 'file1', 'file2', 'file3';
die "$0: could not chmod @cannot\n" if @cannot;
This idiom makes use of the grep function to select only those elements of the list for which the chmod function failed.
chomp
chomp VARIABLE chomp LIST chomp
This is a slightly safer version of chop (see below) in that it removes only any line ending corresponding to the current value of $/, and not just any last character. Unlike chop, chomp returns the number of characters deleted. If $/ is empty (in paragraph mode), chomp removes all trailing newlines from the selected string (or strings, if chomping a LIST).
chop
chop VARIABLE chop LIST chop
This function chops off the last character of a string and returns the character chopped. The chop operator is used primarily to remove the newline from the end of an input record, but is more efficient than s/\n$//. If VARIABLE is omitted, the function chops the $_ variable. For example:
while (<PASSWD>) {
chop; # avoid \n on last field
@array = split /:/;
...
}
If you chop a LIST, each string in the list is chopped:
@lines = `cat myfile`; chop @lines;
You can actually chop anything that is an lvalue, including an assignment:
chop($cwd = `pwd`); chop($answer = <STDIN>);
Note that this is different from:
$answer = chop($tmp = <STDIN>); # WRONG
which puts a newline into $answer, because chop returns the character chopped, not the remaining string (which is in $tmp). One way to get the result intended here is with substr:
$answer = substr <STDIN>, 0, -1;
But this is more commonly written as:
chop($answer = <STDIN>);
To chop more than one character, use substr as an lvalue, assigning a null string. The following removes the last five characters of $caravan:
substr($caravan, -5) = "`;
The negative subscript causes substr to count from the end of the string instead of the beginning.
chown
chown LIST
This function changes the owner (and group) of a list of files. The first two elements of the list must be the numerical uid and gid, in that order. The function returns the number of files successfully changed. For example:
$cnt = chown $uid, $gid, 'file1', 'file2';
will set $cnt to 0, 1, or 2, depending on how many files got changed (in the sense that the operation succeeded, not in the sense that the owner was different afterward). Here's a more typical usage:
chown $uid, $gid, @filenames;
Here's a subroutine that looks everything up for you, and then does the chown:
sub chown_by_name {
local($user, $pattern) = @_;
chown((getpwnam($user))[2,3], glob($pattern));
}
&chown_by_name("fred", "*.c");
Notice that this forces the group of each file to be the gid fetched from the passwd file. An alternative is to pass a -1 for the gid, which leaves the group of the file unchanged.
On most systems, you are not allowed to change the ownership of the file unless you're the superuser, although you should be able to change the group to any of your secondary groups. On insecure systems, these restrictions may be relaxed, but this is not a portable assumption.
chr
chr NUMBER
This function returns the character represented by that NUMBER in the character set. For example, chr(65) is "A" in ASCII. To convert multiple characters, use pack(`C*`, LIST) instead.
chroot
chroot FILENAME
This function does the same operation as the chroot system call--see chroot (2). If successful, FILENAME becomes the new root directory for the current process--the starting point for pathnames beginning with "/". This directory is inherited across exec calls and by all subprocesses. There is no way to undo a chroot. Only the superuser can use this function. Here's some code that approximates what many FTP servers do:
chroot +(getpwnam('ftp'))[7]
or die "Can't do anonymous ftp: $!\n";
close
close FILEHANDLE
This function closes the file, socket, or pipe associated with the filehandle. You don't have to close FILEHANDLE if you are immediately going to do another open on it, since the next 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 afterward), and it prevents the script from exiting before the pipeline is finished.[1] Closing a pipe explicitly also puts the status value of the command executing on the pipe into $?. For example:
[1] Note, however, that a dup'ed pipe is treated as an ordinary filehandle, and close will not wait for the child on that filehandle. You have to wait for the child by closing the filehandle on which it was originally opened.
open OUTPUT, '|sort >foo'; # pipe to sort ... # print stuff to output close OUTPUT; # wait for sort to finish die "sort failed" if $?; # check for sordid sort open INPUT, 'foo'; # get sort's results
FILEHANDLE may be an expression whose value gives the real filehandle name. It may also be a reference to a filehandle object returned by some of the newer object-oriented I/O packages.
closedir
closedir DIRHANDLE
This function closes a directory opened by opendir. See the examples under opendir.
connect
connect SOCKET, NAME
This function does the same thing as the connect system call--see connect (2). The function initiates a connection with another process that is waiting at an accept (2). The function returns true if it succeeded, false otherwise (and puts the error code into $!). NAME should be a packed network address of the proper type for the socket. For example:
connect S, $destadd
or die "Can't connect to $hostname: $!\n";
To disconnect a socket, either close or shutdown. See also the example in the section "Sockets" in Chapter 6, Social Engineering.
cos
cos EXPR
This function returns the cosine of EXPR (expressed in radians). For example, the following script will print a cosine table of angles measured in degrees:
# Here's the lazy way of getting degrees-to-radians.
$pi = atan2(1,1) * 4;
$piover180 = $pi/180;
# Print table.
for ($_ = 0; $_ <= 90; $_++) {
printf "%3d %7.5f\n", $_, cos($_ * $piover180);
}
For the inverse cosine operation, you may use the POSIX::acos() function, or use this relation:
sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
crypt
crypt PLAINTEXT, SALT
This function encrypts a string exactly in the manner of crypt (3). This is useful for checking the password file for lousy passwords.[2] Only the guys wearing white hats are allowed to do this.
[2] What you really want to do is prevent people from adding the bad passwords in the first place.
To see whether a typed-in password $guess matches the password $pass obtained from a file (such as /etc/passwd), try something like the following:
if (crypt($guess, $pass) eq $pass) {
# guess is correct
}
Note that there is no easy way to decrypt an encrypted password apart from guessing. Also, truncating the salt to two characters is a waste of CPU time, although the manpage for crypt (3) would have you believe otherwise.
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 for it is unwise.
The crypt function is unsuitable for encrypting large quantities of data. Find a library module for PGP (or something like that) for something like that.
dbmclose
dbmclose HASH
This function breaks the binding between a DBM file and a hash.
This function is actually just a call to untie with the proper arguments, but is provided for backward compatibility with older versions of Perl.
dbmopen
dbmopen HASH, DBNAME, MODE
This binds a DBM file to a hash (that is, an associative array). (DBM stands for Data Base Management, and consists of a set of C library routines that allow random access to records via a hashing algorithm.) HASH is the name of the hash (with a %). DBNAME is the name of the database (without the .dir or .pag extension). If the database does not exist, and a valid MODE is specified, the database is created with the protection specified by MODE (as modified by the umask). To prevent creation of the database if it doesn't exist, you may specify a MODE of undef, and the function will return a false value if it can't find an existing database. If your system supports only the older DBM functions, you may have only one dbmopen in your program.
Values assigned to the hash prior to the dbmopen are not accessible.
If you don't have write access to the DBM file, you can only read the hash 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 list values when used on large DBM files. You may prefer to use the each function to iterate over large DBM files. This example prints out the mail aliases on a system using sendmail:
dbmopen %ALIASES, "/etc/aliases", 0666
or die "Can't open aliases: $!\n";
while (($key,$val) = each %ALIASES) {
print $key, ' = ', $val, "\n";
}
dbmclose %ALIASES;
Hashes bound to DBM files have the same limitations as DBM files, in particular the restrictions on how much you can put into a bucket. If you stick to short keys and values, it's rarely a problem. Another thing you should bear in mind is that many existing DBM databases contain null-terminated keys and values because they were set up with C programs in mind. The B News history file and the old sendmail aliases file are examples. Just use "$key\0" instead of $key.
There is currently no built-in way to lock generic DBM files. Some would consider this a bug. The DB_File module does provide locking at the granularity of the entire file, however. See the documentation on that module in Chapter 7, The Standard Perl Library for details.
This function is actually just a call to tie with the proper arguments, but is provided for backward compatibility with older versions of Perl.
defined
defined EXPR
This function returns a Boolean value saying whether EXPR has a real value or not. A scalar that contains no valid string, numeric, or reference value is known as the undefined value, or undef for short. 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 string and a defined null string when you're using operators that might return a real null string.
You may also check to see whether arrays, hashes, or subroutines have been allocated any memory yet. Arrays and hashes are allocated when you first put something into them, whereas subroutines are allocated when a definition has been successfully parsed. Using defined on the predefined special variables is not guaranteed to produce intuitive results.
Here is a fragment that tests a scalar value from a hash:
print if defined $switch{'D'};
When used on a hash element like this, defined only tells you whether the value is defined, not whether the key has an entry in the hash table. It's possible to have an undefined scalar value for an existing hash key. Use exists to determine whether the hash key exists.
In the next example we use the fact that some operations return the undefined value when you run out of data:
print "$val\n" while defined($val = pop(@ary));
The same thing goes for error returns from system calls:
die "Can't readlink $sym: $!"
unless defined($value = readlink $sym);
Since symbol tables for packages are stored as hashes (associative arrays), it's possible to check for the existence of a package like this:
die "No XYZ package defined" unless defined %XYZ::;
Finally, it's possible to avoid blowing up on nonexistent subroutines:
sub saymaybe {
if (defined &say) {
say(@_);
}
else {
warn "Can't say";
}
}
See also undef.
delete
delete EXPR
This function deletes the specified key and associated value from the specified hash. (It doesn't delete a file. See unlink for that.) Deleting from $ENV{} modifies the environment. Deleting from a hash that is bound to a (writable) DBM file deletes the entry from the DBM file.
The following naïve example inefficiently deletes all the values of a hash:
foreach $key (keys %HASH) {
delete $HASH{$key};
}
(It would be faster to use the undef command.) EXPR can be arbitrarily complicated as long as the final operation is a hash key lookup:
delete $ref->[$x][$y]{$key};
For normal hashes, the delete function happens to return the value (not the key) that was deleted, but this behavior is not guaranteed for tied hashes, such as those bound to DBM files.
To test whether a hash element has been deleted, use exists.
die
die LIST
Outside of an eval, this function prints the concatenated value of LIST to STDERR and exits with the current value of $! (errno). If $! is 0, it exits with the value of ($? >> 8) (which is the status of the last reaped child from a system, wait, close on a pipe, or `command`). If ($? >> 8) is 0, it exits with 255. If LIST is unspecified, the current value of the $@ variable is propagated, if any. Otherwise the string "Died" is used as the default.
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"
(The second form is generally preferred, since the important part is the chdir.)
Within an eval, the function sets the $@ variable equal to the error message that would have been produced otherwise, and aborts the eval, which then returns the undefined value. The die function can thus be used to raise named exceptions that can be caught at a higher level in the program. See the section on the eval function later in this chapter.
If the final value of LIST does not end in a newline, the current script filename, line number, and input line number (if any) are appended to the message, as well as a newline. Hint: sometimes appending `, stopped" to your message will cause it to make better sense when the string "at scriptname line 123" is appended. Suppose you are running script canasta:
die "/etc/games is no good"; die "/etc/games is no good, stopped";
which produces, respectively:
/etc/games is no good at canasta line 123. /etc/games is no good, stopped at canasta line 123.
If you want your own error messages reporting the filename and linenumber, use the _ _FILE_ _ and _ _LINE_ _ special tokens:
die '"', _ _FILE_ _, '", line ', _ _LINE_ _, ", phooey on you!\n";
This produces output like:
"canasta", line 38, phooey on you!
do
do BLOCK do SUBROUTINE(LIST) do EXPR
The do BLOCK form executes the sequence of commands in the BLOCK, and returns the value of the last expression evaluated in the block. When modified by a loop modifier, Perl executes the BLOCK once before testing the loop condition. (On other statements the loop modifiers test the conditional first.)
The do SUBROUTINE(LIST) is a deprecated form of a subroutine call. See "Subroutines" in Chapter 2, The Gory Details.
The do EXPR, form uses the value of EXPR as a filename and executes the contents of the file as a Perl script. Its primary use is (or rather was) to include subroutines from a Perl subroutine library, so that:
do 'stat.pl';
is rather 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 directories listed in the @INC array. (See the section on "Special Variables" in Chapter 2, The Gory Details.) 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, which also do error checking and raise an exception if there's a problem.
dump
dump LABEL dump
This function causes an immediate core dump. Primarily this is so that you can use undump (1) to turn your core dump into an executable binary after having initialized all your variables at the beginning of the program. (The undump program is not supplied with the Perl distribution, and is not even possible on some architectures. There are hooks in the code for using the GNU unexec() routine as an alternative. Other methods may be supported in the future.) When the new binary is executed it will begin by executing a goto LABEL (with all the restrictions that goto suffers). Think of the operation as a goto with an intervening core dump and reincarnation. If LABEL is omitted, the function arranges for the program to restart from the top. Please note that any files opened at the time of the dump will not be open any more when the program is reincarnated, with possible confusion resulting on the part of Perl. See also the -u command-line switch. For example:
#!/usr/bin/perl
use Getopt::Std;
use MyHorridModule;
%days = (
Sun => 1,
Mon => 2,
Tue => 3,
Wed => 4,
Thu => 5,
Fri => 6,
Sat => 7,
);
dump QUICKSTART if $ARGV[0] eq '-d';
QUICKSTART:
Getopts('f:');
...
This startup code does some slow initialization code, and then calls the dump function to take a snapshot of the program's state. When the dumped version of the program is run, it bypasses all the startup code and goes directly to the QUICKSTART label. If the original script is invoked without the -d switch, it just falls through and runs normally.
If you're looking to use dump to speed up your program, check out the discussion of efficiency matters in Chapter 8, Other Oddments, as well the Perl native-code compiler in Chapter 6, Social Engineering. You might also consider autoloading, which at least makes it appear to run faster.
each
each HASH
This function returns a two-element list consisting of the key and value for the next value of a hash. With successive calls to each you can iterate over the entire hash. Entries are returned in an apparently random order. When the hash is entirely read, a null list is returned (which, when used in a list assignment, produces a false value). The next call to each after that will start a new iteration. The iterator can be reset either by reading all the elements from the hash, or by calling the keys function in scalar context. You must not add elements to the hash while iterating over it, although you are permitted to use delete. In a scalar context, each returns just the key, but watch out for false keys.
There is a single iterator for each hash, shared by all each, keys, and values function calls in the program. This means that after a keys or values call, the next each call will start again from the beginning. The following example prints out your environment like the printenv (1) program, only in a different order:
while (($key,$value) = each %ENV) {
print "$key=$value\n";
}
eof
eof FILEHANDLE eof() eof
This function returns true 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. An eof without an argument returns the end-of-file status for the last file read. Empty parentheses () may be used in connection with the combined files listed on the command line. That is, inside a while (<>) loop eof() will detect the end of only the last of a group of files. Use eof(ARGV) or eof (without the parentheses) to test each file in a while (<>) loop. For example, the following code inserts dashes just before the last line of the last file:
while (<>) {
if (eof()) {
print "-" x 30, "\n";
}
print;
}
On the other hand, this script resets line numbering on each input file:
while (<>) {
print "$.\t$_";
if (eof) { # Not eof().
close ARGV; # reset $.
}
}
Like "$" in a sed program, eof tends to show up in line number ranges. Here's a script that prints lines from /pattern/ to end of each input file:
while (<>) {
print if /pattern/ .. eof;
}
Here, the flip-flop operator (..) evaluates the regular expression match for each line. Until the pattern matches, the operator returns false. When it finally matches, the operator starts returning true, causing the lines to be printed. When the eof operator finally returns true (at the end of the file being examined), the flip-flop operator resets, and starts returning false again.
Note that the eof function actually reads a byte and then pushes it back on the input stream with ungetc (3), so it is not very useful in an interactive context. In fact, experienced Perl programmers rarely use eof, since the various input operators already behave quite nicely in while-loop conditionals. See the example in the description of foreach in Chapter 2, The Gory Details.
eval
eval EXPR eval BLOCK
The value expressed by EXPR is parsed and executed as though it were a little Perl program. It is executed in the context of the current Perl program, so that any variable settings remain afterward, as do any subroutine or format definitions. The code of the eval is treated as a block, so any locally scoped variables declared within the eval last only until the eval is done. (See local and my.) As with any code in a block, a final semicolon is not required. If EXPR is omitted, the operator evaluates $_.
The value returned from an eval is the value of the last expression evaluated, just as with subroutines. Similarly, you may use the return operator to return a value from the middle of the eval. If there is a syntax error or run-time error (including any produced by the die operator), eval returns the undefined value and puts the error message in $@. If there is no error, $@ is guaranteed to be set to the null string, so you can test it reliably afterward for errors.
Here's a statement that assigns an element to a hash chosen at run-time:
eval "\$$arrayname{\$key} = 1";
(You can accomplish that more simply with soft references--see "Symbolic References" in Chapter 4, References and Nested Data Structures.) And here is a simple Perl shell:
while (<>) { eval; print $@; }
Since eval traps otherwise-fatal errors, it is useful for determining whether a particular feature (such as socket or symlink) is implemented. In fact, eval is the way to do all exception handling in Perl. If the code to be executed doesn't vary, you should use the eval BLOCK form to trap run-time errors; the code in the block is compiled only once rather than on each execution, yielding greater efficiency. The error, if any, is still returned in $@. 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 (not trapped)
eval { $answer = };
# a run-time error
eval '$answer ='; # sets $@
Here, the code in the BLOCK has to be valid Perl code to make it past the compilation phase. The code in the string doesn't get examined until run-time, and so doesn't cause an error until run-time.
With an eval you should be 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. (Case 2 has misleading double quotes, making the reader wonder what else might be happening, when nothing is. The contents of $x would in any event have to be converted to a string for parsing.) Cases 3 and 4 likewise behave in the same way: they run the code $x, which does nothing at all except return the value of $x. (Case 4 is preferred since the expression doesn't need to recompiled each time.) Case 5 is a place where normally you would like to use double quotes to let you interpolate the variable name, except that in this particular situation you can just use symbolic references instead, as in case 6.
A frequently asked question is how to set up an exit routine. One common way is to use an END block. But you can also do it with an eval, like this:
#!/usr/bin/perl
eval <<'EndOfEval'; $start = __LINE__;
.
. # your ad here
.
EndOfEval
# Cleanup
unlink "/tmp/myfile$$";
$@ && ($@ =~ s/\(eval \d+\) at line (\d+)/$0 .
" line " . ($1+$start)/e, die $@);
exit 0;
Note that the code supplied for an eval might not be recompiled if the text hasn't changed. On the rare occasions when you want to force a recompilation (because you want to reset a .. operator, for instance), you could say something like this:
eval $prog . '#' . ++$seq;
exec
exec LIST
This function terminates the currently running Perl script by executing another program in place of itself. If there is more than one argument in LIST (or if LIST is an array with more than one value) the function calls C's execvp (3) routine with the arguments in LIST. This bypasses any shell processing of the command. If there is only one scalar argument, the argument is checked for shell metacharacters. If metacharacters are found, the entire argument is passed to "/bin/sh -c" for parsing.[3] If there are no metacharacters, the argument is split into words and passed directly to execvp (3) in the interests of efficiency, since this bypasses all the overhead of shell processing. Ordinarily exec never returns--if it does return, it always returns false, and you should check $! to find out what went wrong. Note that exec (and system) do not flush your output buffer, so you may need to enable command buffering by setting $| on one or more filehandles to avoid lost output. This statement runs the echo program to print the current argument list:
[3] Under UNIX, that is. Other operating systems may use other command interpreters.
exec 'echo', 'Your arguments are: ', @ARGV;
This example shows that you can exec a pipeline:
exec "sort $outfile | uniq" or die "Can't do sort/uniq: $!\n";
The UNIX execv (3) call provides the ability to tell a program the name it was invoked as. This name might have nothing to do with the name of the program you actually gave the operating system to run. By default, Perl simply replicates the first element of LIST and uses it for both purposes. If, however, you don't really want to execute the first argument of LIST, but you want to lie to the program you are executing about its own name, you can do so. Put the real name of the program you want to run into a variable and then put that variable out in front of the LIST without a comma, kind of like a filehandle for a print statement. (This always forces interpretation of the LIST as a multi-valued list, even if there is only a single scalar in the list.) Then the first element of LIST will be used only to mislead the executing program as to its name. For example:
$shell = '/bin/csh'; exec $shell '-sh', @args; # pretend it's a login shell die "Couldn't execute csh: $!\n";
You can also replace the simple scalar holding the program name with a block containing arbitrary code, which simplifies the above example to:
exec {'/bin/csh'} '-sh', @args; # pretend it's a login shell
exists
exists EXPR
This function returns true if the specified hash key exists in its hash, even if the corresponding value is undefined.
print "Exists\n" if exists $hash{$key};
print "Defined\n" if defined $hash{$key};
print "True\n" if $hash{$key};
A hash element can only be true if it's defined, and can only be defined if it exists, but the reverse doesn't necessarily hold true in either case.
EXPR can be arbitrarily complicated as long as the final operation is a hash key lookup:
if (exists $ref->[$x][$y]{$key}) { ... }
exit
exit EXPR
This function evaluates EXPR and exits immediately with that value. Here's a fragment that lets a user exit the program by typing x or X:
$ans = <STDIN>; exit 0 if $ans =~ /^[Xx]/;
If EXPR is omitted, the function exits with 0 status. You shouldn't use exit to abort a subroutine if there's any chance that someone might want to trap whatever error happened. Use die instead, which can be trapped by an eval.
exp
exp EXPR
This function returns e to the power of EXPR. If EXPR is omitted, it gives exp($_). To do general exponentiation, use the ** operator.
fcntl
fcntl FILEHANDLE, FUNCTION, SCALAR
This function calls UNIX's fcntl (2) function. (fcntl stands for "file control".) You'll probably have to say:
use Fcntl;
first to get the correct function definitions. 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 fcntl call. (If SCALAR has no string value but does have a numeric value, that value will be passed directly rather than a pointer to the string value.)
The return value of fcntl (and ioctl) is as follows:
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 = fcntl(...) or $retval = -1; printf "System returned %d\n", $retval;
Here, even the string "0 but true" prints as 0, thanks to the %d format.
For example, since Perl always sets the close-on-exec flag for file descriptors above 2, if you wanted to pass file descriptor 3 to a subprocess, you might want to clear the flag like this:
use Fcntl;
open TTY,"+>/dev/tty" or die "Can't open /dev/tty: $!\n";
fileno TTY == 3 or die "Internal error: fd mixup";
fcntl TTY, &F_SETFL, 0
or die "Can't clear the close-on-exec flag: $!\n";
fcntl will produce a fatal error if used on a machine that doesn't implement fcntl (2). On machines that do implement it, you can do such things as modify the close-on-exec flags, modify the non-blocking I/O flags, emulate the lockf (3) function, and arrange to receive the SIGIO signal when I/O is pending. You might even have record-locking facilities.
fileno
fileno FILEHANDLE
This function returns the file descriptor for a filehandle. (A file descriptor is a small integer, unlike the filehandle, which is a symbol.) It returns undef if the handle is not open. It's useful for constructing bitmaps for select, and for passing to certain obscure system calls if syscall (2) is implemented. It's also useful for double-checking that the open function gave you the file descriptor you wanted--see the example under fcntl.
If FILEHANDLE is an expression, its value is taken to represent a filehandle, either indirectly by name, or directly as a reference to a filehandle object.
A caution: don't count on the association of a Perl filehandle and a numeric file descriptor throughout the life of the program. If a file has been closed and reopened, the file descriptor may change. Filehandles STDIN, STDOUT, and STDERR start with file descriptors of 0, 1, and 2 (the UNIX standard convention), but even they can change if you start closing and opening them with wild abandon. But you can't get into trouble with 0, 1, and 2 as long as you always reopen immediately after closing, since the basic rule on UNIX systems is to pick the lowest available descriptor, and that'll be the one you just closed.
flock
flock FILEHANDLE, OPERATION
This function calls flock (2) on FILEHANDLE. See the manual page for flock (2) for the definition of OPERATION. Invoking flock will produce a fatal error if used on a machine that doesn't implement flock (2) or emulate it through some other locking mechanism. Here's a mailbox appender for some BSD-based 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 is unlikely to work on a file being accessed through a network file system.
fork
fork
This function does a fork (2) call. If it succeeds, the function returns the child pid to the parent process and 0 to the child process. (If it fails, it returns the undefined value to the parent process. There is no child process.) Note that unflushed buffers remain unflushed in both processes, which means you may need to set $| on one or more filehandles earlier in the program to avoid duplicate output.
A nearly bulletproof way to launch a child process while checking for "cannot fork" errors would be:
FORK: {
if ($pid = fork) {
# parent here
# child process pid is available in $pid
} elsif (defined $pid) { # $pid is zero here if defined
# child here
# parent process pid is available with getppid
} elsif ($! =~ /No more process/) {
# EAGAIN, supposedly recoverable fork error
sleep 5;
redo FORK;
} else {
# weird fork error
die "Can't fork: $!\n";
}
}
These precautions are not necessary on operations which do an implicit fork (2), such as system, backquotes, or opening a process as a filehandle, because Perl automatically retries a fork on a temporary failure in these cases. Be very careful to end the child code with an exit, or your child may inadvertently leave the conditional and start executing code intended only for the parent process.
If you fork your child processes, you'll have to wait on their zombies when they die. See the wait function for examples of doing this.
The fork function is unlikely to be implemented on any operating system not resembling UNIX, unless it purports POSIX compliance.
format
format NAME =
picture line
value list
...
.
Declares a named sequence of picture lines (with associated values) for use by the write function. If NAME is omitted, the name defaults to STDOUT, which happens to be the default format name for the STDOUT filehandle. Since, like a sub declaration, this is a global declaration that happens at compile time, any variables used in the value list need to be visible at the point of the format's declaration. That is, lexically scoped variables must be declared earlier in the file, while dynamically scoped variables merely need to be set in the routine that calls write. Here's an example (which assumes we've already calculated $cost and $quantity:
my $str = "widget"; # A lexically scoped variable.
format Nice_Output =
Test: @<<<<<<<< @||||| @>>>>>
$str, $%, '$' . int($num)
.
$~ = "Nice_Output"; # Select our format.
local $num = $cost * $quantity; # Dynamically scoped variable.
write;
Like filehandles, format names are identifiers that exist in a symbol table (package) and may be fully qualified by package name. Within the typeglobs of a symbol table's entries, formats reside in their own namespace, which is distinct from filehandles, directory handles, scalars, arrays, hashes, or subroutines. Like those other six types, however, a format named Whatever would also be affected by a local on the *Whatever typeglob. In other words, a format is just another gadget contained in a typeglob, independent of the other gadgets.
The "Formats" section in Chapter 2, The Gory Details contains numerous details and examples of their use. The "Per Filehandle Special Variables" and "Global Special Variables" sections in Chapter 2, The Gory Details describe the internal format-specific variables, and the English and FileHandle modules in Chapter 7, The Standard Perl Library provide easier access to them.
formline
formline PICTURE, LIST
This is an internal function used by formats, although you may also call it. It formats a list of values according to the contents of PICTURE, placing the output into the format output accumulator, $^A. Eventually, when a write is done, the contents of $^A are written to some filehandle, but you could also read $^A yourself and then set $^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. This means that the ~ and ~~ tokens will treat the entire PICTURE as a single line. You may therefore need to use multiple formlines to implement a single record-format, just like the format compiler.
Be careful if you put double quotes around the picture, since an @ character may be taken to mean the beginning of an array name. formline always returns true. See "Formats" in Chapter 2, The Gory Details for other examples.
getc
getc FILEHANDLE getc
This function returns the next byte from the input file attached to FILEHANDLE. At end-of-file, it returns a null string. If FILEHANDLE is omitted, the function reads from STDIN. This operator is very slow, but is occasionally useful for single-character, buffered input from the keyboard. This does not enable single-character input. For unbuffered input, you have to be slightly more clever, in an operating-system-dependent fashion. Under UNIX you might say this:
if ($BSD_STYLE) {
system "stty cbreak </dev/tty >/dev/tty 2>&1";
} else {
system "stty", "-icanon", "eol", "\001";
}
$key = getc;
if ($BSD_STYLE) {
system "stty -cbreak </dev/tty >/dev/tty 2>&1";
} else {
system "stty", "icanon", "eol", "^@"; # ASCII NUL
}
print "\n";
This code puts the next character typed on the terminal in the string $key. If your stty program has options like cbreak, you'll need to use the code where $BSD_STYLE is true, otherwise, you'll need to use the code where it is false. Determining the options for stty is left as an exercise to the reader.
The POSIX module in Chapter 7, The Standard Perl Library provides a more portable version of this using the POSIX::getattr() function. See also the TERM::ReadKey module from your nearest CPAN site.
getgrent
getgrent setgrent endgrent
These functions do the same thing as their like-named system library routines--see getgrent (3). These routines iterate through your /etc/group file (or its moral equivalent coming from some server somewhere). The return value from getgrent in list context is:
($name, $passwd, $gid, $members)
where $members contains a space-separated list of the login names of the members of the group. To set up a hash for translating group names to gids, say this:
while (($name, $passwd, $gid) = getgrent) {
$gid{$name} = $gid;
}
In scalar context, getgrent returns only the group name.
getgrgid
getgrgid GID
This function does the same thing as getgrgid (3): it looks up a group file entry by group number. The return value in list context is:
($name, $passwd, $gid, $members)
where $members contains a space-separated list of the login names of the members of the group. If you want to do this repeatedly, consider caching the data in a hash (associative array) using getgrent.
In scalar context, getgrgid returns only the group name.
getgrnam
getgrnam NAME
This function does the same thing as getgrnam (3): it looks up a group file entry by group name. The return value in list context is:
($name, $passwd, $gid, $members)
where $members contains a space-separated list of the login names of the members of the group. If you want to do this repeatedly, consider slurping the data into a hash (associative array) using getgrent.
In scalar context, getgrnam returns only the numeric group ID.
gethostbyaddr
gethostbyaddr ADDR, ADDRTYPE
This function does the same thing as gethostbyaddr (3): it translates a packed binary network address to its corresponding names (and alternate addresses). The return value in list context is:
($name, $aliases, $addrtype, $length, @addrs)
where @addrs is a list of packed binary addresses. In the Internet domain, each address is four bytes long, and can be unpacked by saying something like:
($a, $b, $c, $d) = unpack('C4', $addrs[0]);
In scalar context, gethostbyaddr returns only the host name. See the section on "Sockets" in Chapter 6, Social Engineering for another approach.
gethostbyname
gethostbyname NAME
This function does the same thing as gethostbyname (3): it translates a network hostname to its corresponding addresses (and other names). The return value in list context is:
($name, $aliases, $addrtype, $length, @addrs)
where @addrs is a list of raw addresses. In the Internet domain, each address is four bytes long, and can be unpacked by saying something like:
($a, $b, $c, $d) = unpack('C4', $addrs[0]);
In scalar context, gethostbyname returns only the host address. See the section on "Sockets" in Chapter 6, Social Engineering for another approach.
gethostent
gethostent sethostent STAYOPEN endhostent
These functions do the same thing as their like-named system library routines--see gethostent (3).
They iterate through your /etc/hosts file and return each entry one at a time. The return value from gethostent is:
($name, $aliases, $addrtype, $length, @addrs)
where @addrs is a list of raw addresses. In the Internet domain, each address is four bytes long, and can be unpacked by saying something like:
($a, $b, $c, $d) = unpack('C4', $addrs[0]);
Scripts that use these routines should not be considered portable. If a machine uses a nameserver, it would interrogate most of the Internet to try to satisfy a request for all the addresses of every machine on the planet. So these routines are unimplemented on such machines.
getlogin
getlogin
This function returns the current login from /etc/utmp, if any. If null, use getpwuid. For example:
$login = getlogin || (getpwuid($<))[0] || "Intruder!!";
getnetbyaddr
getnetbyaddr ADDR, ADDRTYPE
This function does the same thing as getnetbyaddr (3): it translates a network address to the corresponding network name or names. The return value in list context is:
($name, $aliases, $addrtype, $net)
In scalar context, getnetbyaddr returns only the network name.
getnetbyname
getnetbyname NAME
This function does the same thing as getnetbyname (3): it translates a network name to its corresponding network address. The return value in list context is:
($name, $aliases, $addrtype, $net)
In scalar context, getnetbyname returns only the network address.
getnetent
getnetent setnetent STAYOPEN endnetent
These functions do the same thing as their like-named system library routines--see getnetent (3). They iterate through your /etc/networks file, or moral equivalent. The return value in list context is:
($name, $aliases, $addrtype, $net)
In scalar context, getnetent returns only the network name.
getpeername
getpeername SOCKET
This function returns the packed socket address of other end of the SOCKET connection. For example:
use Socket; $hersockaddr = getpeername SOCK; ($port, $heraddr) = unpack_sockaddr_in($hersockaddr); $herhostname = gethostbyaddr($heraddr, AF_INET); $herstraddr = inet_ntoa($heraddr);
getpgrp
getpgrp PID
This function returns the current process group for the specified PID (use a PID of 0 for the current process). Invoking getpgrp will produce a fatal error if used on a machine that doesn't implement getpgrp (2). If PID is omitted, the function returns the process group of the current process (the same as using a PID of 0). On systems implementing this operator with the POSIX getpgrp (2) system call, PID must be omitted or, if supplied, must be 0.
getppid
getppid
This function returns the process ID of the parent process. On the typical UNIX system, if your parent process ID changes to 1, your parent process has died and you've been adopted by the init program.
getpriority
getpriority WHICH, WHO
This function returns the current priority for a process, a process group, or a user. See getpriority (2). Invoking getpriority will produce a fatal error if used on a machine that doesn't implement getpriority (2). For example, to get the priority of the current process, use:
$curprio = getpriority(0, 0);
getprotobyname
getprotobyname NAME
This function does the same thing as getprotobyname (3): it translates a protocol name to its corresponding number. The return value in list context is:
($name, $aliases, $protocol_number)
In scalar context, getprotobyname returns only the protocol number.
getprotobynumber
getprotobynumber NUMBER
This function does the same thing as getprotobynumber (3): it translates a protocol number to its corresponding name. The return value in list context is:
($name, $aliases, $protocol_number)
In scalar context, getprotobynumber returns only the protocol name.
getprotoent
getprotoent setprotoent STAYOPEN endprotoent
These functions do the same thing as their like-named system library routines--see getprotent (3). The return value from getprotoent is:
($name, $aliases, $protocol_number)
In scalar context, getprotoent returns only the protocol name.
getpwent
getpwent setpwent endpwent
These functions do the same thing as their like-named system library routines--see getpwent (3). They iterate through your /etc/passwd file (or its moral equivalent coming from some server somewhere). The return value in list context is:
($name,$passwd,$uid,$gid,$quota,$comment,$gcos,$dir,$shell)
Some machines may use the quota and comment fields for other purposes, but the remaining fields will always be the same. To set up a hash for translating login names to uids, say this:
while (($name, $passwd, $uid) = getpwent) {
$uid{$name} = $uid;
}
In scalar context, getpwent returns only the username.
getpwnam
getpwnam NAME
This function does the same thing as getpwnam (3): it translates a username to the corresponding passwd file entry. The return value in list context is:
($name,$passwd,$uid,$gid,$quota,$comment,$gcos,$dir,$shell)
If you want to do this repeatedly, consider caching the data in a hash (associative array) using getpwent.
In scalar context, getpwnam returns only the numeric user ID.
getpwuid
getpwuid UID
This function does the same thing as getpwuid (3): it translates a numeric user id to the corresponding passwd file entry. The return value in list context is:
($name,$passwd,$uid,$gid,$quota,$comment,$gcos,$dir,$shell)
If you want to do this repeatedly, consider slurping the data into a hash using getpwent.
In scalar context, getpwuid returns the username.
getservbyname
getservbyname NAME, PROTO
This function does the same thing as getservbyname (3): it translates a service (port) name to its corresponding port number. PROTO is a protocol name such as "tcp". The return value in list context is:
($name, $aliases, $port_number, $protocol_name)
In scalar context, getservbyname returns only the service port number.
getservbyport
getservbyport PORT, PROTO
This function does the same thing as getservbyport (3): it translates a service (port) number to its corresponding names. PROTO is a protocol name such as "tcp". The return value in list context is:
($name, $aliases, $port_number, $protocol_name)
In scalar context, getservbyport returns only the service port name.
getservent
getservent setservent STAYOPEN endservent
These functions do the same thing as their like-named system library routines--see getservent (3). They iterate through the /etc/services file or its equivalent. The return value in list context is:
($name, $aliases, $port_number, $protocol_name)
In scalar context, getservent returns only the service port name.
getsockname
getsockname SOCKET
This function returns the packed sockaddr address of this end of the SOCKET connection. (And why wouldn't you know your own address already? Because you might have bound an address containing wildcards to the generic socket before doing an accept. Or because you might have been passed a socket by your parent process--for example, inetd.)
use Socket; $mysockaddr = getsockname(SOCK); ($port, $myaddr) = unpack_sockaddr_in($mysockaddr);
getsockopt
getsockopt SOCKET, LEVEL, OPTNAME
This function returns the socket option requested, or the undefined value if there is an error. See setsockopt for more.
glob
glob EXPR
This function returns the value of EXPR with filename expansions such as a shell would do. (If EXPR is omitted, $_ is globbed instead.) This is the internal function implementing the <*> operator, except that it may be easier to type this way. For example, compare these two:
@result = map { glob($_) } "*.c", "*.c,v";
@result = map <${_}>, "*.c", "*.c,v";
The glob function is not related to the Perl notion of typeglobs, other than that they both use a * to represent multiple items.
gmtime
gmtime EXPR
This function converts a time as returned by the time function to a 9-element list with the time correct for the Greenwich time zone (aka GMT, or UTC, or even Zulu in certain cultures, not including the Zulu culture, oddly enough). Typically used as follows:
($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
gmtime(time);
All list elements are numeric, and come straight out of a struct tm (that's a C programming structure--don't sweat it). In particular this means that $mon has the range 0..11, $wday has the range 0..6, and the year has had 1,900 subtracted from it. (You can remember which ones are 0-based because those are the ones you're always using as subscripts into 0-based arrays containing month and day names.) If EXPR is omitted, it does gmtime(time). For example, to print the current month in London:
$london_month = (qw(Jan Feb Mar Apr May Jun
Jul Aug Sep Oct Nov Dec))[(gmtime)[4]];
The Perl library module Time::Local contains a subroutine, timegm( ), that can convert in the opposite direction.
In scalar context, gmtime returns a ctime (3)-like string based on the GMT time value.
goto
goto LABEL goto EXPR goto &NAME
goto LABEL 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,[4] including out of subroutines, but for that purpose 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).
[4] This means that if it doesn't find the label in the current routine, it looks back through the routines that called the current routine for the label, thus making it nearly impossible to maintain your program.
Going to even greater heights of orthogonality (and depths of idiocy), Perl allows goto EXPR, which expects EXPR to evaluate to a label name, whose scope is guaranteed to be unresolvable until run-time since the label is unknown when the statement is compiled. This allows for computed gotos per FORTRAN, but isn't necessarily recommended[5] if you're optimizing for maintainability:
[5] Understatement is reputed to be funny, so we thought we'd try one here.
goto +("FOO", "BAR", "GLARCH")[$i];
goto &NAME is highly magical, substituting 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 this subroutine--and not the original one--had been called in the first place (except that any modifications to @_ in the original subroutine are propagated to the replacement subroutine). After the goto, not even caller will be able to tell that the original routine was called first.
grep
grep EXPR, LIST grep BLOCK LIST
This function evaluates EXPR or BLOCK in a Boolean context for each element of LIST, temporarily setting $_ to each element in turn. In list context, it returns a list of those elements for which the expression is true. (The operator is named after a beloved UNIX program that extracts lines out of a file that match a particular pattern. In Perl the expression is often a pattern, but doesn't have to be.) In scalar context, grep returns the number of times the expression was true.
Presuming @all_lines contains lines of code, this example weeds out comment lines:
@code_lines = grep !/^#/, @all_lines;
Since $_ is a reference into the list value, altering $_ will modify the elements of the original list. While this is useful and supported, it can occasionally cause bizarre results if you aren't expecting it. For example:
@list = qw(barney fred dino wilma);
@greplist = grep { s/^[bfd]// } @list;
@greplist is now "arney", "red", "ino", but @list is now "arney", "red", "ino", "wilma"! Caveat Programmor.
See also map. The following two statements are functionally equivalent:
@out = grep { EXPR } @in;
@out = map { EXPR ? $_ : () } @in
hex
hex EXPR
This function interprets EXPR as a hexadecimal string and returns the equivalent decimal value. (To interpret strings that might start with 0 or 0x see oct.) If EXPR is omitted, it interprets $_. The following code sets $number to 4,294,906,560:
$number = hex("ffff12c0");
To do the inverse function, use:
sprintf "%lx", $number; # (That's an ell, not a one.)
import
import CLASSNAME LIST import CLASSNAME
There is no built-in import function. It is merely an ordinary class method defined (or inherited) by modules that wish to export names to another module through the use operator. See use for details.
index
index STR, SUBSTR, POSITION index STR, SUBSTR
This function returns the position of the first occurrence of SUBSTR in STR. The POSITION, if specified, says where to start looking. Positions are based at 0 (or whatever you've set the $[ variable to--but don't do that). If the substring is not found, the function returns one less than the base, ordinarily -1. To work your way through a string, you might say:
$pos = -1;
while (($pos = index($string, $lookfor, $pos)) > -1) {
print "Found at $pos\n";
$pos++;
}
int
int EXPR
This function returns the integer portion of EXPR. If EXPR is omitted, it uses $_. If you're a C programmer, you'll often forget to use int in conjunction with division, which is a floating-point operation in Perl:
$average_age = 939/16; # yields 58.6875 (58 in C) $average_age = int 939/16; # yields 58
ioctl
ioctl FILEHANDLE, FUNCTION, SCALAR
This function implements the ioctl (2) system call. 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>. (The Perl distribution includes a script called h2ph to help you do this, but it's non-trivial.) 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 (2) call. (If SCALAR has no string value but does have a numeric value, that value will be passed directly rather than a pointer to the string value.) 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 on many UNIX systems (see the POSIX module in Chapter 7, The Standard Perl Library for a slightly more portable interface):
require 'ioctl.ph';
$getp = &TIOCGETP or die "NO TIOCGETP";
$sgttyb_t = "ccccs"; # 4 chars and a short
if (ioctl STDIN, $getp, $sgttyb) {
@ary = unpack $sgttyb_t, $sgttyb;
$ary[2] = 127;
$sgttyb = pack $sgttyb_t, @ary;
ioctl STDIN, &TIOCSETP, $sgttyb
or die "Can't ioctl TIOCSETP: $!";
}
The return value of ioctl (and fcntl) is as follows:
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(...) or $retval = -1; printf "System returned %d\n", $retval;
Calls to ioctl should not be considered portable. If, say, you're merely turning off echo once for the whole script, it's much more portable (and not much slower) to say:
system "stty -echo"; # Works on most UNIX boxen.
Just because you can do something in Perl doesn't mean you ought to. To quote the Apostle Paul, "Everything is permissible--but not everything is beneficial."
join
join EXPR, LIST
This function joins the separate strings of LIST into a single string with fields separated by the value of EXPR, and returns the string. For example:
$_ = join ':', $login,$passwd,$uid,$gid,$gcos,$home,$shell;
To do the opposite, see split. To join things together into fixed-position fields, see pack.
The most efficient way to concatenate many strings together is to join them with a null string.
keys
keys HASH
This function returns a list consisting of all the keys of the named hash. The keys are returned in an apparently random order, but it is the same order as either the values or each function produces (assuming that the hash has not been modified between calls). Here is yet another way to print your environment:
@keys = keys %ENV;
@values = values %ENV;
while (@keys) {
print pop(@keys), '=', pop(@values), "\n";
}
or how about sorted by key:
foreach $key (sort keys %ENV) {
print $key, '=', $ENV{$key}, "\n";
}
To sort an array by value, you'll need to provide a comparison function. Here's a descending numeric sort of a hash by its values:
foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash)) {
printf "%4d %s\n", $hash{$key}, $key;
}
Note that using keys on a hash bound to a largish DBM file will produce a largish list, causing you to have a largish process. You might prefer to use the each function in this case, which will iterate over the hash entries one-by-one without slurping them all into a single gargantuan list.
In scalar context, keys returns the number of elements of the hash (and resets the each iterator). However, to get this information for tied hashes, including DBM files, Perl must still walk the entire hash, so it's not very efficient in that case.
kill
kill LIST
This function sends a signal to a list of processes. The first element of the list must be the signal to send. You may use a signal name in quotes (without a SIG on the front). The function returns the number of processes successfully signaled. If the signal is negative, the function kills process groups instead of processes. (On System V, a negative process number will also kill process groups, but that's not portable.) Examples:
$cnt = kill 1, $child1, $child2; kill 9, @goners; kill 'STOP', getppid; # Can *so* suspend my login shell...
last
last LABEL last
The last command is like the 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 continue block, if any, is not executed.
LINE: while (<STDIN>) {
last LINE if /^$/; # exit when done with header
# rest of loop here
}
lc
lc EXPR
This function returns a lowercased version of EXPR (or $_ if omitted). This is the internal function implementing the \L escape in double-quoted strings. POSIX setlocale (3) settings are respected.
lcfirst
lcfirst EXPR
This function returns a version of EXPR (or $_ if omitted) with the first character lowercased. This is the internal function implementing the \l escape in double-quoted strings. POSIX setlocale (3) settings are respected.
length
length EXPR
This function returns the length in bytes of the scalar value EXPR. If EXPR is omitted, the function returns the length of $_, but be careful that the next thing doesn't look like the start of an EXPR, or the tokener will get confused. When in doubt, always put in parentheses.
Do not try to use length to find the size of an array or hash. Use scalar @array for the size of an array, and scalar keys %hash for the size of a hash. (The scalar is typically dropped when redundant, which is typical.)
link
link OLDFILE, NEWFILE
This function creates a new filename linked to the old filename. The function returns 1 for success, 0 otherwise (and puts the error code into $!). See also symlink later in this chapter. This function is unlikely to be implemented on non-UNIX systems.
listen
listen SOCKET, QUEUESIZE
This function does the same thing as the listen (2) system call. It tells the system that you're going to be accepting connections on this socket and that the system can queue the number of waiting connections specified by QUEUESIZE. Imagine having call-waiting on your phone, with up to five callers queued. (Gives me the willies!) The function returns true if it succeeded, false otherwise (and puts the error code into $!). See the section "Sockets" in Chapter 6, Social Engineering.
local
local EXPR
This operator declares one or more global variables to have locally scoped values within the innermost enclosing block, subroutine, eval, or file. If more than one variable is listed, the list must be placed in parentheses, because the operator binds more tightly than comma. All the listed variables must be legal lvalues, that is, something you could assign to. This operator works by saving the current values of those variables on a hidden stack and restoring them upon exiting the block, subroutine, or eval, or file. After the local is executed, but before the scope is exited, any called subroutines will see the local, inner value, not the previous, outer value, because the variable is still a global variable, despite having a localized value. The technical term for this is "dynamic scoping".
The EXPR may be assigned to if desired, which allows you to initialize your local variables. (If no initializer is given, all scalars are initialized to the undefined value and all arrays and hashes to empty.) Commonly, this is used to name the formal arguments to a subroutine. As with ordinary assignment, if you use parentheses around the variables on the left (or if the variable is an array or hash), the expression on the right is evaluated in list context. Otherwise the expression on the right is evaluated in scalar context.
Here is a routine that executes some random piece of code that depends on $i running through a range of numbers. Note that the scope of $i propagates into the eval code.
&RANGEVAL(20, 30, '$foo[$i] = $i');
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;
}
This code demonstrates how to make a temporary modification to a global array:
if ($sw eq '-v') {
# init local array with global array
local @ARGV = @ARGV;
unshift @ARGV, 'echo';
system @ARGV;
}
# @ARGV restored
You can also temporarily modify hashes:
# temporarily add a couple of entries to the %digits hash
if ($base12) {
# (NOTE: not claiming this is efficient!)
local(%digits) = (%digits, T => 10, E => 11);
parse_num();
}
But you probably want to be using my instead, because local isn't really what most people think of as local. See the section on my later.
localtime
localtime EXPR
This function converts the value returned by time to a nine-element list with the time corrected for the local time zone. It's typically used as follows:
($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
localtime(time);
All list elements are numeric, and come straight out of a struct tm. (That's a bit of C programming lingo--don't worry about it.) In particular this means that $mon has the range 0..11, $wday has the range 0..6, and the year has had 1,900 subtracted from it. (You can remember which ones are 0-based because those are the ones you're always using as subscripts into 0-based arrays containing month and day names.) If EXPR is omitted, it does localtime(time). For example, to get the name of the current day of the week:
$thisday = (Sun,Mon,Tue,Wed,Thu,Fri,Sat)[(localtime)[6]];
The Perl library module Time::Local contains a subroutine, timelocal(), that can convert in the opposite direction.
In scalar context, localtime returns a ctime (3)-like string based on the localtime value. For example, the date command can be emulated with:
perl -e 'print scalar localtime'
See also POSIX::strftime() in Chapter 7, The Standard Perl Library for a more fine-grained approach to formatting times.
log
log EXPR
This function returns logarithm (base e) of EXPR. If EXPR is omitted, the function returns the logarithm of $_.
lstat
lstat EXPR
This function does the same thing as the stat function, but if the last component of the filename is a symbolic link, 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 instead.)
map
map BLOCK LIST map EXPR, LIST
This function 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. It evaluates BLOCK or EXPR in a list context, so each element of LIST may produce zero, one, or more elements in the returned value. These are all flattened into one list. For instance:
@words = map { split ' ' } @lines;
splits a list of lines into a list of words. Often, though, there is a one-to-one mapping between input values and output values:
@chars = map chr, @nums;
translates a list of numbers to the corresponding characters. And here's an example of a one-to-two mapping:
%hash = map { genkey($_), $_ } @array;
which is just a funny functional way to write this:
%hash = ();
foreach $_ (@array) {
$hash{genkey($_)} = $_;
}
See also grep. map differs from grep in that map returns a list consisting of the results of each successive evaluation of EXPR, whereas grep returns a list consisting of each value of LIST for which EXPR evaluates to true.
mkdir
mkdir FILENAME, MODE
This function creates the directory specified by FILENAME, with permissions specified by the numeric MODE (as modified by the current umask). If it succeeds it returns 1, otherwise it returns 0 and sets $! (from the value of errno).
If mkdir (2) is not built in to your C library, Perl emulates it by calling the mkdir (1) program. If you are creating a long list of directories on such a system it will be more efficient to call the mkdir program yourself with the list of directories to avoid starting zillions of subprocesses.
msgctl
msgctl ID, CMD, ARG
This function calls the msgctl (2) system call. See msgctl (2) for details. If CMD is &IPC_STAT, then ARG must be a variable that will hold the returned msqid_ds structure. The return value works like ioctl's: the undefined value for error, "0 but true" for zero, or the actual return value otherwise. On error, it puts the error code into $!. Before calling, you should say:
require "ipc.ph"; require "msg.ph";
This function is available only on machines supporting System V IPC, which turns out to be far fewer than those supporting sockets.
msgget
msgget KEY, FLAGS
This function calls the System V IPC msgget (2) system call. See msgget (2) for details. The function returns the message queue ID, or the undefined value if there is an error. On error, it puts the error code into $!. Before calling, you should say:
require "ipc.ph"; require "msg.ph";
This function is available only on machines supporting System V IPC.
msgrcv
msgrcv ID, VAR, SIZE, TYPE, FLAGS
This function calls the msgrcv (2) system call to receive a message from message queue ID into variable VAR with a maximum message size of SIZE. See msgrcv (2) for details. When 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. The function returns true if successful, or false if there is an error. On error, it puts the error code into $!. Before calling, you should say:
require "ipc.ph"; require "msg.ph";
This function is available only on machines supporting System V IPC.
msgsnd
msgsnd ID, MSG, FLAGS
This function calls the msgsnd (2) system call to send the message MSG to the message queue ID. See msgsnd (2) for details. MSG must begin with the long integer message type. You can create a message like this:
$msg = pack "L a*", $type, $text_of_message;
The function returns true if successful, or false if there is an error. On error, it puts the error code into $!. Before calling, you should say:
require "ipc.ph"; require "msg.ph";
This function is available only on machines supporting System V IPC.
my
my EXPR
This operator declares one or more private variables to exist only within the innermost enclosing block, subroutine, eval, or file. If more than one variable is listed, the list must be placed in parentheses, because the operator binds more tightly than comma. Only simple scalars or complete arrays and hashes may be declared this way. The variable name may not be package qualified, because package variables are all global, and private variables are not related to any package. Unlike local, this operator has nothing to do with global variables, other than hiding any other variable of the same name from view within its scope. (A global variable can always be accessed through its package-qualified form, however.) A private variable is not visible until the statement after its declaration. Subroutines called from within the scope of such a private variable cannot see the private variable unless the subroutine is also textually declared within the scope of the variable. The technical term for this is "lexical scoping", so we often call these "lexical variables". In C culture they're called "auto" variables, since they're automatically allocated and deallocated at scope entry and exit.
The EXPR may be assigned to if desired, which allows you to initialize your lexical variables. (If no initializer is given, all scalars are initialized to the undefined value and all arrays and hashes to empty arrays.) As with ordinary assignment, if you use parentheses around the variables on the left (or if the variable is an array or hash), the expression on the right is evaluated in list context. Otherwise the expression on the right is evaluated in scalar context. You can name your formal subroutine parameters with a list assignment, like this:
my ($friends, $romans, $countrymen) = @_;
Be careful not to omit the parentheses indicating list assignment, like this:
my $country = @_; # right or wrong?
This assigns the length of the array (that is, the number of the subroutine's arguments) to the variable, since the array is being evaluated in scalar context. You can profitably use scalar assignment for a formal parameter though, as long as you use the shift operator. In fact, since object methods are passed the object as the first argument, many such method subroutines start off like this:
sub simple_as {
my $self = shift; # scalar assignment
my ($a,$b,$c) = @_; # list assignment
...
}
new
new CLASSNAME LIST new CLASSNAME
There is no built-in new function. It is merely an ordinary constructor method (subroutine) defined (or inherited) by the CLASSNAME module to let you construct objects of type CLASSNAME. Most constructors are named "new", but only by convention, just to delude C++ programmers into thinking they know what's going on.
next
next LABEL next
The next command is like the continue statement in C: it starts the next iteration of the loop designated by LABEL:
LINE: while (<STDIN>) {
next LINE if /^#/; # discard comments
...
}
Note that if there were a continue block in this example, it would execute immediately following the invocation of next. When LABEL is omitted, the command refers to the innermost enclosing loop.
oct
oct EXPR
This function interprets EXPR as an octal string and returns the equivalent decimal value. (If EXPR happens to start off with 0x, it is interpreted as a hex string instead.) The following will handle decimal, octal, and hex in the standard notation:
$val = oct $val if $val =~ /^0/;
If EXPR is omitted, the function interprets $_. To perform the inverse function on octal numbers, use:
$oct_string = sprintf "%lo", $number;
open
open FILEHANDLE, EXPR open FILEHANDLE
This function opens the file whose filename is given by EXPR, and associates it with FILEHANDLE. If EXPR is omitted, the scalar variable of the same name as the FILEHANDLE must contain the filename. (And you must also be careful to use "or die" after the statement rather than "|| die", because the precedence of || is higher than list operators like open.) FILEHANDLE may be a directly specified filehandle name, or an expression whose value will be used for the filehandle. The latter is called an indirect filehandle. If you supply an undefined variable for the indirect filehandle, Perl will not automatically fill it in for you--you have to make sure the expression returns something unique, either a string specifying the actual filehandle name, or a filehandle object from one of the object-oriented I/O packages. (A filehandle object is unique because you call a constructor to generate the object. See the example later in this section.)
After the filehandle is determined, the filename string is processed. First, any leading and trailing whitespace is removed from the string. Then the string is examined on both ends for characters specifying how the file is to be opened. (By an amazing coincidence, these characters look just like the characters you'd use to indicate I/O redirection to the Bourne shell.) If the filename begins with < or nothing, the file is opened for input. If the filename begins with >, the file is truncated and opened for output. If the filename begins with >>, the file is opened for appending. (You can also 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 an open command that pipes both in and out, although the IPC::Open2 and IPC::Open3 library routines give you a close equivalent. See the section "Bidirectional Communication" in Chapter 6, Social Engineering.
Any pipe command containing shell metacharacters is passed to /bin/sh for execution; otherwise it is executed directly by Perl. The filename "-" refers to STDIN, and ">-" refers to STDOUT. open returns non-zero upon success, the undefined value otherwise. If the open involved a pipe, the return value happens to be the process ID of the subprocess.
If you're unfortunate enough to be running Perl on a system that distinguishes between text files and binary files (modern operating systems don't care), then you should check out binmode for tips for dealing with this. The key distinction between systems that need binmode and those that don't is their text file formats. Systems like UNIX and Plan9 that delimit lines with a single character, and that encode that character in C as '\n', do not need binmode. The rest need it.
Here is some code that shows the relatedness of a filehandle and a variable of the same name:
$ARTICLE = "/usr/spool/news/comp/lang/perl/misc/38245";
open ARTICLE or die "Can't find article $ARTICLE: $!\n";
while (<ARTICLE>) {...
Append to a file like this:
open LOG, '>>/usr/spool/news/twitlog'; # (`log' is reserved)
Pipe your data from a process:
open ARTICLE, "caesar <$article |"; # decrypt article with rot13
Here < does not indicate that Perl should open the file for input, because < is not the first character of EXPR. Rather, the concluding | indicates that input is to be piped from caesar <$article (from the program caesar, which takes $article as its standard input). The < is interpreted by the subshell that Perl uses to start the pipe, because < is a shell metacharacter.
Or pipe your data to a process:
open EXTRACT, "|sort >/tmp/Tmp$$"; # $$ is our process number
In this next example we show one way to do recursive opens, via indirect filehandles. The files will be opened on filehandles fh01, fh02, fh03, and so on. Because $input is a local variable, it is preserved through recursion, allowing us to close the correct file before we return.
# 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 the use of indirection
if (/^#include "(.*)"/) {
process($1, $input);
next;
}
... # whatever
}
close $input;
}
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.[6] 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:
[6] The word "dup" is UNIX-speak for "duplicate". We're not really trying to dupe you. Trust us.
#!/usr/bin/perl open SAVEOUT, ">&STDOUT"; open SAVEERR, ">&STDERR"; open STDOUT, ">foo.out" or die "Can't redirect stdout"; open STDERR, ">&STDOUT" or die "Can't dup stdout"; select STDERR; $| = 1; # make unbuffered select STDOUT; $| = 1; # make unbuffered print STDOUT "stdout 1\n"; # this propagates to 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 (3) of that file descriptor; this is more parsimonious with file descriptors than the dup form described earlier. (On the other hand, it's more dangerous, since two filehandles may now be sharing the same file descriptor, and a close on one filehandle may prematurely close the other.) For example:
open FILEHANDLE, "<&=$fd";
If you open a pipe to or from the command "-" (that is, either |- or -|), then an implicit fork is 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) in either the parent or child to determine whether the open was successful.) The filehandle behaves normally for the parent, but input and output to that filehandle is piped from or to the STDOUT or STDIN of the child process. In the child process the filehandle isn't opened--I/O happens from or to the new STDIN or STDOUT. Typically this is used like the normal piped open when you want to exercise more control over just how the pipe command gets executed, such as when you are running setuid, and don't want to have to scan shell commands for metacharacters. The following pairs are equivalent:
open FOO, "|tr '[a-z]' '[A-Z]'"; open FOO, "|-" or exec 'tr', '[a-z]', '[A-Z]'; open FOO, "cat -n file|"; open FOO, "-|" or 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 $?. On any operation which may do a fork, unflushed buffers remain unflushed in both processes, which means you may need to set $| on one or more filehandles to avoid duplicate output (and then do output to flush them).
Filehandles STDIN, STDOUT, and STDERR remain open following an exec. Other filehandles do not. (However, on systems supporting the fcntl function, you may modify the close-on-exec flag for a filehandle. See fcntl earlier in this chapter. See also the special $^F variable.)
Using the constructor from the FileHandle module, described in Chapter 7, The Standard Perl Library, you can generate anonymous filehandles which have the scope of whatever variables hold references to them, and automatically close whenever and however you leave that scope:
use FileHandle;
...
sub read_myfile_munged {
my $ALL = shift;
my $handle = new FileHandle;
open $handle, "myfile" or die "myfile: $!";
$first = <$handle> or return (); # Automatically closed here.
mung $first or die "mung failed"; # Or here.
return $first, <$handle> if $ALL; # Or here.
$first; # Or here.
}
In order to open a file with arbitrary weird characters in it, it's necessary to protect any leading and trailing whitespace, like this:
$file =~ s#^\s#./$&#; open FOO, "< $file\0";
But we've never actually seen anyone use that in a script . . .
If you want a real C open (2), then you should use the sysopen function. This is another way to protect your filenames from interpretation. For example:
use FileHandle;
sysopen HANDLE, $path, O_RDWR|O_CREAT|O_EXCL, 0700
or die "sysopen $path: $!";
HANDLE->autoflush(1);
HANDLE->print("stuff $$\n");
seek HANDLE, 0, 0;
print "File contains: ", <HANDLE>;
See seek for some details about mixing reading and writing.
opendir
opendir DIRHANDLE, EXPR
This function opens a directory named EXPR for processing by readdir, telldir, seekdir, rewinddir, and closedir. The function returns true if successful. Directory handles have their own namespace separate from filehandles.
ord
ord EXPR
This function returns the numeric ASCII value of the first character of EXPR. If EXPR is omitted, it uses $_. The return value is always unsigned. If you want a signed value, use unpack('c', EXPR). If you want all the characters of the string converted to a list of numbers, use unpack('C*', EXPR) instead.
pack
pack TEMPLATE, LIST
This function takes a 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:
| Character | Meaning |
|---|---|
| a | An ASCII string, will be null padded |
| A | An ASCII string, will be space padded |
| b | A bit string, low-to-high order (like vec( )) |
| B | A bit string, high-to-low order |
| c | A signed char value |
| C | An unsigned char value |
| d | A double-precision float in the native format |
| f | A single-precision float in the native format |
| h | A hexadecimal string, low nybble first |
| H | A hexadecimal string, high nybble first |
| i | A signed integer value |
| I | An unsigned integer value |
| l | A signed long value |
| L | An unsigned long value (continued) |
| n | A short in "network" (big-endian) order |
| N | A long in "network" (big-endian) order |
| p | A pointer to a string |
| P | A pointer to a structure (fixed-length string) |
| s | A signed short value |
| S | An unsigned short value |
| v | A short in "VAX" (little-endian) order |
| V | A long in "VAX" (little-endian) order |
| u | A uuencoded string |
| x | A null byte |
| X | Back up a byte |
| @ | Null-fill to absolute position |
Each character may optionally be followed by a number which gives a repeat count. Together the character and the repeat count make a field specifier. Field specifiers may be separated by whitespace, which will be ignored. With all types except "a" and "A", the pack function will gobble up that many values from the LIST. Saying "*" 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.) 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). Also, Perl uses doubles internally for all numeric calculation, and converting from double to float to double will lose precision; that is, unpack(`f`, pack(`f`,$num)) will not in general equal $num.
This first pair of examples packs numeric values into bytes:
$out = pack "cccc", 65, 66, 67, 68; # $out eq "ABCD" $out = pack "c4", 65, 66, 67, 68; # same thing
This does a similar thing, with a couple of nulls thrown in:
$out = pack "ccxxcc", 65, 66, 67, 68; # $out eq "AB\0\0CD"
Packing your shorts doesn't imply that you're portable:
$out = pack "s2", 1, 2; # "\1\0\2\0" on little-endian
# "\0\1\0\2" on big-endian
On binary and hex packs, the count refers to the number of bits or nybbles, not the number of bytes produced:
$out = pack "B32", "01010000011001010111001001101100"; $out = pack "H8", "5065726c"; # both produce "Perl"
The length on an "a" field applies only to one string:
$out = pack "a4", "abcd", "x", "y", "z"; # "abcd"
To get around that limitation, use multiple specifiers:
$out = pack "aaaa", "abcd", "x", "y", "z"; # "axyz" $out = pack "a" x 4, "abcd", "x", "y", "z"; # "axyz"
The "a" format does null filling:
$out = pack "a14", "abcdefg"; # "abcdefg\0\0\0\0\0\0\0"
This template packs a C struct tm record (at least on some systems):
$out = pack "i9pl", gmtime, $tz, $toff;
The same template may generally also be used in the unpack function. If you want to join variable length fields with a delimiter, use the join function.
Note that, although all of our examples use literal strings as templates, there is no reason you couldn't pull in your templates from a disk file. You could, in fact, build an entire relational database system around this function.
package
package NAMESPACE
This is not really a function, but a declaration that says that the rest of the innermost enclosing block, subroutine, eval or file belongs to the indicated namespace. (The scope of a package declaration is thus the same as the scope of a local or my declaration.) All subsequent references to unqualified global identifiers will be resolved by looking them up in the declared package's symbol table. A package declaration affects only global variables--including those you've used local on--but not lexical variables created with my.
Typically you would put a package declaration as the first thing in a file that is to be included by the require or use operator, but you can put one anywhere that a statement would be legal. When defining a class or a module file, it is customary to name the package the same name as the file, to avoid confusion. (It's also customary to name such packages beginning with a capital letter, because lowercase modules are by convention interpreted as pragmas.)
You can switch into a given package in more than one place; it merely influences which symbol table is used by the compiler for the rest of that block. (If it sees another package declaration at the same level, the new one overrides the previous one.) Your main program is assumed to start with a package main declaration.
You can refer to variables and filehandles in other packages by qualifying the identifier with the package name and a double colon: $Package::Variable. If the package name is null, the main package as assumed. That is, $::sail is equivalent to $main::sail.
The symbol table for a package is stored in a hash with a name ending in a double colon. The main package's symbol table is named %main:: for example. So the package symbol *main::sail can also be accessed as $main::{"sail"}.
See "Packages" in Chapter 5, Packages, Modules, and Object Classes, for more information about packages, modules, and classes. See my in Chapter 3, Functions, for other scoping issues.
pipe
pipe READHANDLE, WRITEHANDLE
Like the corresponding system call, this function opens a pair of connected pipes--see pipe (2). This call is almost always used right before a fork, after which the pipe's reader should close WRITEHANDLE, and the writer close READHANDLE. (Otherwise the pipe won't indicate EOF to the reader when the writer closes it.) 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 standard I/O buffering, so you may need to set $| on your WRITEHANDLE to flush after each output command, depending on the application--see select (output filehandle).
See also the section on "Pipes" in Chapter 6, Social Engineering.
pop
pop ARRAY pop
This function treats an array like a stack--it pops and returns the last value of the array, shortening the array by 1. If ARRAY is omitted, the function pops @ARGV (in the main program), or @_ (in subroutines). It has the same effect as:
$tmp = $ARRAY[$#ARRAY--];
or:
$tmp = splice @ARRAY, -1;
If there are no elements in the array, pop returns the undefined value. See also push and shift. If you want to pop more than one element, use splice.
Note that pop requires its first argument to be an array, not a list. If you just want the last element of a list, use this:
(something_returning_a_list)[-1]
pos
pos SCALAR
Returns the location in SCALAR where the last m//g search over SCALAR left off. It returns the offset of the character after the last one matched. (That is, it's equivalent to length($`) + length($&).) This is the offset where the next m//g search on that string will start. Remember that the offset of the beginning of the string is 0. For example:
$grafitto = "fee fie foe foo";
while ($grafitto =~ m/e/g) {
print pos $grafitto, "\n";
}
prints 2, 3, 7, and 11, the offsets of each of the characters following an "e". The pos function may be assigned a value to tell the next m//g where to start:
$grafitto = "fee fie foe foo";
pos $grafitto = 4; # Skip the fee, start at fie
while ($grafitto =~ m/e/g) {
print pos $grafitto, "\n";
}
This prints only 7 and 11. (Thank heaven.) The regular expression assertion, \G, matches only at the location currently specified by pos for the string being searched.
print FILEHANDLE LIST print LIST print
This function prints a string or a comma-separated list of strings. The function returns 1 if successful, 0 otherwise. FILEHANDLE may be a scalar variable name (unsubscripted), in which case the variable contains either the name of the actual filehandle or a reference to a filehandle object from one of the object-oriented filehandle packages. FILEHANDLE may also be a block that returns either kind of value:
print { $OK ? "STDOUT" : "STDERR" } "stuff\n";
print { $iohandle[$i] } "stuff\n";
Note that 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 parentheses around the arguments. For example:
print $a - 2; # prints $a - 2 to default filehandle (usually STDOUT) print $a (- 2); # prints -2 to filehandle specified in $a print $a -2; # ditto (weird parsing rules :-)
If FILEHANDLE is omitted, the function prints to the currently selected output filehandle, initially STDOUT. To set the default output filehandle to something other than STDOUT use the select(FILEHANDLE) operation.[7] If LIST is also omitted, prints $_. Note that, because print takes a LIST, anything in the LIST is evaluated in list context, and any subroutine that you call will likely have one or more of its own internal expressions evaluated in list context. Thus, when you say:
[7] Thus, STDOUT isn't really the default filehandle for print. It's merely the default default filehandle.
print OUT <STDIN>;
it is not going to print out the next line from standard input, but all the rest of the lines from standard input up to end-of-file, since that's what <STDIN> returns in list context. Also, remembering the if-it-looks-like-a-function-it-is-a-function rule, 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:
print (1+2)*3, "\n"; # WRONG print +(1+2)*3, "\n"; # ok print ((1+2)*3, "\n"); # ok
printf
printf FILEHANDLE LIST printf LIST
This function prints a formatted string to FILEHANDLE or, if omitted, the currently selected output filehandle, initially STDOUT. The first item in the LIST must be a string that says how to format the rest of the items. This is similar to the C library's printf (3) and fprintf (3) function, except that the * field width specifier is not supported. The function is equivalent to:
print FILEHANDLE sprintf LIST
See print and sprintf. The description of sprintf includes the list of acceptable specifications for the format string.
Don't fall into the trap of using a printf when a simple print would do. The print is more efficient, and less error prone.
push
push ARRAY, LIST
This function 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. The function returns this new length. The push function has the same effect as:
foreach $value (LIST) {
$ARRAY[++$#ARRAY] = $value;
}
or:
splice @ARRAY, @ARRAY, 0, LIST;
but is more efficient (for both you and your computer). You can use push in combination with shift to make a fairly time-efficient shift register or queue:
for (;;) {
push @ARRAY, shift @ARRAY;
...
}
q/STRING/
q/STRING/ qq/STRING/ qx/STRING/ qw/STRING/
Generalized quotes. See Chapter 2, The Gory Details.
quotemeta
quotemeta EXPR
This function returns the value of EXPR (or $_ if not specified) with all non-alphanumeric characters backslashed. This is the internal function implementing the \Q escape in interpolative contexts (including double-quoted strings, backticks, and patterns).
rand
rand EXPR rand
This function returns a random fractional number between 0 and the value of EXPR. (EXPR should be positive.) If EXPR is omitted, the function returns a value between 0 and 1 (including 0, but excluding 1). See also srand.
To get an integral value, combine this with int, as in:
$roll = int(rand 6) + 1; # $roll is now an integer between 1 and 6
read
read FILEHANDLE, SCALAR, LENGTH, OFFSET read FILEHANDLE, SCALAR, LENGTH
This function attempts to read LENGTH bytes of data into variable SCALAR from the specified FILEHANDLE. The function returns the number of bytes actually read, 0 at end-of-file. It returns the undefined value on error. SCALAR will be grown or shrunk to the length actually read. The OFFSET, if specified, says where in the variable to start putting bytes, so that you can do a read into the middle of a string.
To copy data from filehandle FROM into filehandle TO, you could say:
while (read FROM, $buf, 16384) {
print TO $buf;
}
Note that the opposite of read is simply a print, which already knows the length of the string you want to write, and can write a string of any length.
Perl's read function is actually implemented in terms of standard I/O's fread (3) function, so the actual read (2) system call may read more than LENGTH bytes to fill the input buffer, and fread (3) may do more than one system read (2) in order to fill the buffer. To gain greater control, specify the real system call using sysread. Calls to read and sysread should not be intermixed unless you are into heavy wizardry (or pain).
readdir
readdir DIRHANDLE
This function reads directory entries from a directory handle opened by opendir. In scalar context, this function returns the next directory entry, if any, otherwise an undefined value. In list context, it returns all the rest of the entries in the directory, which will of course be a null list if there are none. For example:
opendir THISDIR, "." or die "serious dainbramage: $!"; @allfiles = readdir THISDIR; closedir THISDIR; print "@allfiles\n";
prints all the files in the current directory on one line. If you want to avoid the "." and ".." entries, use this instead:
@allfiles = grep !/^\.\.?$/, readdir THISDIR;
And to avoid all .* files (like the ls program):
@allfiles = grep !/^\./, readdir THISDIR;
To get just text files, say this:
@textfiles = grep -T, readdir THISDIR;
But watch out on that last one, because the result of readdir needs to have the directory part glued back on if it's not the current directory--like this:
opendir THATDIR, $thatdir; @text_of_thatdir = grep -T, map "$thatdir/$_", readdir THATDIR; closedir THATDIR;
readlink
readlink EXPR
This function returns the name of a file pointed to by a symbolic link. EXPR should evaluate to a filename, the last component of which is a symbolic link. If it is not a symbolic link, or if symbolic links are not implemented, or if some system error occurs, the undefined value is returned, and you should check the error code in $!. If EXPR is omitted, the function uses $_.
Be aware that the returned symlink may be relative to the location you specified. For instance, you may say:
readlink "/usr/local/src/express/yourself.h"
and readlink might return:
../express.1.23/includes/yourself.h
which is not directly usable as a filename unless your current directory happens to be /usr/local/src/express.
recv
recv SOCKET, SCALAR, LEN, FLAGS
This function receives a message on a socket. It attempts to receive LENGTH bytes of data into variable SCALAR from the specified SOCKET filehandle. The function returns the address of the sender, or the undefined value if there's an error. SCALAR will be grown or shrunk to the length actually read. The function takes the same flags as recv (2). See the section "Sockets" in Chapter 6, Social Engineering.
redo
redo LABEL redo
The redo command restarts a loop block without evaluating the conditional again. The 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 wish to deceive themselves about what was just input:
# A loop that joins lines continued with a backslash.
LINE: while (<STDIN>) {
if (s/\\\n$// and $nextline = <STDIN>) {
$_ .= $nextline;
redo LINE;
}
print; # or whatever...
}
ref
ref EXPR
The ref operator returns a true value if EXPR is a reference, the null string otherwise. The value returned depends on the type of thing the reference is a reference to. Built-in 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 a hash.\n";
}
elsif (ref($r) eq "Hump") {
print "r is a reference to a Hump object.\n";
}
elsif (not ref $r) {
print "r is not a reference at all.\n";
}
See Chapter 4, References and Nested Data Structures for more details.
rename
rename OLDNAME, NEWNAME
This function changes the name of a file. It returns 1 for success, 0 otherwise (and puts the error code into $!). It will not work across filesystem boundaries. If there is already a file named NEWNAME, it will be destroyed.
require
require EXPR require
This function asserts a dependency of some kind on its argument. (If EXPR is not supplied, $_ is used as the argument.)
If the argument is a string, this function includes and executes the Perl code found in the separate file whose name is given by the string. This is similar to performing an eval on the contents of the file, except that require checks to see that the library file has not been included already. (It can thus be used to express file dependencies without worrying about duplicate compilation.) The function also knows how to search the include path stored in the @INC array (see the section "Special Variables" in Chapter 2, The Gory Details).
This form of the require function behaves much like this subroutine:
sub require {
my($filename) = @_;
return 1 if $INC{$filename};
my($realfilename, $result);
ITER: {
foreach $prefix (@INC) {
$realfilename = "$prefix/$filename";
if (-f $realfilename) {
$result = eval `cat $realfilename`;
last ITER;
}
}
die "Can't find $filename in \@INC";
}
die $@ if $@;
die "$filename did not return true value" unless $result;
$INC{$filename} = $realfilename;
return $result;
}
Note that the file must return true as the last value 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.
This operator differs from the now somewhat obsolete do EXPR operator in that the file will not be included again if it was included previously with either a require or do EXPR command, and any difficulties will be detected and reported as fatal errors (which may be trapped by use of eval). The do command does know how to do the @INC path search, however.
If require's argument is a number, the version number of the currently executing Perl binary (as known by $]) is compared to EXPR, and if smaller, execution is immediately aborted. Thus, a script that requires Perl version 5.003 can have as its first line:
require 5.003;
and earlier versions of Perl will abort.
If require's argument is a package name (see package), require assumes an automatic .pm suffix, making it easy to load standard modules. This is like use, except that it happens at run-time, not compile time, and the import routine is not called. For example, to pull in Socket.pm without introducing any symbols into the current package, say this:
require Socket; # instead of "use Socket;"
However, one can get the same effect with the following, which has the advantage of giving a compile-time warning if Socket.pm can't be located:
use Socket ();
reset
reset EXPR reset
This function is generally used at the top of a loop or in a continue block at the end of a loop, to clear global variables or reset ?? searches so that they work again. The expression is interpreted as a list of single characters (hyphens are allowed for ranges). All scalar variables, arrays, and hashes 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. The function resets variables or searches for the current package only. It always returns 1.
To reset all "X" variables, say this:
reset 'X';
To reset all lowercase variables, say this:
reset 'a-z';
Lastly, to just reset ?? searches, say:
reset;
Note that resetting "A-Z" is not recommended since you'll wipe out your ARGV, INC, ENV, and SIG arrays.
Lexical variables (created by my) are not affected. Use of reset is vaguely deprecated.
return
return EXPR
This function returns from a subroutine (or eval) with the value specified. (In the absence of an explicit return, the value of the last expression evaluated is returned.) Use of return outside of a subroutine or eval is verboten, and results in a fatal error. Note also that an eval cannot do a return on behalf of the subroutine that called the eval.
The supplied expression will be evaluated in the context of the subroutine invocation. That is, if the subroutine was called in a scalar context, EXPR is also evaluated in scalar context. If the subroutine was invoked in a list context, then EXPR is also evaluated in list context, and can return a list value. A return with no argument returns the undefined value in scalar context, and a null list in list context. The context of the subroutine call can be determined from within the subroutine by using the (misnamed) wantarray function.
reverse
reverse LIST
In list context, this function returns a list value consisting of the elements of LIST in the opposite order. This is fairly efficient because it just swaps the pointers around. The function can be used to create descending sequences:
for (reverse 1 .. 10) { ... }
Because of the way hashes flatten into lists when passed to (non-hash-aware) functions, reverse can also be used to invert a hash, presuming the values are unique:
%barfoo = reverse %foobar;
In scalar context, the function concatenates all the elements of LIST together and then returns the reverse of that, character by character.
A small hint: reversing a list sorted earlier by a user-defined function can sometimes be achieved more easily by simply sorting in the opposite direction in the first place.
rewinddir
rewinddir DIRHANDLE
This function sets the current position to the beginning of the directory for the readdir routine on DIRHANDLE. The function may not be available on all machines that support readdir.
rindex
rindex STR, SUBSTR, POSITION rindex STR, SUBSTR
This function works just like index except that it returns the position of the last occurrence of SUBSTR in STR (a reverse index). The function returns $[-1 if not found. Since $[ is almost always 0 nowadays, the function almost always returns -1. POSITION, if specified, is the rightmost position that may be returned. To work your way through a string backward, say:
$pos = length $string;
while (($pos = rindex $string, $lookfor, $pos) >= 0) {
print "Found at $pos\n";
$pos--;
}
rmdir
rmdir FILENAME
This function deletes the directory specified by FILENAME if it is empty. If it succeeds, it returns 1, otherwise it returns 0 and puts the error code into $!. If FILENAME is omitted, the function uses $_.
s///
s///
The substitution operator. See "Pattern Matching Operators" in Chapter 2, The Gory Details.
scalar
scalar EXPR
This pseudo-function may be used within a LIST to force EXPR to be evaluated in scalar context when evaluation in list context would produce a different result.
For example:
local($nextvar) = scalar <STDIN>;
prevents <STDIN> from reading all the lines from standard input before doing the assignment, since assignment to a local list provides a list context. (Without the use of scalar in this example, the first line from <STDIN> would still be assigned to $nextvar, but the subsequent lines would be read and thrown away. This is because the assignment is being made to a list--one that happens to be able to receive only a single, scalar value.)
Of course, a simpler way with less typing would be to simply leave the parentheses off, thereby changing the list context to a scalar one:
local $nextvar = <STDIN>;
Since a print function is a LIST operator, you have to say:
print "Length is ", scalar(@ARRAY), "\n";
if you want the length of @ARRAY to be printed out.
One never needs to force evaluation in a list context, because any operation that wants a list already provides a list context to its list arguments for free. So there's no list function corresponding to scalar.
seek
seek FILEHANDLE, OFFSET, WHENCE
This function positions the file pointer for FILEHANDLE, just like the fseek (3) call of standard I/O. The first position in a file is at offset 0, not offset 1, and offsets refer to byte positions, not line numbers. (In general, since line lengths vary, it's not possible to access a particular line number without examining the whole file up to that line number, unless all your lines are known to be of a particular length, or you've built an index that translates line numbers into byte offsets.) FILEHANDLE may be an expression whose value gives the name of the filehandle or a reference to a filehandle object. The function returns 1 upon success, 0 otherwise. For handiness, the function can calculate offsets from various file positions for you. The value of WHENCE specifies which file position your OFFSET is relative to: 0, the beginning of the file; 1, the current position in the file; or 2, the end of the file. OFFSET may be negative for a WHENCE of 1 or 2.
One interesting use for this function is to allow you to follow growing files, like this:
for (;;) {
while (<LOG>) {
... # Process file.
}
sleep 15;
seek LOG,0,1; # Reset end-of-file error.
}
The final seek clears the end-of-file error without moving the pointer. If that doesn't work (depending on your C library's standard I/O implementation), then you may need something more like this:
for (;;) {
for ($curpos = tell FILE; $_ = <FILE>; $curpos = tell FILE) {
# search for some stuff and put it into files
}
sleep $for_a_while;
seek FILE, $curpos, 0;
}
Similar strategies could be used to remember the seek addresses of each line in an array.
seekdir
seekdir DIRHANDLE, POS
This function sets the current position for the readdir routine on DIRHANDLE. POS must be a value returned by telldir. This function has the same caveats about possible directory compaction as the corresponding system library routine. The function may not be implemented everywhere that readdir is. It's certainly not implemented where readdir isn't.
select (output filehandle)
select FILEHANDLE select
For historical reasons, there are two select operators that are totally unrelated to each other. See the next section for the other one. This select operator returns the currently selected output filehandle, and if FILEHANDLE is supplied, sets the current default filehandle for output. This has two effects: first, a write or a print without a filehandle will default to this FILEHANDLE. Second, special variables related to output will refer to this output filehandle. For example, if you have to set the same top-of-form format for more than one output filehandle, you might do the following:
select REPORT1; $^ = 'MyTop'; select REPORT2; $^ = 'MyTop';
But note that this leaves REPORT2 as the currently selected filehandle. This could be construed as antisocial, since it could really foul up some other routine's print or write statements. Properly written library routines leave the currently selected filehandle the same on exit as it was upon entry. To support this, FILEHANDLE may be an expression whose value gives the name of the actual filehandle. Thus, you can save and restore the currently selected filehandle:
my $oldfh = select STDERR; $| = 1; select $oldfh;
or (being bizarre and obscure):
select((select(STDERR), $| = 1)[0])
This example works by building a list consisting of the returned value from select(STDERR) (which selects STDERR as a side effect) and $| = 1 (which is always 1), but sets autoflushing on the now-selected STDERR as a side effect. The first element of that list (the previously selected filehandle) is now used as an argument to the outer select. Bizarre, right? That's what you get for knowing just enough Lisp to be dangerous.
However, now that we've explained all that, we should point out that you rarely need to use this form of select nowadays, because most of the special variables you would want to set have object-oriented wrapper methods to do it for you. So instead of setting $| directly, you might say:
use FileHandle; STDOUT->autoflush (1);
And the earlier format example might be coded as:
use FileHandle;
REPORT1->format_top_name("MyTop");
REPORT2->format_top_name("MyTop");
select (ready file descriptors)
select RBITS, WBITS, EBITS, TIMEOUT
The four-argument select operator is totally unrelated to the previously described operator. This operator is for discovering which (if any) of your file descriptors are ready to do input or output, or to report an exceptional condition. (This helps you avoid having to do polling.) It calls the select (2) system call with the bitmasks you've specified, which you can construct using fileno and vec, like this:
$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 {
my @fhlist = @_;
my $bits;
for (@fhlist) {
vec($bits, fileno($_), 1) = 1;
}
return $bits;
}
$rin = fhbits(qw(STDIN TTY MYSOCK));
If you wish to use the same bitmasks repeatedly (and it's more efficient if you do), the usual idiom is:
($nfound, $timeleft) =
select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
Or to block until any file descriptor becomes ready:
$nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
The $wout=$win trick works because the value of an assignment is its left side, so $wout gets clobbered first by the assignment, and then by the select, while $win remains unchanged.
Any of the bitmasks can also be undef. The timeout, if specified, is in seconds, which may be fractional. (A timeout of 0 effects a poll.) Not many implementations are capable of returning the $timeleft. If not, they always return $timeleft equal to the supplied $timeout.
One use for select is to sleep with a finer resolution than sleep allows. To do this, specify undef for all the bitmasks. So, to sleep for (at least) 4.75 seconds, use:
select undef, undef, undef, 4.75;
(On some non-UNIX systems this may not work, and you may need to fake up at least one bitmask for a valid descriptor that won't ever be ready.)
Mixing buffered I/O (like read or <HANDLE>) with four-argument select is asking for trouble. Use sysread instead.
semctl
semctl ID, SEMNUM, CMD, ARG
This function calls the System V IPC system call semctl (2). 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. The function returns like ioctl: the undefined value for error, "0 but true" for zero, or the actual return value otherwise. On error, it puts the error code into $!. Before calling, you should say:
require "ipc.ph"; require "sem.ph";
This function is available only on machines supporting System V IPC.
semget
semget KEY, NSEMS, SIZE, FLAGS
This function calls the System V IPC system call semget (2). The function returns the semaphore ID, or the undefined value if there is an error. On error, it puts the error code into $!. Before calling, you should say:
require "ipc.ph"; require "sem.ph";
This function is available only on machines supporting System V IPC.
semop
semop KEY, OPSTRING
This function calls the System V IPC system call semop (2) to perform semaphore operations such as signaling and waiting. OPSTRING must be a packed array of semop structures. You can make each semop structure by saying pack(`s*`, $semnum, $semop, $semflag). The number of semaphore operations is implied by the length of OPSTRING. The function returns true if successful, or false if there is an error. On error, it puts the error code into $!. Before calling, you should say:
require "ipc.ph"; require "sem.ph";
The following code waits on semaphore $semnum of semaphore id $semid:
$semop = pack "s*", $semnum, -1, 0; die "Semaphore trouble: $!\n" unless semop $semid, $semop;
To signal the semaphore, simply replace -1 with 1.
This function is available only on machines supporting System V IPC.
send
send SOCKET, MSG, FLAGS, TO send SOCKET, MSG, FLAGS
This function sends a message on a socket. It takes the same flags as the system call of the same name--see send (2). On unconnected sockets you must specify a destination to send TO, in which case send works like sendto (2). The function returns the number of bytes sent, or the undefined value if there is an error. On error, it puts the error code into $!.
(Some non-UNIX systems improperly treat sockets as different objects than ordinary file descriptors, with the result that you must always use send and recv on sockets rather than the handier standard I/O operators.)
setpgrp
setpgrp PID, PGRP
This function sets the current process group (pgrp) for the specified PID (use a PID of 0 for the current process). Invoking setpgrp will produce a fatal error if used on a machine that doesn't implement setpgrp (2). Beware: some systems will ignore the arguments you provide and always do setpgrp(0, $$). Fortunately, those are the arguments one usually provides. (For better portability (by some definition), use the setpgid() function in the POSIX module, or if you're really just trying to daemonize your script, consider the POSIX::setsid() function as well.)
setpriority
setpriority WHICH, WHO, PRIORITY
This function sets the current priority for a process, a process group, or a user. See setpriority (2). Invoking setpriority will produce a fatal error if used on a machine that doesn't implement setpriority (2). To "nice" your process down by four units (the same as executing your program with nice (1)), try:
setpriority 0, 0, getpriority(0, 0) + 4;
The interpretation of a given priority may vary from one operating system to the next.
setsockopt
setsockopt SOCKET, LEVEL, OPTNAME, OPTVAL
This function sets the socket option requested. The function returns undefined if there is an error. OPTVAL may be specified as undef if you don't want to pass an argument. A common option to set on a socket is SO_REUSEADDR, to get around the problem of not being able to bind to a particular address while the previous TCP connection on that port is still making up its mind to shut down. That would look like this:
use Socket;
...
setsockopt(MYSOCK, SOL_SOCKET, SO_REUSEADDR, 1)
or warn "Can't do setsockopt: $!\n";
shift
shift ARRAY shift
This function shifts the first value of the array off and returns it, shortening the array by 1 and moving everything down. (Or up, or left, depending on how you visualize the array list.) If there are no elements in the array, the function returns the undefined value. If ARRAY is omitted, the function shifts @ARGV (in the main program), or @_ (in subroutines). See also unshift, push, pop, and splice. The shift and unshift functions do the same thing to the left end of an array that pop and push do to the right end.
shmctl
shmctl ID, CMD, ARG
This function calls the System V IPC system call, shmctl (2). If CMD is &IPC_STAT, then ARG must be a variable which will hold the returned shmid_ds structure. The function returns like ioctl: the undefined value for error, "0 but true" for zero, or the actual return value otherwise. On error, it puts the error code into $!. Before calling, you should say:
require "ipc.ph"; require "shm.ph";
This function is available only on machines supporting System V IPC.
shmget
shmget KEY, SIZE, FLAGS
This function calls the System V IPC system call, shmget (2). The function returns the shared memory segment ID, or the undefined value if there is an error. On error, it puts the error code into $!. Before calling, you should say:
require "ipc.ph"; require "shm.ph";
This function is available only on machines supporting System V IPC.
shmread
shmread ID, VAR, POS, SIZE
This function reads from the shared memory segment ID starting at position POS for size SIZE (by attaching to it, copying out, and detaching from it). VAR must be a variable that will hold the data read. The function returns true if successful, or false if there is an error. On error, it puts the error code into $!. This function is available only on machines supporting System V IPC.
shmwrite
shmwrite ID, STRING, POS, SIZE
This function writes to the shared memory segment ID starting at position POS for size SIZE (by attaching to it, copying in, and detaching from it). If STRING is too long, only SIZE bytes are used; if STRING is too short, nulls are written to fill out SIZE bytes. The function returns true if successful, or false if there is an error. On error, it puts the error code into $!. This function is available only on machines supporting System V IPC.
shutdown
shutdown SOCKET, HOW
This function shuts down a socket connection in the manner indicated by HOW. If HOW is 0, further receives are disallowed. If HOW is 1, further sends are disallowed. If HOW is 2, everything is disallowed.
(If you came here trying to figure out how to shut down your system, you'll have to execute an external program to do that. See system.)
sin
sin EXPR
Sorry, there's nothing wicked about this operator. It merely returns the sine of EXPR (expressed in radians). If EXPR is omitted, it returns sine of $_.
For the inverse sine operation, you may use the POSIX::asin() function, or use this relation:
sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
sleep
sleep EXPR sleep
This function causes the script to sleep for EXPR seconds, or forever if no EXPR. It may be interrupted by sending the process a SIGALRM. The function returns the number of seconds actually slept. On some systems, the function sleeps till the "top of the second," so, for instance, a sleep 1 may sleep anywhere from 0 to 1 second, depending on when in the current second you started sleeping. A sleep 2 may sleep anywhere from 1 to 2 seconds. And so on. If available, the select (ready file descriptors) call can give you better resolution. You may also be able to use syscall to call the getitimer (2) and setitimer (2) routines that some UNIX systems support.
socket
socket SOCKET, DOMAIN, TYPE, PROTOCOL
This function opens a socket of the specified kind and attaches it to filehandle SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for socket (2). Before using this function, your program should contain the line:
use Socket;
This gives you the proper constants. The function returns true if successful. See the examples in the section "Sockets" in Chapter 6, Social Engineering.
socketpair
socketpair SOCKET1, SOCKET2, DOMAIN, TYPE, PROTOCOL
This function creates an unnamed pair of sockets in the specified domain, of the specified type. DOMAIN, TYPE, and PROTOCOL are specified the same as for socketpair (2). If socketpair (2) is unimplemented, invoking this function yields a fatal error. The function returns true if successful.
This function is typically used just before a fork. One of the resulting processes should close SOCKET1, and the other should close SOCKET2. You can use these sockets bidirectionally, unlike the filehandles created by the pipe function.
sort
sort SUBNAME LIST sort BLOCK LIST sort LIST
This function sorts the LIST and returns the sorted list value. By default, it sorts in standard string comparison order (undefined values sorting before defined null strings, which sort before everything else). SUBNAME, if given, is the name of a subroutine that returns an integer less than, equal to, or greater than 0, depending on how the elements of the list are to be ordered. (The handy <=> and cmp operators can be used to perform three-way numeric and string comparisons.) 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 the examples below). The variables $a and $b are passed by reference, so don't modify them in the subroutine. SUBNAME may be a scalar variable name (unsubscripted), in which case the value provides the name of (or a reference to) the actual subroutine to use. In place of a SUBNAME, you can provide a BLOCK as an anonymous, in-line sort subroutine.
To do an ordinary numeric sort, say this:
sub numerically { $a <=> $b; }
@sortedbynumber = sort numerically 53,29,11,32,7;
To sort in descending order, simply reverse the $a and $b. To sort a list value by some associated value, use a hash lookup in the sort routine:
sub byage {
$age{$a} <=> $age{$b};
}
@sortedclass = sort byage @class;
As an extension of that notion, you can cascade several different comparisons using the handy comparison operators, which work nicely for this because when they return 0 they fall through to the next case. The routine below sorts to the front of the list those people who are first richer, then taller, then younger, then less alphabetically challenged. We also put a final comparison between $a and $b to make sure the ordering is always well defined.
sub prospects {
$money{$b} <=> $money{$a}
or
$height{$b} <=> $height{$a}
or
$age{$a} <=> $age{$b}
or
$lastname{$a} cmp $lastname{$b}
or
$a cmp $b;
}
@sortedclass = sort prospects @class;
To sort fields without regard to case, say:
@sorted = sort { lc($a) cmp lc($b) } @unsorted;
And finally, note the equivalence of the two ways to sort in reverse:
sub backwards { $b cmp $a; }
@harry = qw(dog cat x Cain Abel);
@george = qw(gone chased yz Punished Axed);
print sort @harry; # prints AbelCaincatdogx
print sort backwards @harry; # prints xdogcatCainAbel
print reverse sort @harry; # prints xdogcatCainAbel
print sort @george, "to", @harry; # Remember, it's one LIST.
# prints AbelAxedCainPunishedcatchaseddoggonetoxyz
Do not declare $a and $b as lexical variables (with my). They are package globals (though they're exempt from the usual restrictions on globals when you're using use strict). You do need to make sure your sort routine is in the same package though, or qualify $a and $b with the package name of the caller.
One last caveat. Perl's sort is implemented in terms of C's qsort (3) function. Some qsort (3) versions will dump core if your sort subroutine provides inconsistent ordering of values.
splice
splice ARRAY, OFFSET, LENGTH, LIST splice ARRAY, OFFSET, LENGTH splice ARRAY, OFFSET
This function removes the elements designated by OFFSET and LENGTH from an array, and replaces them with the elements of LIST, if any. The function returns the elements removed from the array. The array grows or shrinks as necessary. If LENGTH is omitted, the function removes everything from OFFSET onward. The following equivalences hold (assuming $[ is 0):
| Direct Method | Splice Equivalent |
|---|---|
| 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); |
The splice function is also handy for carving up the argument list passed to a subroutine. For example, assuming list lengths are passed before lists:
sub list_eq { # compare two list values
my @a = splice(@_, 0, shift);
my @b = splice(@_, 0, shift);
return 0 unless @a == @b; # same len?
while (@a) {
return 0 if pop(@a) ne pop(@b);
}
return 1;
}
if (list_eq($len, @foo[1..$len], scalar(@bar), @bar)) { ... }
It would probably be cleaner just to use references for this, however.
split
split /PATTERN/, EXPR, LIMIT split /PATTERN/, EXPR split /PATTERN/ split
This function scans a string given by EXPR for delimiters, and splits the string into a list of substrings, returning the resulting list value in list context, or the count of substrings in scalar context. The delimiters are determined by repeated pattern matching, using the regular expression given in PATTERN, so the delimiters may be of any size, and need not be the same string on every match. (The delimiters are not ordinarily returned, but see below.) If the PATTERN doesn't match at all, split returns the original string as a single substring. If it matches once, you get two substrings, and so on.
If LIMIT is specified and is not negative, the function splits into no more than that many fields (though it may split into fewer if it runs out of delimiters). If LIMIT is negative, it is treated as if an arbitrarily large LIMIT has been specified. If LIMIT is omitted, trailing null fields are stripped from the result (which potential users of pop would do well to remember). If EXPR is omitted, the function splits the $_ string. If PATTERN is also omitted, the function splits on whitespace, /\s+/, after skipping any leading whitespace.
Strings of any length can be split:
@chars = split //, $word; @fields = split /:/, $line; @words = split ' ', $paragraph; @lines = split /^/m, $buffer;
A pattern capable of matching either the null string or something longer than the null string (for instance, a pattern consisting of any single character modified by a * or ?) will split the value of EXPR into separate characters wherever it is the null string that produces the match; non-null matches will skip over occurrences of the delimiter in the usual fashion. (In other words, a pattern won't match in one spot more than once, even if it matched with a zero width.) For example:
print join ':', split / */, 'hi there';
produces the output "h:i:t:h:e:r:e". The space disappears because it matched as part of the delimiter. As a trivial case, the null pattern // simply splits into separate characters (and spaces do not disappear).
The LIMIT parameter is used to split only part of a string:
($login, $passwd, $remainder) = split /:/, $_, 3;
We encourage you to split to lists of names like this in order to make your code self-documenting. (For purposes of error checking, note that $remainder would be undefined if there were fewer than three fields.) 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 split above, LIMIT would have been 4 by default, and $remainder would have received only the third field, not all the rest of the fields. In time-critical applications it behooves you not to split into more fields than you really need.
We said earlier that the delimiters are not returned, but if the PATTERN contains parentheses, then the substring matched by each pair of parentheses is included in the resulting list, interspersed with the fields that are ordinarily returned. Here's a simple case:
split /([-,])/, "1-10,20";
produces the list value:
(1, '-', 10, ',', 20)
With more parentheses, a field is returned for each pair, even if some of the pairs don't match, in which case undefined values are returned in those positions. So if you say:
split /(-)|(,)/, "1-10,20";
you get the value:
(1, '-', undef, 10, undef, ',', 20)
The /PATTERN/ argument may be replaced with an expression to specify patterns that vary at run-time. (To do run-time compilation only once, use /$variable/o.) As a special case, specifying a space ` ` will split on whitespace just as split with no arguments does. Thus, split(` `) can be used to emulate awk 's default behavior, whereas split(/ /) will give you as many null initial fields as there are leading spaces. (Other than this special case, if you supply a string instead of a regular expression, it'll be interpreted as a regular expression anyway.)
The following example splits an RFC-822 message header into a hash containing $head{Date}, $head{Subject}, and so on. It uses the trick of assigning a list of pairs to a hash, based on the fact that delimiters alternate with delimited fields. It makes use of parentheses to return part of each delimiter as part of the returned list value. Since the split pattern is guaranteed to return things in pairs by virtue of containing one set of parentheses, the hash assignment is guaranteed to receive a list consisting of key/value pairs, where each key is the name of a header field. (Unfortunately this technique loses information for multiple lines with the same key field, such as Received-By lines. Ah, well. . . .)
$header =~ s/\n\s+/ /g; # Merge continuation lines.
%head = ('FRONTSTUFF', split /^([-\w]+):/m, $header);
The following example processes the entries in a UNIX passwd file. You could leave out the chop, in which case $shell would have a newline on the end of it.
open PASSWD, '/etc/passwd';
while (<PASSWD>) {
chop; # remove trailing newline
($login, $passwd, $uid, $gid, $gcos, $home, $shell) =
split /:/;
...
}
The inverse of split is performed by join (except that join can only join with the same delimiter between all fields). To break apart a string with fixed-position fields, use unpack.
sprintf
sprintf FORMAT, LIST
This function returns a string formatted by the usual printf conventions. The FORMAT string contains text with embedded field specifiers into which the elements of LIST are substituted, one per field. Field specifiers are roughly of the form:
%m.nx
where the m and n are optional sizes whose interpretation depends on the type of field, and x is one of:
| Code | Meaning |
|---|---|
| c | Character |
| d | Decimal integer |
| e | Exponential format floating-point number |
| f | Fixed point format floating-point number |
| g | Compact format floating-point number |
| ld | Long decimal integer |
| lo | Long octal integer |
| lu | Long unsigned decimal integer |
| lx | Long hexadecimal integer |
| o | Octal integer |
| s | String |
| u | Unsigned decimal integer |
| x | Hexadecimal integer |
| X | Hexadecimal integer with upper-case letters |
The various combinations are fully documented in the manpage for printf (3), but we'll mention that m is typically the minimum length of the field (negative for left justified), and n is precision for exponential formats and the maximum length for other formats. Padding is typically done with spaces for strings and zeroes for numbers. The * character as a length specifier is not supported. But, you can easily get around this by including the length expression directly into FORMAT, as in:
$width = 20; $value = sin 1.0;
foreach $precision (0..($width-2)) {
printf "%${width}.${precision}f\n", $value;
}
sqrt
sqrt EXPR sqrt
This function returns the square root of EXPR. If EXPR is omitted, it returns the square root of $_. For other roots such as cube roots, you can use the ** operator to raise something to a fractional power.[8]
[8] Don't try either of these approaches with negative numbers, as that poses a slightly more complex problem.
srand
srand EXPR
This function sets the random number seed for the rand operator. If EXPR is omitted, it does srand(time), which is pretty predictable, so don't use it for security-type things, such as random password generation. Try something like this instead:[9]
[9] Frequently called programs (like CGI scripts) that simply use
time ^ $$for a seed can fall prey to the mathematical property that
a^b == (a+1)^(b+1)one-third of the time. If you're particularly concerned with this, see the Math::TrulyRandom module in CPAN.
srand( time() ^ ($$ + ($$ << 15)) );
Of course, you'd need something much more random than that for serious cryptographic purposes, since it's easy to guess the current time. Checksumming the compressed output of one or more rapidly changing operating system status programs is the usual method. For example:
srand (time ^ $$ ^ unpack "%32L*", `ps axww | gzip`);
Do not call srand multiple times in your program unless you know exactly what you're doing and why you're doing it. The point of the function is to "seed" the rand function so that rand can produce a different sequence each time you run your program. Just do it once at the top of your program, or you won't get random numbers out of rand!
stat
stat FILEHANDLE stat EXPR
This function returns a 13-element list giving the statistics for a file, either the file opened via FILEHANDLE, or named by EXPR. It's typically used as follows:
($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
$atime,$mtime,$ctime,$blksize,$blocks)
= stat $filename;
Not all fields are supported on all filesystem types. Here are the meanings of the fields:
| Field | Meaning |
|---|---|
| dev | Device number of filesystem |
| ino | Inode number |
| mode | File mode (type and permissions) |
| nlink | Number of (hard) links to the file |
| uid | Numeric user ID of file's owner |
| gid | Numeric group ID of file's owner |
| rdev | The device identifier (special files only) |
| size | Total size of file, in bytes |
| atime | Last access time since the epoch |
| mtime | Last modify time since the epoch |
| ctime | Inode change time (NOT creation time!) since the epoch |
| blksize | Preferred blocksize for file system I/O |
| blocks | Actual number of blocks allocated |
$dev and $ino, taken together, uniquely identify a file. The $blksize and $blocks are likely defined only on BSD-derived filesystems. The $blocks field (if defined) is reported in 512-byte blocks. Note that $blocks*512 can differ greatly from $size for files containing unallocated blocks, or "holes", which aren't counted in $blocks.
If stat is passed the special filehandle consisting of an underline, no actual stat (2) is done, but the current contents of the stat structure from the last stat or stat-based file test (the -x operators) are returned.
The following example first stats $file to see whether it is executable. If it is, it then pulls the device number out of the existing stat structure and tests it to see whether it looks like a Network File System (NFS). Such filesystems tend to have negative device numbers.
if (-x $file and ($d) = stat(_) and $d < 0) {
print "$file is executable NFS file\n";
}
Hint: if you need only the size of the file, check out the -s file test operator, which returns the size in bytes directly. There are also file tests that return the ages of files in days.
study
study SCALAR study
This function 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 run-times with and without it to see which runs faster. Those loops that scan for many short constant strings (including the constant parts of more complex patterns) will benefit most. If all your pattern matches are constant strings, anchored at the front, study won't help at all, because no scanning is done. 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 that 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.
If you have to look for strings that you don't know until run-time, you can build an entire loop as a string and eval that to avoid recompiling all your patterns all the time. Together with setting $/ to input entire files as one record, this can be very fast, often faster than specialized programs like fgrep. The following scans a list of files (@files) for a list of words (@words), and prints out the names of those files that contain a match:
$search = 'while (<>) { study;';
foreach $word (@words) {
$search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n";
}
$search .= "}";
@ARGV = @files;
undef $/; # slurp each entire file
eval $search; # this screams
die $@ if $@; # in case eval failed
$/ = "\n"; # put back to normal input delim
foreach $file (sort keys(%seen)) {
print $file, "\n";
}
sub
sub NAME BLOCK sub NAME sub BLOCK sub NAME PROTO BLOCK sub NAME PROTO sub PROTO BLOCK
The first two of these are not really operators, but rather they declare the existence of named subroutines, which is why the syntax includes a NAME, after all. (As declarations, they return no value.) The first one additionally defines the subroutine with a BLOCK, which contains the code for the subroutine. The second one (the one without the BLOCK) is just a forward declaration, that is, a declaration that introduces the subroutine name without defining it, with the expectation that the real definition will come later. (This is useful because the parser treats a word specially if it knows it's a user-defined subroutine. You can call such a subroutine as if it were a list operator, for instance.)
The third form really is an operator, in that it can be used within expressions to generate an anonymous subroutine at run-time. (More specifically, it returns a reference to an anonymous subroutine, since you can't talk about something anonymous without some kind of reference to it.) If the anonymous subroutine refers to any lexical variables declared outside its BLOCK, it functions as a closure, which means that different calls to the same sub operator will do the bookkeeping necessary to keep the correct "version" of each such lexical variable in sight for the life of the closure, even if the original scope of the lexical variable has been destroyed.
The final three forms are identical to the first three, except that they also supply a prototype that lets you specify how calls to your subroutine should be parsed and analyzed, so you can make your routines act more like some of Perl's built-in functions. See "Subroutines" in Chapter 2, The Gory Details and "Anonymous Subroutines" in Chapter 4, References and Nested Data Structures for more details.
substr
substr EXPR, OFFSET, LENGTH substr EXPR, OFFSET
This function extracts a substring out of the string given by EXPR and returns it. The substring is extracted starting at OFFSET characters from the front of the string. (Note: if you've messed with $[, the beginning of the string isn't at 0, but since you haven't messed with it (have you?), it is.) If OFFSET is negative, the substring starts that far from the end of the string instead. If LENGTH is omitted, everything to the end of the string is returned. If LENGTH is negative, the length is calculated to leave that many characters off the end of the string. Otherwise, LENGTH indicates the length of the substring to extract, which is sort of what you'd expect.
You can use substr as an lvalue (something to assign to), in which case EXPR must also be a legal lvalue. If you assign something shorter than the length of your substring, the string will shrink, and if you assign something longer than the length, 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 or the x operator.
To prepend the string "Larry" to the current value of $_, use:
substr($_, 0, 0) = "Larry";
To instead replace the first character of $_ with "Moe", use:
substr($_, 0, 1) = "Moe";
and finally, to replace the last character of $_ with "Curly", use:
substr($_, -1, 1) = "Curly";
These last few examples presume you haven't messed with the value of $[. You haven't, have you? Good.
symlink
symlink OLDFILE, NEWFILE
This function creates a new filename symbolically linked to the old filename. The function returns 1 for success, 0 otherwise. On systems that don't support symbolic links, it produces a fatal error at run-time. To check for that, use eval to trap the potential error:
$can_symlink = (eval { symlink("", ""); }, $@ eq "");
Or use the Config module. Be careful if you supply a relative symbolic link, since it'll be interpreted relative to the location of the symbolic link itself, not your current working directory.
syscall
syscall LIST
This function calls the system call specified as the first element of the list, passing the remaining elements as arguments to the system call. (Many of these are now more readily available through the POSIX module, and others.) The function produces a fatal error if syscall (2) is unimplemented. The arguments are interpreted as follows: if a given argument is numeric, the argument is passed as a C integer. If not, a pointer to the string value is passed. You are responsible for making sure the string is long enough to receive any result that might be written into it. Otherwise you're looking at a coredump. 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. (See the following example.)
This example calls the setgroups (2) system call to add to the group list of the current process. (It will only work on machines that support multiple group membership.)
require 'syscall.ph';
syscall &SYS_setgroups, @groups+0, pack("i*", @groups);
Note that you may have to run h2ph as indicated in the Perl installation instructions for syscall.ph to exist. Some systems may require a pack template of "s*" instead. Best of all, the syscall function assumes the size equivalence of the C types int, long, and char *.
Try not to think of syscall as the epitome of portability.
sysopen
sysopen FILEHANDLE, FILENAME, MODE sysopen FILEHANDLE, FILENAME, MODE, PERMS
This function opens the file whose filename is given by FILENAME, and associates it with FILEHANDLE. If FILEHANDLE is an expression, its value is used as the name of (or reference to) the filehandle. This function calls open (2) with the parameters FILENAME, MODE, PERMS.
The possible values and flag bits of the MODE parameter are system-dependent; they are available via the Fcntl library module. However, for historical reasons, some values are universal: zero means read-only, one means write-only, and two means read/write.
If the file named by FILENAME does not exist and sysopen creates it (typically because MODE includes the O_CREAT flag), then the value of PERMS specifies the permissions of the newly created file. If PERMS is omitted, the default value is 0666, which allows read and write for all. This default is reasonable: see umask.
The FileHandle module described in Chapter 7, The Standard Perl Library provides a more object-oriented approach to sysopen. See also open earlier in this chapter.
sysread
sysread FILEHANDLE, SCALAR, LENGTH, OFFSET sysread FILEHANDLE, SCALAR, LENGTH
This function attempts to read LENGTH bytes of data into variable SCALAR from the specified FILEHANDLE using read (2). The function returns the number of bytes actually read, or 0 at EOF. It returns the undefined value on error. SCALAR will be grown or shrunk to the length actually read. The OFFSET, if specified, says where in the string to start putting the bytes, so that you can read into the middle of a string that's being used as a buffer. For an example, see syswrite. You should be prepared to handle the problems (like interrupted system calls) that standard I/O normally handles for you. Also, do not mix calls to read and sysread on the same filehandle unless you are into heavy wizardry (and/or pain).
system
system LIST
This function executes any program on the system for you. It does exactly the same thing as exec LIST except that it does a fork first, and then, after the exec, it waits for the exec'd program to complete. That is (in non-UNIX terms), it runs the program for you, and returns when it's done, unlike exec, which never returns (if it succeeds). Note that argument processing varies depending on the number of arguments, as described for exec. The return value is the exit status of the program as returned by the wait (2) call. To get the actual exit value, divide by 256. (The lower 8 bits are set if the process died from a signal.) See exec.
Because system and backticks block SIGINT and SIGQUIT, killing the program they're running with one of those signals doesn't actually interrupt your program.
@args = ("command", "arg1", "arg2");
system(@args) == 0
or die "system @args failed: $?"
Here's a more elaborate example of analyzing the return value from system on a UNIX system to check for all possibilities, including for signals and coredumps.
$rc = 0xffff & system @args;
printf "system(%s) returned %#04x: ", "@args", $rc;
if ($rc == 0) {
print "ran with normal exit\n";
}
elsif ($rc == 0xff00) {
print "command failed: $!\n";
}
elsif ($rc > 0x80) {
$rc >>= 8;
print "ran with non-zero exit status $rc\n";
}
else {
print "ran with ";
if ($rc & 0x80) {
$rc &= ~0x80;
print "coredump from ";
}
print "signal $rc\n"
}
$ok = ($rc != 0);
syswrite
syswrite FILEHANDLE, SCALAR, LENGTH, OFFSET syswrite FILEHANDLE, SCALAR, LENGTH
This function attempts to write LENGTH bytes of data from variable SCALAR to the specified FILEHANDLE using write (2). The function returns the number of bytes actually written, or the undefined value on error. You should be prepared to handle the problems that standard I/O normally handles for you, such as partial writes. The OFFSET, if specified, says where in the string to start writing from, in case you're using the string as a buffer, for instance, or you need to recover from a partial write. To copy data from filehandle FROM into filehandle TO, use something like:
$blksize = (stat FROM)[11] || 16384; # preferred block size?
while ($len = sysread FROM, $buf, $blksize) {
if (!defined $len) {
next if $! =~ /^Interrupted/;
die "System read error: $!\n";
}
$offset = 0;
while ($len) { # Handle partial writes.
$written = syswrite TO, $buf, $len, $offset;
die "System write error: $!\n"
unless defined $written;
$len -= $written;
$offset += $written;
};
}
Do not mix calls to (print or write) and syswrite on the same filehandle unless you are into heavy wizardry.
tell
tell FILEHANDLE tell
This function returns the current file position (in bytes, 0-based) for FILEHANDLE. This value is typically fed to the seek function at some future time to get back to the current position. FILEHANDLE may be an expression whose value gives the name of the actual filehandle, or a reference to a filehandle object. If FILEHANDLE is omitted, the function returns the position of the file last read. File positions are only meaningful on regular files. Devices, pipes, and sockets have no file position.
See seek for an example.
telldir
telldir DIRHANDLE
This function returns the current position of the readdir routines on DIRHANDLE. This value may be given to seekdir to access a particular location in a directory. The function has the same caveats about possible directory compaction as the corresponding system library routine. This function may not be implemented everywhere that readdir is. Even if it is, no calculation may be done with the return value. It's just an opaque value, meaningful only to seekdir.
tie
tie VARIABLE, CLASSNAME, LIST
This function binds a variable to a package class that will provide the implementation for the variable. VARIABLE is the name of the variable to be tied. CLASSNAME is the name of a class implementing objects of an appropriate type. Any additional arguments are passed to the "new" method of the class (meaning TIESCALAR, TIEARRAY, or TIEHASH). Typically these are arguments such as might be passed to the dbm_open (3) function of C, but this is package dependent. The object returned by the "new" method is also returned by the tie function, which can be useful if you want to access other methods in CLASSNAME. (The object can also be accessed through the tied function.) So, a class for tying a hash to an ISAM implementation might provide an extra method to traverse a set of keys sequentially (the "S" of ISAM), since your typical DBM implementation can't do that.
Note that functions such as keys and values may return huge list values when used on large objects like DBM files. You may prefer to use the each function to iterate over such. For example:
use NDBM_File;
tie %ALIASES, "NDBM_File", "/etc/aliases", 1, 0
or die "Can't open aliases: $!\n";
while (($key,$val) = each %ALIASES) {
print $key, ' = ', $val, "\n";
}
untie %ALIASES;
A class implementing a hash should provide the following methods:
TIEHASH $class, LIST DESTROY $self FETCH $self, $key STORE $self, $key, $value DELETE $self, $key EXISTS $self, $key FIRSTKEY $self NEXTKEY $self, $lastkey
A class implementing an ordinary array should provide the following methods:
TIEARRAY $classname, LIST DESTROY $self FETCH $self, $subscript STORE $self, $subscript, $value
(As of this writing, other methods are still being designed. Check the online documentation for additions.)
A class implementing a scalar should provide the following methods:
TIESCALAR $classname, LIST DESTROY $self FETCH $self, STORE $self, $value
See "Using Tied Variables" in Chapter 5, Packages, Modules, and Object Classes for detailed discussion of all these methods. Unlike dbmopen, the tie function will not use or require a module for you--you need to do that explicitly yourself. See the DB_File and Config modules for interesting tie implementations.
tied
tied VARIABLE
This function returns a reference to the object underlying VARIABLE (the same value that was originally returned by the tie call which bound the variable to a package.) It returns the undefined value if VARIABLE isn't tied to a package. So, for example, you can use:
ref tied %hash
to find out which package your hash is currently tied to. (Presuming you've forgotten.)
time
time
This function returns the number of non-leap seconds since January 1, 1970, UTC.[10] The returned value is suitable for feeding to gmtime and localtime, and for comparison with file modification and access times returned by stat, and for feeding to utime--see the examples under utime.
[10] Also known as the "epoch", not to be confused with the "epic", which is about the making of UNIX. (Other operating systems may have a different epoch, not to mention a different epic.)
times
times
This function returns a four-element list giving the user and system CPU times, in seconds (possibly fractional), for this process and the children of this process.
($user, $system, $cuser, $csystem) = times;
For example, to time the execution speed of a section of Perl code:
$start = (times)[0]; ... $end = (times)[0]; printf "that took %.2f CPU seconds\n", $end - $start;
tr///
tr/// y///
This is the translation operator, which is like the one in the UNIX sed program, only better, in everybody's humble opinion. See Chapter 2, The Gory Details.
truncate
truncate FILEHANDLE, LENGTH truncate EXPR, LENGTH
This function truncates the file opened on FILEHANDLE, or named by EXPR, to the specified length. The function produces a fatal error if truncate (2) or an equivalent isn't implemented on your system. (You can always truncate a file by copying the front of it, if you have the disk space.)
uc
uc EXPR
This function returns an uppercased version of EXPR (or $_ if EXPR is omitted). This is the internal function implementing the \U escape in double-quoted strings. POSIX setlocale (3) settings are respected.
ucfirst
ucfirst EXPR
This function returns a version of EXPR (or $_ if EXPR is omitted) with the first character uppercased, that is, capitalized. This is the internal function implementing the \u escape in double-quoted strings. POSIX setlocale (3) settings are respected.
To force initial caps, and everything else lowercase, use:
ucfirst lc $word
which is equivalent to "\u\L$word".
umask
umask EXPR umask
This function sets the umask for the process and returns the old one. (The umask tells UNIX which permission bits to disallow when creating a file.) If EXPR is omitted, the function merely returns the current umask. For example, to ensure that the "other" bits are turned on, and the "user" bits are turned off, try something like:
umask((umask() & 077) | 7);
undef
undef EXPR undef
This function undefines the value of EXPR, which must be an lvalue. Use only on a scalar value, an entire array or hash, or a subroutine name (using the & prefix). Any storage associated with the object will be recovered for reuse (though not returned to the system, for most versions of UNIX). The undef function will probably not do what you expect on most special variables.
The function always returns the undefined value. This is useful because you can omit the EXPR, in which case nothing gets undefined, but you still get an undefined value that you could, for instance, return from a subroutine to indicate an error. Here are some uses of undef as a unary operator:
undef $foo;
undef $bar{'blurfl'};
undef @ary;
undef %assoc;
undef &mysub;
Without an argument, undef is just used for its value:
return (wantarray ? () : undef) if $they_blew_it; select(undef, undef, undef, $naptime);
You may use undef as a placeholder on the left side of a list assignment, in which case the corresponding value from the right side is simply discarded. Apart from that, you may not use undef as an lvalue.
unlink
unlink LIST
This function deletes a list of files.[11] If LIST is omitted, it unlinks the file given in $_. The function returns the number of files successfully deleted. Some sample commands:
[11] Actually, under UNIX, it removes the directory entries that refer to the real files. Since a file may be referenced (linked) from more than one directory, the file isn't actually removed until the last reference to it is removed.
$cnt = unlink 'a', 'b', 'c'; unlink @goners; unlink <*.bak>;
Note that unlink will not delete directories unless you are superuser and the -U flag is supplied to Perl. Even if these conditions are met, be warned that unlinking a directory can inflict Serious Damage on your filesystem. Use rmdir instead.
Here's a very simple rm command with very simple error checking:
#!/usr/bin/perl
@cannot = grep {not unlink} @ARGV;
die "$0: could not unlink @cannot\n" if @cannot;
unpack
unpack TEMPLATE, EXPR
This function does the reverse of pack: it takes a string (EXPR) representing a data structure and expands it out into a list value, returning the list value. (In a scalar context, it can be used to unpack a single value.) The TEMPLATE has much the same format as in the pack function--it specifies the order and type of the values to be unpacked. (See pack for a more detailed description of TEMPLATE.)
Here's a subroutine that does (some of) substr, only slower:
sub substr {
my($what, $where, $howmuch) = @_;
if ($where < 0) {
$where = -$where;
return unpack "\@* X$where a$howmuch", $what;
}
else {
return unpack "x$where a$howmuch", $what;
}
}
and then there's:
sub signed_ord { unpack "c", shift }
Here's a complete uudecode program:
#!/usr/bin/perl
$_ = <> until ($mode,$file) = /^begin\s*(\d*)\s*(\S*)/;
open(OUT,"> $file") if $file ne "";
while (<>) {
last if /^end/;
next if /[a-z]/;
next unless int((((ord() - 32) & 077) + 2) / 3) ==
int(length() / 4);
print OUT unpack "u", $_;
}
chmod oct $mode, $file;
In addition, you may prefix a field with %number to indicate that you want it to return 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:
undef $/;
$checksum = unpack ("%32C*", <>) % 32767;
The following efficiently counts the number of set bits in a bit vector:
$setbits = unpack "%32b*", $selectmask;
Here's a simple MIME decoder:
while (<>) {
tr#A-Za-z0-9+/##cd; # remove non-base64 chars
tr#A-Za-z0-9+/# -_#; # convert to uuencoded format
$len = pack("c", 32 + 0.75*length); # compute length byte
print unpack("u", $len . $_); # uudecode and print
}
unshift
unshift ARRAY, LIST
This function does the opposite of a shift. (Or the opposite of a push, depending on how you look at it.) It prepends LIST to the front of the array, and returns the new number of elements in the array:
unshift @ARGV, '-e', $cmd unless $ARGV[0] =~ /^-/;
use
use Module LIST use Module
The use declaration 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 the following:
BEGIN { require Module; import Module LIST; }
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 built-in--it's just an ordinary static method call into the package named by Module 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. See Chapter 5, Packages, Modules, and Object Classes for more information.
If you don't want your namespace altered, explicitly supply an empty list:
use Module ();
That is exactly equivalent to the following:
BEGIN { require Module; }
Because this is a wide-open interface, pragmas (compiler directives) are also implemented this way. Currently implemented pragmas include:
use integer; use diagnostics; use sigtrap qw(SEGV BUS); use strict qw(subs vars refs);
These pseudomodules typically import semantics into the current block scope, unlike ordinary modules, which import symbols into the current package. (The latter are effective through the end of the file.)
There's a corresponding declaration, no, that "unimports" any meanings originally imported by use, but that have since become, er, unimportant:
no integer; no strict 'refs';
See Chapter 7, The Standard Perl Library for a list of standard modules and pragmas.
utime
utime LIST
This function 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. The function returns the number of files successfully changed. The inode change time of each file is set to the current time. Here's an example of a touch command:
#!/usr/bin/perl $now = time; utime $now, $now, @ARGV;
and here's a more sophisticated touch command with a bit of error checking:
#!/usr/bin/perl
$now = time;
@cannot = grep {not utime $now, $now, $_} @ARGV;
die "$0: Could not touch @cannot.\n" if @cannot;
The standard touch command will actually create missing files, something like this:
$now = time;
foreach $file (@ARGV) {
utime $now, $now, $file
or open TMP, ">>$file"
or warn "Couldn't touch $file: $!\n";
}
To read the times from existing files, use stat.
values
values HASH
This function returns a list consisting of all the values of the named hash. 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 hash. To sort the hash by its values, see the example under keys. Note that using values on a hash that is bound to a humongous DBM file is bound to produce a humongous list, causing you to have a humongous process, leaving you in a bind. You might prefer to use the each function, which will iterate over the hash entries one by one without slurping them all into a single gargantuan (that is, humongous) list.
vec
vec EXPR, OFFSET, BITS
This function treats a string (the value of EXPR) as a vector of unsigned integers, and returns the value of the element specified by OFFSET and BITS. The function may also be assigned to, which causes the element to be modified. The purpose of the function is to provide very compact storage of lists of small integers. The integers may be very small--vectors can hold numbers that are as small as one bit, resulting in a bitstring.
The OFFSET specifies how many elements to skip over to find the one you want. BITS is the number of bits per element in the vector, so each element can contain an unsigned integer in the range 0..(2**BITS)-1. BITS must be one of 1, 2, 4, 8, 16, or 32. As many elements as possible are packed into each byte, and the ordering is such that vec($vectorstring,0,1) is guaranteed to go into the lowest bit of the first byte of the string. To find out the position of the byte in which an element is going to be put, you have to multiply the OFFSET by the number of elements per byte. When BITS is 1, there are eight elements per byte. When BITS is 2, there are four elements per byte. When BITS is 4, there are two elements (called nybbles) per byte. And so on.
Regardless of whether your machine is big-endian or little-endian, vec($foo, 0, 8) always refers to the first byte of string $foo. See select for examples of bitmaps generated with vec.
Vectors created with vec can also be manipulated with the logical operators |, &, ^, and ~, which will assume a bit vector operation is desired when the operands are strings.
A bit vector (BITS == 1) can be translated to or from a string of 1s and 0s by supplying a b* template to unpack or pack. Similarly, a vector of nybbles (BITS == 4) can be translated with an h* template.
wait
wait
This function waits for a child process to terminate and returns the pid of the deceased process, or -1 if there are no child processes. The status is returned in $?. If you get zombie child processes, you should be calling this function, or waitpid. A common strategy to avoid such zombies is:
$SIG{CHLD} = sub { wait };
If you expected a child and didn't find it, you probably had a call to system, a close on a pipe, or backticks between the fork and the wait. These constructs also do a wait (2) and may have harvested your child process. Use waitpid to avoid this problem.
waitpid
waitpid PID, FLAGS
This function waits for a particular child process to terminate and returns the pid when the process is dead, or -1 if there are no child processes, or if the FLAGS specify non-blocking and the process isn't dead yet. The status of the dead process is returned in $?. To get valid flag values say this:
use POSIX "sys_wait_h";
On systems that implement neither the waitpid (2) nor wait4 (2) system call, FLAGS may be specified only as 0. In other words, you can wait for a specific PID, but you can't do it in non-blocking mode.
wantarray
wantarray
This function returns true if the context of the currently executing subroutine is looking for a list value. The function returns false if the context is looking for a scalar. Here's a typical usage, demonstrating an "unsuccessful" return:
return wantarray ? () : undef;
See also caller. This function should really have been named "wantlist", but we named it back when list contexts were still called array contexts.
warn
warn LIST
This function produces a message on STDERR just like die, but doesn't try to exit or throw an exception. For example:
warn "Debug enabled" if $debug;
If the message supplied is null, the message "Something's wrong" is used. As with die, a message not ending with a newline will have file and line number information automatically appended. The warn operator is unrelated to the -w switch.
write
write FILEHANDLE write
This function writes a formatted record (possibly multi-line) to the specified filehandle, using the format associated with that filehandle--see the section "Formats" in Chapter 2, The Gory Details. By default the format for a filehandle is the one having the same name as the filehandle. However, the format for a filehandle may be changed by saying:
use FileHandle;
HANDLE->format_name("NEWNAME");
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. The number of lines remaining on the current page is in variable $-, which can be set to 0 to force a new page on the next write. (You may need to select the filehandle first.) By default the name of the top-of-page format is the name of the filehandle with "_TOP" appended, but the format for a filehandle may be changed by saying:
use FileHandle;
HANDLE->format_top_name("NEWNAME_TOP");
If FILEHANDLE is unspecified, output goes to the current default output filehandle, which starts out as STDOUT but may be changed by the select operator. If the FILEHANDLE is an expression, then the expression is evaluated to determine the actual FILEHANDLE at run-time.
Note that write is not the opposite of read. Use print for simple string output. If you looked up this entry because you wanted to bypass standard I/O, see syswrite.
|
 |
|
| Perl Functions by Category |  |
References and Nested Data Structures |
