Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 280 insertions, 0 deletions

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 <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>.
+.\"
+.\" 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 <signal.h>
+.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 <bsd/signal.h>
+.\" instead of
+.\" .IR <signal.h> ,
+.\" 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)