@node sigtrap, strict, ptkFAQ, Module List
@unnumbered Perl pragma to enable simple signal handling


@unnumberedsec NAME

sigtrap - Perl pragma to enable simple signal handling

@unnumberedsec SYNOPSIS

@example
use sigtrap;
use sigtrap qw(stack-trace old-interface-signals);	# equivalent
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);
@end example

@unnumberedsec DESCRIPTION

The sigtrap pragma is a simple interface to installing signal
handlers.  You can have it install one of two handlers supplied by
sigtrap itself (one which provides a Perl stack trace and one which
simply @code{die()}s), or alternately you can supply your own handler for it
to install.  It can be told only to install a handler for signals which
are either untrapped or ignored.  It has a couple of lists of signals to
trap, plus you can supply your own list of signals.

The arguments passed to the use statement which invokes sigtrap
are processed in order.  When a signal name or the name of one of
sigtrap@'s signal lists is encountered a handler is immediately
installed, when an option is encountered it affects subsequently
installed handlers.

@unnumberedsec OPTIONS

@unnumberedsubsec SIGNAL HANDLERS

These options affect which handler will be used for subsequently
installed signals.

@table @asis
@item @strong{stack-trace}
The handler used for subsequently installed signals will output a Perl
stack trace to STDERR and then tries to dump core.  This is the default
signal handler.

@item die
The handler used for subsequently installed signals calls die
(actually croak) with a message indicating which signal was caught.

@item handler @emph{your-handler}
@emph{your-handler} will be used as the handler for subsequently installed
signals.  @emph{your-handler} can be any value which is valid as an
assignment to an element of @code{%SIG}.

@end table
@unnumberedsubsec SIGNAL LISTS

sigtrap has two built-in lists of signals to trap.  They are:

@table @asis
@item @strong{normal-signals}
These are the signals which a program might normally expect to encounter
and which by default cause it to terminate.  They are HUP, INT, PIPE and
TERM.

@item @strong{error-signals}
These signals usually indicate a serious problem with the Perl
interpreter or with your script.  They are ABRT, BUS, EMT, FPE, ILL,
QUIT, SEGV, SYS and TRAP.

@item @strong{old-interface-signals}
These are the signals which were trapped by default by the old
sigtrap interface, they are ABRT, BUS, EMT, FPE, ILL, PIPE, QUIT,
SEGV, SYS, TERM, and TRAP.  If no signals or signals lists are passed to
sigtrap this list is used.

@end table
@unnumberedsubsec OTHER

@table @asis
@item untrapped
This token tells sigtrap only to install handlers for subsequently
listed signals which aren@'t already trapped or ignored.

@item any
This token tells sigtrap to install handlers for all subsequently
listed signals.  This is the default behavior.

@item signal
Any argument which looks like a signals name (that is,
@code{/^[A-Z][A-Z0-9]*$/}) is taken as a signal name and indicates that
sigtrap should install a handler for it.

@item number
Require that at least version number of sigtrap is being used.

@end table
@unnumberedsec EXAMPLES

Provide a stack trace for the old-interface-signals:

@example
use sigtrap;
@end example

Ditto:

@example
use sigtrap qw(stack-trace old-interface-signals);
@end example

Provide a stack trace on the 4 listed signals only:

@example
use sigtrap qw(BUS SEGV PIPE ABRT);
@end example

Die on INT or QUIT:

@example
use sigtrap qw(die INT QUIT);
@end example

Die on HUP, INT, PIPE or TERM:

@example
use sigtrap qw(die normal-signals);
@end example

Die on HUP, INT, PIPE or TERM, except don@'t change the behavior for
signals which are already trapped or ignored:

@example
use sigtrap qw(die untrapped normal-signals);
@end example

Die on receipt one of an of the @strong{normal-signals} which is currently
untrapped, provide a stack trace on receipt of any of the
@strong{error-signals}:

@example
use sigtrap qw(die untrapped normal-signals
		    stack-trace any error-signals);
@end example

Install my_handler() as the handler for the @strong{normal-signals}:

@example
use sigtrap @'handler@', \&my_handler, @'normal-signals@';
@end example

Install my_handler() as the handler for the normal-signals, provide a
Perl stack trace on receipt of one of the error-signals:

@example
use sigtrap qw(handler my_handler normal-signals
	    	    stack-trace error-signals);
@end example

