Debian Codegraph @

upstream/debian-unstable/man2/signal.2

raw
1 .\" Copyright 2000, Andries E. Brouwer <[email protected]>
2 .\" Copyright 2007, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH signal 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 signal \- ANSI C signal handling
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <signal.h>
16 .P
17 .B "typedef typeof(void (int)) *sighandler_t;"
18 .P
19 .BI "sighandler_t signal(int " signum ", sighandler_t " handler );
20 .fi
21 .SH DESCRIPTION
22 .BR WARNING :
23 the behavior of
24 .BR signal ()
25 varies across UNIX versions,
26 and has also varied historically across different versions of Linux.
27 .BR "Avoid its use" :
28 use
29 .BR sigaction (2)
30 instead.
31 See
32 .I Portability
33 below.
34 .P
35 .BR signal ()
36 sets the disposition of the signal
37 .I signum
38 to
39 .IR handler ,
40 which is either
41 .BR SIG_IGN ,
42 .BR SIG_DFL ,
43 or the address of a programmer-defined function (a "signal handler").
44 .P
45 If the signal
46 .I signum
47 is delivered to the process, then one of the following happens:
48 .TP 3
49 *
50 If the disposition is set to
51 .BR SIG_IGN ,
52 then the signal is ignored.
53 .TP
54 *
55 If the disposition is set to
56 .BR SIG_DFL ,
57 then the default action associated with the signal (see
58 .BR signal (7))
59 occurs.
60 .TP
61 *
62 If the disposition is set to a function,
63 then first either the disposition is reset to
64 .BR SIG_DFL ,
65 or the signal is blocked (see
66 .I Portability
67 below), and then
68 .I handler
69 is called with argument
70 .IR signum .
71 If invocation of the handler caused the signal to be blocked,
72 then the signal is unblocked upon return from the handler.
73 .P
74 The signals
75 .B SIGKILL
76 and
77 .B SIGSTOP
78 cannot be caught or ignored.
79 .SH RETURN VALUE
80 .BR signal ()
81 returns the previous value of the signal handler.
82 On failure, it returns
83 .BR SIG_ERR ,
84 and
85 .I errno
86 is set to indicate the error.
87 .SH ERRORS
88 .TP
89 .B EINVAL
90 .I signum
91 is invalid.
92 .SH VERSIONS
93 The use of
94 .I sighandler_t
95 is a GNU extension, exposed if
96 .B _GNU_SOURCE
97 is defined;
98 .\" libc4 and libc5 define
99 .\" .IR SignalHandler ;
100 glibc also defines (the BSD-derived)
101 .I sig_t
102 if
103 .B _BSD_SOURCE
104 (glibc 2.19 and earlier)
105 or
106 .B _DEFAULT_SOURCE
107 (glibc 2.19 and later)
108 is defined.
109 The standard definition of
110 .BR signal ()
111 is:
112 .P
113 .in +4n
114 .EX
115 .BI "typeof(void (int)) *signal(int " signum ", typeof(void (int)) *" handler );
116 .EE
117 .in
118 .SS Portability
119 The only portable use of
120 .BR signal ()
121 is to set a signal's disposition to
122 .B SIG_DFL
123 or
124 .BR SIG_IGN .
125 The semantics when using
126 .BR signal ()
127 to establish a signal handler vary across systems
128 (and POSIX.1 explicitly permits this variation);
129 .B do not use it for this purpose.
130 .P
131 POSIX.1 solved the portability mess by specifying
132 .BR sigaction (2),
133 which provides explicit control of the semantics
134 when a signal handler is invoked;
135 use that interface instead of
136 .BR signal ().
137 .SH STANDARDS
138 C11, POSIX.1-2024.
139 .SH HISTORY
140 C89, POSIX.1-2001.
141 .P
142 In the original UNIX systems, when a handler that was established using
143 .BR signal ()
144 was invoked by the delivery of a signal,
145 the disposition of the signal would be reset to
146 .BR SIG_DFL ,
147 and the system did not block delivery of further instances of the signal.
148 This is equivalent to calling
149 .BR sigaction (2)
150 with the following flags:
151 .P
152 .in +4n
153 .EX
154 sa.sa_flags = SA_RESETHAND | SA_NODEFER;
155 .EE
156 .in
157 .P
158 System\ V also provides these semantics for
159 .BR signal ().
160 This was bad because the signal might be delivered again
161 before the handler had a chance to reestablish itself.
162 Furthermore, rapid deliveries of the same signal could
163 result in recursive invocations of the handler.
164 .P
165 BSD improved on this situation, but unfortunately also
166 changed the semantics of the existing
167 .BR signal ()
168 interface while doing so.
169 On BSD, when a signal handler is invoked,
170 the signal disposition is not reset,
171 and further instances of the signal are blocked from
172 being delivered while the handler is executing.
173 Furthermore, certain blocking system calls are automatically
174 restarted if interrupted by a signal handler (see
175 .BR signal (7)).
176 The BSD semantics are equivalent to calling
177 .BR sigaction (2)
178 with the following flags:
179 .P
180 .in +4n
181 .EX
182 sa.sa_flags = SA_RESTART;
183 .EE
184 .in
185 .P
186 The situation on Linux is as follows:
187 .IP \[bu] 3
188 The kernel's
189 .BR signal ()
190 system call provides System\ V semantics.
191 .IP \[bu]
192 By default, in glibc 2 and later, the
193 .BR signal ()
194 wrapper function does not invoke the kernel system call.
195 Instead, it calls
196 .BR sigaction (2)
197 using flags that supply BSD semantics.
198 This default behavior is provided as long as a suitable
199 feature test macro is defined:
200 .B _BSD_SOURCE
201 on glibc 2.19 and earlier or
202 .B _DEFAULT_SOURCE
203 in glibc 2.19 and later.
204 (By default, these macros are defined;
205 see
206 .BR feature_test_macros (7)
207 for details.)
208 If such a feature test macro is not defined, then
209 .BR signal ()
210 provides System\ V semantics.
211 .\"
212 .\" System V semantics are also provided if one uses the separate
213 .\" .BR sysv_signal (3)
214 .\" function.
215 .\" .IP \[bu]
216 .\" The
217 .\" .BR signal ()
218 .\" function in Linux libc4 and libc5 provide System\ V semantics.
219 .\" If one on a libc5 system includes
220 .\" .I <bsd/signal.h>
221 .\" instead of
222 .\" .IR <signal.h> ,
223 .\" then
224 .\" .BR signal ()
225 .\" provides BSD semantics.
226 .SH NOTES
227 The effects of
228 .BR signal ()
229 in a multithreaded process are unspecified.
230 .P
231 According to POSIX, the behavior of a process is undefined after it
232 ignores a
233 .BR SIGFPE ,
234 .BR SIGILL ,
235 or
236 .B SIGSEGV
237 signal that was not generated by
238 .BR kill (2)
239 or
240 .BR raise (3).
241 Integer division by zero has undefined result.
242 On some architectures it will generate a
243 .B SIGFPE
244 signal.
245 (Also dividing the most negative integer by \-1 may generate
246 .BR SIGFPE .)
247 Ignoring this signal might lead to an endless loop.
248 .P
249 See
250 .BR sigaction (2)
251 for details on what happens when the disposition
252 .B SIGCHLD
253 is set to
254 .BR SIG_IGN .
255 .P
256 See
257 .BR signal\-safety (7)
258 for a list of the async-signal-safe functions that can be
259 safely called from inside a signal handler.
260 .SH SEE ALSO
261 .BR kill (1),
262 .BR alarm (2),
263 .BR kill (2),
264 .BR pause (2),
265 .BR sigaction (2),
266 .BR signalfd (2),
267 .BR sigpending (2),
268 .BR sigprocmask (2),
269 .BR sigsuspend (2),
270 .BR bsd_signal (3),
271 .BR killpg (3),
272 .BR raise (3),
273 .BR siginterrupt (3),
274 .BR sigqueue (3),
275 .BR sigsetops (3),
276 .BR sigvec (3),
277 .BR sysv_signal (3),
278 .BR signal (7)