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