man3/pthread_atfork.3

   1 .\" Copyright (C) 2017 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH pthread_atfork 3 (date) "Linux man-pages (unreleased)"
   6 .SH NAME
   7 pthread_atfork \- register fork handlers
   8 .SH LIBRARY
   9 POSIX threads library
  10 .RI ( libpthread ", " \-lpthread )
  11 .SH SYNOPSIS
  12 .nf
  13 .B  #include <pthread.h>
  14 .PP
  15 .BI "int pthread_atfork(void (*" prepare ")(void), void (*" parent ")(void),"
  16 .BI "                   void (*" child ")(void));"
  17 .fi
  18 .SH DESCRIPTION
  19 The
  20 .BR pthread_atfork ()
  21 function registers fork handlers that are to be executed when
  22 .BR fork (2)
  23 is called by any thread in a process.
  24 The handlers are executed in the context of the thread that calls
  25 .BR fork (2).
  26 .PP
  27 Three kinds of handler can be registered:
  28 .IP \(bu 3
  29 .I prepare
  30 specifies a handler that is executed in the parent process before
  31 .BR fork (2)
  32 processing starts.
  33 .IP \(bu
  34 .I parent
  35 specifies a handler that is executed in the parent process after
  36 .BR fork (2)
  37 processing completes.
  38 .IP \(bu
  39 .I child
  40 specifies a handler that is executed in the child process after
  41 .BR fork (2)
  42 processing completes.
  43 .PP
  44 Any of the three arguments may be NULL if no handler is needed
  45 in the corresponding phase of
  46 .BR fork (2)
  47 processing.
  48 .SH RETURN VALUE
  49 On success,
  50 .BR pthread_atfork ()
  51 returns zero.
  52 On error, it returns an error number.
  53 .BR pthread_atfork ()
  54 may be called multiple times by a process
  55 to register additional handlers.
  56 The handlers for each phase are called in a specified order: the
  57 .I prepare
  58 handlers are called in reverse order of registration; the
  59 .I parent
  60 and
  61 .I child
  62 handlers are called in the order of registration.
  63 .SH ERRORS
  64 .TP
  65 .B ENOMEM
  66 Could not allocate memory to record the fork handler list entry.
  67 .SH STANDARDS
  68 POSIX.1-2001, POSIX.1-2008.
  69 .SH NOTES
  70 When
  71 .BR fork (2)
  72 is called in a multithreaded process,
  73 only the calling thread is duplicated in the child process.
  74 The original intention of
  75 .BR pthread_atfork ()
  76 was to allow the child process to be returned to a consistent state.
  77 For example, at the time of the call to
  78 .BR fork (2),
  79 other threads may have locked mutexes that are visible in the
  80 user-space memory duplicated in the child.
  81 Such mutexes would never be unlocked,
  82 since the threads that placed the locks are not duplicated in the child.
  83 The intent of
  84 .BR pthread_atfork ()
  85 was to provide a mechanism whereby the application (or a library)
  86 could ensure that mutexes and other process and thread state would be
  87 restored to a consistent state.
  88 In practice, this task is generally too difficult to be practicable.
  89 .PP
  90 After a
  91 .BR fork (2)
  92 in a multithreaded process returns in the child,
  93 the child should call only async-signal-safe functions (see
  94 .BR signal\-safety (7))
  95 until such time as it calls
  96 .BR execve (2)
  97 to execute a new program.
  98 .PP
  99 POSIX.1 specifies that
 100 .BR pthread_atfork ()
 101 shall not fail with the error
 102 .BR EINTR .
 103 .SH SEE ALSO
 104 .BR fork (2),
 105 .BR atexit (3),
 106 .BR pthreads (7)