2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2000 Andries Brouwer <aeb@cwi.nl>
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" and Copyright (c) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
|
2008-07-11 11:25:06 +00:00
|
|
|
.\" and Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
|
2008-07-18 03:55:11 +00:00
|
|
|
.\" <mtk.manpages@gmail.com>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" Modified 2004-11-19, mtk:
|
|
|
|
.\" added pointer to sigaction.2 for details of ignoring SIGCHLD
|
2008-07-11 11:16:14 +00:00
|
|
|
.\" 2007-06-03, mtk: strengthened portability warning, and rewrote
|
2007-05-27 21:33:14 +00:00
|
|
|
.\" various sections.
|
2008-07-11 11:16:14 +00:00
|
|
|
.\" 2008-07-11, mtk: rewrote and expanded portability discussion.
|
2004-11-19 17:34:32 +00:00
|
|
|
.\"
|
2013-02-09 02:34:59 +00:00
|
|
|
.TH SIGNAL 2 2013-02-09 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.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
|
2007-06-21 22:55:04 +00:00
|
|
|
The behavior of
|
2007-05-27 21:03:48 +00:00
|
|
|
.BR signal ()
|
intro.1, time.1, accept.2, bind.2, connect.2, execve.2, flock.2, getdents.2, getpriority.2, getuid.2, intro.2, ioctl.2, mincore.2, mknod.2, personality.2, ptrace.2, read.2, recv.2, select_tut.2, send.2, sendfile.2, shmctl.2, sigaction.2, signal.2, stat.2, times.2, truncate.2, umask.2, wait.2, MB_CUR_MAX.3, MB_LEN_MAX.3, argz_add.3, btowc.3, clearenv.3, clock.3, cmsg.3, end.3, endian.3, errno.3, exit.3, fgetwc.3, fgetws.3, fopen.3, fputwc.3, fputws.3, fseek.3, fwide.3, getfsent.3, getgrnam.3, gethostid.3, getipnodebyname.3, getmntent.3, getpwnam.3, getwchar.3, grantpt.3, iconv.3, iconv_close.3, iconv_open.3, insque.3, intro.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, malloc.3, mblen.3, mbrlen.3, mbrtowc.3, mbsinit.3, mbsnrtowcs.3, mbsrtowcs.3, mbstowcs.3, mbtowc.3, mkstemp.3, mktemp.3, nl_langinfo.3, openpty.3, posix_openpt.3, printf.3, ptsname.3, putwchar.3, qecvt.3, rcmd.3, readdir.3, rexec.3, rpc.3, setnetgrent.3, shm_open.3, sigpause.3, stdin.3, stpcpy.3, strftime.3, strptime.3, syslog.3, towctrans.3, towlower.3, towupper.3, ttyslot.3, ungetwc.3, unlocked_stdio.3, wcpcpy.3, wcpncpy.3, wcrtomb.3, wcscasecmp.3, wcscat.3, wcschr.3, wcscmp.3, wcscpy.3, wcscspn.3, wcsdup.3, wcslen.3, wcsncasecmp.3, wcsncat.3, wcsncmp.3, wcsncpy.3, wcsnlen.3, wcsnrtombs.3, wcspbrk.3, wcsrchr.3, wcsrtombs.3, wcsspn.3, wcsstr.3, wcstok.3, wcstombs.3, wcswidth.3, wctob.3, wctomb.3, wctrans.3, wctype.3, wcwidth.3, wmemchr.3, wmemcmp.3, wmemcpy.3, wmemmove.3, wmemset.3, wprintf.3, console_ioctl.4, pts.4, elf.5, filesystems.5, hosts.5, proc.5, ttytype.5, boot.7, capabilities.7, credentials.7, epoll.7, glob.7, koi8-r.7, path_resolution.7, pty.7, signal.7, suffixes.7, time.7, unicode.7, unix.7, uri.7, utf-8.7: global fix: s/Unix/UNIX/
The man pages were rather inconsistent in the use of "Unix"
versus "UNIX". Let's go with the trademark usage.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-10-12 04:45:38 +00:00
|
|
|
varies across UNIX versions,
|
2007-05-27 21:03:48 +00:00
|
|
|
and has also varied historically across different versions of Linux.
|
|
|
|
\fBAvoid its use\fP: use
|
|
|
|
.BR sigaction (2)
|
|
|
|
instead.
|
|
|
|
See \fIPortability\fP below.
|
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR signal ()
|
2007-05-27 21:33:14 +00:00
|
|
|
sets the disposition of the signal
|
2007-09-20 16:26:31 +00:00
|
|
|
.I signum
|
2007-05-27 21:33:14 +00:00
|
|
|
to
|
|
|
|
.IR handler ,
|
|
|
|
which is either
|
|
|
|
.BR SIG_IGN ,
|
|
|
|
.BR SIG_DFL ,
|
2007-07-10 03:57:50 +00:00
|
|
|
or the address of a programmer-defined function (a "signal handler").
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2007-05-27 21:33:14 +00:00
|
|
|
If the signal
|
2004-11-03 13:51:07 +00:00
|
|
|
.I signum
|
2007-05-27 21:33:14 +00:00
|
|
|
is delivered to the process, then one of the following happens:
|
|
|
|
.TP 3
|
|
|
|
*
|
|
|
|
If the disposition is set to
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR SIG_IGN ,
|
|
|
|
then the signal is ignored.
|
2007-05-27 21:33:14 +00:00
|
|
|
.TP
|
|
|
|
*
|
|
|
|
If the disposition is set to
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR SIG_DFL ,
|
2004-12-13 08:40:20 +00:00
|
|
|
then the default action associated with the signal (see
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR signal (7))
|
|
|
|
occurs.
|
2007-05-27 21:33:14 +00:00
|
|
|
.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
|
2006-12-27 03:54:12 +00:00
|
|
|
.I handler
|
2004-11-03 13:51:07 +00:00
|
|
|
is called with argument
|
|
|
|
.IR signum .
|
2007-06-08 10:58:53 +00:00
|
|
|
If invocation of the handler caused the signal to be blocked,
|
2007-05-27 21:33:14 +00:00
|
|
|
then the signal is unblocked upon return from the handler.
|
|
|
|
.PP
|
2004-11-03 13:51:07 +00:00
|
|
|
The signals
|
|
|
|
.B SIGKILL
|
|
|
|
and
|
|
|
|
.B SIGSTOP
|
|
|
|
cannot be caught or ignored.
|
|
|
|
.SH "RETURN VALUE"
|
|
|
|
.BR signal ()
|
2007-05-27 21:03:48 +00:00
|
|
|
returns the previous value of the signal handler, or
|
2004-11-03 13:51:07 +00:00
|
|
|
.B SIG_ERR
|
|
|
|
on error.
|
2007-05-27 21:33:14 +00:00
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
.I signum
|
|
|
|
is invalid.
|
2007-05-18 16:30:46 +00:00
|
|
|
.SH "CONFORMING TO"
|
|
|
|
C89, C99, POSIX.1-2001.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NOTES
|
2007-06-21 22:55:04 +00:00
|
|
|
The effects of
|
2007-05-27 21:33:14 +00:00
|
|
|
.BR signal ()
|
2008-11-19 19:31:54 +00:00
|
|
|
in a multithreaded process are unspecified.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2007-06-08 09:56:56 +00:00
|
|
|
According to POSIX, the behavior of a process is undefined after it
|
2004-11-03 13:51:07 +00:00
|
|
|
ignores a
|
|
|
|
.BR SIGFPE ,
|
|
|
|
.BR SIGILL ,
|
|
|
|
or
|
|
|
|
.B SIGSEGV
|
2007-05-27 21:03:48 +00:00
|
|
|
signal that was not generated by
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR kill (2)
|
2007-07-10 03:57:50 +00:00
|
|
|
or
|
2007-05-27 21:03:48 +00:00
|
|
|
.BR raise (3).
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2004-11-19 17:34:32 +00:00
|
|
|
See
|
|
|
|
.BR sigaction (2)
|
|
|
|
for details on what happens when
|
2004-11-03 13:51:07 +00:00
|
|
|
.B SIGCHLD
|
|
|
|
is set to
|
|
|
|
.BR SIG_IGN .
|
|
|
|
.PP
|
2007-05-04 20:32:31 +00:00
|
|
|
See
|
|
|
|
.BR signal (7)
|
2007-06-21 22:55:04 +00:00
|
|
|
for a list of the async-signal-safe functions that can be
|
2008-07-11 11:16:14 +00:00
|
|
|
safely called from inside a signal handler.
|
2007-05-04 20:32:31 +00:00
|
|
|
.PP
|
2004-11-03 13:51:07 +00:00
|
|
|
The use of
|
2007-06-23 07:19:07 +00:00
|
|
|
.I sighandler_t
|
2012-05-04 23:51:22 +00:00
|
|
|
is a GNU extension, exposed if
|
2004-11-03 13:51:07 +00:00
|
|
|
.B _GNU_SOURCE
|
2012-05-04 23:51:22 +00:00
|
|
|
is defined;
|
|
|
|
.\" libc4 and libc5 define
|
|
|
|
.\" .IR SignalHandler ;
|
|
|
|
glibc also defines (the BSD-derived)
|
|
|
|
.I sig_t
|
|
|
|
if
|
|
|
|
.B _BSD_SOURCE
|
|
|
|
is defined.
|
2008-07-11 11:16:14 +00:00
|
|
|
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
|
2007-05-16 02:45:55 +00:00
|
|
|
.SS Portability
|
2008-07-11 11:16:14 +00:00
|
|
|
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
|
2007-05-16 02:45:55 +00:00
|
|
|
.BR signal ()
|
2008-07-11 11:16:14 +00:00
|
|
|
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 ().
|
|
|
|
|
intro.1, time.1, accept.2, bind.2, connect.2, execve.2, flock.2, getdents.2, getpriority.2, getuid.2, intro.2, ioctl.2, mincore.2, mknod.2, personality.2, ptrace.2, read.2, recv.2, select_tut.2, send.2, sendfile.2, shmctl.2, sigaction.2, signal.2, stat.2, times.2, truncate.2, umask.2, wait.2, MB_CUR_MAX.3, MB_LEN_MAX.3, argz_add.3, btowc.3, clearenv.3, clock.3, cmsg.3, end.3, endian.3, errno.3, exit.3, fgetwc.3, fgetws.3, fopen.3, fputwc.3, fputws.3, fseek.3, fwide.3, getfsent.3, getgrnam.3, gethostid.3, getipnodebyname.3, getmntent.3, getpwnam.3, getwchar.3, grantpt.3, iconv.3, iconv_close.3, iconv_open.3, insque.3, intro.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, malloc.3, mblen.3, mbrlen.3, mbrtowc.3, mbsinit.3, mbsnrtowcs.3, mbsrtowcs.3, mbstowcs.3, mbtowc.3, mkstemp.3, mktemp.3, nl_langinfo.3, openpty.3, posix_openpt.3, printf.3, ptsname.3, putwchar.3, qecvt.3, rcmd.3, readdir.3, rexec.3, rpc.3, setnetgrent.3, shm_open.3, sigpause.3, stdin.3, stpcpy.3, strftime.3, strptime.3, syslog.3, towctrans.3, towlower.3, towupper.3, ttyslot.3, ungetwc.3, unlocked_stdio.3, wcpcpy.3, wcpncpy.3, wcrtomb.3, wcscasecmp.3, wcscat.3, wcschr.3, wcscmp.3, wcscpy.3, wcscspn.3, wcsdup.3, wcslen.3, wcsncasecmp.3, wcsncat.3, wcsncmp.3, wcsncpy.3, wcsnlen.3, wcsnrtombs.3, wcspbrk.3, wcsrchr.3, wcsrtombs.3, wcsspn.3, wcsstr.3, wcstok.3, wcstombs.3, wcswidth.3, wctob.3, wctomb.3, wctrans.3, wctype.3, wcwidth.3, wmemchr.3, wmemcmp.3, wmemcpy.3, wmemmove.3, wmemset.3, wprintf.3, console_ioctl.4, pts.4, elf.5, filesystems.5, hosts.5, proc.5, ttytype.5, boot.7, capabilities.7, credentials.7, epoll.7, glob.7, koi8-r.7, path_resolution.7, pty.7, signal.7, suffixes.7, time.7, unicode.7, unix.7, uri.7, utf-8.7: global fix: s/Unix/UNIX/
The man pages were rather inconsistent in the use of "Unix"
versus "UNIX". Let's go with the trademark usage.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-10-12 04:45:38 +00:00
|
|
|
In the original UNIX systems, when a handler that was established using
|
2008-07-11 11:16:14 +00:00
|
|
|
.BR signal ()
|
|
|
|
was invoked by the delivery of a signal,
|
|
|
|
the disposition of the signal would be reset to
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR SIG_DFL ,
|
2008-07-11 11:16:14 +00:00
|
|
|
and the system did not block delivery of further instances of the signal.
|
2013-02-09 02:34:59 +00:00
|
|
|
This is equivalent to calling
|
|
|
|
.BR sigaction (2)
|
|
|
|
with the following flags:
|
|
|
|
|
|
|
|
sa.sa_flags = SA_RESETHAND | SA_NODEFER;
|
|
|
|
|
2008-07-11 11:16:14 +00:00
|
|
|
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.
|
|
|
|
|
2013-02-09 02:34:59 +00:00
|
|
|
BSD improved on this situation, but unfortunately also
|
|
|
|
changed the semantics of the existing
|
|
|
|
.BR signal ()
|
|
|
|
interface while doing so.
|
2008-07-11 11:16:14 +00:00
|
|
|
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.
|
2013-02-09 02:34:59 +00:00
|
|
|
Furthermore, certain blocking system calls are automatically
|
|
|
|
restarted if interrupted by a signal handler (see
|
|
|
|
.BR signal (7)).
|
|
|
|
The BSD semantics are equivalent to calling
|
|
|
|
.BR sigaction (2)
|
|
|
|
with the following flags:
|
|
|
|
|
|
|
|
sa.sa_flags = SA_RESTART;
|
2007-05-16 02:45:55 +00:00
|
|
|
|
2008-07-11 11:16:14 +00:00
|
|
|
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).)
|
2008-07-16 13:11:30 +00:00
|
|
|
.\"
|
2008-07-11 11:16:14 +00:00
|
|
|
.\" 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.
|
2007-05-16 02:45:55 +00:00
|
|
|
If one on a libc5 system includes
|
2007-06-20 21:53:34 +00:00
|
|
|
.I <bsd/signal.h>
|
2007-05-16 02:45:55 +00:00
|
|
|
instead of
|
2008-07-11 11:16:14 +00:00
|
|
|
.IR <signal.h> ,
|
2007-05-16 02:45:55 +00:00
|
|
|
then
|
|
|
|
.BR signal ()
|
2008-07-11 11:16:14 +00:00
|
|
|
provides BSD semantics.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR kill (1),
|
|
|
|
.BR alarm (2),
|
|
|
|
.BR kill (2),
|
2007-07-08 15:05:14 +00:00
|
|
|
.BR killpg (2),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR pause (2),
|
|
|
|
.BR sigaction (2),
|
2008-02-11 11:41:18 +00:00
|
|
|
.BR signalfd (2),
|
2005-09-15 09:20:05 +00:00
|
|
|
.BR sigpending (2),
|
|
|
|
.BR sigprocmask (2),
|
|
|
|
.BR sigsuspend (2),
|
2007-05-04 21:22:28 +00:00
|
|
|
.BR bsd_signal (3),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR raise (3),
|
2007-05-27 21:03:48 +00:00
|
|
|
.BR siginterrupt (3),
|
getrlimit.2, kill.2, rt_sigqueueinfo.2, sigaction.2, signal.2, signalfd.2, sigprocmask.2, sigwaitinfo.2, psignal.3, pthread_sigqueue.3, credentials.7, signal.7: Change reference to "sigqueue(2)" to "sigqueue(3)"
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2011-09-18 04:27:57 +00:00
|
|
|
.BR sigqueue (3),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR sigsetops (3),
|
2005-11-29 15:01:54 +00:00
|
|
|
.BR sigvec (3),
|
2007-05-04 21:22:28 +00:00
|
|
|
.BR sysv_signal (3),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR signal (7)
|