Debian Codegraph @

upstream/debian-trixie/man7/signal.7

raw
1 '\" t
2 .\" Copyright (c) 1993 by Thomas Koenig ([email protected])
3 .\" and Copyright (c) 2002, 2006, 2020 by Michael Kerrisk <[email protected]>
4 .\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
5 .\" <[email protected]>
6 .\"
7 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
8 .\"
9 .\" Modified Sat Jul 24 17:34:08 1993 by Rik Faith ([email protected])
10 .\" Modified Sun Jan 7 01:41:27 1996 by Andries Brouwer ([email protected])
11 .\" Modified Sun Apr 14 12:02:29 1996 by Andries Brouwer ([email protected])
12 .\" Modified Sat Nov 13 16:28:23 1999 by Andries Brouwer ([email protected])
13 .\" Modified 10 Apr 2002, by Michael Kerrisk <[email protected]>
14 .\" Modified 7 Jun 2002, by Michael Kerrisk <[email protected]>
15 .\" Added information on real-time signals
16 .\" Modified 13 Jun 2002, by Michael Kerrisk <[email protected]>
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 2024-06-17 "Linux man-pages 6.9.1"
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 This object reflects the state at which the signal is delivered,
287 rather than in the handler;
288 for example,
289 the mask of blocked signals stored in this object
290 will not contain the mask of new signals blocked through
291 .BR sigaction (2).
292 .IP (1.4)
293 Any signals specified in
294 .I act\->sa_mask
295 when registering the handler with
296 .BR sigaction (2)
297 are added to the thread's signal mask.
298 The signal being delivered is also
299 added to the signal mask, unless
300 .B SA_NODEFER
301 was specified when registering the handler.
302 These signals are thus blocked while the handler executes.
303 .RE
304 .IP (2)
305 The kernel constructs a frame for the signal handler on the stack.
306 The kernel sets the program counter for the thread to point to the first
307 instruction of the signal handler function,
308 and configures the return address for that function to point to a piece
309 of user-space code known as the signal trampoline (described in
310 .BR sigreturn (2)).
311 .IP (3)
312 The kernel passes control back to user-space, where execution
313 commences at the start of the signal handler function.
314 .IP (4)
315 When the signal handler returns, control passes to the signal trampoline code.
316 .IP (5)
317 The signal trampoline calls
318 .BR sigreturn (2),
319 a system call that uses the information in the stack frame created in step 1
320 to restore the thread to its state before the signal handler was
321 called.
322 The thread's signal mask and alternate signal stack settings
323 are restored as part of this procedure.
324 Upon completion of the call to
325 .BR sigreturn (2),
326 the kernel transfers control back to user space,
327 and the thread recommences execution at the point where it was
328 interrupted by the signal handler.
329 .P
330 Note that if the signal handler does not return
331 (e.g., control is transferred out of the handler using
332 .BR siglongjmp (3),
333 or the handler executes a new program with
334 .BR execve (2)),
335 then the final step is not performed.
336 In particular, in such scenarios it is the programmer's responsibility
337 to restore the state of the signal mask (using
338 .BR sigprocmask (2)),
339 if it is desired to unblock the signals that were blocked on entry
340 to the signal handler.
341 (Note that
342 .BR siglongjmp (3)
343 may or may not restore the signal mask, depending on the
344 .I savesigs
345 value that was specified in the corresponding call to
346 .BR sigsetjmp (3).)
347 .P
348 From the kernel's point of view,
349 execution of the signal handler code is exactly the same as the execution
350 of any other user-space code.
351 That is to say, the kernel does not record any special state information
352 indicating that the thread is currently executing inside a signal handler.
353 All necessary state information is maintained in user-space registers
354 and the user-space stack.
355 The depth to which nested signal handlers may be invoked is thus
356 limited only by the user-space stack (and sensible software design!).
357 .\"
358 .SS Standard signals
359 Linux supports the standard signals listed below.
360 The second column of the table indicates which standard (if any)
361 specified the signal: "P1990" indicates that the signal is described
362 in the original POSIX.1-1990 standard;
363 "P2001" indicates that the signal was added in SUSv2 and POSIX.1-2001.
364 .TS
365 l c c l
366 ____
367 lB c c l.
368 Signal Standard Action Comment
369 SIGABRT P1990 Core Abort signal from \fBabort\fP(3)
370 SIGALRM P1990 Term Timer signal from \fBalarm\fP(2)
371 SIGBUS P2001 Core Bus error (bad memory access)
372 SIGCHLD P1990 Ign Child stopped or terminated
373 SIGCLD \- Ign A synonym for \fBSIGCHLD\fP
374 SIGCONT P1990 Cont Continue if stopped
375 SIGEMT \- Term Emulator trap
376 SIGFPE P1990 Core Floating-point exception
377 SIGHUP P1990 Term Hangup detected on controlling terminal
378 or death of controlling process
379 SIGILL P1990 Core Illegal Instruction
380 SIGINFO \- A synonym for \fBSIGPWR\fP
381 SIGINT P1990 Term Interrupt from keyboard
382 SIGIO \- Term I/O now possible (4.2BSD)
383 SIGIOT \- Core IOT trap. A synonym for \fBSIGABRT\fP
384 SIGKILL P1990 Term Kill signal
385 SIGLOST \- Term File lock lost (unused)
386 SIGPIPE P1990 Term Broken pipe: write to pipe with no
387 readers; see \fBpipe\fP(7)
388 SIGPOLL P2001 Term Pollable event (Sys V);
389 synonym for \fBSIGIO\fP
390 SIGPROF P2001 Term Profiling timer expired
391 SIGPWR \- Term Power failure (System V)
392 SIGQUIT P1990 Core Quit from keyboard
393 SIGSEGV P1990 Core Invalid memory reference
394 SIGSTKFLT \- Term Stack fault on coprocessor (unused)
395 SIGSTOP P1990 Stop Stop process
396 SIGTSTP P1990 Stop Stop typed at terminal
397 SIGSYS P2001 Core Bad system call (SVr4);
398 see also \fBseccomp\fP(2)
399 SIGTERM P1990 Term Termination signal
400 SIGTRAP P2001 Core Trace/breakpoint trap
401 SIGTTIN P1990 Stop Terminal input for background process
402 SIGTTOU P1990 Stop Terminal output for background process
403 SIGUNUSED \- Core Synonymous with \fBSIGSYS\fP
404 SIGURG P2001 Ign Urgent condition on socket (4.2BSD)
405 SIGUSR1 P1990 Term User-defined signal 1
406 SIGUSR2 P1990 Term User-defined signal 2
407 SIGVTALRM P2001 Term Virtual alarm clock (4.2BSD)
408 SIGXCPU P2001 Core CPU time limit exceeded (4.2BSD);
409 see \fBsetrlimit\fP(2)
410 SIGXFSZ P2001 Core File size limit exceeded (4.2BSD);
411 see \fBsetrlimit\fP(2)
412 SIGWINCH \- Ign Window resize signal (4.3BSD, Sun)
413 .TE
414 .P
415 The signals
416 .B SIGKILL
417 and
418 .B SIGSTOP
419 cannot be caught, blocked, or ignored.
420 .P
421 Up to and including Linux 2.2, the default behavior for
422 .BR SIGSYS ", " SIGXCPU ", " SIGXFSZ ,
423 and (on architectures other than SPARC and MIPS)
424 .B SIGBUS
425 was to terminate the process (without a core dump).
426 (On some other UNIX systems the default action for
427 .BR SIGXCPU " and " SIGXFSZ
428 is to terminate the process without a core dump.)
429 Linux 2.4 conforms to the POSIX.1-2001 requirements for these signals,
430 terminating the process with a core dump.
431 .P
432 .B SIGEMT
433 is not specified in POSIX.1-2001, but nevertheless appears
434 on most other UNIX systems,
435 where its default action is typically to terminate
436 the process with a core dump.
437 .P
438 .B SIGPWR
439 (which is not specified in POSIX.1-2001) is typically ignored
440 by default on those other UNIX systems where it appears.
441 .P
442 .B SIGIO
443 (which is not specified in POSIX.1-2001) is ignored by default
444 on several other UNIX systems.
445 .\"
446 .SS Queueing and delivery semantics for standard signals
447 If multiple standard signals are pending for a process,
448 the order in which the signals are delivered is unspecified.
449 .P
450 Standard signals do not queue.
451 If multiple instances of a standard signal are generated while
452 that signal is blocked,
453 then only one instance of the signal is marked as pending
454 (and the signal will be delivered just once when it is unblocked).
455 In the case where a standard signal is already pending, the
456 .I siginfo_t
457 structure (see
458 .BR sigaction (2))
459 associated with that signal is not overwritten
460 on arrival of subsequent instances of the same signal.
461 Thus, the process will receive the information
462 associated with the first instance of the signal.
463 .\"
464 .SS Signal numbering for standard signals
465 The numeric value for each signal is given in the table below.
466 As shown in the table, many signals have different numeric values
467 on different architectures.
468 The first numeric value in each table row shows the signal number
469 on x86, ARM, and most other architectures;
470 the second value is for Alpha and SPARC; the third is for MIPS;
471 and the last is for PARISC.
472 A dash (\-) denotes that a signal is absent on the corresponding architecture.
473 .TS
474 l c c c c l
475 l c c c c l
476 ______
477 lB c c c c l.
478 Signal x86/ARM Alpha/ MIPS PARISC Notes
479 most others SPARC
480 SIGHUP \01 \01 \01 \01
481 SIGINT \02 \02 \02 \02
482 SIGQUIT \03 \03 \03 \03
483 SIGILL \04 \04 \04 \04
484 SIGTRAP \05 \05 \05 \05
485 SIGABRT \06 \06 \06 \06
486 SIGIOT \06 \06 \06 \06
487 SIGBUS \07 10 10 10
488 SIGEMT \- \07 \07 -
489 SIGFPE \08 \08 \08 \08
490 SIGKILL \09 \09 \09 \09
491 SIGUSR1 10 30 16 16
492 SIGSEGV 11 11 11 11
493 SIGUSR2 12 31 17 17
494 SIGPIPE 13 13 13 13
495 SIGALRM 14 14 14 14
496 SIGTERM 15 15 15 15
497 SIGSTKFLT 16 \- \- \07
498 SIGCHLD 17 20 18 18
499 SIGCLD \- \- 18 \-
500 SIGCONT 18 19 25 26
501 SIGSTOP 19 17 23 24
502 SIGTSTP 20 18 24 25
503 SIGTTIN 21 21 26 27
504 SIGTTOU 22 22 27 28
505 SIGURG 23 16 21 29
506 SIGXCPU 24 24 30 12
507 SIGXFSZ 25 25 31 30
508 SIGVTALRM 26 26 28 20
509 SIGPROF 27 27 29 21
510 SIGWINCH 28 28 20 23
511 SIGIO 29 23 22 22
512 SIGPOLL Same as SIGIO
513 SIGPWR 30 29/\- 19 19
514 SIGINFO \- 29/\- \- \-
515 SIGLOST \- \-/29 \- \-
516 SIGSYS 31 12 12 31
517 SIGUNUSED 31 \- \- 31
518 .TE
519 .P
520 Note the following:
521 .IP \[bu] 3
522 Where defined,
523 .B SIGUNUSED
524 is synonymous with
525 .BR SIGSYS .
526 Since glibc 2.26,
527 .B SIGUNUSED
528 is no longer defined on any architecture.
529 .IP \[bu]
530 Signal 29 is
531 .BR SIGINFO / SIGPWR
532 (synonyms for the same value) on Alpha but
533 .B SIGLOST
534 on SPARC.
535 .\"
536 .SS Real-time signals
537 Starting with Linux 2.2,
538 Linux supports real-time signals as originally defined in the POSIX.1b
539 real-time extensions (and now included in POSIX.1-2001).
540 The range of supported real-time signals is defined by the macros
541 .B SIGRTMIN
542 and
543 .BR SIGRTMAX .
544 POSIX.1-2001 requires that an implementation support at least
545 .B _POSIX_RTSIG_MAX
546 (8) real-time signals.
547 .P
548 The Linux kernel supports a range of 33 different real-time
549 signals, numbered 32 to 64.
550 However, the glibc POSIX threads implementation internally uses
551 two (for NPTL) or three (for LinuxThreads) real-time signals
552 (see
553 .BR pthreads (7)),
554 and adjusts the value of
555 .B SIGRTMIN
556 suitably (to 34 or 35).
557 Because the range of available real-time signals varies according
558 to the glibc threading implementation (and this variation can occur
559 at run time according to the available kernel and glibc),
560 and indeed the range of real-time signals varies across UNIX systems,
561 programs should
562 .IR "never refer to real-time signals using hard-coded numbers" ,
563 but instead should always refer to real-time signals using the notation
564 .BR SIGRTMIN +n,
565 and include suitable (run-time) checks that
566 .BR SIGRTMIN +n
567 does not exceed
568 .BR SIGRTMAX .
569 .P
570 Unlike standard signals, real-time signals have no predefined meanings:
571 the entire set of real-time signals can be used for application-defined
572 purposes.
573 .P
574 The default action for an unhandled real-time signal is to terminate the
575 receiving process.
576 .P
577 Real-time signals are distinguished by the following:
578 .IP \[bu] 3
579 Multiple instances of real-time signals can be queued.
580 By contrast, if multiple instances of a standard signal are delivered
581 while that signal is currently blocked, then only one instance is queued.
582 .IP \[bu]
583 If the signal is sent using
584 .BR sigqueue (3),
585 an accompanying value (either an integer or a pointer) can be sent
586 with the signal.
587 If the receiving process establishes a handler for this signal using the
588 .B SA_SIGINFO
589 flag to
590 .BR sigaction (2),
591 then it can obtain this data via the
592 .I si_value
593 field of the
594 .I siginfo_t
595 structure passed as the second argument to the handler.
596 Furthermore, the
597 .I si_pid
598 and
599 .I si_uid
600 fields of this structure can be used to obtain the PID
601 and real user ID of the process sending the signal.
602 .IP \[bu]
603 Real-time signals are delivered in a guaranteed order.
604 Multiple real-time signals of the same type are delivered in the order
605 they were sent.
606 If different real-time signals are sent to a process, they are delivered
607 starting with the lowest-numbered signal.
608 (I.e., low-numbered signals have highest priority.)
609 By contrast, if multiple standard signals are pending for a process,
610 the order in which they are delivered is unspecified.
611 .P
612 If both standard and real-time signals are pending for a process,
613 POSIX leaves it unspecified which is delivered first.
614 Linux, like many other implementations, gives priority
615 to standard signals in this case.
616 .P
617 According to POSIX, an implementation should permit at least
618 .B _POSIX_SIGQUEUE_MAX
619 (32) real-time signals to be queued to
620 a process.
621 However, Linux does things differently.
622 Up to and including Linux 2.6.7, Linux imposes
623 a system-wide limit on the number of queued real-time signals
624 for all processes.
625 This limit can be viewed and (with privilege) changed via the
626 .I /proc/sys/kernel/rtsig\-max
627 file.
628 A related file,
629 .IR /proc/sys/kernel/rtsig\-nr ,
630 can be used to find out how many real-time signals are currently queued.
631 In Linux 2.6.8, these
632 .I /proc
633 interfaces were replaced by the
634 .B RLIMIT_SIGPENDING
635 resource limit, which specifies a per-user limit for queued
636 signals; see
637 .BR setrlimit (2)
638 for further details.
639 .P
640 The addition of real-time signals required the widening
641 of the signal set structure
642 .RI ( sigset_t )
643 from 32 to 64 bits.
644 Consequently, various system calls were superseded by new system calls
645 that supported the larger signal sets.
646 The old and new system calls are as follows:
647 .TS
648 lb lb
649 l l.
650 Linux 2.0 and earlier Linux 2.2 and later
651 \fBsigaction\fP(2) \fBrt_sigaction\fP(2)
652 \fBsigpending\fP(2) \fBrt_sigpending\fP(2)
653 \fBsigprocmask\fP(2) \fBrt_sigprocmask\fP(2)
654 \fBsigreturn\fP(2) \fBrt_sigreturn\fP(2)
655 \fBsigsuspend\fP(2) \fBrt_sigsuspend\fP(2)
656 \fBsigtimedwait\fP(2) \fBrt_sigtimedwait\fP(2)
657 .TE
658 .\"
659 .SS Interruption of system calls and library functions by signal handlers
660 If a signal handler is invoked while a system call or library
661 function call is blocked, then either:
662 .IP \[bu] 3
663 the call is automatically restarted after the signal handler returns; or
664 .IP \[bu]
665 the call fails with the error
666 .BR EINTR .
667 .P
668 Which of these two behaviors occurs depends on the interface and
669 whether or not the signal handler was established using the
670 .B SA_RESTART
671 flag (see
672 .BR sigaction (2)).
673 The details vary across UNIX systems;
674 below, the details for Linux.
675 .P
676 If a blocked call to one of the following interfaces is interrupted
677 by a signal handler, then the call is automatically restarted
678 after the signal handler returns if the
679 .B SA_RESTART
680 flag was used; otherwise the call fails with the error
681 .BR EINTR :
682 .\" The following system calls use ERESTARTSYS,
683 .\" so that they are restartable
684 .IP \[bu] 3
685 .BR read (2),
686 .BR readv (2),
687 .BR write (2),
688 .BR writev (2),
689 and
690 .BR ioctl (2)
691 calls on "slow" devices.
692 A "slow" device is one where the I/O call may block for an
693 indefinite time, for example, a terminal, pipe, or socket.
694 If an I/O call on a slow device has already transferred some
695 data by the time it is interrupted by a signal handler,
696 then the call will return a success status
697 (normally, the number of bytes transferred).
698 Note that a (local) disk is not a slow device according to this definition;
699 I/O operations on disk devices are not interrupted by signals.
700 .IP \[bu]
701 .BR open (2),
702 if it can block (e.g., when opening a FIFO; see
703 .BR fifo (7)).
704 .IP \[bu]
705 .BR wait (2),
706 .BR wait3 (2),
707 .BR wait4 (2),
708 .BR waitid (2),
709 and
710 .BR waitpid (2).
711 .IP \[bu]
712 Socket interfaces:
713 .\" If a timeout (setsockopt()) is in effect on the socket, then these
714 .\" system calls switch to using EINTR. Consequently, they and are not
715 .\" automatically restarted, and they show the stop/cont behavior
716 .\" described below. (Verified from Linux 2.6.26 source, and by experiment; mtk)
717 .BR accept (2),
718 .BR connect (2),
719 .BR recv (2),
720 .BR recvfrom (2),
721 .BR recvmmsg (2),
722 .BR recvmsg (2),
723 .BR send (2),
724 .BR sendto (2),
725 and
726 .BR sendmsg (2),
727 .\" FIXME What about sendmmsg()?
728 unless a timeout has been set on the socket (see below).
729 .IP \[bu]
730 File locking interfaces:
731 .BR flock (2)
732 and
733 the
734 .B F_SETLKW
735 and
736 .B F_OFD_SETLKW
737 operations of
738 .BR fcntl (2)
739 .IP \[bu]
740 POSIX message queue interfaces:
741 .BR mq_receive (3),
742 .BR mq_timedreceive (3),
743 .BR mq_send (3),
744 and
745 .BR mq_timedsend (3).
746 .IP \[bu]
747 .BR futex (2)
748 .B FUTEX_WAIT
749 (since Linux 2.6.22;
750 .\" commit 72c1bbf308c75a136803d2d76d0e18258be14c7a
751 beforehand, always failed with
752 .BR EINTR ).
753 .IP \[bu]
754 .BR getrandom (2).
755 .IP \[bu]
756 .BR pthread_mutex_lock (3),
757 .BR pthread_cond_wait (3),
758 and related APIs.
759 .IP \[bu]
760 .BR futex (2)
761 .BR FUTEX_WAIT_BITSET .
762 .IP \[bu]
763 POSIX semaphore interfaces:
764 .BR sem_wait (3)
765 and
766 .BR sem_timedwait (3)
767 (since Linux 2.6.22;
768 .\" as a consequence of the 2.6.22 changes in the futex() implementation
769 beforehand, always failed with
770 .BR EINTR ).
771 .IP \[bu]
772 .BR read (2)
773 from an
774 .BR inotify (7)
775 file descriptor
776 (since Linux 3.8;
777 .\" commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06
778 beforehand, always failed with
779 .BR EINTR ).
780 .P
781 The following interfaces are never restarted after
782 being interrupted by a signal handler,
783 regardless of the use of
784 .BR SA_RESTART ;
785 they always fail with the error
786 .B EINTR
787 when interrupted by a signal handler:
788 .\" These are the system calls that give EINTR or ERESTARTNOHAND
789 .\" on interruption by a signal handler.
790 .IP \[bu] 3
791 "Input" socket interfaces, when a timeout
792 .RB ( SO_RCVTIMEO )
793 has been set on the socket using
794 .BR setsockopt (2):
795 .BR accept (2),
796 .BR recv (2),
797 .BR recvfrom (2),
798 .BR recvmmsg (2)
799 (also with a non-NULL
800 .I timeout
801 argument),
802 and
803 .BR recvmsg (2).
804 .IP \[bu]
805 "Output" socket interfaces, when a timeout
806 .RB ( SO_RCVTIMEO )
807 has been set on the socket using
808 .BR setsockopt (2):
809 .BR connect (2),
810 .BR send (2),
811 .BR sendto (2),
812 and
813 .BR sendmsg (2).
814 .\" FIXME What about sendmmsg()?
815 .IP \[bu]
816 Interfaces used to wait for signals:
817 .BR pause (2),
818 .BR sigsuspend (2),
819 .BR sigtimedwait (2),
820 and
821 .BR sigwaitinfo (2).
822 .IP \[bu]
823 File descriptor multiplexing interfaces:
824 .BR epoll_wait (2),
825 .BR epoll_pwait (2),
826 .BR poll (2),
827 .BR ppoll (2),
828 .BR select (2),
829 and
830 .BR pselect (2).
831 .IP \[bu]
832 System V IPC interfaces:
833 .\" On some other systems, SA_RESTART does restart these system calls
834 .BR msgrcv (2),
835 .BR msgsnd (2),
836 .BR semop (2),
837 and
838 .BR semtimedop (2).
839 .IP \[bu]
840 Sleep interfaces:
841 .BR clock_nanosleep (2),
842 .BR nanosleep (2),
843 and
844 .BR usleep (3).
845 .IP \[bu]
846 .BR io_getevents (2).
847 .P
848 The
849 .BR sleep (3)
850 function is also never restarted if interrupted by a handler,
851 but gives a success return: the number of seconds remaining to sleep.
852 .P
853 In certain circumstances, the
854 .BR seccomp (2)
855 user-space notification feature can lead to restarting of system calls
856 that would otherwise never be restarted by
857 .BR SA_RESTART ;
858 for details, see
859 .BR seccomp_unotify (2).
860 .\"
861 .SS Interruption of system calls and library functions by stop signals
862 On Linux, even in the absence of signal handlers,
863 certain blocking interfaces can fail with the error
864 .B EINTR
865 after the process is stopped by one of the stop signals
866 and then resumed via
867 .BR SIGCONT .
868 This behavior is not sanctioned by POSIX.1, and doesn't occur
869 on other systems.
870 .P
871 The Linux interfaces that display this behavior are:
872 .IP \[bu] 3
873 "Input" socket interfaces, when a timeout
874 .RB ( SO_RCVTIMEO )
875 has been set on the socket using
876 .BR setsockopt (2):
877 .BR accept (2),
878 .BR recv (2),
879 .BR recvfrom (2),
880 .BR recvmmsg (2)
881 (also with a non-NULL
882 .I timeout
883 argument),
884 and
885 .BR recvmsg (2).
886 .IP \[bu]
887 "Output" socket interfaces, when a timeout
888 .RB ( SO_RCVTIMEO )
889 has been set on the socket using
890 .BR setsockopt (2):
891 .BR connect (2),
892 .BR send (2),
893 .BR sendto (2),
894 and
895 .\" FIXME What about sendmmsg()?
896 .BR sendmsg (2),
897 if a send timeout
898 .RB ( SO_SNDTIMEO )
899 has been set.
900 .IP \[bu]
901 .BR epoll_wait (2),
902 .BR epoll_pwait (2).
903 .IP \[bu]
904 .BR semop (2),
905 .BR semtimedop (2).
906 .IP \[bu]
907 .BR sigtimedwait (2),
908 .BR sigwaitinfo (2).
909 .IP \[bu]
910 Linux 3.7 and earlier:
911 .BR read (2)
912 from an
913 .BR inotify (7)
914 file descriptor
915 .\" commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06
916 .IP \[bu]
917 Linux 2.6.21 and earlier:
918 .BR futex (2)
919 .BR FUTEX_WAIT ,
920 .BR sem_timedwait (3),
921 .BR sem_wait (3).
922 .IP \[bu]
923 Linux 2.6.8 and earlier:
924 .BR msgrcv (2),
925 .BR msgsnd (2).
926 .IP \[bu]
927 Linux 2.4 and earlier:
928 .BR nanosleep (2).
929 .SH STANDARDS
930 POSIX.1, except as noted.
931 .SH NOTES
932 For a discussion of async-signal-safe functions, see
933 .BR signal\-safety (7).
934 .P
935 The
936 .IR /proc/ pid /task/ tid /status
937 file contains various fields that show the signals
938 that a thread is blocking
939 .RI ( SigBlk ),
940 catching
941 .RI ( SigCgt ),
942 or ignoring
943 .RI ( SigIgn ).
944 (The set of signals that are caught or ignored will be the same
945 across all threads in a process.)
946 Other fields show the set of pending signals that are directed to the thread
947 .RI ( SigPnd )
948 as well as the set of pending signals that are directed
949 to the process as a whole
950 .RI ( ShdPnd ).
951 The corresponding fields in
952 .IR /proc/ pid /status
953 show the information for the main thread.
954 See
955 .BR proc (5)
956 for further details.
957 .SH BUGS
958 There are six signals that can be delivered
959 as a consequence of a hardware exception:
960 .BR SIGBUS ,
961 .BR SIGEMT ,
962 .BR SIGFPE ,
963 .BR SIGILL ,
964 .BR SIGSEGV ,
965 and
966 .BR SIGTRAP .
967 Which of these signals is delivered,
968 for any given hardware exception,
969 is not documented and does not always make sense.
970 .P
971 For example, an invalid memory access that causes delivery of
972 .B SIGSEGV
973 on one CPU architecture may cause delivery of
974 .B SIGBUS
975 on another architecture, or vice versa.
976 .P
977 For another example, using the x86
978 .I int
979 instruction with a forbidden argument
980 (any number other than 3 or 128)
981 causes delivery of
982 .BR SIGSEGV ,
983 even though
984 .B SIGILL
985 would make more sense,
986 because of how the CPU reports the forbidden operation to the kernel.
987 .SH SEE ALSO
988 .BR kill (1),
989 .BR clone (2),
990 .BR getrlimit (2),
991 .BR kill (2),
992 .BR pidfd_send_signal (2),
993 .BR restart_syscall (2),
994 .BR rt_sigqueueinfo (2),
995 .BR setitimer (2),
996 .BR setrlimit (2),
997 .BR sgetmask (2),
998 .BR sigaction (2),
999 .BR sigaltstack (2),
1000 .BR signal (2),
1001 .BR signalfd (2),
1002 .BR sigpending (2),
1003 .BR sigprocmask (2),
1004 .BR sigreturn (2),
1005 .BR sigsuspend (2),
1006 .BR sigwaitinfo (2),
1007 .BR abort (3),
1008 .BR bsd_signal (3),
1009 .BR killpg (3),
1010 .BR longjmp (3),
1011 .BR pthread_sigqueue (3),
1012 .BR raise (3),
1013 .BR sigqueue (3),
1014 .BR sigset (3),
1015 .BR sigsetops (3),
1016 .BR sigvec (3),
1017 .BR sigwait (3),
1018 .BR strsignal (3),
1019 .BR swapcontext (3),
1020 .BR sysv_signal (3),
1021 .BR core (5),
1022 .BR proc (5),
1023 .BR nptl (7),
1024 .BR pthreads (7),
1025 .BR sigevent (3type)