]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | '\" t |
2 | .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) | |
743bc395 MK |
3 | .\" and Copyright (c) 2002, 2006 by Michael Kerrisk <mtk.manpages@gmail.com> |
4 | .\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk | |
5 | .\" <mtk.manpages@gmail.com> | |
fea681da | 6 | .\" |
93015253 | 7 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
8 | .\" Permission is granted to make and distribute verbatim copies of this |
9 | .\" manual provided the copyright notice and this permission notice are | |
10 | .\" preserved on all copies. | |
11 | .\" | |
12 | .\" Permission is granted to copy and distribute modified versions of this | |
13 | .\" manual under the conditions for verbatim copying, provided that the | |
14 | .\" entire resulting derived work is distributed under the terms of a | |
15 | .\" permission notice identical to this one. | |
c13182ef | 16 | .\" |
fea681da MK |
17 | .\" Since the Linux kernel and libraries are constantly changing, this |
18 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
19 | .\" responsibility for errors or omissions, or for damages resulting from | |
20 | .\" the use of the information contained herein. The author(s) may not | |
21 | .\" have taken the same level of care in the production of this manual, | |
22 | .\" which is licensed free of charge, as they might when working | |
23 | .\" professionally. | |
c13182ef | 24 | .\" |
fea681da MK |
25 | .\" Formatted or processed versions of this manual, if unaccompanied by |
26 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 27 | .\" %%%LICENSE_END |
1b88e9c2 | 28 | .\" |
fea681da MK |
29 | .\" Modified Sat Jul 24 17:34:08 1993 by Rik Faith (faith@cs.unc.edu) |
30 | .\" Modified Sun Jan 7 01:41:27 1996 by Andries Brouwer (aeb@cwi.nl) | |
31 | .\" Modified Sun Apr 14 12:02:29 1996 by Andries Brouwer (aeb@cwi.nl) | |
32 | .\" Modified Sat Nov 13 16:28:23 1999 by Andries Brouwer (aeb@cwi.nl) | |
c11b1abf MK |
33 | .\" Modified 10 Apr 2002, by Michael Kerrisk <mtk.manpages@gmail.com> |
34 | .\" Modified 7 Jun 2002, by Michael Kerrisk <mtk.manpages@gmail.com> | |
fea681da | 35 | .\" Added information on real-time signals |
c11b1abf | 36 | .\" Modified 13 Jun 2002, by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 37 | .\" Noted that SIGSTKFLT is in fact unused |
1c1634c0 | 38 | .\" 2004-12-03, Modified mtk, added notes on RLIMIT_SIGPENDING |
ae74cd0d MK |
39 | .\" 2006-04-24, mtk, Added text on changing signal dispositions, |
40 | .\" signal mask, and pending signals. | |
743bc395 MK |
41 | .\" 2008-07-04, mtk: |
42 | .\" Added section on system call restarting (SA_RESTART) | |
43 | .\" Added section on stop/cont signals interrupting syscalls. | |
2411effe | 44 | .\" 2008-10-05, mtk: various additions |
fea681da | 45 | .\" |
b8efb414 | 46 | .TH SIGNAL 7 2016-10-08 "Linux" "Linux Programmer's Manual" |
fea681da | 47 | .SH NAME |
2411effe | 48 | signal \- overview of signals |
fea681da MK |
49 | .SH DESCRIPTION |
50 | Linux supports both POSIX reliable signals (hereinafter | |
51 | "standard signals") and POSIX real-time signals. | |
73d8cece | 52 | .SS Signal dispositions |
c13182ef | 53 | Each signal has a current |
ae74cd0d | 54 | .IR disposition , |
c13182ef | 55 | which determines how the process behaves when it is delivered |
ae74cd0d | 56 | the signal. |
fea681da | 57 | |
ae74cd0d MK |
58 | The entries in the "Action" column of the tables below specify |
59 | the default disposition for each signal, as follows: | |
fea681da MK |
60 | .IP Term |
61 | Default action is to terminate the process. | |
62 | .IP Ign | |
63 | Default action is to ignore the signal. | |
64 | .IP Core | |
ae74cd0d MK |
65 | Default action is to terminate the process and dump core (see |
66 | .BR core (5)). | |
fea681da MK |
67 | .IP Stop |
68 | Default action is to stop the process. | |
ae74cd0d MK |
69 | .IP Cont |
70 | Default action is to continue the process if it is currently stopped. | |
fea681da | 71 | .PP |
ae74cd0d MK |
72 | A process can change the disposition of a signal using |
73 | .BR sigaction (2) | |
7edfdaca | 74 | or |
ae74cd0d | 75 | .BR signal (2). |
7edfdaca MK |
76 | (The latter is less portable when establishing a signal handler; |
77 | see | |
78 | .BR signal (2) | |
79 | for details.) | |
c13182ef | 80 | Using these system calls, a process can elect one of the |
6beb1671 | 81 | following behaviors to occur on delivery of the signal: |
c13182ef | 82 | perform the default action; ignore the signal; |
ae74cd0d | 83 | or catch the signal with a |
c13182ef MK |
84 | .IR "signal handler" , |
85 | a programmer-defined function that is automatically invoked | |
ae74cd0d | 86 | when the signal is delivered. |
eeccef1d MK |
87 | (By default, the signal handler is invoked on the |
88 | normal process stack. | |
89 | It is possible to arrange that the signal handler | |
90 | uses an alternate stack; see | |
91 | .BR sigaltstack (2) | |
92 | for a discussion of how to do this and when it might be useful.) | |
ae74cd0d MK |
93 | |
94 | The signal disposition is a per-process attribute: | |
c13182ef | 95 | in a multithreaded application, the disposition of a |
ae74cd0d | 96 | particular signal is the same for all threads. |
d5c88298 MK |
97 | |
98 | A child created via | |
99 | .BR fork (2) | |
100 | inherits a copy of its parent's signal dispositions. | |
101 | During an | |
102 | .BR execve (2), | |
103 | the dispositions of handled signals are reset to the default; | |
104 | the dispositions of ignored signals are left unchanged. | |
c634028a | 105 | .SS Sending a signal |
7a414038 MK |
106 | The following system calls and library functions allow |
107 | the caller to send a signal: | |
4704a09b | 108 | .TP 16 |
7a414038 MK |
109 | .BR raise (3) |
110 | Sends a signal to the calling thread. | |
111 | .TP | |
112 | .BR kill (2) | |
113 | Sends a signal to a specified process, | |
114 | to all members of a specified process group, | |
115 | or to all processes on the system. | |
116 | .TP | |
498aad50 | 117 | .BR killpg (3) |
7a414038 MK |
118 | Sends a signal to all of the members of a specified process group. |
119 | .TP | |
120 | .BR pthread_kill (3) | |
121 | Sends a signal to a specified POSIX thread in the same process as | |
122 | the caller. | |
123 | .TP | |
124 | .BR tgkill (2) | |
125 | Sends a signal to a specified thread within a specific process. | |
126 | (This is the system call used to implement | |
127 | .BR pthread_kill (3).) | |
128 | .TP | |
485ab701 | 129 | .BR sigqueue (3) |
7a414038 | 130 | Sends a real-time signal with accompanying data to a specified process. |
c634028a | 131 | .SS Waiting for a signal to be caught |
22fe4981 MK |
132 | The following system calls suspend execution of the calling process |
133 | or thread until a signal is caught | |
134 | (or an unhandled signal terminates the process): | |
135 | .TP 16 | |
136 | .BR pause (2) | |
137 | Suspends execution until any signal is caught. | |
138 | .TP | |
139 | .BR sigsuspend (2) | |
140 | Temporarily changes the signal mask (see below) and suspends | |
141 | execution until one of the unmasked signals is caught. | |
c634028a | 142 | .SS Synchronously accepting a signal |
e66d51d1 MK |
143 | Rather than asynchronously catching a signal via a signal handler, |
144 | it is possible to synchronously accept the signal, that is, | |
145 | to block execution until the signal is delivered, | |
146 | at which point the kernel returns information about the | |
147 | signal to the caller. | |
148 | There are two general ways to do this: | |
4697f7a7 | 149 | .IP * 2 |
e66d51d1 MK |
150 | .BR sigwaitinfo (2), |
151 | .BR sigtimedwait (2), | |
152 | and | |
153 | .BR sigwait (3) | |
154 | suspend execution until one of the signals in a specified | |
155 | set is delivered. | |
156 | Each of these calls returns information about the delivered signal. | |
157 | .IP * | |
158 | .BR signalfd (2) | |
159 | returns a file descriptor that can be used to read information | |
160 | about signals that are delivered to the caller. | |
161 | Each | |
162 | .BR read (2) | |
163 | from this file descriptor blocks until one of the signals | |
164 | in the set specified in the | |
165 | .BR signalfd (2) | |
166 | call is delivered to the caller. | |
167 | The buffer returned by | |
168 | .BR read (2) | |
169 | contains a structure describing the signal. | |
73d8cece | 170 | .SS Signal mask and pending signals |
ae74cd0d MK |
171 | A signal may be |
172 | .IR blocked , | |
173 | which means that it will not be delivered until it is later unblocked. | |
174 | Between the time when it is generated and when it is delivered | |
c13182ef | 175 | a signal is said to be |
ae74cd0d MK |
176 | .IR pending . |
177 | ||
c13182ef MK |
178 | Each thread in a process has an independent |
179 | .IR "signal mask" , | |
ae74cd0d MK |
180 | which indicates the set of signals that the thread is currently blocking. |
181 | A thread can manipulate its signal mask using | |
182 | .BR pthread_sigmask (3). | |
c13182ef | 183 | In a traditional single-threaded application, |
ae74cd0d MK |
184 | .BR sigprocmask (2) |
185 | can be used to manipulate the signal mask. | |
186 | ||
d5c88298 MK |
187 | A child created via |
188 | .BR fork (2) | |
189 | inherits a copy of its parent's signal mask; | |
190 | the signal mask is preserved across | |
191 | .BR execve (2). | |
192 | ||
ae74cd0d MK |
193 | A signal may be generated (and thus pending) |
194 | for a process as a whole (e.g., when sent using | |
c13182ef MK |
195 | .BR kill (2)) |
196 | or for a specific thread (e.g., certain signals, | |
5a5574b9 MK |
197 | such as |
198 | .B SIGSEGV | |
199 | and | |
200 | .BR SIGFPE , | |
201 | generated as a | |
c13182ef | 202 | consequence of executing a specific machine-language instruction |
ae74cd0d | 203 | are thread directed, as are signals targeted at a specific thread using |
8869be19 | 204 | .BR pthread_kill (3)). |
ae74cd0d MK |
205 | A process-directed signal may be delivered to any one of the |
206 | threads that does not currently have the signal blocked. | |
c13182ef | 207 | If more than one of the threads has the signal unblocked, then the |
ae74cd0d MK |
208 | kernel chooses an arbitrary thread to which to deliver the signal. |
209 | ||
210 | A thread can obtain the set of signals that it currently has pending | |
211 | using | |
212 | .BR sigpending (2). | |
c13182ef MK |
213 | This set will consist of the union of the set of pending |
214 | process-directed signals and the set of signals pending for | |
ae74cd0d | 215 | the calling thread. |
d5c88298 MK |
216 | |
217 | A child created via | |
218 | .BR fork (2) | |
219 | initially has an empty pending signal set; | |
220 | the pending signal set is preserved across an | |
221 | .BR execve (2). | |
73d8cece | 222 | .SS Standard signals |
c13182ef MK |
223 | Linux supports the standard signals listed below. |
224 | Several signal numbers | |
a43eed0c | 225 | are architecture-dependent, as indicated in the "Value" column. |
ae74cd0d | 226 | (Where three values are given, the first one is usually valid for |
8c69c923 | 227 | alpha and sparc, |
df2b6326 | 228 | the middle one for x86, arm, and most other architectures, |
8c69c923 | 229 | and the last one for mips. |
0ab8aeec | 230 | (Values for parisc are |
df2b6326 | 231 | .I not |
66a9882e | 232 | shown; see the Linux kernel source for signal numbering on that architecture.) |
ae74cd0d MK |
233 | A \- denotes that a signal is absent on the corresponding architecture.) |
234 | ||
4dec66f9 | 235 | First the signals described in the original POSIX.1-1990 standard. |
fea681da MK |
236 | .TS |
237 | l c c l | |
238 | ____ | |
239 | lB c c l. | |
240 | Signal Value Action Comment | |
241 | SIGHUP \01 Term Hangup detected on controlling terminal | |
242 | or death of controlling process | |
243 | SIGINT \02 Term Interrupt from keyboard | |
244 | SIGQUIT \03 Core Quit from keyboard | |
245 | SIGILL \04 Core Illegal Instruction | |
d9c1ae64 | 246 | SIGABRT \06 Core Abort signal from \fBabort\fP(3) |
fea681da MK |
247 | SIGFPE \08 Core Floating point exception |
248 | SIGKILL \09 Term Kill signal | |
249 | SIGSEGV 11 Core Invalid memory reference | |
10a100d0 MK |
250 | SIGPIPE 13 Term Broken pipe: write to pipe with no |
251 | readers | |
d9c1ae64 | 252 | SIGALRM 14 Term Timer signal from \fBalarm\fP(2) |
fea681da | 253 | SIGTERM 15 Term Termination signal |
2706f299 MK |
254 | SIGUSR1 30,10,16 Term User-defined signal 1 |
255 | SIGUSR2 31,12,17 Term User-defined signal 2 | |
fea681da | 256 | SIGCHLD 20,17,18 Ign Child stopped or terminated |
ae74cd0d | 257 | SIGCONT 19,18,25 Cont Continue if stopped |
fea681da | 258 | SIGSTOP 17,19,23 Stop Stop process |
1285ff3d MK |
259 | SIGTSTP 18,20,24 Stop Stop typed at terminal |
260 | SIGTTIN 21,21,26 Stop Terminal input for background process | |
261 | SIGTTOU 22,22,27 Stop Terminal output for background process | |
fea681da MK |
262 | .TE |
263 | ||
264 | The signals | |
265 | .B SIGKILL | |
266 | and | |
267 | .B SIGSTOP | |
268 | cannot be caught, blocked, or ignored. | |
269 | ||
c13182ef | 270 | Next the signals not in the POSIX.1-1990 standard but described in |
4dec66f9 | 271 | SUSv2 and POSIX.1-2001. |
fea681da MK |
272 | .TS |
273 | l c c l | |
274 | ____ | |
275 | lB c c l. | |
276 | Signal Value Action Comment | |
277 | SIGBUS 10,7,10 Core Bus error (bad memory access) | |
10a100d0 MK |
278 | SIGPOLL Term Pollable event (Sys V). |
279 | Synonym for \fBSIGIO\fP | |
fea681da | 280 | SIGPROF 27,27,29 Term Profiling timer expired |
07b00378 | 281 | SIGSYS 12,31,12 Core Bad argument to routine (SVr4) |
fea681da | 282 | SIGTRAP 5 Core Trace/breakpoint trap |
66679b1f MK |
283 | SIGURG 16,23,21 Ign Urgent condition on socket (4.2BSD) |
284 | SIGVTALRM 26,26,28 Term Virtual alarm clock (4.2BSD) | |
285 | SIGXCPU 24,24,30 Core CPU time limit exceeded (4.2BSD) | |
286 | SIGXFSZ 25,25,31 Core File size limit exceeded (4.2BSD) | |
fea681da MK |
287 | .TE |
288 | ||
d9bfdb9c | 289 | Up to and including Linux 2.2, the default behavior for |
fea681da MK |
290 | .BR SIGSYS ", " SIGXCPU ", " SIGXFSZ ", " |
291 | and (on architectures other than SPARC and MIPS) | |
292 | .B SIGBUS | |
293 | was to terminate the process (without a core dump). | |
008f1ecc | 294 | (On some other UNIX systems the default action for |
fea681da MK |
295 | .BR SIGXCPU " and " SIGXFSZ |
296 | is to terminate the process without a core dump.) | |
4dec66f9 | 297 | Linux 2.4 conforms to the POSIX.1-2001 requirements for these signals, |
fea681da MK |
298 | terminating the process with a core dump. |
299 | ||
300 | Next various other signals. | |
fea681da MK |
301 | .TS |
302 | l c c l | |
303 | ____ | |
304 | lB c c l. | |
305 | Signal Value Action Comment | |
5a5574b9 | 306 | SIGIOT 6 Core IOT trap. A synonym for \fBSIGABRT\fP |
fea681da MK |
307 | SIGEMT 7,\-,7 Term |
308 | SIGSTKFLT \-,16,\- Term Stack fault on coprocessor (unused) | |
66679b1f | 309 | SIGIO 23,29,22 Term I/O now possible (4.2BSD) |
5a5574b9 | 310 | SIGCLD \-,\-,18 Ign A synonym for \fBSIGCHLD\fP |
fea681da | 311 | SIGPWR 29,30,19 Term Power failure (System V) |
5a5574b9 | 312 | SIGINFO 29,\-,\- A synonym for \fBSIGPWR\fP |
6cf29ace | 313 | SIGLOST \-,\-,\- Term File lock lost (unused) |
66679b1f | 314 | SIGWINCH 28,28,20 Ign Window resize signal (4.3BSD, Sun) |
07b00378 | 315 | SIGUNUSED \-,31,\- Core Synonymous with \fBSIGSYS\fP |
fea681da MK |
316 | .TE |
317 | ||
318 | (Signal 29 is | |
319 | .B SIGINFO | |
320 | / | |
321 | .B SIGPWR | |
322 | on an alpha but | |
323 | .B SIGLOST | |
324 | on a sparc.) | |
325 | ||
326 | .B SIGEMT | |
4dec66f9 | 327 | is not specified in POSIX.1-2001, but nevertheless appears |
008f1ecc | 328 | on most other UNIX systems, |
d24e2319 | 329 | where its default action is typically to terminate |
fea681da MK |
330 | the process with a core dump. |
331 | ||
332 | .B SIGPWR | |
4dec66f9 | 333 | (which is not specified in POSIX.1-2001) is typically ignored |
008f1ecc | 334 | by default on those other UNIX systems where it appears. |
fea681da MK |
335 | |
336 | .B SIGIO | |
4dec66f9 | 337 | (which is not specified in POSIX.1-2001) is ignored by default |
008f1ecc | 338 | on several other UNIX systems. |
07b00378 MK |
339 | |
340 | Where defined, | |
341 | .B SIGUNUSED | |
342 | is synonymous with | |
343 | .\" parisc is the only exception: SIGSYS is 12, SIGUNUSED is 31 | |
344 | .B SIGSYS | |
345 | on most architectures. | |
73d8cece | 346 | .SS Real-time signals |
6c6aa9a8 | 347 | Starting with version 2.2, |
4dec66f9 MK |
348 | Linux supports real-time signals as originally defined in the POSIX.1b |
349 | real-time extensions (and now included in POSIX.1-2001). | |
5a5574b9 MK |
350 | The range of supported real-time signals is defined by the macros |
351 | .B SIGRTMIN | |
352 | and | |
353 | .BR SIGRTMAX . | |
354 | POSIX.1-2001 requires that an implementation support at least | |
355 | .B _POSIX_RTSIG_MAX | |
356 | (8) real-time signals. | |
357 | .PP | |
373ed9ba MK |
358 | The Linux kernel supports a range of 33 different real-time |
359 | signals, numbered 32 to 64. | |
5a5574b9 | 360 | However, the glibc POSIX threads implementation internally uses |
e0bf9127 | 361 | two (for NPTL) or three (for LinuxThreads) real-time signals |
5a5574b9 MK |
362 | (see |
363 | .BR pthreads (7)), | |
364 | and adjusts the value of | |
365 | .B SIGRTMIN | |
366 | suitably (to 34 or 35). | |
367 | Because the range of available real-time signals varies according | |
368 | to the glibc threading implementation (and this variation can occur | |
cf50118f | 369 | at run time according to the available kernel and glibc), |
008f1ecc | 370 | and indeed the range of real-time signals varies across UNIX systems, |
5a5574b9 MK |
371 | programs should |
372 | .IR "never refer to real-time signals using hard-coded numbers" , | |
373 | but instead should always refer to real-time signals using the notation | |
fea681da | 374 | .BR SIGRTMIN +n, |
e0bf9127 | 375 | and include suitable (run-time) checks that |
5a5574b9 MK |
376 | .BR SIGRTMIN +n |
377 | does not exceed | |
378 | .BR SIGRTMAX . | |
fea681da MK |
379 | .PP |
380 | Unlike standard signals, real-time signals have no predefined meanings: | |
381 | the entire set of real-time signals can be used for application-defined | |
382 | purposes. | |
fea681da MK |
383 | .PP |
384 | The default action for an unhandled real-time signal is to terminate the | |
385 | receiving process. | |
386 | .PP | |
387 | Real-time signals are distinguished by the following: | |
388 | .IP 1. 4 | |
389 | Multiple instances of real-time signals can be queued. | |
390 | By contrast, if multiple instances of a standard signal are delivered | |
391 | while that signal is currently blocked, then only one instance is queued. | |
392 | .IP 2. 4 | |
393 | If the signal is sent using | |
485ab701 | 394 | .BR sigqueue (3), |
fea681da MK |
395 | an accompanying value (either an integer or a pointer) can be sent |
396 | with the signal. | |
397 | If the receiving process establishes a handler for this signal using the | |
9fdfa163 | 398 | .B SA_SIGINFO |
fea681da | 399 | flag to |
1c1cbf3d | 400 | .BR sigaction (2), |
fea681da MK |
401 | then it can obtain this data via the |
402 | .I si_value | |
403 | field of the | |
404 | .I siginfo_t | |
405 | structure passed as the second argument to the handler. | |
406 | Furthermore, the | |
407 | .I si_pid | |
408 | and | |
409 | .I si_uid | |
410 | fields of this structure can be used to obtain the PID | |
411 | and real user ID of the process sending the signal. | |
412 | .IP 3. 4 | |
413 | Real-time signals are delivered in a guaranteed order. | |
414 | Multiple real-time signals of the same type are delivered in the order | |
415 | they were sent. | |
416 | If different real-time signals are sent to a process, they are delivered | |
417 | starting with the lowest-numbered signal. | |
418 | (I.e., low-numbered signals have highest priority.) | |
4564433c MK |
419 | By contrast, if multiple standard signals are pending for a process, |
420 | the order in which they are delivered is unspecified. | |
fea681da MK |
421 | .PP |
422 | If both standard and real-time signals are pending for a process, | |
423 | POSIX leaves it unspecified which is delivered first. | |
424 | Linux, like many other implementations, gives priority | |
425 | to standard signals in this case. | |
426 | .PP | |
427 | According to POSIX, an implementation should permit at least | |
5a5574b9 MK |
428 | .B _POSIX_SIGQUEUE_MAX |
429 | (32) real-time signals to be queued to | |
fea681da | 430 | a process. |
1c1634c0 MK |
431 | However, Linux does things differently. |
432 | In kernels up to and including 2.6.7, Linux imposes | |
fea681da MK |
433 | a system-wide limit on the number of queued real-time signals |
434 | for all processes. | |
435 | This limit can be viewed and (with privilege) changed via the | |
436 | .I /proc/sys/kernel/rtsig-max | |
437 | file. | |
438 | A related file, | |
439 | .IR /proc/sys/kernel/rtsig-nr , | |
440 | can be used to find out how many real-time signals are currently queued. | |
1c1634c0 MK |
441 | In Linux 2.6.8, these |
442 | .I /proc | |
de7e5e18 | 443 | interfaces were replaced by the |
1c1634c0 MK |
444 | .B RLIMIT_SIGPENDING |
445 | resource limit, which specifies a per-user limit for queued | |
c0722da0 | 446 | signals; see |
1c1634c0 MK |
447 | .BR setrlimit (2) |
448 | for further details. | |
530156fe MK |
449 | |
450 | The addition or real-time signals required the widening | |
451 | of the signal set structure | |
452 | .RI ( sigset_t ) | |
453 | from 32 to 64 bits. | |
454 | Consequently, various system calls were superseded by new system calls | |
455 | that supported the larger signal sets. | |
456 | The old and new system calls are as follows: | |
457 | .TS | |
458 | lb lb | |
459 | l l. | |
460 | Linux 2.0 and earlier Linux 2.2 and later | |
461 | \fBsigaction\fP(2) \fBrt_sigaction\fP(2) | |
462 | \fBsigpending\fP(2) \fBrt_sigpending\fP(2) | |
463 | \fBsigprocmask\fP(2) \fBrt_sigprocmask\fP(2) | |
464 | \fBsigreturn\fP(2) \fBrt_sigreturn\fP(2) | |
465 | \fBsigsuspend\fP(2) \fBrt_sigsuspend\fP(2) | |
466 | \fBsigtimedwait\fP(2) \fBrt_sigtimedwait\fP(2) | |
467 | .TE | |
468 | .\" | |
73d8cece | 469 | .SS Async-signal-safe functions |
e8f5dd81 | 470 | .PP |
8d4eb5f8 MK |
471 | A signal handler function must be very careful, |
472 | since processing elsewhere may be interrupted | |
74d32233 | 473 | at some arbitrary point in the execution of the program. |
e8f5dd81 MK |
474 | POSIX has the concept of "safe function". |
475 | If a signal interrupts the execution of an unsafe function, and | |
476 | .I handler | |
082efcce MK |
477 | either calls an unsafe function or |
478 | .I handler | |
479 | terminates via a call to | |
480 | .BR longjmp () | |
481 | or | |
482 | .BR siglongjmp () | |
483 | and the program subsequently calls an unsafe function, | |
484 | then the behavior of the program is undefined. | |
a574189c | 485 | |
72ee5ec2 MK |
486 | POSIX.1-2004 (also known as POSIX.1-2001 Technical Corrigendum 2) |
487 | requires an implementation to guarantee that the following | |
e8f5dd81 MK |
488 | functions can be safely called inside a signal handler: |
489 | ||
a574189c MK |
490 | .in +4 |
491 | .nf | |
492 | _Exit() | |
493 | _exit() | |
494 | abort() | |
495 | accept() | |
496 | access() | |
497 | aio_error() | |
498 | aio_return() | |
499 | aio_suspend() | |
500 | alarm() | |
501 | bind() | |
502 | cfgetispeed() | |
503 | cfgetospeed() | |
504 | cfsetispeed() | |
505 | cfsetospeed() | |
506 | chdir() | |
507 | chmod() | |
508 | chown() | |
509 | clock_gettime() | |
510 | close() | |
511 | connect() | |
512 | creat() | |
513 | dup() | |
514 | dup2() | |
515 | execle() | |
516 | execve() | |
517 | fchmod() | |
518 | fchown() | |
519 | fcntl() | |
520 | fdatasync() | |
521 | fork() | |
522 | fpathconf() | |
523 | fstat() | |
524 | fsync() | |
525 | ftruncate() | |
526 | getegid() | |
527 | geteuid() | |
528 | getgid() | |
529 | getgroups() | |
530 | getpeername() | |
531 | getpgrp() | |
532 | getpid() | |
533 | getppid() | |
534 | getsockname() | |
535 | getsockopt() | |
536 | getuid() | |
537 | kill() | |
538 | link() | |
539 | listen() | |
540 | lseek() | |
541 | lstat() | |
542 | mkdir() | |
543 | mkfifo() | |
544 | open() | |
545 | pathconf() | |
546 | pause() | |
547 | pipe() | |
548 | poll() | |
549 | posix_trace_event() | |
550 | pselect() | |
551 | raise() | |
552 | read() | |
553 | readlink() | |
554 | recv() | |
555 | recvfrom() | |
556 | recvmsg() | |
557 | rename() | |
558 | rmdir() | |
559 | select() | |
560 | sem_post() | |
561 | send() | |
562 | sendmsg() | |
563 | sendto() | |
564 | setgid() | |
565 | setpgid() | |
566 | setsid() | |
567 | setsockopt() | |
568 | setuid() | |
569 | shutdown() | |
570 | sigaction() | |
571 | sigaddset() | |
572 | sigdelset() | |
573 | sigemptyset() | |
574 | sigfillset() | |
575 | sigismember() | |
576 | signal() | |
577 | sigpause() | |
578 | sigpending() | |
579 | sigprocmask() | |
580 | sigqueue() | |
581 | sigset() | |
582 | sigsuspend() | |
583 | sleep() | |
72ee5ec2 | 584 | sockatmark() |
07d72ca8 | 585 | socket() |
a574189c MK |
586 | socketpair() |
587 | stat() | |
588 | symlink() | |
589 | sysconf() | |
590 | tcdrain() | |
591 | tcflow() | |
592 | tcflush() | |
593 | tcgetattr() | |
594 | tcgetpgrp() | |
595 | tcsendbreak() | |
596 | tcsetattr() | |
597 | tcsetpgrp() | |
598 | time() | |
599 | timer_getoverrun() | |
600 | timer_gettime() | |
601 | timer_settime() | |
602 | times() | |
603 | umask() | |
604 | uname() | |
605 | unlink() | |
606 | utime() | |
607 | wait() | |
608 | waitpid() | |
609 | write() | |
610 | .fi | |
611 | .in | |
a0f7c7d8 MK |
612 | .PP |
613 | POSIX.1-2008 removes fpathconf(), pathconf(), and sysconf() | |
614 | from the above list, and adds the following functions: | |
615 | .PP | |
616 | .in +4n | |
617 | .nf | |
618 | execl() | |
619 | execv() | |
620 | faccessat() | |
621 | fchmodat() | |
622 | fchownat() | |
623 | fexecve() | |
624 | fstatat() | |
625 | futimens() | |
626 | linkat() | |
627 | mkdirat() | |
628 | mkfifoat() | |
629 | mknod() | |
630 | mknodat() | |
631 | openat() | |
632 | readlinkat() | |
633 | renameat() | |
634 | symlinkat() | |
635 | unlinkat() | |
636 | utimensat() | |
637 | utimes() | |
638 | .fi | |
639 | .in | |
adce1084 MK |
640 | .PP |
641 | POSIX.1-2008 Technical Corrigendum 1 (2013) | |
642 | adds the following functions: | |
643 | .PP | |
644 | .in +4n | |
645 | .nf | |
646 | fchdir() | |
647 | pthread_kill() | |
648 | pthread_self() | |
649 | pthread_sigmask() | |
650 | .fi | |
651 | .in | |
b76f24dd | 652 | .\" FIXME POSIX.1-2008 TC 2 looks set to add many more async-signal-safe |
6248a90b | 653 | .\" functions. Document these. |
c634028a | 654 | .SS Interruption of system calls and library functions by signal handlers |
72710182 MK |
655 | If a signal handler is invoked while a system call or library |
656 | function call is blocked, then either: | |
657 | .IP * 2 | |
658 | the call is automatically restarted after the signal handler returns; or | |
659 | .IP * | |
660 | the call fails with the error | |
af3c87d0 | 661 | .BR EINTR . |
72710182 MK |
662 | .PP |
663 | Which of these two behaviors occurs depends on the interface and | |
664 | whether or not the signal handler was established using the | |
af3c87d0 MK |
665 | .BR SA_RESTART |
666 | flag (see | |
667 | .BR sigaction (2)). | |
008f1ecc | 668 | The details vary across UNIX systems; |
164be4fc | 669 | below, the details for Linux. |
af3c87d0 | 670 | |
72710182 MK |
671 | If a blocked call to one of the following interfaces is interrupted |
672 | by a signal handler, then the call will be automatically restarted | |
673 | after the signal handler returns if the | |
af3c87d0 | 674 | .BR SA_RESTART |
72710182 | 675 | flag was used; otherwise the call will fail with the error |
af3c87d0 MK |
676 | .BR EINTR : |
677 | .\" The following system calls use ERESTARTSYS, | |
678 | .\" so that they are restartable | |
af3c87d0 MK |
679 | .IP * 2 |
680 | .BR read (2), | |
681 | .BR readv (2), | |
682 | .BR write (2), | |
683 | .BR writev (2), | |
684 | and | |
685 | .BR ioctl (2) | |
686 | calls on "slow" devices. | |
72710182 MK |
687 | A "slow" device is one where the I/O call may block for an |
688 | indefinite time, for example, a terminal, pipe, or socket. | |
72710182 MK |
689 | If an I/O call on a slow device has already transferred some |
690 | data by the time it is interrupted by a signal handler, | |
af3c87d0 MK |
691 | then the call will return a success status |
692 | (normally, the number of bytes transferred). | |
ae1c1caa MK |
693 | Note that a (local) disk is not a slow device according to this definition; |
694 | I/O operations on disk devices are not interrupted by signals. | |
af3c87d0 MK |
695 | .IP * |
696 | .BR open (2), | |
72ee5ec2 | 697 | if it can block (e.g., when opening a FIFO; see |
af3c87d0 MK |
698 | .BR fifo (7)). |
699 | .IP * | |
700 | .BR wait (2), | |
701 | .BR wait3 (2), | |
702 | .BR wait4 (2), | |
703 | .BR waitid (2), | |
704 | and | |
705 | .BR waitpid (2). | |
706 | .IP * | |
707 | Socket interfaces: | |
72710182 | 708 | .\" If a timeout (setsockopt()) is in effect on the socket, then these |
af3c87d0 MK |
709 | .\" system calls switch to using EINTR. Consequently, they and are not |
710 | .\" automatically restarted, and they show the stop/cont behavior | |
711 | .\" described below. (Verified from 2.6.26 source, and by experiment; mtk) | |
712 | .BR accept (2), | |
713 | .BR connect (2), | |
714 | .BR recv (2), | |
715 | .BR recvfrom (2), | |
88fb4f09 | 716 | .BR recvmmsg (2), |
af3c87d0 MK |
717 | .BR recvmsg (2), |
718 | .BR send (2), | |
719 | .BR sendto (2), | |
720 | and | |
4f6d71a1 | 721 | .BR sendmsg (2), |
6248a90b | 722 | .\" FIXME What about sendmmsg()? |
4f6d71a1 | 723 | unless a timeout has been set on the socket (see below). |
af3c87d0 MK |
724 | .IP * |
725 | File locking interfaces: | |
726 | .BR flock (2) | |
727 | and | |
6f0dcebc MK |
728 | the |
729 | .BR F_SETLKW | |
730 | and | |
731 | .BR F_OFD_SETLKW | |
732 | operations of | |
af3c87d0 | 733 | .BR fcntl (2) |
af3c87d0 MK |
734 | .IP * |
735 | POSIX message queue interfaces: | |
c1667735 MK |
736 | .BR mq_receive (3), |
737 | .BR mq_timedreceive (3), | |
738 | .BR mq_send (3), | |
af3c87d0 | 739 | and |
c1667735 | 740 | .BR mq_timedsend (3). |
af3c87d0 MK |
741 | .IP * |
742 | .BR futex (2) | |
743 | .B FUTEX_WAIT | |
4b139190 MK |
744 | (since Linux 2.6.22; |
745 | .\" commit 72c1bbf308c75a136803d2d76d0e18258be14c7a | |
746 | beforehand, always failed with | |
af3c87d0 MK |
747 | .BR EINTR ). |
748 | .IP * | |
3168ff2d MK |
749 | .BR getrandom (2). |
750 | .IP * | |
d53ad479 MK |
751 | .BR pthread_mutex_lock (3), |
752 | .BR pthread_cond_wait (3), | |
753 | and related APIs. | |
754 | .IP * | |
4b139190 MK |
755 | .BR futex (2) |
756 | .BR FUTEX_WAIT_BITSET . | |
757 | .IP * | |
af3c87d0 MK |
758 | POSIX semaphore interfaces: |
759 | .BR sem_wait (3) | |
760 | and | |
761 | .BR sem_timedwait (3) | |
4b139190 MK |
762 | (since Linux 2.6.22; |
763 | .\" as a consequence of the 2.6.22 changes in the futex() implementation | |
764 | beforehand, always failed with | |
af3c87d0 | 765 | .BR EINTR ). |
af3c87d0 MK |
766 | .PP |
767 | The following interfaces are never restarted after | |
768 | being interrupted by a signal handler, | |
769 | regardless of the use of | |
495edd81 MK |
770 | .BR SA_RESTART ; |
771 | they always fail with the error | |
772 | .B EINTR | |
773 | when interrupted by a signal handler: | |
af3c87d0 MK |
774 | .\" These are the system calls that give EINTR or ERESTARTNOHAND |
775 | .\" on interruption by a signal handler. | |
af3c87d0 | 776 | .IP * 2 |
8efc0168 MK |
777 | "Input" socket interfaces, when a timeout |
778 | .RB ( SO_RCVTIMEO ) | |
779 | has been set on the socket using | |
4f6d71a1 MK |
780 | .BR setsockopt (2): |
781 | .BR accept (2), | |
782 | .BR recv (2), | |
783 | .BR recvfrom (2), | |
88fb4f09 | 784 | .BR recvmmsg (2) |
8efc0168 | 785 | (also with a non-NULL |
88fb4f09 MK |
786 | .IR timeout |
787 | argument), | |
4f6d71a1 | 788 | and |
8efc0168 MK |
789 | .BR recvmsg (2). |
790 | .IP * | |
791 | "Output" socket interfaces, when a timeout | |
4b139190 | 792 | .RB ( SO_RCVTIMEO ) |
8efc0168 MK |
793 | has been set on the socket using |
794 | .BR setsockopt (2): | |
4f6d71a1 MK |
795 | .BR connect (2), |
796 | .BR send (2), | |
797 | .BR sendto (2), | |
798 | and | |
8efc0168 | 799 | .BR sendmsg (2). |
6248a90b | 800 | .\" FIXME What about sendmmsg()? |
4f6d71a1 | 801 | .IP * |
af3c87d0 MK |
802 | Interfaces used to wait for signals: |
803 | .BR pause (2), | |
804 | .BR sigsuspend (2), | |
743bc395 | 805 | .BR sigtimedwait (2), |
af3c87d0 MK |
806 | and |
807 | .BR sigwaitinfo (2). | |
808 | .IP * | |
809 | File descriptor multiplexing interfaces: | |
810 | .BR epoll_wait (2), | |
811 | .BR epoll_pwait (2), | |
812 | .BR poll (2), | |
813 | .BR ppoll (2), | |
814 | .BR select (2), | |
815 | and | |
816 | .BR pselect (2). | |
817 | .IP * | |
b24473a3 | 818 | System V IPC interfaces: |
af3c87d0 MK |
819 | .\" On some other systems, SA_RESTART does restart these system calls |
820 | .BR msgrcv (2), | |
821 | .BR msgsnd (2), | |
822 | .BR semop (2), | |
823 | and | |
824 | .BR semtimedop (2). | |
825 | .IP * | |
826 | Sleep interfaces: | |
827 | .BR clock_nanosleep (2), | |
828 | .BR nanosleep (2), | |
af3c87d0 MK |
829 | and |
830 | .BR usleep (3). | |
831 | .IP * | |
4b139190 MK |
832 | .BR read (2) |
833 | from an | |
834 | .BR inotify (7) | |
835 | file descriptor. | |
836 | .IP * | |
af3c87d0 | 837 | .BR io_getevents (2). |
495edd81 MK |
838 | .PP |
839 | The | |
840 | .BR sleep (3) | |
841 | function is also never restarted if interrupted by a handler, | |
842 | but gives a success return: the number of seconds remaining to sleep. | |
c634028a | 843 | .SS Interruption of system calls and library functions by stop signals |
48b9ec3f MK |
844 | On Linux, even in the absence of signal handlers, |
845 | certain blocking interfaces can fail with the error | |
846 | .BR EINTR | |
847 | after the process is stopped by one of the stop signals | |
848 | and then resumed via | |
849 | .BR SIGCONT . | |
850 | This behavior is not sanctioned by POSIX.1, and doesn't occur | |
851 | on other systems. | |
852 | ||
853 | The Linux interfaces that display this behavior are: | |
48b9ec3f | 854 | .IP * 2 |
8efc0168 MK |
855 | "Input" socket interfaces, when a timeout |
856 | .RB ( SO_RCVTIMEO ) | |
857 | has been set on the socket using | |
4f6d71a1 MK |
858 | .BR setsockopt (2): |
859 | .BR accept (2), | |
860 | .BR recv (2), | |
861 | .BR recvfrom (2), | |
88fb4f09 | 862 | .BR recvmmsg (2) |
8efc0168 | 863 | (also with a non-NULL |
88fb4f09 MK |
864 | .IR timeout |
865 | argument), | |
4f6d71a1 | 866 | and |
8efc0168 MK |
867 | .BR recvmsg (2). |
868 | .IP * | |
869 | "Output" socket interfaces, when a timeout | |
4b139190 | 870 | .RB ( SO_RCVTIMEO ) |
8efc0168 MK |
871 | has been set on the socket using |
872 | .BR setsockopt (2): | |
4f6d71a1 MK |
873 | .BR connect (2), |
874 | .BR send (2), | |
875 | .BR sendto (2), | |
876 | and | |
4b139190 MK |
877 | .\" FIXME What about sendmmsg()? |
878 | .BR sendmsg (2), | |
879 | if a send timeout | |
880 | .RB ( SO_SNDTIMEO ) | |
881 | has been set. | |
4f6d71a1 | 882 | .IP * 2 |
48b9ec3f MK |
883 | .BR epoll_wait (2), |
884 | .BR epoll_pwait (2). | |
885 | .IP * | |
886 | .BR semop (2), | |
887 | .BR semtimedop (2). | |
888 | .IP * | |
889 | .BR sigtimedwait (2), | |
890 | .BR sigwaitinfo (2). | |
891 | .IP * | |
892 | .BR read (2) | |
893 | from an | |
894 | .BR inotify (7) | |
895 | file descriptor. | |
896 | .IP * | |
897 | Linux 2.6.21 and earlier: | |
898 | .BR futex (2) | |
899 | .BR FUTEX_WAIT , | |
900 | .BR sem_timedwait (3), | |
901 | .BR sem_wait (3). | |
902 | .IP * | |
903 | Linux 2.6.8 and earlier: | |
904 | .BR msgrcv (2), | |
905 | .BR msgsnd (2). | |
906 | .IP * | |
907 | Linux 2.4 and earlier: | |
908 | .BR nanosleep (2). | |
47297adb | 909 | .SH CONFORMING TO |
495edd81 | 910 | POSIX.1, except as noted. |
d396c177 MK |
911 | .\" It must be a *very* long time since this was true: |
912 | .\" .SH BUGS | |
913 | .\" .B SIGIO | |
914 | .\" and | |
915 | .\" .B SIGLOST | |
916 | .\" have the same value. | |
917 | .\" The latter is commented out in the kernel source, but | |
918 | .\" the build process of some software still thinks that | |
919 | .\" signal 29 is | |
920 | .\" .BR SIGLOST . | |
47297adb | 921 | .SH SEE ALSO |
fea681da | 922 | .BR kill (1), |
8c69c923 | 923 | .BR getrlimit (2), |
fea681da | 924 | .BR kill (2), |
d806bc05 | 925 | .BR restart_syscall (2), |
23038eae | 926 | .BR rt_sigqueueinfo (2), |
af3c87d0 MK |
927 | .BR setitimer (2), |
928 | .BR setrlimit (2), | |
929 | .BR sgetmask (2), | |
930 | .BR sigaction (2), | |
8c69c923 | 931 | .BR sigaltstack (2), |
af3c87d0 | 932 | .BR signal (2), |
058c1165 | 933 | .BR signalfd (2), |
af3c87d0 MK |
934 | .BR sigpending (2), |
935 | .BR sigprocmask (2), | |
af3c87d0 MK |
936 | .BR sigsuspend (2), |
937 | .BR sigwaitinfo (2), | |
8c69c923 | 938 | .BR abort (3), |
af3c87d0 | 939 | .BR bsd_signal (3), |
498aad50 | 940 | .BR killpg (3), |
8c69c923 | 941 | .BR longjmp (3), |
36757dc1 | 942 | .BR pthread_sigqueue (3), |
b4cb896f | 943 | .BR raise (3), |
485ab701 | 944 | .BR sigqueue (3), |
af3c87d0 | 945 | .BR sigset (3), |
8c69c923 MK |
946 | .BR sigsetops (3), |
947 | .BR sigvec (3), | |
7c85aa6b | 948 | .BR sigwait (3), |
af3c87d0 MK |
949 | .BR strsignal (3), |
950 | .BR sysv_signal (3), | |
e1a9bc1b | 951 | .BR core (5), |
4f62997d | 952 | .BR proc (5), |
cb066271 | 953 | .BR nptl (7), |
16ca4564 MK |
954 | .BR pthreads (7), |
955 | .BR sigevent (7) |