dbmclose, dbmopen
-
=back
=head2 Alphabetical Listing of Perl Functions
-
=over 8
=item -X FILEHANDLE
See also exit() and warn().
+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.
+
=item do BLOCK
Not really a function. Returns the value of the last command in the
If there is a syntax error or runtime error, or a die() statement is
executed, an undefined value is returned by eval(), and C<$@> is set to the
error message. If there was no error, C<$@> is guaranteed to be a null
-string. If EXPR is omitted, evaluates $_. The final semicolon, if
-any, may be omitted from the expression.
+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>.
Note that, because eval() traps otherwise-fatal errors, it is useful for
determining whether a particular feature (such as socket() or symlink())
# a run-time error
eval '$answer ='; # sets $@
+When using the eval{} form as an exception trap in libraries, you may
+wish not to trigger any C<__DIE__> hooks that user code may have
+installed. You can use the C<local $SIG{__DIE__}> construct for this
+purpose, as shown in this example:
+
+ # a very private exception trap for divide-by-zero
+ eval { local $SIG{'__DIE__'}; $answer = $a / $b; }; warn $@ if $@;
+
+This is especially significant, given that C<__DIE__> hooks can call
+die() again, which has the effect of changing their error messages:
+
+ # __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"
+ }
+
With an eval(), you should be especially careful to remember what's
being looked at when:
$ans = <STDIN>;
exit 0 if $ans =~ /^[Xx]/;
-See also die(). If EXPR is omitted, exits with 0 status.
+See also die(). If EXPR is omitted, exits with 0 status. The only
+univerally portable values for EXPR are 0 for success and 1 for error;
+all other values are subject to unpredictable interpretation depending
+on the environment in which the Perl program is running.
You shouldn't use exit() to abort a subroutine if there's any chance that
someone might want to trap whatever error happened. Use die() instead,
}
print "\n";
-Determination of whether to whether $BSD_STYLE should be set
+Determination of whether $BSD_STYLE should be set
is left as an exercise to the reader.
The POSIX::getattr() function can do this more portably on systems
Returns the current login from F</etc/utmp>, if any. If null, use
getpwuid().
- $login = getlogin || (getpwuid($<))[0] || "Kilroy";
+ $login = getlogin || getpwuid($<) || "Kilroy";
Do not consider getlogin() for authentication: it is not as
secure as getpwuid().
=item glob EXPR
+=item glob
+
Returns the value of EXPR with filename expansions such as a shell
would do. This is the internal function implementing the E<lt>*.*E<gt>
operator, except it's easier to use.
+If EXPR is omitted, $_ is used.
=item gmtime EXPR
In particular this means that $mon has the range 0..11 and $wday has
the range 0..6. If EXPR is omitted, does C<gmtime(time())>.
+In a scalar context, prints out the ctime(3) value:
+
+ $now_string = gmtime; # e.g., "Thu Oct 13 04:54:34 1994"
+
+Also see the F<timegm.pl> library, and the strftime(3) function available
+via the POSIX module.
+
=item goto LABEL
=item goto EXPR
The goto-LABEL form finds the statement labeled with LABEL and resumes
execution there. It may not be used to go into any construct that
requires initialization, such as a subroutine or a foreach loop. It
-also can't be used to go into a construct that is optimized away. It
-can be used to go almost anywhere else within the dynamic scope,
+also can't be used to go into a construct that is optimized away,
+or to get out of a block or subroutine given to sort().
+It can be used to go almost anywhere else within the dynamic scope,
including out of subroutines, but it's usually better to use some other
construct such as last or die. The author of Perl has never felt the
need to use this form of goto (in Perl, that is--C is another matter).
All array elements are numeric, and come straight out of a struct tm.
In particular this means that $mon has the range 0..11 and $wday has
-the range 0..6. If EXPR is omitted, does localtime(time).
+the range 0..6 and $year is year-1900, that is, $year is 123 in year
+2023. If EXPR is omitted, uses the current time ("localtime(time)").
-In a scalar context, prints out the ctime(3) value:
+In a scalar context, returns the ctime(3) value:
$now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
-Also see the F<timelocal.pl> library, and the strftime(3) function available
+Also see the Time::Local module, and the strftime(3) function available
via the POSIX module.
=item log EXPR
$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.
+You also cannot exit out of the sort block or subroutine using any of the
+loop control operators described in L<perlsyn> or with goto().
+
When C<use locale> is in effect, C<sort LIST> sorts LIST according to the
current collation locale. See L<perllocale>.
a^b == (a+1)^(b+1)
one-third of the time. So don't do that.
-
+
=item stat FILEHANDLE
=item stat EXPR
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
+ ctime inode change time (NOT creation time!) since the epoch
blksize preferred block size for file system I/O
blocks actual number of blocks allocated
print "signal $rc\n"
}
$ok = ($rc != 0);
-
+
=item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
=item syswrite FILEHANDLE,SCALAR,LENGTH
=item warn LIST
-Produces a message on STDERR just like die(), but doesn't exit or
-on an exception.
+Produces a message on STDERR just like die(), but doesn't exit or throw
+an exception.
+
+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
+handlers must therefore make arrangements to actually display the
+warnings that they are not prepared to deal with, by calling warn()
+again in the handler. Note that this is quite safe and will not
+produce an endless loop, since C<__WARN__> hooks are not called from
+inside one.
+
+You will find this behavior is slightly different from that of
+C<$SIG{__DIE__}> handlers (which don't suppress the error text, but can
+instead call die() again to change it).
+
+Using a C<__WARN__> handler provides a powerful way to silence all
+warnings (even the so-called mandatory ones). An example:
+
+ # wipe out *all* compile-time warnings
+ BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } }
+ my $foo = 10;
+ my $foo = 20; # no warning about duplicate my $foo,
+ # but hey, you asked for it!
+ # no compile-time or run-time warnings before here
+ $DOWARN = 1;
+
+ # run-time warnings enabled after here
+ warn "\$foo is alive and $foo!"; # does show up
+
+See L<perlvar> for details on setting C<%SIG> entries, and for more
+examples.
=item write FILEHANDLE
projects / p5sagit/p5-mst-13.2.git / blobdiff