Debian Codegraph @

upstream/debian-unstable/man7/signal-safety.7

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