use sigtrap (Programming Perl)

31.18. use sigtrap

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.

31.18.1. Signal Handlers

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?)

31.18.2. Predefined Signal Lists

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.)

31.18.3. Other Arguments to sigtrap

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.

signal

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.

number

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

31.18.4. Examples of sigtrap

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);