[This function has been superseded by the tie() function.]
-This binds a dbm(3), ndbm(3), sdbm(3), gdbm(), or Berkeley DB file to a
+This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file to a
hash. HASH is the name of the hash. (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
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 exec LIST
+=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).
+Since it's a common mistake to use system() instead of exec(), Perl
+warns you if there is a following statement which isn't die(), warn()
+or exit() (if C<-w> is set - but you always do that). If you
+I<really> want to follow an exec() with some other statement, you
+can use one of these styles to avoid the warning:
+
+ exec ('foo') or print STDERR "couldn't exec foo";
+ { exec ('foo') }; print STDERR "couldn't exec foo";
+
If there is more than one argument in LIST, or if LIST is an array with
more than one value, calls execvp(3) with the arguments in LIST. If
there is only one scalar argument, the argument is checked for shell
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,
=item format
-Declare a picture format with use by the write() function. For
+Declare a picture format for use by the write() function. For
example:
format Something =
various get routines are as follows:
($name,$passwd,$uid,$gid,
- $quota,$comment,$gcos,$dir,$shell) = getpw*
+ $quota,$comment,$gcos,$dir,$shell,$expire) = getpw*
($name,$passwd,$gid,$members) = getgr*
($name,$aliases,$addrtype,$length,@addrs) = gethost*
($name,$aliases,$addrtype,$net) = getnet*
$name = getgrent
etc.
+In I<getpw*()> the fields $quota, $comment, and $expire are special
+cases in the sense that in many systems they are unsupported. If the
+$quota is unsupported, it is an empty scalar. If it is supported, it
+usually encodes the disk quota. If the $comment field is unsupported,
+it is an empty scalar. If it is supported it usually encodes some
+administrative comment about the user. In some systems the $quota
+field may be $change or $age, fields that have to do with password
+aging. In some systems the $comment field may be $class. The $expire
+field, if present, encodes the expiration period of the account or the
+password. For the availability and the exact meaning of these fields
+in your system, please consult your getpwnam(3) documentation and your
+<pwd.h> file. You can also find out from within Perl which meaning
+your $quota and $comment fields have and whether you have the $expire
+field by using the Config module and the values d_pwquota, d_pwage,
+d_pwchange, d_pwcomment, and d_pwexpire.
+
The $members value returned by I<getgr*()> is a space separated list of
the login names of the members of the group.
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. Similarly, grep returns aliases into the original list,
-much like the way that L<Foreach Loops>'s index variable aliases the list
+much like the way that a for 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.
list must be placed in parentheses. See L<perlsub/"Temporary Values via
local()"> for details, including issues with tied arrays and hashes.
-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
+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"
-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.
+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
=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>.
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.
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 L</use> and
-L<perlmod>.
+In other words, if you try this:
+
+ require Foo::Bar ; # a splendid bareword
+
+The require function will actually look for the "Foo/Bar.pm" file in the
+directories specified in the @INC array.
+
+But if you try this :
+
+ $class = 'Foo::Bar';
+ require $class ; # $class is not a bareword
+or
+ require "Foo::Bar" ; # not a bareword because of the ""
+
+The require function will look for the "Foo::Bar" file in the @INC array and
+will complain about not finding "Foo::Bar" there. In this case you can do :
+
+ eval "require $class";
+
+For a yet-more-powerful import facility, see L</use> and L<perlmod>.
=item reset EXPR
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()> above.
See also the POSIX module's sigpause() function.
=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)
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
+If LIMIT is specified and is positive, splits into no more than that
+many fields (though it may split into fewer). If LIMIT is unspecified
+or zero, 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.
+ 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
ID, among other things. In versions of Perl prior to 5.004 the default
seed was just the current time(). This isn't a particularly good seed,
so many old programs supply their own seed value (often C<time ^ $$> or
-C<time ^ ($$ + ($$ << 15))>), but that isn't necessary any more.
+C<time ^ ($$ + ($$ E<lt>E<lt> 15))>), but that isn't necessary any more.
In fact, it's usually not necessary to call srand() at all, because if
it is not called explicitly, it is called implicitly at the first use of
value: the CODE ref of the closure you just created. See L<perlsub> and
L<perlref> for details.
+=item substr EXPR,OFFSET,LEN,REPLACEMENT
+
=item substr EXPR,OFFSET,LEN
=item substr EXPR,OFFSET
keep the string the same length you may need to pad or chop your value
using sprintf().
+An alternative to using substr() as an lvalue is to specify the
+replacement string as the 4th argument. This allows you to replace
+parts of the EXPR and return what was there before in one operation.
+In this case LEN can be C<undef> if you want to affect everything to
+the end of the string.
+
=item symlink OLDFILE,NEWFILE
Creates a new filename symbolically linked to the old filename.
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.
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.
+check the value of C<$!> 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
=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.
system() on a Unix system to check for all possibilities, including for
signals and core dumps.
- $rc = 0xffff & system @args;
+ $! = 0;
+ $rc = system @args;
printf "system(%s) returned %#04x: ", "@args", $rc;
if ($rc == 0) {
print "ran with normal exit\n";
}
elsif ($rc == 0xff00) {
- print "command failed: $!\n";
+ # Note that $! can be an empty string if the command that
+ # system() tried to execute was not found, not executable, etc.
+ # These errors occur in the child process after system() has
+ # forked, so the errno value is not visible in the parent.
+ printf "command failed: %s\n", ($! || "Unknown system() error");
}
- elsif ($rc > 0x80) {
+ elsif (($rc & 0xff) == 0) {
$rc >>= 8;
print "ran with non-zero exit status $rc\n";
}
=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 umask
Sets the umask for the process to EXPR and returns the previous value.
-If EXPR is omitted, merely returns the current umask. Remember that a
+If EXPR is omitted, merely returns the current umask. If umask(2) is
+not implemented on your system, returns C<undef>. Remember that a
umask is a number, usually given in octal; it is I<not> a string of octal
digits. See also L</oct>, if all you have is a string.
=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
projects / p5sagit/p5-mst-13.2.git / blobdiff