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