1.\" $OpenBSD: fork.2,v 1.18 2015/09/10 17:55:21 schwarze Exp $ 2.\" $NetBSD: fork.2,v 1.6 1995/02/27 12:32:36 cgd Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)fork.2 8.1 (Berkeley) 6/4/93 32.\" 33.Dd $Mdocdate: September 10 2015 $ 34.Dt FORK 2 35.Os 36.Sh NAME 37.Nm fork 38.Nd create a new process 39.Sh SYNOPSIS 40.In unistd.h 41.Ft pid_t 42.Fn fork void 43.Sh DESCRIPTION 44.Fn fork 45causes creation of a new process. 46The new process (child process) is an exact copy of the 47calling process (parent process) except for the following: 48.Bl -bullet -offset indent 49.It 50The child process has a unique process ID, 51which also does not match any existing process group ID. 52.It 53The child process has a different parent 54process ID (i.e., the process ID of the parent process). 55.It 56The child process has a single thread. 57.It 58The child process has its own copy of the parent's descriptors. 59These descriptors reference the same underlying objects, so that, 60for instance, file pointers in file objects are shared between 61the child and the parent, so that an 62.Xr lseek 2 63on a descriptor in the child process can affect a subsequent 64.Xr read 2 65or 66.Xr write 2 67by the parent. 68This descriptor copying is also used by the shell to 69establish standard input and output for newly created processes 70as well as to set up pipes. 71.It 72The child process has no 73.Xr fcntl 2 Ns -style 74file locks. 75.It 76The child process' resource utilizations 77are set to 0; see 78.Xr getrusage 2 . 79.It 80All interval timers are cleared; see 81.Xr setitimer 2 . 82.It 83The child process' semaphore undo values are set to 0; see 84.Xr semop 2 . 85.It 86The child process' pending signals set is empty. 87.It 88The child process has no memory locks; see 89.Xr mlock 2 90and 91.Xr mlockall 2 . 92.El 93.Pp 94In general, the child process should call 95.Xr _exit 2 96rather than 97.Xr exit 3 . 98Otherwise, any stdio buffers that exist both in the parent and child 99will be flushed twice. 100Similarly, 101.Xr _exit 2 102should be used to prevent 103.Xr atexit 3 104routines from being called twice (once in the parent and once in the child). 105.Sh RETURN VALUES 106Upon successful completion, 107.Fn fork 108returns a value 109of 0 to the child process and returns the process ID of the child 110process to the parent process. 111Otherwise, a value of \-1 is returned to the parent process, 112no child process is created, and the global variable 113.Va errno 114is set to indicate the error. 115.Sh ERRORS 116.Fn fork 117will fail and no child process will be created if: 118.Bl -tag -width [EAGAIN] 119.It Bq Er EAGAIN 120The system-imposed limits on the total 121number of processes or total number of threads 122under execution would be exceeded. 123These limits are configuration dependent. 124.It Bq Er EAGAIN 125The limit 126.Dv RLIMIT_NPROC 127on the total number of processes under execution by the user ID 128would be exceeded. 129.It Bq Er ENOMEM 130There is insufficient swap space for the new process. 131.El 132.Sh SEE ALSO 133.Xr execve 2 , 134.Xr getrusage 2 , 135.Xr wait 2 136.Sh STANDARDS 137The 138.Fn fork 139function conforms to 140.St -p1003.1-2008 . 141.Sh HISTORY 142The 143.Fn fork 144system call first appeared in 145.At v1 . 146