]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (c) 1992 Drew Eckhardt <drew@cs.colorado.edu>, March 28, 1992 |
8c7b566c | 2 | .\" and Copyright (c) Michael Kerrisk, 2001, 2002, 2005, 2013 |
2297bf0e | 3 | .\" |
fd0fc519 | 4 | .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) |
fea681da | 5 | .\" May be distributed under the GNU General Public License. |
fd0fc519 | 6 | .\" %%%LICENSE_END |
dccaff1e | 7 | .\" |
fea681da MK |
8 | .\" Modified by Michael Haardt <michael@moria.de> |
9 | .\" Modified 24 Jul 1993 by Rik Faith <faith@cs.unc.edu> | |
10 | .\" Modified 21 Aug 1994 by Michael Chastain <mec@shell.portal.com>: | |
11 | .\" New man page (copied from 'fork.2'). | |
12 | .\" Modified 10 June 1995 by Andries Brouwer <aeb@cwi.nl> | |
13 | .\" Modified 25 April 1998 by Xavier Leroy <Xavier.Leroy@inria.fr> | |
14 | .\" Modified 26 Jun 2001 by Michael Kerrisk | |
15 | .\" Mostly upgraded to 2.4.x | |
16 | .\" Added prototype for sys_clone() plus description | |
17 | .\" Added CLONE_THREAD with a brief description of thread groups | |
c13182ef | 18 | .\" Added CLONE_PARENT and revised entire page remove ambiguity |
fea681da MK |
19 | .\" between "calling process" and "parent process" |
20 | .\" Added CLONE_PTRACE and CLONE_VFORK | |
21 | .\" Added EPERM and EINVAL error codes | |
fd8a5be4 | 22 | .\" Renamed "__clone" to "clone" (which is the prototype in <sched.h>) |
fea681da | 23 | .\" various other minor tidy ups and clarifications. |
c11b1abf | 24 | .\" Modified 26 Jun 2001 by Michael Kerrisk <mtk.manpages@gmail.com> |
d9bfdb9c | 25 | .\" Updated notes for 2.4.7+ behavior of CLONE_THREAD |
c11b1abf | 26 | .\" Modified 15 Oct 2002 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
27 | .\" Added description for CLONE_NEWNS, which was added in 2.4.19 |
28 | .\" Slightly rephrased, aeb. | |
29 | .\" Modified 1 Feb 2003 - added CLONE_SIGHAND restriction, aeb. | |
30 | .\" Modified 1 Jan 2004 - various updates, aeb | |
0967c11f | 31 | .\" Modified 2004-09-10 - added CLONE_PARENT_SETTID etc. - aeb. |
d9bfdb9c | 32 | .\" 2005-04-12, mtk, noted the PID caching behavior of NPTL's getpid() |
31830ef0 | 33 | .\" wrapper under BUGS. |
fd8a5be4 MK |
34 | .\" 2005-05-10, mtk, added CLONE_SYSVSEM, CLONE_UNTRACED, CLONE_STOPPED. |
35 | .\" 2005-05-17, mtk, Substantially enhanced discussion of CLONE_THREAD. | |
4e836144 | 36 | .\" 2008-11-18, mtk, order CLONE_* flags alphabetically |
82ee147a | 37 | .\" 2008-11-18, mtk, document CLONE_NEWPID |
43ce9dda | 38 | .\" 2008-11-19, mtk, document CLONE_NEWUTS |
667417b3 | 39 | .\" 2008-11-19, mtk, document CLONE_NEWIPC |
cfdc761b | 40 | .\" 2008-11-19, Jens Axboe, mtk, document CLONE_IO |
fea681da | 41 | .\" |
63121bd4 | 42 | .TH CLONE 2 2019-08-02 "Linux" "Linux Programmer's Manual" |
fea681da | 43 | .SH NAME |
9b0e0996 | 44 | clone, __clone2 \- create a child process |
fea681da | 45 | .SH SYNOPSIS |
c10859eb | 46 | .nf |
81f10dad | 47 | /* Prototype for the glibc wrapper function */ |
dbfe9c70 | 48 | .PP |
4f71ba5d | 49 | .B #define _GNU_SOURCE |
fea681da | 50 | .B #include <sched.h> |
dbfe9c70 | 51 | .PP |
ff929e3b MK |
52 | .BI "int clone(int (*" "fn" ")(void *), void *" child_stack , |
53 | .BI " int " flags ", void *" "arg" ", ... " | |
dd6d3d2e | 54 | .BI " /* pid_t *" ptid ", void *" newtls \ |
ff929e3b | 55 | ", pid_t *" ctid " */ );" |
dbfe9c70 | 56 | .PP |
2a15a76b | 57 | /* For the prototype of the raw system call, see NOTES */ |
c10859eb | 58 | .fi |
fea681da | 59 | .SH DESCRIPTION |
edcc65ff MK |
60 | .BR clone () |
61 | creates a new process, in a manner similar to | |
fea681da | 62 | .BR fork (2). |
efeece04 | 63 | .PP |
81f10dad | 64 | This page describes both the glibc |
e511ffb6 | 65 | .BR clone () |
e585064b | 66 | wrapper function and the underlying system call on which it is based. |
81f10dad | 67 | The main text describes the wrapper function; |
e585064b | 68 | the differences for the raw system call |
81f10dad | 69 | are described toward the end of this page. |
efeece04 | 70 | .PP |
fea681da MK |
71 | Unlike |
72 | .BR fork (2), | |
81f10dad MK |
73 | .BR clone () |
74 | allows the child process to share parts of its execution context with | |
4ba17a6d | 75 | the calling process, such as the virtual address space, the table of file |
c13182ef MK |
76 | descriptors, and the table of signal handlers. |
77 | (Note that on this manual | |
78 | page, "calling process" normally corresponds to "parent process". | |
79 | But see the description of | |
80 | .B CLONE_PARENT | |
fea681da | 81 | below.) |
efeece04 | 82 | .PP |
1533d242 | 83 | One use of |
edcc65ff | 84 | .BR clone () |
4ba17a6d MK |
85 | is to implement threads: multiple flows of control in a program that |
86 | run concurrently in a shared address space. | |
efeece04 | 87 | .PP |
fea681da | 88 | When the child process is created with |
c13182ef | 89 | .BR clone (), |
7495cbc7 MK |
90 | it commences execution by calling the function pointed to by the argument |
91 | .IR fn . | |
fea681da | 92 | (This differs from |
c13182ef | 93 | .BR fork (2), |
fea681da | 94 | where execution continues in the child from the point |
c13182ef MK |
95 | of the |
96 | .BR fork (2) | |
fea681da MK |
97 | call.) |
98 | The | |
fea681da | 99 | .I arg |
7495cbc7 MK |
100 | argument is passed as the argument of the function |
101 | .IR fn . | |
efeece04 | 102 | .PP |
c13182ef | 103 | When the |
fea681da | 104 | .IR fn ( arg ) |
4ba17a6d | 105 | function returns, the child process terminates. |
c13182ef | 106 | The integer returned by |
fea681da | 107 | .I fn |
4ba17a6d | 108 | is the exit status for the child process. |
c13182ef | 109 | The child process may also terminate explicitly by calling |
fea681da MK |
110 | .BR exit (2) |
111 | or after receiving a fatal signal. | |
efeece04 | 112 | .PP |
fea681da MK |
113 | The |
114 | .I child_stack | |
c13182ef MK |
115 | argument specifies the location of the stack used by the child process. |
116 | Since the child and calling process may share memory, | |
fea681da | 117 | it is not possible for the child process to execute in the |
c13182ef MK |
118 | same stack as the calling process. |
119 | The calling process must therefore | |
fea681da MK |
120 | set up memory space for the child stack and pass a pointer to this |
121 | space to | |
edcc65ff | 122 | .BR clone (). |
5fab2e7c | 123 | Stacks grow downward on all processors that run Linux |
fea681da MK |
124 | (except the HP PA processors), so |
125 | .I child_stack | |
126 | usually points to the topmost address of the memory space set up for | |
127 | the child stack. | |
efeece04 | 128 | .PP |
fea681da MK |
129 | The low byte of |
130 | .I flags | |
fd8a5be4 MK |
131 | contains the number of the |
132 | .I "termination signal" | |
133 | sent to the parent when the child dies. | |
134 | If this signal is specified as anything other than | |
fea681da MK |
135 | .BR SIGCHLD , |
136 | then the parent process must specify the | |
c13182ef MK |
137 | .B __WALL |
138 | or | |
fea681da | 139 | .B __WCLONE |
c13182ef MK |
140 | options when waiting for the child with |
141 | .BR wait (2). | |
fea681da MK |
142 | If no signal is specified, then the parent process is not signaled |
143 | when the child terminates. | |
efeece04 | 144 | .PP |
fea681da | 145 | .I flags |
4ba17a6d | 146 | may also be bitwise-ORed with zero or more of the following constants, |
fd8a5be4 | 147 | in order to specify what is shared between the calling process |
fea681da | 148 | and the child process: |
fea681da | 149 | .TP |
f5dbc7c8 | 150 | .BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)" |
4ba5392d | 151 | Clear (zero) the child thread ID at the location |
d3dbc9b1 | 152 | .I ctid |
f5dbc7c8 MK |
153 | in child memory when the child exits, and do a wakeup on the futex |
154 | at that address. | |
155 | The address involved may be changed by the | |
156 | .BR set_tid_address (2) | |
157 | system call. | |
158 | This is used by threading libraries. | |
159 | .TP | |
160 | .BR CLONE_CHILD_SETTID " (since Linux 2.5.49)" | |
8ef021ea | 161 | Store the child thread ID at the location |
d3dbc9b1 | 162 | .I ctid |
8ef021ea | 163 | in the child's memory. |
b5da2f91 MK |
164 | The store operation completes before |
165 | .BR clone () | |
6ab62ed8 MK |
166 | returns control to user space in the child process. |
167 | (Note that the store operation may not have completed before | |
168 | .BR clone () | |
169 | returns in the parent process, which will be relevant if the | |
170 | .BR CLONE_VM | |
171 | flag is also employed.) | |
f5dbc7c8 | 172 | .TP |
1603d6a1 | 173 | .BR CLONE_FILES " (since Linux 2.0)" |
fea681da | 174 | If |
f5dbc7c8 MK |
175 | .B CLONE_FILES |
176 | is set, the calling process and the child process share the same file | |
177 | descriptor table. | |
178 | Any file descriptor created by the calling process or by the child | |
179 | process is also valid in the other process. | |
180 | Similarly, if one of the processes closes a file descriptor, | |
181 | or changes its associated flags (using the | |
182 | .BR fcntl (2) | |
183 | .B F_SETFD | |
184 | operation), the other process is also affected. | |
8a76b19e KE |
185 | If a process sharing a file descriptor table calls |
186 | .BR execve (2), | |
187 | its file descriptor table is duplicated (unshared). | |
efeece04 | 188 | .IP |
fea681da | 189 | If |
f5dbc7c8 MK |
190 | .B CLONE_FILES |
191 | is not set, the child process inherits a copy of all file descriptors | |
192 | opened in the calling process at the time of | |
193 | .BR clone (). | |
f5dbc7c8 MK |
194 | Subsequent operations that open or close file descriptors, |
195 | or change file descriptor flags, | |
196 | performed by either the calling | |
197 | process or the child process do not affect the other process. | |
db8ba2b4 | 198 | Note, however, |
839d161f MK |
199 | that the duplicated file descriptors in the child refer to the same |
200 | open file descriptions as the corresponding file descriptors | |
201 | in the calling process, | |
2433365b | 202 | and thus share file offsets and file status flags (see |
db8ba2b4 | 203 | .BR open (2)). |
fea681da | 204 | .TP |
1603d6a1 | 205 | .BR CLONE_FS " (since Linux 2.0)" |
fea681da MK |
206 | If |
207 | .B CLONE_FS | |
9ee4a2b6 | 208 | is set, the caller and the child process share the same filesystem |
c13182ef | 209 | information. |
9ee4a2b6 | 210 | This includes the root of the filesystem, the current |
c13182ef MK |
211 | working directory, and the umask. |
212 | Any call to | |
fea681da MK |
213 | .BR chroot (2), |
214 | .BR chdir (2), | |
215 | or | |
216 | .BR umask (2) | |
edcc65ff | 217 | performed by the calling process or the child process also affects the |
fea681da | 218 | other process. |
efeece04 | 219 | .IP |
c13182ef | 220 | If |
fea681da | 221 | .B CLONE_FS |
9ee4a2b6 | 222 | is not set, the child process works on a copy of the filesystem |
fea681da | 223 | information of the calling process at the time of the |
edcc65ff | 224 | .BR clone () |
fea681da MK |
225 | call. |
226 | Calls to | |
227 | .BR chroot (2), | |
228 | .BR chdir (2), | |
4ba17a6d | 229 | or |
fea681da MK |
230 | .BR umask (2) |
231 | performed later by one of the processes do not affect the other process. | |
fea681da | 232 | .TP |
a4cc375e | 233 | .BR CLONE_IO " (since Linux 2.6.25)" |
11f27a1c JA |
234 | If |
235 | .B CLONE_IO | |
236 | is set, then the new process shares an I/O context with | |
237 | the calling process. | |
238 | If this flag is not set, then (as with | |
239 | .BR fork (2)) | |
240 | the new process has its own I/O context. | |
efeece04 | 241 | .IP |
11f27a1c | 242 | .\" The following based on text from Jens Axboe |
d1f84ed7 | 243 | The I/O context is the I/O scope of the disk scheduler (i.e., |
11f27a1c JA |
244 | what the I/O scheduler uses to model scheduling of a process's I/O). |
245 | If processes share the same I/O context, | |
246 | they are treated as one by the I/O scheduler. | |
247 | As a consequence, they get to share disk time. | |
248 | For some I/O schedulers, | |
249 | .\" the anticipatory and CFQ scheduler | |
250 | if two processes share an I/O context, | |
251 | they will be allowed to interleave their disk access. | |
252 | If several threads are doing I/O on behalf of the same process | |
253 | .RB ( aio_read (3), | |
254 | for instance), they should employ | |
255 | .BR CLONE_IO | |
256 | to get better I/O performance. | |
257 | .\" with CFQ and AS. | |
efeece04 | 258 | .IP |
11f27a1c JA |
259 | If the kernel is not configured with the |
260 | .B CONFIG_BLOCK | |
261 | option, this flag is a no-op. | |
262 | .TP | |
c5af0674 MK |
263 | .BR CLONE_NEWCGROUP " (since Linux 4.6)" |
264 | Create the process in a new cgroup namespace. | |
265 | If this flag is not set, then (as with | |
266 | .BR fork (2)) | |
267 | the process is created in the same cgroup namespaces as the calling process. | |
268 | This flag is intended for the implementation of containers. | |
efeece04 | 269 | .IP |
c5af0674 | 270 | For further information on cgroup namespaces, see |
b9fe4bc3 | 271 | .BR cgroup_namespaces (7). |
efeece04 | 272 | .IP |
c5af0674 MK |
273 | Only a privileged process |
274 | .RB ( CAP_SYS_ADMIN ) | |
275 | can employ | |
276 | .BR CLONE_NEWCGROUP . | |
277 | .\" | |
278 | .TP | |
8722311b | 279 | .BR CLONE_NEWIPC " (since Linux 2.6.19)" |
667417b3 MK |
280 | If |
281 | .B CLONE_NEWIPC | |
282 | is set, then create the process in a new IPC namespace. | |
283 | If this flag is not set, then (as with | |
06b30458 | 284 | .BR fork (2)), |
667417b3 MK |
285 | the process is created in the same IPC namespace as |
286 | the calling process. | |
0236bea9 | 287 | This flag is intended for the implementation of containers. |
efeece04 | 288 | .IP |
efbfd7ec | 289 | An IPC namespace provides an isolated view of System\ V IPC objects (see |
343cdc5a | 290 | .BR sysvipc (7)) |
009a049e MK |
291 | and (since Linux 2.6.30) |
292 | .\" commit 7eafd7c74c3f2e67c27621b987b28397110d643f | |
293 | .\" https://lwn.net/Articles/312232/ | |
294 | POSIX message queues | |
295 | (see | |
296 | .BR mq_overview (7)). | |
19911fa5 MK |
297 | The common characteristic of these IPC mechanisms is that IPC |
298 | objects are identified by mechanisms other than filesystem | |
299 | pathnames. | |
efeece04 | 300 | .IP |
c440fe01 | 301 | Objects created in an IPC namespace are visible to all other processes |
667417b3 MK |
302 | that are members of that namespace, |
303 | but are not visible to processes in other IPC namespaces. | |
efeece04 | 304 | .IP |
83c1f4b5 | 305 | When an IPC namespace is destroyed |
009a049e | 306 | (i.e., when the last process that is a member of the namespace terminates), |
83c1f4b5 | 307 | all IPC objects in the namespace are automatically destroyed. |
efeece04 | 308 | .IP |
ab5dd83f MK |
309 | Only a privileged process |
310 | .RB ( CAP_SYS_ADMIN ) | |
311 | can employ | |
312 | .BR CLONE_NEWIPC . | |
667417b3 MK |
313 | This flag can't be specified in conjunction with |
314 | .BR CLONE_SYSVSEM . | |
efeece04 | 315 | .IP |
9343f8e7 MK |
316 | For further information on IPC namespaces, see |
317 | .BR namespaces (7). | |
667417b3 | 318 | .TP |
163bf178 | 319 | .BR CLONE_NEWNET " (since Linux 2.6.24)" |
33a0ccb2 | 320 | (The implementation of this flag was completed only |
9108d867 | 321 | by about kernel version 2.6.29.) |
efeece04 | 322 | .IP |
163bf178 MK |
323 | If |
324 | .B CLONE_NEWNET | |
325 | is set, then create the process in a new network namespace. | |
326 | If this flag is not set, then (as with | |
57ef8c39 | 327 | .BR fork (2)) |
163bf178 MK |
328 | the process is created in the same network namespace as |
329 | the calling process. | |
330 | This flag is intended for the implementation of containers. | |
efeece04 | 331 | .IP |
163bf178 MK |
332 | A network namespace provides an isolated view of the networking stack |
333 | (network device interfaces, IPv4 and IPv6 protocol stacks, | |
334 | IP routing tables, firewall rules, the | |
335 | .I /proc/net | |
336 | and | |
337 | .I /sys/class/net | |
338 | directory trees, sockets, etc.). | |
339 | A physical network device can live in exactly one | |
340 | network namespace. | |
6f34a82c MK |
341 | A virtual network |
342 | .RB ( veth (4)) | |
343 | device pair provides a pipe-like abstraction | |
163bf178 MK |
344 | that can be used to create tunnels between network namespaces, |
345 | and can be used to create a bridge to a physical network device | |
346 | in another namespace. | |
efeece04 | 347 | .IP |
bf032425 SH |
348 | When a network namespace is freed |
349 | (i.e., when the last process in the namespace terminates), | |
350 | its physical network devices are moved back to the | |
351 | initial network namespace (not to the parent of the process). | |
73680728 MK |
352 | For further information on network namespaces, see |
353 | .BR namespaces (7). | |
efeece04 | 354 | .IP |
ab5dd83f MK |
355 | Only a privileged process |
356 | .RB ( CAP_SYS_ADMIN ) | |
357 | can employ | |
358 | .BR CLONE_NEWNET . | |
163bf178 | 359 | .TP |
c10859eb | 360 | .BR CLONE_NEWNS " (since Linux 2.4.19)" |
3dd2331c MK |
361 | If |
362 | .B CLONE_NEWNS | |
363 | is set, the cloned child is started in a new mount namespace, | |
364 | initialized with a copy of the namespace of the parent. | |
365 | If | |
fea681da | 366 | .B CLONE_NEWNS |
3dd2331c | 367 | is not set, the child lives in the same mount |
4df2eb09 | 368 | namespace as the parent. |
efeece04 | 369 | .IP |
ab5dd83f MK |
370 | Only a privileged process |
371 | .RB ( CAP_SYS_ADMIN ) | |
372 | can employ | |
373 | .BR CLONE_NEWNS . | |
fea681da MK |
374 | It is not permitted to specify both |
375 | .B CLONE_NEWNS | |
376 | and | |
377 | .B CLONE_FS | |
9219d208 | 378 | .\" See https://lwn.net/Articles/543273/ |
fea681da | 379 | in the same |
e511ffb6 | 380 | .BR clone () |
fea681da | 381 | call. |
efeece04 | 382 | .IP |
c212248c MK |
383 | For further information on mount namespaces, see |
384 | .BR namespaces (7) | |
385 | and | |
386 | .BR mount_namespaces (7). | |
9d005472 MK |
387 | .TP |
388 | .BR CLONE_NEWPID " (since Linux 2.6.24)" | |
389 | .\" This explanation draws a lot of details from | |
390 | .\" http://lwn.net/Articles/259217/ | |
391 | .\" Authors: Pavel Emelyanov <xemul@openvz.org> | |
392 | .\" and Kir Kolyshkin <kir@openvz.org> | |
393 | .\" | |
394 | .\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264 | |
395 | .\" Author: Pavel Emelyanov <xemul@openvz.org> | |
396 | If | |
397 | .B CLONE_NEWPID | |
398 | is set, then create the process in a new PID namespace. | |
399 | If this flag is not set, then (as with | |
400 | .BR fork (2)) | |
401 | the process is created in the same PID namespace as | |
402 | the calling process. | |
403 | This flag is intended for the implementation of containers. | |
efeece04 | 404 | .IP |
9d005472 | 405 | For further information on PID namespaces, see |
7e0e902b MK |
406 | .BR namespaces (7) |
407 | and | |
39b3f005 | 408 | .BR pid_namespaces (7). |
efeece04 | 409 | .IP |
ab5dd83f MK |
410 | Only a privileged process |
411 | .RB ( CAP_SYS_ADMIN ) | |
412 | can employ | |
413 | .BR CLONE_NEWPID . | |
9d005472 | 414 | This flag can't be specified in conjunction with |
f0007192 MK |
415 | .BR CLONE_THREAD |
416 | or | |
417 | .BR CLONE_PARENT . | |
70d21f17 | 418 | .TP |
06b30458 MK |
419 | .BR CLONE_NEWUSER |
420 | (This flag first became meaningful for | |
421 | .BR clone () | |
4d2b3ed7 MK |
422 | in Linux 2.6.23, |
423 | the current | |
11a38815 | 424 | .BR clone () |
4d2b3ed7 MK |
425 | semantics were merged in Linux 3.5, |
426 | and the final pieces to make the user namespaces completely usable were | |
427 | merged in Linux 3.8.) | |
efeece04 | 428 | .IP |
70d21f17 EB |
429 | If |
430 | .B CLONE_NEWUSER | |
06b30458 MK |
431 | is set, then create the process in a new user namespace. |
432 | If this flag is not set, then (as with | |
57ef8c39 | 433 | .BR fork (2)) |
70d21f17 | 434 | the process is created in the same user namespace as the calling process. |
efeece04 | 435 | .IP |
fefbcba8 MK |
436 | Before Linux 3.8, use of |
437 | .BR CLONE_NEWUSER | |
438 | required that the caller have three capabilities: | |
439 | .BR CAP_SYS_ADMIN , | |
440 | .BR CAP_SETUID , | |
441 | and | |
442 | .BR CAP_SETGID . | |
443 | .\" Before Linux 2.6.29, it appears that only CAP_SYS_ADMIN was needed | |
06b30458 | 444 | Starting with Linux 3.8, |
9d005472 | 445 | no privileges are needed to create a user namespace. |
efeece04 | 446 | .IP |
5e72cf7d MK |
447 | This flag can't be specified in conjunction with |
448 | .BR CLONE_THREAD | |
449 | or | |
450 | .BR CLONE_PARENT . | |
451 | For security reasons, | |
452 | .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 | |
453 | .\" https://lwn.net/Articles/543273/ | |
454 | .\" The fix actually went into 3.9 and into 3.8.3. However, user namespaces | |
455 | .\" were, for practical purposes, unusable in earlier 3.8.x because of the | |
ab3311aa | 456 | .\" various filesystems that didn't support userns. |
f0007192 MK |
457 | .BR CLONE_NEWUSER |
458 | cannot be specified in conjunction with | |
5e72cf7d | 459 | .BR CLONE_FS . |
efeece04 | 460 | .IP |
5e72cf7d | 461 | For further information on user namespaces, see |
e5f3df48 MK |
462 | .BR namespaces (7) |
463 | and | |
5e72cf7d | 464 | .BR user_namespaces (7). |
82ee147a | 465 | .TP |
43ce9dda MK |
466 | .BR CLONE_NEWUTS " (since Linux 2.6.19)" |
467 | If | |
468 | .B CLONE_NEWUTS | |
e1b11906 MK |
469 | is set, then create the process in a new UTS namespace, |
470 | whose identifiers are initialized by duplicating the identifiers | |
471 | from the UTS namespace of the calling process. | |
43ce9dda | 472 | If this flag is not set, then (as with |
57ef8c39 | 473 | .BR fork (2)) |
43ce9dda MK |
474 | the process is created in the same UTS namespace as |
475 | the calling process. | |
0236bea9 | 476 | This flag is intended for the implementation of containers. |
efeece04 | 477 | .IP |
43ce9dda MK |
478 | A UTS namespace is the set of identifiers returned by |
479 | .BR uname (2); | |
850905cf | 480 | among these, the domain name and the hostname can be modified by |
43ce9dda MK |
481 | .BR setdomainname (2) |
482 | and | |
43ce9dda MK |
483 | .BR sethostname (2), |
484 | respectively. | |
c440fe01 MK |
485 | Changes made to the identifiers in a UTS namespace |
486 | are visible to all other processes in the same namespace, | |
43ce9dda | 487 | but are not visible to processes in other UTS namespaces. |
efeece04 | 488 | .IP |
ab5dd83f MK |
489 | Only a privileged process |
490 | .RB ( CAP_SYS_ADMIN ) | |
491 | can employ | |
492 | .BR CLONE_NEWUTS . | |
efeece04 | 493 | .IP |
83d9e9b2 | 494 | For further information on UTS namespaces, see |
9cc7ad66 | 495 | .BR namespaces (7). |
43ce9dda | 496 | .TP |
f5dbc7c8 MK |
497 | .BR CLONE_PARENT " (since Linux 2.3.12)" |
498 | If | |
499 | .B CLONE_PARENT | |
500 | is set, then the parent of the new child (as returned by | |
501 | .BR getppid (2)) | |
502 | will be the same as that of the calling process. | |
efeece04 | 503 | .IP |
f5dbc7c8 MK |
504 | If |
505 | .B CLONE_PARENT | |
506 | is not set, then (as with | |
507 | .BR fork (2)) | |
508 | the child's parent is the calling process. | |
efeece04 | 509 | .IP |
f5dbc7c8 MK |
510 | Note that it is the parent process, as returned by |
511 | .BR getppid (2), | |
512 | which is signaled when the child terminates, so that | |
513 | if | |
514 | .B CLONE_PARENT | |
515 | is set, then the parent of the calling process, rather than the | |
516 | calling process itself, will be signaled. | |
517 | .TP | |
518 | .BR CLONE_PARENT_SETTID " (since Linux 2.5.49)" | |
8ef021ea | 519 | Store the child thread ID at the location |
d3dbc9b1 | 520 | .I ptid |
8ef021ea | 521 | in the parent's memory. |
f5dbc7c8 MK |
522 | (In Linux 2.5.32-2.5.48 there was a flag |
523 | .B CLONE_SETTID | |
524 | that did this.) | |
b5da2f91 MK |
525 | The store operation completes before |
526 | .BR clone () | |
527 | returns control to user space. | |
f5dbc7c8 | 528 | .TP |
1c173eb3 | 529 | .BR CLONE_PID " (Linux 2.0 to 2.5.15)" |
f5dbc7c8 MK |
530 | If |
531 | .B CLONE_PID | |
532 | is set, the child process is created with the same process ID as | |
533 | the calling process. | |
534 | This is good for hacking the system, but otherwise | |
535 | of not much use. | |
1c173eb3 | 536 | From Linux 2.3.21 onward, this flag could be |
f5dbc7c8 | 537 | specified only by the system boot process (PID 0). |
1c173eb3 MK |
538 | The flag disappeared completely from the kernel sources in Linux 2.5.16. |
539 | Since then, the kernel silently ignores this bit if it is specified in | |
540 | .IR flags . | |
f5dbc7c8 | 541 | .TP |
1603d6a1 | 542 | .BR CLONE_PTRACE " (since Linux 2.2)" |
f5dbc7c8 MK |
543 | If |
544 | .B CLONE_PTRACE | |
545 | is specified, and the calling process is being traced, | |
546 | then trace the child also (see | |
547 | .BR ptrace (2)). | |
548 | .TP | |
549 | .BR CLONE_SETTLS " (since Linux 2.5.32)" | |
dd6d3d2e | 550 | The TLS (Thread Local Storage) descriptor is set to |
2551f801 | 551 | .IR newtls . |
efeece04 | 552 | .IP |
dd6d3d2e KF |
553 | The interpretation of |
554 | .I newtls | |
555 | and the resulting effect is architecture dependent. | |
556 | On x86, | |
f5dbc7c8 | 557 | .I newtls |
dd6d3d2e | 558 | is interpreted as a |
2551f801 | 559 | .IR "struct user_desc\ *" |
35bf8cb4 | 560 | (see |
dd6d3d2e | 561 | .BR set_thread_area (2)). |
9ea5bc66 | 562 | On x86-64 it is the new value to be set for the %fs base register |
35bf8cb4 | 563 | (see the |
2551f801 | 564 | .B ARCH_SET_FS |
dd6d3d2e KF |
565 | argument to |
566 | .BR arch_prctl (2)). | |
567 | On architectures with a dedicated TLS register, it is the new value | |
568 | of that register. | |
f5dbc7c8 | 569 | .TP |
1603d6a1 | 570 | .BR CLONE_SIGHAND " (since Linux 2.0)" |
fea681da MK |
571 | If |
572 | .B CLONE_SIGHAND | |
314c8ff4 | 573 | is set, the calling process and the child process share the same table of |
c13182ef MK |
574 | signal handlers. |
575 | If the calling process or child process calls | |
fea681da | 576 | .BR sigaction (2) |
c13182ef MK |
577 | to change the behavior associated with a signal, the behavior is |
578 | changed in the other process as well. | |
579 | However, the calling process and child | |
fea681da | 580 | processes still have distinct signal masks and sets of pending |
c13182ef | 581 | signals. |
4ba17a6d | 582 | So, one of them may block or unblock signals using |
fea681da MK |
583 | .BR sigprocmask (2) |
584 | without affecting the other process. | |
efeece04 | 585 | .IP |
fea681da MK |
586 | If |
587 | .B CLONE_SIGHAND | |
588 | is not set, the child process inherits a copy of the signal handlers | |
589 | of the calling process at the time | |
edcc65ff | 590 | .BR clone () |
c13182ef MK |
591 | is called. |
592 | Calls to | |
fea681da MK |
593 | .BR sigaction (2) |
594 | performed later by one of the processes have no effect on the other | |
595 | process. | |
efeece04 | 596 | .IP |
d6bec36e MK |
597 | Since Linux 2.6.0, |
598 | .\" Precisely: Linux 2.6.0-test6 | |
29546c24 MK |
599 | .I flags |
600 | must also include | |
601 | .B CLONE_VM | |
602 | if | |
603 | .B CLONE_SIGHAND | |
604 | is specified | |
fea681da | 605 | .TP |
d6bec36e MK |
606 | .BR CLONE_STOPPED " (since Linux 2.6.0)" |
607 | .\" Precisely: Linux 2.6.0-test2 | |
a69b6bda MK |
608 | If |
609 | .B CLONE_STOPPED | |
610 | is set, then the child is initially stopped (as though it was sent a | |
611 | .B SIGSTOP | |
612 | signal), and must be resumed by sending it a | |
613 | .B SIGCONT | |
614 | signal. | |
efeece04 | 615 | .IP |
a60450a9 MK |
616 | This flag was |
617 | .I deprecated | |
618 | from Linux 2.6.25 onward, | |
619 | and was | |
620 | .I removed | |
28b44abc MK |
621 | altogether in Linux 2.6.38. |
622 | Since then, the kernel silently ignores it without error. | |
a5a061ee | 623 | .\" glibc 2.8 removed this defn from bits/sched.h |
c5af0674 MK |
624 | Starting with Linux 4.6, the same bit was reused for the |
625 | .BR CLONE_NEWCGROUP | |
626 | flag. | |
a69b6bda | 627 | .TP |
f5dbc7c8 | 628 | .BR CLONE_SYSVSEM " (since Linux 2.5.10)" |
fea681da | 629 | If |
f5dbc7c8 MK |
630 | .B CLONE_SYSVSEM |
631 | is set, then the child and the calling process share | |
5ada4b94 MK |
632 | a single list of System V semaphore adjustment |
633 | .RI ( semadj ) | |
634 | values (see | |
f5dbc7c8 | 635 | .BR semop (2)). |
5ada4b94 MK |
636 | In this case, the shared list accumulates |
637 | .I semadj | |
638 | values across all processes sharing the list, | |
639 | and semaphore adjustments are performed only when the last process | |
640 | that is sharing the list terminates (or ceases sharing the list using | |
641 | .BR unshare (2)). | |
f5d401dd | 642 | If this flag is not set, then the child has a separate |
5ada4b94 MK |
643 | .I semadj |
644 | list that is initially empty. | |
fea681da | 645 | .TP |
d6bec36e MK |
646 | .BR CLONE_THREAD " (since Linux 2.4.0)" |
647 | .\" Precisely: Linux 2.6.0-test8 | |
fea681da MK |
648 | If |
649 | .B CLONE_THREAD | |
650 | is set, the child is placed in the same thread group as the calling process. | |
fd8a5be4 MK |
651 | To make the remainder of the discussion of |
652 | .B CLONE_THREAD | |
653 | more readable, the term "thread" is used to refer to the | |
654 | processes within a thread group. | |
efeece04 | 655 | .IP |
fd8a5be4 MK |
656 | Thread groups were a feature added in Linux 2.4 to support the |
657 | POSIX threads notion of a set of threads that share a single PID. | |
658 | Internally, this shared PID is the so-called | |
659 | thread group identifier (TGID) for the thread group. | |
c13182ef | 660 | Since Linux 2.4, calls to |
fea681da | 661 | .BR getpid (2) |
fd8a5be4 | 662 | return the TGID of the caller. |
efeece04 | 663 | .IP |
fd8a5be4 MK |
664 | The threads within a group can be distinguished by their (system-wide) |
665 | unique thread IDs (TID). | |
666 | A new thread's TID is available as the function result | |
667 | returned to the caller of | |
668 | .BR clone (), | |
669 | and a thread can obtain | |
670 | its own TID using | |
671 | .BR gettid (2). | |
efeece04 | 672 | .IP |
c13182ef | 673 | When a call is made to |
fd8a5be4 MK |
674 | .BR clone () |
675 | without specifying | |
676 | .BR CLONE_THREAD , | |
677 | then the resulting thread is placed in a new thread group | |
678 | whose TGID is the same as the thread's TID. | |
679 | This thread is the | |
680 | .I leader | |
681 | of the new thread group. | |
efeece04 | 682 | .IP |
fd8a5be4 MK |
683 | A new thread created with |
684 | .B CLONE_THREAD | |
685 | has the same parent process as the caller of | |
686 | .BR clone () | |
c13182ef | 687 | (i.e., like |
fd8a5be4 MK |
688 | .BR CLONE_PARENT ), |
689 | so that calls to | |
690 | .BR getppid (2) | |
691 | return the same value for all of the threads in a thread group. | |
692 | When a | |
c13182ef | 693 | .B CLONE_THREAD |
fd8a5be4 MK |
694 | thread terminates, the thread that created it using |
695 | .BR clone () | |
696 | is not sent a | |
697 | .B SIGCHLD | |
698 | (or other termination) signal; | |
699 | nor can the status of such a thread be obtained | |
700 | using | |
701 | .BR wait (2). | |
702 | (The thread is said to be | |
703 | .IR detached .) | |
efeece04 | 704 | .IP |
e2fbf61d MK |
705 | After all of the threads in a thread group terminate |
706 | the parent process of the thread group is sent a | |
fd8a5be4 MK |
707 | .B SIGCHLD |
708 | (or other termination) signal. | |
efeece04 | 709 | .IP |
fd8a5be4 MK |
710 | If any of the threads in a thread group performs an |
711 | .BR execve (2), | |
712 | then all threads other than the thread group leader are terminated, | |
713 | and the new program is executed in the thread group leader. | |
efeece04 | 714 | .IP |
f7110f60 MK |
715 | If one of the threads in a thread group creates a child using |
716 | .BR fork (2), | |
717 | then any thread in the group can | |
718 | .BR wait (2) | |
719 | for that child. | |
efeece04 | 720 | .IP |
edcc65ff | 721 | Since Linux 2.5.35, |
fd8a5be4 MK |
722 | .I flags |
723 | must also include | |
724 | .B CLONE_SIGHAND | |
725 | if | |
726 | .B CLONE_THREAD | |
6fd69f33 | 727 | is specified |
d6bec36e MK |
728 | (and note that, since Linux 2.6.0, |
729 | .\" Precisely: Linux 2.6.0-test6 | |
6fd69f33 MK |
730 | .BR CLONE_SIGHAND |
731 | also requires | |
732 | .BR CLONE_VM | |
733 | to be included). | |
efeece04 | 734 | .IP |
e2fbf61d MK |
735 | Signal dispositions and actions are process-wide: |
736 | if an unhandled signal is delivered to a thread, then | |
737 | it will affect (terminate, stop, continue, be ignored in) | |
738 | all members of the thread group. | |
efeece04 | 739 | .IP |
99408a60 | 740 | Each thread has its own signal mask, as set by |
f957eebd MK |
741 | .BR sigprocmask (2). |
742 | .IP | |
743 | A signal may be process-directed or thread-directed. | |
744 | A process-directed signal is targeted at a thread group (i.e., a TGID), | |
745 | and is delivered to an arbitrarily selected thread from among those | |
746 | that are not blocking the signal. | |
9d32816b | 747 | A signal may be process directed because it was generated by the kernel |
f957eebd MK |
748 | for reasons other than a hardware exception, or because it was sent using |
749 | .BR kill (2) | |
750 | or | |
751 | .BR sigqueue (3). | |
752 | A thread-directed signal is targeted at (i.e., delivered to) | |
753 | a specific thread. | |
754 | A signal may be thread directed because it was sent using | |
755 | .BR tgkill (2) | |
756 | or | |
757 | .BR pthread_sigqueue (3), | |
758 | or because the thread executed a machine language instruction that triggered | |
759 | a hardware exception | |
760 | (e.g., invalid memory access triggering | |
761 | .BR SIGSEGV | |
762 | or a floating-point exception triggering | |
763 | .BR SIGFPE ). | |
764 | .IP | |
99408a60 MK |
765 | A call to |
766 | .BR sigpending (2) | |
f957eebd MK |
767 | returns a signal set that is the union of the pending process-directed |
768 | signals and the signals that are pending for the calling thread. | |
efeece04 | 769 | .IP |
475c2753 | 770 | If a process-directed signal is delivered to a thread group, |
e2fbf61d MK |
771 | and the thread group has installed a handler for the signal, then |
772 | the handler will be invoked in exactly one, arbitrarily selected | |
773 | member of the thread group that has not blocked the signal. | |
c13182ef | 774 | If multiple threads in a group are waiting to accept the same signal using |
e2fbf61d MK |
775 | .BR sigwaitinfo (2), |
776 | the kernel will arbitrarily select one of these threads | |
475c2753 | 777 | to receive the signal. |
a69b6bda | 778 | .TP |
f5dbc7c8 | 779 | .BR CLONE_UNTRACED " (since Linux 2.5.46)" |
a69b6bda | 780 | If |
f5dbc7c8 MK |
781 | .B CLONE_UNTRACED |
782 | is specified, then a tracing process cannot force | |
783 | .B CLONE_PTRACE | |
784 | on this child process. | |
fea681da | 785 | .TP |
1603d6a1 | 786 | .BR CLONE_VFORK " (since Linux 2.2)" |
f5dbc7c8 MK |
787 | If |
788 | .B CLONE_VFORK | |
789 | is set, the execution of the calling process is suspended | |
790 | until the child releases its virtual memory | |
791 | resources via a call to | |
792 | .BR execve (2) | |
793 | or | |
794 | .BR _exit (2) | |
795 | (as with | |
796 | .BR vfork (2)). | |
efeece04 | 797 | .IP |
f5dbc7c8 MK |
798 | If |
799 | .B CLONE_VFORK | |
4b4a853a | 800 | is not set, then both the calling process and the child are schedulable |
f5dbc7c8 MK |
801 | after the call, and an application should not rely on execution occurring |
802 | in any particular order. | |
fea681da | 803 | .TP |
1603d6a1 | 804 | .BR CLONE_VM " (since Linux 2.0)" |
f5dbc7c8 MK |
805 | If |
806 | .B CLONE_VM | |
807 | is set, the calling process and the child process run in the same memory | |
808 | space. | |
809 | In particular, memory writes performed by the calling process | |
810 | or by the child process are also visible in the other process. | |
811 | Moreover, any memory mapping or unmapping performed with | |
812 | .BR mmap (2) | |
813 | or | |
814 | .BR munmap (2) | |
815 | by the child or calling process also affects the other process. | |
efeece04 | 816 | .IP |
f5dbc7c8 MK |
817 | If |
818 | .B CLONE_VM | |
819 | is not set, the child process runs in a separate copy of the memory | |
820 | space of the calling process at the time of | |
821 | .BR clone (). | |
822 | Memory writes or file mappings/unmappings performed by one of the | |
823 | processes do not affect the other, as with | |
824 | .BR fork (2). | |
1874193e | 825 | .SH NOTES |
1c6ebc4b MK |
826 | Note that the glibc |
827 | .BR clone () | |
828 | wrapper function makes some changes | |
829 | in the memory pointed to by | |
830 | .I child_stack | |
831 | (changes required to set the stack up correctly for the child) | |
832 | .I before | |
833 | invoking the | |
834 | .BR clone () | |
835 | system call. | |
836 | So, in cases where | |
837 | .BR clone () | |
838 | is used to recursively create children, | |
839 | do not use the buffer employed for the parent's stack | |
840 | as the stack of the child. | |
841 | .\" | |
0722a578 | 842 | .SS C library/kernel differences |
e585064b MK |
843 | The raw |
844 | .BR clone () | |
fea681da MK |
845 | system call corresponds more closely to |
846 | .BR fork (2) | |
847 | in that execution in the child continues from the point of the | |
c13182ef | 848 | call. |
5add3af3 MK |
849 | As such, the |
850 | .I fn | |
c13182ef | 851 | and |
5add3af3 MK |
852 | .I arg |
853 | arguments of the | |
854 | .BR clone () | |
855 | wrapper function are omitted. | |
161fce30 | 856 | .PP |
b219e68c | 857 | Another difference for the raw |
d35f5c34 | 858 | .BR clone () |
b219e68c MK |
859 | system call is that the |
860 | .I child_stack | |
82f9cb98 | 861 | argument may be NULL, |
b219e68c MK |
862 | in which case the child uses a duplicate of the parent's stack. |
863 | (Copy-on-write semantics ensure that the child gets separate copies | |
864 | of stack pages when either process modifies the stack.) | |
865 | In this case, for correct operation, the | |
866 | .B CLONE_VM | |
867 | option should not be specified. | |
d35f5c34 MK |
868 | (If the child |
869 | .I shares | |
870 | the parent's memory because of the use of the | |
871 | .BR CLONE_VM | |
b219e68c MK |
872 | flag, |
873 | then no copy-on-write duplication occurs and chaos is likely to result.) | |
d35f5c34 | 874 | .PP |
161fce30 MK |
875 | The order of the arguments also differs in the raw system call, |
876 | and there are variations in the arguments across architectures, | |
877 | as detailed in the following paragraphs. | |
efeece04 | 878 | .PP |
2a15a76b | 879 | The raw system call interface on x86-64 and some other architectures |
8016cc90 | 880 | (including sh, tile, ia-64, and alpha) is: |
efeece04 | 881 | .PP |
5add3af3 | 882 | .in +4 |
b76974c1 | 883 | .EX |
2a15a76b MK |
884 | .BI "long clone(unsigned long " flags ", void *" child_stack , |
885 | .BI " int *" ptid ", int *" ctid , | |
886 | .BI " unsigned long " newtls ); | |
b76974c1 | 887 | .EE |
2a15a76b | 888 | .in |
efeece04 | 889 | .PP |
2a15a76b MK |
890 | On x86-32, and several other common architectures |
891 | (including score, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa, | |
892 | and MIPS), | |
893 | .\" CONFIG_CLONE_BACKWARDS | |
894 | the order of the last two arguments is reversed: | |
efeece04 | 895 | .PP |
2a15a76b | 896 | .in +4 |
b76974c1 | 897 | .EX |
5add3af3 | 898 | .BI "long clone(unsigned long " flags ", void *" child_stack , |
2a15a76b MK |
899 | .BI " int *" ptid ", unsigned long " newtls , |
900 | .BI " int *" ctid ); | |
b76974c1 | 901 | .EE |
2a15a76b | 902 | .in |
efeece04 | 903 | .PP |
2a15a76b MK |
904 | On the cris and s390 architectures, |
905 | .\" CONFIG_CLONE_BACKWARDS2 | |
906 | the order of the first two arguments is reversed: | |
efeece04 | 907 | .PP |
2a15a76b | 908 | .in +4 |
b76974c1 | 909 | .EX |
2a15a76b | 910 | .BI "long clone(void *" child_stack ", unsigned long " flags , |
fda55470 | 911 | .BI " int *" ptid ", int *" ctid , |
dd6d3d2e | 912 | .BI " unsigned long " newtls ); |
b76974c1 | 913 | .EE |
2a15a76b | 914 | .in |
efeece04 | 915 | .PP |
2a15a76b MK |
916 | On the microblaze architecture, |
917 | .\" CONFIG_CLONE_BACKWARDS3 | |
918 | an additional argument is supplied: | |
efeece04 | 919 | .PP |
2a15a76b | 920 | .in +4 |
b76974c1 | 921 | .EX |
2a15a76b MK |
922 | .BI "long clone(unsigned long " flags ", void *" child_stack , |
923 | .BI " int " stack_size , "\fR /* Size of stack */" | |
924 | .BI " int *" ptid ", int *" ctid , | |
925 | .BI " unsigned long " newtls ); | |
b76974c1 | 926 | .EE |
5add3af3 | 927 | .in |
2a15a76b | 928 | .\" |
251113d0 | 929 | .SS blackfin, m68k, and sparc |
2a15a76b MK |
930 | .\" Mike Frysinger noted in a 2013 mail: |
931 | .\" these arches don't define __ARCH_WANT_SYS_CLONE: | |
932 | .\" blackfin ia64 m68k sparc | |
251113d0 | 933 | The argument-passing conventions on |
04346be5 | 934 | blackfin, m68k, and sparc are different from the descriptions above. |
251113d0 | 935 | For details, see the kernel (and glibc) source. |
574c92b6 | 936 | .SS ia64 |
097a1f3b | 937 | On ia64, a different interface is used: |
7a346077 | 938 | .PP |
8016cc90 ES |
939 | .in +4 |
940 | .EX | |
097a1f3b MK |
941 | .BI "int __clone2(int (*" "fn" ")(void *), " |
942 | .BI " void *" child_stack_base ", size_t " stack_size , | |
943 | .BI " int " flags ", void *" "arg" ", ... " | |
944 | .BI " /* pid_t *" ptid ", struct user_desc *" tls \ | |
945 | ", pid_t *" ctid " */ );" | |
8016cc90 ES |
946 | .EE |
947 | .in | |
097a1f3b | 948 | .PP |
9b9c895c MK |
949 | The prototype shown above is for the glibc wrapper function; |
950 | for the system call itself, | |
951 | the prototype can be described as follows (it is identical to the | |
8016cc90 ES |
952 | .BR clone () |
953 | prototype on microblaze): | |
954 | .PP | |
955 | .in +4 | |
956 | .EX | |
957 | .BI "long clone2(unsigned long " flags ", void *" child_stack_base , | |
958 | .BI " int " stack_size , "\fR /* Size of stack */" | |
959 | .BI " int *" ptid ", int *" ctid , | |
960 | .BI " unsigned long " tls ); | |
961 | .EE | |
962 | .in | |
097a1f3b MK |
963 | .PP |
964 | .BR __clone2 () | |
965 | operates in the same way as | |
966 | .BR clone (), | |
967 | except that | |
968 | .I child_stack_base | |
969 | points to the lowest address of the child's stack area, | |
970 | and | |
971 | .I stack_size | |
972 | specifies the size of the stack pointed to by | |
973 | .IR child_stack_base . | |
5add3af3 | 974 | .SS Linux 2.4 and earlier |
577f9b62 MK |
975 | In Linux 2.4 and earlier, |
976 | .BR clone () | |
977 | does not take arguments | |
978 | .IR ptid , | |
979 | .IR tls , | |
980 | and | |
130b2e49 | 981 | .IR ctid . |
47297adb | 982 | .SH RETURN VALUE |
0bfa087b MK |
983 | .\" gettid(2) returns current->pid; |
984 | .\" getpid(2) returns current->tgid; | |
fea681da | 985 | On success, the thread ID of the child process is returned |
c13182ef | 986 | in the caller's thread of execution. |
84811e86 | 987 | On failure, \-1 is returned |
fea681da MK |
988 | in the caller's context, no child process will be created, and |
989 | .I errno | |
990 | will be set appropriately. | |
fea681da MK |
991 | .SH ERRORS |
992 | .TP | |
993 | .B EAGAIN | |
e1b6e186 MK |
994 | Too many processes are already running; see |
995 | .BR fork (2). | |
fea681da MK |
996 | .TP |
997 | .B EINVAL | |
998 | .B CLONE_SIGHAND | |
999 | was specified, but | |
1000 | .B CLONE_VM | |
2e8a7fb3 | 1001 | was not. |
d6bec36e MK |
1002 | (Since Linux 2.6.0.) |
1003 | .\" Precisely: Linux 2.6.0-test6 | |
fea681da MK |
1004 | .TP |
1005 | .B EINVAL | |
1006 | .B CLONE_THREAD | |
1007 | was specified, but | |
1008 | .B CLONE_SIGHAND | |
6387216b MK |
1009 | was not. |
1010 | (Since Linux 2.5.35.) | |
29546c24 MK |
1011 | .\" .TP |
1012 | .\" .B EINVAL | |
1013 | .\" Precisely one of | |
1014 | .\" .B CLONE_DETACHED | |
1015 | .\" and | |
1016 | .\" .B CLONE_THREAD | |
6387216b MK |
1017 | .\" was specified. |
1018 | .\" (Since Linux 2.6.0-test6.) | |
fea681da MK |
1019 | .TP |
1020 | .B EINVAL | |
d6868c69 JH |
1021 | .B CLONE_THREAD |
1022 | was specified, but the current process previously called | |
1023 | .BR unshare (2) | |
1024 | with the | |
1025 | .B CLONE_NEWPID | |
1026 | flag or used | |
1027 | .BR setns (2) | |
1028 | to reassociate itself with a PID namespace. | |
1029 | .TP | |
1030 | .B EINVAL | |
d34e5645 | 1031 | .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 |
fea681da MK |
1032 | Both |
1033 | .B CLONE_FS | |
1034 | and | |
1035 | .B CLONE_NEWNS | |
1036 | were specified in | |
1037 | .IR flags . | |
1038 | .TP | |
d34e5645 MK |
1039 | .BR EINVAL " (since Linux 3.9)" |
1040 | Both | |
1041 | .B CLONE_NEWUSER | |
1042 | and | |
1043 | .B CLONE_FS | |
1044 | were specified in | |
1045 | .IR flags . | |
1046 | .TP | |
fea681da | 1047 | .B EINVAL |
82ee147a | 1048 | Both |
667417b3 MK |
1049 | .B CLONE_NEWIPC |
1050 | and | |
1051 | .B CLONE_SYSVSEM | |
1052 | were specified in | |
1053 | .IR flags . | |
1054 | .TP | |
1055 | .B EINVAL | |
f0007192 | 1056 | One (or both) of |
82ee147a | 1057 | .BR CLONE_NEWPID |
f0007192 MK |
1058 | or |
1059 | .BR CLONE_NEWUSER | |
1060 | and one (or both) of | |
82ee147a | 1061 | .BR CLONE_THREAD |
f0007192 MK |
1062 | or |
1063 | .BR CLONE_PARENT | |
82ee147a MK |
1064 | were specified in |
1065 | .IR flags . | |
1066 | .TP | |
1067 | .B EINVAL | |
d4748fad | 1068 | Returned by the glibc |
edcc65ff | 1069 | .BR clone () |
d4748fad MK |
1070 | wrapper function when |
1071 | .IR fn | |
1072 | or | |
1073 | .IR child_stack | |
1074 | is specified as NULL. | |
fea681da | 1075 | .TP |
28cad2c1 | 1076 | .B EINVAL |
667417b3 MK |
1077 | .BR CLONE_NEWIPC |
1078 | was specified in | |
1079 | .IR flags , | |
1080 | but the kernel was not configured with the | |
1081 | .B CONFIG_SYSVIPC | |
1082 | and | |
1083 | .BR CONFIG_IPC_NS | |
1084 | options. | |
1085 | .TP | |
1086 | .B EINVAL | |
163bf178 MK |
1087 | .BR CLONE_NEWNET |
1088 | was specified in | |
1089 | .IR flags , | |
1090 | but the kernel was not configured with the | |
1091 | .B CONFIG_NET_NS | |
1092 | option. | |
1093 | .TP | |
1094 | .B EINVAL | |
28cad2c1 MK |
1095 | .BR CLONE_NEWPID |
1096 | was specified in | |
1097 | .IR flags , | |
1098 | but the kernel was not configured with the | |
1099 | .B CONFIG_PID_NS | |
1100 | option. | |
1101 | .TP | |
43ce9dda | 1102 | .B EINVAL |
231d0bbe MK |
1103 | .BR CLONE_NEWUSER |
1104 | was specified in | |
1105 | .IR flags , | |
1106 | but the kernel was not configured with the | |
1107 | .B CONFIG_USER_NS | |
1108 | option. | |
1109 | .TP | |
1110 | .B EINVAL | |
43ce9dda MK |
1111 | .BR CLONE_NEWUTS |
1112 | was specified in | |
1113 | .IR flags , | |
1114 | but the kernel was not configured with the | |
832fe8ea | 1115 | .B CONFIG_UTS_NS |
43ce9dda MK |
1116 | option. |
1117 | .TP | |
c550a897 MK |
1118 | .B EINVAL |
1119 | .I child_stack | |
1120 | is not aligned to a suitable boundary for this architecture. | |
1121 | For example, on aarch64, | |
1122 | .I child_stack | |
1123 | must be a multiple of 16. | |
1124 | .TP | |
fea681da MK |
1125 | .B ENOMEM |
1126 | Cannot allocate sufficient memory to allocate a task structure for the | |
1127 | child, or to copy those parts of the caller's context that need to be | |
1128 | copied. | |
1129 | .TP | |
b20e22ae MK |
1130 | .BR ENOSPC " (since Linux 3.7)" |
1131 | .\" commit f2302505775fd13ba93f034206f1e2a587017929 | |
1132 | .B CLONE_NEWPID | |
1133 | was specified in flags, | |
1134 | but the limit on the nesting depth of PID namespaces | |
1135 | would have been exceeded; see | |
1136 | .BR pid_namespaces (7). | |
1137 | .TP | |
b5742ecc MK |
1138 | .BR ENOSPC " (since Linux 4.9; beforehand " EUSERS ) |
1139 | .B CLONE_NEWUSER | |
1140 | was specified in | |
1141 | .IR flags , | |
1142 | and the call would cause the limit on the number of | |
1143 | nested user namespaces to be exceeded. | |
1144 | See | |
1145 | .BR user_namespaces (7). | |
efeece04 | 1146 | .IP |
b5742ecc MK |
1147 | From Linux 3.11 to Linux 4.8, the error diagnosed in this case was |
1148 | .BR EUSERS . | |
1149 | .TP | |
2f7a331e MK |
1150 | .BR ENOSPC " (since Linux 4.9)" |
1151 | One of the values in | |
1152 | .I flags | |
1153 | specified the creation of a new user namespace, | |
1154 | but doing so would have caused the limit defined by the corresponding file in | |
1155 | .IR /proc/sys/user | |
1156 | to be exceeded. | |
1157 | For further details, see | |
1158 | .BR namespaces (7). | |
1159 | .TP | |
fea681da | 1160 | .B EPERM |
aa825b59 | 1161 | .BR CLONE_NEWCGROUP , |
667417b3 | 1162 | .BR CLONE_NEWIPC , |
163bf178 | 1163 | .BR CLONE_NEWNET , |
43ce9dda MK |
1164 | .BR CLONE_NEWNS , |
1165 | .BR CLONE_NEWPID , | |
82ee147a | 1166 | or |
43ce9dda | 1167 | .BR CLONE_NEWUTS |
00b08db3 | 1168 | was specified by an unprivileged process (process without \fBCAP_SYS_ADMIN\fP). |
fea681da MK |
1169 | .TP |
1170 | .B EPERM | |
1171 | .B CLONE_PID | |
1172 | was specified by a process other than process 0. | |
1c173eb3 | 1173 | (This error occurs only on Linux 2.5.15 and earlier.) |
365d292a MK |
1174 | .TP |
1175 | .B EPERM | |
1176 | .BR CLONE_NEWUSER | |
1177 | was specified in | |
1178 | .IR flags , | |
1179 | but either the effective user ID or the effective group ID of the caller | |
1180 | does not have a mapping in the parent namespace (see | |
f58fb24f | 1181 | .BR user_namespaces (7)). |
6fd119e7 | 1182 | .TP |
ac007938 MK |
1183 | .BR EPERM " (since Linux 3.9)" |
1184 | .\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d | |
11a38815 AM |
1185 | .B CLONE_NEWUSER |
1186 | was specified in | |
ac007938 MK |
1187 | .I flags |
1188 | and the caller is in a chroot environment | |
1189 | .\" FIXME What is the rationale for this restriction? | |
1190 | (i.e., the caller's root directory does not match the root directory | |
1191 | of the mount namespace in which it resides). | |
1192 | .TP | |
6717ee86 MK |
1193 | .BR ERESTARTNOINTR " (since Linux 2.6.17)" |
1194 | .\" commit 4a2c7a7837da1b91468e50426066d988050e4d56 | |
1195 | System call was interrupted by a signal and will be restarted. | |
1196 | (This can be seen only during a trace.) | |
1197 | .TP | |
b5742ecc | 1198 | .BR EUSERS " (Linux 3.11 to Linux 4.8)" |
6fd119e7 MK |
1199 | .B CLONE_NEWUSER |
1200 | was specified in | |
1201 | .IR flags , | |
b5742ecc MK |
1202 | and the limit on the number of nested user namespaces would be exceeded. |
1203 | See the discussion of the | |
1204 | .BR ENOSPC | |
1205 | error above. | |
92b72224 MK |
1206 | .\" .SH VERSIONS |
1207 | .\" There is no entry for | |
1208 | .\" .BR clone () | |
1209 | .\" in libc5. | |
1210 | .\" glibc2 provides | |
1211 | .\" .BR clone () | |
1212 | .\" as described in this manual page. | |
47297adb | 1213 | .SH CONFORMING TO |
a1d5f77c | 1214 | .BR clone () |
e585064b | 1215 | is Linux-specific and should not be used in programs |
a1d5f77c | 1216 | intended to be portable. |
fea681da | 1217 | .SH NOTES |
79bdcc4a MK |
1218 | The |
1219 | .BR kcmp (2) | |
1220 | system call can be used to test whether two processes share various | |
49dba87f | 1221 | resources such as a file descriptor table, |
79bdcc4a | 1222 | System V semaphore undo operations, or a virtual address space. |
efeece04 MK |
1223 | .PP |
1224 | .PP | |
c471c363 MK |
1225 | Handlers registered using |
1226 | .BR pthread_atfork (3) | |
1227 | are not executed during a call to | |
1228 | .BR clone (). | |
efeece04 | 1229 | .PP |
ca8b1e32 | 1230 | In the Linux 2.4.x series, |
fd8a5be4 MK |
1231 | .B CLONE_THREAD |
1232 | generally does not make the parent of the new thread the same | |
1233 | as the parent of the calling process. | |
1234 | However, for kernel versions 2.4.7 to 2.4.18 the | |
1235 | .B CLONE_THREAD | |
1236 | flag implied the | |
c13182ef | 1237 | .B CLONE_PARENT |
ca8b1e32 | 1238 | flag (as in Linux 2.6.0 and later). |
efeece04 | 1239 | .PP |
c13182ef MK |
1240 | For a while there was |
1241 | .B CLONE_DETACHED | |
a5053dcb | 1242 | (introduced in 2.5.32): |
c13182ef | 1243 | parent wants no child-exit signal. |
4d543007 | 1244 | In Linux 2.6.2, the need to give this flag together with |
c13182ef | 1245 | .B CLONE_THREAD |
a5053dcb MK |
1246 | disappeared. |
1247 | This flag is still defined, but has no effect. | |
efeece04 | 1248 | .PP |
34ccb744 | 1249 | On i386, |
a5a997ca MK |
1250 | .BR clone () |
1251 | should not be called through vsyscall, but directly through | |
1252 | .IR "int $0x80" . | |
31830ef0 | 1253 | .SH BUGS |
abcf3b1d MK |
1254 | GNU C library versions 2.3.4 up to and including 2.24 |
1255 | contained a wrapper function for | |
0bfa087b | 1256 | .BR getpid (2) |
abcf3b1d MK |
1257 | that performed caching of PIDs. |
1258 | This caching relied on support in the glibc wrapper for | |
c60237c9 | 1259 | .BR clone (), |
abcf3b1d MK |
1260 | but limitations in the implementation |
1261 | meant that the cache was not up to date in some circumstances. | |
c60237c9 | 1262 | In particular, |
abcf3b1d | 1263 | if a signal was delivered to the child immediately after the |
c60237c9 MK |
1264 | .BR clone () |
1265 | call, then a call to | |
0b80cf56 | 1266 | .BR getpid (2) |
abcf3b1d | 1267 | in a handler for the signal could return the PID |
c60237c9 | 1268 | of the calling process ("the parent"), |
abcf3b1d | 1269 | if the clone wrapper had not yet had a chance to update the PID |
c60237c9 MK |
1270 | cache in the child. |
1271 | (This discussion ignores the case where the child was created using | |
9291ce36 | 1272 | .BR CLONE_THREAD , |
c60237c9 | 1273 | when |
0b80cf56 | 1274 | .BR getpid (2) |
c60237c9 MK |
1275 | .I should |
1276 | return the same value in the child and in the process that called | |
1277 | .BR clone (), | |
a1d48abb | 1278 | since the caller and the child are in the same thread group. |
e7d807b7 | 1279 | The stale-cache problem also does not occur if the |
a1d48abb JR |
1280 | .I flags |
1281 | argument includes | |
1282 | .BR CLONE_VM .) | |
abcf3b1d MK |
1283 | To get the truth, it was sometimes necessary to use code such as the following: |
1284 | .PP | |
47f743f1 MK |
1285 | .in +4n |
1286 | .EX | |
1287 | #include <syscall.h> | |
31830ef0 | 1288 | |
47f743f1 | 1289 | pid_t mypid; |
31830ef0 | 1290 | |
47f743f1 MK |
1291 | mypid = syscall(SYS_getpid); |
1292 | .EE | |
1293 | .in | |
c60237c9 MK |
1294 | .\" See also the following bug reports |
1295 | .\" https://bugzilla.redhat.com/show_bug.cgi?id=417521 | |
1296 | .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910 | |
abcf3b1d MK |
1297 | .PP |
1298 | Because of the stale-cache problem, as well as other problems noted in | |
1299 | .BR getpid (2), | |
1300 | the PID caching feature was removed in glibc 2.25. | |
8c7b566c | 1301 | .SH EXAMPLE |
8c7b566c | 1302 | The following program demonstrates the use of |
9c13072a | 1303 | .BR clone () |
8c7b566c MK |
1304 | to create a child process that executes in a separate UTS namespace. |
1305 | The child changes the hostname in its UTS namespace. | |
1306 | Both parent and child then display the system hostname, | |
1307 | making it possible to see that the hostname | |
1308 | differs in the UTS namespaces of the parent and child. | |
1309 | For an example of the use of this program, see | |
1310 | .BR setns (2). | |
f30b7415 | 1311 | .SS Program source |
e7d0bb47 | 1312 | .EX |
8c7b566c MK |
1313 | #define _GNU_SOURCE |
1314 | #include <sys/wait.h> | |
1315 | #include <sys/utsname.h> | |
1316 | #include <sched.h> | |
1317 | #include <string.h> | |
1318 | #include <stdio.h> | |
1319 | #include <stdlib.h> | |
1320 | #include <unistd.h> | |
1321 | ||
d1a71985 | 1322 | #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e |
8c7b566c MK |
1323 | } while (0) |
1324 | ||
1325 | static int /* Start function for cloned child */ | |
1326 | childFunc(void *arg) | |
1327 | { | |
1328 | struct utsname uts; | |
1329 | ||
1330 | /* Change hostname in UTS namespace of child */ | |
1331 | ||
1332 | if (sethostname(arg, strlen(arg)) == \-1) | |
1333 | errExit("sethostname"); | |
1334 | ||
07d4e6ea | 1335 | /* Retrieve and display hostname */ |
8c7b566c MK |
1336 | |
1337 | if (uname(&uts) == \-1) | |
1338 | errExit("uname"); | |
d1a71985 | 1339 | printf("uts.nodename in child: %s\en", uts.nodename); |
8c7b566c MK |
1340 | |
1341 | /* Keep the namespace open for a while, by sleeping. | |
1342 | This allows some experimentation\-\-for example, another | |
1343 | process might join the namespace. */ | |
9f1b9726 | 1344 | |
8c7b566c MK |
1345 | sleep(200); |
1346 | ||
1347 | return 0; /* Child terminates now */ | |
1348 | } | |
1349 | ||
1350 | #define STACK_SIZE (1024 * 1024) /* Stack size for cloned child */ | |
1351 | ||
1352 | int | |
1353 | main(int argc, char *argv[]) | |
1354 | { | |
1355 | char *stack; /* Start of stack buffer */ | |
1356 | char *stackTop; /* End of stack buffer */ | |
1357 | pid_t pid; | |
1358 | struct utsname uts; | |
1359 | ||
1360 | if (argc < 2) { | |
d1a71985 | 1361 | fprintf(stderr, "Usage: %s <child\-hostname>\en", argv[0]); |
8c7b566c MK |
1362 | exit(EXIT_SUCCESS); |
1363 | } | |
1364 | ||
1365 | /* Allocate stack for child */ | |
1366 | ||
1367 | stack = malloc(STACK_SIZE); | |
1368 | if (stack == NULL) | |
1369 | errExit("malloc"); | |
1370 | stackTop = stack + STACK_SIZE; /* Assume stack grows downward */ | |
1371 | ||
1372 | /* Create child that has its own UTS namespace; | |
1373 | child commences execution in childFunc() */ | |
1374 | ||
1375 | pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]); | |
1376 | if (pid == \-1) | |
1377 | errExit("clone"); | |
d1a71985 | 1378 | printf("clone() returned %ld\en", (long) pid); |
8c7b566c MK |
1379 | |
1380 | /* Parent falls through to here */ | |
1381 | ||
1382 | sleep(1); /* Give child time to change its hostname */ | |
1383 | ||
9f1b9726 | 1384 | /* Display hostname in parent\(aqs UTS namespace. This will be |
8c7b566c MK |
1385 | different from hostname in child\(aqs UTS namespace. */ |
1386 | ||
1387 | if (uname(&uts) == \-1) | |
1388 | errExit("uname"); | |
d1a71985 | 1389 | printf("uts.nodename in parent: %s\en", uts.nodename); |
8c7b566c MK |
1390 | |
1391 | if (waitpid(pid, NULL, 0) == \-1) /* Wait for child */ | |
1392 | errExit("waitpid"); | |
d1a71985 | 1393 | printf("child has terminated\en"); |
8c7b566c MK |
1394 | |
1395 | exit(EXIT_SUCCESS); | |
1396 | } | |
e7d0bb47 | 1397 | .EE |
47297adb | 1398 | .SH SEE ALSO |
fea681da | 1399 | .BR fork (2), |
2b44301c | 1400 | .BR futex (2), |
fea681da MK |
1401 | .BR getpid (2), |
1402 | .BR gettid (2), | |
6f8746e4 | 1403 | .BR kcmp (2), |
f2d0bbf1 | 1404 | .BR set_thread_area (2), |
2b44301c | 1405 | .BR set_tid_address (2), |
8403481f | 1406 | .BR setns (2), |
f2d0bbf1 | 1407 | .BR tkill (2), |
5cc01e9c | 1408 | .BR unshare (2), |
fea681da | 1409 | .BR wait (2), |
3616b7c0 | 1410 | .BR capabilities (7), |
41096af1 | 1411 | .BR namespaces (7), |
3616b7c0 | 1412 | .BR pthreads (7) |