| blob | dbdaf5aad22abba787ccccdf00d1e6b0ad00861f |
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
46 The
47 .Nm
48 system call (and associated library support code) creates a new process
49 in a way that allows the caller to specify several options for the new
50 process creation.
51 .Pp
52 Unlike
53 .Xr fork 2
54 or
55 .Xr vfork 2 ,
56 in which the child process returns to the call site,
57 .Nm
58 causes the child process to begin execution at the function specified
59 by
60 .Ar func .
61 The argument
62 .Ar arg
63 is passed to the entry point, as a means for the parent to provide
64 context to the child.
65 The stack pointer for the child process will be set to
66 .Ar stack .
67 Note that the
68 .Nm
69 interface requires that the application know the stack direction
70 for the architecture, and that the caller initialize the
71 .Ar stack
72 argument as appropriate for the stack direction.
73 .Pp
74 The
75 .Ar flags
76 argument specifies several options that control how the child process
77 is created.
78 The lower 8 bits of
79 .Ar flags
80 specify the signal that is to be sent to the parent when the child
81 exits.
82 The following flags may also be specified by bitwise-or'ing
83 them with the signal value:
84 .Bl -tag -width "CLONE_SIGHAND" -offset 2n
85 .It Dv CLONE_VM
86 Share the virtual address space with the parent.
87 The address space is shared in the same way as
88 .Xr vfork 2 .
89 .It Dv CLONE_FS
90 Share the
91 .Dq file system information
92 with the parent.
93 This include the current working directory and file creation mask.
94 .It Dv CLONE_FILES
95 Share the file descriptor table with the parent.
96 .It Dv CLONE_SIGHAND
97 Share the signal handler set with the parent.
98 Note that the signal mask
99 is never shared between the parent and the child, even if
100 .Dv CLONE_SIGHAND
101 is set.
102 .It Dv CLONE_VFORK
103 Preserve the synchronization semantics of
104 .Xr vfork 2 ;
105 the parent blocks until the child exits.
106 .El
107 .Pp
108 The
109 .Nm
110 call returns the pid of the child in the parent's context.
111 The child is provided no return value, since it begins execution at
112 a different address.
113 .Pp
114 If the child process's entry point returns, the value it returns
115 is passed to
116 .Xr _exit 2 ,
117 and the child process exits.
118 Note that if the child process wants to exit directly, it should use
119 .Xr _exit 2 ,
120 and not
121 .Xr exit 3 ,
122 since
123 .Xr exit 3
124 will flush and close standard I/O channels, and thereby corrupt the
125 parent process's standard I/O data structures (even with
126 .Xr fork 2
127 it is wrong to call
128 .Xr exit 3
129 since buffered data would then be flushed twice).
130 .Pp
131 Note that
132 .Nm
133 is not intended to be used for new native
134 .Nx
135 applications.
136 It is provided as a means to port software
137 originally written for the Linux operating system to
138 .Nx .
139 .Sh RETURN VALUES
140 Same as for
141 .Xr fork 2 .
142 .Sh ERRORS
143 Same 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
155 The
156 .Fn clone
157 function call appeared in
158 .Nx 1.6 .
159 It is compatible with the Linux function call of the same name
160 with respect to the described options.
161 .Sh BUGS
162 The
163 .Nx
164 implementation of
165 .Fn clone
166 does not implement the following
167 .Ar flags
168 that 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