1FORK(3P)                   POSIX Programmer's Manual                  FORK(3P)
2
3
4

PROLOG

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

NAME

12       fork - create a new process
13

SYNOPSIS

15       #include <unistd.h>
16
17       pid_t fork(void);
18
19

DESCRIPTION

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
25        * The child process shall have a unique process ID.
26
27        * The child process ID also shall not match any active  process  group
28          ID.
29
30        * The  child  process  shall have a different parent process ID, which
31          shall be the process ID of the calling process.
32
33        * 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
38        * 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
43        * The child process shall have its own copy of  the  parent's  message
44          catalog descriptors.
45
46        * The  child  process' values of tms_utime, tms_stime, tms_cutime, and
47          tms_cstime shall be set to 0.
48
49        * 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
52        * All semadj values shall be cleared.
53
54        * File  locks  set by the parent process shall not be inherited by the
55          child process.
56
57        * The set of signals pending for the child process shall  be  initial‐
58          ized to the empty set.
59
60        * Interval timers shall be reset in the child process.
61
62        * Any  semaphores  that  are  open in the parent process shall also be
63          open in the child process.
64
65        * 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
69        * 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
78        * 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
83        * Per-process timers created by the parent shall not be  inherited  by
84          the child process.
85
86        * 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
91        * No asynchronous input or asynchronous  output  operations  shall  be
92          inherited by the child process.
93
94        * 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
104       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
108        * If the Trace option and the Trace Inherit option are both supported:
109
110       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
120        * If  the  Trace  option is supported, but the Trace Inherit option is
121          not supported:
122
123       The child process shall not be traced into any of the trace streams  of
124       its parent process.
125
126        * 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
130        * The  initial  value of the CPU-time clock of the child process shall
131          be set to zero.
132
133        * The initial value of the CPU-time clock of the single thread of  the
134          child process shall be set to zero.
135
136       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
141       After fork(), both the parent and the child processes shall be  capable
142       of executing independently before either one terminates.
143

RETURN VALUE

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

ERRORS

152       The fork() function shall fail if:
153
154       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
159
160       The fork() function may fail if:
161
162       ENOMEM Insufficient storage space is available.
163
164
165       The following sections are informative.
166

EXAMPLES

168       None.
169

APPLICATION USAGE

171       None.
172

RATIONALE

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
195       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
202       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
214       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
219       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
230       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
239       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
246       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
258       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
265       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
279       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
288       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

FUTURE DIRECTIONS

298       None.
299

SEE ALSO

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 .
316
317
318
319IEEE/The Open Group                  2003                             FORK(3P)
Impressum