|
Packit |
7cfc04 |
.\" Copyright (c) 2000 Andries Brouwer <aeb@cwi.nl>
|
|
Packit |
7cfc04 |
.\" and Copyright (c) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\" and Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
|
|
Packit |
7cfc04 |
.\" <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\" based on work by Rik Faith <faith@cs.unc.edu>
|
|
Packit |
7cfc04 |
.\" and Mike Battersby <mike@starbug.apana.org.au>.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(VERBATIM)
|
|
Packit |
7cfc04 |
.\" Permission is granted to make and distribute verbatim copies of this
|
|
Packit |
7cfc04 |
.\" manual provided the copyright notice and this permission notice are
|
|
Packit |
7cfc04 |
.\" preserved on all copies.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Permission is granted to copy and distribute modified versions of this
|
|
Packit |
7cfc04 |
.\" manual under the conditions for verbatim copying, provided that the
|
|
Packit |
7cfc04 |
.\" entire resulting derived work is distributed under the terms of a
|
|
Packit |
7cfc04 |
.\" permission notice identical to this one.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
Packit |
7cfc04 |
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
Packit |
7cfc04 |
.\" responsibility for errors or omissions, or for damages resulting from
|
|
Packit |
7cfc04 |
.\" the use of the information contained herein. The author(s) may not
|
|
Packit |
7cfc04 |
.\" have taken the same level of care in the production of this manual,
|
|
Packit |
7cfc04 |
.\" which is licensed free of charge, as they might when working
|
|
Packit |
7cfc04 |
.\" professionally.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
Packit |
7cfc04 |
.\" the source, must acknowledge the copyright and authors of this work.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Modified 2004-11-19, mtk:
|
|
Packit |
7cfc04 |
.\" added pointer to sigaction.2 for details of ignoring SIGCHLD
|
|
Packit |
7cfc04 |
.\" 2007-06-03, mtk: strengthened portability warning, and rewrote
|
|
Packit |
7cfc04 |
.\" various sections.
|
|
Packit |
7cfc04 |
.\" 2008-07-11, mtk: rewrote and expanded portability discussion.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.TH SIGNAL 2 2017-09-15 "Linux" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
signal \- ANSI C signal handling
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.B #include <signal.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.B typedef void (*sighandler_t)(int);
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "sighandler_t signal(int " signum ", sighandler_t " handler );
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The behavior of
|
|
Packit |
7cfc04 |
.BR signal ()
|
|
Packit |
7cfc04 |
varies across UNIX versions,
|
|
Packit |
7cfc04 |
and has also varied historically across different versions of Linux.
|
|
Packit |
7cfc04 |
\fBAvoid its use\fP: use
|
|
Packit |
7cfc04 |
.BR sigaction (2)
|
|
Packit |
7cfc04 |
instead.
|
|
Packit |
7cfc04 |
See \fIPortability\fP below.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BR signal ()
|
|
Packit |
7cfc04 |
sets the disposition of the signal
|
|
Packit |
7cfc04 |
.I signum
|
|
Packit |
7cfc04 |
to
|
|
Packit |
7cfc04 |
.IR handler ,
|
|
Packit |
7cfc04 |
which is either
|
|
Packit |
7cfc04 |
.BR SIG_IGN ,
|
|
Packit |
7cfc04 |
.BR SIG_DFL ,
|
|
Packit |
7cfc04 |
or the address of a programmer-defined function (a "signal handler").
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If the signal
|
|
Packit |
7cfc04 |
.I signum
|
|
Packit |
7cfc04 |
is delivered to the process, then one of the following happens:
|
|
Packit |
7cfc04 |
.TP 3
|
|
Packit |
7cfc04 |
*
|
|
Packit |
7cfc04 |
If the disposition is set to
|
|
Packit |
7cfc04 |
.BR SIG_IGN ,
|
|
Packit |
7cfc04 |
then the signal is ignored.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
*
|
|
Packit |
7cfc04 |
If the disposition is set to
|
|
Packit |
7cfc04 |
.BR SIG_DFL ,
|
|
Packit |
7cfc04 |
then the default action associated with the signal (see
|
|
Packit |
7cfc04 |
.BR signal (7))
|
|
Packit |
7cfc04 |
occurs.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
*
|
|
Packit |
7cfc04 |
If the disposition is set to a function,
|
|
Packit |
7cfc04 |
then first either the disposition is reset to
|
|
Packit |
7cfc04 |
.BR SIG_DFL ,
|
|
Packit |
7cfc04 |
or the signal is blocked (see \fIPortability\fP below), and then
|
|
Packit |
7cfc04 |
.I handler
|
|
Packit |
7cfc04 |
is called with argument
|
|
Packit |
7cfc04 |
.IR signum .
|
|
Packit |
7cfc04 |
If invocation of the handler caused the signal to be blocked,
|
|
Packit |
7cfc04 |
then the signal is unblocked upon return from the handler.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The signals
|
|
Packit |
7cfc04 |
.B SIGKILL
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.B SIGSTOP
|
|
Packit |
7cfc04 |
cannot be caught or ignored.
|
|
Packit |
7cfc04 |
.SH RETURN VALUE
|
|
Packit |
7cfc04 |
.BR signal ()
|
|
Packit |
7cfc04 |
returns the previous value of the signal handler, or
|
|
Packit |
7cfc04 |
.B SIG_ERR
|
|
Packit |
7cfc04 |
on error.
|
|
Packit |
7cfc04 |
In the event of an error,
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
is set to indicate the cause.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
.I signum
|
|
Packit |
7cfc04 |
is invalid.
|
|
Packit |
7cfc04 |
.SH CONFORMING TO
|
|
Packit |
7cfc04 |
POSIX.1-2001, POSIX.1-2008, C89, C99.
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
The effects of
|
|
Packit |
7cfc04 |
.BR signal ()
|
|
Packit |
7cfc04 |
in a multithreaded process are unspecified.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
According to POSIX, the behavior of a process is undefined after it
|
|
Packit |
7cfc04 |
ignores a
|
|
Packit |
7cfc04 |
.BR SIGFPE ,
|
|
Packit |
7cfc04 |
.BR SIGILL ,
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.B SIGSEGV
|
|
Packit |
7cfc04 |
signal that was not generated by
|
|
Packit |
7cfc04 |
.BR kill (2)
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR raise (3).
|
|
Packit |
7cfc04 |
Integer division by zero has undefined result.
|
|
Packit |
7cfc04 |
On some architectures it will generate a
|
|
Packit |
7cfc04 |
.B SIGFPE
|
|
Packit |
7cfc04 |
signal.
|
|
Packit |
7cfc04 |
(Also dividing the most negative integer by \-1 may generate
|
|
Packit |
7cfc04 |
.BR SIGFPE .)
|
|
Packit |
7cfc04 |
Ignoring this signal might lead to an endless loop.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
See
|
|
Packit |
7cfc04 |
.BR sigaction (2)
|
|
Packit |
7cfc04 |
for details on what happens when the disposition
|
|
Packit |
7cfc04 |
.B SIGCHLD
|
|
Packit |
7cfc04 |
is set to
|
|
Packit |
7cfc04 |
.BR SIG_IGN .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
See
|
|
Packit |
7cfc04 |
.BR signal-safety (7)
|
|
Packit |
7cfc04 |
for a list of the async-signal-safe functions that can be
|
|
Packit |
7cfc04 |
safely called from inside a signal handler.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The use of
|
|
Packit |
7cfc04 |
.I sighandler_t
|
|
Packit |
7cfc04 |
is a GNU extension, exposed if
|
|
Packit |
7cfc04 |
.B _GNU_SOURCE
|
|
Packit |
7cfc04 |
is defined;
|
|
Packit |
7cfc04 |
.\" libc4 and libc5 define
|
|
Packit |
7cfc04 |
.\" .IR SignalHandler ;
|
|
Packit |
7cfc04 |
glibc also defines (the BSD-derived)
|
|
Packit |
7cfc04 |
.I sig_t
|
|
Packit |
7cfc04 |
if
|
|
Packit |
7cfc04 |
.B _BSD_SOURCE
|
|
Packit |
7cfc04 |
(glibc 2.19 and earlier)
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR _DEFAULT_SOURCE
|
|
Packit |
7cfc04 |
(glibc 2.19 and later)
|
|
Packit |
7cfc04 |
is defined.
|
|
Packit |
7cfc04 |
Without use of such a type, the declaration of
|
|
Packit |
7cfc04 |
.BR signal ()
|
|
Packit |
7cfc04 |
is the somewhat harder to read:
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
.BI "void ( *" signal "(int " signum ", void (*" handler ")(int)) ) (int);"
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.SS Portability
|
|
Packit |
7cfc04 |
The only portable use of
|
|
Packit |
7cfc04 |
.BR signal ()
|
|
Packit |
7cfc04 |
is to set a signal's disposition to
|
|
Packit |
7cfc04 |
.BR SIG_DFL
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR SIG_IGN .
|
|
Packit |
7cfc04 |
The semantics when using
|
|
Packit |
7cfc04 |
.BR signal ()
|
|
Packit |
7cfc04 |
to establish a signal handler vary across systems
|
|
Packit |
7cfc04 |
(and POSIX.1 explicitly permits this variation);
|
|
Packit |
7cfc04 |
.B do not use it for this purpose.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
POSIX.1 solved the portability mess by specifying
|
|
Packit |
7cfc04 |
.BR sigaction (2),
|
|
Packit |
7cfc04 |
which provides explicit control of the semantics when a
|
|
Packit |
7cfc04 |
signal handler is invoked; use that interface instead of
|
|
Packit |
7cfc04 |
.BR signal ().
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
In the original UNIX systems, when a handler that was established using
|
|
Packit |
7cfc04 |
.BR signal ()
|
|
Packit |
7cfc04 |
was invoked by the delivery of a signal,
|
|
Packit |
7cfc04 |
the disposition of the signal would be reset to
|
|
Packit |
7cfc04 |
.BR SIG_DFL ,
|
|
Packit |
7cfc04 |
and the system did not block delivery of further instances of the signal.
|
|
Packit |
7cfc04 |
This is equivalent to calling
|
|
Packit |
7cfc04 |
.BR sigaction (2)
|
|
Packit |
7cfc04 |
with the following flags:
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
sa.sa_flags = SA_RESETHAND | SA_NODEFER;
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
System\ V also provides these semantics for
|
|
Packit |
7cfc04 |
.BR signal ().
|
|
Packit |
7cfc04 |
This was bad because the signal might be delivered again
|
|
Packit |
7cfc04 |
before the handler had a chance to reestablish itself.
|
|
Packit |
7cfc04 |
Furthermore, rapid deliveries of the same signal could
|
|
Packit |
7cfc04 |
result in recursive invocations of the handler.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
BSD improved on this situation, but unfortunately also
|
|
Packit |
7cfc04 |
changed the semantics of the existing
|
|
Packit |
7cfc04 |
.BR signal ()
|
|
Packit |
7cfc04 |
interface while doing so.
|
|
Packit |
7cfc04 |
On BSD, when a signal handler is invoked,
|
|
Packit |
7cfc04 |
the signal disposition is not reset,
|
|
Packit |
7cfc04 |
and further instances of the signal are blocked from
|
|
Packit |
7cfc04 |
being delivered while the handler is executing.
|
|
Packit |
7cfc04 |
Furthermore, certain blocking system calls are automatically
|
|
Packit |
7cfc04 |
restarted if interrupted by a signal handler (see
|
|
Packit |
7cfc04 |
.BR signal (7)).
|
|
Packit |
7cfc04 |
The BSD semantics are equivalent to calling
|
|
Packit |
7cfc04 |
.BR sigaction (2)
|
|
Packit |
7cfc04 |
with the following flags:
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
sa.sa_flags = SA_RESTART;
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The situation on Linux is as follows:
|
|
Packit |
7cfc04 |
.IP * 2
|
|
Packit |
7cfc04 |
The kernel's
|
|
Packit |
7cfc04 |
.BR signal ()
|
|
Packit |
7cfc04 |
system call provides System\ V semantics.
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
By default, in glibc 2 and later, the
|
|
Packit |
7cfc04 |
.BR signal ()
|
|
Packit |
7cfc04 |
wrapper function does not invoke the kernel system call.
|
|
Packit |
7cfc04 |
Instead, it calls
|
|
Packit |
7cfc04 |
.BR sigaction (2)
|
|
Packit |
7cfc04 |
using flags that supply BSD semantics.
|
|
Packit |
7cfc04 |
This default behavior is provided as long as a suitable
|
|
Packit |
7cfc04 |
feature test macro is defined:
|
|
Packit |
7cfc04 |
.B _BSD_SOURCE
|
|
Packit |
7cfc04 |
on glibc 2.19 and earlier or
|
|
Packit |
7cfc04 |
.BR _DEFAULT_SOURCE
|
|
Packit |
7cfc04 |
in glibc 2.19 and later.
|
|
Packit |
7cfc04 |
(By default, these macros are defined; see
|
|
Packit |
7cfc04 |
.BR feature_test_macros (7)
|
|
Packit |
7cfc04 |
for details.)
|
|
Packit |
7cfc04 |
If such a feature test macro is not defined, then
|
|
Packit |
7cfc04 |
.BR signal ()
|
|
Packit |
7cfc04 |
provides System\ V semantics.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" System V semantics are also provided if one uses the separate
|
|
Packit |
7cfc04 |
.\" .BR sysv_signal (3)
|
|
Packit |
7cfc04 |
.\" function.
|
|
Packit |
7cfc04 |
.\" .IP *
|
|
Packit |
7cfc04 |
.\" The
|
|
Packit |
7cfc04 |
.\" .BR signal ()
|
|
Packit |
7cfc04 |
.\" function in Linux libc4 and libc5 provide System\ V semantics.
|
|
Packit |
7cfc04 |
.\" If one on a libc5 system includes
|
|
Packit |
7cfc04 |
.\" .I <bsd/signal.h>
|
|
Packit |
7cfc04 |
.\" instead of
|
|
Packit |
7cfc04 |
.\" .IR <signal.h> ,
|
|
Packit |
7cfc04 |
.\" then
|
|
Packit |
7cfc04 |
.\" .BR signal ()
|
|
Packit |
7cfc04 |
.\" provides BSD semantics.
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.BR kill (1),
|
|
Packit |
7cfc04 |
.BR alarm (2),
|
|
Packit |
7cfc04 |
.BR kill (2),
|
|
Packit |
7cfc04 |
.BR pause (2),
|
|
Packit |
7cfc04 |
.BR sigaction (2),
|
|
Packit |
7cfc04 |
.BR signalfd (2),
|
|
Packit |
7cfc04 |
.BR sigpending (2),
|
|
Packit |
7cfc04 |
.BR sigprocmask (2),
|
|
Packit |
7cfc04 |
.BR sigsuspend (2),
|
|
Packit |
7cfc04 |
.BR bsd_signal (3),
|
|
Packit |
7cfc04 |
.BR killpg (3),
|
|
Packit |
7cfc04 |
.BR raise (3),
|
|
Packit |
7cfc04 |
.BR siginterrupt (3),
|
|
Packit |
7cfc04 |
.BR sigqueue (3),
|
|
Packit |
7cfc04 |
.BR sigsetops (3),
|
|
Packit |
7cfc04 |
.BR sigvec (3),
|
|
Packit |
7cfc04 |
.BR sysv_signal (3),
|
|
Packit |
7cfc04 |
.BR signal (7)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|