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
12 fork - create a new process
13
15 #include <unistd.h>
16 pid_t fork(void);
18
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 direc‐
41 tory 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 child
70 process. MAP_PRIVATE mappings inherited from the parent shall also
71 be MAP_PRIVATE mappings in the child, and any modifications to the
72 data in these mappings made by the parent prior to calling fork()
73 shall be visible to the child. Any modifications to the data in
74 MAP_PRIVATE mappings made by the parent after fork() returns shall
75 be visible only to the parent. Modifications to the data in MAP_PRI‐
76 VATE mappings made by the child shall be visible only to the child.
77 * For the SCHED_FIFO and SCHED_RR scheduling policies, the child
79 process shall inherit the policy and priority settings of the parent
80 process during a fork() function. For other scheduling policies, the
81 policy and priority settings on fork() are implementation-defined.
82 * Per-process timers created by the parent shall not be inherited by
84 the child process.
85 * The child process shall have its own copy of the message queue
87 descriptors of the parent. Each of the message descriptors of the
88 child shall refer to the same open message queue description as the
89 corresponding message descriptor of the parent.
90 * No asynchronous input or asynchronous output operations shall be
92 inherited by the child process.
93 * A process shall be created with a single thread. If a multi-threaded
95 process calls fork(), the new process shall contain a replica of the
96 calling thread and its entire address space, possibly including the
97 states of mutexes and other resources. Consequently, to avoid
98 errors, the child process may only execute async-signal-safe opera‐
99 tions until such time as one of the exec functions is called. Fork
100 handlers may be established by means of the pthread_atfork() func‐
101 tion in order to maintain application invariants across fork()
102 calls.
103 When the application calls fork() from a signal handler and any of the
105 fork handlers registered by pthread_atfork() calls a function that is
106 not asynch-signal-safe, the behavior is undefined.
107 * If the Trace option and the Trace Inherit option are both supported:
109 If the calling process was being traced in a trace stream that had its
111 inheritance policy set to POSIX_TRACE_INHERITED, the child process
112 shall be traced into that trace stream, and the child process shall
113 inherit the parent's mapping of trace event names to trace event type
114 identifiers. If the trace stream in which the calling process was being
115 traced had its inheritance policy set to POSIX_TRACE_CLOSE_FOR_CHILD,
116 the child process shall not be traced into that trace stream. The
117 inheritance policy is set by a call to the posix_trace_attr_setinher‐
118 ited() function.
119 * If the Trace option is supported, but the Trace Inherit option is
121 not supported:
122 The child process shall not be traced into any of the trace streams of
124 its parent process.
125 * If the Trace option is supported, the child process of a trace con‐
127 troller process shall not control the trace streams controlled by
128 its parent process.
129 * The initial value of the CPU-time clock of the child process shall
131 be set to zero.
132 * The initial value of the CPU-time clock of the single thread of the
134 child process shall be set to zero.
135 All other process characteristics defined by IEEE Std 1003.1-2001 shall
137 be the same in the parent and child processes. The inheritance of
138 process characteristics not defined by IEEE Std 1003.1-2001 is unspeci‐
139 fied by IEEE Std 1003.1-2001.
140 After fork(), both the parent and the child processes shall be capable
142 of executing independently before either one terminates.
143
145 Upon successful completion, fork() shall return 0 to the child process
146 and shall return the process ID of the child process to the parent
147 process. Both processes shall continue to execute from the fork() func‐
148 tion. Otherwise, -1 shall be returned to the parent process, no child
149 process shall be created, and errno shall be set to indicate the error.
150
152 The fork() function shall fail if:
153 EAGAIN The system lacked the necessary resources to create another
155 process, or the system-imposed limit on the total number of pro‐
156 cesses under execution system-wide or by a single user
157 {CHILD_MAX} would be exceeded.
158 The fork() function may fail if:
161 ENOMEM Insufficient storage space is available.
163 The following sections are informative.
166
168 None.
169
171 None.
172
174 Many historical implementations have timing windows where a signal sent
175 to a process group (for example, an interactive SIGINT) just prior to
176 or during execution of fork() is delivered to the parent following the
177 fork() but not to the child because the fork() code clears the child's
178 set of pending signals. This volume of IEEE Std 1003.1-2001 does not
179 require, or even permit, this behavior. However, it is pragmatic to
180 expect that problems of this nature may continue to exist in implemen‐
181 tations that appear to conform to this volume of IEEE Std 1003.1-2001
182 and pass available verification suites. This behavior is only a conse‐
183 quence of the implementation failing to make the interval between sig‐
184 nal generation and delivery totally invisible. From the application's
185 perspective, a fork() call should appear atomic. A signal that is gen‐
186 erated prior to the fork() should be delivered prior to the fork(). A
187 signal sent to the process group after the fork() should be delivered
188 to both parent and child. The implementation may actually initialize
189 internal data structures corresponding to the child's set of pending
190 signals to include signals sent to the process group during the fork().
191 Since the fork() call can be considered as atomic from the applica‐
192 tion's perspective, the set would be initialized as empty and such sig‐
193 nals would have arrived after the fork(); see also <signal.h>.
194 One approach that has been suggested to address the problem of signal
196 inheritance across fork() is to add an [EINTR] error, which would be
197 returned when a signal is detected during the call. While this is
198 preferable to losing signals, it was not considered an optimal solu‐
199 tion. Although it is not recommended for this purpose, such an error
200 would be an allowable extension for an implementation.
201 The [ENOMEM] error value is reserved for those implementations that
203 detect and distinguish such a condition. This condition occurs when an
204 implementation detects that there is not enough memory to create the
205 process. This is intended to be returned when [EAGAIN] is inappropriate
206 because there can never be enough memory (either primary or secondary
207 storage) to perform the operation. Since fork() duplicates an existing
208 process, this must be a condition where there is sufficient memory for
209 one such process, but not for two. Many historical implementations
210 actually return [ENOMEM] due to temporary lack of memory, a case that
211 is not generally distinct from [EAGAIN] from the perspective of a con‐
212 forming application.
213 Part of the reason for including the optional error [ENOMEM] is because
215 the SVID specifies it and it should be reserved for the error condition
216 specified there. The condition is not applicable on many implementa‐
217 tions.
218 IEEE Std 1003.1-1988 neglected to require concurrent execution of the
220 parent and child of fork(). A system that single-threads processes was
221 clearly not intended and is considered an unacceptable "toy implementa‐
222 tion" of this volume of IEEE Std 1003.1-2001. The only objection antic‐
223 ipated to the phrase "executing independently" is testability, but this
224 assertion should be testable. Such tests require that both the parent
225 and child can block on a detectable action of the other, such as a
226 write to a pipe or a signal. An interactive exchange of such actions
227 should be possible for the system to conform to the intent of this vol‐
228 ume of IEEE Std 1003.1-2001.
229 The [EAGAIN] error exists to warn applications that such a condition
231 might occur. Whether it occurs or not is not in any practical sense
232 under the control of the application because the condition is usually a
233 consequence of the user's use of the system, not of the application's
234 code. Thus, no application can or should rely upon its occurrence under
235 any circumstances, nor should the exact semantics of what concept of
236 "user" is used be of concern to the application writer. Validation
237 writers should be cognizant of this limitation.
238 There are two reasons why POSIX programmers call fork(). One reason is
240 to create a new thread of control within the same program (which was
241 originally only possible in POSIX by creating a new process); the other
242 is to create a new process running a different program. In the latter
243 case, the call to fork() is soon followed by a call to one of the exec
244 functions.
245 The general problem with making fork() work in a multi-threaded world
247 is what to do with all of the threads. There are two alternatives. One
248 is to copy all of the threads into the new process. This causes the
249 programmer or implementation to deal with threads that are suspended on
250 system calls or that might be about to execute system calls that should
251 not be executed in the new process. The other alternative is to copy
252 only the thread that calls fork(). This creates the difficulty that the
253 state of process-local resources is usually held in process memory. If
254 a thread that is not calling fork() holds a resource, that resource is
255 never released in the child process because the thread whose job it is
256 to release the resource does not exist in the child process.
257 When a programmer is writing a multi-threaded program, the first
259 described use of fork(), creating new threads in the same program, is
260 provided by the pthread_create() function. The fork() function is thus
261 used only to run new programs, and the effects of calling functions
262 that require certain resources between the call to fork() and the call
263 to an exec function are undefined.
264 The addition of the forkall() function to the standard was considered
266 and rejected. The forkall() function lets all the threads in the parent
267 be duplicated in the child. This essentially duplicates the state of
268 the parent in the child. This allows threads in the child to continue
269 processing and allows locks and the state to be preserved without
270 explicit pthread_atfork() code. The calling process has to ensure that
271 the threads processing state that is shared between the parent and
272 child (that is, file descriptors or MAP_SHARED memory) behaves properly
273 after forkall(). For example, if a thread is reading a file descriptor
274 in the parent when forkall() is called, then two threads (one in the
275 parent and one in the child) are reading the file descriptor after the
276 forkall(). If this is not desired behavior, the parent process has to
277 synchronize with such threads before calling forkall().
278 While the fork() function is async-signal-safe, there is no way for an
280 implementation to determine whether the fork handlers established by
281 pthread_atfork() are async-signal-safe. The fork handlers may attempt
282 to execute portions of the implementation that are not async-signal-
283 safe, such as those that are protected by mutexes, leading to a dead‐
284 lock condition. It is therefore undefined for the fork handlers to exe‐
285 cute functions that are not async-signal-safe when fork() is called
286 from a signal handler.
287 When forkall() is called, threads, other than the calling thread, that
289 are in functions that can return with an [EINTR] error may have those
290 functions return [EINTR] if the implementation cannot ensure that the
291 function behaves correctly in the parent and child. In particular,
292 pthread_cond_wait() and pthread_cond_timedwait() need to return in
293 order to ensure that the condition has not changed. These functions can
294 be awakened by a spurious condition wakeup rather than returning
295 [EINTR].
296
298 None.
299
301 alarm(), exec(), fcntl(), posix_trace_attr_getinherited(),
302 posix_trace_trid_eventid_open(), pthread_atfork(), semop(), signal(),
303 times(), the Base Definitions volume of IEEE Std 1003.1-2001,
304 <sys/types.h>, <unistd.h>
305
307 Portions of this text are reprinted and reproduced in electronic form
308 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
309 -- Portable Operating System Interface (POSIX), The Open Group Base
310 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
311 Electrical and Electronics Engineers, Inc and The Open Group. In the
312 event of any discrepancy between this version and the original IEEE and
313 The Open Group Standard, the original IEEE and The Open Group Standard
314 is the referee document. The original Standard can be obtained online
315 at http://www.opengroup.org/unix/online.html .
316IEEE/The Open Group 2003 FORK(3P)