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.)
46
47       In  general, a function is async-signal-safe either because it is reen‐
48       trant or because it is atomic with respect to signals (i.e., its execu‐
49       tion can't be interrupted by a signal handler).
50
51       The  set  of  functions  required to be async-signal-safe by POSIX.1 is
52       shown in the following table.  The functions not otherwise  noted  were
53       required  to  be  async-signal-safe  in POSIX.1-2001; the table details
54       changes in the subsequent standards.
55
56       Function               Notes
57       abort(3)               Added in POSIX.1-2003
58       accept(2)
59       access(2)
60       aio_error(3)
61       aio_return(3)
62       aio_suspend(3)         See notes below
63       alarm(2)
64       bind(2)
65       cfgetispeed(3)
66
67       cfgetospeed(3)
68       cfsetispeed(3)
69       cfsetospeed(3)
70       chdir(2)
71       chmod(2)
72       chown(2)
73       clock_gettime(2)
74       close(2)