| blob | 4ba5306c86c39429e4d3a56bb6489810ff7c55bf |
1 '\" t
2 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
3 .\" and Copyright (c) 2002, 2006, 2020 by Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
5 .\" <mtk.manpages@gmail.com>
6 .\"
7 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
8 .\"
9 .\" Modified Sat Jul 24 17:34:08 1993 by Rik Faith (faith@cs.unc.edu)
10 .\" Modified Sun Jan 7 01:41:27 1996 by Andries Brouwer (aeb@cwi.nl)
11 .\" Modified Sun Apr 14 12:02:29 1996 by Andries Brouwer (aeb@cwi.nl)
12 .\" Modified Sat Nov 13 16:28:23 1999 by Andries Brouwer (aeb@cwi.nl)
13 .\" Modified 10 Apr 2002, by Michael Kerrisk <mtk.manpages@gmail.com>
14 .\" Modified 7 Jun 2002, by Michael Kerrisk <mtk.manpages@gmail.com>
15 .\" Added information on real-time signals
16 .\" Modified 13 Jun 2002, by Michael Kerrisk <mtk.manpages@gmail.com>
17 .\" Noted that SIGSTKFLT is in fact unused
18 .\" 2004-12-03, Modified mtk, added notes on RLIMIT_SIGPENDING
19 .\" 2006-04-24, mtk, Added text on changing signal dispositions,
20 .\" signal mask, and pending signals.
21 .\" 2008-07-04, mtk:
22 .\" Added section on system call restarting (SA_RESTART)
23 .\" Added section on stop/cont signals interrupting syscalls.
24 .\" 2008-10-05, mtk: various additions
25 .\"
26 .TH signal 7 (date) "Linux man-pages (unreleased)"
27 .SH NAME
28 signal \- overview of signals
29 .SH DESCRIPTION
30 Linux supports both POSIX reliable signals (hereinafter
31 "standard signals") and POSIX real-time signals.
32 .SS Signal dispositions
33 Each signal has a current
34 .IR disposition ,
35 which determines how the process behaves when it is delivered
36 the signal.
37 .P
38 The entries in the "Action" column of the table below specify
39 the default disposition for each signal, as follows:
40 .TP
41 Term
42 Default action is to terminate the process.
43 .TP
44 Ign
45 Default action is to ignore the signal.
46 .TP
47 Core
48 Default action is to terminate the process and dump core (see
49 .BR core (5)).
50 .TP
51 Stop
52 Default action is to stop the process.
53 .TP
54 Cont
55 Default action is to continue the process if it is currently stopped.
56 .P
57 A process can change the disposition of a signal using
58 .BR sigaction (2)
59 or
60 .BR signal (2).
61 (The latter is less portable when establishing a signal handler;
62 see
63 .BR signal (2)
64 for details.)
65 Using these system calls, a process can elect one of the
66 following behaviors to occur on delivery of the signal:
67 perform the default action; ignore the signal;
68 or catch the signal with a
69 .IR "signal handler" ,
70 a programmer-defined function that is automatically invoked
71 when the signal is delivered.
72 .P
73 By default, a signal handler is invoked on the
74 normal process stack.
75 It is possible to arrange that the signal handler
76 uses an alternate stack; see
77 .BR sigaltstack (2)
78 for a discussion of how to do this and when it might be useful.
79 .P
80 The signal disposition is a per-process attribute:
81 in a multithreaded application, the disposition of a
82 particular signal is the same for all threads.
83 .P
84 A child created via
85 .BR fork (2)
86 inherits a copy of its parent's signal dispositions.
87 During an
88 .BR execve (2),
89 the dispositions of handled signals are reset to the default;
90 the dispositions of ignored signals are left unchanged.
91 .SS Sending a signal
92 The following system calls and library functions allow
93 the caller to send a signal:
94 .TP
95 .BR raise (3)
96 Sends a signal to the calling thread.
97 .TP
98 .BR kill (2)
99 Sends a signal to a specified process,
100 to all members of a specified process group,
101 or to all processes on the system.
102 .TP
103 .BR pidfd_send_signal (2)
104 Sends a signal to a process identified by a PID file descriptor.
105 .TP
106 .BR killpg (3)
107 Sends a signal to all of the members of a specified process group.
108 .TP
109 .BR pthread_kill (3)
110 Sends a signal to a specified POSIX thread in the same process as
111 the caller.
112 .TP
113 .BR tgkill (2)
114 Sends a signal to a specified thread within a specific process.
115 (This is the system call used to implement
116 .BR pthread_kill (3).)
117 .TP
118 .BR sigqueue (3)
119 Sends a real-time signal with accompanying data to a specified process.
120 .SS Waiting for a signal to be caught
121 The following system calls suspend execution of the calling
122 thread until a signal is caught
123 (or an unhandled signal terminates the process):
124 .TP
125 .BR pause (2)
126 Suspends execution until any signal is caught.
127 .TP
128 .BR sigsuspend (2)
129 Temporarily changes the signal mask (see below) and suspends
130 execution until one of the unmasked signals is caught.
131 .\"
132 .SS Synchronously accepting a signal
133 Rather than asynchronously catching a signal via a signal handler,
134 it is possible to synchronously accept the signal, that is,
135 to block execution until the signal is delivered,
136 at which point the kernel returns information about the
137 signal to the caller.
138 There are two general ways to do this:
139 .IP \[bu] 3
140 .BR sigwaitinfo (2),
141 .BR sigtimedwait (2),
142 and
143 .BR sigwait (3)
144 suspend execution until one of the signals in a specified
145 set is delivered.
146 Each of these calls returns information about the delivered signal.
147 .IP \[bu]
148 .BR signalfd (2)
149 returns a file descriptor that can be used to read information
150 about signals that are delivered to the caller.
151 Each
152 .BR read (2)
153 from this file descriptor blocks until one of the signals
154 in the set specified in the
155 .BR signalfd (2)
156 call is delivered to the caller.
157 The buffer returned by
158 .BR read (2)
159 contains a structure describing the signal.
160 .SS Signal mask and pending signals
161 A signal may be
162 .IR blocked ,
163 which means that it will not be delivered until it is later unblocked.
164 Between the time when it is generated and when it is delivered
165 a signal is said to be
166 .IR pending .
167 .P
168 Each thread in a process has an independent
169 .IR "signal mask" ,
170 which indicates the set of signals that the thread is currently blocking.
171 A thread can manipulate its signal mask using
172 .BR pthread_sigmask (3).
173 In a traditional single-threaded application,
174 .BR sigprocmask (2)
175 can be used to manipulate the signal mask.
176 .P
177 A child created via
178 .BR fork (2)
179 inherits a copy of its parent's signal mask;
180 the signal mask is preserved across
181 .BR execve (2).
182 .P
183 A signal may be process-directed or thread-directed.
184 A process-directed signal is one that is targeted at (and thus pending for)
185 the process as a whole.
186 A signal may be process-directed
187 because it was generated by the kernel for reasons
188 other than a hardware exception, or because it was sent using
189 .BR kill (2)
190 or
191 .BR sigqueue (3).
192 A thread-directed signal is one that is targeted at a specific thread.
193 A signal may be thread-directed because it was generated as a consequence
194 of executing a specific machine-language instruction
195 that triggered a hardware exception (e.g.,
196 .B SIGSEGV
197 for an invalid memory access, or
198 .B SIGFPE
199 for a math error), or because it was
200 targeted at a specific thread using
201 interfaces such as
202 .BR tgkill (2)
203 or
204 .BR pthread_kill (3).
205 .P
206 A process-directed signal may be delivered to any one of the
207 threads that does not currently have the signal blocked.
208 .\" Joseph C. Sible notes:
209 .\" On Linux, if the main thread has the signal unblocked, then the kernel
210 .\" will always deliver the signal there, citing this kernel code
211 .\"
212 .\" Per this comment in kernel/signal.c since time immemorial:
213 .\"
214 .\" /*
215 .\" * Now find a thread we can wake up to take the signal off the queue.
216 .\" *
217 .\" * If the main thread wants the signal, it gets first crack.
218 .\" * Probably the least surprising to the average bear.
219 .\" */
220 .\"
221 .\" But this does not mean the signal will be delivered only in the
222 .\" main thread, since if a handler is already executing in the main thread
223 .\" (and thus the signal is blocked in that thread), then a further
224 .\" might be delivered in a different thread.
225 .\"
226 If more than one of the threads has the signal unblocked, then the
227 kernel chooses an arbitrary thread to which to deliver the signal.
228 .P
229 A thread can obtain the set of signals that it currently has pending
230 using
231 .BR sigpending (2).
232 This set will consist of the union of the set of pending
233 process-directed signals and the set of signals pending for
234 the calling thread.
235 .P
236 A child created via
237 .BR fork (2)
238 initially has an empty pending signal set;
239 the pending signal set is preserved across an
240 .BR execve (2).
241 .\"
242 .SS Execution of signal handlers
243 Whenever there is a transition from kernel-mode to user-mode execution
244 (e.g., on return from a system call or scheduling of a thread onto the CPU),
245 the kernel checks whether there is a pending unblocked signal
246 for which the process has established a signal handler.
247 If there is such a pending signal, the following steps occur:
248 .IP (1) 5
249 The kernel performs the necessary preparatory steps for execution of
250 the signal handler:
251 .RS
252 .IP (1.1) 7
253 The signal is removed from the set of pending signals.
254 .IP (1.2)
255 If the signal handler was installed by a call to
256 .BR sigaction (2)
257 that specified the
258 .B SA_ONSTACK
259 flag and the thread has defined an alternate signal stack (using
260 .BR sigaltstack (2)),
261 then that stack is installed.
262 .IP (1.3)
263 Various pieces of signal-related context are saved
264 into a special frame that is created on the stack.
265 The saved information includes:
266 .RS
267 .IP \[bu] 3
268 the program counter register
269 (i.e., the address of the next instruction in the main program that
270 should be executed when the signal handler returns);
271 .IP \[bu]
272 architecture-specific register state required for resuming the
273 interrupted program;
274 .IP \[bu]
275 the thread's current signal mask;
276 .IP \[bu]
277 the thread's alternate signal stack settings.
278 .RE
279 .IP
280 (If the signal handler was installed using the
281 .BR sigaction (2)
282 .B SA_SIGINFO
283 flag, then the above information is accessible via the
284 .I ucontext_t
285 object that is pointed to by the third argument of the signal handler.)
286 .IP (1.4)
287 Any signals specified in
288 .I act\->sa_mask
289 when registering the handler with
290 .BR sigprocmask (2)
291 are added to the thread's signal mask.
292 The signal being delivered is also
293 added to the signal mask, unless
294 .B SA_NODEFER
295 was specified when registering the handler.
296 These signals are thus blocked while the handler executes.
297 .RE
298 .IP (2)
299 The kernel constructs a frame for the signal handler on the stack.
300 The kernel sets the program counter for the thread to point to the first
301 instruction of the signal handler function,
302 and configures the return address for that function to point to a piece
303 of user-space code known as the signal trampoline (described in
304 .BR sigreturn (2)).
305 .IP (3)
306 The kernel passes control back to user-space, where execution
307 commences at the start of the signal handler function.
308 .IP (4)
309 When the signal handler returns, control passes to the signal trampoline code.
310 .IP (5)
311 The signal trampoline calls
312 .BR sigreturn (2),
313 a system call that uses the information in the stack frame created in step 1
314 to restore the thread to its state before the signal handler was
315 called.
316 The thread's signal mask and alternate signal stack settings
317 are restored as part of this procedure.
318 Upon completion of the call to
319 .BR sigreturn (2),
320 the kernel transfers control back to user space,
321 and the thread recommences execution at the point where it was
322 interrupted by the signal handler.
323 .P
324 Note that if the signal handler does not return
325 (e.g., control is transferred out of the handler using
326 .BR siglongjmp (3),
327 or the handler executes a new program with
328 .BR execve (2)),
329 then the final step is not performed.
330 In particular, in such scenarios it is the programmer's responsibility
331 to restore the state of the signal mask (using
332 .BR sigprocmask (2)),
333 if it is desired to unblock the signals that were blocked on entry
334 to the signal handler.
335 (Note that
336 .BR siglongjmp (3)
337 may or may not restore the signal mask, depending on the
338 .I savesigs
339 value that was specified in the corresponding call to
340 .BR sigsetjmp (3).)
341 .P
342 From the kernel's point of view,
343 execution of the signal handler code is exactly the same as the execution
344 of any other user-space code.
345 That is to say, the kernel does not record any special state information
346 indicating that the thread is currently executing inside a signal handler.
347 All necessary state information is maintained in user-space registers
348 and the user-space stack.
349 The depth to which nested signal handlers may be invoked is thus
350 limited only by the user-space stack (and sensible software design!).
351 .\"
352 .SS Standard signals
353 Linux supports the standard signals listed below.
354 The second column of the table indicates which standard (if any)
355 specified the signal: "P1990" indicates that the signal is described
356 in the original POSIX.1-1990 standard;
357 "P2001" indicates that the signal was added in SUSv2 and POSIX.1-2001.
358 .TS
359 l c c l
360 ____
361 lB c c l.
362 Signal Standard Action Comment
363 SIGABRT P1990 Core Abort signal from \fBabort\fP(3)
364 SIGALRM P1990 Term Timer signal from \fBalarm\fP(2)
365 SIGBUS P2001 Core Bus error (bad memory access)
366 SIGCHLD P1990 Ign Child stopped or terminated
367 SIGCLD \- Ign A synonym for \fBSIGCHLD\fP
368 SIGCONT P1990 Cont Continue if stopped
369 SIGEMT \- Term Emulator trap
370 SIGFPE P1990 Core Floating-point exception
371 SIGHUP P1990 Term Hangup detected on controlling terminal
372 or death of controlling process
373 SIGILL P1990 Core Illegal Instruction
374 SIGINFO \- A synonym for \fBSIGPWR\fP
375 SIGINT P1990 Term Interrupt from keyboard
376 SIGIO \- Term I/O now possible (4.2BSD)
377 SIGIOT \- Core IOT trap. A synonym for \fBSIGABRT\fP
378 SIGKILL P1990 Term Kill signal
379 SIGLOST \- Term File lock lost (unused)
380 SIGPIPE P1990 Term Broken pipe: write to pipe with no
381 readers; see \fBpipe\fP(7)
382 SIGPOLL P2001 Term Pollable event (Sys V);
383 synonym for \fBSIGIO\fP
384 SIGPROF P2001 Term Profiling timer expired
385 SIGPWR \- Term Power failure (System V)
386 SIGQUIT P1990 Core Quit from keyboard
387 SIGSEGV P1990 Core Invalid memory reference
388 SIGSTKFLT \- Term Stack fault on coprocessor (unused)
389 SIGSTOP P1990 Stop Stop process
390 SIGTSTP P1990 Stop Stop typed at terminal
391 SIGSYS P2001 Core Bad system call (SVr4);
392 see also \fBseccomp\fP(2)
393 SIGTERM P1990 Term Termination signal
394 SIGTRAP P2001 Core Trace/breakpoint trap
395 SIGTTIN P1990 Stop Terminal input for background process
396 SIGTTOU P1990 Stop Terminal output for background process
397 SIGUNUSED \- Core Synonymous with \fBSIGSYS\fP
398 SIGURG P2001 Ign Urgent condition on socket (4.2BSD)
399 SIGUSR1 P1990 Term User-defined signal 1
400 SIGUSR2 P1990 Term User-defined signal 2
401 SIGVTALRM P2001 Term Virtual alarm clock (4.2BSD)
402 SIGXCPU P2001 Core CPU time limit exceeded (4.2BSD);
403 see \fBsetrlimit\fP(2)
404 SIGXFSZ P2001 Core File size limit exceeded (4.2BSD);
405 see \fBsetrlimit\fP(2)
406 SIGWINCH \- Ign Window resize signal (4.3BSD, Sun)
407 .TE
408 .P
409 The signals
410 .B SIGKILL
411 and
412 .B SIGSTOP
413 cannot be caught, blocked, or ignored.
414 .P
415 Up to and including Linux 2.2, the default behavior for
416 .BR SIGSYS ", " SIGXCPU ", " SIGXFSZ ,
417 and (on architectures other than SPARC and MIPS)
418 .B SIGBUS
419 was to terminate the process (without a core dump).
420 (On some other UNIX systems the default action for
421 .BR SIGXCPU " and " SIGXFSZ
422 is to terminate the process without a core dump.)
423 Linux 2.4 conforms to the POSIX.1-2001 requirements for these signals,
424 terminating the process with a core dump.
425 .P
426 .B SIGEMT
427 is not specified in POSIX.1-2001, but nevertheless appears
428 on most other UNIX systems,
429 where its default action is typically to terminate
430 the process with a core dump.
431 .P
432 .B SIGPWR
433 (which is not specified in POSIX.1-2001) is typically ignored
434 by default on those other UNIX systems where it appears.
435 .P
436 .B SIGIO
437 (which is not specified in POSIX.1-2001) is ignored by default
438 on several other UNIX systems.
439 .\"
440 .SS Queueing and delivery semantics for standard signals
441 If multiple standard signals are pending for a process,
442 the order in which the signals are delivered is unspecified.
443 .P
444 Standard signals do not queue.
445 If multiple instances of a standard signal are generated while
446 that signal is blocked,
447 then only one instance of the signal is marked as pending
448 (and the signal will be delivered just once when it is unblocked).
449 In the case where a standard signal is already pending, the
450 .I siginfo_t
451 structure (see
452 .BR sigaction (2))
453 associated with that signal is not overwritten
454 on arrival of subsequent instances of the same signal.
455 Thus, the process will receive the information
456 associated with the first instance of the signal.
457 .\"
458 .SS Signal numbering for standard signals
459 The numeric value for each signal is given in the table below.
460 As shown in the table, many signals have different numeric values
461 on different architectures.
462 The first numeric value in each table row shows the signal number
463 on x86, ARM, and most other architectures;
464 the second value is for Alpha and SPARC; the third is for MIPS;
465 and the last is for PARISC.
466 A dash (\-) denotes that a signal is absent on the corresponding architecture.
467 .TS
468 l c c c c l
469 l c c c c l
470 ______
471 lB c c c c l.
472 Signal x86/ARM Alpha/ MIPS PARISC Notes
473 most others SPARC
474 SIGHUP \01 \01 \01 \01
475 SIGINT \02 \02 \02 \02
476 SIGQUIT \03 \03 \03 \03
477 SIGILL \04 \04 \04 \04
478 SIGTRAP \05 \05 \05 \05
479 SIGABRT \06 \06 \06 \06
480 SIGIOT \06 \06 \06 \06
481 SIGBUS \07 10 10 10
482 SIGEMT \- \07 \07 -
483 SIGFPE \08 \08 \08 \08
484 SIGKILL \09 \09 \09 \09
485 SIGUSR1 10 30 16 16
486 SIGSEGV 11 11 11 11
487 SIGUSR2 12 31 17 17
488 SIGPIPE 13 13 13 13
489 SIGALRM 14 14 14 14
490 SIGTERM 15 15 15 15
491 SIGSTKFLT 16 \- \- \07
492 SIGCHLD 17 20 18 18
493 SIGCLD \- \- 18 \-
494 SIGCONT 18 19 25 26
495 SIGSTOP 19 17 23 24
496 SIGTSTP 20 18 24 25
497 SIGTTIN 21 21 26 27
498 SIGTTOU 22 22 27 28
499 SIGURG 23 16 21 29
500 SIGXCPU 24 24 30 12
501 SIGXFSZ 25 25 31 30
502 SIGVTALRM 26 26 28 20
503 SIGPROF 27 27 29 21
504 SIGWINCH 28 28 20 23
505 SIGIO 29 23 22 22
506 SIGPOLL Same as SIGIO
507 SIGPWR 30 29/\- 19 19
508 SIGINFO \- 29/\- \- \-
509 SIGLOST \- \-/29 \- \-
510 SIGSYS 31 12 12 31
511 SIGUNUSED 31 \- \- 31
512 .TE
513 .P
514 Note the following:
515 .IP \[bu] 3
516 Where defined,
517 .B SIGUNUSED
518 is synonymous with
519 .BR SIGSYS .
520 Since glibc 2.26,
521 .B SIGUNUSED
522 is no longer defined on any architecture.
523 .IP \[bu]
524 Signal 29 is
525 .BR SIGINFO / SIGPWR
526 (synonyms for the same value) on Alpha but
527 .B SIGLOST
528 on SPARC.
529 .\"
530 .SS Real-time signals
531 Starting with Linux 2.2,
532 Linux supports real-time signals as originally defined in the POSIX.1b
533 real-time extensions (and now included in POSIX.1-2001).
534 The range of supported real-time signals is defined by the macros
535 .B SIGRTMIN
536 and
537 .BR SIGRTMAX .
538 POSIX.1-2001 requires that an implementation support at least
539 .B _POSIX_RTSIG_MAX
540 (8) real-time signals.
541 .P
542 The Linux kernel supports a range of 33 different real-time
543 signals, numbered 32 to 64.
544 However, the glibc POSIX threads implementation internally uses
545 two (for NPTL) or three (for LinuxThreads) real-time signals
546 (see
547 .BR pthreads (7)),
548 and adjusts the value of
549 .B SIGRTMIN
550 suitably (to 34 or 35).
551 Because the range of available real-time signals varies according
552 to the glibc threading implementation (and this variation can occur
553 at run time according to the available kernel and glibc),
554 and indeed the range of real-time signals varies across UNIX systems,
555 programs should
556 .IR "never refer to real-time signals using hard-coded numbers" ,
557 but instead should always refer to real-time signals using the notation
558 .BR SIGRTMIN +n,
559 and include suitable (run-time) checks that
560 .BR SIGRTMIN +n
561 does not exceed
562 .BR SIGRTMAX .
563 .P
564 Unlike standard signals, real-time signals have no predefined meanings:
565 the entire set of real-time signals can be used for application-defined
566 purposes.
567 .P
568 The default action for an unhandled real-time signal is to terminate the
569 receiving process.
570 .P
571 Real-time signals are distinguished by the following:
572 .IP \[bu] 3
573 Multiple instances of real-time signals can be queued.
574 By contrast, if multiple instances of a standard signal are delivered
575 while that signal is currently blocked, then only one instance is queued.
576 .IP \[bu]
577 If the signal is sent using
578 .BR sigqueue (3),
579 an accompanying value (either an integer or a pointer) can be sent
580 with the signal.
581 If the receiving process establishes a handler for this signal using the
582 .B SA_SIGINFO
583 flag to
584 .BR sigaction (2),
585 then it can obtain this data via the
586 .I si_value
587 field of the
588 .I siginfo_t
589 structure passed as the second argument to the handler.
590 Furthermore, the
591 .I si_pid
592 and
593 .I si_uid
594 fields of this structure can be used to obtain the PID
595 and real user ID of the process sending the signal.
596 .IP \[bu]
597 Real-time signals are delivered in a guaranteed order.
598 Multiple real-time signals of the same type are delivered in the order
599 they were sent.
600 If different real-time signals are sent to a process, they are delivered
601 starting with the lowest-numbered signal.
602 (I.e., low-numbered signals have highest priority.)
603 By contrast, if multiple standard signals are pending for a process,
604 the order in which they are delivered is unspecified.
605 .P
606 If both standard and real-time signals are pending for a process,
607 POSIX leaves it unspecified which is delivered first.
608 Linux, like many other implementations, gives priority
609 to standard signals in this case.
610 .P
611 According to POSIX, an implementation should permit at least
612 .B _POSIX_SIGQUEUE_MAX
613 (32) real-time signals to be queued to
614 a process.
615 However, Linux does things differently.
616 Up to and including Linux 2.6.7, Linux imposes
617 a system-wide limit on the number of queued real-time signals
618 for all processes.
619 This limit can be viewed and (with privilege) changed via the
620 .I /proc/sys/kernel/rtsig\-max
621 file.
622 A related file,
623 .IR /proc/sys/kernel/rtsig\-nr ,
624 can be used to find out how many real-time signals are currently queued.
625 In Linux 2.6.8, these
626 .I /proc
627 interfaces were replaced by the
628 .B RLIMIT_SIGPENDING
629 resource limit, which specifies a per-user limit for queued
630 signals; see
631 .BR setrlimit (2)
632 for further details.
633 .P
634 The addition of real-time signals required the widening
635 of the signal set structure
636 .RI ( sigset_t )
637 from 32 to 64 bits.
638 Consequently, various system calls were superseded by new system calls
639 that supported the larger signal sets.
640 The old and new system calls are as follows:
641 .TS
642 lb lb
643 l l.
644 Linux 2.0 and earlier Linux 2.2 and later
645 \fBsigaction\fP(2) \fBrt_sigaction\fP(2)
646 \fBsigpending\fP(2) \fBrt_sigpending\fP(2)
647 \fBsigprocmask\fP(2) \fBrt_sigprocmask\fP(2)
648 \fBsigreturn\fP(2) \fBrt_sigreturn\fP(2)
649 \fBsigsuspend\fP(2) \fBrt_sigsuspend\fP(2)
650 \fBsigtimedwait\fP(2) \fBrt_sigtimedwait\fP(2)
651 .TE
652 .\"
653 .SS Interruption of system calls and library functions by signal handlers
654 If a signal handler is invoked while a system call or library
655 function call is blocked, then either:
656 .IP \[bu] 3
657 the call is automatically restarted after the signal handler returns; or
658 .IP \[bu]
659 the call fails with the error
660 .BR EINTR .
661 .P
662 Which of these two behaviors occurs depends on the interface and
663 whether or not the signal handler was established using the
664 .B SA_RESTART
665 flag (see
666 .BR sigaction (2)).
667 The details vary across UNIX systems;
668 below, the details for Linux.
669 .P
670 If a blocked call to one of the following interfaces is interrupted
671 by a signal handler, then the call is automatically restarted
672 after the signal handler returns if the
673 .B SA_RESTART
674 flag was used; otherwise the call fails with the error
675 .BR EINTR :
676 .\" The following system calls use ERESTARTSYS,
677 .\" so that they are restartable
678 .IP \[bu] 3
679 .BR read (2),
680 .BR readv (2),
681 .BR write (2),
682 .BR writev (2),
683 and
684 .BR ioctl (2)
685 calls on "slow" devices.
686 A "slow" device is one where the I/O call may block for an
687 indefinite time, for example, a terminal, pipe, or socket.
688 If an I/O call on a slow device has already transferred some
689 data by the time it is interrupted by a signal handler,
690 then the call will return a success status
691 (normally, the number of bytes transferred).
692 Note that a (local) disk is not a slow device according to this definition;
693 I/O operations on disk devices are not interrupted by signals.
694 .IP \[bu]
695 .BR open (2),
696 if it can block (e.g., when opening a FIFO; see
697 .BR fifo (7)).
698 .IP \[bu]
699 .BR wait (2),
700 .BR wait3 (2),
701 .BR wait4 (2),
702 .BR waitid (2),
703 and
704 .BR waitpid (2).
705 .IP \[bu]
706 Socket interfaces:
707 .\" If a timeout (setsockopt()) is in effect on the socket, then these
708 .\" system calls switch to using EINTR. Consequently, they and are not
709 .\" automatically restarted, and they show the stop/cont behavior
710 .\" described below. (Verified from Linux 2.6.26 source, and by experiment; mtk)
711 .BR accept (2),
712 .BR connect (2),
713 .BR recv (2),
714 .BR recvfrom (2),
715 .BR recvmmsg (2),
716 .BR recvmsg (2),
717 .BR send (2),
718 .BR sendto (2),
719 and
720 .BR sendmsg (2),
721 .\" FIXME What about sendmmsg()?
722 unless a timeout has been set on the socket (see below).
723 .IP \[bu]
724 File locking interfaces:
725 .BR flock (2)
726 and
727 the
728 .B F_SETLKW
729 and
730 .B F_OFD_SETLKW
731 operations of
732 .BR fcntl (2)
733 .IP \[bu]
734 POSIX message queue interfaces:
735 .BR mq_receive (3),
736 .BR mq_timedreceive (3),
737 .BR mq_send (3),
738 and
739 .BR mq_timedsend (3).
740 .IP \[bu]
741 .BR futex (2)
742 .B FUTEX_WAIT
743 (since Linux 2.6.22;
744 .\" commit 72c1bbf308c75a136803d2d76d0e18258be14c7a
745 beforehand, always failed with
746 .BR EINTR ).
747 .IP \[bu]
748 .BR getrandom (2).
749 .IP \[bu]
750 .BR pthread_mutex_lock (3),
751 .BR pthread_cond_wait (3),
752 and related APIs.
753 .IP \[bu]
754 .BR futex (2)
755 .BR FUTEX_WAIT_BITSET .
756 .IP \[bu]
757 POSIX semaphore interfaces:
758 .BR sem_wait (3)
759 and
760 .BR sem_timedwait (3)
761 (since Linux 2.6.22;
762 .\" as a consequence of the 2.6.22 changes in the futex() implementation
763 beforehand, always failed with
764 .BR EINTR ).
765 .IP \[bu]
766 .BR read (2)
767 from an
768 .BR inotify (7)
769 file descriptor
770 (since Linux 3.8;
771 .\" commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06
772 beforehand, always failed with
773 .BR EINTR ).
774 .P
775 The following interfaces are never restarted after
776 being interrupted by a signal handler,
777 regardless of the use of
778 .BR SA_RESTART ;
779 they always fail with the error
780 .B EINTR
781 when interrupted by a signal handler:
782 .\" These are the system calls that give EINTR or ERESTARTNOHAND
783 .\" on interruption by a signal handler.
784 .IP \[bu] 3
785 "Input" socket interfaces, when a timeout
786 .RB ( SO_RCVTIMEO )
787 has been set on the socket using
788 .BR setsockopt (2):
789 .BR accept (2),
790 .BR recv (2),
791 .BR recvfrom (2),
792 .BR recvmmsg (2)
793 (also with a non-NULL
794 .I timeout
795 argument),
796 and
797 .BR recvmsg (2).
798 .IP \[bu]
799 "Output" socket interfaces, when a timeout
800 .RB ( SO_RCVTIMEO )
801 has been set on the socket using
802 .BR setsockopt (2):
803 .BR connect (2),
804 .BR send (2),
805 .BR sendto (2),
806 and
807 .BR sendmsg (2).
808 .\" FIXME What about sendmmsg()?
809 .IP \[bu]
810 Interfaces used to wait for signals:
811 .BR pause (2),
812 .BR sigsuspend (2),
813 .BR sigtimedwait (2),
814 and
815 .BR sigwaitinfo (2).
816 .IP \[bu]
817 File descriptor multiplexing interfaces:
818 .BR epoll_wait (2),
819 .BR epoll_pwait (2),
820 .BR poll (2),
821 .BR ppoll (2),
822 .BR select (2),
823 and
824 .BR pselect (2).
825 .IP \[bu]
826 System V IPC interfaces:
827 .\" On some other systems, SA_RESTART does restart these system calls
828 .BR msgrcv (2),
829 .BR msgsnd (2),
830 .BR semop (2),
831 and
832 .BR semtimedop (2).
833 .IP \[bu]
834 Sleep interfaces:
835 .BR clock_nanosleep (2),
836 .BR nanosleep (2),
837 and
838 .BR usleep (3).
839 .IP \[bu]
840 .BR io_getevents (2).
841 .P
842 The
843 .BR sleep (3)
844 function is also never restarted if interrupted by a handler,
845 but gives a success return: the number of seconds remaining to sleep.
846 .P
847 In certain circumstances, the
848 .BR seccomp (2)
849 user-space notification feature can lead to restarting of system calls
850 that would otherwise never be restarted by
851 .BR SA_RESTART ;
852 for details, see
853 .BR seccomp_unotify (2).
854 .\"
855 .SS Interruption of system calls and library functions by stop signals
856 On Linux, even in the absence of signal handlers,
857 certain blocking interfaces can fail with the error
858 .B EINTR
859 after the process is stopped by one of the stop signals
860 and then resumed via
861 .BR SIGCONT .
862 This behavior is not sanctioned by POSIX.1, and doesn't occur
863 on other systems.
864 .P
865 The Linux interfaces that display this behavior are:
866 .IP \[bu] 3
867 "Input" socket interfaces, when a timeout
868 .RB ( SO_RCVTIMEO )
869 has been set on the socket using
870 .BR setsockopt (2):
871 .BR accept (2),
872 .BR recv (2),
873 .BR recvfrom (2),
874 .BR recvmmsg (2)
875 (also with a non-NULL
876 .I timeout
877 argument),
878 and
879 .BR recvmsg (2).
880 .IP \[bu]
881 "Output" socket interfaces, when a timeout
882 .RB ( SO_RCVTIMEO )
883 has been set on the socket using
884 .BR setsockopt (2):
885 .BR connect (2),
886 .BR send (2),
887 .BR sendto (2),
888 and
889 .\" FIXME What about sendmmsg()?
890 .BR sendmsg (2),
891 if a send timeout
892 .RB ( SO_SNDTIMEO )
893 has been set.
894 .IP \[bu]
895 .BR epoll_wait (2),
896 .BR epoll_pwait (2).
897 .IP \[bu]
898 .BR semop (2),
899 .BR semtimedop (2).
900 .IP \[bu]
901 .BR sigtimedwait (2),
902 .BR sigwaitinfo (2).
903 .IP \[bu]
904 Linux 3.7 and earlier:
905 .BR read (2)
906 from an
907 .BR inotify (7)
908 file descriptor
909 .\" commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06
910 .IP \[bu]
911 Linux 2.6.21 and earlier:
912 .BR futex (2)
913 .BR FUTEX_WAIT ,
914 .BR sem_timedwait (3),
915 .BR sem_wait (3).
916 .IP \[bu]
917 Linux 2.6.8 and earlier:
918 .BR msgrcv (2),
919 .BR msgsnd (2).
920 .IP \[bu]
921 Linux 2.4 and earlier:
922 .BR nanosleep (2).
923 .SH STANDARDS
924 POSIX.1, except as noted.
925 .SH NOTES
926 For a discussion of async-signal-safe functions, see
927 .BR signal\-safety (7).
928 .P
929 The
930 .IR /proc/ pid /task/ tid /status
931 file contains various fields that show the signals
932 that a thread is blocking
933 .RI ( SigBlk ),
934 catching
935 .RI ( SigCgt ),
936 or ignoring
937 .RI ( SigIgn ).
938 (The set of signals that are caught or ignored will be the same
939 across all threads in a process.)
940 Other fields show the set of pending signals that are directed to the thread
941 .RI ( SigPnd )
942 as well as the set of pending signals that are directed
943 to the process as a whole
944 .RI ( ShdPnd ).
945 The corresponding fields in
946 .IR /proc/ pid /status
947 show the information for the main thread.
948 See
949 .BR proc (5)
950 for further details.
951 .SH BUGS
952 There are six signals that can be delivered
953 as a consequence of a hardware exception:
954 .BR SIGBUS ,
955 .BR SIGEMT ,
956 .BR SIGFPE ,
957 .BR SIGILL ,
958 .BR SIGSEGV ,
959 and
960 .BR SIGTRAP .
961 Which of these signals is delivered,
962 for any given hardware exception,
963 is not documented and does not always make sense.
964 .P
965 For example, an invalid memory access that causes delivery of
966 .B SIGSEGV
967 on one CPU architecture may cause delivery of
968 .B SIGBUS
969 on another architecture, or vice versa.
970 .P
971 For another example, using the x86
972 .I int
973 instruction with a forbidden argument
974 (any number other than 3 or 128)
975 causes delivery of
976 .BR SIGSEGV ,
977 even though
978 .B SIGILL
979 would make more sense,
980 because of how the CPU reports the forbidden operation to the kernel.
981 .SH SEE ALSO
982 .BR kill (1),
983 .BR clone (2),
984 .BR getrlimit (2),
985 .BR kill (2),
986 .BR pidfd_send_signal (2),
987 .BR restart_syscall (2),
988 .BR rt_sigqueueinfo (2),
989 .BR setitimer (2),
990 .BR setrlimit (2),
991 .BR sgetmask (2),
992 .BR sigaction (2),
993 .BR sigaltstack (2),
994 .BR signal (2),
995 .BR signalfd (2),
996 .BR sigpending (2),
997 .BR sigprocmask (2),
998 .BR sigreturn (2),
999 .BR sigsuspend (2),
1000 .BR sigwaitinfo (2),
1001 .BR abort (3),
1002 .BR bsd_signal (3),
1003 .BR killpg (3),
1004 .BR longjmp (3),
1005 .BR pthread_sigqueue (3),
1006 .BR raise (3),
1007 .BR sigqueue (3),
1008 .BR sigset (3),
1009 .BR sigsetops (3),
1010 .BR sigvec (3),
1011 .BR sigwait (3),
1012 .BR strsignal (3),
1013 .BR swapcontext (3),
1014 .BR sysv_signal (3),
1015 .BR core (5),
1016 .BR proc (5),
1017 .BR nptl (7),
1018 .BR pthreads (7),
1019 .BR sigevent (3type)