1.\" $OpenBSD: fork1.9,v 1.32 2022/12/29 06:49:34 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: December 29 2022 $ 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 (*func)(void *)" 46.Fa "void *arg" 47.Fa "register_t *retval" 48.Fa "struct proc **rnewprocp" 49.Fc 50.Sh DESCRIPTION 51.Fn fork1 52creates a new process out of 53.Ar p1 , 54which should be the current thread. 55This function is used primarily to implement the 56.Xr fork 2 57and 58.Xr vfork 2 59system calls, as well as the 60.Xr kthread_create 9 61function. 62.Pp 63The 64.Ar flags 65argument is used to control the behavior of the fork and is created by 66a bitwise-OR of the following values: 67.Bl -tag -width FORK_SHAREFILES 68.It Dv FORK_FORK 69The call is done by the 70.Xr fork 2 71system call. 72Used only for statistics. 73.It Dv FORK_VFORK 74The call is done by the 75.Xr vfork 2 76system call. 77Used only for statistics. 78.It Dv FORK_PPWAIT 79Suspend the parent process until the child is terminated (by calling 80.Xr _exit 2 81or abnormally), or makes a call to 82.Xr execve 2 . 83.It Dv FORK_SHAREFILES 84Let the child share the file descriptor table with the parent through 85.Fn fdshare . 86The default behavior is to copy the table through 87.Fn fdcopy . 88.It Dv FORK_IDLE 89The new thread will be left in the 90.Dv SIDL 91state. 92The default behavior is to make it runnable and add it to the run queue. 93.It Dv FORK_NOZOMBIE 94The child will be dissociated from the parent and will not leave a status 95for the parent to collect. 96See 97.Xr wait 2 . 98.It Dv FORK_SHAREVM 99The child will share the parent's address space. 100The default behavior is 101that the child gets a copy-on-write copy of the address space. 102.It Dv FORK_SYSTEM 103The child will be marked as a system process. 104.It Dv FORK_PTRACE 105The child will start with tracing enabled, as if 106ptrace(PT_TRACE_ME, 0, 0, 0) had been invoked in the child. 107.El 108.Pp 109The new thread will begin execution by calling 110.Fa func , 111which must not be 112.Dv NULL . 113If 114.Fa arg 115is not 116.Dv NULL , 117it is passed as the argument to 118.Fa func . 119Otherwise, a pointer to the new process's only thread is passed. 120.Pp 121If 122.Fa retval 123is not 124.Dv NULL , 125the PID of the child process will be stored in 126.Fa *retval 127on successful completion. 128.Pp 129If 130.Fa rnewprocp 131is not 132.Dv NULL , 133the newly created thread is stored in 134.Fa *rnewprocp 135on successful completion. 136.Sh RETURN VALUES 137Upon successful completion of the fork operation, 138.Fn fork1 139returns 0. 140Otherwise, the following error values are returned: 141.Bl -tag -width [EAGAIN] 142.It Bq Er EAGAIN 143The system limits on the total number of threads or processes would 144be exceeded. 145.It Bq Er EAGAIN 146The limit 147.Dv RLIMIT_NPROC 148on the total number of processes under execution by this 149user id would be exceeded. 150.It Bq Er ENOMEM 151There is insufficient swap space for the new thread. 152.El 153.Sh SEE ALSO 154.Xr execve 2 , 155.Xr fork 2 , 156.Xr vfork 2 , 157.Xr kthread_create 9 , 158.Xr psignal 9 , 159.Xr tfind 9 160.Sh CAVEATS 161The 162.Nm 163function semantics are specific to 164.Ox . 165Other 166.Bx 167systems have different semantics. 168