summaryrefslogtreecommitdiffstats
path: root/man7/signal-safety.7
diff options
context:
space:
mode:
Diffstat (limited to 'man7/signal-safety.7')
-rw-r--r--man7/signal-safety.7341
1 files changed, 0 insertions, 341 deletions
diff --git a/man7/signal-safety.7 b/man7/signal-safety.7
deleted file mode 100644
index d307dda..0000000
--- a/man7/signal-safety.7
+++ /dev/null
@@ -1,341 +0,0 @@
-'\" t
-.\" Copyright (c) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
-.\"
-.\" SPDX-License-Identifier: Linux-man-pages-copyleft
-.\"
-.TH signal-safety 7 2023-10-31 "Linux man-pages 6.7"
-.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)