man3p/pthread_atfork.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "PTHREAD_ATFORK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" pthread_atfork
   4 .SH NAME
   5 pthread_atfork \- register fork handlers
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <pthread.h>
   9 .br
  10 .sp
  11 int pthread_atfork(void (*\fP\fIprepare\fP\fB)(void), void (*\fP\fIparent\fP\fB)(void),
  12 .br
  13 \ \ \ \ \ \  void (*\fP\fIchild\fP\fB)(void)); \fP
  14 \fB
  15 .br
  16 \fP
  17 .SH DESCRIPTION
  18 .LP
  19 The \fIpthread_atfork\fP() function shall declare fork handlers to
  20 be called before and after \fIfork\fP(), in the context of the thread
  21 that called \fIfork\fP(). The \fIprepare\fP fork handler shall be
  22 called before \fIfork\fP() processing commences. The \fIparent\fP
  23 fork handle shall be called after \fIfork\fP() processing completes
  24 in the parent process. The \fIchild\fP fork handler shall be
  25 called after \fIfork\fP() processing completes in the child process.
  26 If no handling is
  27 desired at one or more of these three points, the corresponding fork
  28 handler address(es) may be set to NULL.
  29 .LP
  30 The order of calls to \fIpthread_atfork\fP() is significant. The \fIparent\fP
  31 and \fIchild\fP fork handlers shall be called
  32 in the order in which they were established by calls to \fIpthread_atfork\fP().
  33 The \fIprepare\fP fork handlers shall be called
  34 in the opposite order.
  35 .SH RETURN VALUE
  36 .LP
  37 Upon successful completion, \fIpthread_atfork\fP() shall return a
  38 value of zero; otherwise, an error number shall be returned
  39 to indicate the error.
  40 .SH ERRORS
  41 .LP
  42 The \fIpthread_atfork\fP() function shall fail if:
  43 .TP 7
  44 .B ENOMEM
  45 Insufficient table space exists to record the fork handler addresses.
  46 .sp
  47 .LP
  48 The \fIpthread_atfork\fP() function shall not return an error code
  49 of [EINTR].
  50 .LP
  51 \fIThe following sections are informative.\fP
  52 .SH EXAMPLES
  53 .LP
  54 None.
  55 .SH APPLICATION USAGE
  56 .LP
  57 None.
  58 .SH RATIONALE
  59 .LP
  60 There are at least two serious problems with the semantics of \fIfork\fP()
  61 in a
  62 multi-threaded program. One problem has to do with state (for example,
  63 memory) covered by mutexes. Consider the case where one
  64 thread has a mutex locked and the state covered by that mutex is inconsistent
  65 while another thread calls \fIfork\fP(). In the child, the mutex is
  66 in the locked state (locked by a nonexistent thread and thus
  67 can never be unlocked). Having the child simply reinitialize the mutex
  68 is unsatisfactory since this approach does not resolve the
  69 question about how to correct or otherwise deal with the inconsistent
  70 state in the child.
  71 .LP
  72 It is suggested that programs that use \fIfork\fP() call an \fIexec\fP
  73 function very soon afterwards in the child process, thus resetting
  74 all states. In the
  75 meantime, only a short list of async-signal-safe library routines
  76 are promised to be available.
  77 .LP
  78 Unfortunately, this solution does not address the needs of multi-threaded
  79 libraries. Application programs may not be aware that
  80 a multi-threaded library is in use, and they feel free to call any
  81 number of library routines between the \fIfork\fP() and \fIexec\fP
  82 calls, just as they always have.
  83 Indeed, they may be extant single-threaded programs and cannot, therefore,
  84 be expected to obey new restrictions imposed by the
  85 threads library.
  86 .LP
  87 On the other hand, the multi-threaded library needs a way to protect
  88 its internal state during \fIfork\fP() in case it is re-entered later
  89 in the child process. The problem arises especially in
  90 multi-threaded I/O libraries, which are almost sure to be invoked
  91 between the \fIfork\fP()
  92 and \fIexec\fP calls to effect I/O redirection. The solution may require
  93 locking mutex
  94 variables during \fIfork\fP(), or it may entail simply resetting the
  95 state in the child after
  96 the \fIfork\fP() processing completes.
  97 .LP
  98 The \fIpthread_atfork\fP() function provides multi-threaded libraries
  99 with a means to protect themselves from innocent
 100 application programs that call \fIfork\fP(), and it provides multi-threaded
 101 application
 102 programs with a standard mechanism for protecting themselves from
 103 \fIfork\fP() calls in a
 104 library routine or the application itself.
 105 .LP
 106 The expected usage is that the \fIprepare\fP handler acquires all
 107 mutex locks and the other two fork handlers release them.
 108 .LP
 109 For example, an application can supply a \fIprepare\fP routine that
 110 acquires the necessary mutexes the library maintains and
 111 supply \fIchild\fP and \fIparent\fP routines that release those mutexes,
 112 thus ensuring that the child gets a consistent snapshot
 113 of the state of the library (and that no mutexes are left stranded).
 114 Alternatively, some libraries might be able to supply just a
 115 \fIchild\fP routine that reinitializes the mutexes in the library
 116 and all associated states to some known value (for example, what
 117 it was when the image was originally executed).
 118 .LP
 119 When \fIfork\fP() is called, only the calling thread is duplicated
 120 in the child process.
 121 Synchronization variables remain in the same state in the child as
 122 they were in the parent at the time \fIfork\fP() was called. Thus,
 123 for example, mutex locks may be held by threads that no longer exist
 124 in the child process, and any associated states may be inconsistent.
 125 The parent process may avoid this by explicit code that
 126 acquires and releases locks critical to the child via \fIpthread_atfork\fP().
 127 In addition, any critical threads need to be
 128 recreated and reinitialized to the proper state in the child (also
 129 via \fIpthread_atfork\fP()).
 130 .LP
 131 A higher-level package may acquire locks on its own data structures
 132 before invoking lower-level packages. Under this scenario,
 133 the order specified for fork handler calls allows a simple rule of
 134 initialization for avoiding package deadlock: a package
 135 initializes all packages on which it depends before it calls the \fIpthread_atfork\fP()
 136 function for itself.
 137 .SH FUTURE DIRECTIONS
 138 .LP
 139 None.
 140 .SH SEE ALSO
 141 .LP
 142 \fIatexit\fP() , \fIfork\fP() , the Base Definitions volume of
 143 IEEE\ Std\ 1003.1-2001, \fI<sys/types.h>\fP
 144 .SH COPYRIGHT
 145 Portions of this text are reprinted and reproduced in electronic form
 146 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 147 -- Portable Operating System Interface (POSIX), The Open Group Base
 148 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 149 Electrical and Electronics Engineers, Inc and The Open Group. In the
 150 event of any discrepancy between this version and the original IEEE and
 151 The Open Group Standard, the original IEEE and The Open Group Standard
 152 is the referee document. The original Standard can be obtained online at
 153 http://www.opengroup.org/unix/online.html .