path: root/upstream/archlinux/man3p/fork.3p

'\" et
.TH FORK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.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
\(em create a new process
.SH SYNOPSIS
.LP
.nf
#include <unistd.h>
.P
pid_t fork(void);
.fi
.SH DESCRIPTION
The
\fIfork\fR()
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 " *" 4
The child process shall have a unique process ID.
.IP " *" 4
The child process ID also shall not match any active process group ID.
.IP " *" 4
The child process shall have a different parent process ID, which shall
be the process ID of the calling process.
.IP " *" 4
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.
.IP " *" 4
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.
.IP " *" 4
The child process shall have its own copy of the parent's message
catalog descriptors.
.IP " *" 4
The child process values of
.IR tms_utime ,
.IR tms_stime ,
.IR tms_cutime ,
and
.IR tms_cstime
shall be set to 0.
.IP " *" 4
The time left until an alarm clock signal shall be reset to zero, and
the alarm, if any, shall be canceled; see
.IR "\fIalarm\fR\^(\|)".
.IP " *" 4
All
.IR semadj
values shall be cleared.
.IP " *" 4
File locks set by the parent process shall not be inherited by the
child process.
.IP " *" 4
The set of signals pending for the child process shall be initialized
to the empty set.
.IP " *" 4
Interval timers shall be reset in the child process.
.IP " *" 4
Any semaphores that are open in the parent process shall also be open
in the child process.
.IP " *" 4
The child process shall not inherit any address space memory locks
established by the parent process via calls to
\fImlockall\fR()
or
\fImlock\fR().
.IP " *" 4
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\fR()
shall be visible to the child. Any modifications to the data in
MAP_PRIVATE mappings made by the parent after
\fIfork\fR()
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.
.IP " *" 4
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\fR()
function. For other scheduling policies, the policy and priority
settings on
\fIfork\fR()
are implementation-defined.
.IP " *" 4
Per-process timers created by the parent shall not be inherited by
the child process.
.IP " *" 4
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.
.IP " *" 4
No asynchronous input or asynchronous output operations shall be
inherited by the child process. Any use of asynchronous control blocks
created by the parent produces undefined behavior.
.IP " *" 4
A process shall be created with a single thread. If a multi-threaded
process calls
\fIfork\fR(),
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
.IR exec
functions is called.
.RS 4 
.P
When the application calls
\fIfork\fR()
from a signal handler and any of the fork handlers registered by
\fIpthread_atfork\fR()
calls a function that is not async-signal-safe, the behavior is
undefined.
.RE
.IP " *" 4
If the Trace option and the Trace Inherit option are both supported:
.RS 4 
.P
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\fR()
function.
.RE
.IP " *" 4
If the Trace option is supported, but the Trace Inherit option is not
supported:
.RS 4 
.P
The child process shall not be traced into any of the trace streams
of its parent process.
.RE
.IP " *" 4
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.
.IP " *" 4
The initial value of the CPU-time clock of the child process shall be
set to zero.
.IP " *" 4
The initial value of the CPU-time clock of the single thread of the
child process shall be set to zero.
.P
All other process characteristics defined by POSIX.1\(hy2008 shall be the same in
the parent and child processes. The inheritance of process
characteristics not defined by POSIX.1\(hy2008 is unspecified by POSIX.1\(hy2008.
.P
After
\fIfork\fR(),
both the parent and the child processes shall be capable of executing
independently before either one terminates.
.SH "RETURN VALUE"
Upon successful completion,
\fIfork\fR()
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\fR()
function. Otherwise, \-1 shall be
returned to the parent process, no child process shall be created, and
.IR errno
shall be set to indicate the error.
.SH ERRORS
The
\fIfork\fR()
function shall fail if:
.TP
.BR 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.
.br
.P
The
\fIfork\fR()
function may fail if:
.TP
.BR ENOMEM
Insufficient storage space is available.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
None.
.SH "APPLICATION USAGE"
None.
.SH RATIONALE
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\fR()
is delivered to the parent following the
\fIfork\fR()
but not to the child because the
\fIfork\fR()
code clears the child's set of pending signals. This volume of POSIX.1\(hy2017 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 POSIX.1\(hy2017 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\fR()
call should appear atomic. A signal that is generated prior to the
\fIfork\fR()
should be delivered prior to the
\fIfork\fR().
A signal sent to the process group after the
\fIfork\fR()
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\fR().
Since the
\fIfork\fR()
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\fR();
see also
.IR <signal.h> .
.P
One approach that has been suggested to address the problem of signal
inheritance across
\fIfork\fR()
is to add an
.BR [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.
.P
The
.BR [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
.BR [EAGAIN] 
is inappropriate because there can never be enough memory (either
primary or secondary storage) to perform the operation. Since
\fIfork\fR()
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
.BR [ENOMEM] 
due to temporary lack of memory, a case that is not generally distinct
from
.BR [EAGAIN] 
from the perspective of a conforming application.
.P
Part of the reason for including the optional error
.BR [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.
.P
IEEE\ Std\ 1003.1\(hy1988 neglected to require concurrent execution of the parent and child
of
\fIfork\fR().
A system that single-threads processes was clearly not intended and is
considered an unacceptable ``toy implementation'' of this volume of POSIX.1\(hy2017.
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 POSIX.1\(hy2017.
.P
The
.BR [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 developer.
Validation writers should be cognizant of this limitation.
.P
There are two reasons why POSIX programmers call
\fIfork\fR().
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\fR()
is soon followed by a call to one of the
.IR exec
functions.
.P
The general problem with making
\fIfork\fR()
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\fR().
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\fR()
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.
.P
When a programmer is writing a multi-threaded program, the first
described use of
\fIfork\fR(),
creating new threads in the same program, is provided by the
\fIpthread_create\fR()
function. The
\fIfork\fR()
function is thus used only to run new programs, and the effects of
calling functions that require certain resources between the call to
\fIfork\fR()
and the call to an
.IR exec
function are undefined.
.P
The addition of the
\fIforkall\fR()
function to the standard was considered and rejected. The
\fIforkall\fR()
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\fR()
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\fR().
For example, if a thread is reading a file descriptor in the parent
when
\fIforkall\fR()
is called, then two threads (one in the parent and one in the child)
are reading the file descriptor after the
\fIforkall\fR().
If this is not desired behavior, the parent process has to synchronize
with such threads before calling
\fIforkall\fR().
.P
While the
\fIfork\fR()
function is async-signal-safe, there is no way for an implementation to
determine whether the fork handlers established by
\fIpthread_atfork\fR()
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\fR()
is called from a signal handler.
.P
When
\fIforkall\fR()
is called, threads, other than the calling thread, that are in
functions that can return with an
.BR [EINTR] 
error may have those functions return
.BR [EINTR] 
if the implementation cannot ensure that the function behaves correctly
in the parent and child. In particular,
\fIpthread_cond_wait\fR()
and
\fIpthread_cond_timedwait\fR()
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
.BR [EINTR] .
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIalarm\fR\^(\|)",
.IR "\fIexec\fR\^",
.IR "\fIfcntl\fR\^(\|)",
.IR "\fIposix_trace_attr_getinherited\fR\^(\|)",
.IR "\fIposix_trace_eventid_equal\fR\^(\|)",
.IR "\fIpthread_atfork\fR\^(\|)",
.IR "\fIsemop\fR\^(\|)",
.IR "\fIsignal\fR\^(\|)",
.IR "\fItimes\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 4.12" ", " "Memory Synchronization",
.IR "\fB<sys_types.h>\fP",
.IR "\fB<unistd.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 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 .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .