mirror of https://github.com/mkerrisk/man-pages
279 lines
7.2 KiB
Groff
279 lines
7.2 KiB
Groff
.\" Copyright (c) 2000 Andries Brouwer <aeb@cwi.nl>
|
|
.\" and Copyright (c) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" and Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
|
|
.\" <mtk.manpages@gmail.com>
|
|
.\" based on work by Rik Faith <faith@cs.unc.edu>
|
|
.\" and Mike Battersby <mike@starbug.apana.org.au>.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" Modified 2004-11-19, mtk:
|
|
.\" added pointer to sigaction.2 for details of ignoring SIGCHLD
|
|
.\" 2007-06-03, mtk: strengthened portability warning, and rewrote
|
|
.\" various sections.
|
|
.\" 2008-07-11, mtk: rewrote and expanded portability discussion.
|
|
.\"
|
|
.TH SIGNAL 2 2008-07-11 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
signal \- ANSI C signal handling
|
|
.SH SYNOPSIS
|
|
.B #include <signal.h>
|
|
.sp
|
|
.B typedef void (*sighandler_t)(int);
|
|
.sp
|
|
.BI "sighandler_t signal(int " signum ", sighandler_t " handler );
|
|
.SH DESCRIPTION
|
|
The behavior of
|
|
.BR signal ()
|
|
varies across Unix versions,
|
|
and has also varied historically across different versions of Linux.
|
|
\fBAvoid its use\fP: use
|
|
.BR sigaction (2)
|
|
instead.
|
|
See \fIPortability\fP below.
|
|
|
|
.BR signal ()
|
|
sets the disposition of the signal
|
|
.I signum
|
|
to
|
|
.IR handler ,
|
|
which is either
|
|
.BR SIG_IGN ,
|
|
.BR SIG_DFL ,
|
|
or the address of a programmer-defined function (a "signal handler").
|
|
|
|
If the signal
|
|
.I signum
|
|
is delivered to the process, then one of the following happens:
|
|
.TP 3
|
|
*
|
|
If the disposition is set to
|
|
.BR SIG_IGN ,
|
|
then the signal is ignored.
|
|
.TP
|
|
*
|
|
If the disposition is set to
|
|
.BR SIG_DFL ,
|
|
then the default action associated with the signal (see
|
|
.BR signal (7))
|
|
occurs.
|
|
.TP
|
|
*
|
|
If the disposition is set to a function,
|
|
then first either the disposition is reset to
|
|
.BR SIG_DFL ,
|
|
or the signal is blocked (see \fIPortability\fP below), and then
|
|
.I handler
|
|
is called with argument
|
|
.IR signum .
|
|
If invocation of the handler caused the signal to be blocked,
|
|
then the signal is unblocked upon return from the handler.
|
|
.PP
|
|
The signals
|
|
.B SIGKILL
|
|
and
|
|
.B SIGSTOP
|
|
cannot be caught or ignored.
|
|
.SH "RETURN VALUE"
|
|
.BR signal ()
|
|
returns the previous value of the signal handler, or
|
|
.B SIG_ERR
|
|
on error.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EINVAL
|
|
.I signum
|
|
is invalid.
|
|
.SH "CONFORMING TO"
|
|
C89, C99, POSIX.1-2001.
|
|
.SH NOTES
|
|
The effects of
|
|
.BR signal ()
|
|
in a multithreaded process are unspecified.
|
|
.PP
|
|
According to POSIX, the behavior of a process is undefined after it
|
|
ignores a
|
|
.BR SIGFPE ,
|
|
.BR SIGILL ,
|
|
or
|
|
.B SIGSEGV
|
|
signal that was not generated by
|
|
.BR kill (2)
|
|
or
|
|
.BR raise (3).
|
|
Integer division by zero has undefined result.
|
|
On some architectures it will generate a
|
|
.B SIGFPE
|
|
signal.
|
|
(Also dividing the most negative integer by \-1 may generate
|
|
.BR SIGFPE .)
|
|
Ignoring this signal might lead to an endless loop.
|
|
.PP
|
|
See
|
|
.BR sigaction (2)
|
|
for details on what happens when
|
|
.B SIGCHLD
|
|
is set to
|
|
.BR SIG_IGN .
|
|
.PP
|
|
See
|
|
.BR signal (7)
|
|
for a list of the async-signal-safe functions that can be
|
|
safely called from inside a signal handler.
|
|
.PP
|
|
The use of
|
|
.I sighandler_t
|
|
is a GNU extension.
|
|
Various versions of libc predefine this type; libc4 and libc5 define
|
|
.IR SignalHandler ;
|
|
glibc defines
|
|
.I sig_t
|
|
and, when
|
|
.B _GNU_SOURCE
|
|
is defined, also
|
|
.IR sighandler_t .
|
|
Without use of such a type, the declaration of
|
|
.BR signal ()
|
|
is the somewhat harder to read:
|
|
.in +4n
|
|
.nf
|
|
|
|
.BI "void ( *" signal "(int " signum ", void (*" handler ")(int)) ) (int);"
|
|
.fi
|
|
.in
|
|
.SS Portability
|
|
The only portable use of
|
|
.BR signal ()
|
|
is to set a signal's disposition to
|
|
.BR SIG_DFL
|
|
or
|
|
.BR SIG_IGN .
|
|
The semantics when using
|
|
.BR signal ()
|
|
to establish a signal handler vary across systems
|
|
(and POSIX.1 explicitly permits this variation);
|
|
.B do not use it for this purpose.
|
|
|
|
POSIX.1 solved the portability mess by specifying
|
|
.BR sigaction (2),
|
|
which provides explicit control of the semantics when a
|
|
signal handler is invoked; use that interface instead of
|
|
.BR signal ().
|
|
|
|
In the original Unix systems, when a handler that was established using
|
|
.BR signal ()
|
|
was invoked by the delivery of a signal,
|
|
the disposition of the signal would be reset to
|
|
.BR SIG_DFL ,
|
|
and the system did not block delivery of further instances of the signal.
|
|
System V also provides these semantics for
|
|
.BR signal ().
|
|
This was bad because the signal might be delivered again
|
|
before the handler had a chance to reestablish itself.
|
|
Furthermore, rapid deliveries of the same signal could
|
|
result in recursive invocations of the handler.
|
|
|
|
BSD improved on this situation by changing the semantics of
|
|
signal handling
|
|
(but, unfortunately, silently changed the semantics
|
|
when establishing a handler with
|
|
.BR signal ()).
|
|
On BSD, when a signal handler is invoked,
|
|
the signal disposition is not reset,
|
|
and further instances of the signal are blocked from
|
|
being delivered while the handler is executing.
|
|
|
|
The situation on Linux is as follows:
|
|
.IP * 2
|
|
The kernel's
|
|
.BR signal ()
|
|
system call provides System V semantics.
|
|
.IP *
|
|
By default, in glibc 2 and later, the
|
|
.BR signal ()
|
|
wrapper function does not invoke the kernel system call.
|
|
Instead, it calls
|
|
.BR sigaction (2)
|
|
using flags that supply BSD semantics.
|
|
This default behavior is provided as long as the
|
|
.B _BSD_SOURCE
|
|
feature test macro is defined.
|
|
By default,
|
|
.B _BSD_SOURCE
|
|
is defined;
|
|
it is also implicitly defined if one defines
|
|
.BR _GNU_SOURCE ,
|
|
and can of course be explicitly defined.
|
|
.sp
|
|
On glibc 2 and later, if the
|
|
.B _BSD_SOURCE
|
|
feature test macro is not defined, then
|
|
.BR signal ()
|
|
provides System V semantics.
|
|
(The default implicit definition of
|
|
.B _BSD_SOURCE
|
|
is not provided if one invokes
|
|
.BR gcc (1)
|
|
in one of its standard modes
|
|
.RI ( -std=xxx " or " -ansi )
|
|
or defines various other feature test macros such as
|
|
.BR _POSIX_SOURCE ,
|
|
.BR _XOPEN_SOURCE ,
|
|
or
|
|
.BR _SVID_SOURCE ;
|
|
see
|
|
.BR feature_test_macros (7).)
|
|
.\"
|
|
.\" System V semantics are also provided if one uses the separate
|
|
.\" .BR sysv_signal (3)
|
|
.\" function.
|
|
.IP *
|
|
The
|
|
.BR signal ()
|
|
function in Linux libc4 and libc5 provide System V semantics.
|
|
If one on a libc5 system includes
|
|
.I <bsd/signal.h>
|
|
instead of
|
|
.IR <signal.h> ,
|
|
then
|
|
.BR signal ()
|
|
provides BSD semantics.
|
|
.SH "SEE ALSO"
|
|
.BR kill (1),
|
|
.BR alarm (2),
|
|
.BR kill (2),
|
|
.BR killpg (2),
|
|
.BR pause (2),
|
|
.BR sigaction (2),
|
|
.BR signalfd (2),
|
|
.BR sigpending (2),
|
|
.BR sigprocmask (2),
|
|
.BR sigqueue (2),
|
|
.BR sigsuspend (2),
|
|
.BR bsd_signal (3),
|
|
.BR raise (3),
|
|
.BR siginterrupt (3),
|
|
.BR sigsetops (3),
|
|
.BR sigvec (3),
|
|
.BR sysv_signal (3),
|
|
.BR feature_test_macros (7),
|
|
.BR signal (7)
|