| blob | cde19a575b35df3bc86f6b6ae29d249046f2d826 |
1 '\" t
2 .\" Copyright (c) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH signal-safety 7 (date) "Linux man-pages (unreleased)"
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 l 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 \fBexecl\fP(3) T{
99 Added in POSIX.1-2008; see notes below
100 T}
101 \fBexecle\fP(3) See notes below
102 \fBexecv\fP(3) Added in POSIX.1-2008
103 \fBexecve\fP(2)
104 \fB_exit\fP(2)
105 \fB_Exit\fP(2)
106 \fBfaccessat\fP(2) Added in POSIX.1-2008
107 \fBfchdir\fP(2) Added in POSIX.1-2008 TC1
108 \fBfchmod\fP(2)
109 \fBfchmodat\fP(2) Added in POSIX.1-2008
110 \fBfchown\fP(2)
111 \fBfchownat\fP(2) Added in POSIX.1-2008
112 \fBfcntl\fP(2)
113 \fBfdatasync\fP(2)
114 \fBfexecve\fP(3) Added in POSIX.1-2008
115 \fBffs\fP(3) Added in POSIX.1-2008 TC2
116 \fBfork\fP(2) See notes below
117 \fBfstat\fP(2)
118 \fBfstatat\fP(2) Added in POSIX.1-2008
119 \fBfsync\fP(2)
120 \fBftruncate\fP(2)
121 \fBfutimens\fP(3) Added in POSIX.1-2008
122 \fBgetegid\fP(2)
123 \fBgeteuid\fP(2)
124 \fBgetgid\fP(2)
125 \fBgetgroups\fP(2)
126 \fBgetpeername\fP(2)
127 \fBgetpgrp\fP(2)
128 \fBgetpid\fP(2)
129 \fBgetppid\fP(2)
130 \fBgetsockname\fP(2)
131 \fBgetsockopt\fP(2)
132 \fBgetuid\fP(2)
133 \fBhtonl\fP(3) Added in POSIX.1-2008 TC2
134 \fBhtons\fP(3) Added in POSIX.1-2008 TC2
135 \fBkill\fP(2)
136 \fBlink\fP(2)
137 \fBlinkat\fP(2) Added in POSIX.1-2008
138 \fBlisten\fP(2)
139 \fBlongjmp\fP(3) T{
140 Added in POSIX.1-2008 TC2; see notes below
141 T}
142 \fBlseek\fP(2)
143 \fBlstat\fP(2)
144 \fBmemccpy\fP(3) Added in POSIX.1-2008 TC2
145 \fBmemchr\fP(3) Added in POSIX.1-2008 TC2
146 \fBmemcmp\fP(3) Added in POSIX.1-2008 TC2
147 \fBmemcpy\fP(3) Added in POSIX.1-2008 TC2
148 \fBmemmove\fP(3) Added in POSIX.1-2008 TC2
149 \fBmemset\fP(3) Added in POSIX.1-2008 TC2
150 \fBmkdir\fP(2)
151 \fBmkdirat\fP(2) Added in POSIX.1-2008
152 \fBmkfifo\fP(3)
153 \fBmkfifoat\fP(3) Added in POSIX.1-2008
154 \fBmknod\fP(2) Added in POSIX.1-2008
155 \fBmknodat\fP(2) Added in POSIX.1-2008
156 \fBntohl\fP(3) Added in POSIX.1-2008 TC2
157 \fBntohs\fP(3) Added in POSIX.1-2008 TC2
158 \fBopen\fP(2)
159 \fBopenat\fP(2) Added in POSIX.1-2008
160 \fBpause\fP(2)
161 \fBpipe\fP(2)
162 \fBpoll\fP(2)
163 \fBposix_trace_event\fP(3)
164 \fBpselect\fP(2)
165 \fBpthread_kill\fP(3) Added in POSIX.1-2008 TC1
166 \fBpthread_self\fP(3) Added in POSIX.1-2008 TC1
167 \fBpthread_sigmask\fP(3) Added in POSIX.1-2008 TC1
168 \fBraise\fP(3)
169 \fBread\fP(2)
170 \fBreadlink\fP(2)
171 \fBreadlinkat\fP(2) Added in POSIX.1-2008
172 \fBrecv\fP(2)
173 \fBrecvfrom\fP(2)
174 \fBrecvmsg\fP(2)
175 \fBrename\fP(2)
176 \fBrenameat\fP(2) Added in POSIX.1-2008
177 \fBrmdir\fP(2)
178 \fBselect\fP(2)
179 \fBsem_post\fP(3)
180 \fBsend\fP(2)
181 \fBsendmsg\fP(2)
182 \fBsendto\fP(2)
183 \fBsetgid\fP(2)
184 \fBsetpgid\fP(2)
185 \fBsetsid\fP(2)
186 \fBsetsockopt\fP(2)
187 \fBsetuid\fP(2)
188 \fBshutdown\fP(2)
189 \fBsigaction\fP(2)
190 \fBsigaddset\fP(3)
191 \fBsigdelset\fP(3)
192 \fBsigemptyset\fP(3)
193 \fBsigfillset\fP(3)
194 \fBsigismember\fP(3)
195 \fBsiglongjmp\fP(3) T{
196 Added in POSIX.1-2008 TC2; see notes below
197 T}
198 \fBsignal\fP(2)
199 \fBsigpause\fP(3)
200 \fBsigpending\fP(2)
201 \fBsigprocmask\fP(2)
202 \fBsigqueue\fP(2)
203 \fBsigset\fP(3)
204 \fBsigsuspend\fP(2)
205 \fBsleep\fP(3)
206 \fBsockatmark\fP(3) Added in POSIX.1-2001 TC2
207 \fBsocket\fP(2)
208 \fBsocketpair\fP(2)
209 \fBstat\fP(2)
210 \fBstpcpy\fP(3) Added in POSIX.1-2008 TC2
211 \fBstpncpy\fP(3) Added in POSIX.1-2008 TC2
212 \fBstrcat\fP(3) Added in POSIX.1-2008 TC2
213 \fBstrchr\fP(3) Added in POSIX.1-2008 TC2
214 \fBstrcmp\fP(3) Added in POSIX.1-2008 TC2
215 \fBstrcpy\fP(3) Added in POSIX.1-2008 TC2
216 \fBstrcspn\fP(3) Added in POSIX.1-2008 TC2
217 \fBstrlen\fP(3) Added in POSIX.1-2008 TC2
218 \fBstrncat\fP(3) Added in POSIX.1-2008 TC2
219 \fBstrncmp\fP(3) Added in POSIX.1-2008 TC2
220 \fBstrncpy\fP(3) Added in POSIX.1-2008 TC2
221 \fBstrnlen\fP(3) Added in POSIX.1-2008 TC2
222 \fBstrpbrk\fP(3) Added in POSIX.1-2008 TC2
223 \fBstrrchr\fP(3) Added in POSIX.1-2008 TC2
224 \fBstrspn\fP(3) Added in POSIX.1-2008 TC2
225 \fBstrstr\fP(3) Added in POSIX.1-2008 TC2
226 \fBstrtok_r\fP(3) Added in POSIX.1-2008 TC2
227 \fBsymlink\fP(2)
228 \fBsymlinkat\fP(2) Added in POSIX.1-2008
229 \fBtcdrain\fP(3)
230 \fBtcflow\fP(3)
231 \fBtcflush\fP(3)
232 \fBtcgetattr\fP(3)
233 \fBtcgetpgrp\fP(3)
234 \fBtcsendbreak\fP(3)
235 \fBtcsetattr\fP(3)
236 \fBtcsetpgrp\fP(3)
237 \fBtime\fP(2)
238 \fBtimer_getoverrun\fP(2)
239 \fBtimer_gettime\fP(2)
240 \fBtimer_settime\fP(2)
241 \fBtimes\fP(2)
242 \fBumask\fP(2)
243 \fBuname\fP(2)
244 \fBunlink\fP(2)
245 \fBunlinkat\fP(2) Added in POSIX.1-2008
246 \fButime\fP(2)
247 \fButimensat\fP(2) Added in POSIX.1-2008
248 \fButimes\fP(2) Added in POSIX.1-2008
249 \fBwait\fP(2)
250 \fBwaitpid\fP(2)
251 \fBwcpcpy\fP(3) Added in POSIX.1-2008 TC2
252 \fBwcpncpy\fP(3) Added in POSIX.1-2008 TC2
253 \fBwcscat\fP(3) Added in POSIX.1-2008 TC2
254 \fBwcschr\fP(3) Added in POSIX.1-2008 TC2
255 \fBwcscmp\fP(3) Added in POSIX.1-2008 TC2
256 \fBwcscpy\fP(3) Added in POSIX.1-2008 TC2
257 \fBwcscspn\fP(3) Added in POSIX.1-2008 TC2
258 \fBwcslen\fP(3) Added in POSIX.1-2008 TC2
259 \fBwcsncat\fP(3) Added in POSIX.1-2008 TC2
260 \fBwcsncmp\fP(3) Added in POSIX.1-2008 TC2
261 \fBwcsncpy\fP(3) Added in POSIX.1-2008 TC2
262 \fBwcsnlen\fP(3) Added in POSIX.1-2008 TC2
263 \fBwcspbrk\fP(3) Added in POSIX.1-2008 TC2
264 \fBwcsrchr\fP(3) Added in POSIX.1-2008 TC2
265 \fBwcsspn\fP(3) Added in POSIX.1-2008 TC2
266 \fBwcsstr\fP(3) Added in POSIX.1-2008 TC2
267 \fBwcstok\fP(3) Added in POSIX.1-2008 TC2
268 \fBwmemchr\fP(3) Added in POSIX.1-2008 TC2
269 \fBwmemcmp\fP(3) Added in POSIX.1-2008 TC2
270 \fBwmemcpy\fP(3) Added in POSIX.1-2008 TC2
271 \fBwmemmove\fP(3) Added in POSIX.1-2008 TC2
272 \fBwmemset\fP(3) Added in POSIX.1-2008 TC2
273 \fBwrite\fP(2)
274 .TE
275 .P
276 Notes:
277 .IP \[bu] 3
278 POSIX.1-2001 and POSIX.1-2001 TC2 required the functions
279 .BR fpathconf (3),
280 .BR pathconf (3),
281 and
282 .BR sysconf (3)
283 to be async-signal-safe, but this requirement was removed in POSIX.1-2008.
284 .IP \[bu]
285 If a signal handler interrupts the execution of an unsafe function,
286 and the handler terminates via a call to
287 .BR longjmp (3)
288 or
289 .BR siglongjmp (3)
290 and the program subsequently calls an unsafe function,
291 then the behavior of the program is undefined.
292 .IP \[bu]
293 POSIX.1-2001 TC1 clarified
294 that if an application calls
295 .BR fork (2)
296 from a signal handler and any of the fork handlers registered by
297 .BR pthread_atfork (3)
298 calls a function that is not async-signal-safe, the behavior is undefined.
299 A future revision of the standard
300 .\" http://www.opengroup.org/austin/aardvark/latest/xshbug3.txt
301 is likely to remove
302 .BR fork (2)
303 from the list of async-signal-safe functions.
304 .\"
305 .IP \[bu]
306 Asynchronous signal handlers that call functions which are cancelation
307 points and nest over regions of deferred cancelation may trigger
308 cancelation whose behavior is as if asynchronous cancelation had
309 occurred and may cause application state to become inconsistent.
310 .\"
311 .SS errno
312 Fetching and setting the value of
313 .I errno
314 is async-signal-safe provided that the signal handler saves
315 .I errno
316 on entry and restores its value before returning.
317 .\"
318 .SS Deviations in the GNU C library
319 The following known deviations from the standard occur in
320 the GNU C library:
321 .IP \[bu] 3
322 Before glibc 2.24,
323 .BR execl (3)
324 and
325 .BR execle (3)
326 employed
327 .BR realloc (3)
328 internally and were consequently not async-signal-safe.
329 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=19534
330 This was fixed in glibc 2.24.
331 .IP \[bu]
332 .\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=13172
333 The glibc implementation of
334 .BR aio_suspend (3)
335 is not async-signal-safe because it uses
336 .BR pthread_mutex_lock (3)
337 internally.
338 .SH SEE ALSO
339 .BR sigaction (2),
340 .BR signal (7),
341 .BR standards (7)