1SIGNAL-SAFETY(7)           Linux Programmer's Manual          SIGNAL-SAFETY(7)
2
3
4

NAME

6       signal-safety - async-signal-safe functions
7

DESCRIPTION

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
14       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
18       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
24       moment, 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
28       To avoid  problems  with  unsafe  functions,  there  are  two  possible
29       choices:
30
31       1. Ensure  that  (a)  the  signal  handler calls only async-signal-safe
32          functions, and (b) the  signal  handler  itself  is  reentrant  with
33          respect to global variables in the main program.
34
35       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
39       Generally,  the  second choice is difficult in programs of any complex‐
40       ity, so the first choice is taken.
41
42       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.)  In gen‐
46       eral, a function is async-signal-safe either because it is reentrant or
47       because it is atomic with respect to signals (i.e., its execution can't
48       be interrupted by a signal handler).
49
50       The set of functions required to be  async-signal-safe  by  POSIX.1  is
51       shown  in  the following table.  The functions not otherwise noted were
52       required to be async-signal-safe in  POSIX.1-2001;  the  table  details
53       changes in the subsequent standards.
54
55       Function               Notes
56       abort(3)               Added in POSIX.1-2003
57       accept(2)
58       access(2)
59       aio_error(3)
60       aio_return(3)
61       aio_suspend(3)         See notes below
62       alarm(2)
63       bind(2)
64       cfgetispeed(3)
65       cfgetospeed(3)
66
67       cfsetispeed(3)
68       cfsetospeed(3)
69       chdir(2)
70       chmod(2)
71       chown(2)
72       clock_gettime(2)
73       close(2)
74       connect(2)
75       creat(2)
76       dup(2)
77       dup2(2)
78       execl(3)               Added in POSIX.1-2008; see notes below
79       execle(3)              See notes below
80       execv(3)               Added in POSIX.1-2008
81       execve(2)
82       _exit(2)
83       _Exit(2)
84       faccessat(2)           Added in POSIX.1-2008
85       fchdir(2)              Added in POSIX.1-2013
86       fchmod(2)
87       fchmodat(2)            Added in POSIX.1-2008
88       fchown(2)
89       fchownat(2)            Added in POSIX.1-2008
90       fcntl(2)
91       fdatasync(2)
92       fexecve(3)             Added in POSIX.1-2008
93       ffs(3)                 Added in POSIX.1-2016
94       fork(2)                See notes below
95       fstat(2)
96       fstatat(2)             Added in POSIX.1-2008
97       fsync(2)
98       ftruncate(2)
99       futimens(3)            Added in POSIX.1-2008
100       getegid(2)
101       geteuid(2)
102       getgid(2)
103       getgroups(2)
104       getpeername(2)
105       getpgrp(2)
106       getpid(2)
107       getppid(2)
108       getsockname(2)
109       getsockopt(2)
110       getuid(2)
111       htonl(3)               Added in POSIX.1-2016
112       htons(3)               Added in POSIX.1-2016
113       kill(2)
114       link(2)
115       linkat(2)              Added in POSIX.1-2008
116       listen(2)
117       longjmp(3)             Added in POSIX.1-2016; see notes below
118       lseek(2)
119       lstat(2)
120       memccpy(3)             Added in POSIX.1-2016
121       memchr(3)              Added in POSIX.1-2016
122       memcmp(3)              Added in POSIX.1-2016
123       memcpy(3)              Added in POSIX.1-2016
124       memmove(3)             Added in POSIX.1-2016
125       memset(3)              Added in POSIX.1-2016
126       mkdir(2)
127       mkdirat(2)             Added in POSIX.1-2008
128       mkfifo(3)
129       mkfifoat(3)            Added in POSIX.1-2008
130       mknod(2)               Added in POSIX.1-2008
131       mknodat(2)             Added in POSIX.1-2008
132
133       ntohl(3)               Added in POSIX.1-2016
134       ntohs(3)               Added in POSIX.1-2016
135       open(2)
136       openat(2)              Added in POSIX.1-2008
137       pause(2)
138       pipe(2)
139       poll(2)
140       posix_trace_event(3)
141       pselect(2)
142       pthread_kill(3)        Added in POSIX.1-2013
143       pthread_self(3)        Added in POSIX.1-2013
144       pthread_sigmask(3)     Added in POSIX.1-2013
145       raise(3)
146       read(2)
147       readlink(2)
148       readlinkat(2)          Added in POSIX.1-2008
149       recv(2)
150       recvfrom(2)
151       recvmsg(2)
152       rename(2)
153       renameat(2)            Added in POSIX.1-2008
154       rmdir(2)
155       select(2)
156       sem_post(3)
157       send(2)
158       sendmsg(2)
159       sendto(2)
160       setgid(2)
161       setpgid(2)
162       setsid(2)
163       setsockopt(2)
164       setuid(2)
165       shutdown(2)
166       sigaction(2)
167       sigaddset(3)
168       sigdelset(3)
169       sigemptyset(3)
170       sigfillset(3)
171       sigismember(3)
172       siglongjmp(3)          Added in POSIX.1-2016; see notes below
173       signal(2)
174       sigpause(3)
175       sigpending(2)
176       sigprocmask(2)
177       sigqueue(2)
178       sigset(3)
179       sigsuspend(2)
180       sleep(3)
181       sockatmark(3)          Added in POSIX.1-2004
182       socket(2)
183       socketpair(2)
184       stat(2)
185       stpcpy(3)              Added in POSIX.1-2016
186       stpncpy(3)             Added in POSIX.1-2016
187       strcat(3)              Added in POSIX.1-2016
188       strchr(3)              Added in POSIX.1-2016
189       strcmp(3)              Added in POSIX.1-2016
190       strcpy(3)              Added in POSIX.1-2016
191       strcspn(3)             Added in POSIX.1-2016
192       strlen(3)              Added in POSIX.1-2016
193       strncat(3)             Added in POSIX.1-2016
194       strncmp(3)             Added in POSIX.1-2016
195       strncpy(3)             Added in POSIX.1-2016
196       strnlen(3)             Added in POSIX.1-2016
197       strpbrk(3)             Added in POSIX.1-2016
198
199       strrchr(3)             Added in POSIX.1-2016
200       strspn(3)              Added in POSIX.1-2016
201       strstr(3)              Added in POSIX.1-2016
202       strtok_r(3)            Added in POSIX.1-2016
203       symlink(2)
204       symlinkat(2)           Added in POSIX.1-2008
205       tcdrain(3)
206       tcflow(3)
207       tcflush(3)
208       tcgetattr(3)
209       tcgetpgrp(3)
210       tcsendbreak(3)
211       tcsetattr(3)
212       tcsetpgrp(3)
213       time(2)
214       timer_getoverrun(2)
215       timer_gettime(2)
216       timer_settime(2)
217       times(2)
218       umask(2)
219       uname(2)
220       unlink(2)
221       unlinkat(2)            Added in POSIX.1-2008
222       utime(2)
223       utimensat(2)           Added in POSIX.1-2008
224       utimes(2)              Added in POSIX.1-2008
225       wait(2)
226       waitpid(2)
227       wcpcpy(3)              Added in POSIX.1-2016
228       wcpncpy(3)             Added in POSIX.1-2016
229       wcscat(3)              Added in POSIX.1-2016
230       wcschr(3)              Added in POSIX.1-2016
231       wcscmp(3)              Added in POSIX.1-2016
232       wcscpy(3)              Added in POSIX.1-2016
233       wcscspn(3)             Added in POSIX.1-2016
234       wcslen(3)              Added in POSIX.1-2016
235       wcsncat(3)             Added in POSIX.1-2016
236       wcsncmp(3)             Added in POSIX.1-2016
237       wcsncpy(3)             Added in POSIX.1-2016
238       wcsnlen(3)             Added in POSIX.1-2016
239       wcspbrk(3)             Added in POSIX.1-2016
240       wcsrchr(3)             Added in POSIX.1-2016
241       wcsspn(3)              Added in POSIX.1-2016
242       wcsstr(3)              Added in POSIX.1-2016
243       wcstok(3)              Added in POSIX.1-2016
244       wmemchr(3)             Added in POSIX.1-2016
245       wmemcmp(3)             Added in POSIX.1-2016
246       wmemcpy(3)             Added in POSIX.1-2016
247       wmemmove(3)            Added in POSIX.1-2016
248       wmemset(3)             Added in POSIX.1-2016
249       write(2)
250
251       Notes:
252
253       *  POSIX.1-2001  and  POSIX.1-2004 required the functions fpathconf(3),
254          pathconf(3),  and  sysconf(3)  to  be  async-signal-safe,  but  this
255          requirement was removed in POSIX.1-2008.
256
257       *  If  a signal handler interrupts the execution of an unsafe function,
258          and the handler terminates via a call to longjmp(3) or siglongjmp(3)
259          and  the  program  subsequently  calls  an unsafe function, then the
260          behavior of the program is undefined.
261
262       *  POSIX.1-2003 clarified that if an application calls fork(2)  from  a
263          signal   handler   and  any  of  the  fork  handlers  registered  by
264          pthread_atfork(3) calls a function that  is  not  async-signal-safe,
265          the  behavior  is  undefined.   A future revision of the standard is
266          likely to remove fork(2) from the list  of  async-signal-safe  func‐
267          tions.
268
269   Deviations in the GNU C library
270       The  following  known  deviations  from the standard occur in the GNU C
271       library:
272
273       *  Before glibc 2.24, execl(3) and execle(3) employed realloc(3) inter‐
274          nally  and  were consequently not async-signal-safe.  This was fixed
275          in glibc 2.24.
276
277       *  The glibc implementation of aio_suspend(3) is not  async-signal-safe
278          because it uses pthread_mutex_lock(3) internally.
279

SEE ALSO

281       sigaction(2), signal(7), standards(7)
282

COLOPHON

284       This  page  is  part of release 5.02 of the Linux man-pages project.  A
285       description of the project, information about reporting bugs,  and  the
286       latest     version     of     this    page,    can    be    found    at
287       https://www.kernel.org/doc/man-pages/.
288
289
290
291Linux                             2017-03-13                  SIGNAL-SAFETY(7)
Impressum