1SIGNAL-SAFETY(7)           Linux Programmer's Manual          SIGNAL-SAFETY(7)
2
3
4

NAME

6       signal-safety - async-signal-safe functions
7

DESCRIPTION

9       An  async-signal-safe  function  is  one that can be safely called from
10       within a signal handler.  Many functions are not async-signal-safe.  In
11       particular,  nonreentrant functions are generally unsafe to call from a
12       signal handler.
13
14       The kinds of issues that render a function unsafe can be quickly under‐
15       stood  when  one considers the implementation of the stdio library, all
16       of whose functions are not async-signal-safe.
17
18       When performing buffered I/O on a file, the stdio functions must  main‐
19       tain  a statically allocated data buffer along with associated counters
20       and indexes (or pointers) that record the amount of data and  the  cur‐
21       rent  position  in the buffer.  Suppose that the main program is in the
22       middle of a call to a stdio function such as printf(3) where the buffer
23       and  associated variables have been partially updated.  If, at that mo‐
24       ment, the program is interrupted by a signal handler  that  also  calls
25       printf(3),  then the second call to printf(3) will operate on inconsis‐
26       tent data, with unpredictable results.
27
28       To avoid  problems  with  unsafe  functions,  there  are  two  possible
29       choices:
30
31       1. Ensure  that  (a)  the  signal  handler calls only async-signal-safe
32          functions, and (b) the signal handler itself is reentrant  with  re‐
33          spect to global variables in the main program.
34
35       2. Block  signal  delivery  in  the main program when calling functions
36          that are unsafe or operating on global data that is also accessed by
37          the signal handler.
38
39       Generally,  the  second choice is difficult in programs of any complex‐
40       ity, so the first choice is taken.
41
42       POSIX.1 specifies a set of functions that an implementation  must  make
43       async-signal-safe.  (An implementation may provide safe implementations
44       of additional functions, but this is not required by the  standard  and
45       other implementations may not provide the same guarantees.)
46
47       In  general, a function is async-signal-safe either because it is reen‐
48       trant or because it is atomic with respect to signals (i.e., its execu‐
49       tion can't be interrupted by a signal handler).
50
51       The  set  of  functions  required to be async-signal-safe by POSIX.1 is
52       shown in the following table.  The functions not otherwise  noted  were
53       required  to  be  async-signal-safe  in POSIX.1-2001; the table details
54       changes in the subsequent standards.
55
56       Function               Notes
57       abort(3)               Added in POSIX.1-2001 TC1
58       accept(2)
59       access(2)
60       aio_error(3)
61       aio_return(3)
62       aio_suspend(3)         See notes below
63       alarm(2)
64       bind(2)
65       cfgetispeed(3)
66
67       cfgetospeed(3)
68       cfsetispeed(3)
69       cfsetospeed(3)
70       chdir(2)
71       chmod(2)
72       chown(2)
73       clock_gettime(2)
74       close(2)
75       connect(2)
76       creat(2)
77       dup(2)
78       dup2(2)
79       execl(3)               Added in POSIX.1-2008; see notes below
80       execle(3)              See notes below
81       execv(3)               Added in POSIX.1-2008
82       execve(2)
83       _exit(2)
84       _Exit(2)
85       faccessat(2)           Added in POSIX.1-2008
86       fchdir(2)              Added in POSIX.1-2008 TC1
87       fchmod(2)
88       fchmodat(2)            Added in POSIX.1-2008
89       fchown(2)
90       fchownat(2)            Added in POSIX.1-2008
91       fcntl(2)
92       fdatasync(2)
93       fexecve(3)             Added in POSIX.1-2008
94       ffs(3)                 Added in POSIX.1-2008 TC2
95       fork(2)                See notes below
96       fstat(2)
97       fstatat(2)             Added in POSIX.1-2008
98       fsync(2)
99       ftruncate(2)
100       futimens(3)            Added in POSIX.1-2008
101       getegid(2)
102       geteuid(2)
103       getgid(2)
104       getgroups(2)
105       getpeername(2)
106       getpgrp(2)
107       getpid(2)
108       getppid(2)
109       getsockname(2)
110       getsockopt(2)
111       getuid(2)
112       htonl(3)               Added in POSIX.1-2008 TC2
113       htons(3)               Added in POSIX.1-2008 TC2
114       kill(2)
115       link(2)
116       linkat(2)              Added in POSIX.1-2008
117       listen(2)
118       longjmp(3)             Added in POSIX.1-2008 TC2; see notes below
119       lseek(2)
120       lstat(2)
121       memccpy(3)             Added in POSIX.1-2008 TC2
122       memchr(3)              Added in POSIX.1-2008 TC2
123       memcmp(3)              Added in POSIX.1-2008 TC2
124       memcpy(3)              Added in POSIX.1-2008 TC2
125       memmove(3)             Added in POSIX.1-2008 TC2
126       memset(3)              Added in POSIX.1-2008 TC2
127       mkdir(2)
128       mkdirat(2)             Added in POSIX.1-2008
129       mkfifo(3)
130       mkfifoat(3)            Added in POSIX.1-2008
131       mknod(2)               Added in POSIX.1-2008
132
133       mknodat(2)             Added in POSIX.1-2008
134       ntohl(3)               Added in POSIX.1-2008 TC2
135       ntohs(3)               Added in POSIX.1-2008 TC2
136       open(2)
137       openat(2)              Added in POSIX.1-2008
138       pause(2)
139       pipe(2)
140       poll(2)
141       posix_trace_event(3)
142       pselect(2)
143       pthread_kill(3)        Added in POSIX.1-2008 TC1
144       pthread_self(3)        Added in POSIX.1-2008 TC1
145       pthread_sigmask(3)     Added in POSIX.1-2008 TC1
146       raise(3)
147       read(2)
148       readlink(2)
149       readlinkat(2)          Added in POSIX.1-2008
150       recv(2)
151       recvfrom(2)
152       recvmsg(2)
153       rename(2)
154       renameat(2)            Added in POSIX.1-2008
155       rmdir(2)
156       select(2)
157       sem_post(3)
158       send(2)
159       sendmsg(2)
160       sendto(2)
161       setgid(2)
162       setpgid(2)
163       setsid(2)
164       setsockopt(2)
165       setuid(2)
166       shutdown(2)
167       sigaction(2)
168       sigaddset(3)
169       sigdelset(3)
170       sigemptyset(3)
171       sigfillset(3)
172       sigismember(3)
173       siglongjmp(3)          Added in POSIX.1-2008 TC2; see notes below
174       signal(2)
175       sigpause(3)
176       sigpending(2)
177       sigprocmask(2)
178       sigqueue(2)
179       sigset(3)
180       sigsuspend(2)
181       sleep(3)
182       sockatmark(3)          Added in POSIX.1-2001 TC2
183       socket(2)
184       socketpair(2)
185       stat(2)
186       stpcpy(3)              Added in POSIX.1-2008 TC2
187       stpncpy(3)             Added in POSIX.1-2008 TC2
188       strcat(3)              Added in POSIX.1-2008 TC2
189       strchr(3)              Added in POSIX.1-2008 TC2
190       strcmp(3)              Added in POSIX.1-2008 TC2
191       strcpy(3)              Added in POSIX.1-2008 TC2
192       strcspn(3)             Added in POSIX.1-2008 TC2
193       strlen(3)              Added in POSIX.1-2008 TC2
194       strncat(3)             Added in POSIX.1-2008 TC2
195       strncmp(3)             Added in POSIX.1-2008 TC2
196       strncpy(3)             Added in POSIX.1-2008 TC2
197       strnlen(3)             Added in POSIX.1-2008 TC2
198
199       strpbrk(3)             Added in POSIX.1-2008 TC2
200       strrchr(3)             Added in POSIX.1-2008 TC2
201       strspn(3)              Added in POSIX.1-2008 TC2
202       strstr(3)              Added in POSIX.1-2008 TC2
203       strtok_r(3)            Added in POSIX.1-2008 TC2
204       symlink(2)
205       symlinkat(2)           Added in POSIX.1-2008
206       tcdrain(3)
207       tcflow(3)
208       tcflush(3)
209       tcgetattr(3)
210       tcgetpgrp(3)
211       tcsendbreak(3)
212       tcsetattr(3)
213       tcsetpgrp(3)
214       time(2)
215       timer_getoverrun(2)
216       timer_gettime(2)
217       timer_settime(2)
218       times(2)
219       umask(2)
220       uname(2)
221       unlink(2)
222       unlinkat(2)            Added in POSIX.1-2008
223       utime(2)
224       utimensat(2)           Added in POSIX.1-2008
225       utimes(2)              Added in POSIX.1-2008
226       wait(2)
227       waitpid(2)
228       wcpcpy(3)              Added in POSIX.1-2008 TC2
229       wcpncpy(3)             Added in POSIX.1-2008 TC2
230       wcscat(3)              Added in POSIX.1-2008 TC2
231       wcschr(3)              Added in POSIX.1-2008 TC2
232       wcscmp(3)              Added in POSIX.1-2008 TC2
233       wcscpy(3)              Added in POSIX.1-2008 TC2
234       wcscspn(3)             Added in POSIX.1-2008 TC2
235       wcslen(3)              Added in POSIX.1-2008 TC2
236       wcsncat(3)             Added in POSIX.1-2008 TC2
237       wcsncmp(3)             Added in POSIX.1-2008 TC2
238       wcsncpy(3)             Added in POSIX.1-2008 TC2
239       wcsnlen(3)             Added in POSIX.1-2008 TC2
240       wcspbrk(3)             Added in POSIX.1-2008 TC2
241       wcsrchr(3)             Added in POSIX.1-2008 TC2
242       wcsspn(3)              Added in POSIX.1-2008 TC2
243       wcsstr(3)              Added in POSIX.1-2008 TC2
244       wcstok(3)              Added in POSIX.1-2008 TC2
245       wmemchr(3)             Added in POSIX.1-2008 TC2
246       wmemcmp(3)             Added in POSIX.1-2008 TC2
247       wmemcpy(3)             Added in POSIX.1-2008 TC2
248       wmemmove(3)            Added in POSIX.1-2008 TC2
249       wmemset(3)             Added in POSIX.1-2008 TC2
250       write(2)
251
252       Notes:
253
254       *  POSIX.1-2001 and POSIX.1-2001  TC2  required  the  functions  fpath‐
255          conf(3),  pathconf(3),  and  sysconf(3) to be async-signal-safe, but
256          this requirement was removed in POSIX.1-2008.
257
258       *  If a signal handler interrupts the execution of an unsafe  function,
259          and the handler terminates via a call to longjmp(3) or siglongjmp(3)
260          and the program subsequently calls an unsafe function, then the  be‐
261          havior of the program is undefined.
262
263       *  POSIX.1-2001 TC1 clarified that if an application calls fork(2) from
264          a signal  handler  and  any  of  the  fork  handlers  registered  by
265          pthread_atfork(3)  calls  a  function that is not async-signal-safe,
266          the behavior is undefined.  A future revision  of  the  standard  is
267          likely  to  remove  fork(2) from the list of async-signal-safe func‐
268          tions.
269
270       *  Asynchronous signal handlers that call functions which are cancella‐
271          tion points and nest over regions of deferred cancellation may trig‐
272          ger cancellation whose behavior is as if  asynchronous  cancellation
273          had occurred and may cause application state to become inconsistent.
274
275   errno
276       Fetching  and  setting the value of errno is async-signal-safe provided
277       that the signal handler saves errno on entry and restores its value be‐
278       fore returning.
279
280   Deviations in the GNU C library
281       The following known deviations from the standard occur in the GNU C li‐
282       brary:
283
284       *  Before glibc 2.24, execl(3) and execle(3) employed realloc(3) inter‐
285          nally  and  were consequently not async-signal-safe.  This was fixed
286          in glibc 2.24.
287
288       *  The glibc implementation of aio_suspend(3) is not  async-signal-safe
289          because it uses pthread_mutex_lock(3) internally.
290

SEE ALSO

292       sigaction(2), signal(7), standards(7)
293

COLOPHON

295       This  page  is  part of release 5.10 of the Linux man-pages project.  A
296       description of the project, information about reporting bugs,  and  the
297       latest     version     of     this    page,    can    be    found    at
298       https://www.kernel.org/doc/man-pages/.
299
300
301
302Linux                             2020-12-21                  SIGNAL-SAFETY(7)
Impressum