Remember the following rule:
-=over 5
+=over 8
-=item *
+=item
I<THERE IS NO GENERAL RULE FOR CONVERTING A LIST INTO A SCALAR!>
operations. In general, they do what you want, unless you want
consistency.
+=head2 Perl Functions by Category
+
+Here are Perl's functions (including things that look like
+functions, like some of the keywords and named operators)
+arranged by category. Some functions appear in more
+than one place.
+
+=over
+
+=item Functions for SCALARs or strings
+
+chomp, chop, chr, crypt, hex, index, lc, lcfirst, length,
+oct, ord, pack, q/STRING/, qq/STRING/, reverse, rindex,
+sprintf, substr, tr///, uc, ucfirst, y///
+
+=item Regular expressions and pattern matching
+
+m//, pos, quotemeta, s///, split, study
+
+=item Numeric functions
+
+abs, atan2, cos, exp, hex, int, log, oct, rand, sin, sqrt,
+srand
+
+=item Functions for real @ARRAYs
+
+pop, push, shift, splice, unshift
+
+=item Functions for list data
+
+grep, join, map, qw/STRING/, reverse, sort, unpack
+
+=item Functions for real %HASHes
+
+delete, each, exists, keys, values
+
+=item Input and output functions
+
+binmode, close, closedir, dbmclose, dbmopen, die, eof,
+fileno, flock, format, getc, print, printf, read, readdir,
+rewinddir, seek, seekdir, select, syscall, sysread,
+syswrite, tell, telldir, truncate, warn, write
+
+=item Functions for fixed length data or records
+
+pack, read, syscall, sysread, syswrite, unpack, vec
+
+=item Functions for filehandles, files, or directories
+
+I<-X>, chdir, chmod, chown, chroot, fcntl, glob, ioctl, link,
+lstat, mkdir, open, opendir, readlink, rename, rmdir,
+stat, symlink, umask, unlink, utime
+
+=item Keywords related to the control flow of your perl program
+
+caller, continue, die, do, dump, eval, exit, goto, last,
+next, redo, return, sub, wantarray
+
+=item Keywords related to scoping
+
+caller, import, local, my, package, use
+
+=item Miscellaneous functions
+
+defined, dump, eval, formline, local, my, reset, scalar,
+undef, wantarray
+
+=item Functions for processes and process groups
+
+alarm, exec, fork, getpgrp, getppid, getpriority, kill,
+pipe, qx/STRING/, setpgrp, setpriority, sleep, system,
+times, wait, waitpid
+
+=item Keywords related to perl modules
+
+do, import, no, package, require, use
+
+=item Keywords related to classes and object-orientedness
+
+bless, dbmclose, dbmopen, package, ref, tie, tied, untie, use
+
+=item Low-level socket functions
+
+accept, bind, connect, getpeername, getsockname,
+getsockopt, listen, recv, send, setsockopt, shutdown,
+socket, socketpair
+
+=item System V interprocess communication functions
+
+msgctl, msgget, msgrcv, msgsnd, semctl, semget, semop,
+shmctl, shmget, shmread, shmwrite
+
+=item Fetching user and group info
+
+endgrent, endhostent, endnetent, endpwent, getgrent,
+getgrgid, getgrnam, getlogin, getpwent, getpwnam,
+getpwuid, setgrent, setpwent
+
+=item Fetching network info
+
+endprotoent, endservent, gethostbyaddr, gethostbyname,
+gethostent, getnetbyaddr, getnetbyname, getnetent,
+getprotobyname, getprotobynumber, getprotoent,
+getservbyname, getservbyport, getservent, sethostent,
+setnetent, setprotoent, setservent
+
+=item Time-related functions
+
+gmtime, localtime, time, times
+
+=item Functions new in perl5
+
+abs, bless, chomp, chr, exists, formline, glob, import, lc,
+lcfirst, map, my, no, prototype, qx, qw, readline, readpipe,
+ref, sub*, sysopen, tie, tied, uc, ucfirst, untie, use
+
+* - C<sub> was a keyword in perl4, but in perl5 it is an
+operator which can be used in expressions.
+
+=item Functions obsoleted in perl5
+
+dbmclose, dbmopen
+
+
+=back
+
+=head2 Alphabetical Listing of Perl Functions
+
+
=over 8
=item -X FILEHANDLE
containing null in the first block is considered a binary file. If C<-T>
or C<-B> is used on a filehandle, the current stdio buffer is examined
rather than the first block. Both C<-T> and C<-B> return TRUE on a null
-file, or a file at EOF when testing a filehandle.
+file, or a file at EOF when testing a filehandle. Because you have to
+read a file to do the C<-T> test, on most occasions you want to use a C<-f>
+against the file first, as in C<next unless -f $file && -T $file>.
If any of the file tests (or either the stat() or lstat() operators) are given the
special filehandle consisting of a solitary underline, then the stat
Accepts an incoming socket connect, just as the accept(2) system call
does. Returns the packed address if it succeeded, FALSE otherwise.
-See example in L<perlipc>.
+See example in L<perlipc/"Sockets: Client/Server Communication">.
=item alarm SECONDS
starting a new one. The returned value is the amount of time remaining
on the previous timer.
-For sleeps of finer granularity than one second, you may use Perl's
+For delays of finer granularity than one second, you may use Perl's
syscall() interface to access setitimer(2) if your system supports it,
-or else see L</select()> below.
+or else see L</select()> below. It is not advised to intermix alarm()
+and sleep() calls.
=item atan2 Y,X
Binds a network address to a socket, just as the bind system call
does. Returns TRUE if it succeeded, FALSE otherwise. NAME should be a
-packed address of the appropriate type for the socket. See example in
-L<perlipc>.
+packed address of the appropriate type for the socket. See the examples in
+L<perlipc/"Sockets: Client/Server Communication">.
=item binmode FILEHANDLE
-Arranges for the file to be read or written in "binary" mode in
-operating systems that distinguish between binary and text files.
-Files that are not in binary mode have CR LF sequences translated to LF
-on input and LF translated to CR LF on output. Binmode has no effect
-under Unix; in DOS, it may be imperative. If FILEHANDLE is an expression,
-the value is taken as the name of the filehandle.
+Arranges for the file to be read or written in "binary" mode in operating
+systems that distinguish between binary and text files. Files that are
+not in binary mode have CR LF sequences translated to LF on input and LF
+translated to CR LF on output. Binmode has no effect under Unix; in DOS
+and similarly archaic systems, it may be imperative--otherwise your
+DOS-damaged C library may mangle your file. 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
+C<binmode>. The rest need it. If FILEHANDLE is an expression, the value
+is taken as the name of the filehandle.
-=item bless REF,PACKAGE
+=item bless REF,CLASSNAME
=item bless REF
This function tells the referenced object (passed as REF) that it is now
-an object in PACKAGE--or the current package if no PACKAGE is specified,
-which is the usual case. It returns the reference for convenience, since
-a bless() is often the last thing in a constructor. See L<perlobj> for
-more about the blessing (and blessings) of objects.
+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.
+Always use the two-argument version if the function doing the blessing
+might be inherited by a derived class. See L<perlobj> for more about the
+blessing (and blessings) of objects.
=item caller EXPR
returns TRUE if there is a caller, that is, if we're in a subroutine or
eval() or require(), and FALSE otherwise. In a list context, returns
- ($package,$filename,$line) = caller;
+ ($package, $filename, $line) = caller;
With EXPR, it returns some extra information that the debugger uses to
print a stack trace. The value of EXPR indicates how many call frames
to go back before the current one.
+ ($package, $filename, $line,
+ $subroutine, $hasargs, $wantargs) = 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 with which that subroutine was invoked.
+
=item chdir EXPR
Changes the working directory to EXPR, if possible. If EXPR is
=item chmod LIST
Changes the permissions of a list of files. The first element of the
-list must be the numerical mode. Returns the number of files
-successfully changed.
+list must be the numerical mode, which should probably be an octal
+number. Returns the number of files successfully changed.
$cnt = chmod 0755, 'foo', 'bar';
chmod 0755, @executables;
If you chop a list, each element is chopped. Only the value of the
last chop is returned.
+Note that chop returns the last character. To return all but the last
+character, use C<substr($string, 0, -1)>.
+
=item chown LIST
Changes the owner (and group) of a list of files. The first two
@ary = <${pattern}>; # expand filenames
chown $uid, $gid, @ary;
+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.
+
=item chr NUMBER
Returns the character represented by that NUMBER in the character set.
=item chroot FILENAME
-Does the same as the system call of that name. If you don't know what
-it does, don't worry about it. If FILENAME is omitted, does chroot to
-$_.
+This function works as the system call by the same name: it makes the
+named directory the new root directory for all further pathnames that
+begin with a "/" by your process and all of its children. (It doesn't
+change your current working directory is unaffected.) For security
+reasons, this call is restricted to the superuser. If FILENAME is
+omitted, does chroot to $_.
=item close FILEHANDLE
Closes the file or pipe associated with the file handle, returning TRUE
only if stdio successfully flushes buffers and closes the system file
descriptor. You don't have to close FILEHANDLE if you are immediately
-going to do another open on it, since open will close it for you. (See
+going to do another open() on it, since open() will close it for you. (See
open().) However, an explicit close on an input file resets the line
counter ($.), while the implicit close done by open() does not. Also,
closing a pipe will wait for the process executing on the pipe to
Attempts to connect to a remote socket, just as the connect system call
does. Returns TRUE if it succeeded, FALSE otherwise. NAME should be a
-package address of the appropriate type for the socket. See example in
-L<perlipc>.
+packed address of the appropriate type for the socket. See the examples in
+L<perlipc/"Sockets: Client/Server Communication">.
+
+=item continue BLOCK
+
+Actually a flow control statement rather than a function. If there is a
+C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
+C<foreach>), it is always executed just before the conditional is about to
+be evaluated again, just like the third part of a C<for> loop in C. Thus
+it can be used to increment a loop variable, even when the loop has been
+continued via the C<next> statement (which is similar to the C C<continue>
+statement).
=item cos EXPR
=item crypt PLAINTEXT,SALT
-Encrypts a string exactly like the crypt(3) function in the C library.
-Useful for checking the password file for lousy passwords, amongst
-other things. Only the guys wearing white hats should do this.
+Encrypts a string exactly like the crypt(3) function in the C library
+(assuming that you actually have a version there that has not been
+extirpated as a potential munition). This can prove useful for checking
+the password file for lousy passwords, amongst other things. Only the
+guys wearing white hats should do this.
Here's an example that makes sure that whoever runs this program knows
their own password:
}
Of course, typing in your own password to whoever asks you
-for it is unwise at best.
+for it is unwise.
=item dbmclose ASSOC_ARRAY
[This function has been superseded by the tie() function.]
-This binds a dbm(3) or ndbm(3) file to an associative array. ASSOC is the
-name of the associative array. (Unlike normal open, the first argument
-is I<NOT> a filehandle, even though it looks like one). DBNAME is the
-name of the database (without the F<.dir> or F<.pag> extension). If the
-database does not exist, it is created with protection specified by
-MODE (as modified by the umask()). If your system only supports the
-older DBM functions, you may perform only one dbmopen() in your program.
-If your system has neither DBM nor ndbm, calling dbmopen() produces a
-fatal error.
+This binds a dbm(3), ndbm(3), sdbm(3), gdbm(), or Berkeley DB file to an
+associative array. ASSOC is the name of the associative array. (Unlike
+normal open, the first argument is I<NOT> a filehandle, even though it
+looks like one). DBNAME is the name of the database (without the F<.dir>
+or F<.pag> extension if any). If the database does not exist, it is
+created with protection specified by MODE (as modified by the umask()).
+If your system only supports the older DBM functions, you may perform only
+one dbmopen() in your program. In older versions of Perl, if your system
+had neither DBM nor ndbm, calling dbmopen() produced a fatal error; it now
+falls back to sdbm(3).
If you don't have write access to the DBM file, you can only read
associative array variables, not set them. If you want to test whether
}
dbmclose(%HIST);
+See also L<AnyDBM_File> for a more general description of the pros and
+cons of the various dbm apparoches, as well as L<DB_File> for a particularly
+rich implementation.
+
=item defined EXPR
-Returns a boolean value saying whether the lvalue EXPR has a real value
+Returns a boolean value saying whether EXPR has a real value
or not. Many operations return the undefined value under exceptional
conditions, such as end of file, uninitialized variable, system error
and such. This function allows you to distinguish between an undefined
See also undef().
+Note: many folks tend to overuse defined(), and then are surprised to
+discover that the number 0 and the null string are, in fact, defined
+concepts. For example, if you say
+
+ "ab" =~ /a(.*)b/;
+
+the pattern match succeeds, and $1 is defined, despite the fact that it
+matched "nothing". But it didn't really match nothing--rather, it
+matched something that happened to be 0 characters long. This is all
+very above-board and honest. When a function returns an undefined value,
+it's an admission that it couldn't give you an honest answer. So
+you should only use defined() when you're questioning the integrity
+of what you're trying to do. At other times, a simple comparison to
+0 or "" is what you want.
+
=item delete EXPR
Deletes the specified value from its hash array. Returns the deleted
=item die LIST
Outside of an eval(), prints the value of LIST to C<STDERR> and exits with
-the current value of $! (errno). If $! is 0, exits with the value of
-C<($? E<gt>E<gt> 8)> (`command` status). If C<($? E<gt>E<gt> 8)> is 0,
-exits with 255. Inside an eval(), the error message is stuffed into C<$@>.
-and the eval() is terminated with the undefined value.
+the current value of $! (errno). If $! is 0, exits with the value of
+C<($? E<gt>E<gt> 8)> (backtick `command` status). If C<($? E<gt>E<gt> 8)> is 0,
+exits with 255. Inside an eval(), the error message is stuffed into C<$@>,
+and the eval() is terminated with the undefined value; this makes die()
+the way to raise an exception.
Equivalent examples:
do this inside a loop.
Note that inclusion of library modules is better done with the
-use() and require() operators.
+use() and require() operators, which also do error checking
+and raise an exception if there's a problem.
=item dump LABEL
=item each ASSOC_ARRAY
-Returns a 2 element array consisting of the key and value for the next
-value of an associative array, so that you can iterate over it.
+When called in a list context, returns a 2-element array consisting
+of the key and value for the next element of an associative array,
+so that you can iterate over it. When called in a scalar context,
+returns the key only for the next element in the associative array.
Entries are returned in an apparently random order. When the array is
-entirely read, a null array is returned (which when assigned produces a
-FALSE (0) value). The next call to each() after that will start
+entirely read, a null array is returned in list context (which when
+assigned produces a FALSE (0) value), and C<undef> is returned in a
+scalar context. The next call to each() after that will start
iterating again. The iterator can be reset only by reading all the
elements from the array. You should not add elements to an array while
you're iterating over it. There is a single iterator for each
=item eof FILEHANDLE
+=item eof ()
+
=item eof
Returns 1 if the next read on FILEHANDLE will return end of file, or if
FILEHANDLE is not open. FILEHANDLE may be an expression whose value
gives the real filehandle name. (Note that this function actually
reads a character and then ungetc()s it, so it is not very useful in an
-interactive context.) An C<eof> without an argument returns the eof status
-for the last file read. Empty parentheses () may be used to indicate
-the pseudo file formed of the files listed on the command line, i.e.
-C<eof()> is reasonable to use inside a while (<>) loop to detect the end
+interactive context.) Do not read from a terminal file (or call
+C<eof(FILEHANDLE)> on it) after end-of-file is reached. Filetypes such
+as terminals may lose the end-of-file condition if you do.
+
+An C<eof> without an argument uses the last file read as argument.
+Empty parentheses () may be used to indicate
+the pseudofile formed of the files listed on the command line, i.e.
+C<eof()> is reasonable to use inside a while (E<lt>E<gt>) loop to detect the end
of only the last file. Use C<eof(ARGV)> or eof without the parentheses to
-test I<EACH> file in a while (<>) loop. Examples:
+test I<EACH> file in a while (E<lt>E<gt>) loop. Examples:
+
+ # reset line numbering on each input file
+ while (<>) {
+ print "$.\t$_";
+ close(ARGV) if (eof); # Not eof().
+ }
# insert dashes just before last line of last file
while (<>) {
if (eof()) {
print "--------------\n";
+ close(ARGV); # close or break; is needed if we
+ # are reading from the terminal
}
print;
}
- # reset line numbering on each input file
- while (<>) {
- print "$.\t$_";
- if (eof) { # Not eof().
- close(ARGV);
- }
- }
-
Practical hint: you almost never need to use C<eof> in Perl, because the
-input operators return undef when they run out of data.
+input operators return undef when they run out of data.
=item eval EXPR
any, may be omitted from the expression.
Note that, since eval() traps otherwise-fatal errors, it is useful for
-determining whether a particular feature (such as dbmopen() or symlink())
+determining whether a particular feature (such as socket() or symlink())
is implemented. It is also Perl's exception trapping mechanism, where
the die operator is used to raise exceptions.
likewise behave in the same way: they run the code <$x>, which does
nothing at all. (Case 4 is preferred for purely visual reasons.) Case 5
is a place where normally you I<WOULD> like to use double quotes, except
-that in particular situation, you can just use symbolic references
+that in that particular situation, you can just use symbolic references
instead, as in case 6.
=item exec LIST
metacharacters. If there are any, the entire argument is passed to
C</bin/sh -c> for parsing. If there are none, the argument is split
into words and passed directly to execvp(), which is more efficient.
-Note: exec() (and system(0) do not flush your output buffer, so you may
+Note: exec() and system() do not flush your output buffer, so you may
need to set C<$|> to avoid lost output. Examples:
exec '/bin/echo', 'Your arguments are: ', @ARGV;
=item flock FILEHANDLE,OPERATION
-Calls flock(2) on FILEHANDLE. See L<flock(2)> for
-definition of OPERATION. Returns TRUE for success, FALSE on failure.
-Will produce a fatal error if used on a machine that doesn't implement
-flock(2). Here's a mailbox appender for BSD systems.
+Calls flock(2) on FILEHANDLE. See L<flock(2)> for definition of
+OPERATION. Returns TRUE for success, FALSE on failure. Will produce a
+fatal error if used on a machine that doesn't implement either flock(2) or
+fcntl(2). The fcntl(2) system call will be automatically used if flock(2)
+is missing from your system. This makes flock() the portable file locking
+strategy, although it will only lock entire files, not records. Note also
+that some versions of flock() cannot lock things over the network; you
+would need to use the more system-specific fcntl() for that.
+
+Here's a mailbox appender for BSD systems.
$LOCK_SH = 1;
$LOCK_EX = 2;
print MBOX $msg,"\n\n";
unlock();
-Note that flock() can't lock things over the network. You need to do
-locking with fcntl() for that.
+See also L<DB_File> for other flock() examples.
=item fork
Does a fork(2) system call. Returns the child pid to the parent process
-and 0 to the child process, or undef if the fork is unsuccessful.
+and 0 to the child process, or C<undef> if the fork is unsuccessful.
Note: unflushed buffers remain unflushed in both processes, which means
you may need to set C<$|> ($AUTOFLUSH in English) or call the
autoflush() FileHandle method to avoid duplicate output.
If you fork() without ever waiting on your children, you will accumulate
zombies:
- $SIG{'CHLD'} = sub { wait };
+ $SIG{CHLD} = sub { wait };
There's also the double-fork trick (error checking on
fork() returns omitted);
exec "what you really wanna do";
die "no exec";
# ... or ...
- some_perl_code_here;
+ ## (some_perl_code_here)
exit 0;
}
exit 0;
}
waitpid($pid,0);
+See also L<perlipc> for more examples of forking and reaping
+moribund children.
+
+=item format
+
+Declare a picture format with use by the write() function. For
+example:
+
+ format Something =
+ Test: @<<<<<<<< @||||| @>>>>>
+ $str, $%, '$' . int($num)
+ .
+
+ $str = "widget";
+ $num = $cost/$quantiy;
+ $~ = 'Something';
+ write;
+
+See L<perlform> for many details and examples.
+
=item formline PICTURE, LIST
-This is an internal function used by formats, though you may call it
+This is an internal function used by C<format>s, though you may call it
too. It formats (see L<perlform>) a list of values according to the
contents of PICTURE, placing the output into the format output
-accumulator, C<$^A>. Eventually, when a write() is done, the contents of
+accumulator, C<$^A> (or $ACCUMULATOR in English).
+Eventually, when a write() is done, the contents of
C<$^A> are written to some filehandle, but you could also read C<$^A>
yourself and then set C<$^A> back to "". Note that a format typically
does one formline() per line of form, but the formline() function itself
-doesn't care how many newlines are embedded in the PICTURE. Be careful
-if you put double quotes around the picture, since an "C<@>" character may
-be taken to mean the beginning of an array name. formline() always
-returns TRUE.
+doesn't care how many newlines are embedded in the PICTURE. This means
+that the C<~> and C<~~> 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 "C<@>"
+character may be taken to mean the beginning of an array name.
+formline() always returns TRUE. See L<perlform> for other examples.
=item getc FILEHANDLE
Returns the next character from the input file attached to FILEHANDLE,
or a null string at end of file. If FILEHANDLE is omitted, reads from STDIN.
+This is not particularly efficient. It cannot be used to get unbuffered
+single-characters, however. For that, try something more like:
+
+ if ($BSD_STYLE) {
+ system "stty cbreak </dev/tty >/dev/tty 2>&1";
+ }
+ else {
+ system "stty", '-icanon', 'eol', "\001";
+ }
+
+ $key = getc(STDIN);
+
+ if ($BSD_STYLE) {
+ system "stty -cbreak </dev/tty >/dev/tty 2>&1";
+ }
+ else {
+ system "stty", 'icanon', 'eol', '^@'; # ascii null
+ }
+ print "\n";
+
+Determination of whether to whether $BSD_STYLE should be set
+is left as an exercise to the reader.
+
+See also the C<Term::ReadKey> module from your nearest CPAN site;
+details on CPAN can be found on L<perlmod/CPAN>
=item getlogin
Returns the current login from F</etc/utmp>, if any. If null, use
-getpwuid().
+getpwuid().
$login = getlogin || (getpwuid($<))[0] || "Kilroy";
+Do not consider getlogin() for authentication: it is not as
+secure as getpwuid().
+
=item getpeername SOCKET
Returns the packed sockaddr address of other end of the SOCKET connection.
- # An internet sockaddr
- $sockaddr = 'S n a4 x8';
- $hersockaddr = getpeername(S);
- ($family, $port, $heraddr) = unpack($sockaddr,$hersockaddr);
+ use Socket;
+ $hersockaddr = getpeername(SOCK);
+ ($port, $iaddr) = unpack_sockaddr_in($hersockaddr);
+ $herhostname = gethostbyaddr($iaddr, AF_INET);
+ $herstraddr = inet_ntoa($iaddr);
=item getpgrp PID
Returns the current process group for the specified PID, 0 for the
-current process. Will produce a fatal error if used on a machine that
+current process. Will raise an exception if used on a machine that
doesn't implement getpgrp(2). If PID is omitted, returns process
group of current process.
=item getpriority WHICH,WHO
-Returns the current priority for a process, a process group, or a
-user. (See L<getpriority(2)>.) Will produce a fatal error if used on a
+Returns the current priority for a process, a process group, or a user.
+(See L<getpriority(2)>.) Will raise a fatal exception if used on a
machine that doesn't implement getpriority(2).
=item getpwnam NAME
Returns the packed sockaddr address of this end of the SOCKET connection.
- # An internet sockaddr
- $sockaddr = 'S n a4 x8';
- $mysockaddr = getsockname(S);
- ($family, $port, $myaddr) =
- unpack($sockaddr,$mysockaddr);
+ use Socket;
+ $mysockaddr = getsockname(SOCK);
+ ($port, $myaddr) = unpack_sockaddr_in($mysockaddr);
=item getsockopt SOCKET,LEVEL,OPTNAME
Returns the value of EXPR with filename expansions such as a shell
would do. This is the internal function implementing the <*.*>
-operator.
+operator, except it's easier to use.
=item gmtime EXPR
Converts a time as returned by the time function to a 9-element array
-with the time analyzed for the Greenwich timezone. Typically used as
-follows:
+with the time localized for the standard Greenwich timezone.
+Typically used as follows:
($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
=item goto LABEL
+=item goto EXPR
+
=item goto &NAME
The goto-LABEL form finds the statement labeled with LABEL and resumes
construct such as last or die. The author of Perl has never felt the
need to use this form of goto (in Perl, that is--C is another matter).
+The goto-EXPR form expects a label name, whose scope will be resolved
+dynamically. This allows for computed gotos per FORTRAN, but isn't
+necessarily recommended if you're optimizing for maintainability:
+
+ goto ("FOO", "BAR", "GLARCH")[$i];
+
The goto-&NAME form is highly magical, and substitutes a call to the
named subroutine for the currently running subroutine. This is used by
AUTOLOAD subroutines that wish to load another subroutine and then
=item hex EXPR
-Returns the decimal value of EXPR interpreted as an hex string. (To
-interpret strings that might start with 0 or 0x see oct().) If EXPR is
-omitted, uses $_.
+Interprets EXPR as a hex string and returns the corresponding decimal
+value. (To convert strings that might start with 0 or 0x see
+oct().) If EXPR is omitted, uses $_.
=item import
There is no built-in import() function. It is merely an ordinary
-method subroutine defined (or inherited) by modules that wish to export
+method (subroutine) defined (or inherited) by modules that wish to export
names to another module. The use() function calls the import() method
-for the package used. See also L</use> below and L<perlmod>.
+for the package used. See also L</use>, L<perlmod>, and L<Exporter>.
=item index STR,SUBSTR,POSITION
=item index STR,SUBSTR
-Returns the position of the first occurrence of SUBSTR in STR at or
-after POSITION. If POSITION is omitted, starts searching from the
-beginning of the string. The return value is based at 0, or whatever
-you've set the $[ variable to. If the substring is not found, returns
+Returns the position of the first occurrence of SUBSTR in STR at or after
+POSITION. If POSITION is omitted, starts searching from the beginning of
+the string. The return value is based at 0 (or whatever you've set the $[
+variable to--but don't do that). If the substring is not found, returns
one less than the base, ordinarily -1.
=item int EXPR
Implements the ioctl(2) function. You'll probably have to say
- require "ioctl.ph"; # probably /usr/local/lib/perl/ioctl.ph
+ require "ioctl.ph"; # probably in /usr/local/lib/perl/ioctl.ph
-first to get the correct function definitions. If ioctl.ph doesn't
+first to get the correct function definitions. If F<ioctl.ph> doesn't
exist or doesn't have the correct definitions you'll have to roll your
-own, based on your C header files such as <sys/ioctl.h>. (There is a
-Perl script called B<h2ph> that comes with the Perl kit which may help you
-in this.) SCALAR will be read and/or written depending on the
-FUNCTION--a pointer to the string value of SCALAR will be passed as the
-third argument of the actual ioctl call. (If SCALAR has no string
-value but does have a numeric value, that value will be passed rather
-than a pointer to the string value. To guarantee this to be TRUE, add
-a 0 to the scalar before using it.) The pack() and unpack() functions
-are useful for manipulating the values of structures used by ioctl().
-The following example sets the erase character to DEL.
+own, based on your C header files such as F<E<lt>sys/ioctl.hE<gt>>.
+(There is a Perl script called B<h2ph> that comes with the Perl kit which
+may help you in 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 call. (If SCALAR
+has no string value but does have a numeric value, that value will be
+passed rather than a pointer to the string value. To guarantee this to be
+TRUE, add a 0 to the scalar before using it.) The pack() and unpack()
+functions are useful for manipulating the values of structures used by
+ioctl(). The following example sets the erase character to DEL.
require 'ioctl.ph';
+ $getp = &TIOCGETP;
+ die "NO TIOCGETP" if $@ || !$getp;
$sgttyb_t = "ccccs"; # 4 chars and a short
- if (ioctl(STDIN,$TIOCGETP,$sgttyb)) {
+ if (ioctl(STDIN,$getp,$sgttyb)) {
@ary = unpack($sgttyb_t,$sgttyb);
$ary[2] = 127;
$sgttyb = pack($sgttyb_t,@ary);
- ioctl(STDIN,$TIOCSETP,$sgttyb)
+ ioctl(STDIN,&TIOCSETP,$sgttyb)
|| die "Can't ioctl: $!";
}
print $key, '=', $ENV{$key}, "\n";
}
+To sort an array by value, you'll need to use a C<sort{}>
+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;
+ }
+
=item kill LIST
-Sends a signal to a list of processes. The first element of the list
-must be the signal to send. Returns the number of processes
-successfully signaled.
+Sends a signal to a list of processes. The first element of
+the list must be the signal to send. Returns the number of
+processes successfully signaled.
$cnt = kill 1, $child1, $child2;
kill 9, @goners;
-Unlike in the shell, in Perl
-if the I<SIGNAL> is negative, it kills process groups instead of processes.
-(On System V, a negative I<PROCESS> number will also kill process
-groups, but that's not portable.) That means you usually want to use
-positive not negative signals. You may also use a signal name in quotes.
+Unlike in the shell, in Perl if the I<SIGNAL> is negative, it kills
+process groups instead of processes. (On System V, a negative I<PROCESS>
+number will also kill process groups, but that's not portable.) That
+means you usually want to use positive not negative signals. You may also
+use a signal name in quotes. See L<perlipc/"Signals"> for details.
=item last LABEL
omitted, the command refers to the innermost enclosing loop. The
C<continue> block, if any, is not executed:
- line: while (<STDIN>) {
- last line if /^$/; # exit when done with header
+ LINE: while (<STDIN>) {
+ last LINE if /^$/; # exit when done with header
...
}
=item lc EXPR
Returns an lowercased version of EXPR. This is the internal function
-implementing the \L escape in double-quoted strings.
+implementing the \L escape in double-quoted strings.
+Should respect any POSIX setlocale() settings.
=item lcfirst EXPR
Returns the value of EXPR with the first character lowercased. This is
the internal function implementing the \l escape in double-quoted strings.
+Should respect any POSIX setlocale() settings.
=item length EXPR
=item listen SOCKET,QUEUESIZE
Does the same thing that the listen system call does. Returns TRUE if
-it succeeded, FALSE otherwise. See example in L<perlipc>.
+it succeeded, FALSE otherwise. See example in L<perlipc/"Sockets: Client/Server Communication">.
=item local EXPR
-In general, you should be using "my" instead of "local", because it's
-faster and safer. Format variables have to use "local" though, as
-do any other variables whose local value must be visible to called
-subroutines. This is known as dynamic scoping. Lexical scoping is
-done with "my", which works more like C's auto declarations.
-
A local modifies the listed variables to be local to the enclosing block,
-subroutine, eval or "do". If more than one value is listed, the list
-must be placed in parens. All the listed elements must be legal
-lvalues. This operator works by saving the current values of those
-variables in LIST on a hidden stack and restoring them upon exiting the
-block, subroutine or eval. This means that called subroutines can also
-reference the local variable, but not the global one. The LIST may be
-assigned to if desired, which allows you to initialize your local
-variables. (If no initializer is given for a particular variable, it
-is created with an undefined value.) Commonly this is used to name the
-parameters to a subroutine. Examples:
-
- sub RANGEVAL {
- local($min, $max, $thunk) = @_;
- local $result = '';
- local $i;
-
- # Presumably $thunk makes reference to $i
-
- for ($i = $min; $i < $max; $i++) {
- $result .= eval $thunk;
- }
-
- $result;
- }
-
+subroutine, C<eval{}> or C<do>. If more than one value is listed, the
+list must be placed in parens. See L<perlsub/"Temporary Values via
+local()"> for details.
- if ($sw eq '-v') {
- # init local array with global array
- local @ARGV = @ARGV;
- unshift(@ARGV,'echo');
- system @ARGV;
- }
- # @ARGV restored
-
-
- # temporarily add to digits associative array
- if ($base12) {
- # (NOTE: not claiming this is efficient!)
- local(%digits) = (%digits,'t',10,'e',11);
- parse_num();
- }
-
-Note that local() is a run-time command, and so gets executed every
-time through a loop. In Perl 4 it used up more stack storage each
-time until the loop was exited. Perl 5 reclaims the space each time
-through, but it's still more efficient to declare your variables
-outside the loop.
-
-When you assign to a localized EXPR, the local doesn't change whether
-EXPR is viewed as a scalar or an array. So
-
- local($foo) = <STDIN>;
- local @FOO = <STDIN>;
-
-both supply a list context to the righthand side, while
-
- local $foo = <STDIN>;
-
-supplies a scalar context.
+But you really probably want to be using my() instead, because local() isn't
+what most people think of as "local"). See L<perlsub/"Private Variables
+via my()"> for details.
=item localtime EXPR
$now_string = localtime; # e.g. "Thu Oct 13 04:54:34 1994"
-See also L<perlmod/timelocal> and the strftime(3) function available
-via the POSIX modulie.
+Also see the F<timelocal.pl> library, and the strftime(3) function available
+via the POSIX module.
=item log EXPR
translates a list of numbers to the corresponding characters. And
- %hash = map {&key($_), $_} @array;
+ %hash = map { getkey($_) => $_ } @array;
is just a funny way to write
%hash = ();
foreach $_ (@array) {
- $hash{&key($_)} = $_;
+ $hash{getkey($_)} = $_;
}
=item mkdir FILENAME,MODE
=item msgctl ID,CMD,ARG
-Calls the System V IPC function msgctl. If CMD is &IPC_STAT, then ARG
+Calls the System V IPC function msgctl(2). If CMD is &IPC_STAT, then ARG
must be a variable which will hold the returned msqid_ds structure.
Returns like ioctl: the undefined value for error, "0 but true" for
zero, or the actual return value otherwise.
=item msgget KEY,FLAGS
-Calls the System V IPC function msgget. Returns the message queue id,
+Calls the System V IPC function msgget(2). Returns the message queue id,
or the undefined value if there is an error.
=item msgsnd ID,MSG,FLAGS
Calls the System V IPC function msgsnd to send the message MSG to the
message queue ID. MSG must begin with the long integer message type,
-which may be created with C<pack("L", $type)>. Returns TRUE if
+which may be created with C<pack("l", $type)>. Returns TRUE if
successful, or FALSE if there is an error.
=item msgrcv ID,VAR,SIZE,TYPE,FLAGS
=item my EXPR
A "my" declares the listed variables to be local (lexically) to the
-enclosing block, subroutine, eval or "do". If more than one value is
-listed, the list must be placed in parens. All the listed elements
-must be legal lvalues. Only alphanumeric identifiers may be lexically
-scoped--magical builtins like $/ must be localized with "local"
-instead. In particular, you're not allowed to say
-
- my $_; # Illegal.
-
-Unlike the "local" declaration, variables declared with "my"
-are totally hidden from the outside world, including any called
-subroutines (even if it's the same subroutine--every call gets its own
-copy).
-
-(An eval(), however, can see the lexical variables of the scope it is
-being evaluated in so long as the names aren't hidden by declarations within
-the eval() itself. See L<perlref>.)
-
-The EXPR may be assigned to if desired, which allows you to initialize
-your variables. (If no initializer is given for a particular
-variable, it is created with an undefined value.) Commonly this is
-used to name the parameters to a subroutine. Examples:
-
- sub RANGEVAL {
- my($min, $max, $thunk) = @_;
- my $result = '';
- my $i;
-
- # Presumably $thunk makes reference to $i
-
- for ($i = $min; $i < $max; $i++) {
- $result .= eval $thunk;
- }
-
- $result;
- }
-
-
- if ($sw eq '-v') {
- # init my array with global array
- my @ARGV = @ARGV;
- unshift(@ARGV,'echo');
- system @ARGV;
- }
- # Outer @ARGV again visible
-
-When you assign to the EXPR, the "my" doesn't change whether
-EXPR is viewed as a scalar or an array. So
-
- my($foo) = <STDIN>;
- my @FOO = <STDIN>;
-
-both supply a list context to the righthand side, while
-
- my $foo = <STDIN>;
-
-supplies a scalar context.
-
-Some users may wish to encourage the use of lexically scoped variables.
-As an aid to catching implicit references to package variables,
-if you say
-
- use strict 'vars';
-
-then any variable reference from there to the end of the enclosing
-block must either refer to a lexical variable, or must be fully
-qualified with the package name. A compilation error results
-otherwise. An inner block may countermand this with S<"no strict 'vars'">.
+enclosing block, subroutine, C<eval>, or C<do/require/use>'d file. If
+more than one value is listed, the list must be placed in parens. See
+L<perlsub/"Private Variables via my()"> for details.
=item next LABEL
The C<next> command is like the C<continue> statement in C; it starts
the next iteration of the loop:
- line: while (<STDIN>) {
- next line if /^#/; # discard comments
+ LINE: while (<STDIN>) {
+ next LINE if /^#/; # discard comments
...
}
=item oct EXPR
-Returns the decimal value of EXPR interpreted as an octal string. (If
-EXPR happens to start off with 0x, interprets it as a hex string
-instead.) The following will handle decimal, octal, and hex in the
-standard Perl or C notation:
+Interprets EXPR as an octal string and returns the corresponding
+decimal value. (If EXPR happens to start off with 0x, interprets it as
+a hex string instead.) The following will handle decimal, octal, and
+hex in the standard Perl or C notation:
$val = oct($val) if $val =~ /^0/;
=item open FILEHANDLE
Opens the file whose filename is given by EXPR, and associates it with
-FILEHANDLE. If FILEHANDLE is an expression, its value is used as the
-name of the real filehandle wanted. If EXPR is omitted, the scalar
-variable of the same name as the FILEHANDLE contains the filename. If
-the filename begins with "<" or nothing, the file is opened for input.
-If the filename begins with ">", the file is opened for output. If the
-filename begins with ">>", the file is opened for appending. (You can
-put a '+' in front of the '>' or '<' to indicate that you want both
-read and write access to the file.) If the filename begins with "|",
-the filename is interpreted as a command to which output is to be
-piped, and if the filename ends with a "|", the filename is interpreted
-as command which pipes input to us. (You may not have a command that
-pipes both in and out.) Opening '-' opens STDIN and opening '>-'
-opens STDOUT. Open returns non-zero upon success, the undefined
-value otherwise. If the open involved a pipe, the return value happens
-to be the pid of the subprocess. Examples:
+FILEHANDLE. If FILEHANDLE is an expression, its value is used as the name
+of the real filehandle wanted. If EXPR is omitted, the scalar variable of
+the same name as the FILEHANDLE contains the filename. If the filename
+begins with "<" or nothing, the file is opened for input. If the filename
+begins with ">", the file is opened for output. If the filename begins
+with ">>", the file is opened for appending. You can put a '+' in front
+of the '>' or '<' to indicate that you want both read and write access to
+the file; thus '+<' is usually preferred for read/write updates--the '+>'
+mode would clobber the file first. These correspond to the fopen(3) modes
+of 'r', 'r+', 'w', 'w+', 'a', and 'a+'.
+
+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 See L<perlipc/"Using open() for IPC">
+for more examples of this. as command which pipes input to us. (You may
+not have a raw open() to a command that pipes both in I<and> out, but see L<open2>,
+L<open3>, and L<perlipc/"Bidirectional Communication"> for alternatives.)
+
+Opening '-' opens STDIN and opening '>-' opens STDOUT. Open returns
+non-zero upon success, the undefined value otherwise. If the open
+involved a pipe, the return value happens to be the pid of the
+subprocess.
+
+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 L</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 C<binmode>. The rest need it.
+
+Examples:
$ARTICLE = 100;
open ARTICLE or die "Can't find article $ARTICLE: $!\n";
open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
- open(article, "caesar <$article |"); # decrypt article
+ open(DBASE, '+<dbase.mine'); # open for update
+
+ open(ARTICLE, "caesar <$article |"); # decrypt article
- open(extract, "|sort >/tmp/Tmp$$"); # $$ is our process id
+ open(EXTRACT, "|sort >/tmp/Tmp$$"); # $$ is our process id
# process argument list of files along with any includes
name of a filehandle (or file descriptor, if numeric) which is to be
duped and opened. You may use & after >, >>, <, +>, +>> and +<. The
mode you specify should match the mode of the original filehandle.
+(Duping a filehandle does not take into acount any existing contents of
+stdio buffers.)
Here is a script that saves, redirects, and restores STDOUT and
STDERR:
If you specify "<&=N", where N is a number, then Perl will do an
-equivalent of C's fdopen() of that file descriptor. For example:
+equivalent of C's fdopen() of that file descriptor; this is more
+parsimonious of file descriptors. For example:
open(FILEHANDLE, "<&=$fd")
the new STDOUT or STDIN. Typically this is used like the normal
piped open when you want to exercise more control over just how the
pipe command gets executed, such as when you are running setuid, and
-don't want to have to scan shell commands for metacharacters. The
-following pairs are more or less equivalent:
+don't want to have to scan shell commands for metacharacters.
+The following pairs are more or less equivalent:
open(FOO, "|tr '[a-z]' '[A-Z]'");
open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]';
open(FOO, "cat -n '$file'|");
open(FOO, "-|") || exec 'cat', '-n', $file;
+See L<perlipc/"Safe Pipe Opens"> for more examples of this.
+
Explicitly closing any piped filehandle causes the parent process to
wait for the child to finish, and returns the status value in $?.
Note: on any operation which may do a fork, unflushed buffers remain
unflushed in both processes, which means you may need to set $| to
avoid duplicate output.
+Using the FileHandle constructor from the FileHandle package,
+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.
+ }
+
The filename that is passed to open will have leading and trailing
whitespace deleted. In order to open a file with arbitrary weird
characters in it, it's necessary to protect any leading and trailing
whitespace thusly:
- $file =~ s#^(\s)#./$1#;
- open(FOO, "< $file\0");
+ $file =~ s#^(\s)#./$1#;
+ open(FOO, "< $file\0");
+
+If you want a "real" C open() (see L<open(2)> on your system), 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 L</seek()> for some details about mixing reading and writing.
=item opendir DIRHANDLE,EXPR
The same template may generally also be used in the unpack function.
+=item package NAMESPACE
+
+Declares the compilation unit as being in the given namespace. The scope
+of the package declaration is from the declaration itself through the end of
+the enclosing block (the same scope as the local() operator). All further
+unqualified dynamic identifiers will be in this namespace. A package
+statement only affects dynamic variables--including those you've used
+local() on--but I<not> lexical variables created with my(). Typically it
+would be the first declaration in a file to be included by the C<require>
+or C<use> operator. You can switch into a package in more than one place;
+it merely influences which symbol table is used by the compiler for the
+rest of that block. You can refer to variables and filehandles in other
+packages by prefixing the identifier with the package name and a double
+colon: C<$Package::Variable>. If the package name is null, the C<main>
+package as assumed. That is, C<$::sail> is equivalent to C<$main::sail>.
+
+See L<perlmod/"Packages"> for more information about packages, modules,
+and classes. See L<perlsub> for other scoping issues.
+
=item pipe READHANDLE,WRITEHANDLE
Opens a pair of connected pipes like the corresponding system call.
stdio buffering, so you may need to set $| to flush your WRITEHANDLE
after each command, depending on the application.
+See L<open2>, L<open3>, and L<perlipc/"Bidirectional Communication">
+for examples of such things.
+
=item pop ARRAY
Pops and returns the last value of the array, shortening the array by
$tmp = $ARRAY[$#ARRAY--];
If there are no elements in the array, returns the undefined value.
+If ARRAY is omitted, pops the
+@ARGV array in the main program, and the @_ array in subroutines, just
+like shift().
=item pos SCALAR
-Returns the offset of where the last m//g search left off for the variable
+Returns the offset of where the last C<m//g> search left off for the variable
in question. May be modified to change that offset.
=item print FILEHANDLE LIST
=item print
-Prints a string or a comma-separated list of strings. Returns non-zero
+Prints a string or a comma-separated list of strings. Returns TRUE
if successful. FILEHANDLE may be a scalar variable name, in which case
-the variable contains the name of the filehandle, thus introducing one
+the variable contains the name of or a reference to the filehandle, thus introducing one
level of indirection. (NOTE: If FILEHANDLE is a variable and the next
token is a term, it may be misinterpreted as an operator unless you
interpose a + or put parens around the arguments.) If FILEHANDLE is
omitted, prints by default to standard output (or to the last selected
-output channel--see select()). If LIST is also omitted, prints $_ to
+output channel--see L</select>). If LIST is also omitted, prints $_ to
STDOUT. To set the default output channel to something other than
STDOUT use the select operation. Note that, because print takes a
LIST, anything in the LIST is evaluated in a list context, and any
parenthesis to terminate the arguments to the print--interpose a + or
put parens around all the arguments.
+Note that if you're storing FILEHANDLES in an array or other expression,
+you will have to use a block returning its value instead:
+
+ print { $files[$i] } "stuff\n";
+ print { $OK ? STDOUT : STDERR } "stuff\n";
+
=item printf FILEHANDLE LIST
=item printf LIST
Equivalent to a "print FILEHANDLE sprintf(LIST)". The first argument
of the list will be interpreted as the printf format.
+=item prototype FUNCTION
+
+Returns the prototype of a function as a string (or C<undef> if the
+function has no prototype). FUNCTION is a reference to the the
+function whose prototype you want to retrieve.
+
=item push ARRAY,LIST
Treats ARRAY as a stack, and pushes the values of LIST
directory. If there are no more entries, returns an undefined value in
a scalar context or a null list in a list context.
+If you're planning to filetest the return values out of a readdir(), you'd
+better prepend the directory in question. Otherwise, since we didn't
+chdir() there, it would have been testing the wrong file.
+
+ opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!";
+ @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
+ closedir DIR;
+
=item readlink EXPR
Returns the value of a symbolic link, if symbolic links are
Actually does a C recvfrom(), so that it can returns the address of the
sender. Returns the undefined value if there's an error. SCALAR will
be grown or shrunk to the length actually read. Takes the same flags
-as the system call of the same name.
+as the system call of the same name.
+See L<perlipc/"UDP: Message Passing"> for examples.
=item redo LABEL
# a simpleminded Pascal comment stripper
# (warning: assumes no { or } in strings)
- line: while (<STDIN>) {
+ LINE: while (<STDIN>) {
while (s|({.*}.*){.*}|$1 |) {}
s|{.*}| |;
if (s|{.*| |) {
while (<STDIN>) {
if (/}/) { # end of comment?
s|^|$front{|;
- redo line;
+ redo LINE;
}
}
}
otherwise. But it's better just to put the "C<1;>", in case you add more
statements.
-If EXPR is a bare word, the require assumes a "F<.pm>" extension for you,
+If EXPR is a bare word, the require assumes a "F<.pm>" extension and
+replaces "F<::>" with "F</>" in the filename for you,
to make it easy to load standard modules. This form of loading of
modules does not risk altering your namespace.
-For a yet more powerful import facility, see the L</use()> below, and
-also L<perlmod>.
+For a yet-more-powerful import facility, see L</use> and
+L<perlmod>.
=item reset EXPR
Resetting "A-Z" is not recommended since you'll wipe out your
ARGV and ENV arrays. Only resets package variables--lexical variables
are unaffected, but they clean themselves up on scope exit anyway,
-so anymore you probably want to use them instead. See L</my>.
+so you'll probably want to use them instead. See L</my>.
=item return LIST
Returns from a subroutine or eval with the value specified. (Note that
-in the absence of a return a subroutine or eval will automatically
+in the absence of a return a subroutine or eval() will automatically
return the value of the last expression evaluated.)
=item reverse LIST
In a list context, returns a list value consisting of the elements
of LIST in the opposite order. In a scalar context, returns a string
value consisting of the bytes of the first element of LIST in the
-opposite order.
+opposite order.
+
+ print reverse <>; # line tac
+
+ undef $/;
+ print scalar reverse scalar <>; # byte tac
=item rewinddir DIRHANDLE
=item scalar EXPR
Forces EXPR to be interpreted in a scalar context and returns the value
-of EXPR.
+of EXPR.
+
+ @counts = ( scalar @a, scalar @b, scalar @c );
+
+There is no equivalent operator to force an expression to
+be interpolated in a list context because it's in practice never
+needed. If you really wanted to do so, however, you could use
+the construction C<@{[ (some expression) ]}>, but usually a simple
+C<(some expression)> suffices.
=item seek FILEHANDLE,POSITION,WHENCE
of the filehandle. The values for WHENCE are 0 to set the file pointer to
POSITION, 1 to set the it to current plus POSITION, and 2 to set it to EOF
plus offset. You may use the values SEEK_SET, SEEK_CUR, and SEEK_END for
-this is usin the POSIX module. Returns 1 upon success, 0 otherwise.
+this from POSIX module. Returns 1 upon success, 0 otherwise.
+
+On some systems you have to do a seek whenever you switch between reading
+and writing. Amongst other things, this may have the effect of calling
+stdio's clearerr(3). A "whence" of 1 (SEEK_CUR) is useful for not moving
+the file pointer:
+
+ seek(TEST,0,1);
+
+This is also useful for applications emulating C<tail -f>. Once you hit
+EOF on your read, and then sleep for a while, you might have to stick in a
+seek() to reset things. First the simple trick listed above to clear the
+filepointer. The seek() doesn't change the current position, but it
+I<does> clear the end-of-file condition on the handle, so that the next
+C<E<lt>FILEE<gt>> makes Perl try again to read something. Hopefully.
+
+If that doesn't work (some stdios are particularly cantankerous), 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);
+ }
=item seekdir DIRHANDLE,POS
$oldfh = select(STDERR); $| = 1; select($oldfh);
-With Perl 5, filehandles are objects with methods, and the last example
-is preferably written
+Some programmers may prefer to think of filehandles as objects with
+methods, preferring to write the last example as:
use FileHandle;
STDERR->autoflush(1);
=item select RBITS,WBITS,EBITS,TIMEOUT
-This calls the select system(2) call with the bitmasks specified, which
+This calls the select(2) system call with the bitmasks specified, which
can be constructed using fileno() and vec(), along these lines:
$rin = $win = $ein = '';
}
$bits;
}
- $rin = &fhbits('STDIN TTY SOCK');
+ $rin = fhbits('STDIN TTY SOCK');
The usual idiom is:
($nfound,$timeleft) =
select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
-or to block until something becomes ready:
+or to block until something becomes ready just do this
$nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
+Most systems do not both to return anything useful in $timeleft, so
+calling select() in a scalar context just returns $nfound.
+
Any of the bitmasks can also be undef. The timeout, if specified, is
in seconds, which may be fractional. Note: not all implementations are
capable of returning the $timeleft. If not, they always return
$timeleft equal to the supplied $timeout.
-You can effect a 250 microsecond sleep this way:
+You can effect a 250-millisecond sleep this way:
select(undef, undef, undef, 0.25);
+B<WARNING>: Do not attempt to mix buffered I/O (like read() or <FH>)
+with select(). You have to use sysread() instead.
=item semctl ID,SEMNUM,CMD,ARG
destination to send TO, in which case it does a C sendto(). Returns
the number of characters sent, or the undefined value if there is an
error.
+See L<perlipc/"UDP: Message Passing"> for examples.
=item setpgrp PID,PGRP
=item setpriority WHICH,WHO,PRIORITY
Sets the current priority for a process, a process group, or a user.
-(See Lsetpriority(2)>.) Will produce a fatal error if used on a machine
+(See setpriority(2).) Will produce a fatal error if used on a machine
that doesn't implement setpriority(2).
=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
you requested, depending on how it counts seconds. Most modern systems
always sleep the full amount.
+For delays of finer granularity than one second, you may use Perl's
+syscall() interface to access setitimer(2) if your system supports it,
+or else see L</select()> below.
+
=item socket SOCKET,DOMAIN,TYPE,PROTOCOL
Opens a socket of the specified kind and attaches it to filehandle
SOCKET. DOMAIN, TYPE and PROTOCOL are specified the same as for the
system call of the same name. You should "use Socket;" first to get
-the proper definitions imported. See the example in L<perlipc>.
+the proper definitions imported. See the example in L<perlipc/"Sockets: Client/Server Communication">.
=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
SUBNAME, you can provide a BLOCK as an anonymous, in-line sort
subroutine.
-In the interests of efficiency the normal calling code for subroutines
-is bypassed, with the following effects: the subroutine may not be a
-recursive subroutine, and the two elements to be compared are passed
-into the subroutine not via @_ but as $a and $b (see example below).
-They are passed by reference, so don't modify $a and $b.
+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 the package global variables $a and
+$b (see example below). They are passed by reference, so don't
+modify $a and $b. And don't try to declare them as lexicals either.
Examples:
# same thing, but with explicit sort routine
@articles = sort {$a cmp $b} @files;
+ # now case-insensitively
+ @articles = sort { uc($a) cmp uc($b)} @files;
+
# same thing in reversed order
@articles = sort {$b cmp $a} @files;
}
@sortedclass = sort byage @class;
+ # this sorts the %age associative arrays by value
+ # instead of key using an inline function
+ @eldest = sort { $age{$b} <=> $age{$a} } keys %age;
+
sub backwards { $b cmp $a; }
@harry = ('dog','cat','x','Cain','Abel');
@george = ('gone','chased','yz','Punished','Axed');
print sort @george, 'to', @harry;
# prints AbelAxedCainPunishedcatchaseddoggonetoxyz
+ # inefficiently sort by descending numeric compare using
+ # the first integer after the first = sign, or the
+ # whole record case-insensitively otherwise
+
+ @new = sort {
+ ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
+ ||
+ uc($a) cmp uc($b)
+ } @old;
+
+ # same thing, but much more efficiently;
+ # we'll build auxiliary indices instead
+ # for speed
+ @nums = @caps = ();
+ for (@old) {
+ push @nums, /=(\d+)/;
+ push @caps, uc($_);
+ }
+
+ @new = @old[ sort {
+ $nums[$b] <=> $nums[$a]
+ ||
+ $caps[$a] cmp $caps[$b]
+ } 0..$#old
+ ];
+
+ # same thing using a Schwartzian Transform (no temps)
+ @new = map { $_->[0] }
+ sort { $b->[1] <=> $a->[1]
+ ||
+ $a->[2] cmp $b->[2]
+ } map { [$_, /=(\d+)/, uc($_)] } @old;
+
+If you're and using strict, you I<MUST NOT> declare $a
+and $b as lexicals. They are package globals. That means
+if you're in the C<main> package, it's
+
+ @articles = sort {$main::b <=> $main::a} @files;
+
+or just
+
+ @articles = sort {$::b <=> $::a} @files;
+
+but if you're in the C<FooPack> package, it's
+
+ @articles = sort {$FooPack::b <=> $FooPack::a} @files;
+
=item splice ARRAY,OFFSET,LENGTH,LIST
=item splice ARRAY,OFFSET,LENGTH
value.) The use of implicit split to @_ is deprecated, however.
If EXPR is omitted, splits the $_ string. If PATTERN is also omitted,
-splits on whitespace (C</[ \t\n]+/>). Anything matching PATTERN is taken
-to be a delimiter separating the fields. (Note that the delimiter may
-be longer than one character.) If LIMIT is specified and is not
-negative, splits into no more than that many fields (though it may
-split into fewer). If LIMIT is unspecified, trailing null fields are
-stripped (which potential users of pop() would do well to remember).
-If LIMIT is negative, it is treated as if an arbitrarily large LIMIT
-had been specified.
+splits on whitespace (after skipping any leading whitespace). Anything
+matching PATTERN is taken to be a delimiter separating the fields. (Note
+that the delimiter may be longer than one character.) If LIMIT is
+specified and is not negative, splits into no more than that many fields
+(though it may split into fewer). If LIMIT is unspecified, trailing null
+fields are stripped (which potential users of pop() would do well to
+remember). If LIMIT is negative, it is treated as if an arbitrarily large
+LIMIT had been specified.
A pattern matching the null string (not to be confused with
-a null pattern C<//., which is just one member of the set of patterns
+a null pattern C<//>, which is just one member of the set of patterns
matching a null string) will split the value of EXPR into separate
characters at each point it matches that way. For example:
If the PATTERN contains parentheses, additional array elements are
created from each matching substring in the delimiter.
- split(/([,-])/, "1-10,20");
+ split(/([,-])/, "1-10,20", 3);
produces the list value
(1, '-', 10, ',', 20)
+If you had the entire header of a normal Unix email message in $header,
+you could split it up into fields and their values this way:
+
+ $header =~ s/\n\s+/ /g; # fix continuation lines
+ %hdrs = (UNIX_FROM => split /^(.*?):\s*/m, $header);
+
The pattern C</PATTERN/> may be replaced with an expression to specify
patterns that vary at runtime. (To do runtime compilation only once,
-use C</$variable/o>.) As a special case, specifying a space S<(' ')> will
-split on white space just as split with no arguments does, but leading
-white space does I<NOT> produce a null first field. Thus, split(' ') can
-be used to emulate B<awk>'s default behavior, whereas C<split(/ /)> will
-give you as many null initial fields as there are leading spaces.
+use C</$variable/o>.)
+
+As a special case, specifying a PATTERN of space (C<' '>) will split on
+white space just as split with no arguments does. Thus, split(' ') can
+be used to emulate B<awk>'s default behavior, whereas C<split(/ /)>
+will give you as many null initial fields as there are leading spaces.
+A split on /\s+/ is like a split(' ') except that any leading
+whitespace produces a null first field. A split with no arguments
+really does a C<split(' ', $_)> internally.
Example:
open(passwd, '/etc/passwd');
while (<passwd>) {
- ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(/:/);
+ ($login, $passwd, $uid, $gid, $gcos,
+ $home, $shell) = split(/:/);
...
}
=item sprintf FORMAT,LIST
Returns a string formatted by the usual printf conventions of the C
-language. (The * character for an indirectly specified length is not
+language. See L<sprintf(3)> or L<printf(3)> on your system for details.
+(The * character for an indirectly specified length is not
supported, but you can get the same effect by interpolating a variable
-into the pattern.)
+into the pattern.) Some C libraries' implementations of sprintf() can
+dump core when fed ludicrous arguments.
=item sqrt EXPR
=item srand EXPR
-Sets the random number seed for the C<rand> operator. If EXPR is
-omitted, does C<srand(time)>. Of course, you'd need something much more
-random than that for cryptographic purposes, since it's easy to guess
-the current time. Checksumming the compressed output of rapidly
-changing operating system status programs is the usual method.
-Examples are posted regularly to comp.security.unix.
+Sets the random number seed for the C<rand> operator. If EXPR is omitted,
+uses a semirandom value based on the current time and process ID, among
+other things. Of course, you'd need something much more random than that for
+cryptographic purposes, since it's easy to guess the current time.
+Checksumming the compressed output of rapidly changing operating system
+status programs is the usual method. Examples are posted regularly to
+the comp.security.unix newsgroup.
=item stat FILEHANDLE
$atime,$mtime,$ctime,$blksize,$blocks)
= stat($filename);
+Not all fields are supported on all filesystem types. Here are the
+meaning of the fields:
+
+ 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 numer 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 type!) since the epoch
+ blksize preferred blocksize for file system I/O
+ blocks actual number of blocks allocated
+
+(The epoch was at 00:00 January 1, 1970 GMT.)
+
If stat is passed the special filehandle consisting of an underline, no
stat is done, but the current contents of the stat structure from the
last stat or filetest are returned. Example:
print $file, "\n";
}
+=item sub BLOCK
+
+=item sub NAME
+
+=item sub NAME BLOCK
+
+This is subroutine definition, not a real function I<per se>. With just a
+NAME (and possibly prototypes), it's just a forward declaration. Without
+a NAME, it's an anonymous function declaration, and does actually return a
+value: the CODE ref of the closure you just created. See L<perlsub> and
+L<perlref> for details.
+
=item substr EXPR,OFFSET,LEN
=item substr EXPR,OFFSET
Extracts a substring out of EXPR and returns it. First character is at
offset 0, or whatever you've set $[ to. If OFFSET is negative, starts
that far from the end of the string. If LEN is omitted, returns
-everything to the end of the string. You can use the substr() function
+everything to the end of the string. If LEN is negative, leaves that
+many characters off the end of the string.
+
+You can use the substr() function
as an lvalue, in which case EXPR must be an lvalue. If you assign
something shorter than LEN, the string will shrink, and if you assign
something longer than LEN, the string will grow to accommodate it. To
Note that Perl only supports passing of up to 14 arguments to your system call,
which in practice should usually suffice.
+=item sysopen FILEHANDLE,FILENAME,MODE
+
+=item sysopen FILEHANDLE,FILENAME,MODE,PERMS
+
+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 the real filehandle wanted. This function calls the
+underlying operating system's C<open> function with the parameters
+FILENAME, MODE, PERMS.
+
+The possible values and flag bits of the MODE parameter are
+system-dependent; they are available via the standard module C<Fcntl>.
+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 the C<open> call
+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 C<umask>.
+
=item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
=item sysread FILEHANDLE,SCALAR,LENGTH
Note that argument processing varies depending on the number of
arguments. The return value is the exit status of the program as
returned by the wait() call. To get the actual exit value divide by
-256. See also L</exec>.
+256. See also L</exec>. This is I<NOT> what you want to use to capture
+the output from a command, for that you should merely use backticks, as
+described in L<perlop/"`STRING`">.
=item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
specified FILEHANDLE, using the system call write(2). It bypasses
stdio, so mixing this with prints may cause confusion. Returns the
number of bytes actually written, or undef if there was an error. An
-OFFSET may be specified to place the read data at some other place than
+OFFSET may be specified to get the write data from some other place than
the beginning of the string.
=item tell FILEHANDLE
directory. Has the same caveats about possible directory compaction as
the corresponding system library routine.
-=item tie VARIABLE,PACKAGENAME,LIST
+=item tie VARIABLE,CLASSNAME,LIST
-This function binds a variable to a package that will provide the
+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 enchanted. PACKAGENAME is the name of a package implementing
-objects of correct type. Any additional arguments are passed to the
-"new" method of the package. Typically these are arguments such as
-might be passed to the dbm_open() function of C.
+to be enchanted. CLASSNAME is the name of a class implementing objects
+of correct 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()
+function of C. The object returned by the "new" method is also
+returned by the tie() function, which would be useful if you want to
+access other methods in CLASSNAME.
Note that functions such as keys() and values() may return huge array
-values when used on large DBM files. You may prefer to use the each()
-function to iterate over large DBM files. Example:
+values when used on large objects, like DBM files. You may prefer to
+use the each() function to iterate over such. Example:
# print out history file offsets
- tie(%HIST, NDBM_File, '/usr/lib/news/history', 1, 0);
+ use NDBM_File;
+ tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
while (($key,$val) = each %HIST) {
print $key, ' = ', unpack('L',$val), "\n";
}
untie(%HIST);
-A package implementing an associative array should have the following
+A class implementing an associative array should have the following
methods:
- TIEHASH objectname, LIST
+ TIEHASH classname, LIST
DESTROY this
FETCH this, key
STORE this, key, value
FIRSTKEY this
NEXTKEY this, lastkey
-A package implementing an ordinary array should have the following methods:
+A class implementing an ordinary array should have the following methods:
- TIEARRAY objectname, LIST
+ TIEARRAY classname, LIST
DESTROY this
FETCH this, key
STORE this, key, value
[others TBD]
-A package implementing a scalar should have the following methods:
+A class implementing a scalar should have the following methods:
- TIESCALAR objectname, LIST
+ TIESCALAR classname, LIST
DESTROY this
FETCH this,
STORE this, value
+Unlike dbmopen(), the tie() function will not use or require a module
+for you--you need to do that explicitly yourself. See L<DB_File>
+or the F<Config> module for interesting tie() implementations.
+
+=item tied VARIABLE
+
+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.) Returns the undefined value if VARIABLE isn't tied to a
+package.
+
=item time
-Returns the number of non-leap seconds since 00:00:00 UTC, January 1,
-1970. Suitable for feeding to gmtime() and localtime().
+Returns the number of non-leap seconds since whatever time the system
+considers to be the epoch (that's 00:00:00, January 1, 1904 for MacOS,
+and 00:00:00 UTC, January 1, 1970 for most other systems).
+Suitable for feeding to gmtime() and localtime().
=item times
Returns an uppercased version of EXPR. This is the internal function
implementing the \U escape in double-quoted strings.
+Should respect any POSIX setlocale() settings.
=item ucfirst EXPR
Returns the value of EXPR with the first character uppercased. This is
the internal function implementing the \u escape in double-quoted strings.
+Should respect any POSIX setlocale() settings.
=item umask EXPR
=item use Module
+=item use Module VERSION LIST
+
+=item use VERSION
+
Imports some semantics into the current package from the named module,
generally by aliasing certain subroutine or variable names into your
package. It is exactly equivalent to
BEGIN { require Module; import Module LIST; }
-If you don't want your namespace altered, use require instead.
+except that Module I<must> be a bare word.
+
+If the first argument to C<use> is a number, it is treated as a version
+number instead of a module name. If the version of the Perl interpreter
+is less than VERSION, then an error message is printed and Perl exits
+immediately. This is often useful if you need to check the current
+Perl version before C<use>ing library modules which have changed in
+incompatible ways from older versions of Perl. (We try not to do
+this more than we have to.)
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
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.
+is defined in the Exporter module. See L<Exporter>.
+
+If you don't want your namespace altered, explicitly supply an empty list:
+
+ use Module ();
+
+That is exactly equivalent to
+
+ BEGIN { require Module; }
+
+If the VERSION argument is present between Module and LIST, then the
+C<use> will fail if the C<$VERSION> variable in package Module is
+less than VERSION.
Because this is a wide-open interface, pragmas (compiler directives)
are also implemented this way. Currently implemented pragmas are:
use integer;
+ use diagnostics;
use sigtrap qw(SEGV BUS);
use strict qw(subs vars refs);
use subs qw(afunc blurfl);
effective through the end of the file).
There's a corresponding "no" command that unimports meanings imported
-by use.
+by use, i.e. it calls C<unimport Module LIST> instead of C<import>.
no integer;
no strict 'refs';
associative array. (In a scalar context, returns the number of
values.) The values are returned in an apparently random order, but it
is the same order as either the keys() or each() function would produce
-on the same array. See also keys() and each().
+on the same array. See also keys(), each(), and sort().
=item vec EXPR,OFFSET,BITS
-Treats a string as a vector of unsigned integers, and returns the value
-of the bitfield specified. May also be assigned to. BITS must be a
-power of two from 1 to 32.
+Treats the string in EXPR as a vector of unsigned integers, and
+returns the value of the bitfield specified by OFFSET. BITS specifies
+the number of bits that are reserved for each entry in the bit
+vector. This must be a power of two from 1 to 32. vec() may also be
+assigned to, in which case parens are needed to give the expression
+the correct precedence as in
+
+ vec($image, $max_x * $x + $y, 8) = 3;
Vectors created with vec() can also be manipulated with the logical
operators |, & and ^, which will assume a bit vector operation is
=item warn LIST
Produces a message on STDERR just like die(), but doesn't exit or
-throw an exception.
+on an exception.
=item write FILEHANDLE
=item y///
-The translation operator. See L<perlop/tr///>.
+The translation operator. See L<perlop>.
=back
projects / p5sagit/p5-mst-13.2.git / blobdiff