huschi.net

PTHREAD_ATFORK(3)          Linux Programmer's Manual         PTHREAD_ATFORK(3)
NAME
       pthread_atfork - register fork handlers
SYNOPSIS
       #include <pthread.h>
       int pthread_atfork(void (*prepare)(void), void (*parent)(void),
                          void (*child)(void));
       Link with -pthread.
DESCRIPTION
       The  pthread_atfork()  function  registers fork handlers that are to be
       executed when fork(2) is called by this thread.  The handlers are  exe-
       cuted in the context of the thread that calls fork(2).
       Three kinds of handler can be registered:
       *  prepare specifies a handler that is executed before fork(2) process-
          ing starts.
       *  parent specifies a handler that is executed in  the  parent  process
          after fork(2) processing completes.
       *  child  specifies  a  handler  that  is executed in the child process
          after fork(2) processing completes.
       Any of the three arguments may be NULL if no handler is needed  in  the
       corresponding phase of fork(2) processing.
RETURN VALUE
       On  success,  pthread_atfork()  returns  zero.  On error, it returns an
       error number.  pthread_atfork() may  be  called  multiple  times  by  a
       thread, to register multiple handlers for each phase.  The handlers for
       each phase are called in a specified order: the  prepare  handlers  are
       called  in reverse order of registration; the parent and child handlers
       are called in the order of registration.
ERRORS
       ENOMEM Could not allocate memory to record the form handler entry.
CONFORMING TO
       POSIX.1-2001, POSIX.1-2008.
NOTES
       When fork(2) is called in a multithreaded  process,  only  the  calling
       thread  is  duplicated in the child process.  The original intention of
       pthread_atfork() was to allow the calling thread to be  returned  to  a
       consistent  state.   For  example,  at the time of the call to fork(2),
       other threads may have locked mutexes that are  visible  in  the  user-
       space  memory  duplicated  in  the  child.  Such mutexes would never be
       unlocked, since the threads that placed the locks are not duplicated in
       the  child.   The intent of pthread_atfork() was to provide a mechanism
       whereby the application (or a library) could ensure  that  mutexes  and
       other process and thread state would be restored to a consistent state.
       In practice, this task is generally too difficult to be practicable.
       After a fork(2) in a multithreaded process returns in  the  child,  the
       child   should  call  only  async-signal-safe  functions  (see  signal-
       safety(7)) until such time as it calls execve(2) to execute a new  pro-
       gram.
       POSIX.1  specifies  that pthread_atfork() shall not fail with the error
       EINTR.
SEE ALSO
       fork(2), atexit(3), pthreads(7)
COLOPHON
       This page is part of release 4.15 of the Linux  man-pages  project.   A
       description  of  the project, information about reporting bugs, and the
       latest    version    of    this    page,    can     be     found     at
       https://www.kernel.org/doc/man-pages/.
Linux                             2017-09-15                 PTHREAD_ATFORK(3)