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