mirror of https://github.com/mkerrisk/man-pages
1025 lines
30 KiB
Groff
1025 lines
30 KiB
Groff
.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
|
|
.\" and Copyright (c) 2002, 2006, 2020 by Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
|
|
.\" <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" Modified Sat Jul 24 17:34:08 1993 by Rik Faith (faith@cs.unc.edu)
|
|
.\" Modified Sun Jan 7 01:41:27 1996 by Andries Brouwer (aeb@cwi.nl)
|
|
.\" Modified Sun Apr 14 12:02:29 1996 by Andries Brouwer (aeb@cwi.nl)
|
|
.\" Modified Sat Nov 13 16:28:23 1999 by Andries Brouwer (aeb@cwi.nl)
|
|
.\" Modified 10 Apr 2002, by Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" Modified 7 Jun 2002, by Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" Added information on real-time signals
|
|
.\" Modified 13 Jun 2002, by Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" Noted that SIGSTKFLT is in fact unused
|
|
.\" 2004-12-03, Modified mtk, added notes on RLIMIT_SIGPENDING
|
|
.\" 2006-04-24, mtk, Added text on changing signal dispositions,
|
|
.\" signal mask, and pending signals.
|
|
.\" 2008-07-04, mtk:
|
|
.\" Added section on system call restarting (SA_RESTART)
|
|
.\" Added section on stop/cont signals interrupting syscalls.
|
|
.\" 2008-10-05, mtk: various additions
|
|
.\"
|
|
.TH SIGNAL 7 2020-12-21 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
signal \- overview of signals
|
|
.SH DESCRIPTION
|
|
Linux supports both POSIX reliable signals (hereinafter
|
|
"standard signals") and POSIX real-time signals.
|
|
.SS Signal dispositions
|
|
Each signal has a current
|
|
.IR disposition ,
|
|
which determines how the process behaves when it is delivered
|
|
the signal.
|
|
.PP
|
|
The entries in the "Action" column of the table below specify
|
|
the default disposition for each signal, as follows:
|
|
.IP Term
|
|
Default action is to terminate the process.
|
|
.IP Ign
|
|
Default action is to ignore the signal.
|
|
.IP Core
|
|
Default action is to terminate the process and dump core (see
|
|
.BR core (5)).
|
|
.IP Stop
|
|
Default action is to stop the process.
|
|
.IP Cont
|
|
Default action is to continue the process if it is currently stopped.
|
|
.PP
|
|
A process can change the disposition of a signal using
|
|
.BR sigaction (2)
|
|
or
|
|
.BR signal (2).
|
|
(The latter is less portable when establishing a signal handler;
|
|
see
|
|
.BR signal (2)
|
|
for details.)
|
|
Using these system calls, a process can elect one of the
|
|
following behaviors to occur on delivery of the signal:
|
|
perform the default action; ignore the signal;
|
|
or catch the signal with a
|
|
.IR "signal handler" ,
|
|
a programmer-defined function that is automatically invoked
|
|
when the signal is delivered.
|
|
.PP
|
|
By default, a signal handler is invoked on the
|
|
normal process stack.
|
|
It is possible to arrange that the signal handler
|
|
uses an alternate stack; see
|
|
.BR sigaltstack (2)
|
|
for a discussion of how to do this and when it might be useful.
|
|
.PP
|
|
The signal disposition is a per-process attribute:
|
|
in a multithreaded application, the disposition of a
|
|
particular signal is the same for all threads.
|
|
.PP
|
|
A child created via
|
|
.BR fork (2)
|
|
inherits a copy of its parent's signal dispositions.
|
|
During an
|
|
.BR execve (2),
|
|
the dispositions of handled signals are reset to the default;
|
|
the dispositions of ignored signals are left unchanged.
|
|
.SS Sending a signal
|
|
The following system calls and library functions allow
|
|
the caller to send a signal:
|
|
.TP
|
|
.BR raise (3)
|
|
Sends a signal to the calling thread.
|
|
.TP
|
|
.BR kill (2)
|
|
Sends a signal to a specified process,
|
|
to all members of a specified process group,
|
|
or to all processes on the system.
|
|
.TP
|
|
.BR pidfd_send_signal (2)
|
|
Sends a signal to a process identified by a PID file descriptor.
|
|
.TP
|
|
.BR killpg (3)
|
|
Sends a signal to all of the members of a specified process group.
|
|
.TP
|
|
.BR pthread_kill (3)
|
|
Sends a signal to a specified POSIX thread in the same process as
|
|
the caller.
|
|
.TP
|
|
.BR tgkill (2)
|
|
Sends a signal to a specified thread within a specific process.
|
|
(This is the system call used to implement
|
|
.BR pthread_kill (3).)
|
|
.TP
|
|
.BR sigqueue (3)
|
|
Sends a real-time signal with accompanying data to a specified process.
|
|
.SS Waiting for a signal to be caught
|
|
The following system calls suspend execution of the calling
|
|
thread until a signal is caught
|
|
(or an unhandled signal terminates the process):
|
|
.TP
|
|
.BR pause (2)
|
|
Suspends execution until any signal is caught.
|
|
.TP
|
|
.BR sigsuspend (2)
|
|
Temporarily changes the signal mask (see below) and suspends
|
|
execution until one of the unmasked signals is caught.
|
|
.\"
|
|
.SS Synchronously accepting a signal
|
|
Rather than asynchronously catching a signal via a signal handler,
|
|
it is possible to synchronously accept the signal, that is,
|
|
to block execution until the signal is delivered,
|
|
at which point the kernel returns information about the
|
|
signal to the caller.
|
|
There are two general ways to do this:
|
|
.IP * 2
|
|
.BR sigwaitinfo (2),
|
|
.BR sigtimedwait (2),
|
|
and
|
|
.BR sigwait (3)
|
|
suspend execution until one of the signals in a specified
|
|
set is delivered.
|
|
Each of these calls returns information about the delivered signal.
|
|
.IP *
|
|
.BR signalfd (2)
|
|
returns a file descriptor that can be used to read information
|
|
about signals that are delivered to the caller.
|
|
Each
|
|
.BR read (2)
|
|
from this file descriptor blocks until one of the signals
|
|
in the set specified in the
|
|
.BR signalfd (2)
|
|
call is delivered to the caller.
|
|
The buffer returned by
|
|
.BR read (2)
|
|
contains a structure describing the signal.
|
|
.SS Signal mask and pending signals
|
|
A signal may be
|
|
.IR blocked ,
|
|
which means that it will not be delivered until it is later unblocked.
|
|
Between the time when it is generated and when it is delivered
|
|
a signal is said to be
|
|
.IR pending .
|
|
.PP
|
|
Each thread in a process has an independent
|
|
.IR "signal mask" ,
|
|
which indicates the set of signals that the thread is currently blocking.
|
|
A thread can manipulate its signal mask using
|
|
.BR pthread_sigmask (3).
|
|
In a traditional single-threaded application,
|
|
.BR sigprocmask (2)
|
|
can be used to manipulate the signal mask.
|
|
.PP
|
|
A child created via
|
|
.BR fork (2)
|
|
inherits a copy of its parent's signal mask;
|
|
the signal mask is preserved across
|
|
.BR execve (2).
|
|
.PP
|
|
A signal may be process-directed or thread-directed.
|
|
A process-directed signal is one that is targeted at (and thus pending for)
|
|
the process as a whole.
|
|
A signal may be process-directed
|
|
because it was generated by the kernel for reasons
|
|
other than a hardware exception, or because it was sent using
|
|
.BR kill (2)
|
|
or
|
|
.BR sigqueue (3).
|
|
A thread-directed signal is one that is targeted at a specific thread.
|
|
A signal may be thread-directed because it was generated as a consequence
|
|
of executing a specific machine-language instruction
|
|
that triggered a hardware exception (e.g.,
|
|
.B SIGSEGV
|
|
for an invalid memory access, or
|
|
.B SIGFPE
|
|
for a math error), or because it was
|
|
targeted at a specific thread using
|
|
interfaces such as
|
|
.BR tgkill (2)
|
|
or
|
|
.BR pthread_kill (3).
|
|
.PP
|
|
A process-directed signal may be delivered to any one of the
|
|
threads that does not currently have the signal blocked.
|
|
.\" Joseph C. Sible notes:
|
|
.\" On Linux, if the main thread has the signal unblocked, then the kernel
|
|
.\" will always deliver the signal there, citing this kernel code
|
|
.\"
|
|
.\" Per this comment in kernel/signal.c since time immemorial:
|
|
.\"
|
|
.\" /*
|
|
.\" * Now find a thread we can wake up to take the signal off the queue.
|
|
.\" *
|
|
.\" * If the main thread wants the signal, it gets first crack.
|
|
.\" * Probably the least surprising to the average bear.
|
|
.\" */
|
|
.\"
|
|
.\" But this does not mean the signal will be delivered only in the
|
|
.\" main thread, since if a handler is already executing in the main thread
|
|
.\" (and thus the signal is blocked in that thread), then a further
|
|
.\" might be delivered in a different thread.
|
|
.\"
|
|
If more than one of the threads has the signal unblocked, then the
|
|
kernel chooses an arbitrary thread to which to deliver the signal.
|
|
.PP
|
|
A thread can obtain the set of signals that it currently has pending
|
|
using
|
|
.BR sigpending (2).
|
|
This set will consist of the union of the set of pending
|
|
process-directed signals and the set of signals pending for
|
|
the calling thread.
|
|
.PP
|
|
A child created via
|
|
.BR fork (2)
|
|
initially has an empty pending signal set;
|
|
the pending signal set is preserved across an
|
|
.BR execve (2).
|
|
.\"
|
|
.SS Execution of signal handlers
|
|
Whenever there is a transition from kernel-mode to user-mode execution
|
|
(e.g., on return from a system call or scheduling of a thread onto the CPU),
|
|
the kernel checks whether there is a pending unblocked signal
|
|
for which the process has established a signal handler.
|
|
If there is such a pending signal, the following steps occur:
|
|
.IP 1. 3
|
|
The kernel performs the necessary preparatory steps for execution of
|
|
the signal handler:
|
|
.RS
|
|
.IP a) 3
|
|
The signal is removed from the set of pending signals.
|
|
.IP b)
|
|
If the signal handler was installed by a call to
|
|
.BR sigaction (2)
|
|
that specified the
|
|
.BR SA_ONSTACK
|
|
flag and the thread has defined an alternate signal stack (using
|
|
.BR sigaltstack (2)),
|
|
then that stack is installed.
|
|
.IP c)
|
|
Various pieces of signal-related context are saved
|
|
into a special frame that is created on the stack.
|
|
The saved information includes:
|
|
.RS
|
|
.IP + 2
|
|
the program counter register
|
|
(i.e., the address of the next instruction in the main program that
|
|
should be executed when the signal handler returns);
|
|
.IP +
|
|
architecture-specific register state required for resuming the
|
|
interrupted program;
|
|
.IP +
|
|
the thread's current signal mask;
|
|
.IP +
|
|
the thread's alternate signal stack settings.
|
|
.RE
|
|
.IP
|
|
(If the signal handler was installed using the
|
|
.BR sigaction (2)
|
|
.B SA_SIGINFO
|
|
flag, then the above information is accessible via the
|
|
.I ucontext_t
|
|
object that is pointed to by the third argument of the signal handler.)
|
|
.IP d)
|
|
Any signals specified in
|
|
.I act\->sa_mask
|
|
when registering the handler with
|
|
.BR sigprocmask (2)
|
|
are added to the thread's signal mask.
|
|
The signal being delivered is also
|
|
added to the signal mask, unless
|
|
.B SA_NODEFER
|
|
was specified when registering the handler.
|
|
These signals are thus blocked while the handler executes.
|
|
.RE
|
|
.IP 2.
|
|
The kernel constructs a frame for the signal handler on the stack.
|
|
The kernel sets the program counter for the thread to point to the first
|
|
instruction of the signal handler function,
|
|
and configures the return address for that function to point to a piece
|
|
of user-space code known as the signal trampoline (described in
|
|
.BR sigreturn (2)).
|
|
.IP 3.
|
|
The kernel passes control back to user-space, where execution
|
|
commences at the start of the signal handler function.
|
|
.IP 4.
|
|
When the signal handler returns, control passes to the signal trampoline code.
|
|
.IP 5.
|
|
The signal trampoline calls
|
|
.BR sigreturn (2),
|
|
a system call that uses the information in the stack frame created in step 1
|
|
to restore the thread to its state before the signal handler was
|
|
called.
|
|
The thread's signal mask and alternate signal stack settings
|
|
are restored as part of this procedure.
|
|
Upon completion of the call to
|
|
.BR sigreturn (2),
|
|
the kernel transfers control back to user space,
|
|
and the thread recommences execution at the point where it was
|
|
interrupted by the signal handler.
|
|
.PP
|
|
Note that if the signal handler does not return
|
|
(e.g., control is transferred out of the handler using
|
|
.BR siglongjmp (3),
|
|
or the handler executes a new program with
|
|
.BR execve (2)),
|
|
then the final step is not performed.
|
|
In particular, in such scenarios it is the programmer's responsibility
|
|
to restore the state of the signal mask (using
|
|
.BR sigprocmask (2)),
|
|
if it is desired to unblock the signals that were blocked on entry
|
|
to the signal handler.
|
|
(Note that
|
|
.BR siglongjmp (3)
|
|
may or may not restore the signal mask, depending on the
|
|
.I savesigs
|
|
value that was specified in the corresponding call to
|
|
.BR sigsetjmp (3).)
|
|
.PP
|
|
From the kernel's point of view,
|
|
execution of the signal handler code is exactly the same as the execution
|
|
of any other user-space code.
|
|
That is to say, the kernel does not record any special state information
|
|
indicating that the thread is currently executing inside a signal handler.
|
|
All necessary state information is maintained in user-space registers
|
|
and the user-space stack.
|
|
The depth to which nested signal handlers may be invoked is thus
|
|
limited only by the user-space stack (and sensible software design!).
|
|
.\"
|
|
.SS Standard signals
|
|
Linux supports the standard signals listed below.
|
|
The second column of the table indicates which standard (if any)
|
|
specified the signal: "P1990" indicates that the signal is described
|
|
in the original POSIX.1-1990 standard;
|
|
"P2001" indicates that the signal was added in SUSv2 and POSIX.1-2001.
|
|
.TS
|
|
l c c l
|
|
____
|
|
lB c c l.
|
|
Signal Standard Action Comment
|
|
SIGABRT P1990 Core Abort signal from \fBabort\fP(3)
|
|
SIGALRM P1990 Term Timer signal from \fBalarm\fP(2)
|
|
SIGBUS P2001 Core Bus error (bad memory access)
|
|
SIGCHLD P1990 Ign Child stopped or terminated
|
|
SIGCLD \- Ign A synonym for \fBSIGCHLD\fP
|
|
SIGCONT P1990 Cont Continue if stopped
|
|
SIGEMT \- Term Emulator trap
|
|
SIGFPE P1990 Core Floating-point exception
|
|
SIGHUP P1990 Term Hangup detected on controlling terminal
|
|
or death of controlling process
|
|
SIGILL P1990 Core Illegal Instruction
|
|
SIGINFO \- A synonym for \fBSIGPWR\fP
|
|
SIGINT P1990 Term Interrupt from keyboard
|
|
SIGIO \- Term I/O now possible (4.2BSD)
|
|
SIGIOT \- Core IOT trap. A synonym for \fBSIGABRT\fP
|
|
SIGKILL P1990 Term Kill signal
|
|
SIGLOST \- Term File lock lost (unused)
|
|
SIGPIPE P1990 Term Broken pipe: write to pipe with no
|
|
readers; see \fBpipe\fP(7)
|
|
SIGPOLL P2001 Term Pollable event (Sys V);
|
|
synonym for \fBSIGIO\fP
|
|
SIGPROF P2001 Term Profiling timer expired
|
|
SIGPWR \- Term Power failure (System V)
|
|
SIGQUIT P1990 Core Quit from keyboard
|
|
SIGSEGV P1990 Core Invalid memory reference
|
|
SIGSTKFLT \- Term Stack fault on coprocessor (unused)
|
|
SIGSTOP P1990 Stop Stop process
|
|
SIGTSTP P1990 Stop Stop typed at terminal
|
|
SIGSYS P2001 Core Bad system call (SVr4);
|
|
see also \fBseccomp\fP(2)
|
|
SIGTERM P1990 Term Termination signal
|
|
SIGTRAP P2001 Core Trace/breakpoint trap
|
|
SIGTTIN P1990 Stop Terminal input for background process
|
|
SIGTTOU P1990 Stop Terminal output for background process
|
|
SIGUNUSED \- Core Synonymous with \fBSIGSYS\fP
|
|
SIGURG P2001 Ign Urgent condition on socket (4.2BSD)
|
|
SIGUSR1 P1990 Term User-defined signal 1
|
|
SIGUSR2 P1990 Term User-defined signal 2
|
|
SIGVTALRM P2001 Term Virtual alarm clock (4.2BSD)
|
|
SIGXCPU P2001 Core CPU time limit exceeded (4.2BSD);
|
|
see \fBsetrlimit\fP(2)
|
|
SIGXFSZ P2001 Core File size limit exceeded (4.2BSD);
|
|
see \fBsetrlimit\fP(2)
|
|
SIGWINCH \- Ign Window resize signal (4.3BSD, Sun)
|
|
.TE
|
|
.PP
|
|
The signals
|
|
.B SIGKILL
|
|
and
|
|
.B SIGSTOP
|
|
cannot be caught, blocked, or ignored.
|
|
.PP
|
|
Up to and including Linux 2.2, the default behavior for
|
|
.BR SIGSYS ", " SIGXCPU ", " SIGXFSZ ,
|
|
and (on architectures other than SPARC and MIPS)
|
|
.B SIGBUS
|
|
was to terminate the process (without a core dump).
|
|
(On some other UNIX systems the default action for
|
|
.BR SIGXCPU " and " SIGXFSZ
|
|
is to terminate the process without a core dump.)
|
|
Linux 2.4 conforms to the POSIX.1-2001 requirements for these signals,
|
|
terminating the process with a core dump.
|
|
.PP
|
|
.B SIGEMT
|
|
is not specified in POSIX.1-2001, but nevertheless appears
|
|
on most other UNIX systems,
|
|
where its default action is typically to terminate
|
|
the process with a core dump.
|
|
.PP
|
|
.B SIGPWR
|
|
(which is not specified in POSIX.1-2001) is typically ignored
|
|
by default on those other UNIX systems where it appears.
|
|
.PP
|
|
.B SIGIO
|
|
(which is not specified in POSIX.1-2001) is ignored by default
|
|
on several other UNIX systems.
|
|
.\"
|
|
.SS Queueing and delivery semantics for standard signals
|
|
If multiple standard signals are pending for a process,
|
|
the order in which the signals are delivered is unspecified.
|
|
.PP
|
|
Standard signals do not queue.
|
|
If multiple instances of a standard signal are generated while
|
|
that signal is blocked,
|
|
then only one instance of the signal is marked as pending
|
|
(and the signal will be delivered just once when it is unblocked).
|
|
In the case where a standard signal is already pending, the
|
|
.I siginfo_t
|
|
structure (see
|
|
.BR sigaction (2))
|
|
associated with that signal is not overwritten
|
|
on arrival of subsequent instances of the same signal.
|
|
Thus, the process will receive the information
|
|
associated with the first instance of the signal.
|
|
.\"
|
|
.SS Signal numbering for standard signals
|
|
The numeric value for each signal is given in the table below.
|
|
As shown in the table, many signals have different numeric values
|
|
on different architectures.
|
|
The first numeric value in each table row shows the signal number
|
|
on x86, ARM, and most other architectures;
|
|
the second value is for Alpha and SPARC; the third is for MIPS;
|
|
and the last is for PARISC.
|
|
A dash (\-) denotes that a signal is absent on the corresponding architecture.
|
|
.TS
|
|
l c c c c l
|
|
l c c c c l
|
|
______
|
|
lB c c c c l.
|
|
Signal x86/ARM Alpha/ MIPS PARISC Notes
|
|
most others SPARC
|
|
SIGHUP \01 \01 \01 \01
|
|
SIGINT \02 \02 \02 \02
|
|
SIGQUIT \03 \03 \03 \03
|
|
SIGILL \04 \04 \04 \04
|
|
SIGTRAP \05 \05 \05 \05
|
|
SIGABRT \06 \06 \06 \06
|
|
SIGIOT \06 \06 \06 \06
|
|
SIGBUS \07 10 10 10
|
|
SIGEMT \- \07 \07 -
|
|
SIGFPE \08 \08 \08 \08
|
|
SIGKILL \09 \09 \09 \09
|
|
SIGUSR1 10 30 16 16
|
|
SIGSEGV 11 11 11 11
|
|
SIGUSR2 12 31 17 17
|
|
SIGPIPE 13 13 13 13
|
|
SIGALRM 14 14 14 14
|
|
SIGTERM 15 15 15 15
|
|
SIGSTKFLT 16 \- \- \07
|
|
SIGCHLD 17 20 18 18
|
|
SIGCLD \- \- 18 \-
|
|
SIGCONT 18 19 25 26
|
|
SIGSTOP 19 17 23 24
|
|
SIGTSTP 20 18 24 25
|
|
SIGTTIN 21 21 26 27
|
|
SIGTTOU 22 22 27 28
|
|
SIGURG 23 16 21 29
|
|
SIGXCPU 24 24 30 12
|
|
SIGXFSZ 25 25 31 30
|
|
SIGVTALRM 26 26 28 20
|
|
SIGPROF 27 27 29 21
|
|
SIGWINCH 28 28 20 23
|
|
SIGIO 29 23 22 22
|
|
SIGPOLL Same as SIGIO
|
|
SIGPWR 30 29/\- 19 19
|
|
SIGINFO \- 29/\- \- \-
|
|
SIGLOST \- \-/29 \- \-
|
|
SIGSYS 31 12 12 31
|
|
SIGUNUSED 31 \- \- 31
|
|
.TE
|
|
.PP
|
|
Note the following:
|
|
.IP * 3
|
|
Where defined,
|
|
.B SIGUNUSED
|
|
is synonymous with
|
|
.BR SIGSYS .
|
|
Since glibc 2.26,
|
|
.B SIGUNUSED
|
|
is no longer defined on any architecture.
|
|
.IP *
|
|
Signal 29 is
|
|
.BR SIGINFO / SIGPWR
|
|
(synonyms for the same value) on Alpha but
|
|
.B SIGLOST
|
|
on SPARC.
|
|
.\"
|
|
.SS Real-time signals
|
|
Starting with version 2.2,
|
|
Linux supports real-time signals as originally defined in the POSIX.1b
|
|
real-time extensions (and now included in POSIX.1-2001).
|
|
The range of supported real-time signals is defined by the macros
|
|
.B SIGRTMIN
|
|
and
|
|
.BR SIGRTMAX .
|
|
POSIX.1-2001 requires that an implementation support at least
|
|
.B _POSIX_RTSIG_MAX
|
|
(8) real-time signals.
|
|
.PP
|
|
The Linux kernel supports a range of 33 different real-time
|
|
signals, numbered 32 to 64.
|
|
However, the glibc POSIX threads implementation internally uses
|
|
two (for NPTL) or three (for LinuxThreads) real-time signals
|
|
(see
|
|
.BR pthreads (7)),
|
|
and adjusts the value of
|
|
.B SIGRTMIN
|
|
suitably (to 34 or 35).
|
|
Because the range of available real-time signals varies according
|
|
to the glibc threading implementation (and this variation can occur
|
|
at run time according to the available kernel and glibc),
|
|
and indeed the range of real-time signals varies across UNIX systems,
|
|
programs should
|
|
.IR "never refer to real-time signals using hard-coded numbers" ,
|
|
but instead should always refer to real-time signals using the notation
|
|
.BR SIGRTMIN +n,
|
|
and include suitable (run-time) checks that
|
|
.BR SIGRTMIN +n
|
|
does not exceed
|
|
.BR SIGRTMAX .
|
|
.PP
|
|
Unlike standard signals, real-time signals have no predefined meanings:
|
|
the entire set of real-time signals can be used for application-defined
|
|
purposes.
|
|
.PP
|
|
The default action for an unhandled real-time signal is to terminate the
|
|
receiving process.
|
|
.PP
|
|
Real-time signals are distinguished by the following:
|
|
.IP 1. 4
|
|
Multiple instances of real-time signals can be queued.
|
|
By contrast, if multiple instances of a standard signal are delivered
|
|
while that signal is currently blocked, then only one instance is queued.
|
|
.IP 2. 4
|
|
If the signal is sent using
|
|
.BR sigqueue (3),
|
|
an accompanying value (either an integer or a pointer) can be sent
|
|
with the signal.
|
|
If the receiving process establishes a handler for this signal using the
|
|
.B SA_SIGINFO
|
|
flag to
|
|
.BR sigaction (2),
|
|
then it can obtain this data via the
|
|
.I si_value
|
|
field of the
|
|
.I siginfo_t
|
|
structure passed as the second argument to the handler.
|
|
Furthermore, the
|
|
.I si_pid
|
|
and
|
|
.I si_uid
|
|
fields of this structure can be used to obtain the PID
|
|
and real user ID of the process sending the signal.
|
|
.IP 3. 4
|
|
Real-time signals are delivered in a guaranteed order.
|
|
Multiple real-time signals of the same type are delivered in the order
|
|
they were sent.
|
|
If different real-time signals are sent to a process, they are delivered
|
|
starting with the lowest-numbered signal.
|
|
(I.e., low-numbered signals have highest priority.)
|
|
By contrast, if multiple standard signals are pending for a process,
|
|
the order in which they are delivered is unspecified.
|
|
.PP
|
|
If both standard and real-time signals are pending for a process,
|
|
POSIX leaves it unspecified which is delivered first.
|
|
Linux, like many other implementations, gives priority
|
|
to standard signals in this case.
|
|
.PP
|
|
According to POSIX, an implementation should permit at least
|
|
.B _POSIX_SIGQUEUE_MAX
|
|
(32) real-time signals to be queued to
|
|
a process.
|
|
However, Linux does things differently.
|
|
In kernels up to and including 2.6.7, Linux imposes
|
|
a system-wide limit on the number of queued real-time signals
|
|
for all processes.
|
|
This limit can be viewed and (with privilege) changed via the
|
|
.I /proc/sys/kernel/rtsig-max
|
|
file.
|
|
A related file,
|
|
.IR /proc/sys/kernel/rtsig-nr ,
|
|
can be used to find out how many real-time signals are currently queued.
|
|
In Linux 2.6.8, these
|
|
.I /proc
|
|
interfaces were replaced by the
|
|
.B RLIMIT_SIGPENDING
|
|
resource limit, which specifies a per-user limit for queued
|
|
signals; see
|
|
.BR setrlimit (2)
|
|
for further details.
|
|
.PP
|
|
The addition of real-time signals required the widening
|
|
of the signal set structure
|
|
.RI ( sigset_t )
|
|
from 32 to 64 bits.
|
|
Consequently, various system calls were superseded by new system calls
|
|
that supported the larger signal sets.
|
|
The old and new system calls are as follows:
|
|
.TS
|
|
lb lb
|
|
l l.
|
|
Linux 2.0 and earlier Linux 2.2 and later
|
|
\fBsigaction\fP(2) \fBrt_sigaction\fP(2)
|
|
\fBsigpending\fP(2) \fBrt_sigpending\fP(2)
|
|
\fBsigprocmask\fP(2) \fBrt_sigprocmask\fP(2)
|
|
\fBsigreturn\fP(2) \fBrt_sigreturn\fP(2)
|
|
\fBsigsuspend\fP(2) \fBrt_sigsuspend\fP(2)
|
|
\fBsigtimedwait\fP(2) \fBrt_sigtimedwait\fP(2)
|
|
.TE
|
|
.\"
|
|
.SS Interruption of system calls and library functions by signal handlers
|
|
If a signal handler is invoked while a system call or library
|
|
function call is blocked, then either:
|
|
.IP * 2
|
|
the call is automatically restarted after the signal handler returns; or
|
|
.IP *
|
|
the call fails with the error
|
|
.BR EINTR .
|
|
.PP
|
|
Which of these two behaviors occurs depends on the interface and
|
|
whether or not the signal handler was established using the
|
|
.BR SA_RESTART
|
|
flag (see
|
|
.BR sigaction (2)).
|
|
The details vary across UNIX systems;
|
|
below, the details for Linux.
|
|
.PP
|
|
If a blocked call to one of the following interfaces is interrupted
|
|
by a signal handler, then the call is automatically restarted
|
|
after the signal handler returns if the
|
|
.BR SA_RESTART
|
|
flag was used; otherwise the call fails with the error
|
|
.BR EINTR :
|
|
.\" The following system calls use ERESTARTSYS,
|
|
.\" so that they are restartable
|
|
.IP * 2
|
|
.BR read (2),
|
|
.BR readv (2),
|
|
.BR write (2),
|
|
.BR writev (2),
|
|
and
|
|
.BR ioctl (2)
|
|
calls on "slow" devices.
|
|
A "slow" device is one where the I/O call may block for an
|
|
indefinite time, for example, a terminal, pipe, or socket.
|
|
If an I/O call on a slow device has already transferred some
|
|
data by the time it is interrupted by a signal handler,
|
|
then the call will return a success status
|
|
(normally, the number of bytes transferred).
|
|
Note that a (local) disk is not a slow device according to this definition;
|
|
I/O operations on disk devices are not interrupted by signals.
|
|
.IP *
|
|
.BR open (2),
|
|
if it can block (e.g., when opening a FIFO; see
|
|
.BR fifo (7)).
|
|
.IP *
|
|
.BR wait (2),
|
|
.BR wait3 (2),
|
|
.BR wait4 (2),
|
|
.BR waitid (2),
|
|
and
|
|
.BR waitpid (2).
|
|
.IP *
|
|
Socket interfaces:
|
|
.\" If a timeout (setsockopt()) is in effect on the socket, then these
|
|
.\" system calls switch to using EINTR. Consequently, they and are not
|
|
.\" automatically restarted, and they show the stop/cont behavior
|
|
.\" described below. (Verified from 2.6.26 source, and by experiment; mtk)
|
|
.BR accept (2),
|
|
.BR connect (2),
|
|
.BR recv (2),
|
|
.BR recvfrom (2),
|
|
.BR recvmmsg (2),
|
|
.BR recvmsg (2),
|
|
.BR send (2),
|
|
.BR sendto (2),
|
|
and
|
|
.BR sendmsg (2),
|
|
.\" FIXME What about sendmmsg()?
|
|
unless a timeout has been set on the socket (see below).
|
|
.IP *
|
|
File locking interfaces:
|
|
.BR flock (2)
|
|
and
|
|
the
|
|
.BR F_SETLKW
|
|
and
|
|
.BR F_OFD_SETLKW
|
|
operations of
|
|
.BR fcntl (2)
|
|
.IP *
|
|
POSIX message queue interfaces:
|
|
.BR mq_receive (3),
|
|
.BR mq_timedreceive (3),
|
|
.BR mq_send (3),
|
|
and
|
|
.BR mq_timedsend (3).
|
|
.IP *
|
|
.BR futex (2)
|
|
.B FUTEX_WAIT
|
|
(since Linux 2.6.22;
|
|
.\" commit 72c1bbf308c75a136803d2d76d0e18258be14c7a
|
|
beforehand, always failed with
|
|
.BR EINTR ).
|
|
.IP *
|
|
.BR getrandom (2).
|
|
.IP *
|
|
.BR pthread_mutex_lock (3),
|
|
.BR pthread_cond_wait (3),
|
|
and related APIs.
|
|
.IP *
|
|
.BR futex (2)
|
|
.BR FUTEX_WAIT_BITSET .
|
|
.IP *
|
|
POSIX semaphore interfaces:
|
|
.BR sem_wait (3)
|
|
and
|
|
.BR sem_timedwait (3)
|
|
(since Linux 2.6.22;
|
|
.\" as a consequence of the 2.6.22 changes in the futex() implementation
|
|
beforehand, always failed with
|
|
.BR EINTR ).
|
|
.IP *
|
|
.BR read (2)
|
|
from an
|
|
.BR inotify (7)
|
|
file descriptor
|
|
(since Linux 3.8;
|
|
.\" commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06
|
|
beforehand, always failed with
|
|
.BR EINTR ).
|
|
.PP
|
|
The following interfaces are never restarted after
|
|
being interrupted by a signal handler,
|
|
regardless of the use of
|
|
.BR SA_RESTART ;
|
|
they always fail with the error
|
|
.B EINTR
|
|
when interrupted by a signal handler:
|
|
.\" These are the system calls that give EINTR or ERESTARTNOHAND
|
|
.\" on interruption by a signal handler.
|
|
.IP * 2
|
|
"Input" socket interfaces, when a timeout
|
|
.RB ( SO_RCVTIMEO )
|
|
has been set on the socket using
|
|
.BR setsockopt (2):
|
|
.BR accept (2),
|
|
.BR recv (2),
|
|
.BR recvfrom (2),
|
|
.BR recvmmsg (2)
|
|
(also with a non-NULL
|
|
.IR timeout
|
|
argument),
|
|
and
|
|
.BR recvmsg (2).
|
|
.IP *
|
|
"Output" socket interfaces, when a timeout
|
|
.RB ( SO_RCVTIMEO )
|
|
has been set on the socket using
|
|
.BR setsockopt (2):
|
|
.BR connect (2),
|
|
.BR send (2),
|
|
.BR sendto (2),
|
|
and
|
|
.BR sendmsg (2).
|
|
.\" FIXME What about sendmmsg()?
|
|
.IP *
|
|
Interfaces used to wait for signals:
|
|
.BR pause (2),
|
|
.BR sigsuspend (2),
|
|
.BR sigtimedwait (2),
|
|
and
|
|
.BR sigwaitinfo (2).
|
|
.IP *
|
|
File descriptor multiplexing interfaces:
|
|
.BR epoll_wait (2),
|
|
.BR epoll_pwait (2),
|
|
.BR poll (2),
|
|
.BR ppoll (2),
|
|
.BR select (2),
|
|
and
|
|
.BR pselect (2).
|
|
.IP *
|
|
System V IPC interfaces:
|
|
.\" On some other systems, SA_RESTART does restart these system calls
|
|
.BR msgrcv (2),
|
|
.BR msgsnd (2),
|
|
.BR semop (2),
|
|
and
|
|
.BR semtimedop (2).
|
|
.IP *
|
|
Sleep interfaces:
|
|
.BR clock_nanosleep (2),
|
|
.BR nanosleep (2),
|
|
and
|
|
.BR usleep (3).
|
|
.IP *
|
|
.BR io_getevents (2).
|
|
.PP
|
|
The
|
|
.BR sleep (3)
|
|
function is also never restarted if interrupted by a handler,
|
|
but gives a success return: the number of seconds remaining to sleep.
|
|
.SS Interruption of system calls and library functions by stop signals
|
|
On Linux, even in the absence of signal handlers,
|
|
certain blocking interfaces can fail with the error
|
|
.BR EINTR
|
|
after the process is stopped by one of the stop signals
|
|
and then resumed via
|
|
.BR SIGCONT .
|
|
This behavior is not sanctioned by POSIX.1, and doesn't occur
|
|
on other systems.
|
|
.PP
|
|
The Linux interfaces that display this behavior are:
|
|
.IP * 2
|
|
"Input" socket interfaces, when a timeout
|
|
.RB ( SO_RCVTIMEO )
|
|
has been set on the socket using
|
|
.BR setsockopt (2):
|
|
.BR accept (2),
|
|
.BR recv (2),
|
|
.BR recvfrom (2),
|
|
.BR recvmmsg (2)
|
|
(also with a non-NULL
|
|
.IR timeout
|
|
argument),
|
|
and
|
|
.BR recvmsg (2).
|
|
.IP *
|
|
"Output" socket interfaces, when a timeout
|
|
.RB ( SO_RCVTIMEO )
|
|
has been set on the socket using
|
|
.BR setsockopt (2):
|
|
.BR connect (2),
|
|
.BR send (2),
|
|
.BR sendto (2),
|
|
and
|
|
.\" FIXME What about sendmmsg()?
|
|
.BR sendmsg (2),
|
|
if a send timeout
|
|
.RB ( SO_SNDTIMEO )
|
|
has been set.
|
|
.IP * 2
|
|
.BR epoll_wait (2),
|
|
.BR epoll_pwait (2).
|
|
.IP *
|
|
.BR semop (2),
|
|
.BR semtimedop (2).
|
|
.IP *
|
|
.BR sigtimedwait (2),
|
|
.BR sigwaitinfo (2).
|
|
.IP *
|
|
Linux 3.7 and earlier:
|
|
.BR read (2)
|
|
from an
|
|
.BR inotify (7)
|
|
file descriptor
|
|
.\" commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06
|
|
.IP *
|
|
Linux 2.6.21 and earlier:
|
|
.BR futex (2)
|
|
.BR FUTEX_WAIT ,
|
|
.BR sem_timedwait (3),
|
|
.BR sem_wait (3).
|
|
.IP *
|
|
Linux 2.6.8 and earlier:
|
|
.BR msgrcv (2),
|
|
.BR msgsnd (2).
|
|
.IP *
|
|
Linux 2.4 and earlier:
|
|
.BR nanosleep (2).
|
|
.SH CONFORMING TO
|
|
POSIX.1, except as noted.
|
|
.SH NOTES
|
|
For a discussion of async-signal-safe functions, see
|
|
.BR signal\-safety (7).
|
|
.PP
|
|
The
|
|
.I /proc/[pid]/task/[tid]/status
|
|
file contains various fields that show the signals
|
|
that a thread is blocking
|
|
.RI ( SigBlk ),
|
|
catching
|
|
.RI ( SigCgt ),
|
|
or ignoring
|
|
.RI ( SigIgn ).
|
|
(The set of signals that are caught or ignored will be the same
|
|
across all threads in a process.)
|
|
Other fields show the set of pending signals that are directed to the thread
|
|
.RI ( SigPnd )
|
|
as well as the set of pending signals that are directed
|
|
to the process as a whole
|
|
.RI ( ShdPnd ).
|
|
The corresponding fields in
|
|
.I /proc/[pid]/status
|
|
show the information for the main thread.
|
|
See
|
|
.BR proc (5)
|
|
for further details.
|
|
.SH BUGS
|
|
There are six signals that can be delivered
|
|
as a consequence of a hardware exception:
|
|
.BR SIGBUS ,
|
|
.BR SIGEMT ,
|
|
.BR SIGFPE ,
|
|
.BR SIGILL ,
|
|
.BR SIGSEGV ,
|
|
and
|
|
.BR SIGTRAP .
|
|
Which of these signals is delivered,
|
|
for any given hardware exception,
|
|
is not documented and does not always make sense.
|
|
.PP
|
|
For example, an invalid memory access that causes delivery of
|
|
.B SIGSEGV
|
|
on one CPU architecture may cause delivery of
|
|
.B SIGBUS
|
|
on another architecture, or vice versa.
|
|
.PP
|
|
For another example, using the x86
|
|
.I int
|
|
instruction with a forbidden argument
|
|
(any number other than 3 or 128)
|
|
causes delivery of
|
|
.BR SIGSEGV ,
|
|
even though
|
|
.B SIGILL
|
|
would make more sense,
|
|
because of how the CPU reports the forbidden operation to the kernel.
|
|
.SH SEE ALSO
|
|
.BR kill (1),
|
|
.BR clone (2),
|
|
.BR getrlimit (2),
|
|
.BR kill (2),
|
|
.BR pidfd_send_signal (2),
|
|
.BR restart_syscall (2),
|
|
.BR rt_sigqueueinfo (2),
|
|
.BR setitimer (2),
|
|
.BR setrlimit (2),
|
|
.BR sgetmask (2),
|
|
.BR sigaction (2),
|
|
.BR sigaltstack (2),
|
|
.BR signal (2),
|
|
.BR signalfd (2),
|
|
.BR sigpending (2),
|
|
.BR sigprocmask (2),
|
|
.BR sigreturn (2),
|
|
.BR sigsuspend (2),
|
|
.BR sigwaitinfo (2),
|
|
.BR abort (3),
|
|
.BR bsd_signal (3),
|
|
.BR killpg (3),
|
|
.BR longjmp (3),
|
|
.BR pthread_sigqueue (3),
|
|
.BR raise (3),
|
|
.BR sigqueue (3),
|
|
.BR sigset (3),
|
|
.BR sigsetops (3),
|
|
.BR sigvec (3),
|
|
.BR sigwait (3),
|
|
.BR strsignal (3),
|
|
.BR swapcontext (3),
|
|
.BR sysv_signal (3),
|
|
.BR core (5),
|
|
.BR proc (5),
|
|
.BR nptl (7),
|
|
.BR pthreads (7),
|
|
.BR sigevent (7)
|