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