diff options
Diffstat (limited to 'man-pages-posix-2003/man3p/fork.3p')
| -rw-r--r-- | man-pages-posix-2003/man3p/fork.3p | 363 |
1 files changed, 363 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man3p/fork.3p b/man-pages-posix-2003/man3p/fork.3p new file mode 100644 index 0000000..647099d --- /dev/null +++ b/man-pages-posix-2003/man3p/fork.3p @@ -0,0 +1,363 @@ +.\" 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 . |