Debian Codegraph @

upstream/fedora-44/man7/signal-safety.7

raw
1 '\" t
2 .\" Copyright (c) 2016 Michael Kerrisk <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH signal-safety 7 2024-08-31 "Linux man-pages 6.13"
7 .SH NAME
8 signal-safety \- async-signal-safe functions
9 .SH DESCRIPTION
10 An
11 .I async-signal-safe
12 function is one that can be safely called from within a signal handler.
13 Many functions are
14 .I not
15 async-signal-safe.
16 In particular,
17 nonreentrant functions are generally unsafe to call from a signal handler.
18 .P
19 The kinds of issues that render a function
20 unsafe can be quickly understood when one considers
21 the implementation of the
22 .I stdio
23 library, all of whose functions are not async-signal-safe.
24 .P
25 When performing buffered I/O on a file, the
26 .I stdio
27 functions must maintain a statically allocated data buffer
28 along with associated counters and indexes (or pointers)
29 that record the amount of data and the current position in the buffer.
30 Suppose that the main program is in the middle of a call to a
31 .I stdio
32 function such as
33 .BR printf (3)
34 where the buffer and associated variables have been partially updated.
35 If, at that moment,
36 the program is interrupted by a signal handler that also calls
37 .BR printf (3),
38 then the second call to
39 .BR printf (3)
40 will operate on inconsistent data, with unpredictable results.
41 .P
42 To avoid problems with unsafe functions, there are two possible choices:
43 .IP (a) 5
44 Ensure that
45 (1) the signal handler calls only async-signal-safe functions,
46 and
47 (2) the signal handler itself is reentrant
48 with respect to global variables in the main program.
49 .IP (b)
50 Block signal delivery in the main program when calling functions
51 that are unsafe or operating on global data that is also accessed
52 by the signal handler.
53 .P
54 Generally, the second choice is difficult in programs of any complexity,
55 so the first choice is taken.
56 .P
57 POSIX.1 specifies a set of functions that an implementation
58 must make async-signal-safe.
59 (An implementation may provide safe implementations of additional functions,
60 but this is not required by the standard and other implementations
61 may not provide the same guarantees.)
62 .P
63 In general, a function is async-signal-safe either because it is reentrant
64 or because it is atomic with respect to signals
65 (i.e., its execution can't be interrupted by a signal handler).
66 .P
67 The set of functions required to be async-signal-safe by POSIX.1
68 is shown in the following table.
69 The functions not otherwise noted were required to be async-signal-safe
70 in POSIX.1-2001;
71 the table details changes in the subsequent standards.
72 .P
73 .TS
74 lb lb
75 lw(24n) l.
76 Function Notes
77 \fBabort\fP(3) Added in POSIX.1-2001 TC1
78 \fBaccept\fP(2)
79 \fBaccess\fP(2)
80 \fBaio_error\fP(3)
81 \fBaio_return\fP(3)
82 \fBaio_suspend\fP(3) See notes below
83 \fBalarm\fP(2)
84 \fBbind\fP(2)
85 \fBcfgetispeed\fP(3)
86 \fBcfgetospeed\fP(3)
87 \fBcfsetispeed\fP(3)
88 \fBcfsetospeed\fP(3)
89 \fBchdir\fP(2)
90 \fBchmod\fP(2)
91 \fBchown\fP(2)
92 \fBclock_gettime\fP(2)
93 \fBclose\fP(2)
94 \fBconnect\fP(2)
95 \fBcreat\fP(2)
96 \fBdup\fP(2)
97 \fBdup2\fP(2)
98 T{
99 .BR execl (3)
100 T} T{
101 Added in POSIX.1-2008; see notes below
102 T}
103 \fBexecle\fP(3) See notes below
104 \fBexecv\fP(3) Added in POSIX.1-2008
105 \fBexecve\fP(2)
106 \fB_exit\fP(2)
107 \fB_Exit\fP(2)
108 \fBfaccessat\fP(2) Added in POSIX.1-2008
109 \fBfchdir\fP(2) Added in POSIX.1-2008 TC1
110 \fBfchmod\fP(2)
111 \fBfchmodat\fP(2) Added in POSIX.1-2008
112 \fBfchown\fP(2)
113 \fBfchownat\fP(2) Added in POSIX.1-2008
114 \fBfcntl\fP(2)
115 \fBfdatasync\fP(2)
116 \fBfexecve\fP(3) Added in POSIX.1-2008
117 \fBffs\fP(3) Added in POSIX.1-2008 TC2
118 \fBfork\fP(2) See notes below
119 \fBfstat\fP(2)
120 \fBfstatat\fP(2) Added in POSIX.1-2008
121 \fBfsync\fP(2)
122 \fBftruncate\fP(2)
123 \fBfutimens\fP(3) Added in POSIX.1-2008
124 \fBgetegid\fP(2)
125 \fBgeteuid\fP(2)
126 \fBgetgid\fP(2)
127 \fBgetgroups\fP(2)
128 \fBgetpeername\fP(2)
129 \fBgetpgrp\fP(2)
130 \fBgetpid\fP(2)
131 \fBgetppid\fP(2)
132 \fBgetsockname\fP(2)
133 \fBgetsockopt\fP(2)
134 \fBgetuid\fP(2)
135 \fBhtonl\fP(3) Added in POSIX.1-2008 TC2
136 \fBhtons\fP(3) Added in POSIX.1-2008 TC2
137 \fBkill\fP(2)
138 \fBlink\fP(2)
139 \fBlinkat\fP(2) Added in POSIX.1-2008
140 \fBlisten\fP(2)
141 T{
142 .BR longjmp (3)
143 T} T{
144 Added in POSIX.1-2008 TC2; see notes below
145 T}
146 \fBlseek\fP(2)
147 \fBlstat\fP(2)
148 \fBmemccpy\fP(3) Added in POSIX.1-2008 TC2
149 \fBmemchr\fP(3) Added in POSIX.1-2008 TC2
150 \fBmemcmp\fP(3) Added in POSIX.1-2008 TC2
151 \fBmemcpy\fP(3) Added in POSIX.1-2008 TC2
152 \fBmemmove\fP(3) Added in POSIX.1-2008 TC2
153 \fBmemset\fP(3) Added in POSIX.1-2008 TC2
154 \fBmkdir\fP(2)
155 \fBmkdirat\fP(2) Added in POSIX.1-2008
156 \fBmkfifo\fP(3)
157 \fBmkfifoat\fP(3) Added in POSIX.1-2008
158 \fBmknod\fP(2) Added in POSIX.1-2008
159 \fBmknodat\fP(2) Added in POSIX.1-2008
160 \fBntohl\fP(3) Added in POSIX.1-2008 TC2
161 \fBntohs\fP(3) Added in POSIX.1-2008 TC2
162 \fBopen\fP(2)
163 \fBopenat\fP(2) Added in POSIX.1-2008
164 \fBpause\fP(2)
165 \fBpipe\fP(2)
166 \fBpoll\fP(2)
167 \fBposix_trace_event\fP(3)
168 \fBpselect\fP(2)
169 \fBpthread_kill\fP(3) Added in POSIX.1-2008 TC1
170 \fBpthread_self\fP(3) Added in POSIX.1-2008 TC1
171 \fBpthread_sigmask\fP(3) Added in POSIX.1-2008 TC1
172 \fBraise\fP(3)
173 \fBread\fP(2)
174 \fBreadlink\fP(2)
175 \fBreadlinkat\fP(2) Added in POSIX.1-2008
176 \fBrecv\fP(2)
177 \fBrecvfrom\fP(2)
178 \fBrecvmsg\fP(2)
179 \fBrename\fP(2)
180 \fBrenameat\fP(2) Added in POSIX.1-2008
181 \fBrmdir\fP(2)
182 \fBselect\fP(2)
183 \fBsem_post\fP(3)
184 \fBsend\fP(2)
185 \fBsendmsg\fP(2)
186 \fBsendto\fP(2)
187 \fBsetgid\fP(2)
188 \fBsetpgid\fP(2)
189 \fBsetsid\fP(2)
190 \fBsetsockopt\fP(2)
191 \fBsetuid\fP(2)
192 \fBshutdown\fP(2)
193 \fBsigaction\fP(2)
194 \fBsigaddset\fP(3)
195 \fBsigdelset\fP(3)
196 \fBsigemptyset\fP(3)
197 \fBsigfillset\fP(3)
198 \fBsigismember\fP(3)
199 T{
200 .BR siglongjmp (3)
201 T} T{
202 Added in POSIX.1-2008 TC2; see notes below
203 T}
204 \fBsignal\fP(2)
205 \fBsigpause\fP(3)
206 \fBsigpending\fP(2)
207 \fBsigprocmask\fP(2)
208 \fBsigqueue\fP(2)
209 \fBsigset\fP(3)
210 \fBsigsuspend\fP(2)
211 \fBsleep\fP(3)
212 \fBsockatmark\fP(3) Added in POSIX.1-2001 TC2
213 \fBsocket\fP(2)
214 \fBsocketpair\fP(2)
215 \fBstat\fP(2)
216 \fBstpcpy\fP(3) Added in POSIX.1-2008 TC2
217 \fBstpncpy\fP(3) Added in POSIX.1-2008 TC2
218 \fBstrcat\fP(3) Added in POSIX.1-2008 TC2
219 \fBstrchr\fP(3) Added in POSIX.1-2008 TC2
220 \fBstrcmp\fP(3) Added in POSIX.1-2008 TC2
221 \fBstrcpy\fP(3) Added in POSIX.1-2008 TC2
222 \fBstrcspn\fP(3) Added in POSIX.1-2008 TC2
223 \fBstrlen\fP(3) Added in POSIX.1-2008 TC2
224 \fBstrncat\fP(3) Added in POSIX.1-2008 TC2
225 \fBstrncmp\fP(3) Added in POSIX.1-2008 TC2
226 \fBstrncpy\fP(3) Added in POSIX.1-2008 TC2
227 \fBstrnlen\fP(3) Added in POSIX.1-2008 TC2
228 \fBstrpbrk\fP(3) Added in POSIX.1-2008 TC2
229 \fBstrrchr\fP(3) Added in POSIX.1-2008 TC2
230 \fBstrspn\fP(3) Added in POSIX.1-2008 TC2
231 \fBstrstr\fP(3) Added in POSIX.1-2008 TC2
232 \fBstrtok_r\fP(3) Added in POSIX.1-2008 TC2
233 \fBsymlink\fP(2)
234 \fBsymlinkat\fP(2) Added in POSIX.1-2008
235 \fBtcdrain\fP(3)
236 \fBtcflow\fP(3)
237 \fBtcflush\fP(3)
238 \fBtcgetattr\fP(3)
239 \fBtcgetpgrp\fP(3)
240 \fBtcsendbreak\fP(3)
241 \fBtcsetattr\fP(3)
242 \fBtcsetpgrp\fP(3)
243 \fBtime\fP(2)
244 \fBtimer_getoverrun\fP(2)
245 \fBtimer_gettime\fP(2)
246 \fBtimer_settime\fP(2)
247 \fBtimes\fP(2)
248 \fBumask\fP(2)
249 \fBuname\fP(2)
250 \fBunlink\fP(2)
251 \fBunlinkat\fP(2) Added in POSIX.1-2008
252 \fButime\fP(2)
253 \fButimensat\fP(2) Added in POSIX.1-2008
254 \fButimes\fP(2) Added in POSIX.1-2008
255 \fBwait\fP(2)
256 \fBwaitpid\fP(2)
257 \fBwcpcpy\fP(3) Added in POSIX.1-2008 TC2
258 \fBwcpncpy\fP(3) Added in POSIX.1-2008 TC2
259 \fBwcscat\fP(3) Added in POSIX.1-2008 TC2
260 \fBwcschr\fP(3) Added in POSIX.1-2008 TC2
261 \fBwcscmp\fP(3) Added in POSIX.1-2008 TC2
262 \fBwcscpy\fP(3) Added in POSIX.1-2008 TC2
263 \fBwcscspn\fP(3) Added in POSIX.1-2008 TC2
264 \fBwcslen\fP(3) Added in POSIX.1-2008 TC2
265 \fBwcsncat\fP(3) Added in POSIX.1-2008 TC2
266 \fBwcsncmp\fP(3) Added in POSIX.1-2008 TC2
267 \fBwcsncpy\fP(3) Added in POSIX.1-2008 TC2
268 \fBwcsnlen\fP(3) Added in POSIX.1-2008 TC2
269 \fBwcspbrk\fP(3) Added in POSIX.1-2008 TC2
270 \fBwcsrchr\fP(3) Added in POSIX.1-2008 TC2
271 \fBwcsspn\fP(3) Added in POSIX.1-2008 TC2
272 \fBwcsstr\fP(3) Added in POSIX.1-2008 TC2
273 \fBwcstok\fP(3) Added in POSIX.1-2008 TC2
274 \fBwmemchr\fP(3) Added in POSIX.1-2008 TC2
275 \fBwmemcmp\fP(3) Added in POSIX.1-2008 TC2
276 \fBwmemcpy\fP(3) Added in POSIX.1-2008 TC2
277 \fBwmemmove\fP(3) Added in POSIX.1-2008 TC2
278 \fBwmemset\fP(3) Added in POSIX.1-2008 TC2
279 \fBwrite\fP(2)
280 .TE
281 .P
282 Notes:
283 .IP \[bu] 3
284 POSIX.1-2001 and POSIX.1-2001 TC2 required the functions
285 .BR fpathconf (3),
286 .BR pathconf (3),
287 and
288 .BR sysconf (3)
289 to be async-signal-safe, but this requirement was removed in POSIX.1-2008.
290 .IP \[bu]
291 If a signal handler interrupts the execution of an unsafe function,
292 and the handler terminates via a call to
293 .BR longjmp (3)
294 or
295 .BR siglongjmp (3)
296 and the program subsequently calls an unsafe function,
297 then the behavior of the program is undefined.
298 .IP \[bu]
299 POSIX.1-2001 TC1 clarified
300 that if an application calls
301 .BR fork (2)
302 from a signal handler and any of the fork handlers registered by
303 .BR pthread_atfork (3)
304 calls a function that is not async-signal-safe, the behavior is undefined.
305 A future revision of the standard
306 .\" http://www.opengroup.org/austin/aardvark/latest/xshbug3.txt
307 is likely to remove
308 .BR fork (2)
309 from the list of async-signal-safe functions.
310 .\"
311 .IP \[bu]
312 Asynchronous signal handlers that call functions which are cancelation
313 points and nest over regions of deferred cancelation may trigger
314 cancelation whose behavior is as if asynchronous cancelation had
315 occurred and may cause application state to become inconsistent.
316 .\"
317 .SS errno
318 Fetching and setting the value of
319 .I errno
320 is async-signal-safe provided that the signal handler saves
321 .I errno
322 on entry and restores its value before returning.
323 .\"
324 .SS Deviations in the GNU C library
325 The following known deviations from the standard occur in
326 the GNU C library:
327 .IP \[bu] 3
328 Before glibc 2.24,
329 .BR execl (3)
330 and
331 .BR execle (3)
332 employed
333 .BR realloc (3)
334 internally and were consequently not async-signal-safe.
335 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=19534
336 This was fixed in glibc 2.24.
337 .IP \[bu]
338 .\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=13172
339 The glibc implementation of
340 .BR aio_suspend (3)
341 is not async-signal-safe because it uses
342 .BR pthread_mutex_lock (3)
343 internally.
344 .SH SEE ALSO
345 .BR sigaction (2),
346 .BR signal (7),
347 .BR standards (7)