]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
3 | .\" Copyright (c) 1992 Drew Eckhardt <drew@cs.colorado.edu>, March 28, 1992 | |
1130df60 | 4 | .\" and Copyright (c) Michael Kerrisk, 2001, 2002, 2005 |
fea681da MK |
5 | .\" May be distributed under the GNU General Public License. |
6 | .\" Modified by Michael Haardt <michael@moria.de> | |
7 | .\" Modified 24 Jul 1993 by Rik Faith <faith@cs.unc.edu> | |
8 | .\" Modified 21 Aug 1994 by Michael Chastain <mec@shell.portal.com>: | |
9 | .\" New man page (copied from 'fork.2'). | |
10 | .\" Modified 10 June 1995 by Andries Brouwer <aeb@cwi.nl> | |
11 | .\" Modified 25 April 1998 by Xavier Leroy <Xavier.Leroy@inria.fr> | |
12 | .\" Modified 26 Jun 2001 by Michael Kerrisk | |
13 | .\" Mostly upgraded to 2.4.x | |
14 | .\" Added prototype for sys_clone() plus description | |
15 | .\" Added CLONE_THREAD with a brief description of thread groups | |
c13182ef | 16 | .\" Added CLONE_PARENT and revised entire page remove ambiguity |
fea681da MK |
17 | .\" between "calling process" and "parent process" |
18 | .\" Added CLONE_PTRACE and CLONE_VFORK | |
19 | .\" Added EPERM and EINVAL error codes | |
fd8a5be4 | 20 | .\" Renamed "__clone" to "clone" (which is the prototype in <sched.h>) |
fea681da | 21 | .\" various other minor tidy ups and clarifications. |
c11b1abf | 22 | .\" Modified 26 Jun 2001 by Michael Kerrisk <mtk.manpages@gmail.com> |
d9bfdb9c | 23 | .\" Updated notes for 2.4.7+ behavior of CLONE_THREAD |
c11b1abf | 24 | .\" Modified 15 Oct 2002 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
25 | .\" Added description for CLONE_NEWNS, which was added in 2.4.19 |
26 | .\" Slightly rephrased, aeb. | |
27 | .\" Modified 1 Feb 2003 - added CLONE_SIGHAND restriction, aeb. | |
28 | .\" Modified 1 Jan 2004 - various updates, aeb | |
0967c11f | 29 | .\" Modified 2004-09-10 - added CLONE_PARENT_SETTID etc. - aeb. |
d9bfdb9c | 30 | .\" 2005-04-12, mtk, noted the PID caching behavior of NPTL's getpid() |
31830ef0 | 31 | .\" wrapper under BUGS. |
fd8a5be4 MK |
32 | .\" 2005-05-10, mtk, added CLONE_SYSVSEM, CLONE_UNTRACED, CLONE_STOPPED. |
33 | .\" 2005-05-17, mtk, Substantially enhanced discussion of CLONE_THREAD. | |
82ee147a MK |
34 | .\" 2008-11-18, mtk, order CLONE_* flags alphabetically |
35 | .\" 2008-11-18, mtk, document CLONE_NEWPID | |
43ce9dda | 36 | .\" 2008-11-19, mtk, document CLONE_NEWUTS |
667417b3 | 37 | .\" 2008-11-19, mtk, document CLONE_NEWIPC |
cfdc761b | 38 | .\" 2008-11-19, Jens Axboe, mtk, document CLONE_IO |
fea681da | 39 | .\" |
185341d4 MK |
40 | .\" FIXME Document CLONE_NEWUSER, which is new in 2.6.23 |
41 | .\" (also supported for unshare()?) | |
6807c79a | 42 | .\" FIXME . 2.6.25 marks the unused CLONE_STOPPED as obsolete, and it will |
21a0b03d | 43 | .\" probably be removed in the future. |
360ed6b3 | 44 | .\" |
732e54dd | 45 | .TH CLONE 2 2008-11-20 "Linux" "Linux Programmer's Manual" |
fea681da | 46 | .SH NAME |
9b0e0996 | 47 | clone, __clone2 \- create a child process |
fea681da | 48 | .SH SYNOPSIS |
c10859eb | 49 | .nf |
cc4615cc MK |
50 | .B #define _GNU_SOURCE |
51 | .\" Actually _BSD_SOURCE || _SVID_SOURCE | |
52 | .\" See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749 | |
fea681da | 53 | .B #include <sched.h> |
c10859eb | 54 | |
ff929e3b MK |
55 | .BI "int clone(int (*" "fn" ")(void *), void *" child_stack , |
56 | .BI " int " flags ", void *" "arg" ", ... " | |
57 | .BI " /* pid_t *" pid ", struct user_desc *" tls \ | |
58 | ", pid_t *" ctid " */ );" | |
c10859eb | 59 | .fi |
fea681da | 60 | .SH DESCRIPTION |
edcc65ff MK |
61 | .BR clone () |
62 | creates a new process, in a manner similar to | |
fea681da | 63 | .BR fork (2). |
735f354f | 64 | It is actually a library function layered on top of the underlying |
e511ffb6 | 65 | .BR clone () |
fea681da MK |
66 | system call, hereinafter referred to as |
67 | .BR sys_clone . | |
68 | A description of | |
0daa9e92 | 69 | .B sys_clone |
fea681da MK |
70 | is given towards the end of this page. |
71 | ||
72 | Unlike | |
73 | .BR fork (2), | |
c13182ef | 74 | these calls |
fea681da MK |
75 | allow the child process to share parts of its execution context with |
76 | the calling process, such as the memory space, the table of file | |
c13182ef MK |
77 | descriptors, and the table of signal handlers. |
78 | (Note that on this manual | |
79 | page, "calling process" normally corresponds to "parent process". | |
80 | But see the description of | |
81 | .B CLONE_PARENT | |
fea681da MK |
82 | below.) |
83 | ||
84 | The main use of | |
edcc65ff | 85 | .BR clone () |
fea681da MK |
86 | is to implement threads: multiple threads of control in a program that |
87 | run concurrently in a shared memory space. | |
88 | ||
89 | When the child process is created with | |
c13182ef | 90 | .BR clone (), |
fea681da MK |
91 | it executes the function |
92 | application | |
c13182ef | 93 | .IR fn ( arg ). |
fea681da | 94 | (This differs from |
c13182ef | 95 | .BR fork (2), |
fea681da | 96 | where execution continues in the child from the point |
c13182ef MK |
97 | of the |
98 | .BR fork (2) | |
fea681da MK |
99 | call.) |
100 | The | |
101 | .I fn | |
102 | argument is a pointer to a function that is called by the child | |
103 | process at the beginning of its execution. | |
104 | The | |
105 | .I arg | |
106 | argument is passed to the | |
107 | .I fn | |
108 | function. | |
109 | ||
c13182ef | 110 | When the |
fea681da | 111 | .IR fn ( arg ) |
c13182ef MK |
112 | function application returns, the child process terminates. |
113 | The integer returned by | |
fea681da | 114 | .I fn |
c13182ef MK |
115 | is the exit code for the child process. |
116 | The child process may also terminate explicitly by calling | |
fea681da MK |
117 | .BR exit (2) |
118 | or after receiving a fatal signal. | |
119 | ||
120 | The | |
121 | .I child_stack | |
c13182ef MK |
122 | argument specifies the location of the stack used by the child process. |
123 | Since the child and calling process may share memory, | |
fea681da | 124 | it is not possible for the child process to execute in the |
c13182ef MK |
125 | same stack as the calling process. |
126 | The calling process must therefore | |
fea681da MK |
127 | set up memory space for the child stack and pass a pointer to this |
128 | space to | |
edcc65ff | 129 | .BR clone (). |
fea681da MK |
130 | Stacks grow downwards on all processors that run Linux |
131 | (except the HP PA processors), so | |
132 | .I child_stack | |
133 | usually points to the topmost address of the memory space set up for | |
134 | the child stack. | |
135 | ||
136 | The low byte of | |
137 | .I flags | |
fd8a5be4 MK |
138 | contains the number of the |
139 | .I "termination signal" | |
140 | sent to the parent when the child dies. | |
141 | If this signal is specified as anything other than | |
fea681da MK |
142 | .BR SIGCHLD , |
143 | then the parent process must specify the | |
c13182ef MK |
144 | .B __WALL |
145 | or | |
fea681da | 146 | .B __WCLONE |
c13182ef MK |
147 | options when waiting for the child with |
148 | .BR wait (2). | |
fea681da MK |
149 | If no signal is specified, then the parent process is not signaled |
150 | when the child terminates. | |
151 | ||
152 | .I flags | |
fd8a5be4 MK |
153 | may also be bitwise-or'ed with zero or more of the following constants, |
154 | in order to specify what is shared between the calling process | |
fea681da | 155 | and the child process: |
fea681da | 156 | .TP |
f5dbc7c8 MK |
157 | .BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)" |
158 | Erase child thread ID at location | |
159 | .I child_tidptr | |
160 | in child memory when the child exits, and do a wakeup on the futex | |
161 | at that address. | |
162 | The address involved may be changed by the | |
163 | .BR set_tid_address (2) | |
164 | system call. | |
165 | This is used by threading libraries. | |
166 | .TP | |
167 | .BR CLONE_CHILD_SETTID " (since Linux 2.5.49)" | |
168 | Store child thread ID at location | |
169 | .I child_tidptr | |
170 | in child memory. | |
171 | .TP | |
172 | .B CLONE_FILES | |
fea681da | 173 | If |
f5dbc7c8 MK |
174 | .B CLONE_FILES |
175 | is set, the calling process and the child process share the same file | |
176 | descriptor table. | |
177 | Any file descriptor created by the calling process or by the child | |
178 | process is also valid in the other process. | |
179 | Similarly, if one of the processes closes a file descriptor, | |
180 | or changes its associated flags (using the | |
181 | .BR fcntl (2) | |
182 | .B F_SETFD | |
183 | operation), the other process is also affected. | |
fea681da MK |
184 | |
185 | If | |
f5dbc7c8 MK |
186 | .B CLONE_FILES |
187 | is not set, the child process inherits a copy of all file descriptors | |
188 | opened in the calling process at the time of | |
189 | .BR clone (). | |
190 | (The duplicated file descriptors in the child refer to the | |
191 | same open file descriptions (see | |
192 | .BR open (2)) | |
193 | as the corresponding file descriptors in the calling process.) | |
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. | |
fea681da MK |
198 | .TP |
199 | .B CLONE_FS | |
200 | If | |
201 | .B CLONE_FS | |
314c8ff4 | 202 | is set, the caller and the child process share the same file system |
c13182ef MK |
203 | information. |
204 | This includes the root of the file system, the current | |
205 | working directory, and the umask. | |
206 | Any call to | |
fea681da MK |
207 | .BR chroot (2), |
208 | .BR chdir (2), | |
209 | or | |
210 | .BR umask (2) | |
edcc65ff | 211 | performed by the calling process or the child process also affects the |
fea681da MK |
212 | other process. |
213 | ||
c13182ef | 214 | If |
fea681da MK |
215 | .B CLONE_FS |
216 | is not set, the child process works on a copy of the file system | |
217 | information of the calling process at the time of the | |
edcc65ff | 218 | .BR clone () |
fea681da MK |
219 | call. |
220 | Calls to | |
221 | .BR chroot (2), | |
222 | .BR chdir (2), | |
223 | .BR umask (2) | |
224 | performed later by one of the processes do not affect the other process. | |
fea681da | 225 | .TP |
a4cc375e | 226 | .BR CLONE_IO " (since Linux 2.6.25)" |
11f27a1c JA |
227 | If |
228 | .B CLONE_IO | |
229 | is set, then the new process shares an I/O context with | |
230 | the calling process. | |
231 | If this flag is not set, then (as with | |
232 | .BR fork (2)) | |
233 | the new process has its own I/O context. | |
234 | ||
235 | .\" The following based on text from Jens Axboe | |
236 | The I/O context is the I/O scope of the disk scheduler (i.e, | |
237 | what the I/O scheduler uses to model scheduling of a process's I/O). | |
238 | If processes share the same I/O context, | |
239 | they are treated as one by the I/O scheduler. | |
240 | As a consequence, they get to share disk time. | |
241 | For some I/O schedulers, | |
242 | .\" the anticipatory and CFQ scheduler | |
243 | if two processes share an I/O context, | |
244 | they will be allowed to interleave their disk access. | |
245 | If several threads are doing I/O on behalf of the same process | |
246 | .RB ( aio_read (3), | |
247 | for instance), they should employ | |
248 | .BR CLONE_IO | |
249 | to get better I/O performance. | |
250 | .\" with CFQ and AS. | |
251 | ||
252 | If the kernel is not configured with the | |
253 | .B CONFIG_BLOCK | |
254 | option, this flag is a no-op. | |
255 | .TP | |
667417b3 MK |
256 | .BR CLONE_NEWIPC " (since Linux 2.4.19)" |
257 | If | |
258 | .B CLONE_NEWIPC | |
259 | is set, then create the process in a new IPC namespace. | |
260 | If this flag is not set, then (as with | |
261 | .BR fork (2)), | |
262 | the process is created in the same IPC namespace as | |
263 | the calling process. | |
0236bea9 | 264 | This flag is intended for the implementation of containers. |
667417b3 MK |
265 | |
266 | An IPC namespace consists of the set of identifiers for | |
267 | System V IPC objects. | |
268 | (These objects are created using | |
269 | .BR msgctl (2), | |
270 | .BR semctl (2), | |
271 | and | |
272 | .BR shmctl (2)). | |
273 | Objects created in an IPC namespace are visible to other processes | |
274 | that are members of that namespace, | |
275 | but are not visible to processes in other IPC namespaces. | |
276 | ||
83c1f4b5 MK |
277 | When an IPC namespace is destroyed |
278 | (i.e, when the last process that is a member of the namespace terminates), | |
279 | all IPC objects in the namespace are automatically destroyed. | |
280 | ||
667417b3 MK |
281 | Use of this flag requires: a kernel configured with the |
282 | .B CONFIG_SYSVIPC | |
283 | and | |
284 | .B CONFIG_IPC_NS | |
c8e18bd1 | 285 | options and that the process be privileged |
667417b3 MK |
286 | .RB ( CAP_SYS_ADMIN ). |
287 | This flag can't be specified in conjunction with | |
288 | .BR CLONE_SYSVSEM . | |
289 | .TP | |
163bf178 MK |
290 | .BR CLONE_NEWNET " (since Linux 2.6.24)" |
291 | (The implementation of this flag is not yet complete, | |
292 | but probably will be mostly complete by about Linux 2.6.28.) | |
293 | ||
294 | If | |
295 | .B CLONE_NEWNET | |
296 | is set, then create the process in a new network namespace. | |
297 | If this flag is not set, then (as with | |
298 | .BR fork (2)), | |
299 | the process is created in the same network namespace as | |
300 | the calling process. | |
301 | This flag is intended for the implementation of containers. | |
302 | ||
303 | A network namespace provides an isolated view of the networking stack | |
304 | (network device interfaces, IPv4 and IPv6 protocol stacks, | |
305 | IP routing tables, firewall rules, the | |
306 | .I /proc/net | |
307 | and | |
308 | .I /sys/class/net | |
309 | directory trees, sockets, etc.). | |
310 | A physical network device can live in exactly one | |
311 | network namespace. | |
312 | A virtual network device ("veth") pair provides a pipe-like abstraction | |
313 | that can be used to create tunnels between network namespaces, | |
314 | and can be used to create a bridge to a physical network device | |
315 | in another namespace. | |
316 | ||
317 | Use of this flag requires: a kernel configured with the | |
318 | .B CONFIG_NET_NS | |
319 | option and that the process be privileged | |
cae2ec15 | 320 | .RB ( CAP_SYS_ADMIN ). |
163bf178 | 321 | .TP |
c10859eb | 322 | .BR CLONE_NEWNS " (since Linux 2.4.19)" |
732e54dd | 323 | Start the child in a new mount namespace. |
fea681da | 324 | |
732e54dd | 325 | Every process lives in a mount namespace. |
c13182ef | 326 | The |
fea681da MK |
327 | .I namespace |
328 | of a process is the data (the set of mounts) describing the file hierarchy | |
c13182ef MK |
329 | as seen by that process. |
330 | After a | |
fea681da MK |
331 | .BR fork (2) |
332 | or | |
2777b1ca | 333 | .BR clone () |
fea681da MK |
334 | where the |
335 | .B CLONE_NEWNS | |
732e54dd | 336 | flag is not set, the child lives in the same mount |
4df2eb09 | 337 | namespace as the parent. |
fea681da MK |
338 | The system calls |
339 | .BR mount (2) | |
340 | and | |
341 | .BR umount (2) | |
732e54dd | 342 | change the mount namespace of the calling process, and hence affect |
fea681da | 343 | all processes that live in the same namespace, but do not affect |
732e54dd | 344 | processes in a different mount namespace. |
fea681da MK |
345 | |
346 | After a | |
2777b1ca | 347 | .BR clone () |
fea681da MK |
348 | where the |
349 | .B CLONE_NEWNS | |
732e54dd | 350 | flag is set, the cloned child is started in a new mount namespace, |
fea681da MK |
351 | initialized with a copy of the namespace of the parent. |
352 | ||
0b9bdf82 | 353 | Only a privileged process (one having the \fBCAP_SYS_ADMIN\fP capability) |
fea681da MK |
354 | may specify the |
355 | .B CLONE_NEWNS | |
356 | flag. | |
357 | It is not permitted to specify both | |
358 | .B CLONE_NEWNS | |
359 | and | |
360 | .B CLONE_FS | |
361 | in the same | |
e511ffb6 | 362 | .BR clone () |
fea681da | 363 | call. |
fea681da | 364 | .TP |
82ee147a MK |
365 | .BR CLONE_NEWPID " (since Linux 2.6.24)" |
366 | .\" This explanation draws a lot of details from | |
367 | .\" http://lwn.net/Articles/259217/ | |
368 | .\" Authors: Pavel Emelyanov <xemul@openvz.org> | |
369 | .\" and Kir Kolyshkin <kir@openvz.org> | |
370 | .\" | |
371 | .\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264 | |
372 | .\" Author: Pavel Emelyanov <xemul@openvz.org> | |
373 | If | |
5c95e5e8 | 374 | .B CLONE_NEWPID |
82ee147a MK |
375 | is set, then create the process in a new PID namespace. |
376 | If this flag is not set, then (as with | |
377 | .BR fork (2)), | |
378 | the process is created in the same PID namespace as | |
379 | the calling process. | |
0236bea9 | 380 | This flag is intended for the implementation of containers. |
82ee147a MK |
381 | |
382 | A PID namespace provides an isolated environment for PIDs: | |
383 | PIDs in a new namespace start at 1, | |
384 | somewhat like a standalone system, and calls to | |
385 | .BR fork (2), | |
386 | .BR vfork (2), | |
387 | or | |
388 | .BR clone (2) | |
389 | will produce processes whose PIDs within the namespace | |
390 | are only guaranteed to be unique within that namespace. | |
391 | ||
392 | The first process created in a new namespace | |
393 | (i.e., the process created using the | |
394 | .BR CLONE_NEWPID | |
395 | flag) has the PID 1, and is the "init" process for the namespace. | |
396 | Children that are orphaned within the namespace will be reparented | |
397 | to this process rather than | |
398 | .BR init (8). | |
399 | Unlike the traditional | |
400 | .B init | |
401 | process, the "init" process of a PID namespace can terminate, | |
402 | and if it does, all of the processes in the namespace are terminated. | |
403 | ||
404 | PID namespaces form a hierarchy. | |
405 | When a PID new namespace is created, | |
406 | the PIDs of the processes in that namespace are visible | |
407 | in the PID namespace of the process that created the new namespace; | |
408 | analogously, if the parent PID namespace is itself | |
409 | the child of another PID namespace, | |
410 | then PIDs of the child and parent PID namespaces will both be | |
411 | visible in the grandparent PID namespace. | |
412 | Conversely, the processes in the "child" PID namespace do not see | |
413 | the PIDs of the processes in the parent namespace. | |
414 | The existence of a namespace hierarchy means that each process | |
415 | may now have multiple PIDs: | |
416 | one for each namespace in which it is visible. | |
417 | (A call to | |
418 | .BR getpid (2) | |
419 | always returns the PID associated with the namespace in which | |
420 | the process was created.) | |
421 | ||
422 | After creating the new namespace, | |
423 | it is useful for the child to change its root directory | |
424 | and mount a new procfs instance at | |
425 | .I /proc | |
426 | so that tools such as | |
427 | .BR ps (1) | |
428 | work correctly. | |
429 | .\" mount -t proc proc /proc | |
430 | ||
431 | Use of this flag requires: a kernel configured with the | |
432 | .B CONFIG_PID_NS | |
c8e18bd1 | 433 | option and that the process be privileged |
af3c728e | 434 | .RB ( CAP_SYS_ADMIN ). |
82ee147a MK |
435 | This flag can't be specified in conjunction with |
436 | .BR CLONE_THREAD . | |
437 | .TP | |
43ce9dda MK |
438 | .BR CLONE_NEWUTS " (since Linux 2.6.19)" |
439 | If | |
440 | .B CLONE_NEWUTS | |
e1b11906 MK |
441 | is set, then create the process in a new UTS namespace, |
442 | whose identifiers are initialized by duplicating the identifiers | |
443 | from the UTS namespace of the calling process. | |
43ce9dda MK |
444 | If this flag is not set, then (as with |
445 | .BR fork (2)), | |
446 | the process is created in the same UTS namespace as | |
447 | the calling process. | |
0236bea9 | 448 | This flag is intended for the implementation of containers. |
43ce9dda MK |
449 | |
450 | A UTS namespace is the set of identifiers returned by | |
451 | .BR uname (2); | |
452 | among these, the domain name and the host name can be modified by | |
453 | .BR setdomainname (2) | |
454 | and | |
455 | .BR | |
456 | .BR sethostname (2), | |
457 | respectively. | |
458 | Changes made to these identifiers in one UTS namespace | |
459 | are visible to other processes in the same namespace, | |
460 | but are not visible to processes in other UTS namespaces. | |
461 | ||
462 | Use of this flag requires: a kernel configured with the | |
463 | .B CONFIG_UTS_NS | |
c8e18bd1 | 464 | option and that the process be privileged |
43ce9dda MK |
465 | .RB ( CAP_SYS_ADMIN ). |
466 | .TP | |
f5dbc7c8 MK |
467 | .BR CLONE_PARENT " (since Linux 2.3.12)" |
468 | If | |
469 | .B CLONE_PARENT | |
470 | is set, then the parent of the new child (as returned by | |
471 | .BR getppid (2)) | |
472 | will be the same as that of the calling process. | |
473 | ||
474 | If | |
475 | .B CLONE_PARENT | |
476 | is not set, then (as with | |
477 | .BR fork (2)) | |
478 | the child's parent is the calling process. | |
479 | ||
480 | Note that it is the parent process, as returned by | |
481 | .BR getppid (2), | |
482 | which is signaled when the child terminates, so that | |
483 | if | |
484 | .B CLONE_PARENT | |
485 | is set, then the parent of the calling process, rather than the | |
486 | calling process itself, will be signaled. | |
487 | .TP | |
488 | .BR CLONE_PARENT_SETTID " (since Linux 2.5.49)" | |
489 | Store child thread ID at location | |
490 | .I parent_tidptr | |
491 | in parent and child memory. | |
492 | (In Linux 2.5.32-2.5.48 there was a flag | |
493 | .B CLONE_SETTID | |
494 | that did this.) | |
495 | .TP | |
496 | .BR CLONE_PID " (obsolete)" | |
497 | If | |
498 | .B CLONE_PID | |
499 | is set, the child process is created with the same process ID as | |
500 | the calling process. | |
501 | This is good for hacking the system, but otherwise | |
502 | of not much use. | |
503 | Since 2.3.21 this flag can be | |
504 | specified only by the system boot process (PID 0). | |
505 | It disappeared in Linux 2.5.16. | |
506 | .TP | |
507 | .B CLONE_PTRACE | |
508 | If | |
509 | .B CLONE_PTRACE | |
510 | is specified, and the calling process is being traced, | |
511 | then trace the child also (see | |
512 | .BR ptrace (2)). | |
513 | .TP | |
514 | .BR CLONE_SETTLS " (since Linux 2.5.32)" | |
515 | The | |
516 | .I newtls | |
517 | argument is the new TLS (Thread Local Storage) descriptor. | |
518 | (See | |
519 | .BR set_thread_area (2).) | |
520 | .TP | |
fea681da MK |
521 | .B CLONE_SIGHAND |
522 | If | |
523 | .B CLONE_SIGHAND | |
314c8ff4 | 524 | is set, the calling process and the child process share the same table of |
c13182ef MK |
525 | signal handlers. |
526 | If the calling process or child process calls | |
fea681da | 527 | .BR sigaction (2) |
c13182ef MK |
528 | to change the behavior associated with a signal, the behavior is |
529 | changed in the other process as well. | |
530 | However, the calling process and child | |
fea681da | 531 | processes still have distinct signal masks and sets of pending |
c13182ef MK |
532 | signals. |
533 | So, one of them may block or unblock some signals using | |
fea681da MK |
534 | .BR sigprocmask (2) |
535 | without affecting the other process. | |
536 | ||
537 | If | |
538 | .B CLONE_SIGHAND | |
539 | is not set, the child process inherits a copy of the signal handlers | |
540 | of the calling process at the time | |
edcc65ff | 541 | .BR clone () |
c13182ef MK |
542 | is called. |
543 | Calls to | |
fea681da MK |
544 | .BR sigaction (2) |
545 | performed later by one of the processes have no effect on the other | |
546 | process. | |
29546c24 MK |
547 | |
548 | Since Linux 2.6.0-test6, | |
549 | .I flags | |
550 | must also include | |
551 | .B CLONE_VM | |
552 | if | |
553 | .B CLONE_SIGHAND | |
554 | is specified | |
fea681da | 555 | .TP |
a69b6bda MK |
556 | .BR CLONE_STOPPED " (since Linux 2.6.0-test2)" |
557 | If | |
558 | .B CLONE_STOPPED | |
559 | is set, then the child is initially stopped (as though it was sent a | |
560 | .B SIGSTOP | |
561 | signal), and must be resumed by sending it a | |
562 | .B SIGCONT | |
563 | signal. | |
ef37eaf2 MK |
564 | |
565 | .I "From Linux 2.6.25 this flag is deprecated." | |
566 | You probably never wanted to use it, | |
53c94269 | 567 | you certainly shouldn't be using it, and soon it will go away. |
a5a061ee | 568 | .\" glibc 2.8 removed this defn from bits/sched.h |
a69b6bda | 569 | .TP |
f5dbc7c8 | 570 | .BR CLONE_SYSVSEM " (since Linux 2.5.10)" |
fea681da | 571 | If |
f5dbc7c8 MK |
572 | .B CLONE_SYSVSEM |
573 | is set, then the child and the calling process share | |
574 | a single list of System V semaphore undo values (see | |
575 | .BR semop (2)). | |
576 | If this flag is not set, then the child has a separate undo list, | |
577 | which is initially empty. | |
fea681da MK |
578 | .TP |
579 | .BR CLONE_THREAD " (since Linux 2.4.0-test8)" | |
580 | If | |
581 | .B CLONE_THREAD | |
582 | is set, the child is placed in the same thread group as the calling process. | |
fd8a5be4 MK |
583 | To make the remainder of the discussion of |
584 | .B CLONE_THREAD | |
585 | more readable, the term "thread" is used to refer to the | |
586 | processes within a thread group. | |
fea681da | 587 | |
fd8a5be4 MK |
588 | Thread groups were a feature added in Linux 2.4 to support the |
589 | POSIX threads notion of a set of threads that share a single PID. | |
590 | Internally, this shared PID is the so-called | |
591 | thread group identifier (TGID) for the thread group. | |
c13182ef | 592 | Since Linux 2.4, calls to |
fea681da | 593 | .BR getpid (2) |
fd8a5be4 MK |
594 | return the TGID of the caller. |
595 | ||
596 | The threads within a group can be distinguished by their (system-wide) | |
597 | unique thread IDs (TID). | |
598 | A new thread's TID is available as the function result | |
599 | returned to the caller of | |
600 | .BR clone (), | |
601 | and a thread can obtain | |
602 | its own TID using | |
603 | .BR gettid (2). | |
604 | ||
c13182ef | 605 | When a call is made to |
fd8a5be4 MK |
606 | .BR clone () |
607 | without specifying | |
608 | .BR CLONE_THREAD , | |
609 | then the resulting thread is placed in a new thread group | |
610 | whose TGID is the same as the thread's TID. | |
611 | This thread is the | |
612 | .I leader | |
613 | of the new thread group. | |
614 | ||
615 | A new thread created with | |
616 | .B CLONE_THREAD | |
617 | has the same parent process as the caller of | |
618 | .BR clone () | |
c13182ef | 619 | (i.e., like |
fd8a5be4 MK |
620 | .BR CLONE_PARENT ), |
621 | so that calls to | |
622 | .BR getppid (2) | |
623 | return the same value for all of the threads in a thread group. | |
624 | When a | |
c13182ef | 625 | .B CLONE_THREAD |
fd8a5be4 MK |
626 | thread terminates, the thread that created it using |
627 | .BR clone () | |
628 | is not sent a | |
629 | .B SIGCHLD | |
630 | (or other termination) signal; | |
631 | nor can the status of such a thread be obtained | |
632 | using | |
633 | .BR wait (2). | |
634 | (The thread is said to be | |
635 | .IR detached .) | |
636 | ||
e2fbf61d MK |
637 | After all of the threads in a thread group terminate |
638 | the parent process of the thread group is sent a | |
fd8a5be4 MK |
639 | .B SIGCHLD |
640 | (or other termination) signal. | |
641 | ||
642 | If any of the threads in a thread group performs an | |
643 | .BR execve (2), | |
644 | then all threads other than the thread group leader are terminated, | |
645 | and the new program is executed in the thread group leader. | |
646 | ||
f7110f60 MK |
647 | If one of the threads in a thread group creates a child using |
648 | .BR fork (2), | |
649 | then any thread in the group can | |
650 | .BR wait (2) | |
651 | for that child. | |
652 | ||
edcc65ff | 653 | Since Linux 2.5.35, |
fd8a5be4 MK |
654 | .I flags |
655 | must also include | |
656 | .B CLONE_SIGHAND | |
657 | if | |
658 | .B CLONE_THREAD | |
659 | is specified. | |
e2fbf61d MK |
660 | |
661 | Signals may be sent to a thread group as a whole (i.e., a TGID) using | |
662 | .BR kill (2), | |
663 | or to a specific thread (i.e., TID) using | |
664 | .BR tgkill (2). | |
665 | ||
666 | Signal dispositions and actions are process-wide: | |
667 | if an unhandled signal is delivered to a thread, then | |
668 | it will affect (terminate, stop, continue, be ignored in) | |
669 | all members of the thread group. | |
670 | ||
99408a60 | 671 | Each thread has its own signal mask, as set by |
e2fbf61d | 672 | .BR sigprocmask (2), |
82a06020 | 673 | but signals can be pending either: for the whole process |
e2fbf61d MK |
674 | (i.e., deliverable to any member of the thread group), |
675 | when sent with | |
82a06020 | 676 | .BR kill (2); |
e2fbf61d MK |
677 | or for an individual thread, when sent with |
678 | .BR tgkill (2). | |
99408a60 MK |
679 | A call to |
680 | .BR sigpending (2) | |
681 | returns a signal set that is the union of the signals pending for the | |
682 | whole process and the signals that are pending for the calling thread. | |
e2fbf61d | 683 | |
c13182ef | 684 | If |
e2fbf61d MK |
685 | .BR kill (2) |
686 | is used to send a signal to a thread group, | |
687 | and the thread group has installed a handler for the signal, then | |
688 | the handler will be invoked in exactly one, arbitrarily selected | |
689 | member of the thread group that has not blocked the signal. | |
c13182ef | 690 | If multiple threads in a group are waiting to accept the same signal using |
e2fbf61d MK |
691 | .BR sigwaitinfo (2), |
692 | the kernel will arbitrarily select one of these threads | |
c13182ef | 693 | to receive a signal sent using |
e2fbf61d | 694 | .BR kill (2). |
a69b6bda | 695 | .TP |
f5dbc7c8 | 696 | .BR CLONE_UNTRACED " (since Linux 2.5.46)" |
a69b6bda | 697 | If |
f5dbc7c8 MK |
698 | .B CLONE_UNTRACED |
699 | is specified, then a tracing process cannot force | |
700 | .B CLONE_PTRACE | |
701 | on this child process. | |
fea681da | 702 | .TP |
f5dbc7c8 MK |
703 | .B CLONE_VFORK |
704 | If | |
705 | .B CLONE_VFORK | |
706 | is set, the execution of the calling process is suspended | |
707 | until the child releases its virtual memory | |
708 | resources via a call to | |
709 | .BR execve (2) | |
710 | or | |
711 | .BR _exit (2) | |
712 | (as with | |
713 | .BR vfork (2)). | |
714 | ||
715 | If | |
716 | .B CLONE_VFORK | |
717 | is not set then both the calling process and the child are schedulable | |
718 | after the call, and an application should not rely on execution occurring | |
719 | in any particular order. | |
fea681da | 720 | .TP |
f5dbc7c8 MK |
721 | .B CLONE_VM |
722 | If | |
723 | .B CLONE_VM | |
724 | is set, the calling process and the child process run in the same memory | |
725 | space. | |
726 | In particular, memory writes performed by the calling process | |
727 | or by the child process are also visible in the other process. | |
728 | Moreover, any memory mapping or unmapping performed with | |
729 | .BR mmap (2) | |
730 | or | |
731 | .BR munmap (2) | |
732 | by the child or calling process also affects the other process. | |
733 | ||
734 | If | |
735 | .B CLONE_VM | |
736 | is not set, the child process runs in a separate copy of the memory | |
737 | space of the calling process at the time of | |
738 | .BR clone (). | |
739 | Memory writes or file mappings/unmappings performed by one of the | |
740 | processes do not affect the other, as with | |
741 | .BR fork (2). | |
fea681da MK |
742 | .SS "sys_clone" |
743 | The | |
744 | .B sys_clone | |
745 | system call corresponds more closely to | |
746 | .BR fork (2) | |
747 | in that execution in the child continues from the point of the | |
c13182ef MK |
748 | call. |
749 | Thus, | |
fea681da MK |
750 | .B sys_clone |
751 | only requires the | |
752 | .I flags | |
c13182ef | 753 | and |
fea681da | 754 | .I child_stack |
c13182ef MK |
755 | arguments, which have the same meaning as for |
756 | .BR clone (). | |
fea681da | 757 | (Note that the order of these arguments differs from |
c13182ef | 758 | .BR clone ().) |
fea681da | 759 | |
c13182ef | 760 | Another difference for |
fea681da MK |
761 | .B sys_clone |
762 | is that the | |
763 | .I child_stack | |
c13182ef | 764 | argument may be zero, in which case copy-on-write semantics ensure that the |
fea681da | 765 | child gets separate copies of stack pages when either process modifies |
c13182ef MK |
766 | the stack. |
767 | In this case, for correct operation, the | |
fea681da MK |
768 | .B CLONE_VM |
769 | option should not be specified. | |
770 | ||
c4bb193f MK |
771 | Since Linux 2.5.49 the system call has five arguments. |
772 | The two new arguments are | |
fea681da MK |
773 | .I parent_tidptr |
774 | which points to the location (in parent and child memory) where | |
682edefb MK |
775 | the child thread ID will be written in case |
776 | .B CLONE_PARENT_SETTID | |
fea681da MK |
777 | was specified, and |
778 | .I child_tidptr | |
779 | which points to the location (in child memory) where the child thread ID | |
682edefb MK |
780 | will be written in case |
781 | .B CLONE_CHILD_SETTID | |
782 | was specified. | |
fea681da | 783 | .SH "RETURN VALUE" |
0bfa087b MK |
784 | .\" gettid(2) returns current->pid; |
785 | .\" getpid(2) returns current->tgid; | |
fea681da | 786 | On success, the thread ID of the child process is returned |
c13182ef | 787 | in the caller's thread of execution. |
84811e86 | 788 | On failure, \-1 is returned |
fea681da MK |
789 | in the caller's context, no child process will be created, and |
790 | .I errno | |
791 | will be set appropriately. | |
fea681da MK |
792 | .SH ERRORS |
793 | .TP | |
794 | .B EAGAIN | |
795 | Too many processes are already running. | |
796 | .TP | |
797 | .B EINVAL | |
798 | .B CLONE_SIGHAND | |
799 | was specified, but | |
800 | .B CLONE_VM | |
2e8a7fb3 MK |
801 | was not. |
802 | (Since Linux 2.6.0-test6.) | |
fea681da MK |
803 | .TP |
804 | .B EINVAL | |
805 | .B CLONE_THREAD | |
806 | was specified, but | |
807 | .B CLONE_SIGHAND | |
6387216b MK |
808 | was not. |
809 | (Since Linux 2.5.35.) | |
29546c24 MK |
810 | .\" .TP |
811 | .\" .B EINVAL | |
812 | .\" Precisely one of | |
813 | .\" .B CLONE_DETACHED | |
814 | .\" and | |
815 | .\" .B CLONE_THREAD | |
6387216b MK |
816 | .\" was specified. |
817 | .\" (Since Linux 2.6.0-test6.) | |
fea681da MK |
818 | .TP |
819 | .B EINVAL | |
820 | Both | |
821 | .B CLONE_FS | |
822 | and | |
823 | .B CLONE_NEWNS | |
824 | were specified in | |
825 | .IR flags . | |
826 | .TP | |
827 | .B EINVAL | |
82ee147a | 828 | Both |
667417b3 MK |
829 | .B CLONE_NEWIPC |
830 | and | |
831 | .B CLONE_SYSVSEM | |
832 | were specified in | |
833 | .IR flags . | |
834 | .TP | |
835 | .B EINVAL | |
836 | Both | |
82ee147a MK |
837 | .BR CLONE_NEWPID |
838 | and | |
839 | .BR CLONE_THREAD | |
840 | were specified in | |
841 | .IR flags . | |
842 | .TP | |
843 | .B EINVAL | |
c13182ef | 844 | Returned by |
edcc65ff | 845 | .BR clone () |
c13182ef | 846 | when a zero value is specified for |
fea681da MK |
847 | .IR child_stack . |
848 | .TP | |
28cad2c1 | 849 | .B EINVAL |
667417b3 MK |
850 | .BR CLONE_NEWIPC |
851 | was specified in | |
852 | .IR flags , | |
853 | but the kernel was not configured with the | |
854 | .B CONFIG_SYSVIPC | |
855 | and | |
856 | .BR CONFIG_IPC_NS | |
857 | options. | |
858 | .TP | |
859 | .B EINVAL | |
163bf178 MK |
860 | .BR CLONE_NEWNET |
861 | was specified in | |
862 | .IR flags , | |
863 | but the kernel was not configured with the | |
864 | .B CONFIG_NET_NS | |
865 | option. | |
866 | .TP | |
867 | .B EINVAL | |
28cad2c1 MK |
868 | .BR CLONE_NEWPID |
869 | was specified in | |
870 | .IR flags , | |
871 | but the kernel was not configured with the | |
872 | .B CONFIG_PID_NS | |
873 | option. | |
874 | .TP | |
43ce9dda MK |
875 | .B EINVAL |
876 | .BR CLONE_NEWUTS | |
877 | was specified in | |
878 | .IR flags , | |
879 | but the kernel was not configured with the | |
880 | .B CONFIG_UTS | |
881 | option. | |
882 | .TP | |
fea681da MK |
883 | .B ENOMEM |
884 | Cannot allocate sufficient memory to allocate a task structure for the | |
885 | child, or to copy those parts of the caller's context that need to be | |
886 | copied. | |
887 | .TP | |
888 | .B EPERM | |
667417b3 | 889 | .BR CLONE_NEWIPC , |
163bf178 | 890 | .BR CLONE_NEWNET , |
43ce9dda MK |
891 | .BR CLONE_NEWNS , |
892 | .BR CLONE_NEWPID , | |
82ee147a | 893 | or |
43ce9dda | 894 | .BR CLONE_NEWUTS |
0b9bdf82 | 895 | was specified by a non-root process (process without \fBCAP_SYS_ADMIN\fP). |
fea681da MK |
896 | .TP |
897 | .B EPERM | |
898 | .B CLONE_PID | |
899 | was specified by a process other than process 0. | |
a759cc87 | 900 | .SH VERSIONS |
fea681da | 901 | There is no entry for |
edcc65ff | 902 | .BR clone () |
a759cc87 MK |
903 | in libc5. |
904 | glibc2 provides | |
edcc65ff | 905 | .BR clone () |
fea681da | 906 | as described in this manual page. |
a1d5f77c MK |
907 | .SH "CONFORMING TO" |
908 | The | |
909 | .BR clone () | |
910 | and | |
911 | .B sys_clone | |
8382f16d | 912 | calls are Linux-specific and should not be used in programs |
a1d5f77c | 913 | intended to be portable. |
fea681da | 914 | .SH NOTES |
fd8a5be4 MK |
915 | In the kernel 2.4.x series, |
916 | .B CLONE_THREAD | |
917 | generally does not make the parent of the new thread the same | |
918 | as the parent of the calling process. | |
919 | However, for kernel versions 2.4.7 to 2.4.18 the | |
920 | .B CLONE_THREAD | |
921 | flag implied the | |
c13182ef | 922 | .B CLONE_PARENT |
fd8a5be4 | 923 | flag (as in kernel 2.6). |
fea681da | 924 | |
c13182ef MK |
925 | For a while there was |
926 | .B CLONE_DETACHED | |
a5053dcb | 927 | (introduced in 2.5.32): |
c13182ef | 928 | parent wants no child-exit signal. |
a5053dcb | 929 | In 2.6.2 the need to give this |
c13182ef MK |
930 | together with |
931 | .B CLONE_THREAD | |
a5053dcb MK |
932 | disappeared. |
933 | This flag is still defined, but has no effect. | |
934 | ||
34ccb744 | 935 | On i386, |
a5a997ca MK |
936 | .BR clone () |
937 | should not be called through vsyscall, but directly through | |
938 | .IR "int $0x80" . | |
ff929e3b | 939 | |
22399250 | 940 | On ia64, a different system call is used: |
ff929e3b MK |
941 | .nf |
942 | ||
9b0e0996 MK |
943 | .BI "int __clone2(int (*" "fn" ")(void *), " |
944 | .BI " void *" child_stack_base ", size_t " stack_size , | |
945 | .BI " int " flags ", void *" "arg" ", ... " | |
946 | .BI " /* pid_t *" pid ", struct user_desc *" tls \ | |
ff929e3b MK |
947 | ", pid_t *" ctid " */ );" |
948 | .fi | |
949 | .PP | |
950 | The | |
9b0e0996 | 951 | .BR __clone2 () |
c13182ef | 952 | system call operates in the same way as |
ff929e3b MK |
953 | .BR clone (), |
954 | except that | |
955 | .I child_stack_base | |
956 | points to the lowest address of the child's stack area, | |
957 | and | |
958 | .I stack_size | |
959 | specifies the size of the stack pointed to by | |
960 | .IR child_stack_base . | |
31830ef0 MK |
961 | .SH BUGS |
962 | Versions of the GNU C library that include the NPTL threading library | |
c13182ef | 963 | contain a wrapper function for |
0bfa087b | 964 | .BR getpid (2) |
31830ef0 | 965 | that performs caching of PIDs. |
c60237c9 MK |
966 | This caching relies on support in the glibc wrapper for |
967 | .BR clone (), | |
968 | but as currently implemented, | |
969 | the cache may not be up to date in some circumstances. | |
970 | In particular, | |
971 | if a signal is delivered to the child immediately after the | |
972 | .BR clone () | |
973 | call, then a call to | |
974 | .BR getpid () | |
975 | in a handler for the signal may return the PID | |
976 | of the calling process ("the parent"), | |
88619baf | 977 | if the clone wrapper has not yet had a chance to update the PID |
c60237c9 MK |
978 | cache in the child. |
979 | (This discussion ignores the case where the child was created using | |
9291ce36 | 980 | .BR CLONE_THREAD , |
c60237c9 MK |
981 | when |
982 | .BR getpid () | |
983 | .I should | |
984 | return the same value in the child and in the process that called | |
985 | .BR clone (), | |
a1d48abb | 986 | since the caller and the child are in the same thread group. |
e7d807b7 | 987 | The stale-cache problem also does not occur if the |
a1d48abb JR |
988 | .I flags |
989 | argument includes | |
990 | .BR CLONE_VM .) | |
c60237c9 | 991 | To get the truth, it may be necessary to use code such as the following: |
31830ef0 MK |
992 | .nf |
993 | ||
994 | #include <syscall.h> | |
995 | ||
996 | pid_t mypid; | |
997 | ||
998 | mypid = syscall(SYS_getpid); | |
999 | .fi | |
c60237c9 MK |
1000 | .\" See also the following bug reports |
1001 | .\" https://bugzilla.redhat.com/show_bug.cgi?id=417521 | |
1002 | .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910 | |
fea681da MK |
1003 | .SH "SEE ALSO" |
1004 | .BR fork (2), | |
2b44301c | 1005 | .BR futex (2), |
fea681da MK |
1006 | .BR getpid (2), |
1007 | .BR gettid (2), | |
f2d0bbf1 | 1008 | .BR set_thread_area (2), |
2b44301c | 1009 | .BR set_tid_address (2), |
f2d0bbf1 | 1010 | .BR tkill (2), |
5cc01e9c | 1011 | .BR unshare (2), |
fea681da | 1012 | .BR wait (2), |
3616b7c0 MK |
1013 | .BR capabilities (7), |
1014 | .BR pthreads (7) |