FORK(3)                    POSIX Programmer's Manual                   FORK(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       fork -- create a new process

SSYYNNOOPPSSIISS
       #include <unistd.h>

       pid_t fork(void);

DDEESSCCRRIIPPTTIIOONN
       The _f_o_r_k() 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:

        *  The child process shall have a unique process ID.

        *  The child process ID also shall not match any active process group
           ID.

        *  The child process shall have a different parent process ID, which
           shall be the process ID of the calling process.

        *  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.

        *  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.

        *  The child process shall have its own copy of the parent's message
           catalog descriptors.

        *  The child process values of _t_m_s___u_t_i_m_e, _t_m_s___s_t_i_m_e, _t_m_s___c_u_t_i_m_e, and
           _t_m_s___c_s_t_i_m_e shall be set to 0.

        *  The time left until an alarm clock signal shall be reset to zero,
           and the alarm, if any, shall be canceled; see _a_l_a_r_m().

        *  All _s_e_m_a_d_j values shall be cleared.

        *  File locks set by the parent process shall not be inherited by the
           child process.

        *  The set of signals pending for the child process shall be
           initialized to the empty set.

        *  Interval timers shall be reset in the child process.

        *  Any semaphores that are open in the parent process shall also be
           open in the child process.

        *  The child process shall not inherit any address space memory locks
           established by the parent process via calls to _m_l_o_c_k_a_l_l() or
           _m_l_o_c_k().

        *  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
           _f_o_r_k() shall be visible to the child. Any modifications to the data
           in MAP_PRIVATE mappings made by the parent after _f_o_r_k() 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.

        *  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 _f_o_r_k() function. For other scheduling
           policies, the policy and priority settings on _f_o_r_k() are
           implementation-defined.

        *  Per-process timers created by the parent shall not be inherited by
           the child process.

        *  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.

        *  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.

        *  A process shall be created with a single thread. If a multi-
           threaded process calls _f_o_r_k(), 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 _e_x_e_c
           functions is called. Fork handlers may be established by means of
           the _p_t_h_r_e_a_d___a_t_f_o_r_k() function in order to maintain application
           invariants across _f_o_r_k() calls.

           When the application calls _f_o_r_k() from a signal handler and any of
           the fork handlers registered by _p_t_h_r_e_a_d___a_t_f_o_r_k() calls a function
           that is not async-signal-safe, the behavior is undefined.

        *  If the Trace option and the Trace Inherit option are both
           supported:

           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 _p_o_s_i_x___t_r_a_c_e___a_t_t_r___s_e_t_i_n_h_e_r_i_t_e_d() function.

        *  If the Trace option is supported, but the Trace Inherit option is
           not supported:

           The child process shall not be traced into any of the trace streams
           of its parent process.

        *  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.

        *  The initial value of the CPU-time clock of the child process shall
           be set to zero.

        *  The initial value of the CPU-time clock of the single thread of the
           child process shall be set to zero.

       All other process characteristics defined by POSIX.1-2008 shall be the
       same in the parent and child processes. The inheritance of process
       characteristics not defined by POSIX.1-2008 is unspecified by
       POSIX.1-2008.

       After _f_o_r_k(), both the parent and the child processes shall be capable
       of executing independently before either one terminates.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, _f_o_r_k() 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 _f_o_r_k()
       function. Otherwise, -1 shall be returned to the parent process, no
       child process shall be created, and _e_r_r_n_o shall be set to indicate the
       error.

