+
=head1 NAME
perlfunc - Perl builtin functions
=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///
+C<chomp>, C<chop>, C<chr>, C<crypt>, C<hex>, C<index>, C<lc>, C<lcfirst>,
+C<length>, C<oct>, C<ord>, C<pack>, C<q>/STRING/, C<qq>/STRING/, C<reverse>,
+C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y>///
=item Regular expressions and pattern matching
-m//, pos, quotemeta, s///, split, study
+C<m>//, C<pos>, C<quotemeta>, C<s>///, C<split>, C<study>
=item Numeric functions
-abs, atan2, cos, exp, hex, int, log, oct, rand, sin, sqrt,
-srand
+C<abs>, C<atan2>, C<cos>, C<exp>, C<hex>, C<int>, C<log>, C<oct>, C<rand>,
+C<sin>, C<sqrt>, C<srand>
=item Functions for real @ARRAYs
-pop, push, shift, splice, unshift
+C<pop>, C<push>, C<shift>, C<splice>, C<unshift>
=item Functions for list data
-grep, join, map, qw/STRING/, reverse, sort, unpack
+C<grep>, C<join>, C<map>, C<qw>/STRING/, C<reverse>, C<sort>, C<unpack>
=item Functions for real %HASHes
-delete, each, exists, keys, values
+C<delete>, C<each>, C<exists>, C<keys>, C<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, sysseek,
-syswrite, tell, telldir, truncate, warn, write
+C<binmode>, C<close>, C<closedir>, C<dbmclose>, C<dbmopen>, C<die>, C<eof>,
+C<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>,
+C<readdir>, C<rewinddir>, C<seek>, C<seekdir>, C<select>, C<syscall>,
+C<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>, C<truncate>,
+C<warn>, C<write>
=item Functions for fixed length data or records
-pack, read, syscall, sysread, syswrite, unpack, vec
+C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<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
+C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
+C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>, C<readlink>,
+C<rename>, C<rmdir>, C<stat>, C<symlink>, C<umask>, C<unlink>, C<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
+C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>,
+C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>
=item Keywords related to scoping
-caller, import, local, my, package, use
+C<caller>, C<import>, C<local>, C<my>, C<package>, C<use>
=item Miscellaneous functions
-defined, dump, eval, formline, local, my, reset, scalar,
-undef, wantarray
+C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<reset>,
+C<scalar>, C<undef>, C<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
+C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>,
+C<pipe>, C<qx>/STRING/, C<setpgrp>, C<setpriority>, C<sleep>, C<system>,
+C<times>, C<wait>, C<waitpid>
=item Keywords related to perl modules
-do, import, no, package, require, use
+C<do>, C<import>, C<no>, C<package>, C<require>, C<use>
=item Keywords related to classes and object-orientedness
-bless, dbmclose, dbmopen, package, ref, tie, tied, untie, use
+C<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>,
+C<untie>, C<use>
=item Low-level socket functions
-accept, bind, connect, getpeername, getsockname,
-getsockopt, listen, recv, send, setsockopt, shutdown,
-socket, socketpair
+C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
+C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
+C<socket>, C<socketpair>
=item System V interprocess communication functions
-msgctl, msgget, msgrcv, msgsnd, semctl, semget, semop,
-shmctl, shmget, shmread, shmwrite
+C<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<semctl>, C<semget>, C<semop>,
+C<shmctl>, C<shmget>, C<shmread>, C<shmwrite>
=item Fetching user and group info
-endgrent, endhostent, endnetent, endpwent, getgrent,
-getgrgid, getgrnam, getlogin, getpwent, getpwnam,
-getpwuid, setgrent, setpwent
+C<endgrent>, C<endhostent>, C<endnetent>, C<endpwent>, C<getgrent>,
+C<getgrgid>, C<getgrnam>, C<getlogin>, C<getpwent>, C<getpwnam>,
+C<getpwuid>, C<setgrent>, C<setpwent>
=item Fetching network info
-endprotoent, endservent, gethostbyaddr, gethostbyname,
-gethostent, getnetbyaddr, getnetbyname, getnetent,
-getprotobyname, getprotobynumber, getprotoent,
-getservbyname, getservbyport, getservent, sethostent,
-setnetent, setprotoent, setservent
+C<endprotoent>, C<endservent>, C<gethostbyaddr>, C<gethostbyname>,
+C<gethostent>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
+C<getprotobyname>, C<getprotobynumber>, C<getprotoent>,
+C<getservbyname>, C<getservbyport>, C<getservent>, C<sethostent>,
+C<setnetent>, C<setprotoent>, C<setservent>
=item Time-related functions
-gmtime, localtime, time, times
+C<gmtime>, C<localtime>, C<time>, C<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<abs>, C<bless>, C<chomp>, C<chr>, C<exists>, C<formline>, C<glob>,
+C<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<prototype>, C<qx>,
+C<qw>, C<readline>, C<readpipe>, C<ref>, C<sub*>, C<sysopen>, C<tie>,
+C<tied>, C<uc>, C<ucfirst>, C<untie>, C<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
+C<dbmclose>, C<dbmopen>
=back
=over 8
-=item -X FILEHANDLE
+=item I<-X> FILEHANDLE
-=item -X EXPR
+=item I<-X> EXPR
-=item -X
+=item I<-X>
A file test, where X is one of the letters listed below. This unary
operator takes one argument, either a filename or a filehandle, and
Closes the file or pipe associated with the file handle, returning TRUE
only if stdio successfully flushes buffers and closes the system file
-descriptor. If the file handle came from a piped open C<close> will
-additionally return FALSE if one of the other system calls involved
-fails or if the program exits with non-zero status. (If the problem was
-that the program exited non-zero $! will be set to 0.)
-You don't have to close FILEHANDLE if you are immediately
-going to do another open() on it, because open() will close it for you. (See
+descriptor.
+
+You don't have to close FILEHANDLE if you are immediately going to do
+another open() on it, because open() will close it for you. (See
open().) However, an explicit close on an input file resets the line
-counter ($.), while the implicit close done by open() does not. Also,
-closing a pipe will wait for the process executing on the pipe to
-complete, in case you want to look at the output of the pipe
-afterwards. Closing a pipe explicitly also puts the status value of
-the command into C<$?>. Example:
+counter ($.), while the implicit close done by open() does not.
+
+If the file handle came from a piped open C<close> will additionally
+return FALSE if one of the other system calls involved fails or if the
+program exits with non-zero status. (If the only problem was that the
+program exited non-zero $! will be set to 0.) Also, closing a pipe will
+wait for the process executing on the pipe to complete, in case you
+want to look at the output of the pipe afterwards. Closing a pipe
+explicitly also puts the exit status value of the command into C<$?>.
+Example:
- open(OUTPUT, '|sort >foo'); # pipe to sort
+ open(OUTPUT, '|sort >foo') # pipe to sort
+ or die "Can't start sort: $!";
... # print stuff to output
- close OUTPUT; # wait for sort to finish
- open(INPUT, 'foo'); # get sort's results
+ close OUTPUT # wait for sort to finish
+ or warn $! ? "Error closing sort pipe: $!"
+ : "Exit status $? from sort";
+ open(INPUT, 'foo') # get sort's results
+ or die "Can't open 'foo' for input: $!";
FILEHANDLE may be an expression whose value gives the real filehandle name.
See also exit() and warn().
+If LIST is empty and $@ already contains a value (typically from a
+previous eval) that value is reused after appending "\t...propagated".
+This is useful for propagating exceptions:
+
+ eval { ... };
+ die unless $@ =~ /Expected exception/;
+
+If $@ is empty then the string "Died" is used.
+
You can arrange for a callback to be called just before the die() does
its deed, by setting the C<$SIG{__DIE__}> hook. The associated handler
will be called with the error text and can change the error message, if
-it sees fit, by calling die() again. See L<perlvar> for details on
-setting C<%SIG> entries, and eval() for some examples.
+it sees fit, by calling die() again. See L<perlvar/$SIG{expr}> for details on
+setting C<%SIG> entries, and L<"eval BLOCK"> for some examples.
+
+Note that the C<$SIG{__DIE__}> hook is called even inside eval()ed
+blocks/strings. If one wants the hook to do nothing in such
+situations, put
+
+ die @_ if $^S;
+
+as the first line of the handler (see L<perlvar/$^S>).
=item do BLOCK
is just like
- eval `cat stat.pl`;
+ scalar eval `cat stat.pl`;
except that it's more efficient, more concise, keeps track of the
current filename for error messages, and searches all the B<-I>
libraries if the file isn't in the current directory (see also the @INC
-array in L<perlvar/Predefined Names>). It's the same, however, in that it does
+array in L<perlvar/Predefined Names>). It is also different in how
+code evaluated with C<do FILENAME> doesn't see lexicals in the enclosing
+scope like C<eval STRING> does. 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.
=item eval BLOCK
-EXPR is parsed and executed as if it were a little Perl program. It
-is executed in the context of the current Perl program, so that any
+In the first form, the return value of EXPR is parsed and executed as if it
+were a little Perl program. The value of the expression (which is itself
+determined within a scalar context) is first parsed, and if there are no
+errors, executed in the context of the current Perl program, so that any
variable settings or subroutine and format definitions remain afterwards.
-The value returned is the value of the last expression evaluated, or a
-return statement may be used, just as with subroutines. The last
-expression is evaluated in scalar or array context, depending on the
-context of the eval.
+Note that the value is parsed every time the eval executes. If EXPR is
+omitted, evaluates C<$_>. This form is typically used to delay parsing
+and subsequent execution of the text of EXPR until run time.
+
+In the second form, the code within the BLOCK is parsed only once--at the
+same time the code surrounding the eval itself was parsed--and executed
+within the context of the current Perl program. This form is typically
+used to trap exceptions more efficiently than the first (see below), while
+also providing the benefit of checking the code within BLOCK at compile
+time.
+
+The final semicolon, if any, may be omitted from the value of EXPR or within
+the BLOCK.
+
+In both forms, the value returned is the value of the last expression
+evaluated inside the mini-program, or a return statement may be used, just
+as with subroutines. The expression providing the return value is evaluated
+in void, scalar or array context, depending on the context of the eval itself.
+See L</wantarray> for more on how the evaluation context can be determined.
If there is a syntax error or runtime error, or a die() statement is
executed, an undefined value is returned by eval(), and C<$@> is set to the
error message. If there was no error, C<$@> is guaranteed to be a null
-string. If EXPR is omitted, evaluates C<$_>. The final semicolon, if
-any, may be omitted from the expression. Beware that using eval()
-neither silences perl from printing warnings to STDERR, nor does it
-stuff the text of warning messages into C<$@>. To do either of those,
-you have to use the C<$SIG{__WARN__}> facility. See warn() and L<perlvar>.
+string. Beware that using eval() neither silences perl from printing
+warnings to STDERR, nor does it stuff the text of warning messages into C<$@>.
+To do either of those, you have to use the C<$SIG{__WARN__}> facility. See
+L</warn> and L<perlvar>.
Note that, because eval() traps otherwise-fatal errors, it is useful for
determining whether a particular feature (such as socket() or symlink())
# __DIE__ hooks may modify error messages
{
local $SIG{'__DIE__'} = sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
- eval { die "foo foofs here" };
- print $@ if $@; # prints "bar barfs here"
+ eval { die "foo lives here" };
+ print $@ if $@; # prints "bar lives here"
}
With an eval(), you should be especially careful to remember what's
=item exec LIST
-The exec() function executes a system command I<AND NEVER RETURNS>,
-unless the command does not exist and is executed directly instead of
-via your system's command shell (see below). Use system() instead of
-exec() if you want it to return.
+=item exec PROGRAM LIST
+
+The exec() function executes a system command I<AND NEVER RETURNS> -
+use system() instead of exec() if you want it to return. It fails and
+returns FALSE only if the command does not exist I<and> it is executed
+directly instead of via your system's command shell (see below).
If there is more than one argument in LIST, or if LIST is an array with
more than one value, calls execvp(3) with the arguments in LIST. If
is Perl's portable file locking interface, although it locks only entire
files, not records.
+On many platforms (including most versions or clones of Unix), locks
+established by flock() are B<merely advisory>. This means that files
+locked with flock() may be modified by programs which do not also use
+flock(). Windows NT and OS/2, however, are among the platforms which
+supply mandatory locking. See your local documentation for details.
+
OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with
LOCK_NB. These constants are traditionally valued 1, 2, 8 and 4, but
you can use the symbolic names if import them from the Fcntl module,
array. Similarly, grep returns aliases into the original list,
much like the way that L<Foreach Loops>'s index variable aliases the list
elements. That is, modifying an element of a list returned by grep
+(for example, in a C<foreach>, C<map> or another C<grep>)
actually modifies the element in the original list.
+See also L</map> for an array composed of the results of the BLOCK or EXPR.
+
=item hex EXPR
=item hex
$now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
-Also see the Time::Local module, and the strftime(3) and mktime(3)
-function available via the POSIX module.
+This scalar value is B<not> locale dependent, see L<perllocale>, but
+instead a Perl builtin. Also see the Time::Local module, and the
+strftime(3) and mktime(3) function available via the POSIX module. To
+get somewhat similar but locale dependent date strings, set up your
+locale environment variables appropriately (please see L<perllocale>)
+and try for example
+
+ use POSIX qw(strftime)
+ $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
+
+Note that the C<%a> and C<%b>, the short forms of the day of the week
+and the month of the year, may not necessarily be three characters wide.
=item log EXPR
$hash{getkey($_)} = $_;
}
+Note that, because $_ is a reference into the list value, it can be used
+to modify the elements of the array. While this is useful and
+supported, it can cause bizarre results if the LIST is not a named
+array. See also L</grep> for an array composed of those items of the
+original list for which the BLOCK or EXPR evaluates to true.
+
=item mkdir FILENAME,MODE
Creates the directory specified by FILENAME, with permissions specified
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.
+When opening a file, it's usually a bad idea to continue normal execution
+if the request failed, so C<open> is frequently used in connection with
+C<die>. Even if C<die> won't do what you want (say, in a CGI script,
+where you want to make a nicely formatted error message (but there are
+modules which can help with that problem)) you should always check
+the return value from opening a file. The infrequent exception is when
+working with an unopened filehandle is actually what you want to do.
+
Examples:
$ARTICLE = 100;
while (<ARTICLE>) {...
open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
+ # if the open fails, output is discarded
- open(DBASE, '+<dbase.mine'); # open for update
+ open(DBASE, '+<dbase.mine') # open for update
+ or die "Can't open 'dbase.mine' for update: $!";
- open(ARTICLE, "caesar <$article |"); # decrypt article
+ open(ARTICLE, "caesar <$article |") # decrypt article
+ or die "Can't start caesar: $!";
- open(EXTRACT, "|sort >/tmp/Tmp$$"); # $$ is our process id
+ open(EXTRACT, "|sort >/tmp/Tmp$$") # $$ is our process id
+ or die "Can't start sort: $!";
# process argument list of files along with any includes
=item printf FORMAT, LIST
-Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>. The first argument
+Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that $\
+(the output record separator) is not appended. The first argument
of the list will be interpreted as the printf format. If C<use locale> is
in effect, the character used for the decimal point in formatted real numbers
is affected by the LC_NUMERIC locale. See L<perllocale>.
function has no prototype). FUNCTION is a reference to, or the name of,
the function whose prototype you want to retrieve.
+If FUNCTION is a string starting with C<CORE::>, the rest is taken as
+a name for Perl builtin. If builtin is not I<overridable> (such as
+C<qw>) or its arguments cannot be expressed by a prototype (such as
+C<system>) - in other words, the builtin does not behave like a Perl
+function - returns C<undef>. Otherwise, the string describing the
+equivalent prototype is returned.
+
=item push ARRAY,LIST
Treats ARRAY as a stack, and pushes the values of LIST
Receives a message on a socket. Attempts to receive LENGTH bytes of
data into variable SCALAR from the specified SOCKET filehandle.
-Actually does a C recvfrom(), so that it can returns the address of the
+Actually does a C recvfrom(), so that it can return 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.
Shifts the first value of the array off and returns it, shortening the
array by 1 and moving everything down. If there are no elements in the
array, returns the undefined value. If ARRAY is omitted, shifts the
-@ARGV array in the main program, and the @_ array in subroutines.
-(This is determined lexically.) See also unshift(), push(), and pop().
-Shift() and unshift() do the same thing to the left end of an array
-that pop() and push() do to the right end.
+@_ array within the lexical scope of subroutines and formats, and the
+@ARGV array at file scopes or within the lexical scopes established by
+the C<eval ''>, C<BEGIN {}>, C<END {}>, and C<INIT {}> constructs.
+See also unshift(), push(), and pop(). Shift() and unshift() do the
+same thing to the left end of an array that pop() and push() do to the
+right end.
=item shmctl ID,CMD,ARG
=item splice ARRAY,OFFSET
Removes the elements designated by OFFSET and LENGTH from an array, and
-replaces them with the elements of LIST, if any. Returns the elements
-removed from the array. The array grows or shrinks as necessary. If
-LENGTH is omitted, removes everything from OFFSET onward. The
-following equivalences hold (assuming C<$[ == 0>):
+replaces them with the elements of LIST, if any. In a list context,
+returns the elements removed from the array. In a scalar context,
+returns the last element removed, or C<undef> if no elements are
+removed. The array grows or shrinks as necessary. If LENGTH is
+omitted, removes everything from OFFSET onward. The following
+equivalences hold (assuming C<$[ == 0>):
push(@a,$x,$y) splice(@a,$#a+1,0,$x,$y)
pop(@a) splice(@a,-1)
If EXPR is omitted, splits the $_ string. If PATTERN is also omitted,
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.
+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
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);
+ %hdrs = (UNIX_FROM => split /^(\S*?):\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,
+ prefix positive number with a plus sign
- left-justify within the field
0 use zeros, not spaces, to right-justify
- # prefix octal with "0", hex with "0x"
+ # prefix non-zero octal with "0", non-zero hex with "0x"
number minimum field width
.number "precision": digits after decimal point for floating-point,
max length for string, minimum length for integer
as follows: if a given argument is numeric, the argument is passed as
an int. If not, the pointer to the string value is passed. You are
responsible to make sure a string is pre-extended long enough to
-receive any result that might be written into a string. If your
+receive any result that might be written into a string. You can't use a
+string literal (or other read-only string) as an argument to syscall()
+because Perl has to assume that any string pointer might be written
+through. If your
integer arguments are not literals and have never been interpreted in a
numeric context, you may need to add 0 to them to force them to look
like numbers.
require 'syscall.ph'; # may need to run h2ph
- syscall(&SYS_write, fileno(STDOUT), "hi there\n", 9);
+ $s = "hi there\n";
+ syscall(&SYS_write, fileno(STDOUT), $s, length $s);
Note that Perl supports passing of up to only 14 arguments to your system call,
which in practice should usually suffice.
+Syscall returns whatever value returned by the system call it calls.
+If the system call fails, syscall returns -1 and sets C<$!> (errno).
+Note that some system calls can legitimately return -1. The proper
+way to handle such calls is to assign C<$!=0;> before the call and
+check the value of <$!> if syscall returns -1.
+
+There's a problem with C<syscall(&SYS_pipe)>: it returns the file
+number of the read end of the pipe it creates. There is no way
+to retrieve the file number of the other end. You can avoid this
+problem by using C<pipe> instead.
+
=item sysopen FILEHANDLE,FILENAME,MODE
=item sysopen FILEHANDLE,FILENAME,MODE,PERMS
=item sysread FILEHANDLE,SCALAR,LENGTH
Attempts to read LENGTH bytes of data into variable SCALAR from the
-specified FILEHANDLE, using the system call read(2). It bypasses stdio,
-so mixing this with other kinds of reads, print(), write(), seek(), or
-tell() can cause confusion. Returns the number of bytes actually read,
-or undef if there was an error. SCALAR will be grown or shrunk so that
-the last byte actually read is the last byte of the scalar after the
-read.
+specified FILEHANDLE, using the system call read(2). It bypasses
+stdio, so mixing this with other kinds of reads, print(), write(),
+seek(), or tell() can cause confusion because stdio usually buffers
+data. Returns the number of bytes actually read, or undef if there
+was an error. SCALAR will be grown or shrunk so that the last byte
+actually read is the last byte of the scalar after the read.
An OFFSET may be specified to place the read data at some place in the
string other than the beginning. A negative OFFSET specifies
=item system LIST
+=item system PROGRAM LIST
+
Does exactly the same thing as "exec LIST" except that a fork is done
first, and the parent process waits for the child process to complete.
Note that argument processing varies depending on the number of
the output from a command, for that you should use merely backticks or
qx//, as described in L<perlop/"`STRING`">.
+Like exec(), system() allows you to lie to a program about its name if
+you use the "system PROGRAM LIST" syntax. Again, see L</exec>.
+
Because system() and backticks block SIGINT and SIGQUIT, killing the
program they're running doesn't actually interrupt your program.
Attempts to write LENGTH bytes of data from variable SCALAR to the
specified FILEHANDLE, using the system call write(2). It bypasses
stdio, so mixing this with reads (other than sysread()), print(),
-write(), seek(), or tell() may cause confusion. Returns the number of
-bytes actually written, or undef if there was an error. If the length
-is greater than the available data, only as much data as is available
+write(), seek(), or tell() may cause confusion because stdio usually
+buffers data. Returns the number of bytes actually written, or undef
+if there was an error. If the LENGTH is greater than the available
+data in the SCALAR after the OFFSET, only as much data as is available
will be written.
An OFFSET may be specified to write the data from some part of the
string other than the beginning. A negative OFFSET specifies writing
-that many bytes counting backwards from the end of the string.
+that many bytes counting backwards from the end of the string. In the
+case the SCALAR is empty you can use OFFSET but only zero offset.
=item tell FILEHANDLE
for you--you need to do that explicitly yourself. See L<DB_File>
or the F<Config> module for interesting tie() implementations.
+For further details see L<perltie>, L<tied VARIABLE>.
+
=item tied VARIABLE
Returns a reference to the object underlying VARIABLE (the same value
=item tr///
-The translation operator. Same as y///. See L<perlop>.
+The transliteration operator. Same as y///. See L<perlop>.
=item truncate FILEHANDLE,LENGTH
Truncates the file opened on FILEHANDLE, or named by EXPR, to the
specified length. Produces a fatal error if truncate isn't implemented
-on your system.
+on your system. Returns TRUE if successful, the undefined value
+otherwise.
=item uc EXPR
=item undef
Undefines the value of EXPR, which must be an lvalue. Use only on a
-scalar value, an entire array, an entire hash, or a subroutine name (using
-"&"). (Using undef() will probably not do what you expect on most
-predefined variables or DBM list values, so don't do that.) Always
-returns the undefined value. You can omit the EXPR, in which case
-nothing is undefined, but you still get an undefined value that you
-could, for instance, return from a subroutine, assign to a variable or
-pass as a parameter. Examples:
+scalar value, an array (using "@"), a hash (using "%"), a subroutine
+(using "&"), or a typeglob (using "*"). (Saying C<undef $hash{$key}>
+will probably not do what you expect on most predefined variables or
+DBM list values, so don't do that; see L<delete>.) Always returns the
+undefined value. You can omit the EXPR, in which case nothing is
+undefined, but you still get an undefined value that you could, for
+instance, return from a subroutine, assign to a variable or pass as a
+parameter. Examples:
undef $foo;
undef $bar{'blurfl'}; # Compare to: delete $bar{'blurfl'};
undef @ary;
undef %hash;
undef &mysub;
+ undef *xyz; # destroys $xyz, @xyz, %xyz, &xyz, etc.
return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
select undef, undef, undef, 0.25;
($a, $b, undef, $c) = &foo; # Ignore third value returned
files. The first two elements of the list must be the NUMERICAL access
and modification times, in that order. Returns the number of files
successfully changed. The inode modification time of each file is set
-to the current time. Example of a "touch" command:
+to the current time. This code has the same effect as the "touch"
+command if the files already exist:
#!/usr/bin/perl
$now = time;
Produces a message on STDERR just like die(), but doesn't exit or throw
an exception.
+If LIST is empty and $@ already contains a value (typically from a
+previous eval) that value is used after appending "\t...caught"
+to $@. This is useful for staying almost, but not entirely similar to
+die().
+
+If $@ is empty then the string "Warning: Something's wrong" is used.
+
No message is printed if there is a C<$SIG{__WARN__}> handler
installed. It is the handler's responsibility to deal with the message
as it sees fit (like, for instance, converting it into a die()). Most
=item y///
-The translation operator. Same as tr///. See L<perlop>.
+The transliteration operator. Same as tr///. See L<perlop>.
=back