1.\" $NetBSD: clone.2,v 1.6 2002/02/08 01:28:17 ross 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. The stack pointer for the child process will 71be 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. The lower 8 bits of 84.Ar flags 85specify the signal that is to be sent to the parent when the child 86exits. The following flags may also be specified by bitwise-or'ing 87them with the signal value: 88.Bl -tag -width "CLONE_SIGHAND" 89.It Dv CLONE_VM 90Share the virtual address space with the parent. The address 91space is shared in the same way as 92.Xr vfork 2 . 93.It Dv CLONE_FS 94Share the 95.Dq file system information 96with the parent. This include the current working directory and file 97creation mask. 98.It Dv CLONE_FILES 99Share the file descriptor table with the parent. 100.It Dv CLONE_SIGHAND 101Share the signal handler set with the parent. Note that the signal mask 102is never shared between the parent and the child, even if 103.Dv CLONE_SIGHAND 104is set. 105.It Dv CLONE_VFORK 106Preserve the synchronization semanics of 107.Xr vfork 2 ; 108the parent blocks until the child exits. 109.El 110.Pp 111The 112.Nm 113call returns the pid of the child in the parent's context. The child 114is provided no return value, since it begins execution at a different 115address. 116.Pp 117If the child process's entry point returns, the value it returns 118is passed to 119.Xr _exit 2 , 120and the child process exits. Note that if the child process wants 121to exit directly, it should use 122.Xr _exit 2 , 123and not 124.Xr exit 3 , 125since 126.Xr exit 3 127will flush and close standard I/O channels, and thereby corrupt the 128parent process's standard I/O data structures (even with 129.Xr fork 2 130it is wrong to call 131.Xr exit 3 132since buffered data would then be flushed twice). 133.Pp 134Note that 135.Nm 136is not intended to be used for new native 137.Nx 138applications. It is provided as a means to port software 139originally written for the Linux operating system to 140.Nx . 141.Sh RETURN VALUES 142Same as for 143.Xr fork 2 . 144.Sh ERRORS 145Same as for 146.Xr fork 2 . 147.Sh SEE ALSO 148.Xr chdir 2 , 149.Xr chroot 2 , 150.Xr fork 2 , 151.Xr sigaction 2 , 152.Xr sigprocmask 2 , 153.Xr umask 2 , 154.Xr vfork 2 , 155.Xr wait 2 156.Sh HISTORY 157The 158.Fn clone 159function call appeared in 160.Nx 1.6 . 161It is compatible with the Linux function call of the same name. 162.Sh BUGS 163The 164.Nx 165implementation of 166.Nm 167does not implement the 168.Dv CLONE_PID 169option that is present in the Linux implementation. 170.Pp 171The 172.Nx 173implementation of 174.Nm 175does not implement the 176.Dv CLONE_PTRACE 177option that is present in the Linux implementation. 178