Changeset View
Changeset View
Standalone View
Standalone View
lib/libc/sys/fork.2
Show All 22 Lines | ||||||||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |||||||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |||||||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |||||||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | |||||||||
.\" | .\" | |||||||||
.\" @(#)fork.2 8.1 (Berkeley) 6/4/93 | .\" @(#)fork.2 8.1 (Berkeley) 6/4/93 | |||||||||
.\" $FreeBSD$ | .\" $FreeBSD$ | |||||||||
.\" | .\" | |||||||||
.Dd April 20, 2021 | .Dd August 2, 2021 | |||||||||
.Dt FORK 2 | .Dt FORK 2 | |||||||||
.Os | .Os | |||||||||
.Sh NAME | .Sh NAME | |||||||||
.Nm fork | .Nm fork | |||||||||
.Nd create a new process | .Nd create a new process | |||||||||
.Sh LIBRARY | .Sh LIBRARY | |||||||||
.Lb libc | .Lb libc | |||||||||
.Sh SYNOPSIS | .Sh SYNOPSIS | |||||||||
.In unistd.h | .In unistd.h | |||||||||
.Ft pid_t | .Ft pid_t | |||||||||
.Fn fork void | .Fn fork void | |||||||||
.Ft pid_t | ||||||||||
.Fn _Fork void | ||||||||||
.Sh DESCRIPTION | .Sh DESCRIPTION | |||||||||
The | The | |||||||||
.Fn fork | .Fn fork | |||||||||
system call causes creation of a new process. | function causes creation of a new process. | |||||||||
The new process (child process) is an exact copy of the | The new process (child process) is an exact copy of the | |||||||||
calling process (parent process) except for the following: | calling process (parent process) except for the following: | |||||||||
.Bl -bullet -offset indent | .Bl -bullet -offset indent | |||||||||
.It | .It | |||||||||
The child process has a unique process ID. | The child process has a unique process ID. | |||||||||
.It | .It | |||||||||
The child process has a different parent | The child process has a different parent | |||||||||
process ID (i.e., the process ID of the parent process). | process ID (i.e., the process ID of the parent process). | |||||||||
Show All 17 Lines | ||||||||||
.It | .It | |||||||||
The child process' resource utilizations | The child process' resource utilizations | |||||||||
are set to 0; see | are set to 0; see | |||||||||
.Xr setrlimit 2 . | .Xr setrlimit 2 . | |||||||||
.It | .It | |||||||||
All interval timers are cleared; see | All interval timers are cleared; see | |||||||||
.Xr setitimer 2 . | .Xr setitimer 2 . | |||||||||
.It | .It | |||||||||
Robust mutexes list (see | ||||||||||
markjUnsubmitted Done Inline Actions
markj: | ||||||||||
.Xr pthread_mutexattr_setrobust 3 ) | ||||||||||
is cleared for the child. | ||||||||||
.It | ||||||||||
The atfork handlers established with | ||||||||||
markjUnsubmitted Done Inline Actions
markj: | ||||||||||
.Xr pthread_atfork 3 | ||||||||||
function are called as appropriate before fork in the parent process, | ||||||||||
and after the child is created, in parent and child. | ||||||||||
.It | ||||||||||
The child process has only one thread, | The child process has only one thread, | |||||||||
corresponding to the calling thread in the parent process. | corresponding to the calling thread in the parent process. | |||||||||
If the process has more than one thread, | If the process has more than one thread, | |||||||||
locks and other resources held by the other threads are not released | locks and other resources held by the other threads are not released | |||||||||
and therefore only async-signal-safe functions | and therefore only async-signal-safe functions | |||||||||
(see | (see | |||||||||
.Xr sigaction 2 ) | .Xr sigaction 2 ) | |||||||||
are guaranteed to work in the child process until a call to | are guaranteed to work in the child process until a call to | |||||||||
.Xr execve 2 | .Xr execve 2 | |||||||||
or a similar function. | or a similar function. | |||||||||
.Fx | ||||||||||
markjUnsubmitted Done Inline Actions".Fx's implementation", or "The .Fx implementation" markj: ".Fx's implementation", or "The .Fx implementation" | ||||||||||
implementation of | ||||||||||
.Fn fork | ||||||||||
provides a usable | ||||||||||
.Xr malloc 3 | ||||||||||
and | ||||||||||
Done Inline Actions
markj: | ||||||||||
.Xr rtld 1 | ||||||||||
services in the child process. | ||||||||||
.El | .El | |||||||||
.Pp | ||||||||||
The | ||||||||||
.Fn fork | ||||||||||
function is not async-signal safe and creates a cancellation point | ||||||||||
in the parent process. | ||||||||||
It cannot be safely used from signal handlers, the atfork handlers | ||||||||||
markjUnsubmitted Done Inline Actions
markj: | ||||||||||
established by | ||||||||||
.Xr pthread_atfork 3 | ||||||||||
do not need to be async-signal safe either. | ||||||||||
.Pp | ||||||||||
The | ||||||||||
.Fn _Fork | ||||||||||
function creates a new process, similarly to | ||||||||||
.Fn fork , | ||||||||||
but it is async-signal safe. | ||||||||||
.Fn _Fork | ||||||||||
does not call atfork handlers, and does not create a cancellation point. | ||||||||||
It can be used safely from the signal handlers, but then no userspace | ||||||||||
markjUnsubmitted Done Inline Actions
markj: | ||||||||||
services ( | ||||||||||
.Xr malloc 3 | ||||||||||
or | ||||||||||
.Xr rtld 1 ) | ||||||||||
are available in the child. | ||||||||||
In particular, if using dynamic linking, all dynamic symbols used by the | ||||||||||
child after | ||||||||||
.Fn _Fork | ||||||||||
must be pre-resolved. | ||||||||||
markjUnsubmitted Done Inline ActionsDoes it effectively mean that LD_BIND_NOW must be set if the child performs cross-DSO calls? It might be worth explaining this a bit further. markj: Does it effectively mean that LD_BIND_NOW must be set if the child performs cross-DSO calls? It… | ||||||||||
.Sh RETURN VALUES | .Sh RETURN VALUES | |||||||||
Upon successful completion, | Upon successful completion, | |||||||||
.Fn fork | .Fn fork | |||||||||
Done Inline Actions
markj: | ||||||||||
returns a value | and | |||||||||
.Fn _Fork | ||||||||||
return a value | ||||||||||
of 0 to the child process and returns the process ID of the child | of 0 to the child process and returns the process ID of the child | |||||||||
process to the parent process. | process to the parent process. | |||||||||
Otherwise, a value of -1 is returned | Otherwise, a value of -1 is returned | |||||||||
to the parent process, no child process is created, and the global | to the parent process, no child process is created, and the global | |||||||||
variable | variable | |||||||||
.Va errno | .Va errno | |||||||||
is set to indicate the error. | is set to indicate the error. | |||||||||
.Sh EXAMPLES | .Sh EXAMPLES | |||||||||
▲ Show 20 Lines • Show All 68 Lines • ▼ Show 20 Lines | ||||||||||
.El | .El | |||||||||
.Sh SEE ALSO | .Sh SEE ALSO | |||||||||
.Xr execve 2 , | .Xr execve 2 , | |||||||||
.Xr rfork 2 , | .Xr rfork 2 , | |||||||||
.Xr setitimer 2 , | .Xr setitimer 2 , | |||||||||
.Xr setrlimit 2 , | .Xr setrlimit 2 , | |||||||||
.Xr sigaction 2 , | .Xr sigaction 2 , | |||||||||
.Xr vfork 2 , | .Xr vfork 2 , | |||||||||
.Xr wait 2 | .Xr wait 2 , | |||||||||
.Xr pthread_atfork 3 | ||||||||||
.Sh HISTORY | .Sh HISTORY | |||||||||
The | The | |||||||||
.Fn fork | .Fn fork | |||||||||
function appeared in | function appeared in | |||||||||
.At v1 . | .At v1 . | |||||||||
The | ||||||||||
.Fn _Fork | ||||||||||
function was defined by Austin Group together with dropping a requirement | ||||||||||
markjUnsubmitted Done Inline Actions
markj: | ||||||||||
that | ||||||||||
markjUnsubmitted Done Inline Actions
markj: | ||||||||||
.Fn fork | ||||||||||
implementation must be async-signal safe, and it appeared in | ||||||||||
.Fx 14.0 . |