Merging upstream version 6.8.

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

1 files changed, 341 insertions, 0 deletions

diff --git a/man/man7/signal-safety.7 b/man/man7/signal-safety.7
new file mode 100644
index 0000000..dfb3ba5
--- /dev/null
+++ b/man/man7/signal-safety.7
@@ -0,0 +1,341 @@
+'\" t
+.\" Copyright (c) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH signal-safety 7 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+signal-safety \- async-signal-safe functions
+.SH DESCRIPTION
+An
+.I async-signal-safe
+function is one that can be safely called from within a signal handler.
+Many functions are
+.I not
+async-signal-safe.
+In particular,
+nonreentrant functions are generally unsafe to call from a signal handler.
+.P
+The kinds of issues that render a function
+unsafe can be quickly understood when one considers
+the implementation of the
+.I stdio
+library, all of whose functions are not async-signal-safe.
+.P
+When performing buffered I/O on a file, the
+.I stdio
+functions must maintain a statically allocated data buffer
+along with associated counters and indexes (or pointers)
+that record the amount of data and the current position in the buffer.
+Suppose that the main program is in the middle of a call to a
+.I stdio
+function such as
+.BR printf (3)
+where the buffer and associated variables have been partially updated.
+If, at that moment,
+the program is interrupted by a signal handler that also calls
+.BR printf (3),
+then the second call to
+.BR printf (3)
+will operate on inconsistent data, with unpredictable results.
+.P
+To avoid problems with unsafe functions, there are two possible choices:
+.IP (a) 5
+Ensure that
+(1) the signal handler calls only async-signal-safe functions,
+and
+(2) the signal handler itself is reentrant
+with respect to global variables in the main program.
+.IP (b)
+Block signal delivery in the main program when calling functions
+that are unsafe or operating on global data that is also accessed
+by the signal handler.
+.P
+Generally, the second choice is difficult in programs of any complexity,
+so the first choice is taken.
+.P
+POSIX.1 specifies a set of functions that an implementation
+must make async-signal-safe.
+(An implementation may provide safe implementations of additional functions,
+but this is not required by the standard and other implementations
+may not provide the same guarantees.)
+.P
+In general, a function is async-signal-safe either because it is reentrant
+or because it is atomic with respect to signals
+(i.e., its execution can't be interrupted by a signal handler).
+.P
+The set of functions required to be async-signal-safe by POSIX.1
+is shown in the following table.
+The functions not otherwise noted were required to be async-signal-safe
+in POSIX.1-2001;
+the table details changes in the subsequent standards.
+.P
+.TS
+lb lb
+l l.
+Function	Notes
+\fBabort\fP(3)	Added in POSIX.1-2001 TC1
+\fBaccept\fP(2)
+\fBaccess\fP(2)
+\fBaio_error\fP(3)
+\fBaio_return\fP(3)
+\fBaio_suspend\fP(3)	See notes below
+\fBalarm\fP(2)
+\fBbind\fP(2)
+\fBcfgetispeed\fP(3)
+\fBcfgetospeed\fP(3)
+\fBcfsetispeed\fP(3)
+\fBcfsetospeed\fP(3)
+\fBchdir\fP(2)
+\fBchmod\fP(2)
+\fBchown\fP(2)
+\fBclock_gettime\fP(2)
+\fBclose\fP(2)
+\fBconnect\fP(2)
+\fBcreat\fP(2)
+\fBdup\fP(2)
+\fBdup2\fP(2)
+\fBexecl\fP(3)	T{
+Added in POSIX.1-2008; see notes below
+T}
+\fBexecle\fP(3)	See notes below
+\fBexecv\fP(3)	Added in POSIX.1-2008
+\fBexecve\fP(2)
+\fB_exit\fP(2)
+\fB_Exit\fP(2)
+\fBfaccessat\fP(2)	Added in POSIX.1-2008
+\fBfchdir\fP(2)	Added in POSIX.1-2008 TC1
+\fBfchmod\fP(2)
+\fBfchmodat\fP(2)	Added in POSIX.1-2008
+\fBfchown\fP(2)
+\fBfchownat\fP(2)	Added in POSIX.1-2008
+\fBfcntl\fP(2)
+\fBfdatasync\fP(2)
+\fBfexecve\fP(3)	Added in POSIX.1-2008
+\fBffs\fP(3)	Added in POSIX.1-2008 TC2
+\fBfork\fP(2)	See notes below
+\fBfstat\fP(2)
+\fBfstatat\fP(2)	Added in POSIX.1-2008
+\fBfsync\fP(2)
+\fBftruncate\fP(2)
+\fBfutimens\fP(3)	Added in POSIX.1-2008
+\fBgetegid\fP(2)
+\fBgeteuid\fP(2)
+\fBgetgid\fP(2)
+\fBgetgroups\fP(2)
+\fBgetpeername\fP(2)
+\fBgetpgrp\fP(2)
+\fBgetpid\fP(2)
+\fBgetppid\fP(2)
+\fBgetsockname\fP(2)
+\fBgetsockopt\fP(2)
+\fBgetuid\fP(2)
+\fBhtonl\fP(3)	Added in POSIX.1-2008 TC2
+\fBhtons\fP(3)	Added in POSIX.1-2008 TC2
+\fBkill\fP(2)
+\fBlink\fP(2)
+\fBlinkat\fP(2)	Added in POSIX.1-2008
+\fBlisten\fP(2)
+\fBlongjmp\fP(3)	T{
+Added in POSIX.1-2008 TC2; see notes below
+T}
+\fBlseek\fP(2)
+\fBlstat\fP(2)
+\fBmemccpy\fP(3)	Added in POSIX.1-2008 TC2
+\fBmemchr\fP(3)	Added in POSIX.1-2008 TC2
+\fBmemcmp\fP(3)	Added in POSIX.1-2008 TC2
+\fBmemcpy\fP(3)	Added in POSIX.1-2008 TC2
+\fBmemmove\fP(3)	Added in POSIX.1-2008 TC2
+\fBmemset\fP(3)	Added in POSIX.1-2008 TC2
+\fBmkdir\fP(2)
+\fBmkdirat\fP(2)	Added in POSIX.1-2008
+\fBmkfifo\fP(3)
+\fBmkfifoat\fP(3)	Added in POSIX.1-2008
+\fBmknod\fP(2)	Added in POSIX.1-2008
+\fBmknodat\fP(2)	Added in POSIX.1-2008
+\fBntohl\fP(3)	Added in POSIX.1-2008 TC2
+\fBntohs\fP(3)	Added in POSIX.1-2008 TC2
+\fBopen\fP(2)
+\fBopenat\fP(2)	Added in POSIX.1-2008
+\fBpause\fP(2)
+\fBpipe\fP(2)
+\fBpoll\fP(2)
+\fBposix_trace_event\fP(3)
+\fBpselect\fP(2)
+\fBpthread_kill\fP(3)	Added in POSIX.1-2008 TC1
+\fBpthread_self\fP(3)	Added in POSIX.1-2008 TC1
+\fBpthread_sigmask\fP(3)	Added in POSIX.1-2008 TC1
+\fBraise\fP(3)
+\fBread\fP(2)
+\fBreadlink\fP(2)
+\fBreadlinkat\fP(2)	Added in POSIX.1-2008
+\fBrecv\fP(2)
+\fBrecvfrom\fP(2)
+\fBrecvmsg\fP(2)
+\fBrename\fP(2)
+\fBrenameat\fP(2)	Added in POSIX.1-2008
+\fBrmdir\fP(2)
+\fBselect\fP(2)
+\fBsem_post\fP(3)
+\fBsend\fP(2)
+\fBsendmsg\fP(2)
+\fBsendto\fP(2)
+\fBsetgid\fP(2)
+\fBsetpgid\fP(2)
+\fBsetsid\fP(2)
+\fBsetsockopt\fP(2)
+\fBsetuid\fP(2)
+\fBshutdown\fP(2)
+\fBsigaction\fP(2)
+\fBsigaddset\fP(3)
+\fBsigdelset\fP(3)
+\fBsigemptyset\fP(3)
+\fBsigfillset\fP(3)
+\fBsigismember\fP(3)
+\fBsiglongjmp\fP(3)	T{
+Added in POSIX.1-2008 TC2; see notes below
+T}
+\fBsignal\fP(2)
+\fBsigpause\fP(3)
+\fBsigpending\fP(2)
+\fBsigprocmask\fP(2)
+\fBsigqueue\fP(2)
+\fBsigset\fP(3)
+\fBsigsuspend\fP(2)
+\fBsleep\fP(3)
+\fBsockatmark\fP(3)	Added in POSIX.1-2001 TC2
+\fBsocket\fP(2)
+\fBsocketpair\fP(2)
+\fBstat\fP(2)
+\fBstpcpy\fP(3)	Added in POSIX.1-2008 TC2
+\fBstpncpy\fP(3)	Added in POSIX.1-2008 TC2
+\fBstrcat\fP(3)	Added in POSIX.1-2008 TC2
+\fBstrchr\fP(3)	Added in POSIX.1-2008 TC2
+\fBstrcmp\fP(3)	Added in POSIX.1-2008 TC2
+\fBstrcpy\fP(3)	Added in POSIX.1-2008 TC2
+\fBstrcspn\fP(3)	Added in POSIX.1-2008 TC2
+\fBstrlen\fP(3)	Added in POSIX.1-2008 TC2
+\fBstrncat\fP(3)	Added in POSIX.1-2008 TC2
+\fBstrncmp\fP(3)	Added in POSIX.1-2008 TC2
+\fBstrncpy\fP(3)	Added in POSIX.1-2008 TC2
+\fBstrnlen\fP(3)	Added in POSIX.1-2008 TC2
+\fBstrpbrk\fP(3)	Added in POSIX.1-2008 TC2
+\fBstrrchr\fP(3)	Added in POSIX.1-2008 TC2
+\fBstrspn\fP(3)	Added in POSIX.1-2008 TC2
+\fBstrstr\fP(3)	Added in POSIX.1-2008 TC2
+\fBstrtok_r\fP(3)	Added in POSIX.1-2008 TC2
+\fBsymlink\fP(2)
+\fBsymlinkat\fP(2)	Added in POSIX.1-2008
+\fBtcdrain\fP(3)
+\fBtcflow\fP(3)
+\fBtcflush\fP(3)
+\fBtcgetattr\fP(3)
+\fBtcgetpgrp\fP(3)
+\fBtcsendbreak\fP(3)
+\fBtcsetattr\fP(3)
+\fBtcsetpgrp\fP(3)
+\fBtime\fP(2)
+\fBtimer_getoverrun\fP(2)
+\fBtimer_gettime\fP(2)
+\fBtimer_settime\fP(2)
+\fBtimes\fP(2)
+\fBumask\fP(2)
+\fBuname\fP(2)
+\fBunlink\fP(2)
+\fBunlinkat\fP(2)	Added in POSIX.1-2008
+\fButime\fP(2)
+\fButimensat\fP(2)	Added in POSIX.1-2008
+\fButimes\fP(2)	Added in POSIX.1-2008
+\fBwait\fP(2)
+\fBwaitpid\fP(2)
+\fBwcpcpy\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcpncpy\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcscat\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcschr\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcscmp\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcscpy\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcscspn\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcslen\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcsncat\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcsncmp\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcsncpy\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcsnlen\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcspbrk\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcsrchr\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcsspn\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcsstr\fP(3)	Added in POSIX.1-2008 TC2
+\fBwcstok\fP(3)	Added in POSIX.1-2008 TC2
+\fBwmemchr\fP(3)	Added in POSIX.1-2008 TC2
+\fBwmemcmp\fP(3)	Added in POSIX.1-2008 TC2
+\fBwmemcpy\fP(3)	Added in POSIX.1-2008 TC2
+\fBwmemmove\fP(3)	Added in POSIX.1-2008 TC2
+\fBwmemset\fP(3)	Added in POSIX.1-2008 TC2
+\fBwrite\fP(2)
+.TE
+.P
+Notes:
+.IP \[bu] 3
+POSIX.1-2001 and POSIX.1-2001 TC2 required the functions
+.BR fpathconf (3),
+.BR pathconf (3),
+and
+.BR sysconf (3)
+to be async-signal-safe, but this requirement was removed in POSIX.1-2008.
+.IP \[bu]
+If a signal handler interrupts the execution of an unsafe function,
+and the handler terminates via a call to
+.BR longjmp (3)
+or
+.BR siglongjmp (3)
+and the program subsequently calls an unsafe function,
+then the behavior of the program is undefined.
+.IP \[bu]
+POSIX.1-2001 TC1 clarified
+that if an application calls
+.BR fork (2)
+from a signal handler and any of the fork handlers registered by
+.BR pthread_atfork (3)
+calls a function that is not async-signal-safe, the behavior is undefined.
+A future revision of the standard
+.\" http://www.opengroup.org/austin/aardvark/latest/xshbug3.txt
+is likely to remove
+.BR fork (2)
+from the list of async-signal-safe functions.
+.\"
+.IP \[bu]
+Asynchronous signal handlers that call functions which are cancelation
+points and nest over regions of deferred cancelation may trigger
+cancelation whose behavior is as if asynchronous cancelation had
+occurred and may cause application state to become inconsistent.
+.\"
+.SS errno
+Fetching and setting the value of
+.I errno
+is async-signal-safe provided that the signal handler saves
+.I errno
+on entry and restores its value before returning.
+.\"
+.SS Deviations in the GNU C library
+The following known deviations from the standard occur in
+the GNU C library:
+.IP \[bu] 3
+Before glibc 2.24,
+.BR execl (3)
+and
+.BR execle (3)
+employed
+.BR realloc (3)
+internally and were consequently not async-signal-safe.
+.\" https://sourceware.org/bugzilla/show_bug.cgi?id=19534
+This was fixed in glibc 2.24.
+.IP \[bu]
+.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=13172
+The glibc implementation of
+.BR aio_suspend (3)
+is not async-signal-safe because it uses
+.BR pthread_mutex_lock (3)
+internally.
+.SH SEE ALSO
+.BR sigaction (2),
+.BR signal (7),
+.BR standards (7)