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

fork.3p (15779B)


  1. '\" et
  2. .TH FORK "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. fork
  12. \(em create a new process
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <unistd.h>
  17. .P
  18. pid_t fork(void);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIfork\fR()
  23. function shall create a new process. The new process (child process)
  24. shall be an exact copy of the calling process (parent process) except
  25. as detailed below:
  26. .IP " *" 4
  27. The child process shall have a unique process ID.
  28. .IP " *" 4
  29. The child process ID also shall not match any active process group ID.
  30. .IP " *" 4
  31. The child process shall have a different parent process ID, which shall
  32. be the process ID of the calling process.
  33. .IP " *" 4
  34. The child process shall have its own copy of the parent's file
  35. descriptors. Each of the child's file descriptors shall refer to the
  36. same open file description with the corresponding file descriptor of
  37. the parent.
  38. .IP " *" 4
  39. The child process shall have its own copy of the parent's open directory
  40. streams. Each open directory stream in the child process may share
  41. directory stream positioning with the corresponding directory stream of
  42. the parent.
  43. .IP " *" 4
  44. The child process shall have its own copy of the parent's message
  45. catalog descriptors.
  46. .IP " *" 4
  47. The child process values of
  48. .IR tms_utime ,
  49. .IR tms_stime ,
  50. .IR tms_cutime ,
  51. and
  52. .IR tms_cstime
  53. shall be set to 0.
  54. .IP " *" 4
  55. The time left until an alarm clock signal shall be reset to zero, and
  56. the alarm, if any, shall be canceled; see
  57. .IR "\fIalarm\fR\^(\|)".
  58. .IP " *" 4
  59. All
  60. .IR semadj
  61. values shall be cleared.
  62. .IP " *" 4
  63. File locks set by the parent process shall not be inherited by the
  64. child process.
  65. .IP " *" 4
  66. The set of signals pending for the child process shall be initialized
  67. to the empty set.
  68. .IP " *" 4
  69. Interval timers shall be reset in the child process.
  70. .IP " *" 4
  71. Any semaphores that are open in the parent process shall also be open
  72. in the child process.
  73. .IP " *" 4
  74. The child process shall not inherit any address space memory locks
  75. established by the parent process via calls to
  76. \fImlockall\fR()
  77. or
  78. \fImlock\fR().
  79. .IP " *" 4
  80. Memory mappings created in the parent shall be retained in the child
  81. process. MAP_PRIVATE mappings inherited from the parent shall also be
  82. MAP_PRIVATE mappings in the child, and any modifications to the data in
  83. these mappings made by the parent prior to calling
  84. \fIfork\fR()
  85. shall be visible to the child. Any modifications to the data in
  86. MAP_PRIVATE mappings made by the parent after
  87. \fIfork\fR()
  88. returns shall be visible only to the parent. Modifications to the data
  89. in MAP_PRIVATE mappings made by the child shall be visible only to the
  90. child.
  91. .IP " *" 4
  92. For the SCHED_FIFO and SCHED_RR scheduling policies,
  93. the child process shall inherit the policy and priority settings of the
  94. parent process during a
  95. \fIfork\fR()
  96. function. For other scheduling policies, the policy and priority
  97. settings on
  98. \fIfork\fR()
  99. are implementation-defined.
  100. .IP " *" 4
  101. Per-process timers created by the parent shall not be inherited by
  102. the child process.
  103. .IP " *" 4
  104. The child process shall have its own copy of the message queue
  105. descriptors of the parent. Each of the message descriptors of the child
  106. shall refer to the same open message queue description as the
  107. corresponding message descriptor of the parent.
  108. .IP " *" 4
  109. No asynchronous input or asynchronous output operations shall be
  110. inherited by the child process. Any use of asynchronous control blocks
  111. created by the parent produces undefined behavior.
  112. .IP " *" 4
  113. A process shall be created with a single thread. If a multi-threaded
  114. process calls
  115. \fIfork\fR(),
  116. the new process shall contain a replica of the calling thread and its
  117. entire address space, possibly including the states of mutexes and
  118. other resources. Consequently, to avoid errors, the child process may
  119. only execute async-signal-safe operations until such time as one of the
  120. .IR exec
  121. functions is called.
  122. .RS 4
  123. .P
  124. When the application calls
  125. \fIfork\fR()
  126. from a signal handler and any of the fork handlers registered by
  127. \fIpthread_atfork\fR()
  128. calls a function that is not async-signal-safe, the behavior is
  129. undefined.
  130. .RE
  131. .IP " *" 4
  132. If the Trace option and the Trace Inherit option are both supported:
  133. .RS 4
  134. .P
  135. If the calling process was being traced in a trace stream that had its
  136. inheritance policy set to POSIX_TRACE_INHERITED, the child process shall
  137. be traced into that trace stream, and the child process shall inherit
  138. the parent's mapping of trace event names to trace event type
  139. identifiers. If the trace stream in which the calling process was being
  140. traced had its inheritance policy set to POSIX_TRACE_CLOSE_FOR_CHILD,
  141. the child process shall not be traced into that trace stream. The
  142. inheritance policy is set by a call to the
  143. \fIposix_trace_attr_setinherited\fR()
  144. function.
  145. .RE
  146. .IP " *" 4
  147. If the Trace option is supported, but the Trace Inherit option is not
  148. supported:
  149. .RS 4
  150. .P
  151. The child process shall not be traced into any of the trace streams
  152. of its parent process.
  153. .RE
  154. .IP " *" 4
  155. If the Trace option is supported, the child process of a trace
  156. controller process shall not control the trace streams controlled by
  157. its parent process.
  158. .IP " *" 4
  159. The initial value of the CPU-time clock of the child process shall be
  160. set to zero.
  161. .IP " *" 4
  162. The initial value of the CPU-time clock of the single thread of the
  163. child process shall be set to zero.
  164. .P
  165. All other process characteristics defined by POSIX.1\(hy2008 shall be the same in
  166. the parent and child processes. The inheritance of process
  167. characteristics not defined by POSIX.1\(hy2008 is unspecified by POSIX.1\(hy2008.
  168. .P
  169. After
  170. \fIfork\fR(),
  171. both the parent and the child processes shall be capable of executing
  172. independently before either one terminates.
  173. .SH "RETURN VALUE"
  174. Upon successful completion,
  175. \fIfork\fR()
  176. shall return 0 to the child process and shall return the process ID
  177. of the child process to the parent process. Both processes shall
  178. continue to execute from the
  179. \fIfork\fR()
  180. function. Otherwise, \-1 shall be
  181. returned to the parent process, no child process shall be created, and
  182. .IR errno
  183. shall be set to indicate the error.
  184. .SH ERRORS
  185. The
  186. \fIfork\fR()
  187. function shall fail if:
  188. .TP
  189. .BR EAGAIN
  190. The system lacked the necessary resources to create another process, or
  191. the system-imposed limit on the total number of processes under
  192. execution system-wide or by a single user
  193. {CHILD_MAX}
  194. would be exceeded.
  195. .br
  196. .P
  197. The
  198. \fIfork\fR()
  199. function may fail if:
  200. .TP
  201. .BR ENOMEM
  202. Insufficient storage space is available.
  203. .LP
  204. .IR "The following sections are informative."
  205. .SH EXAMPLES
  206. None.
  207. .SH "APPLICATION USAGE"
  208. None.
  209. .SH RATIONALE
  210. Many historical implementations have timing windows where a signal sent
  211. to a process group (for example, an interactive SIGINT)
  212. just prior to or during execution of
  213. \fIfork\fR()
  214. is delivered to the parent following the
  215. \fIfork\fR()
  216. but not to the child because the
  217. \fIfork\fR()
  218. code clears the child's set of pending signals. This volume of POSIX.1\(hy2017 does not require,
  219. or even permit, this behavior. However, it is pragmatic to expect that
  220. problems of this nature may continue to exist in implementations that
  221. appear to conform to this volume of POSIX.1\(hy2017 and pass available verification suites. This
  222. behavior is only a consequence of the implementation failing to make
  223. the interval between signal generation and delivery totally invisible.
  224. From the application's perspective, a
  225. \fIfork\fR()
  226. call should appear atomic. A signal that is generated prior to the
  227. \fIfork\fR()
  228. should be delivered prior to the
  229. \fIfork\fR().
  230. A signal sent to the process group after the
  231. \fIfork\fR()
  232. should be delivered to both parent and child. The implementation may
  233. actually initialize internal data structures corresponding to the
  234. child's set of pending signals to include signals sent to the process
  235. group during the
  236. \fIfork\fR().
  237. Since the
  238. \fIfork\fR()
  239. call can be considered as atomic from the application's perspective,
  240. the set would be initialized as empty and such signals would have
  241. arrived after the
  242. \fIfork\fR();
  243. see also
  244. .IR <signal.h> .
  245. .P
  246. One approach that has been suggested to address the problem of signal
  247. inheritance across
  248. \fIfork\fR()
  249. is to add an
  250. .BR [EINTR]
  251. error, which would be returned when a signal is detected during the
  252. call. While this is preferable to losing signals, it was not
  253. considered an optimal solution. Although it is not recommended for
  254. this purpose, such an error would be an allowable extension for an
  255. implementation.
  256. .P
  257. The
  258. .BR [ENOMEM]
  259. error value is reserved for those implementations that detect and
  260. distinguish such a condition. This condition occurs when an
  261. implementation detects that there is not enough memory to create the
  262. process. This is intended to be returned when
  263. .BR [EAGAIN]
  264. is inappropriate because there can never be enough memory (either
  265. primary or secondary storage) to perform the operation. Since
  266. \fIfork\fR()
  267. duplicates an existing process, this must be a condition where there is
  268. sufficient memory for one such process, but not for two. Many
  269. historical implementations actually return
  270. .BR [ENOMEM]
  271. due to temporary lack of memory, a case that is not generally distinct
  272. from
  273. .BR [EAGAIN]
  274. from the perspective of a conforming application.
  275. .P
  276. Part of the reason for including the optional error
  277. .BR [ENOMEM]
  278. is because the SVID specifies it and it should be reserved for the
  279. error condition specified there. The condition is not applicable on
  280. many implementations.
  281. .P
  282. IEEE\ Std\ 1003.1\(hy1988 neglected to require concurrent execution of the parent and child
  283. of
  284. \fIfork\fR().
  285. A system that single-threads processes was clearly not intended and is
  286. considered an unacceptable ``toy implementation'' of this volume of POSIX.1\(hy2017.
  287. The only objection anticipated to the phrase ``executing
  288. independently'' is testability, but this assertion should be testable.
  289. Such tests require that both the parent and child can block on a
  290. detectable action of the other, such as a write to a pipe or a signal.
  291. An interactive exchange of such actions should be possible for the
  292. system to conform to the intent of this volume of POSIX.1\(hy2017.
  293. .P
  294. The
  295. .BR [EAGAIN]
  296. error exists to warn applications that such a condition might occur.
  297. Whether it occurs or not is not in any practical sense under the
  298. control of the application because the condition is usually a
  299. consequence of the user's use of the system, not of the application's
  300. code. Thus, no application can or should rely upon its occurrence
  301. under any circumstances, nor should the exact semantics of what concept
  302. of ``user'' is used be of concern to the application developer.
  303. Validation writers should be cognizant of this limitation.
  304. .P
  305. There are two reasons why POSIX programmers call
  306. \fIfork\fR().
  307. One reason is to create a new thread of control within the same program
  308. (which was originally only possible in POSIX by creating a new
  309. process); the other is to create a new process running a different
  310. program. In the latter case, the call to
  311. \fIfork\fR()
  312. is soon followed by a call to one of the
  313. .IR exec
  314. functions.
  315. .P
  316. The general problem with making
  317. \fIfork\fR()
  318. work in a multi-threaded world is what to do with all of the threads.
  319. There are two alternatives. One is to copy all of the threads into the
  320. new process. This causes the programmer or implementation to deal with
  321. threads that are suspended on system calls or that might be about to
  322. execute system calls that should not be executed in the new process.
  323. The other alternative is to copy only the thread that calls
  324. \fIfork\fR().
  325. This creates the difficulty that the state of process-local resources
  326. is usually held in process memory. If a thread that is not calling
  327. \fIfork\fR()
  328. holds a resource, that resource is never released in the child process
  329. because the thread whose job it is to release the resource does not
  330. exist in the child process.
  331. .P
  332. When a programmer is writing a multi-threaded program, the first
  333. described use of
  334. \fIfork\fR(),
  335. creating new threads in the same program, is provided by the
  336. \fIpthread_create\fR()
  337. function. The
  338. \fIfork\fR()
  339. function is thus used only to run new programs, and the effects of
  340. calling functions that require certain resources between the call to
  341. \fIfork\fR()
  342. and the call to an
  343. .IR exec
  344. function are undefined.
  345. .P
  346. The addition of the
  347. \fIforkall\fR()
  348. function to the standard was considered and rejected. The
  349. \fIforkall\fR()
  350. function lets all the threads in the parent be duplicated in the
  351. child. This essentially duplicates the state of the parent in the
  352. child. This allows threads in the child to continue processing and
  353. allows locks and the state to be preserved without explicit
  354. \fIpthread_atfork\fR()
  355. code. The calling process has to ensure that the threads processing
  356. state that is shared between the parent and child (that is, file
  357. descriptors or MAP_SHARED
  358. memory) behaves properly after
  359. \fIforkall\fR().
  360. For example, if a thread is reading a file descriptor in the parent
  361. when
  362. \fIforkall\fR()
  363. is called, then two threads (one in the parent and one in the child)
  364. are reading the file descriptor after the
  365. \fIforkall\fR().
  366. If this is not desired behavior, the parent process has to synchronize
  367. with such threads before calling
  368. \fIforkall\fR().
  369. .P
  370. While the
  371. \fIfork\fR()
  372. function is async-signal-safe, there is no way for an implementation to
  373. determine whether the fork handlers established by
  374. \fIpthread_atfork\fR()
  375. are async-signal-safe. The fork handlers may attempt to execute
  376. portions of the implementation that are not async-signal-safe, such as
  377. those that are protected by mutexes, leading to a deadlock condition.
  378. It is therefore undefined for the fork handlers to execute functions
  379. that are not async-signal-safe when
  380. \fIfork\fR()
  381. is called from a signal handler.
  382. .P
  383. When
  384. \fIforkall\fR()
  385. is called, threads, other than the calling thread, that are in
  386. functions that can return with an
  387. .BR [EINTR]
  388. error may have those functions return
  389. .BR [EINTR]
  390. if the implementation cannot ensure that the function behaves correctly
  391. in the parent and child. In particular,
  392. \fIpthread_cond_wait\fR()
  393. and
  394. \fIpthread_cond_timedwait\fR()
  395. need to return in order to ensure that the condition has not changed.
  396. These functions can be awakened by a spurious condition wakeup rather
  397. than returning
  398. .BR [EINTR] .
  399. .SH "FUTURE DIRECTIONS"
  400. None.
  401. .SH "SEE ALSO"
  402. .IR "\fIalarm\fR\^(\|)",
  403. .IR "\fIexec\fR\^",
  404. .IR "\fIfcntl\fR\^(\|)",
  405. .IR "\fIposix_trace_attr_getinherited\fR\^(\|)",
  406. .IR "\fIposix_trace_eventid_equal\fR\^(\|)",
  407. .IR "\fIpthread_atfork\fR\^(\|)",
  408. .IR "\fIsemop\fR\^(\|)",
  409. .IR "\fIsignal\fR\^(\|)",
  410. .IR "\fItimes\fR\^(\|)"
  411. .P
  412. The Base Definitions volume of POSIX.1\(hy2017,
  413. .IR "Section 4.12" ", " "Memory Synchronization",
  414. .IR "\fB<sys_types.h>\fP",
  415. .IR "\fB<unistd.h>\fP"
  416. .\"
  417. .SH COPYRIGHT
  418. Portions of this text are reprinted and reproduced in electronic form
  419. from IEEE Std 1003.1-2017, Standard for Information Technology
  420. -- Portable Operating System Interface (POSIX), The Open Group Base
  421. Specifications Issue 7, 2018 Edition,
  422. Copyright (C) 2018 by the Institute of
  423. Electrical and Electronics Engineers, Inc and The Open Group.
  424. In the event of any discrepancy between this version and the original IEEE and
  425. The Open Group Standard, the original IEEE and The Open Group Standard
  426. is the referee document. The original Standard can be obtained online at
  427. http://www.opengroup.org/unix/online.html .
  428. .PP
  429. Any typographical or formatting errors that appear
  430. in this page are most likely
  431. to have been introduced during the conversion of the source files to
  432. man page format. To report such errors, see
  433. https://www.kernel.org/doc/man-pages/reporting_bugs.html .