use sigtrap; use sigtrap qw(stack-trace old-interface-signals); # same thing use sigtrap qw(BUS SEGV PIPE ABRT); use sigtrap qw(die INT QUIT); use sigtrap qw(die normal-signals); use sigtrap qw(die untrapped normal-signals); use sigtrap qw(die untrapped normal-signals stack-trace any error-signals); use sigtrap 'handler' => &my_handler, 'normal-signals'; use sigtrap qw(handler my_handler normal-signals stack-trace error-signals);
The sigtrap
pragma installs some simple
signal handlers on your behalf so that you don't have to worry about
them. This is useful in situations where an untrapped signal would
cause your program to misbehave, like when you have END
{}
blocks, object destructors, or other at-exit processing
that needs to be run no matter how your program happens to
terminate.
The sigtrap
pragma provides two simple signal
handlers for your use. One provides a Perl stack trace, and the other
throws an ordinary exception via die
. Alternately,
you can supply your own handler for the pragma to install. You may
specify predefined sets of signals to trap; you can also supply your
own explicit list of signals. The pragma can optionally install
handlers for only those signals that have not otherwise been
handled.
Arguments passed to use sigtrap
are processed
in order. When a user-supplied signal name or the name of one of
sigtrap
's predefined signal lists is encountered, a
handler is immediately installed. When an option is encountered, this
affects only those handlers installed later in processing the argument
list.
These options affect which handler will be used for signals installed later:
stack-trace
This pragma-supplied handler outputs a Perl stack trace
to STDERR
and then tries to dump core. This
is the default signal handler.
die
This pragma-supplied handler calls
die
via Carp::croak
with
a message indicating the signal caught.
handler
YOURHANDLER
YOURHANDLER
will be used as
the handler for signals installed later.
YOURHANDLER
can be any value valid
for assignment into %SIG
. Remember that the
proper functioning of many C library calls (particularly
standard I/O calls) cannot be guaranteed within a signal
handler. Worse, it's hard to guess which bits of C library
code are called from which bits of Perl code. (On the other
hand, many of the signals that sigtrap
traps are pretty vile--they're gonna take you down anyway, so
there's not much harm in trying to do
something, now is there?)
The sigtrap
pragma has a few built-in lists
of signals to trap:
normal-signals
These are the signals a program might normally expect to
encounter, and which, by default, cause it to terminate. They
are the HUP
, INT
,
PIPE
, and TERM
signals.
error-signals
These are the signals that usually indicate a serious
problem with the Perl interpreter or with your program. They
are the ABRT
, BUS
,
EMT
, FPE
,
ILL
, QUIT
,
SEGV
, SYS
, and
TRAP
signals.
old-interface-signals
These are the signals that were trapped by default under
an older version of sigtrap
's interface.
They are ABRT
, BUS
,
EMT
, FPE
,
ILL
, PIPE
,
QUIT
, SEGV
,
SYS
, TERM
, and
TRAP
. If no signals or signals lists are
passed to use sigtrap
, this list is
used.
If your platform does not implement a particular signal named in the predefined lists, that signal name will be silently ignored. (The signal itself can't be ignored, because it doesn't exist.)
untrapped
This token suppresses the installation of handlers for subsequently listed signals if they're already been trapped or ignored.
any
This token installs handlers for all subsequently listed signals. This is the default behavior.
Any argument that looks like a signal name (that is, one
matching the pattern /^[A-Z][A-Z0-9]*$/
)
requests sigtrap
to handle that
signal.
A numeric argument requires the version number of the
sigtrap
pragma to be at least
number. This works is just like most
regular modules that have a $VERSION
package variable:
% perl -Msigtrap -le 'print $sigtrap::VERSION' 1.02
Provide a stack trace for the old interface signals:
use sigtrap;
Same thing, but more explicitly:
use sigtrap qw(stack-trace old-interface-signals);
Provide a stack trace only on the four listed signals:
use sigtrap qw(BUS SEGV PIPE ABRT);
Die on an INT
or a QUIT
signal:
use sigtrap qw(die INT QUIT);
Die on any of HUP
, INT
,
PIPE
, or TERM
:
use sigtrap qw(die normal-signals);
Die on HUP
, INT
,
PIPE
, or TERM
--except don't
change the behavior for signals that have already been trapped or
ignored elsewhere in the program:
use sigtrap qw(die untrapped normal-signals);
Die on receipt of any currently untrapped
normal-signals
; additionally, provide a stack
backtrace on receipt of any of the
error-signals
:
use sigtrap qw(die untrapped normal-signals stack-trace any error-signals);
Install the routine
my_handler
as the handler for the
normal-signals
:
use sigtrap 'handler' => &my_handler, 'normal-signals';
Install my_handler
as the
handler for the normal-signals
; provide a Perl
stack backtrace on receipt of any of the
error-signals
:
use sigtrap qw(handler my_handler normal-signals stack-trace error-signals);