From 3d08cd331c1adcf0d917392f7e527b3f00511748 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 24 May 2024 06:52:22 +0200 Subject: Merging upstream version 6.8. Signed-off-by: Daniel Baumann --- man/man2/signal.2 | 280 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 280 insertions(+) create mode 100644 man/man2/signal.2 (limited to 'man/man2/signal.2') diff --git a/man/man2/signal.2 b/man/man2/signal.2 new file mode 100644 index 0000000..102caaa --- /dev/null +++ b/man/man2/signal.2 @@ -0,0 +1,280 @@ +.\" Copyright (c) 2000 Andries Brouwer +.\" and Copyright (c) 2007 Michael Kerrisk +.\" and Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" based on work by Rik Faith +.\" and Mike Battersby . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 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 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +signal \- ANSI C signal handling +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B typedef void (*sighandler_t)(int); +.P +.BI "sighandler_t signal(int " signum ", sighandler_t " handler ); +.fi +.SH DESCRIPTION +.BR WARNING : +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. +.P +.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"). +.P +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. +.P +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. +On failure, it returns +.BR SIG_ERR , +and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I signum +is invalid. +.SH VERSIONS +The use of +.I sighandler_t +is a GNU extension, exposed if +.B _GNU_SOURCE +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 +.B _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: +.P +.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 +.B 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. +.P +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 (). +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.P +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: +.P +.in +4n +.EX +sa.sa_flags = SA_RESETHAND | SA_NODEFER; +.EE +.in +.P +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. +.P +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: +.P +.in +4n +.EX +sa.sa_flags = SA_RESTART; +.EE +.in +.P +The situation on Linux is as follows: +.IP \[bu] 3 +The kernel's +.BR signal () +system call provides System\ V semantics. +.IP \[bu] +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 +.B _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 \[bu] +.\" The +.\" .BR signal () +.\" function in Linux libc4 and libc5 provide System\ V semantics. +.\" If one on a libc5 system includes +.\" .I +.\" instead of +.\" .IR , +.\" then +.\" .BR signal () +.\" provides BSD semantics. +.SH NOTES +The effects of +.BR signal () +in a multithreaded process are unspecified. +.P +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. +.P +See +.BR sigaction (2) +for details on what happens when the disposition +.B SIGCHLD +is set to +.BR SIG_IGN . +.P +See +.BR signal\-safety (7) +for a list of the async-signal-safe functions that can be +safely called from inside a signal handler. +.SH SEE ALSO +.BR kill (1), +.BR alarm (2), +.BR kill (2), +.BR pause (2), +.BR sigaction (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) -- cgit v1.2.3