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