1.\" $NetBSD: fork1.9,v 1.11 2004/03/13 20:50:17 wiz Exp $ 2.\" 3.\" Copyright (c) 1998 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, 8.\" NASA Ames Research Center. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the NetBSD 21.\" Foundation, Inc. and its contributors. 22.\" 4. Neither the name of The NetBSD Foundation nor the names of its 23.\" contributors may be used to endorse or promote products derived 24.\" from this software without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 30.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36.\" POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd March 11, 2004 39.Dt FORK1 9 40.Os 41.Sh NAME 42.Nm fork1 43.Nd create a new process 44.Sh SYNOPSIS 45.In sys/types.h 46.In sys/proc.h 47.Ft int 48.Fn "fork1" "struct lwp *l1" "int flags" "int exitsig" "void *stack" "size_t stacksize" "void (*func)(void *)" "void *arg" "register_t *retval" "struct proc **rnewprocp" 49.Sh DESCRIPTION 50.Fn fork1 51creates a new process out of the process behind 52.Ar l1 , 53which is assumed to be the current lwp. 54This function is used primarily to implement the 55.Xr fork 2 56and 57.Xr vfork 2 58system calls, but is versatile enough to be used as a backend for 59e.g. the 60.Xr __clone 2 61call. 62.Pp 63The 64.Ar flags 65argument controls the semantics of the fork operation, and is made up of 66the bitwise-OR of the following values: 67.Bl -tag -width FORK_SHAREFILES 68.It FORK_PPWAIT 69The parent process will sleep until the child process successfully calls 70.Xr execve 2 71or exits (either by a call to 72.Xr _exit 2 73or abnormally). 74.It FORK_SHAREVM 75The child process will share the parent's virtual address space. 76If this flag is not specified, the child will get a copy-on-write 77snapshot of the parent's address space. 78.It FORK_SHARECWD 79The child process will share the parent's current directory, root directory, 80and file creation mask. 81.It FORK_SHAREFILES 82The child process will share the parent's file descriptors. 83.It FORK_SHARESIGS 84The child process will share the parent's signal actions. 85.It FORK_NOWAIT 86The child process will at creation time be inherited by the init process. 87.It FORK_CLEANFILES 88The child process will not copy or share the parent's descriptors, but 89rather will start out with a clean set. 90.El 91.Pp 92A 93.Ar flags 94value of 0 indicates a standard fork operation. 95.Pp 96The 97.Ar exitsig 98argument controls the signal sent to the parent on child death. 99If normal operation desired, SIGCHLD should be supplied. 100.Pp 101It is possible to specify the child userspace stack location and size 102by using the 103.Ar stack 104and 105.Ar stacksize 106arguments, respectively. 107Values 108.Dv NULL 109and 0, respectively, will give the child the default values 110for the machine architecture in question. 111.Pp 112The arguments 113.Ar func 114and 115.Ar arg 116can be used to specify a kernel function to called for child return handling 117instead of 118.Fn child_return . 119These are used for example in starting the init process and creating kernel 120threads. 121.Pp 122The 123.Ar retval 124argument is provided for the use of system call stubs. 125If 126.Ar retval 127is not NULL, it will hold the following values after successful completion 128of the fork operation: 129.Bl -tag -width retval[0] 130.It Ar retval[0] 131This will contain the pid of the child process. 132.It Ar retval[1] 133In the parent process, this will contain the value 0. 134In the child process, this will contain 1. 135.El 136.Pp 137User level system call stubs typically subtract 1 from 138.Ar retval[1] 139and bitwise-AND it with 140.Ar retval[0] , 141thus returning the pid to the parent process and 0 to the child. 142.Pp 143If 144.Ar rnewprocp 145is not NULL, 146.Ar *rnewprocp 147will point to the newly created process upon successful completion of 148the fork operation. 149.Sh RETURN VALUES 150Upon successful completion of the fork operation, 151.Fn fork1 152returns 0. 153Otherwise, the following error values are returned: 154.Bl -tag -width [EAGAIN] 155.It Bq Er EAGAIN 156The limit on the total number of system processes would be exceeded. 157.It Bq Er EAGAIN 158The limit 159.Dv RLIMIT_NPROC 160on the total number of processes under execution by this 161user id would be exceeded. 162.El 163.Sh SEE ALSO 164.Xr execve 2 , 165.Xr fork 2 , 166.Xr vfork 2 167