PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

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

PROLOG         top

       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.

NAME         top

       fork — create a new process

SYNOPSIS         top

       #include <unistd.h>

       pid_t fork(void);

DESCRIPTION         top

       The fork() 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 tms_utime, tms_stime, tms_cutime, and
           tms_cstime 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 alarm(3p).

        *  All semadj 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 mlockall()
           or mlock().

        *  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 fork() shall be visible to the child. Any
           modifications to the data in MAP_PRIVATE mappings made by the
           parent after fork() 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 fork() function. For other scheduling
           policies, the policy and priority settings on fork() 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 fork(), 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 exec
           functions is called. Fork handlers may be established by means of
           the pthread_atfork() function in order to maintain application
           invariants across fork() calls.

           When the application calls fork() from a signal handler and any
           of the fork handlers registered by pthread_atfork() 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 posix_trace_attr_setinherited()
           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 fork(), both the parent and the child processes shall be
       capable of executing independently before either one terminates.

RETURN VALUE         top

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

ERRORS         top

       The fork() function shall fail if:

       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.

       The fork() function may fail if:

       ENOMEM Insufficient storage space is available.

       The following sections are informative.

EXAMPLES         top

       None.

APPLICATION USAGE         top

       None.

RATIONALE         top

       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 fork() is delivered to the parent
       following the fork() but not to the child because the fork() 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 fork() call should
       appear atomic. A signal that is generated prior to the fork() should
       be delivered prior to the fork().  A signal sent to the process group
       after the fork() 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 fork().  Since the
       fork() 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 fork(); see also <signal.h>.

       One approach that has been suggested to address the problem of signal
       inheritance across fork() 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.

       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 fork()
       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.

       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.

       IEEE Std 1003.1‐1988 neglected to require concurrent execution of the
       parent and child of fork().  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 [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.

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

       The general problem with making fork() 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 fork().  This
       creates the difficulty that the state of process-local resources is
       usually held in process memory. If a thread that is not calling
       fork() 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 fork(), creating new threads in the same program, is
       provided by the pthread_create() function. The fork() function is
       thus used only to run new programs, and the effects of calling
       functions that require certain resources between the call to fork()
       and the call to an exec function are undefined.

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

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

       When forkall() 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, pthread_cond_wait() and pthread_cond_timedwait() 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].

FUTURE DIRECTIONS         top

       None.

SEE ALSO         top

       alarm(3p), exec(1p), fcntl(3p), posix_trace_attr_getinherited(3p),
       posix_trace_eventid_equal(3p), pthread_atfork(3p), semop(3p),
       signal(3p), times(3p)

       The Base Definitions volume of POSIX.1‐2008, Section 4.11, Memory
       Synchronization, sys_types.h(0p), unistd.h(0p)

COPYRIGHT         top

       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(3P)