Debian Codegraph @

upstream/debian-unstable/man7/signal.7

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