mirror of https://github.com/mkerrisk/man-pages
359 lines
15 KiB
Plaintext
359 lines
15 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "FORK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" fork
|
|
.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 .
|