1.\" $OpenBSD: fork1.9,v 1.11 2008/06/26 05:42:08 ray 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: June 26 2008 $ 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.Fn "fork1" "struct proc *p1" "int exitsig" "int flags" "void *stack" "size_t stacksize" "void (*func)(void *)" "void *arg" "register_t *retval" 43.Sh DESCRIPTION 44.Fn fork1 45creates a new process out of 46.Ar p1 , 47which should be the current process. 48This function is used primarily to implement the 49.Xr fork 2 , 50.Xr rfork 2 , 51.Xr vfork 2 52system calls, as well as the 53.Xr kthread_create 9 54function. 55.Pp 56The 57.Ar flags 58argument is used to control the behavior of the fork and is created by 59a bitwise-OR of the following values: 60.Bl -tag -width FORK_SHAREFILES 61.It Dv FORK_FORK 62The call is done by the 63.Xr fork 2 64system call. 65Used only for statistics. 66.It Dv FORK_VFORK 67The call is done by the 68.Xr vfork 2 69system call. 70Used only for statistics. 71.It Dv FORK_RFORK 72The call is done by the 73.Xr rfork 2 74system call. 75Used only for statistics. 76.It Dv FORK_PPWAIT 77Suspend the parent process until the child is terminated (by calling 78.Xr _exit 2 79or abnormally), or makes a call to 80.Xr execve 2 . 81.It Dv FORK_SHAREFILES 82Let the child share the file descriptor table with the parent through 83fdshare(). 84The default behavior is to copy the table through 85fdcopy(). 86.It Dv FORK_CLEANFILES 87The child starts with a clean file descriptor table created by 88fdinit(). 89.It Dv FORK_NOZOMBIE 90The child will be dissociated from the parent and will not leave a status 91for the parent to collect. 92See 93.Xr wait 2 . 94.It Dv FORK_SHAREVM 95The child will share the parent's address space. 96The default behavior is 97that the child gets a copy-on-write copy of the address space. 98.El 99.Pp 100If 101.Fa stack 102is not 103.Dv NULL , 104the area starting at 105.Fa stack 106of extent 107.Fa stacksize 108will be used for the child's stack, instead of cloning the parent's 109stack. 110.Pp 111If 112.Fa retval 113is not 114.Dv NULL , 115it will hold the following values after successful completion 116of the fork operation: 117.Bl -tag -width retval[0] 118.It Fa retval[0] 119This will contain the pid of the child process. 120.It Fa retval[1] 121In the parent process, this will contain the value 0. 122In the child process, this will contain 1. 123.El 124.Pp 125The signal 126.Fa exitsig 127is sent to the parent 128.Fa p1 129on exit of the new process. 130.Pp 131If 132.Fa func 133is not 134.Dv NULL , 135the new process will begin execution by calling this function. 136It defaults to child_return, which returns to userland. 137.Pp 138If 139.Fa arg 140is not 141.Dv NULL , 142it is the argument to the previous function. 143It defaults to a pointer to the new process. 144.Sh RETURN VALUES 145Upon successful completion of the fork operation, 146.Fn fork1 147returns 0. 148Otherwise, the following error values are returned: 149.Bl -tag -width [EAGAIN] 150.It Bq Er EAGAIN 151The limit on the total number of system processes would be exceeded. 152.It Bq Er EAGAIN 153The limit 154.Dv RLIMIT_NPROC 155on the total number of processes under execution by this 156user id would be exceeded. 157.El 158.Sh SEE ALSO 159.Xr execve 2 , 160.Xr fork 2 , 161.Xr rfork 2 , 162.Xr vfork 2 , 163.Xr kthread_create 9 , 164.Xr pfind 9 , 165.Xr psignal 9 , 166.Xr uvm_fork 9 167.Sh CAVEATS 168The 169.Nm 170function semantics are specific to 171.Ox . 172Other BSD systems have different semantics. 173.Pp 174The system never uses 175.Fn fork1 176with a non-null 177.Fa stack , 178so that feature is not even tested. 179