pthread_atfork(3)

1pthread_atfork(3)          Library Functions Manual          pthread_atfork(3)
2
3
4

NAME

6       pthread_atfork - register fork handlers
7

LIBRARY

9       POSIX threads library (libpthread, -lpthread)
10

SYNOPSIS

12       #include <pthread.h>
13
14       int pthread_atfork(void (*prepare)(void), void (*parent)(void),
15                          void (*child)(void));
16

DESCRIPTION

18       The  pthread_atfork()  function  registers fork handlers that are to be
19       executed when fork(2) is called by any thread in a process.   The  han‐
20       dlers are executed in the context of the thread that calls fork(2).
21
22       Three kinds of handler can be registered:
23
24       •  prepare  specifies  a handler that is executed in the parent process
25          before fork(2) processing starts.
26
27       •  parent specifies a handler that is executed in  the  parent  process
28          after fork(2) processing completes.
29
30       •  child  specifies a handler that is executed in the child process af‐
31          ter fork(2) processing completes.
32
33       Any of the three arguments may be NULL if no handler is needed  in  the
34       corresponding phase of fork(2) processing.
35

RETURN VALUE

37       On success, pthread_atfork() returns zero.  On error, it returns an er‐
38       ror number.  pthread_atfork() may be called multiple times by a process
39       to  register  additional  handlers.   The  handlers  for each phase are
40       called in a specified order: the prepare handlers are called in reverse
41       order  of registration; the parent and child handlers are called in the
42       order of registration.
43

ERRORS

45       ENOMEM Could not allocate memory to record the fork handler list entry.
46

STANDARDS

48       POSIX.1-2008.
49

HISTORY

51       POSIX.1-2001.
52

NOTES

54       When fork(2) is called in a multithreaded  process,  only  the  calling
55       thread  is  duplicated in the child process.  The original intention of
56       pthread_atfork() was to allow the child process to  be  returned  to  a
57       consistent  state.   For  example,  at the time of the call to fork(2),
58       other threads may have locked mutexes that are  visible  in  the  user-
59       space  memory duplicated in the child.  Such mutexes would never be un‐
60       locked, since the threads that placed the locks are not  duplicated  in
61       the  child.   The intent of pthread_atfork() was to provide a mechanism
62       whereby the application (or a library) could ensure  that  mutexes  and
63       other process and thread state would be restored to a consistent state.
64       In practice, this task is generally too difficult to be practicable.
65
66       After a fork(2) in a multithreaded process returns in  the  child,  the
67       child   should   call   only   async-signal-safe  functions  (see  sig‐
68       nal-safety(7)) until such time as it calls execve(2) to execute  a  new
69       program.
70
71       POSIX.1  specifies  that pthread_atfork() shall not fail with the error
72       EINTR.
73