EERRRROORRSS
       The _f_o_r_k() function shall fail if:

       EEAAGGAAIINN 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.

       The _f_o_r_k() function may fail if:

       EENNOOMMEEMM Insufficient storage space is available.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       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 _f_o_r_k() is delivered to the parent following the
       _f_o_r_k() but not to the child because the _f_o_r_k() code clears the child's
       set of pending signals. This volume of POSIX.1-2008 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-2008 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
       _f_o_r_k() call should appear atomic. A signal that is generated prior to
       the _f_o_r_k() should be delivered prior to the _f_o_r_k().  A signal sent to
       the process group after the _f_o_r_k() 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 _f_o_r_k().  Since the
       _f_o_r_k() 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 _f_o_r_k(); see also _<_s_i_g_n_a_l_._h_>.

       One approach that has been suggested to address the problem of signal
       inheritance across _f_o_r_k() is to add an [[EEIINNTTRR]] 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.

       The [[EENNOOMMEEMM]] 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 [[EEAAGGAAIINN]] is inappropriate
       because there can never be enough memory (either primary or secondary
       storage) to perform the operation. Since _f_o_r_k() 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 [[EENNOOMMEEMM]] due to temporary lack of memory, a case that
       is not generally distinct from [[EEAAGGAAIINN]] from the perspective of a
       conforming application.

       Part of the reason for including the optional error [[EENNOOMMEEMM]] 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.

       IEEE Std 1003.1-1988 neglected to require concurrent execution of the
       parent and child of _f_o_r_k().  A system that single-threads processes was
       clearly not intended and is considered an unacceptable ``toy
       implementation'' of this volume of POSIX.1-2008.  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-2008.

       The [[EEAAGGAAIINN]] 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.

       There are two reasons why POSIX programmers call _f_o_r_k().  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 _f_o_r_k() is soon followed by a call to one of the _e_x_e_c
       functions.

       The general problem with making _f_o_r_k() 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 _f_o_r_k().  This creates the difficulty that
       the state of process-local resources is usually held in process memory.
       If a thread that is not calling _f_o_r_k() 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.

       When a programmer is writing a multi-threaded program, the first
       described use of _f_o_r_k(), creating new threads in the same program, is
       provided by the _p_t_h_r_e_a_d___c_r_e_a_t_e() function. The _f_o_r_k() function is thus
       used only to run new programs, and the effects of calling functions
       that require certain resources between the call to _f_o_r_k() and the call
       to an _e_x_e_c function are undefined.

       The addition of the _f_o_r_k_a_l_l() function to the standard was considered
       and rejected. The _f_o_r_k_a_l_l() 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 _p_t_h_r_e_a_d___a_t_f_o_r_k() 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 _f_o_r_k_a_l_l().  For example, if a thread is reading a file descriptor
       in the parent when _f_o_r_k_a_l_l() is called, then two threads (one in the
       parent and one in the child) are reading the file descriptor after the
       _f_o_r_k_a_l_l().  If this is not desired behavior, the parent process has to
       synchronize with such threads before calling _f_o_r_k_a_l_l().

       While the _f_o_r_k() function is async-signal-safe, there is no way for an
       implementation to determine whether the fork handlers established by
       _p_t_h_r_e_a_d___a_t_f_o_r_k() 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 _f_o_r_k() is called
       from a signal handler.

       When _f_o_r_k_a_l_l() is called, threads, other than the calling thread, that
       are in functions that can return with an [[EEIINNTTRR]] error may have those
       functions return [[EEIINNTTRR]] if the implementation cannot ensure that the
       function behaves correctly in the parent and child. In particular,
       _p_t_h_r_e_a_d___c_o_n_d___w_a_i_t() and _p_t_h_r_e_a_d___c_o_n_d___t_i_m_e_d_w_a_i_t() 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
       [[EEIINNTTRR]].

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _a_l_a_r_m(), _e_x_e_c, _f_c_n_t_l(), _p_o_s_i_x___t_r_a_c_e___a_t_t_r___g_e_t_i_n_h_e_r_i_t_e_d(),
       _p_o_s_i_x___t_r_a_c_e___e_v_e_n_t_i_d___e_q_u_a_l(), _p_t_h_r_e_a_d___a_t_f_o_r_k(), _s_e_m_o_p(), _s_i_g_n_a_l(),
       _t_i_m_e_s()

       The Base Definitions volume of POSIX.1-2008, _S_e_c_t_i_o_n _4_._1_1, _M_e_m_o_r_y
       _S_y_n_c_h_r_o_n_i_z_a_t_i_o_n, <<ssyyss__ttyyppeess..hh>>, <<uunniissttdd..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       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 .



IEEE/The Open Group                  2013                              FORK(3)
