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
11

NAME

13       fork — create a new process
14

SYNOPSIS

16       #include <unistd.h>
17
18       pid_t fork(void);
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
41           directory 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
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
79        *  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
85        *  Per-process timers created by the parent shall not be inherited  by
86           the child process.
87
88        *  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
93        *  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
97        *  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
107           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
111        *  If the Trace option and the Trace  Inherit  option  are  both  sup‐
112           ported:
113
114           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
124        *  If  the  Trace option is supported, but the Trace Inherit option is
125           not supported:
126
127           The child process shall not be traced into any of the trace streams
128           of its parent process.
129
130        *  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
134        *  The  initial value of the CPU-time clock of the child process shall
135           be set to zero.
136
137        *  The initial value of the CPU-time clock of the single thread of the
138           child process shall be set to zero.
139
140       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
145       After fork(), both the parent and the child processes shall be  capable
146       of executing independently before either one terminates.
147

RETURN VALUE

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

ERRORS

156       The fork() function shall fail if:
157
158       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
163       The fork() function may fail if:
164
165       ENOMEM Insufficient storage space is available.
166
167       The following sections are informative.
168

EXAMPLES

170       None.
171

APPLICATION USAGE

173       None.
174

RATIONALE

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
197       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
204       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
216       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
221       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
232       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
241       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
248       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
260       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
267       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
281       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
290       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

FUTURE DIRECTIONS

300       None.
301

SEE ALSO

303       alarm(),      exec,      fcntl(),      posix_trace_attr_getinherited(),
304       posix_trace_eventid_equal(),   pthread_atfork(),   semop(),   signal(),
305       times()
306
307       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
322       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 .
326
327
328
329IEEE/The Open Group                  2013                             FORK(3P)
Impressum