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
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 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 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 Notes:
256 * 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 * 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 * 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 * Asynchronous signal handlers that call functions which are cancella‐
274 tion points and nest over regions of deferred cancellation may trig‐
275 ger cancellation whose behavior is as if asynchronous cancellation
276 had occurred and may cause application state to become inconsistent.
277 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 Deviations in the GNU C library
284 The following known deviations from the standard occur in the GNU C li‐
285 brary:
286 * 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 * The glibc implementation of aio_suspend(3) is not async-signal-safe
292 because it uses pthread_mutex_lock(3) internally.
293
295 sigaction(2), signal(7), standards(7)
296
298 This page is part of release 5.13 of the Linux man-pages project. A
299 description of the project, information about reporting bugs, and the
300 latest version of this page, can be found at
301 https://www.kernel.org/doc/man-pages/.
302Linux 2021-03-22 SIGNAL-SAFETY(7)