diff options
Diffstat (limited to 'man/man7/signal-safety.7')
| -rw-r--r-- | man/man7/signal-safety.7 | 341 |
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) |