1.\" $OpenBSD: fork1.9,v 1.30 2017/06/11 17:06:27 schwarze 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 11 2017 $ 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_SIGHAND 103The child will share the parent's signal actions, including the handler, 104mask, and flags, with 105.Fn sigactsshare . 106The default behavior is to copy the signal actions from the parent with 107.Fn sigactsinit . 108.Dv FORK_SHAREVM 109must also be set. 110.It Dv FORK_PTRACE 111The child will start with tracing enabled, as if 112ptrace(PT_TRACE_ME, 0, 0, 0) had been invoked in the child. 113.El 114.Pp 115If 116.Fa func 117is not 118.Dv NULL , 119the new thread will begin execution by calling this function. 120It defaults to child_return, which returns to userland. 121.Pp 122If 123.Fa arg 124is not 125.Dv NULL , 126it is the argument to the previous function. 127It defaults to a pointer to the new thread. 128.Pp 129If 130.Fa retval 131is not 132.Dv NULL , 133the PID of the child process will be stored in 134.Fa *retval 135on successful completion. 136.Pp 137If 138.Fa rnewprocp 139is not 140.Dv NULL , 141the newly created thread is stored in 142.Fa *rnewprocp 143on successful completion. 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 system limits on the total number of threads or processes would 152be exceeded. 153.It Bq Er EAGAIN 154The limit 155.Dv RLIMIT_NPROC 156on the total number of processes under execution by this 157user id would be exceeded. 158.It Bq Er ENOMEM 159There is insufficient swap space for the new thread. 160.El 161.Sh SEE ALSO 162.Xr execve 2 , 163.Xr fork 2 , 164.Xr vfork 2 , 165.Xr kthread_create 9 , 166.Xr psignal 9 , 167.Xr tfind 9 168.Sh CAVEATS 169The 170.Nm 171function semantics are specific to 172.Ox . 173Other 174.Bx 175systems have different semantics. 176