1PTHREAD_ATFORK(3P)         POSIX Programmer's Manual        PTHREAD_ATFORK(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       pthread_atfork — register fork handlers
14

SYNOPSIS

16       #include <pthread.h>
17
18       int pthread_atfork(void (*prepare)(void), void (*parent)(void),
19           void (*child)(void));
20

DESCRIPTION

22       The pthread_atfork() function shall declare fork handlers to be  called
23       before  and  after  fork(),  in  the  context of the thread that called
24       fork().  The prepare fork handler shall be called  before  fork()  pro‐
25       cessing  commences. The parent fork handle shall be called after fork()
26       processing completes in the parent  process.  The  child  fork  handler
27       shall be called after fork() processing completes in the child process.
28       If no handling is desired at one or more of  these  three  points,  the
29       corresponding fork handler address(es) may be set to NULL.
30
31       The  order  of calls to pthread_atfork() is significant. The parent and
32       child fork handlers shall be called in the order  in  which  they  were
33       established  by  calls  to pthread_atfork().  The prepare fork handlers
34       shall be called in the opposite order.
35

RETURN VALUE

37       Upon successful completion, pthread_atfork() shall return  a  value  of
38       zero;  otherwise,  an  error  number  shall be returned to indicate the
39       error.
40

ERRORS

42       The pthread_atfork() function shall fail if:
43
44       ENOMEM Insufficient table space  exists  to  record  the  fork  handler
45              addresses.
46
47       The  pthread_atfork()  function  shall  not  return  an  error  code of
48       [EINTR].
49
50       The following sections are informative.
51

EXAMPLES

53       None.
54

APPLICATION USAGE

56       None.
57

RATIONALE

59       There are at least two serious problems with the semantics of fork() in
60       a  multi-threaded  program. One problem has to do with state (for exam‐
61       ple, memory) covered by mutexes. Consider the case where one thread has
62       a  mutex  locked  and  the  state covered by that mutex is inconsistent
63       while another thread calls fork().  In the child, the mutex is  in  the
64       locked  state  (locked  by  a  nonexistent thread and thus can never be
65       unlocked). Having the child simply reinitialize the mutex  is  unsatis‐
66       factory  since this approach does not resolve the question about how to
67       correct or otherwise deal with the inconsistent state in the child.
68
69       It is suggested that programs that use fork()  call  an  exec  function
70       very  soon  afterwards in the child process, thus resetting all states.
71       In the meantime, only a short list of  async-signal-safe  library  rou‐
72       tines are promised to be available.
73
74       Unfortunately,  this  solution  does  not  address  the needs of multi-
75       threaded libraries. Application programs may not be aware that a multi-
76       threaded  library  is  in use, and they feel free to call any number of
77       library routines between the fork() and exec calls, just as they always
78       have.  Indeed,  they may be extant single-threaded programs and cannot,
79       therefore, be expected to obey new restrictions imposed by the  threads
80       library.
81
82       On  the  other  hand, the multi-threaded library needs a way to protect
83       its internal state during fork() in case it is re-entered later in  the
84       child  process.  The  problem  arises  especially in multi-threaded I/O
85       libraries, which are almost sure to be invoked between the  fork()  and
86       exec  calls to effect I/O redirection. The solution may require locking
87       mutex variables during fork(), or it may entail  simply  resetting  the
88       state in the child after the fork() processing completes.
89
90       The  pthread_atfork()  function  was intended to provide multi-threaded
91       libraries with a means to protect themselves from innocent  application
92       programs  that  call  fork(), and to provide multi-threaded application
93       programs with a  standard  mechanism  for  protecting  themselves  from
94       fork() calls in a library routine or the application itself.
95
96       The expected usage was that the prepare handler would acquire all mutex
97       locks and the other two fork handlers would release them.
98
99       For example, an application could have supplied a prepare routine  that
100       acquires the necessary mutexes the library maintains and supplied child
101       and parent routines that release those mutexes, thus ensuring that  the
102       child  would have got a consistent snapshot of the state of the library
103       (and that no mutexes would have been left stranded). This  is  good  in
104       theory,  but in reality not practical. Each and every mutex and lock in
105       the process must be located and locked. Every component  of  a  program
106       including  third-party  components must participate and they must agree
107       who is responsible for which mutex or lock. This is especially problem‐
108       atic for mutexes and locks in dynamically allocated memory. All mutexes
109       and locks internal to the implementation must be locked, too. This pos‐
110       sibly  delays the thread calling fork() for a long time or even indefi‐
111       nitely since uses of these synchronization objects  may  not  be  under
112       control  of  the  application.  A  final problem to mention here is the
113       problem of locking streams. At least the streams under control  of  the
114       system  (like  stdin,  stdout, stderr) must be protected by locking the
115       stream with flockfile().  But the application itself  could  have  done
116       that,  possibly  in  the same thread calling fork().  In this case, the
117       process will deadlock.
118
119       Alternatively, some libraries might have been able  to  supply  just  a
120       child  routine  that  reinitializes  the mutexes in the library and all
121       associated states to some known value (for example, what  it  was  when
122       the  image  was  originally  executed).  This approach is not possible,
123       though, because  implementations  are  allowed  to  fail  *_init()  and
124       *_destroy()  calls  for mutexes and locks if the mutex or lock is still
125       locked. In this case, the child routine is not able to reinitialize the
126       mutexes and locks.
127
128       When  fork()  is  called,  only the calling thread is duplicated in the
129       child process.  Synchronization variables remain in the same  state  in
130       the  child  as  they  were in the parent at the time fork() was called.
131       Thus, for example, mutex locks may be held by threads  that  no  longer
132       exist  in the child process, and any associated states may be inconsis‐
133       tent. The intention was that the parent process could have avoided this
134       by explicit code that acquires and releases locks critical to the child
135       via pthread_atfork().  In addition, any  critical  threads  would  have
136       needed  to  be  recreated  and reinitialized to the proper state in the
137       child (also via pthread_atfork()).
138
139       A higher-level package may acquire locks on  its  own  data  structures
140       before  invoking  lower-level  packages. Under this scenario, the order
141       specified for fork handler calls allows a simple rule of initialization
142       for  avoiding  package  deadlock: a package initializes all packages on
143       which it depends before it  calls  the  pthread_atfork()  function  for
144       itself.
145
146       As  explained,  there  is  no suitable solution for functionality which
147       requires non-atomic operations to  be  protected  through  mutexes  and
148       locks. This is why the POSIX.1 standard since the 1996 release requires
149       that the child process after fork() in a  multi-threaded  process  only
150       calls async-signal-safe interfaces.
151

FUTURE DIRECTIONS

153       None.
154

SEE ALSO

156       atexit(), exec, fork()
157
158       The Base Definitions volume of POSIX.1‐2008, <pthread.h>, <sys_types.h>
159
161       Portions  of  this text are reprinted and reproduced in electronic form
162       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
163       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
164       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
165       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
166       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
167       event of any discrepancy between this version and the original IEEE and
168       The Open Group Standard, the original IEEE and The Open Group  Standard
169       is  the  referee document. The original Standard can be obtained online
170       at http://www.unix.org/online.html .
171
172       Any typographical or formatting errors that appear  in  this  page  are
173       most likely to have been introduced during the conversion of the source
174       files to man page format. To report such errors,  see  https://www.ker
175       nel.org/doc/man-pages/reporting_bugs.html .
176
177
178
179IEEE/The Open Group                  2013                   PTHREAD_ATFORK(3P)
Impressum