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