1FORK(3P) POSIX Programmer's Manual FORK(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 fork — create a new process
14
16 #include <unistd.h>
17 pid_t fork(void);
19
21 The fork() function shall create a new process. The new process (child
22 process) shall be an exact copy of the calling process (parent process)
23 except as detailed below:
24 * The child process shall have a unique process ID.
26 * The child process ID also shall not match any active process group
28 ID.
29 * The child process shall have a different parent process ID, which
31 shall be the process ID of the calling process.
32 * The child process shall have its own copy of the parent's file
34 descriptors. Each of the child's file descriptors shall refer to
35 the same open file description with the corresponding file descrip‐
36 tor of the parent.
37 * The child process shall have its own copy of the parent's open
39 directory streams. Each open directory stream in the child process
40 may share directory stream positioning with the corresponding
41 directory stream of the parent.
42 * The child process shall have its own copy of the parent's message
44 catalog descriptors.
45 * The child process values of tms_utime, tms_stime, tms_cutime, and
47 tms_cstime shall be set to 0.
48 * The time left until an alarm clock signal shall be reset to zero,
50 and the alarm, if any, shall be canceled; see alarm().
51 * All semadj values shall be cleared.
53 * File locks set by the parent process shall not be inherited by the
55 child process.
56 * The set of signals pending for the child process shall be initial‐
58 ized to the empty set.
59 * Interval timers shall be reset in the child process.
61 * Any semaphores that are open in the parent process shall also be
63 open in the child process.
64 * The child process shall not inherit any address space memory locks
66 established by the parent process via calls to mlockall() or
67 mlock().
68 * Memory mappings created in the parent shall be retained in the
70 child process. MAP_PRIVATE mappings inherited from the parent shall
71 also be MAP_PRIVATE mappings in the child, and any modifications to
72 the data in these mappings made by the parent prior to calling
73 fork() shall be visible to the child. Any modifications to the data
74 in MAP_PRIVATE mappings made by the parent after fork() returns
75 shall be visible only to the parent. Modifications to the data in
76 MAP_PRIVATE mappings made by the child shall be visible only to the
77 child.
78 * For the SCHED_FIFO and SCHED_RR scheduling policies, the child
80 process shall inherit the policy and priority settings of the par‐
81 ent process during a fork() function. For other scheduling poli‐
82 cies, the policy and priority settings on fork() are implementa‐
83 tion-defined.
84 * Per-process timers created by the parent shall not be inherited by
86 the child process.
87 * The child process shall have its own copy of the message queue
89 descriptors of the parent. Each of the message descriptors of the
90 child shall refer to the same open message queue description as the
91 corresponding message descriptor of the parent.
92 * No asynchronous input or asynchronous output operations shall be
94 inherited by the child process. Any use of asynchronous control
95 blocks created by the parent produces undefined behavior.
96 * A process shall be created with a single thread. If a multi-
98 threaded process calls fork(), the new process shall contain a
99 replica of the calling thread and its entire address space, possi‐
100 bly including the states of mutexes and other resources. Conse‐
101 quently, to avoid errors, the child process may only execute async-
102 signal-safe operations until such time as one of the exec functions
103 is called. Fork handlers may be established by means of the
104 pthread_atfork() function in order to maintain application invari‐
105 ants across fork() calls.
106 When the application calls fork() from a signal handler and any of
108 the fork handlers registered by pthread_atfork() calls a function
109 that is not async-signal-safe, the behavior is undefined.
110 * If the Trace option and the Trace Inherit option are both sup‐
112 ported:
113 If the calling process was being traced in a trace stream that had
115 its inheritance policy set to POSIX_TRACE_INHERITED, the child
116 process shall be traced into that trace stream, and the child
117 process shall inherit the parent's mapping of trace event names to
118 trace event type identifiers. If the trace stream in which the
119 calling process was being traced had its inheritance policy set to
120 POSIX_TRACE_CLOSE_FOR_CHILD, the child process shall not be traced
121 into that trace stream. The inheritance policy is set by a call to
122 the posix_trace_attr_setinherited() function.
123 * If the Trace option is supported, but the Trace Inherit option is
125 not supported:
126 The child process shall not be traced into any of the trace streams
128 of its parent process.
129 * If the Trace option is supported, the child process of a trace con‐
131 troller process shall not control the trace streams controlled by
132 its parent process.
133 * The initial value of the CPU-time clock of the child process shall
135 be set to zero.
136 * The initial value of the CPU-time clock of the single thread of the
138 child process shall be set to zero.
139 All other process characteristics defined by POSIX.1‐2008 shall be the
141 same in the parent and child processes. The inheritance of process
142 characteristics not defined by POSIX.1‐2008 is unspecified by
143 POSIX.1‐2008.
144 After fork(), both the parent and the child processes shall be capable
146 of executing independently before either one terminates.
147
149 Upon successful completion, fork() shall return 0 to the child process
150 and shall return the process ID of the child process to the parent
151 process. Both processes shall continue to execute from the fork() func‐
152 tion. Otherwise, −1 shall be returned to the parent process, no child
153 process shall be created, and errno shall be set to indicate the error.
154
156 The fork() function shall fail if:
157 EAGAIN The system lacked the necessary resources to create another
159 process, or the system-imposed limit on the total number of pro‐
160 cesses under execution system-wide or by a single user
161 {CHILD_MAX} would be exceeded.
162 The fork() function may fail if:
164 ENOMEM Insufficient storage space is available.
166 The following sections are informative.
168
170 None.
171
173 None.
174
176 Many historical implementations have timing windows where a signal sent
177 to a process group (for example, an interactive SIGINT) just prior to
178 or during execution of fork() is delivered to the parent following the
179 fork() but not to the child because the fork() code clears the child's
180 set of pending signals. This volume of POSIX.1‐2008 does not require,
181 or even permit, this behavior. However, it is pragmatic to expect that
182 problems of this nature may continue to exist in implementations that
183 appear to conform to this volume of POSIX.1‐2008 and pass available
184 verification suites. This behavior is only a consequence of the imple‐
185 mentation failing to make the interval between signal generation and
186 delivery totally invisible. From the application's perspective, a
187 fork() call should appear atomic. A signal that is generated prior to
188 the fork() should be delivered prior to the fork(). A signal sent to
189 the process group after the fork() should be delivered to both parent
190 and child. The implementation may actually initialize internal data
191 structures corresponding to the child's set of pending signals to
192 include signals sent to the process group during the fork(). Since the
193 fork() call can be considered as atomic from the application's perspec‐
194 tive, the set would be initialized as empty and such signals would have
195 arrived after the fork(); see also <signal.h>.
196 One approach that has been suggested to address the problem of signal
198 inheritance across fork() is to add an [EINTR] error, which would be
199 returned when a signal is detected during the call. While this is
200 preferable to losing signals, it was not considered an optimal solu‐
201 tion. Although it is not recommended for this purpose, such an error
202 would be an allowable extension for an implementation.
203 The [ENOMEM] error value is reserved for those implementations that
205 detect and distinguish such a condition. This condition occurs when an
206 implementation detects that there is not enough memory to create the
207 process. This is intended to be returned when [EAGAIN] is inappropriate
208 because there can never be enough memory (either primary or secondary
209 storage) to perform the operation. Since fork() duplicates an existing
210 process, this must be a condition where there is sufficient memory for
211 one such process, but not for two. Many historical implementations
212 actually return [ENOMEM] due to temporary lack of memory, a case that
213 is not generally distinct from [EAGAIN] from the perspective of a con‐
214 forming application.
215 Part of the reason for including the optional error [ENOMEM] is because
217 the SVID specifies it and it should be reserved for the error condition
218 specified there. The condition is not applicable on many implementa‐
219 tions.
220 IEEE Std 1003.1‐1988 neglected to require concurrent execution of the
222 parent and child of fork(). A system that single-threads processes was
223 clearly not intended and is considered an unacceptable ``toy implemen‐
224 tation'' of this volume of POSIX.1‐2008. The only objection antici‐
225 pated to the phrase ``executing independently'' is testability, but
226 this assertion should be testable. Such tests require that both the
227 parent and child can block on a detectable action of the other, such as
228 a write to a pipe or a signal. An interactive exchange of such actions
229 should be possible for the system to conform to the intent of this vol‐
230 ume of POSIX.1‐2008.
231 The [EAGAIN] error exists to warn applications that such a condition
233 might occur. Whether it occurs or not is not in any practical sense
234 under the control of the application because the condition is usually a
235 consequence of the user's use of the system, not of the application's
236 code. Thus, no application can or should rely upon its occurrence under
237 any circumstances, nor should the exact semantics of what concept of
238 ``user'' is used be of concern to the application developer. Valida‐
239 tion writers should be cognizant of this limitation.
240 There are two reasons why POSIX programmers call fork(). One reason is
242 to create a new thread of control within the same program (which was
243 originally only possible in POSIX by creating a new process); the other
244 is to create a new process running a different program. In the latter
245 case, the call to fork() is soon followed by a call to one of the exec
246 functions.
247 The general problem with making fork() work in a multi-threaded world
249 is what to do with all of the threads. There are two alternatives. One
250 is to copy all of the threads into the new process. This causes the
251 programmer or implementation to deal with threads that are suspended on
252 system calls or that might be about to execute system calls that should
253 not be executed in the new process. The other alternative is to copy
254 only the thread that calls fork(). This creates the difficulty that
255 the state of process-local resources is usually held in process memory.
256 If a thread that is not calling fork() holds a resource, that resource
257 is never released in the child process because the thread whose job it
258 is to release the resource does not exist in the child process.
259 When a programmer is writing a multi-threaded program, the first
261 described use of fork(), creating new threads in the same program, is
262 provided by the pthread_create() function. The fork() function is thus
263 used only to run new programs, and the effects of calling functions
264 that require certain resources between the call to fork() and the call
265 to an exec function are undefined.
266 The addition of the forkall() function to the standard was considered
268 and rejected. The forkall() function lets all the threads in the parent
269 be duplicated in the child. This essentially duplicates the state of
270 the parent in the child. This allows threads in the child to continue
271 processing and allows locks and the state to be preserved without
272 explicit pthread_atfork() code. The calling process has to ensure that
273 the threads processing state that is shared between the parent and
274 child (that is, file descriptors or MAP_SHARED memory) behaves properly
275 after forkall(). For example, if a thread is reading a file descriptor
276 in the parent when forkall() is called, then two threads (one in the
277 parent and one in the child) are reading the file descriptor after the
278 forkall(). If this is not desired behavior, the parent process has to
279 synchronize with such threads before calling forkall().
280 While the fork() function is async-signal-safe, there is no way for an
282 implementation to determine whether the fork handlers established by
283 pthread_atfork() are async-signal-safe. The fork handlers may attempt
284 to execute portions of the implementation that are not async-signal-
285 safe, such as those that are protected by mutexes, leading to a dead‐
286 lock condition. It is therefore undefined for the fork handlers to
287 execute functions that are not async-signal-safe when fork() is called
288 from a signal handler.
289 When forkall() is called, threads, other than the calling thread, that
291 are in functions that can return with an [EINTR] error may have those
292 functions return [EINTR] if the implementation cannot ensure that the
293 function behaves correctly in the parent and child. In particular,
294 pthread_cond_wait() and pthread_cond_timedwait() need to return in
295 order to ensure that the condition has not changed. These functions
296 can be awakened by a spurious condition wakeup rather than returning
297 [EINTR].
298
300 None.
301
303 alarm(), exec, fcntl(), posix_trace_attr_getinherited(),
304 posix_trace_eventid_equal(), pthread_atfork(), semop(), signal(),
305 times()
306 The Base Definitions volume of POSIX.1‐2008, Section 4.11, Memory Syn‐
308 chronization, <sys_types.h>, <unistd.h>
309
311 Portions of this text are reprinted and reproduced in electronic form
312 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
313 -- Portable Operating System Interface (POSIX), The Open Group Base
314 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
315 cal and Electronics Engineers, Inc and The Open Group. (This is
316 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
317 event of any discrepancy between this version and the original IEEE and
318 The Open Group Standard, the original IEEE and The Open Group Standard
319 is the referee document. The original Standard can be obtained online
320 at http://www.unix.org/online.html .
321 Any typographical or formatting errors that appear in this page are
323 most likely to have been introduced during the conversion of the source
324 files to man page format. To report such errors, see https://www.ker‐
325 nel.org/doc/man-pages/reporting_bugs.html .
326IEEE/The Open Group 2013 FORK(3P)