Debian Codegraph @

upstream/mageia-cauldron/man3pm/sigtrap.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "sigtrap 3pm"
61 .TH sigtrap 3pm 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 sigtrap \- Perl pragma to enable simple signal handling
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 11
71 \& use sigtrap;
72 \& use sigtrap qw(stack\-trace old\-interface\-signals); # equivalent
73 \& use sigtrap qw(BUS SEGV PIPE ABRT);
74 \& use sigtrap qw(die INT QUIT);
75 \& use sigtrap qw(die normal\-signals);
76 \& use sigtrap qw(die untrapped normal\-signals);
77 \& use sigtrap qw(die untrapped normal\-signals
78 \& stack\-trace any error\-signals);
79 \& use sigtrap \*(Aqhandler\*(Aq => \e&my_handler, \*(Aqnormal\-signals\*(Aq;
80 \& use sigtrap qw(handler my_handler normal\-signals
81 \& stack\-trace error\-signals);
82 .Ve
83 .SH DESCRIPTION
84 .IX Header "DESCRIPTION"
85 The \fBsigtrap\fR pragma is a simple interface to installing signal
86 handlers. You can have it install one of two handlers supplied by
87 \&\fBsigtrap\fR itself (one which provides a Perl stack trace and one which
88 simply \f(CWdie()\fRs), or alternately you can supply your own handler for it
89 to install. It can be told only to install a handler for signals which
90 are either untrapped or ignored. It has three lists of signals to
91 trap, plus you can supply your own list of signals.
92 .PP
93 The arguments passed to the \f(CW\*(C`use\*(C'\fR statement which invokes \fBsigtrap\fR
94 are processed in order. When a signal name or the name of one of
95 \&\fBsigtrap\fR\*(Aqs signal lists is encountered a handler is immediately
96 installed, when an option is encountered it affects subsequently
97 installed handlers.
98 .SH OPTIONS
99 .IX Header "OPTIONS"
100 .SS "SIGNAL HANDLERS"
101 .IX Subsection "SIGNAL HANDLERS"
102 These options affect which handler will be used for subsequently
103 installed signals.
104 .IP \fBstack\-trace\fR 4
105 .IX Item "stack-trace"
106 The handler used for subsequently installed signals outputs a Perl stack
107 trace to STDERR and then tries to dump core. This is the default signal
108 handler.
109 .IP \fBdie\fR 4
110 .IX Item "die"
111 The handler used for subsequently installed signals calls \f(CW\*(C`die\*(C'\fR
112 (actually \f(CW\*(C`croak\*(C'\fR) with a message indicating which signal was caught.
113 .IP "\fBhandler\fR \fIyour\-handler\fR" 4
114 .IX Item "handler your-handler"
115 \&\fIyour\-handler\fR will be used as the handler for subsequently installed
116 signals. \fIyour\-handler\fR can be any value which is valid as an
117 assignment to an element of \f(CW%SIG\fR. See perlvar for examples of
118 handler functions.
119 .SS "SIGNAL LISTS"
120 .IX Subsection "SIGNAL LISTS"
121 \&\fBsigtrap\fR has a few built\-in lists of signals to trap. They are:
122 .IP \fBnormal\-signals\fR 4
123 .IX Item "normal-signals"
124 These are the signals which a program might normally expect to encounter
125 and which by default cause it to terminate. They are HUP, INT, PIPE and
126 TERM.
127 .IP \fBerror\-signals\fR 4
128 .IX Item "error-signals"
129 These signals usually indicate a serious problem with the Perl
130 interpreter or with your script. They are ABRT, BUS, EMT, FPE, ILL,
131 QUIT, SEGV, SYS and TRAP.
132 .IP \fBold\-interface\-signals\fR 4
133 .IX Item "old-interface-signals"
134 These are the signals which were trapped by default by the old
135 \&\fBsigtrap\fR interface, they are ABRT, BUS, EMT, FPE, ILL, PIPE, QUIT,
136 SEGV, SYS, TERM, and TRAP. If no signals or signals lists are passed to
137 \&\fBsigtrap\fR, this list is used.
138 .PP
139 For each of these three lists, the collection of signals set to be
140 trapped is checked before trapping; if your architecture does not
141 implement a particular signal, it will not be trapped but rather
142 silently ignored.
143 .SS OTHER
144 .IX Subsection "OTHER"
145 .IP \fBuntrapped\fR 4
146 .IX Item "untrapped"
147 This token tells \fBsigtrap\fR to install handlers only for subsequently
148 listed signals which aren\*(Aqt already trapped or ignored.
149 .IP \fBany\fR 4
150 .IX Item "any"
151 This token tells \fBsigtrap\fR to install handlers for all subsequently
152 listed signals. This is the default behavior.
153 .IP \fIsignal\fR 4
154 .IX Item "signal"
155 Any argument which looks like a signal name (that is,
156 \&\f(CW\*(C`/^[A\-Z][A\-Z0\-9]*$/\*(C'\fR) indicates that \fBsigtrap\fR should install a
157 handler for that name.
158 .IP \fInumber\fR 4
159 .IX Item "number"
160 Require that at least version \fInumber\fR of \fBsigtrap\fR is being used.
161 .SH EXAMPLES
162 .IX Header "EXAMPLES"
163 Provide a stack trace for the old\-interface\-signals:
164 .PP
165 .Vb 1
166 \& use sigtrap;
167 .Ve
168 .PP
169 Ditto:
170 .PP
171 .Vb 1
172 \& use sigtrap qw(stack\-trace old\-interface\-signals);
173 .Ve
174 .PP
175 Provide a stack trace on the 4 listed signals only:
176 .PP
177 .Vb 1
178 \& use sigtrap qw(BUS SEGV PIPE ABRT);
179 .Ve
180 .PP
181 Die on INT or QUIT:
182 .PP
183 .Vb 1
184 \& use sigtrap qw(die INT QUIT);
185 .Ve
186 .PP
187 Die on HUP, INT, PIPE or TERM:
188 .PP
189 .Vb 1
190 \& use sigtrap qw(die normal\-signals);
191 .Ve
192 .PP
193 Die on HUP, INT, PIPE or TERM, except don\*(Aqt change the behavior for
194 signals which are already trapped or ignored:
195 .PP
196 .Vb 1
197 \& use sigtrap qw(die untrapped normal\-signals);
198 .Ve
199 .PP
200 Die on receipt one of any of the \fBnormal\-signals\fR which is currently
201 \&\fBuntrapped\fR, provide a stack trace on receipt of \fBany\fR of the
202 \&\fBerror\-signals\fR:
203 .PP
204 .Vb 2
205 \& use sigtrap qw(die untrapped normal\-signals
206 \& stack\-trace any error\-signals);
207 .Ve
208 .PP
209 Install \fBmy_handler()\fR as the handler for the \fBnormal\-signals\fR:
210 .PP
211 .Vb 1
212 \& use sigtrap \*(Aqhandler\*(Aq, \e&my_handler, \*(Aqnormal\-signals\*(Aq;
213 .Ve
214 .PP
215 Install \fBmy_handler()\fR as the handler for the normal\-signals, provide a
216 Perl stack trace on receipt of one of the error\-signals:
217 .PP
218 .Vb 2
219 \& use sigtrap qw(handler my_handler normal\-signals
220 \& stack\-trace error\-signals);
221 .Ve