1sigtrap(3pm)           Perl Programmers Reference Guide           sigtrap(3pm)
2
3
4

NAME

6       sigtrap - Perl pragma to enable simple signal handling
7

SYNOPSIS

9           use sigtrap;
10           use sigtrap qw(stack-trace old-interface-signals);  # equivalent
11           use sigtrap qw(BUS SEGV PIPE ABRT);
12           use sigtrap qw(die INT QUIT);
13           use sigtrap qw(die normal-signals);
14           use sigtrap qw(die untrapped normal-signals);
15           use sigtrap qw(die untrapped normal-signals
16                           stack-trace any error-signals);
17           use sigtrap 'handler' => \&my_handler, 'normal-signals';
18           use sigtrap qw(handler my_handler normal-signals
19                           stack-trace error-signals);
20

DESCRIPTION

22       The sigtrap pragma is a simple interface to installing signal handlers.
23       You can have it install one of two handlers supplied by sigtrap itself
24       (one which provides a Perl stack trace and one which simply "die()"s),
25       or alternately you can supply your own handler for it to install.  It
26       can be told only to install a handler for signals which are either
27       untrapped or ignored.  It has a couple of lists of signals to trap,
28       plus you can supply your own list of signals.
29
30       The arguments passed to the "use" statement which invokes sigtrap are
31       processed in order.  When a signal name or the name of one of sigtrap's
32       signal lists is encountered a handler is immediately installed, when an
33       option is encountered it affects subsequently installed handlers.
34

OPTIONS

36       SIGNAL HANDLERS
37
38       These options affect which handler will be used for subsequently
39       installed signals.
40
41       stack-trace
42           The handler used for subsequently installed signals outputs a Perl
43           stack trace to STDERR and then tries to dump core.  This is the
44           default signal handler.
45
46       die The handler used for subsequently installed signals calls "die"
47           (actually "croak") with a message indicating which signal was
48           caught.
49
50       handler your-handler
51           your-handler will be used as the handler for subsequently installed
52           signals.  your-handler can be any value which is valid as an
53           assignment to an element of %SIG.
54
55       SIGNAL LISTS
56
57       sigtrap has a few built-in lists of signals to trap.  They are:
58
59       normal-signals
60           These are the signals which a program might normally expect to
61           encounter and which by default cause it to terminate.  They are
62           HUP, INT, PIPE and TERM.
63
64       error-signals
65           These signals usually indicate a serious problem with the Perl
66           interpreter or with your script.  They are ABRT, BUS, EMT, FPE,
67           ILL, QUIT, SEGV, SYS and TRAP.
68
69       old-interface-signals
70           These are the signals which were trapped by default by the old sig‐
71           trap interface, they are ABRT, BUS, EMT, FPE, ILL, PIPE, QUIT,
72           SEGV, SYS, TERM, and TRAP.  If no signals or signals lists are
73           passed to sigtrap, this list is used.
74
75       For each of these three lists, the collection of signals set to be
76       trapped is checked before trapping; if your architecture does not
77       implement a particular signal, it will not be trapped but rather
78       silently ignored.
79
80       OTHER
81
82       untrapped
83           This token tells sigtrap to install handlers only for subsequently
84           listed signals which aren't already trapped or ignored.
85
86       any This token tells sigtrap to install handlers for all subsequently
87           listed signals.  This is the default behavior.
88
89       signal
90           Any argument which looks like a signal name (that is,
91           "/^[A-Z][A-Z0-9]*$/") indicates that sigtrap should install a han‐
92           dler for that name.
93
94       number
95           Require that at least version number of sigtrap is being used.
96

EXAMPLES

98       Provide a stack trace for the old-interface-signals:
99
100           use sigtrap;
101
102       Ditto:
103
104           use sigtrap qw(stack-trace old-interface-signals);
105
106       Provide a stack trace on the 4 listed signals only:
107
108           use sigtrap qw(BUS SEGV PIPE ABRT);
109
110       Die on INT or QUIT:
111
112           use sigtrap qw(die INT QUIT);
113
114       Die on HUP, INT, PIPE or TERM:
115
116           use sigtrap qw(die normal-signals);
117
118       Die on HUP, INT, PIPE or TERM, except don't change the behavior for
119       signals which are already trapped or ignored:
120
121           use sigtrap qw(die untrapped normal-signals);
122
123       Die on receipt one of an of the normal-signals which is currently
124       untrapped, provide a stack trace on receipt of any of the error-sig‐
125       nals:
126
127           use sigtrap qw(die untrapped normal-signals
128                           stack-trace any error-signals);
129
130       Install my_handler() as the handler for the normal-signals:
131
132           use sigtrap 'handler', \&my_handler, 'normal-signals';
133
134       Install my_handler() as the handler for the normal-signals, provide a
135       Perl stack trace on receipt of one of the error-signals:
136
137           use sigtrap qw(handler my_handler normal-signals
138                           stack-trace error-signals);
139
140
141
142perl v5.8.8                       2001-09-21                      sigtrap(3pm)