1.\" $NetBSD: clone.2,v 1.13 2012/01/29 11:44:54 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 May 4, 2010 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.In sched.h 41.Ft pid_t 42.Fn clone "int (*func)(void *arg)" "void *stack" "int flags" "void *arg" 43.Ft pid_t 44.Fn __clone "int (*func)(void *arg)" "void *stack" "int flags" "void *arg" 45.Sh DESCRIPTION 46The 47.Nm 48system call (and associated library support code) creates a new process 49in a way that allows the caller to specify several options for the new 50process creation. 51.Pp 52Unlike 53.Xr fork 2 54or 55.Xr vfork 2 , 56in which the child process returns to the call site, 57.Nm 58causes the child process to begin execution at the function specified 59by 60.Ar func . 61The argument 62.Ar arg 63is passed to the entry point, as a means for the parent to provide 64context to the child. 65The stack pointer for the child process will be set to 66.Ar stack . 67Note that the 68.Nm 69interface requires that the application know the stack direction 70for the architecture, and that the caller initialize the 71.Ar stack 72argument as appropriate for the stack direction. 73.Pp 74The 75.Ar flags 76argument specifies several options that control how the child process 77is created. 78The lower 8 bits of 79.Ar flags 80specify the signal that is to be sent to the parent when the child 81exits. 82The following flags may also be specified by bitwise-or'ing 83them with the signal value: 84.Bl -tag -width "CLONE_SIGHAND" -offset 2n 85.It Dv CLONE_VM 86Share the virtual address space with the parent. 87The address space is shared in the same way as 88.Xr vfork 2 . 89.It Dv CLONE_FS 90Share the 91.Dq file system information 92with the parent. 93This include the current working directory and file creation mask. 94.It Dv CLONE_FILES 95Share the file descriptor table with the parent. 96.It Dv CLONE_SIGHAND 97Share the signal handler set with the parent. 98Note that the signal mask 99is never shared between the parent and the child, even if 100.Dv CLONE_SIGHAND 101is set. 102.It Dv CLONE_VFORK 103Preserve the synchronization semantics of 104.Xr vfork 2 ; 105the parent blocks until the child exits. 106.El 107.Pp 108The 109.Nm 110call returns the pid of the child in the parent's context. 111The child is provided no return value, since it begins execution at 112a different address. 113.Pp 114If the child process's entry point returns, the value it returns 115is passed to 116.Xr _exit 2 , 117and the child process exits. 118Note that if the child process wants to exit directly, it should use 119.Xr _exit 2 , 120and not 121.Xr exit 3 , 122since 123.Xr exit 3 124will flush and close standard I/O channels, and thereby corrupt the 125parent process's standard I/O data structures (even with 126.Xr fork 2 127it is wrong to call 128.Xr exit 3 129since buffered data would then be flushed twice). 130.Pp 131Note that 132.Nm 133is not intended to be used for new native 134.Nx 135applications. 136It is provided as a means to port software 137originally written for the Linux operating system to 138.Nx . 139.Sh RETURN VALUES 140Same as for 141.Xr fork 2 . 142.Sh ERRORS 143Same as for 144.Xr fork 2 . 145.Sh SEE ALSO 146.Xr chdir 2 , 147.Xr chroot 2 , 148.Xr fork 2 , 149.Xr sigaction 2 , 150.Xr sigprocmask 2 , 151.Xr umask 2 , 152.Xr vfork 2 , 153.Xr wait 2 154.Sh HISTORY 155The 156.Fn clone 157function call appeared in 158.Nx 1.6 . 159It is compatible with the Linux function call of the same name 160with respect to the described options. 161.Sh BUGS 162The 163.Nx 164implementation of 165.Fn clone 166does not implement the following 167.Ar flags 168that are present in the Linux implementation: 169.Pp 170.Bl -bullet -offset indent -compact 171.It 172.Dv CLONE_CHILD_CLEARTID 173.It 174.Dv CLONE_CHILD_SETTID 175.It 176.Dv CLONE_IO 177.It 178.Dv CLONE_NEWIPC 179.It 180.Dv CLONE_NEWNET 181.It 182.Dv CLONE_NEWNS 183.It 184.Dv CLONE_NEWPID 185.It 186.Dv CLONE_NEWUTS 187.It 188.Dv CLONE_PARENT 189.It 190.Dv CLONE_PARENT_SETTID 191.It 192.Dv CLONE_PID 193.It 194.Dv CLONE_PTRACE 195.It 196.Dv CLONE_SETTLS 197.It 198.Dv CLONE_STOPPED 199.It 200.Dv CLONE_SYSVSEM 201.It 202.Dv CLONE_THREAD 203.It 204.Dv CLONE_UNTRACED 205.El 206