die LIST
die
raises an exception. Inside an eval
the error message is stuffedinto $@
and the eval
is terminated with the undefined value.If the exception is outside of all enclosing eval
s, then the uncaughtexception prints LIST to STDERR
and exits with a non-zero value. If youneed to exit the process with a specific exit code, see exit.
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 last element of LIST does not end in a newline, the currentscript line number and input line number (if any) are also printed,and a newline is supplied. Note that the "input line number" (alsoknown as "chunk") is subject to whatever notion of "line" happens tobe currently in effect, and is also available as the special variable$.
. See $/ in perlvar and $. in perlvar.
Hint: sometimes appending ", stopped"
to your message will cause itto 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.
If the output is empty and $@
already contains a value (typically from aprevious eval) that value is reused after appending "\t...propagated"
.This is useful for propagating exceptions:
- eval { ... };
- die unless $@ =~ /Expected exception/;
If the output is empty and $@
contains an object reference that has aPROPAGATE
method, that method will be called with additional fileand line number parameters. The return value replaces the value in$@
; i.e., as if $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) };
were called.
If $@
is empty then the string "Died"
is used.
If an uncaught exception results in interpreter exit, the exit code isdetermined from the values of $!
and $?
with this pseudocode:
- exit $! if $!; # errno
- exit $? >> 8 if $? >> 8; # child exit status
- exit 255; # last resort
The intent is to squeeze as much possible information about the likely causeinto the limited space of the system exitcode. However, as $!
is the valueof C's errno
, which can be set by any system call, this means that the valueof the exit code used by die
can be non-predictable, so should not be reliedupon, other than to be non-zero.
You can also call die
with a reference argument, and if this is trappedwithin an eval
, $@
contains that reference. This permits moreelaborate exception handling using objects that maintain arbitrary stateabout the exception. Such a scheme is sometimes preferable to matchingparticular string values of $@
with regular expressions. Because $@
is a global variable and eval
may be used within object implementations,be careful that analyzing the error object doesn't replace the reference inthe global variable. It's easiest to make a local copy of the referencebefore any manipulations. Here's an example:
- use Scalar::Util "blessed";
- eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
- if (my $ev_err = $@) {
- if (blessed($ev_err) && $ev_err->isa("Some::Module::Exception")) {
- # handle Some::Module::Exception
- }
- else {
- # handle all other possible exceptions
- }
- }
Because Perl stringifies uncaught exception messages before display,you'll probably want to overload stringification operations onexception objects. See overload 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 associatedhandler is called with the error text and can change the errormessage, if it sees fit, by calling die
again. See%SIG in perlvar for details on setting %SIG
entries, andeval BLOCK for some examples. Although this feature was to be run only right before your program was to exit, this is notcurrently so: the $SIG{__DIE__}
hook is currently calledeven inside eval()ed blocks/strings! If one wants the hook to donothing in such situations, put
- die @_ if $^S;
as the first line of the handler (see $^S in perlvar). Becausethis promotes strange action at a distance, this counterintuitivebehavior may be fixed in a future release.
See also exit(), warn(), and the Carp module.