1.\" $OpenBSD: fork1.9,v 1.12 2009/07/28 12:27:03 jmc Exp $ 2.\" $NetBSD: fork1.9,v 1.3 1999/03/16 00:40:47 garbled Exp $ 3.\" 4.\" Copyright (c) 1998 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, 9.\" NASA Ames Research Center. 10.\" 11.\" Redistribution and use in source and binary forms, with or without 12.\" modification, are permitted provided that the following conditions 13.\" are met: 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in the 18.\" documentation and/or other materials provided with the distribution. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 22.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 24.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 25.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 26.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 28.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 29.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 30.\" POSSIBILITY OF SUCH DAMAGE. 31.\" 32.Dd $Mdocdate: July 28 2009 $ 33.Dt FORK1 9 34.Os 35.Sh NAME 36.Nm fork1 37.Nd create a new process 38.Sh SYNOPSIS 39.Fd #include <sys/types.h> 40.Fd #include <sys/proc.h> 41.Ft int 42.Fo "fork1" 43.Fa "struct proc *p1" 44.Fa "int exitsig" 45.Fa "int flags" 46.Fa "void *stack" 47.Fa "size_t stacksize" 48.Fa "void (*func)(void *)" 49.Fa "void *arg" 50.Fa "register_t *retval" 51.Fa "struct proc **rnewprocp" 52.Fc 53.Sh DESCRIPTION 54.Fn fork1 55creates a new process out of 56.Ar p1 , 57which should be the current process. 58This function is used primarily to implement the 59.Xr fork 2 , 60.Xr rfork 2 , 61.Xr vfork 2 62system calls, as well as the 63.Xr kthread_create 9 64function. 65.Pp 66The 67.Ar flags 68argument is used to control the behavior of the fork and is created by 69a bitwise-OR of the following values: 70.Bl -tag -width FORK_SHAREFILES 71.It Dv FORK_FORK 72The call is done by the 73.Xr fork 2 74system call. 75Used only for statistics. 76.It Dv FORK_VFORK 77The call is done by the 78.Xr vfork 2 79system call. 80Used only for statistics. 81.It Dv FORK_RFORK 82The call is done by the 83.Xr rfork 2 84system call. 85Used only for statistics. 86.It Dv FORK_PPWAIT 87Suspend the parent process until the child is terminated (by calling 88.Xr _exit 2 89or abnormally), or makes a call to 90.Xr execve 2 . 91.It Dv FORK_SHAREFILES 92Let the child share the file descriptor table with the parent through 93fdshare(). 94The default behavior is to copy the table through 95fdcopy(). 96.It Dv FORK_CLEANFILES 97The child starts with a clean file descriptor table created by 98fdinit(). 99.It Dv FORK_NOZOMBIE 100The child will be dissociated from the parent and will not leave a status 101for the parent to collect. 102See 103.Xr wait 2 . 104.It Dv FORK_SHAREVM 105The child will share the parent's address space. 106The default behavior is 107that the child gets a copy-on-write copy of the address space. 108.El 109.Pp 110If 111.Fa stack 112is not 113.Dv NULL , 114the area starting at 115.Fa stack 116of extent 117.Fa stacksize 118will be used for the child's stack, instead of cloning the parent's 119stack. 120.Pp 121If 122.Fa retval 123is not 124.Dv NULL , 125it will hold the following values after successful completion 126of the fork operation: 127.Bl -tag -width retval[0] 128.It Fa retval[0] 129This will contain the pid of the child process. 130.It Fa retval[1] 131In the parent process, this will contain the value 0. 132In the child process, this will contain 1. 133.El 134.Pp 135The signal 136.Fa exitsig 137is sent to the parent 138.Fa p1 139on exit of the new process. 140.Pp 141If 142.Fa func 143is not 144.Dv NULL , 145the new process will begin execution by calling this function. 146It defaults to child_return, which returns to userland. 147.Pp 148If 149.Fa arg 150is not 151.Dv NULL , 152it is the argument to the previous function. 153It defaults to a pointer to the new process. 154.Pp 155The newly created process is returned through 156.Fa *rnewprocp . 157.Sh RETURN VALUES 158Upon successful completion of the fork operation, 159.Fn fork1 160returns 0. 161Otherwise, the following error values are returned: 162.Bl -tag -width [EAGAIN] 163.It Bq Er EAGAIN 164The limit on the total number of system processes would be exceeded. 165.It Bq Er EAGAIN 166The limit 167.Dv RLIMIT_NPROC 168on the total number of processes under execution by this 169user id would be exceeded. 170.El 171.Sh SEE ALSO 172.Xr execve 2 , 173.Xr fork 2 , 174.Xr rfork 2 , 175.Xr vfork 2 , 176.Xr kthread_create 9 , 177.Xr pfind 9 , 178.Xr psignal 9 , 179.Xr uvm_fork 9 180.Sh CAVEATS 181The 182.Nm 183function semantics are specific to 184.Ox . 185Other BSD systems have different semantics. 186.Pp 187The system never uses 188.Fn fork1 189with a non-null 190.Fa stack , 191so that feature is not even tested. 192