.\" 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>.
.\"
+.\" %%%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.
.\" 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
.\" 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
.\"
-.TH SIGNAL 2 2000-04-28 "Linux 2.2" "Linux Programmer's Manual"
+.\" 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 2017-09-15 "Linux" "Linux Programmer's Manual"
.SH NAME
signal \- ANSI C signal handling
.SH SYNOPSIS
.B #include <signal.h>
-.sp
+.PP
.B typedef void (*sighandler_t)(int);
-.sp
+.PP
.BI "sighandler_t signal(int " signum ", sighandler_t " handler );
.SH DESCRIPTION
-The
+The behavior of
.BR signal ()
-system call installs a new signal handler for the signal with number
-.IR signum .
-The signal handler is set to
-.I sighandler
-which may be a user specified function, or either
-.B SIG_IGN
-or
-.BR SIG_DFL .
-
-Upon arrival of a signal with number
+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.
+.PP
+.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").
+.PP
+If the signal
.I signum
-the following happens.
-If the corresponding handler is set to
+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.
-If the handler is set to
+.TP
+*
+If the disposition is set to
.BR SIG_DFL ,
-then the default action associated to the signal (see
+then the default action associated with the signal (see
.BR signal (7))
occurs.
-Finally, if the handler is set to a function
-.I sighandler
-then first either the handler is reset to SIG_DFL
-or an implementation-dependent blocking of the signal
-is performed and next
-.I sighandler
+.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 .
-
-Using a signal handler function for a signal
-is called "catching the signal".
+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"
-The
+.SH RETURN VALUE
.BR signal ()
-function returns the previous value of the signal handler, or
+returns the previous value of the signal handler, or
.B SIG_ERR
on error.
-
-.SH PORTABILITY
-The original Unix
-.BR signal ()
-would reset the handler to SIG_DFL, and System V
-(and the Linux kernel and libc4,5) does the same.
-On the other hand, BSD does not reset the handler, but blocks
-new instances of this signal from occurring during a call of the handler.
-The glibc2 library follows the BSD behaviour.
-
-If one on a libc5 system includes
-.B "<bsd/signal.h>"
-instead of
-.B "<signal.h>"
-then
-.B signal
-is redefined as
-.B __bsd_signal
-and signal has the BSD semantics. This is not recommended.
-
-If one on a glibc2 system defines a feature test
-macro such as
-.B _XOPEN_SOURCE
-or uses a separate
-.B sysv_signal
-function, one obtains classical behaviour. This is not recommended.
-
-Trying to change the semantics of this call using
-defines and includes is not a good idea. It is better to avoid
-.B signal
-altogether, and use
-.BR sigaction (2)
-instead.
-
+In the event of an error,
+.I errno
+is set to indicate the cause.
+.SH ERRORS
+.TP
+.B EINVAL
+.I signum
+is invalid.
+.SH CONFORMING TO
+POSIX.1-2001, POSIX.1-2008, C89, C99.
.SH NOTES
-The effects of this call in a multi-threaded process are unspecified.
-.PP
-The routine
-.I handler
-must be very careful, since processing elsewhere was interrupted
-at some arbitrary point. POSIX has the concept of "safe function".
-If a signal interrupts an unsafe function, and
-.I handler
-calls an unsafe function, then the behavior is undefined. Safe
-functions are listed explicitly in the various standards.
-The POSIX 1003.1-2003 list is
-
-_Exit()
-_exit()
-abort()
-accept()
-access()
-aio_error()
-aio_return()
-aio_suspend()
-alarm()
-bind()
-cfgetispeed()
-cfgetospeed()
-cfsetispeed()
-cfsetospeed()
-chdir()
-chmod()
-chown()
-clock_gettime()
-close()
-connect()
-creat()
-dup()
-dup2()
-execle()
-execve()
-fchmod()
-fchown()
-fcntl()
-fdatasync()
-fork()
-fpathconf()
-fstat()
-fsync()
-ftruncate()
-getegid()
-geteuid()
-getgid()
-getgroups()
-getpeername()
-getpgrp()
-getpid()
-getppid()
-getsockname()
-getsockopt()
-getuid()
-kill()
-link()
-listen()
-lseek()
-lstat()
-mkdir()
-mkfifo()
-open()
-pathconf()
-pause()
-pipe()
-poll()
-posix_trace_event()
-pselect()
-raise()
-read()
-readlink()
-recv()
-recvfrom()
-recvmsg()
-rename()
-rmdir()
-select()
-sem_post()
-send()
-sendmsg()
-sendto()
-setgid()
-setpgid()
-setsid()
-setsockopt()
-setuid()
-shutdown()
-sigaction()
-sigaddset()
-sigdelset()
-sigemptyset()
-sigfillset()
-sigismember()
-signal()
-sigpause()
-sigpending()
-sigprocmask()
-sigqueue()
-sigset()
-sigsuspend()
-sleep()
-socket()
-socketpair()
-stat()
-symlink()
-sysconf()
-tcdrain()
-tcflow()
-tcflush()
-tcgetattr()
-tcgetpgrp()
-tcsendbreak()
-tcsetattr()
-tcsetpgrp()
-time()
-timer_getoverrun()
-timer_gettime()
-timer_settime()
-times()
-umask()
-uname()
-unlink()
-utime()
-wait()
-waitpid()
-write().
+The effects of
+.BR signal ()
+in a multithreaded process are unspecified.
.PP
-According to POSIX, the behaviour of a process is undefined after it
+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 the
+signal that was not generated by
.BR kill (2)
-or the
-.BR raise (3)
-functions.
+or
+.BR raise (3).
Integer division by zero has undefined result.
On some architectures it will generate a
.B SIGFPE
.BR SIGFPE .)
Ignoring this signal might lead to an endless loop.
.PP
-According to POSIX (3.3.1.3) it is unspecified what happens when
+See
+.BR sigaction (2)
+for details on what happens when the disposition
.B SIGCHLD
is set to
.BR SIG_IGN .
-Here the BSD and SYSV behaviours differ, causing BSD software
-that sets the action for
-.B SIGCHLD
-to
-.B SIG_IGN
-to fail on Linux.
+.PP
+See
+.BR signal-safety (7)
+for a list of the async-signal-safe functions that can be
+safely called from inside a signal handler.
.PP
The use of
-.B 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
+.I sighandler_t
+is a GNU extension, exposed if
.B _GNU_SOURCE
-is defined, also
-.IR sighandler_t .
-.SH "CONFORMING TO"
-ANSI C
-
-.SH "SEE ALSO"
+is defined;
+.\" libc4 and libc5 define
+.\" .IR SignalHandler ;
+glibc also defines (the BSD-derived)
+.I sig_t
+if
+.B _BSD_SOURCE
+(glibc 2.19 and earlier)
+or
+.BR _DEFAULT_SOURCE
+(glibc 2.19 and later)
+is defined.
+Without use of such a type, the declaration of
+.BR signal ()
+is the somewhat harder to read:
+.PP
+.in +4n
+.EX
+.BI "void ( *" signal "(int " signum ", void (*" handler ")(int)) ) (int);"
+.EE
+.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.
+.PP
+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 ().
+.PP
+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.
+This is equivalent to calling
+.BR sigaction (2)
+with the following flags:
+.PP
+.EX
+ sa.sa_flags = SA_RESETHAND | SA_NODEFER;
+.EE
+.PP
+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.
+.PP
+BSD improved on this situation, but unfortunately also
+changed the semantics of the existing
+.BR signal ()
+interface while doing so.
+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.
+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:
+.PP
+.EX
+ sa.sa_flags = SA_RESTART;
+.EE
+.PP
+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 a suitable
+feature test macro is defined:
+.B _BSD_SOURCE
+on glibc 2.19 and earlier or
+.BR _DEFAULT_SOURCE
+in glibc 2.19 and later.
+(By default, these macros are defined; see
+.BR feature_test_macros (7)
+for details.)
+If such a feature test macro is not defined, then
+.BR signal ()
+provides System\ V semantics.
+.\"
+.\" 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 sigvec (2),
+.BR signalfd (2),
+.BR sigpending (2),
+.BR sigprocmask (2),
+.BR sigsuspend (2),
+.BR bsd_signal (3),
+.BR killpg (3),
.BR raise (3),
+.BR siginterrupt (3),
+.BR sigqueue (3),
.BR sigsetops (3),
+.BR sigvec (3),
+.BR sysv_signal (3),
.BR signal (7)
projects / thirdparty / man-pages.git / blobdiff