Debian Codegraph @

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