mirror of https://github.com/mkerrisk/man-pages
361 lines
11 KiB
Groff
361 lines
11 KiB
Groff
.\" Copyright (c) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.TH SIGNAL-SAFETY 7 2021-03-22 "Linux" "Linux Programmer's Manual"
|
|
.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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
To avoid problems with unsafe functions, there are two possible choices:
|
|
.IP 1. 3
|
|
Ensure that
|
|
(a) the signal handler calls only async-signal-safe functions,
|
|
and
|
|
(b) the signal handler itself is reentrant
|
|
with respect to global variables in the main program.
|
|
.IP 2.
|
|
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.
|
|
.PP
|
|
Generally, the second choice is difficult in programs of any complexity,
|
|
so the first choice is taken.
|
|
.PP
|
|
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.)
|
|
.PP
|
|
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).
|
|
.PP
|
|
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.
|
|
.PP
|
|
.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
|
|
.PP
|
|
Notes:
|
|
.IP * 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 *
|
|
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 *
|
|
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 * 3
|
|
Asynchronous signal handlers that call functions which are cancellation
|
|
points and nest over regions of deferred cancellation may trigger
|
|
cancellation whose behavior is as if asynchronous cancellation 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 * 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 *
|
|
.\" 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)
|