1.\" $NetBSD: clone.2,v 1.15 2022/08/01 14:22:32 wiz Exp $ 2.\" 3.\" Copyright (c) 2001 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. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd August 1, 2022 31.Dt CLONE 2 32.Os 33.Sh NAME 34.Nm clone , 35.Nm __clone 36.Nd spawn new process with options 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.Fd #define _GNU_SOURCE 41.In sched.h 42.Ft pid_t 43.Fn clone "int (*func)(void *arg)" "void *stack" "int flags" "void *arg" 44.Ft pid_t 45.Fn __clone "int (*func)(void *arg)" "void *stack" "int flags" "void *arg" 46.Sh DESCRIPTION 47The 48.Nm 49system call (and associated library support code) creates a new process 50in a way that allows the caller to specify several options for the new 51process creation. 52.Pp 53Unlike 54.Xr fork 2 55or 56.Xr vfork 2 , 57in which the child process returns to the call site, 58.Nm 59causes the child process to begin execution at the function specified 60by 61.Ar func . 62The argument 63.Ar arg 64is passed to the entry point, as a means for the parent to provide 65context to the child. 66The stack pointer for the child process will be set to 67.Ar stack . 68Note that the 69.Nm 70interface requires that the application know the stack direction 71for the architecture, and that the caller initialize the 72.Ar stack 73argument as appropriate for the stack direction. 74.Pp 75The 76.Ar flags 77argument specifies several options that control how the child process 78is created. 79The lower 8 bits of 80.Ar flags 81specify the signal that is to be sent to the parent when the child 82exits. 83The following flags may also be specified by bitwise-or'ing 84them with the signal value: 85.Bl -tag -width "CLONE_SIGHAND" -offset 2n 86.It Dv CLONE_VM 87Share the virtual address space with the parent. 88The address space is shared in the same way as 89.Xr vfork 2 . 90.It Dv CLONE_FS 91Share the 92.Dq file system information 93with the parent. 94This include the current working directory and file creation mask. 95.It Dv CLONE_FILES 96Share the file descriptor table with the parent. 97.It Dv CLONE_SIGHAND 98Share the signal handler set with the parent. 99Note that the signal mask 100is never shared between the parent and the child, even if 101.Dv CLONE_SIGHAND 102is set. 103.It Dv CLONE_VFORK 104Preserve the synchronization semantics of 105.Xr vfork 2 ; 106the parent blocks until the child exits. 107.El 108.Pp 109The 110.Nm 111call returns the pid of the child in the parent's context. 112The child is provided no return value, since it begins execution at 113a different address. 114.Pp 115If the child process's entry point returns, the value it returns 116is passed to 117.Xr _exit 2 , 118and the child process exits. 119Note that if the child process wants to exit directly, it should use 120.Xr _exit 2 , 121and not 122.Xr exit 3 , 123since 124.Xr exit 3 125will flush and close standard I/O channels, and thereby corrupt the 126parent process's standard I/O data structures (even with 127.Xr fork 2 128it is wrong to call 129.Xr exit 3 130since buffered data would then be flushed twice). 131.Pp 132Note that 133.Nm 134is not intended to be used for new native 135.Nx 136applications. 137It is provided as a means to port software 138originally written for the Linux operating system to 139.Nx . 140.Sh RETURN VALUES 141Same as for 142.Xr fork 2 . 143.Sh ERRORS 144Same as for 145.Xr fork 2 . 146.Sh SEE ALSO 147.Xr chdir 2 , 148.Xr chroot 2 , 149.Xr fork 2 , 150.Xr sigaction 2 , 151.Xr sigprocmask 2 , 152.Xr umask 2 , 153.Xr vfork 2 , 154.Xr wait 2 155.Sh HISTORY 156The 157.Fn clone 158function call appeared in 159.Nx 1.6 . 160It is compatible with the Linux function call of the same name 161with respect to the described options. 162.Sh BUGS 163The 164.Nx 165implementation of 166.Fn clone 167does not implement the following 168.Ar flags 169that are present in the Linux implementation: 170.Pp 171.Bl -bullet -offset indent -compact 172.It 173.Dv CLONE_CHILD_CLEARTID 174.It 175.Dv CLONE_CHILD_SETTID 176.It 177.Dv CLONE_IO 178.It 179.Dv CLONE_NEWIPC 180.It 181.Dv CLONE_NEWNET 182.It 183.Dv CLONE_NEWNS 184.It 185.Dv CLONE_NEWPID 186.It 187.Dv CLONE_NEWUTS 188.It 189.Dv CLONE_PARENT 190.It 191.Dv CLONE_PARENT_SETTID 192.It 193.Dv CLONE_PTRACE 194.It 195.Dv CLONE_SETTLS 196.It 197.Dv CLONE_SYSVSEM 198.It 199.Dv CLONE_THREAD 200.It 201.Dv CLONE_UNTRACED 202.El 203