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