1.\" $OpenBSD: fork1.9,v 1.27 2016/03/30 06:58:06 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: March 30 2016 $ 33.Dt FORK1 9 34.Os 35.Sh NAME 36.Nm fork1 37.Nd create a new process 38.Sh SYNOPSIS 39.In sys/types.h 40.In sys/proc.h 41.Ft int 42.Fo fork1 43.Fa "struct proc *p1" 44.Fa "int flags" 45.Fa "void *stack" 46.Fa "pid_t *tidptr" 47.Fa "void (*func)(void *)" 48.Fa "void *arg" 49.Fa "register_t *retval" 50.Fa "struct proc **rnewprocp" 51.Fc 52.Sh DESCRIPTION 53.Fn fork1 54creates a new process out of 55.Ar p1 , 56which should be the current process. 57This function is used primarily to implement the 58.Xr fork 2 , 59.Xr __tfork 3 , 60.Xr vfork 2 61system calls, as well as the 62.Xr kthread_create 9 63function. 64.Pp 65The 66.Ar flags 67argument is used to control the behavior of the fork and is created by 68a bitwise-OR of the following values: 69.Bl -tag -width FORK_SHAREFILES 70.It Dv FORK_FORK 71The call is done by the 72.Xr fork 2 73system call. 74Used only for statistics. 75.It Dv FORK_VFORK 76The call is done by the 77.Xr vfork 2 78system call. 79Used only for statistics. 80.It Dv FORK_TFORK 81The call is done by the 82.Xr __tfork 3 83system call. 84Used only for statistics. 85.It Dv FORK_PPWAIT 86Suspend the parent process until the child is terminated (by calling 87.Xr _exit 2 88or abnormally), or makes a call to 89.Xr execve 2 . 90.It Dv FORK_SHAREFILES 91Let the child share the file descriptor table with the parent through 92fdshare(). 93The default behavior is to copy the table through 94fdcopy(). 95.It Dv FORK_IDLE 96The child will be left in the 97.Dv SIDL 98state. 99The default behavior is to make it runnable and add it to the run queue. 100.It Dv FORK_NOZOMBIE 101The child will be dissociated from the parent and will not leave a status 102for the parent to collect. 103See 104.Xr wait 2 . 105.It Dv FORK_SHAREVM 106The child will share the parent's address space. 107The default behavior is 108that the child gets a copy-on-write copy of the address space. 109.It Dv FORK_SIGHAND 110The child will share the parent's signal actions, including the handler, 111mask, and flags, with sigactsshare(). 112The default behavior is to copy the signal actions from the parent with 113sigactsinit(). 114.Dv FORK_SHAREVM 115must also be set. 116.It Dv FORK_PTRACE 117The child will start with tracing enabled, as if 118ptrace(PT_TRACE_ME, 0, 0, 0) had been invoked in the child. 119.It Dv FORK_THREAD 120The child will instead be a kernel-level thread in the same process 121as the parent. 122.Dv FORK_SHAREFILES , 123.Dv FORK_SHAREVM , 124and 125.Dv FORK_SIGHAND 126must also be set. 127.El 128.Pp 129If 130.Fa stack 131is not 132.Dv NULL , 133it will be used as the initial value of the child's stack pointer, 134instead of using the child's copy of the parent's stack. 135.Pp 136If 137.Fa tidptr 138is not 139.Dv NULL , 140the PID of the child process will be written there in the parent 141on success. 142This is guaranteed to be done before 143the child process is started. 144.Pp 145If 146.Fa retval 147is not 148.Dv NULL , 149it will hold the following values after successful completion 150of the fork operation: 151.Bl -tag -width retval[0] 152.It Fa retval[0] 153This will contain the PID of the child process. 154.It Fa retval[1] 155In the parent process, this will contain the value 0. 156In the child process, this will contain 1. 157.El 158.Pp 159If 160.Fa func 161is not 162.Dv NULL , 163the new process will begin execution by calling this function. 164It defaults to child_return, which returns to userland. 165.Pp 166If 167.Fa arg 168is not 169.Dv NULL , 170it is the argument to the previous function. 171It defaults to a pointer to the new process. 172.Pp 173The newly created process is returned through 174.Fa *rnewprocp . 175.Sh RETURN VALUES 176Upon successful completion of the fork operation, 177.Fn fork1 178returns 0. 179Otherwise, the following error values are returned: 180.Bl -tag -width [EAGAIN] 181.It Bq Er EAGAIN 182The limit on the total number of system processes would be exceeded. 183.It Bq Er EAGAIN 184The limit 185.Dv RLIMIT_NPROC 186on the total number of processes under execution by this 187user id would be exceeded. 188.El 189.Sh SEE ALSO 190.Xr execve 2 , 191.Xr fork 2 , 192.Xr vfork 2 , 193.Xr __tfork 3 , 194.Xr kthread_create 9 , 195.Xr pfind 9 , 196.Xr psignal 9 197.Sh CAVEATS 198The 199.Nm 200function semantics are specific to 201.Ox . 202Other 203.Bx 204systems have different semantics. 205