1SIGNAL-SAFETY(7) Linux Programmer's Manual SIGNAL-SAFETY(7)
2
6 signal-safety - async-signal-safe functions
7
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 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 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 To avoid problems with unsafe functions, there are two possible
29 choices:
30 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 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 Generally, the second choice is difficult in programs of any complex‐
40 ity, so the first choice is taken.
41 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 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 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 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 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 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 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 Notes:
253 * 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 * 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 * 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 * 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 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 Deviations in the GNU C library
281 The following known deviations from the standard occur in the GNU C li‐
282 brary:
283 * 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 * The glibc implementation of aio_suspend(3) is not async-signal-safe
289 because it uses pthread_mutex_lock(3) internally.
290
292 sigaction(2), signal(7), standards(7)
293
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/.
299Linux 2020-12-21 SIGNAL-SAFETY(7)