logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

pthread_atfork.3p (9294B)


  1. '\" et
  2. .TH PTHREAD_ATFORK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. pthread_atfork
  12. \(em register fork handlers
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <pthread.h>
  17. .P
  18. int pthread_atfork(void (*\fIprepare\fP)(void), void (*\fIparent\fP)(void),
  19. void (*\fIchild\fP)(void));
  20. .fi
  21. .SH DESCRIPTION
  22. The
  23. \fIpthread_atfork\fR()
  24. function shall declare fork handlers to be called before and after
  25. \fIfork\fR(),
  26. in the context of the thread that called
  27. \fIfork\fR().
  28. The
  29. .IR prepare
  30. fork handler shall be called before
  31. \fIfork\fR()
  32. processing commences. The
  33. .IR parent
  34. fork handle shall be called after
  35. \fIfork\fR()
  36. processing completes in the parent process. The
  37. .IR child
  38. fork handler shall be called after
  39. \fIfork\fR()
  40. processing completes in the child process. If no handling is desired
  41. at one or more of these three points, the corresponding fork handler
  42. address(es) may be set to NULL.
  43. .P
  44. If a
  45. \fIfork\fR()
  46. call in a multi-threaded process leads to a
  47. .IR child
  48. fork handler calling any function that is not async-signal-safe, the
  49. behavior is undefined.
  50. .P
  51. The order of calls to
  52. \fIpthread_atfork\fR()
  53. is significant. The
  54. .IR parent
  55. and
  56. .IR child
  57. fork handlers shall be called in the order in which they were
  58. established by calls to
  59. \fIpthread_atfork\fR().
  60. The
  61. .IR prepare
  62. fork handlers shall be called in the opposite order.
  63. .SH "RETURN VALUE"
  64. Upon successful completion,
  65. \fIpthread_atfork\fR()
  66. shall return a value of zero; otherwise, an error number shall be
  67. returned to indicate the error.
  68. .SH ERRORS
  69. The
  70. \fIpthread_atfork\fR()
  71. function shall fail if:
  72. .TP
  73. .BR ENOMEM
  74. Insufficient table space exists to record the fork handler addresses.
  75. .P
  76. The
  77. \fIpthread_atfork\fR()
  78. function shall not return an error code of
  79. .BR [EINTR] .
  80. .LP
  81. .IR "The following sections are informative."
  82. .SH EXAMPLES
  83. None.
  84. .SH "APPLICATION USAGE"
  85. The original usage pattern envisaged for
  86. \fIpthread_atfork\fR()
  87. was for the
  88. .IR prepare
  89. fork handler to lock mutexes and other locks, and for the
  90. .IR parent
  91. and
  92. .IR child
  93. handlers to unlock them. However, since all of the relevant unlocking
  94. functions, except
  95. \fIsem_post\fR(),
  96. are not async-signal-safe, this usage results in undefined behavior in
  97. the child process unless the only such unlocking function it calls is
  98. \fIsem_post\fR().
  99. .SH RATIONALE
  100. There are at least two serious problems with the semantics of
  101. \fIfork\fR()
  102. in a multi-threaded program. One problem has to do with state (for
  103. example, memory) covered by mutexes. Consider the case where one
  104. thread has a mutex locked and the state covered by that mutex is
  105. inconsistent while another thread calls
  106. \fIfork\fR().
  107. In the child, the mutex is in the locked state (locked by a nonexistent
  108. thread and thus can never be unlocked). Having the child simply
  109. reinitialize the mutex is unsatisfactory since this approach does not
  110. resolve the question about how to correct or otherwise deal with the
  111. inconsistent state in the child.
  112. .P
  113. It is suggested that programs that use
  114. \fIfork\fR()
  115. call an
  116. .IR exec
  117. function very soon afterwards in the child process, thus resetting all
  118. states. In the meantime, only a short list of async-signal-safe
  119. library routines are promised to be available.
  120. .P
  121. Unfortunately, this solution does not address the needs of
  122. multi-threaded libraries. Application programs may not be aware that a
  123. multi-threaded library is in use, and they feel free to call any number
  124. of library routines between the
  125. \fIfork\fR()
  126. and
  127. .IR exec
  128. calls, just as they always have. Indeed, they may be extant
  129. single-threaded programs and cannot, therefore, be expected to obey new
  130. restrictions imposed by the threads library.
  131. .P
  132. On the other hand, the multi-threaded library needs a way to protect
  133. its internal state during
  134. \fIfork\fR()
  135. in case it is re-entered later in the child process. The problem
  136. arises especially in multi-threaded I/O libraries, which are almost
  137. sure to be invoked between the
  138. \fIfork\fR()
  139. and
  140. .IR exec
  141. calls to effect I/O redirection. The solution may require locking
  142. mutex variables during
  143. \fIfork\fR(),
  144. or it may entail simply resetting the state in the child after the
  145. \fIfork\fR()
  146. processing completes.
  147. .P
  148. The
  149. \fIpthread_atfork\fR()
  150. function was intended to provide multi-threaded libraries with a means
  151. to protect themselves from innocent application programs that call
  152. \fIfork\fR(),
  153. and to provide multi-threaded application programs with a standard
  154. mechanism for protecting themselves from
  155. \fIfork\fR()
  156. calls in a library routine or the application itself.
  157. .P
  158. The expected usage was that the prepare handler would acquire all mutex
  159. locks and the other two fork handlers would release them.
  160. .P
  161. For example, an application could have supplied a prepare routine that
  162. acquires the necessary mutexes the library maintains and supplied child
  163. and parent routines that release those mutexes, thus ensuring that the
  164. child would have got a consistent snapshot of the state of the library
  165. (and that no mutexes would have been left stranded). This is good in
  166. theory, but in reality not practical. Each and every mutex and lock
  167. in the process must be located and locked. Every component of a program
  168. including third-party components must participate and they must agree who
  169. is responsible for which mutex or lock. This is especially problematic
  170. for mutexes and locks in dynamically allocated memory. All mutexes and
  171. locks internal to the implementation must be locked, too. This possibly
  172. delays the thread calling
  173. \fIfork\fR()
  174. for a long time or even indefinitely since uses of these synchronization
  175. objects may not be under control of the application. A final problem
  176. to mention here is the problem of locking streams. At least the streams
  177. under control of the system (like
  178. .IR stdin ,
  179. .IR stdout ,
  180. .IR stderr )
  181. must be protected by locking the stream with
  182. \fIflockfile\fR().
  183. But the application itself could have done that, possibly in the same
  184. thread calling
  185. \fIfork\fR().
  186. In this case, the process will deadlock.
  187. .P
  188. Alternatively, some libraries might have been able to supply just a
  189. .IR child
  190. routine that reinitializes the mutexes in the library and all associated
  191. states to some known value (for example, what it was when the image
  192. was originally executed). This approach is not possible, though,
  193. because implementations are allowed to fail
  194. .IR *_init (\|)
  195. and
  196. .IR *_destroy (\|)
  197. calls for mutexes and locks if the mutex or lock is still locked. In
  198. this case, the
  199. .IR child
  200. routine is not able to reinitialize the mutexes and locks.
  201. .P
  202. When
  203. \fIfork\fR()
  204. is called, only the calling thread is duplicated in the child process.
  205. Synchronization variables remain in the same state in the child as they
  206. were in the parent at the time
  207. \fIfork\fR()
  208. was called. Thus, for example, mutex locks may be held by threads that
  209. no longer exist in the child process, and any associated states may
  210. be inconsistent. The intention was that the parent process could have
  211. avoided this by explicit code that acquires and releases locks critical
  212. to the child via
  213. \fIpthread_atfork\fR().
  214. In addition, any critical threads would have needed to be recreated and
  215. reinitialized to the proper state in the child (also via
  216. \fIpthread_atfork\fR()).
  217. .P
  218. A higher-level package may acquire locks on its own data structures
  219. before invoking lower-level packages. Under this scenario, the order
  220. specified for fork handler calls allows a simple rule of initialization
  221. for avoiding package deadlock: a package initializes all packages on
  222. which it depends before it calls the
  223. \fIpthread_atfork\fR()
  224. function for itself.
  225. .P
  226. As explained, there is no suitable solution for functionality which
  227. requires non-atomic operations to be protected through mutexes and
  228. locks. This is why the POSIX.1 standard since the 1996 release requires
  229. that the child process after
  230. \fIfork\fR()
  231. in a multi-threaded process only calls async-signal-safe interfaces.
  232. .SH "FUTURE DIRECTIONS"
  233. The
  234. \fIpthread_atfork\fR()
  235. function may be formally deprecated (for example, by shading it OB) in
  236. a future version of this standard.
  237. .SH "SEE ALSO"
  238. .IR "\fIatexit\fR\^(\|)",
  239. .IR "\fIexec\fR\^",
  240. .IR "\fIfork\fR\^(\|)"
  241. .P
  242. The Base Definitions volume of POSIX.1\(hy2017,
  243. .IR "\fB<pthread.h>\fP",
  244. .IR "\fB<sys_types.h>\fP"
  245. .\"
  246. .SH COPYRIGHT
  247. Portions of this text are reprinted and reproduced in electronic form
  248. from IEEE Std 1003.1-2017, Standard for Information Technology
  249. -- Portable Operating System Interface (POSIX), The Open Group Base
  250. Specifications Issue 7, 2018 Edition,
  251. Copyright (C) 2018 by the Institute of
  252. Electrical and Electronics Engineers, Inc and The Open Group.
  253. In the event of any discrepancy between this version and the original IEEE and
  254. The Open Group Standard, the original IEEE and The Open Group Standard
  255. is the referee document. The original Standard can be obtained online at
  256. http://www.opengroup.org/unix/online.html .
  257. .PP
  258. Any typographical or formatting errors that appear
  259. in this page are most likely
  260. to have been introduced during the conversion of the source files to
  261. man page format. To report such errors, see
  262. https://www.kernel.org/doc/man-pages/reporting_bugs.html .