1signal-safety(7)       Miscellaneous Information 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       (a)  Ensure  that  (1)  the signal handler calls only async-signal-safe
32            functions, and (2) the signal handler itself is reentrant with re‐
33            spect to global variables in the main program.
34
35       (b)  Block  signal  delivery in the main program when calling functions
36            that are unsafe or operating on global data that is also  accessed
37            by 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
80                              notes below
81       execle(3)              See notes below
82       execv(3)               Added in POSIX.1-2008
83       execve(2)
84       _exit(2)
85       _Exit(2)
86       faccessat(2)           Added in POSIX.1-2008
87       fchdir(2)              Added in POSIX.1-2008 TC1
88       fchmod(2)
89       fchmodat(2)            Added in POSIX.1-2008
90       fchown(2)
91       fchownat(2)            Added in POSIX.1-2008
92       fcntl(2)
93       fdatasync(2)
94       fexecve(3)             Added in POSIX.1-2008
95       ffs(3)                 Added in POSIX.1-2008 TC2
96       fork(2)                See notes below
97       fstat(2)
98       fstatat(2)             Added in POSIX.1-2008
99       fsync(2)
100       ftruncate(2)
101       futimens(3)            Added in POSIX.1-2008
102       getegid(2)
103       geteuid(2)
104       getgid(2)
105       getgroups(2)
106       getpeername(2)
107       getpgrp(2)
108       getpid(2)
109       getppid(2)
110       getsockname(2)
111       getsockopt(2)
112       getuid(2)
113       htonl(3)               Added in POSIX.1-2008 TC2
114       htons(3)               Added in POSIX.1-2008 TC2
115       kill(2)
116       link(2)
117       linkat(2)              Added in POSIX.1-2008
118       listen(2)
119       longjmp(3)             Added in POSIX.1-2008 TC2;
120                              see notes below
121       lseek(2)
122       lstat(2)
123       memccpy(3)             Added in POSIX.1-2008 TC2
124       memchr(3)              Added in POSIX.1-2008 TC2
125       memcmp(3)              Added in POSIX.1-2008 TC2
126       memcpy(3)              Added in POSIX.1-2008 TC2
127       memmove(3)             Added in POSIX.1-2008 TC2
128       memset(3)              Added in POSIX.1-2008 TC2
129       mkdir(2)
130       mkdirat(2)             Added in POSIX.1-2008
131       mkfifo(3)
132
133       mkfifoat(3)            Added in POSIX.1-2008
134       mknod(2)               Added in POSIX.1-2008
135       mknodat(2)             Added in POSIX.1-2008
136       ntohl(3)               Added in POSIX.1-2008 TC2
137       ntohs(3)               Added in POSIX.1-2008 TC2
138       open(2)
139       openat(2)              Added in POSIX.1-2008
140       pause(2)
141       pipe(2)
142       poll(2)
143       posix_trace_event(3)
144       pselect(2)
145       pthread_kill(3)        Added in POSIX.1-2008 TC1
146       pthread_self(3)        Added in POSIX.1-2008 TC1
147       pthread_sigmask(3)     Added in POSIX.1-2008 TC1
148       raise(3)
149       read(2)
150       readlink(2)
151       readlinkat(2)          Added in POSIX.1-2008
152       recv(2)
153       recvfrom(2)
154       recvmsg(2)
155       rename(2)
156       renameat(2)            Added in POSIX.1-2008
157       rmdir(2)
158       select(2)
159       sem_post(3)
160       send(2)
161       sendmsg(2)
162       sendto(2)
163       setgid(2)
164       setpgid(2)
165       setsid(2)
166       setsockopt(2)
167       setuid(2)
168       shutdown(2)
169       sigaction(2)
170       sigaddset(3)
171       sigdelset(3)
172       sigemptyset(3)
173       sigfillset(3)
174       sigismember(3)
175       siglongjmp(3)          Added in POSIX.1-2008 TC2;
176                              see notes below
177       signal(2)
178       sigpause(3)
179       sigpending(2)
180       sigprocmask(2)
181       sigqueue(2)
182       sigset(3)
183       sigsuspend(2)
184       sleep(3)
185       sockatmark(3)          Added in POSIX.1-2001 TC2
186       socket(2)
187       socketpair(2)
188       stat(2)
189       stpcpy(3)              Added in POSIX.1-2008 TC2
190       stpncpy(3)             Added in POSIX.1-2008 TC2
191       strcat(3)              Added in POSIX.1-2008 TC2
192       strchr(3)              Added in POSIX.1-2008 TC2
193       strcmp(3)              Added in POSIX.1-2008 TC2
194       strcpy(3)              Added in POSIX.1-2008 TC2
195       strcspn(3)             Added in POSIX.1-2008 TC2
196       strlen(3)              Added in POSIX.1-2008 TC2
197       strncat(3)             Added in POSIX.1-2008 TC2
198
199       strncmp(3)             Added in POSIX.1-2008 TC2
200       strncpy(3)             Added in POSIX.1-2008 TC2
201       strnlen(3)             Added in POSIX.1-2008 TC2
202       strpbrk(3)             Added in POSIX.1-2008 TC2
203       strrchr(3)             Added in POSIX.1-2008 TC2
204       strspn(3)              Added in POSIX.1-2008 TC2
205       strstr(3)              Added in POSIX.1-2008 TC2
206       strtok_r(3)            Added in POSIX.1-2008 TC2
207       symlink(2)
208       symlinkat(2)           Added in POSIX.1-2008
209       tcdrain(3)
210       tcflow(3)
211       tcflush(3)
212       tcgetattr(3)
213       tcgetpgrp(3)
214       tcsendbreak(3)
215       tcsetattr(3)
216       tcsetpgrp(3)
217       time(2)
218       timer_getoverrun(2)
219       timer_gettime(2)
220       timer_settime(2)
221       times(2)
222       umask(2)
223       uname(2)
224       unlink(2)
225       unlinkat(2)            Added in POSIX.1-2008
226       utime(2)
227       utimensat(2)           Added in POSIX.1-2008
228       utimes(2)              Added in POSIX.1-2008
229       wait(2)
230       waitpid(2)
231       wcpcpy(3)              Added in POSIX.1-2008 TC2
232       wcpncpy(3)             Added in POSIX.1-2008 TC2
233       wcscat(3)              Added in POSIX.1-2008 TC2
234       wcschr(3)              Added in POSIX.1-2008 TC2
235       wcscmp(3)              Added in POSIX.1-2008 TC2
236       wcscpy(3)              Added in POSIX.1-2008 TC2
237       wcscspn(3)             Added in POSIX.1-2008 TC2
238       wcslen(3)              Added in POSIX.1-2008 TC2
239       wcsncat(3)             Added in POSIX.1-2008 TC2
240       wcsncmp(3)             Added in POSIX.1-2008 TC2
241       wcsncpy(3)             Added in POSIX.1-2008 TC2
242       wcsnlen(3)             Added in POSIX.1-2008 TC2
243       wcspbrk(3)             Added in POSIX.1-2008 TC2
244       wcsrchr(3)             Added in POSIX.1-2008 TC2
245       wcsspn(3)              Added in POSIX.1-2008 TC2
246       wcsstr(3)              Added in POSIX.1-2008 TC2
247       wcstok(3)              Added in POSIX.1-2008 TC2
248       wmemchr(3)             Added in POSIX.1-2008 TC2
249       wmemcmp(3)             Added in POSIX.1-2008 TC2
250       wmemcpy(3)             Added in POSIX.1-2008 TC2
251       wmemmove(3)            Added in POSIX.1-2008 TC2
252       wmemset(3)             Added in POSIX.1-2008 TC2
253       write(2)
254
255       Notes:
256
257       •  POSIX.1-2001  and  POSIX.1-2001  TC2  required  the functions fpath‐
258          conf(3), pathconf(3), and sysconf(3) to  be  async-signal-safe,  but
259          this requirement was removed in POSIX.1-2008.
260
261       •  If  a signal handler interrupts the execution of an unsafe function,
262          and the handler terminates via a call to longjmp(3) or siglongjmp(3)
263          and  the program subsequently calls an unsafe function, then the be‐
264          havior of the program is undefined.
265
266       •  POSIX.1-2001 TC1 clarified that if an application calls fork(2) from
267          a  signal  handler  and  any  of  the  fork  handlers  registered by
268          pthread_atfork(3) calls a function that  is  not  async-signal-safe,
269          the  behavior  is  undefined.   A future revision of the standard is
270          likely to remove fork(2) from the list  of  async-signal-safe  func‐
271          tions.
272
273       •  Asynchronous  signal handlers that call functions which are cancela‐
274          tion points and nest over regions of deferred cancelation may  trig‐
275          ger cancelation whose behavior is as if asynchronous cancelation had
276          occurred and may cause application state to become inconsistent.
277
278   errno
279       Fetching and setting the value of errno is  async-signal-safe  provided
280       that the signal handler saves errno on entry and restores its value be‐
281       fore returning.
282
283   Deviations in the GNU C library
284       The following known deviations from the standard occur in the GNU C li‐
285       brary:
286
287       •  Before glibc 2.24, execl(3) and execle(3) employed realloc(3) inter‐
288          nally and were consequently not async-signal-safe.  This  was  fixed
289          in glibc 2.24.
290
291       •  The  glibc implementation of aio_suspend(3) is not async-signal-safe
292          because it uses pthread_mutex_lock(3) internally.
293

SEE ALSO

295       sigaction(2), signal(7), standards(7)
296
297
298
299Linux man-pages 6.05              2023-02-05                  signal-safety(7)
Impressum