.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "FORK" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" fork 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
fork \- create a new process
.SH SYNOPSIS
.LP
\fB#include <unistd.h>
.br
.sp
pid_t fork(void);
.br
\fP
.SH DESCRIPTION
.LP
The \fIfork\fP() function shall create a new process. The new process
(child process) shall be an exact copy of the calling
process (parent process) except as detailed below:
.IP " *" 3
The child process shall have a unique process ID.
.LP
.IP " *" 3
The child process ID also shall not match any active process group
ID.
.LP
.IP " *" 3
The child process shall have a different parent process ID, which
shall be the process ID of the calling process.
.LP
.IP " *" 3
The child process shall have its own copy of the parent's file descriptors.
Each of the child's file descriptors shall refer to
the same open file description with the corresponding file descriptor
of the parent.
.LP
.IP " *" 3
The child process shall have its own copy of the parent's open directory
streams. Each open directory stream in the child
process may share directory stream positioning with the corresponding
directory stream of the parent.
.LP
.IP " *" 3
The child process shall have its own copy of the parent's message
catalog descriptors. 
.LP
.IP " *" 3
The child process' values of \fItms_utime\fP, \fItms_stime\fP, \fItms_cutime\fP,
and \fItms_cstime\fP shall be set to 0.
.LP
.IP " *" 3
The time left until an alarm clock signal shall be reset to zero,
and the alarm, if any, shall be canceled; see \fIalarm\fP().
.LP
.IP " *" 3
All \fIsemadj\fP values shall be cleared. 
.LP
.IP " *" 3
File locks set by the parent process shall not be inherited by the
child process.
.LP
.IP " *" 3
The set of signals pending for the child process shall be initialized
to the empty set.
.LP
.IP " *" 3
Interval timers shall be reset in the child process. 
.LP
.IP " *" 3
Any semaphores that are open in the parent process shall also be open
in the child process. 
.LP
.IP " *" 3
The
child process shall not inherit any address space memory locks established
by the parent process via calls to \fImlockall\fP() or \fImlock\fP().
.LP
.IP " *" 3
Memory mappings created in the parent shall be retained in the child
process. MAP_PRIVATE mappings inherited from the parent shall
also be MAP_PRIVATE mappings in the child, and any modifications to
the data in these mappings made by the parent prior to calling
\fIfork\fP() shall be visible to the child. Any modifications to the
data in MAP_PRIVATE mappings made by the parent after
\fIfork\fP() returns shall be visible only to the parent. Modifications
to the data in MAP_PRIVATE mappings made by the child
shall be visible only to the child. 
.LP
.IP " *" 3
For
the SCHED_FIFO and SCHED_RR scheduling policies, the child process
shall inherit the policy and priority settings of the parent
process during a \fIfork\fP() function. For other scheduling policies,
the policy and priority settings on \fIfork\fP() are
implementation-defined. 
.LP
.IP " *" 3
Per-process timers created by the parent shall not be inherited by
the child process. 
.LP
.IP " *" 3
The child process shall have its own copy of the message queue descriptors
of the parent. Each of the message descriptors of the
child shall refer to the same open message queue description as the
corresponding message descriptor of the parent. 
.LP
.IP " *" 3
No asynchronous input or asynchronous output operations shall be inherited
by the child process. 
.LP
.IP " *" 3
A process shall be created with a single thread. If a multi-threaded
process calls \fIfork\fP(), the new process shall contain
a replica of the calling thread and its entire address space, possibly
including the states of mutexes and other resources.
Consequently, to avoid errors, the child process may only execute
async-signal-safe operations until such time as one of the \fIexec\fP
functions is called.  Fork handlers may be established by means
of the \fIpthread_atfork\fP() function in order to maintain application
invariants across
\fIfork\fP() calls. 
.LP
When the application calls \fIfork\fP() from a signal handler and
any of the fork handlers registered by \fIpthread_atfork\fP() calls
a function that is not asynch-signal-safe, the behavior is
undefined.
.LP
.IP " *" 3
If the Trace option and the Trace Inherit option are both supported:
.LP
If the calling process was being traced in a trace stream that had
its inheritance policy set to POSIX_TRACE_INHERITED, the
child process shall be traced into that trace stream, and the child
process shall inherit the parent's mapping of trace event names
to trace event type identifiers. If the trace stream in which the
calling process was being traced had its inheritance policy set
to POSIX_TRACE_CLOSE_FOR_CHILD, the child process shall not be traced
into that trace stream. The inheritance policy is set by a
call to the \fIposix_trace_attr_setinherited\fP() function. 
.LP
.IP " *" 3
If the Trace option is supported, but the Trace Inherit option is
not supported:
.LP
The child process shall not be traced into any of the trace streams
of its parent process. 
.LP
.IP " *" 3
If the Trace option is supported, the child process of a trace controller
process shall not control the trace streams controlled by
its parent process. 
.LP
.IP " *" 3
The initial value of the CPU-time clock of the child process shall
be set to zero. 
.LP
.IP " *" 3
The initial value of the CPU-time clock of the single thread of the
child process shall be set to zero. 
.LP
.LP
All other process characteristics defined by IEEE\ Std\ 1003.1-2001
shall be the same in the parent and child processes.
The inheritance of process characteristics not defined by IEEE\ Std\ 1003.1-2001
is unspecified by
IEEE\ Std\ 1003.1-2001.
.LP
After \fIfork\fP(), both the parent and the child processes shall
be capable of executing independently before either one
terminates.
.SH RETURN VALUE
.LP
Upon successful completion, \fIfork\fP() shall return 0 to the child
process and shall return the process ID of the child
process to the parent process. Both processes shall continue to execute
from the \fIfork\fP() function. Otherwise, -1 shall be
returned to the parent process, no child process shall be created,
and \fIerrno\fP shall be set to indicate the error.
.SH ERRORS
.LP
The \fIfork\fP() function shall fail if:
.TP 7
.B EAGAIN
The system lacked the necessary resources to create another process,
or the system-imposed limit on the total number of
processes under execution system-wide or by a single user {CHILD_MAX}
would be exceeded.
.sp
.LP
The \fIfork\fP() function may fail if:
.TP 7
.B ENOMEM
Insufficient storage space is available.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
Many historical implementations have timing windows where a signal
sent to a process group (for example, an interactive SIGINT)
just prior to or during execution of \fIfork\fP() is delivered to
the parent following the \fIfork\fP() but not to the child
because the \fIfork\fP() code clears the child's set of pending signals.
This volume of IEEE\ Std\ 1003.1-2001 does not
require, or even permit, this behavior. However, it is pragmatic to
expect that problems of this nature may continue to exist in
implementations that appear to conform to this volume of IEEE\ Std\ 1003.1-2001
and pass available verification suites.
This behavior is only a consequence of the implementation failing
to make the interval between signal generation and delivery
totally invisible. From the application's perspective, a \fIfork\fP()
call should appear atomic. A signal that is generated prior
to the \fIfork\fP() should be delivered prior to the \fIfork\fP().
A signal sent to the process group after the \fIfork\fP()
should be delivered to both parent and child. The implementation may
actually initialize internal data structures corresponding to
the child's set of pending signals to include signals sent to the
process group during the \fIfork\fP(). Since the \fIfork\fP()
call can be considered as atomic from the application's perspective,
the set would be initialized as empty and such signals would
have arrived after the \fIfork\fP(); see also \fI<signal.h>\fP.
.LP
One approach that has been suggested to address the problem of signal
inheritance across \fIfork\fP() is to add an [EINTR]
error, which would be returned when a signal is detected during the
call. While this is preferable to losing signals, it was not
considered an optimal solution. Although it is not recommended for
this purpose, such an error would be an allowable extension for
an implementation.
.LP
The [ENOMEM] error value is reserved for those implementations that
detect and distinguish such a condition. This condition
occurs when an implementation detects that there is not enough memory
to create the process. This is intended to be returned when
[EAGAIN] is inappropriate because there can never be enough memory
(either primary or secondary storage) to perform the operation.
Since \fIfork\fP() duplicates an existing process, this must be a
condition where there is sufficient memory for one such process,
but not for two. Many historical implementations actually return [ENOMEM]
due to temporary lack of memory, a case that is not
generally distinct from [EAGAIN] from the perspective of a conforming
application.
.LP
Part of the reason for including the optional error [ENOMEM] is because
the SVID specifies it and it should be reserved for the
error condition specified there. The condition is not applicable on
many implementations.
.LP
IEEE\ Std\ 1003.1-1988 neglected to require concurrent execution of
the parent and child of \fIfork\fP(). A system that
single-threads processes was clearly not intended and is considered
an unacceptable "toy implementation" of this volume of
IEEE\ Std\ 1003.1-2001. The only objection anticipated to the phrase
"executing independently" is testability, but this
assertion should be testable. Such tests require that both the parent
and child can block on a detectable action of the other, such
as a write to a pipe or a signal. An interactive exchange of such
actions should be possible for the system to conform to the
intent of this volume of IEEE\ Std\ 1003.1-2001.
.LP
The [EAGAIN] error exists to warn applications that such a condition
might occur. Whether it occurs or not is not in any
practical sense under the control of the application because the condition
is usually a consequence of the user's use of the
system, not of the application's code. Thus, no application can or
should rely upon its occurrence under any circumstances, nor
should the exact semantics of what concept of "user" is used be of
concern to the application writer. Validation writers should
be cognizant of this limitation.
.LP
There are two reasons why POSIX programmers call \fIfork\fP(). One
reason is to create a new thread of control within the same
program (which was originally only possible in POSIX by creating a
new process); the other is to create a new process running a
different program. In the latter case, the call to \fIfork\fP() is
soon followed by a call to one of the \fIexec\fP functions.
.LP
The general problem with making \fIfork\fP() work in a multi-threaded
world is what to do with all of the threads. There are
two alternatives. One is to copy all of the threads into the new process.
This causes the programmer or implementation to deal with
threads that are suspended on system calls or that might be about
to execute system calls that should not be executed in the new
process. The other alternative is to copy only the thread that calls
\fIfork\fP(). This creates the difficulty that the state of
process-local resources is usually held in process memory. If a thread
that is not calling \fIfork\fP() holds a resource, that
resource is never released in the child process because the thread
whose job it is to release the resource does not exist in the
child process.
.LP
When a programmer is writing a multi-threaded program, the first described
use of \fIfork\fP(), creating new threads in the
same program, is provided by the \fIpthread_create\fP() function.
The \fIfork\fP()
function is thus used only to run new programs, and the effects of
calling functions that require certain resources between the
call to \fIfork\fP() and the call to an \fIexec\fP function are undefined.
.LP
The addition of the \fIforkall\fP() function to the standard was considered
and rejected. The \fIforkall\fP() function lets
all the threads in the parent be duplicated in the child. This essentially
duplicates the state of the parent in the child. This
allows threads in the child to continue processing and allows locks
and the state to be preserved without explicit \fIpthread_atfork\fP()
code. The calling process has to ensure that the threads processing
state that is shared between the parent and child (that is, file descriptors
or MAP_SHARED memory) behaves properly after
\fIforkall\fP(). For example, if a thread is reading a file descriptor
in the parent when \fIforkall\fP() is called, then two
threads (one in the parent and one in the child) are reading the file
descriptor after the \fIforkall\fP(). If this is not desired
behavior, the parent process has to synchronize with such threads
before calling \fIforkall\fP().
.LP
While the \fIfork\fP() function is async-signal-safe, there is no
way for an implementation to determine whether the fork
handlers established by \fIpthread_atfork\fP() are async-signal-safe.
The fork
handlers may attempt to execute portions of the implementation that
are not async-signal-safe, such as those that are protected by
mutexes, leading to a deadlock condition. It is therefore undefined
for the fork handlers to execute functions that are not
async-signal-safe when \fIfork\fP() is called from a signal handler.
.LP
When \fIforkall\fP() is called, threads, other than the calling thread,
that are in functions that can return with an [EINTR]
error may have those functions return [EINTR] if the implementation
cannot ensure that the function behaves correctly in the parent
and child. In particular, \fIpthread_cond_wait\fP() and \fIpthread_cond_timedwait\fP()
need to return in order to ensure that the condition
has not changed. These functions can be awakened by a spurious condition
wakeup rather than returning [EINTR].
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIalarm\fP(), \fIexec\fP(), \fIfcntl\fP(), \fIposix_trace_attr_getinherited\fP(),
\fIposix_trace_trid_eventid_open\fP(), \fIpthread_atfork\fP(),
\fIsemop\fP(), \fIsignal\fP(), \fItimes\fP(), the Base Definitions
volume of
IEEE\ Std\ 1003.1-2001, \fI<sys/types.h>\fP, \fI<unistd.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .