diff options
Diffstat (limited to 'man7/signal-safety.7')
| -rw-r--r-- | man7/signal-safety.7 | 341 |
1 files changed, 0 insertions, 341 deletions
diff --git a/man7/signal-safety.7 b/man7/signal-safety.7 deleted file mode 100644 index cde19a575..000000000 --- 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 (date) "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) |