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