die - raise an exception or bail out
die LIST
Outside an eval, prints the value of
LIST to STDERR and
exits with the current value of $! (errno). If $! is 0,
exits with the value of ($? >> 8) (backtick `command`
status). If ($? >> 8) is 0, exits with 255. Inside
an eval(), the error message is stuffed into $@ and the
eval is terminated with the undefined value. This makes
die the way to raise an exception.
Equivalent examples:
die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
If the value of
EXPR does not end in a newline, the current script line
number and input line number (if any) are also printed, and a newline
is supplied. Note that the ``input line number'' (also known as ``chunk'')
is subject to whatever notion of ``line'' happens to be currently in
effect, and is also available as the special variable $..
See $/ in the perlvar manpage and $. in the perlvar manpage.
Hint: sometimes appending ", stopped" to your message
will cause it to make better sense when the string "at foo line 123" is
appended. Suppose you are running script ``canasta''.
die "/etc/games is no good";
die "/etc/games is no good, stopped";
produce, respectively
/etc/games is no good at canasta line 123.
/etc/games is no good, stopped at canasta line 123.
See also exit(), warn(), and the Carp module.
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.
die() can also be called with a reference argument. If this happens to be
trapped within an eval(), $@ contains the reference. This behavior permits
a more elaborate exception handling implementation using objects that
maintain arbitary state about the nature of the exception. Such a scheme
is sometimes preferable to matching particular string values of $@ using
regular expressions. Here's an example:
eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
if ($@) {
if (ref($@) && UNIVERSAL::isa($@,"Some::Module::Exception")) {
# handle Some::Module::Exception
}
else {
# handle all other possible exceptions
}
}
Because perl will stringify uncaught exception messages before displaying them, you may want to overload stringification operations on such custom exception objects. See the overload manpage for details about that.
You can arrange for a callback to be run just before the die
does its deed, by setting the $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
$SIG{expr} in the perlvar manpage for details on setting %SIG entries, and
eval
BLOCK for some examples. Although this feature was meant
to be run only right before your program was to exit, this is not
currently the case--the $SIG{__DIE__} hook is currently 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 $^S in the perlvar manpage). Because this promotes strange action at a distance, this counterintuitive behavior may be fixed in a future release.