1 .\" Hey Emacs! This file is -*- nroff -*- source.
3 .\" Copyright (c) 1992 Drew Eckhardt <drew@cs.colorado.edu>, March 28, 1992
4 .\" and Copyright (c) Michael Kerrisk, 2001, 2002, 2005
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
40 .\" FIXME Document CLONE_NEWUSER, which is new in 2.6.23
41 .\" (also supported for unshare()?)
42 .\" FIXME . 2.6.25 marks the unused CLONE_STOPPED as obsolete, and it will
43 .\" probably be removed in the future.
45 .TH CLONE 2 2010-11-01 "Linux" "Linux Programmer's Manual"
47 clone, __clone2 \- create a child process
50 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
51 .\" Actually _BSD_SOURCE || _SVID_SOURCE
52 .\" See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749
55 .BI "int clone(int (*" "fn" ")(void *), void *" child_stack ,
56 .BI " int " flags ", void *" "arg" ", ... "
57 .BI " /* pid_t *" ptid ", struct user_desc *" tls \
58 ", pid_t *" ctid " */ );"
62 creates a new process, in a manner similar to
64 It is actually a library function layered on top of the underlying
66 system call, hereinafter referred to as
70 is given toward the end of this page.
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
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
86 is to implement threads: multiple threads of control in a program that
87 run concurrently in a shared memory space.
89 When the child process is created with
91 it executes the function
96 where execution continues in the child from the point
102 argument is a pointer to a function that is called by the child
103 process at the beginning of its execution.
106 argument is passed to the
112 function application returns, the child process terminates.
113 The integer returned by
115 is the exit code for the child process.
116 The child process may also terminate explicitly by calling
118 or after receiving a fatal signal.
122 argument specifies the location of the stack used by the child process.
123 Since the child and calling process may share memory,
124 it is not possible for the child process to execute in the
125 same stack as the calling process.
126 The calling process must therefore
127 set up memory space for the child stack and pass a pointer to this
130 Stacks grow downward on all processors that run Linux
131 (except the HP PA processors), so
133 usually points to the topmost address of the memory space set up for
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
143 then the parent process must specify the
147 options when waiting for the child with
149 If no signal is specified, then the parent process is not signaled
150 when the child terminates.
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
155 and the child process:
157 .BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)"
158 Erase child thread ID at location
160 in child memory when the child exits, and do a wakeup on the futex
162 The address involved may be changed by the
163 .BR set_tid_address (2)
165 This is used by threading libraries.
167 .BR CLONE_CHILD_SETTID " (since Linux 2.5.49)"
168 Store child thread ID at location
175 is set, the calling process and the child process share the same file
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
183 operation), the other process is also affected.
187 is not set, the child process inherits a copy of all file descriptors
188 opened in the calling process at the time of
190 (The duplicated file descriptors in the child refer to the
191 same open file descriptions (see
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.
202 is set, the caller and the child process share the same file system
204 This includes the root of the file system, the current
205 working directory, and the umask.
211 performed by the calling process or the child process also affects the
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
224 performed later by one of the processes do not affect the other process.
226 .BR CLONE_IO " (since Linux 2.6.25)"
229 is set, then the new process shares an I/O context with
231 If this flag is not set, then (as with
233 the new process has its own I/O context.
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
247 for instance), they should employ
249 to get better I/O performance.
252 If the kernel is not configured with the
254 option, this flag is a no-op.
256 .BR CLONE_NEWIPC " (since Linux 2.6.19)"
259 is set, then create the process in a new IPC namespace.
260 If this flag is not set, then (as with
262 the process is created in the same IPC namespace as
264 This flag is intended for the implementation of containers.
266 An IPC namespace consists of the set of identifiers for
267 System V IPC objects.
268 (These objects are created using
273 Objects created in an IPC namespace are visible to all other processes
274 that are members of that namespace,
275 but are not visible to processes in other IPC namespaces.
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.
281 Use of this flag requires: a kernel configured with the
285 options and that the process be privileged
286 .RB ( CAP_SYS_ADMIN ).
287 This flag can't be specified in conjunction with
290 .BR CLONE_NEWNET " (since Linux 2.6.24)"
291 (The implementation of this flag was only completed
292 by about kernel version 2.6.29.)
296 is set, then create the process in a new network namespace.
297 If this flag is not set, then (as with
299 the process is created in the same network namespace as
301 This flag is intended for the implementation of containers.
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
309 directory trees, sockets, etc.).
310 A physical network device can live in exactly one
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.
317 When a network namespace is freed
318 (i.e., when the last process in the namespace terminates),
319 its physical network devices are moved back to the
320 initial network namespace (not to the parent of the process).
322 Use of this flag requires: a kernel configured with the
324 option and that the process be privileged
325 .RB ( CAP_SYS_ADMIN ).
327 .BR CLONE_NEWNS " (since Linux 2.4.19)"
328 Start the child in a new mount namespace.
330 Every process lives in a mount namespace.
333 of a process is the data (the set of mounts) describing the file hierarchy
334 as seen by that process.
341 flag is not set, the child lives in the same mount
342 namespace as the parent.
347 change the mount namespace of the calling process, and hence affect
348 all processes that live in the same namespace, but do not affect
349 processes in a different mount namespace.
355 flag is set, the cloned child is started in a new mount namespace,
356 initialized with a copy of the namespace of the parent.
358 Only a privileged process (one having the \fBCAP_SYS_ADMIN\fP capability)
362 It is not permitted to specify both
370 .BR CLONE_NEWPID " (since Linux 2.6.24)"
371 .\" This explanation draws a lot of details from
372 .\" http://lwn.net/Articles/259217/
373 .\" Authors: Pavel Emelyanov <xemul@openvz.org>
374 .\" and Kir Kolyshkin <kir@openvz.org>
376 .\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264
377 .\" Author: Pavel Emelyanov <xemul@openvz.org>
380 is set, then create the process in a new PID namespace.
381 If this flag is not set, then (as with
383 the process is created in the same PID namespace as
385 This flag is intended for the implementation of containers.
387 A PID namespace provides an isolated environment for PIDs:
388 PIDs in a new namespace start at 1,
389 somewhat like a standalone system, and calls to
394 will produce processes with PIDs that are unique within the namespace.
396 The first process created in a new namespace
397 (i.e., the process created using the
399 flag) has the PID 1, and is the "init" process for the namespace.
400 Children that are orphaned within the namespace will be reparented
401 to this process rather than
403 Unlike the traditional
405 process, the "init" process of a PID namespace can terminate,
406 and if it does, all of the processes in the namespace are terminated.
408 PID namespaces form a hierarchy.
409 When a new PID namespace is created,
410 the processes in that namespace are visible
411 in the PID namespace of the process that created the new namespace;
412 analogously, if the parent PID namespace is itself
413 the child of another PID namespace,
414 then processes in the child and parent PID namespaces will both be
415 visible in the grandparent PID namespace.
416 Conversely, the processes in the "child" PID namespace do not see
417 the processes in the parent namespace.
418 The existence of a namespace hierarchy means that each process
419 may now have multiple PIDs:
420 one for each namespace in which it is visible;
421 each of these PIDs is unique within the corresponding namespace.
424 always returns the PID associated with the namespace in which
427 After creating the new namespace,
428 it is useful for the child to change its root directory
429 and mount a new procfs instance at
431 so that tools such as
434 .\" mount -t proc proc /proc
439 then it isn't necessary to change the root directory:
440 a new procfs instance can be mounted directly over
443 Use of this flag requires: a kernel configured with the
445 option and that the process be privileged
446 .RB ( CAP_SYS_ADMIN ).
447 This flag can't be specified in conjunction with
450 .BR CLONE_NEWUTS " (since Linux 2.6.19)"
453 is set, then create the process in a new UTS namespace,
454 whose identifiers are initialized by duplicating the identifiers
455 from the UTS namespace of the calling process.
456 If this flag is not set, then (as with
458 the process is created in the same UTS namespace as
460 This flag is intended for the implementation of containers.
462 A UTS namespace is the set of identifiers returned by
464 among these, the domain name and the host name can be modified by
465 .BR setdomainname (2)
470 Changes made to the identifiers in a UTS namespace
471 are visible to all other processes in the same namespace,
472 but are not visible to processes in other UTS namespaces.
474 Use of this flag requires: a kernel configured with the
476 option and that the process be privileged
477 .RB ( CAP_SYS_ADMIN ).
479 .BR CLONE_PARENT " (since Linux 2.3.12)"
482 is set, then the parent of the new child (as returned by
484 will be the same as that of the calling process.
488 is not set, then (as with
490 the child's parent is the calling process.
492 Note that it is the parent process, as returned by
494 which is signaled when the child terminates, so that
497 is set, then the parent of the calling process, rather than the
498 calling process itself, will be signaled.
500 .BR CLONE_PARENT_SETTID " (since Linux 2.5.49)"
501 Store child thread ID at location
503 in parent and child memory.
504 (In Linux 2.5.32-2.5.48 there was a flag
508 .BR CLONE_PID " (obsolete)"
511 is set, the child process is created with the same process ID as
513 This is good for hacking the system, but otherwise
515 Since 2.3.21 this flag can be
516 specified only by the system boot process (PID 0).
517 It disappeared in Linux 2.5.16.
522 is specified, and the calling process is being traced,
523 then trace the child also (see
526 .BR CLONE_SETTLS " (since Linux 2.5.32)"
529 argument is the new TLS (Thread Local Storage) descriptor.
531 .BR set_thread_area (2).)
536 is set, the calling process and the child process share the same table of
538 If the calling process or child process calls
540 to change the behavior associated with a signal, the behavior is
541 changed in the other process as well.
542 However, the calling process and child
543 processes still have distinct signal masks and sets of pending
545 So, one of them may block or unblock some signals using
547 without affecting the other process.
551 is not set, the child process inherits a copy of the signal handlers
552 of the calling process at the time
557 performed later by one of the processes have no effect on the other
560 Since Linux 2.6.0-test6,
568 .BR CLONE_STOPPED " (since Linux 2.6.0-test2)"
571 is set, then the child is initially stopped (as though it was sent a
573 signal), and must be resumed by sending it a
577 .I "From Linux 2.6.25 this flag is deprecated."
578 You probably never wanted to use it,
579 you certainly shouldn't be using it, and soon it will go away.
580 .\" glibc 2.8 removed this defn from bits/sched.h
582 .BR CLONE_SYSVSEM " (since Linux 2.5.10)"
585 is set, then the child and the calling process share
586 a single list of System V semaphore undo values (see
588 If this flag is not set, then the child has a separate undo list,
589 which is initially empty.
591 .BR CLONE_THREAD " (since Linux 2.4.0-test8)"
594 is set, the child is placed in the same thread group as the calling process.
595 To make the remainder of the discussion of
597 more readable, the term "thread" is used to refer to the
598 processes within a thread group.
600 Thread groups were a feature added in Linux 2.4 to support the
601 POSIX threads notion of a set of threads that share a single PID.
602 Internally, this shared PID is the so-called
603 thread group identifier (TGID) for the thread group.
604 Since Linux 2.4, calls to
606 return the TGID of the caller.
608 The threads within a group can be distinguished by their (system-wide)
609 unique thread IDs (TID).
610 A new thread's TID is available as the function result
611 returned to the caller of
613 and a thread can obtain
617 When a call is made to
621 then the resulting thread is placed in a new thread group
622 whose TGID is the same as the thread's TID.
625 of the new thread group.
627 A new thread created with
629 has the same parent process as the caller of
635 return the same value for all of the threads in a thread group.
638 thread terminates, the thread that created it using
642 (or other termination) signal;
643 nor can the status of such a thread be obtained
646 (The thread is said to be
649 After all of the threads in a thread group terminate
650 the parent process of the thread group is sent a
652 (or other termination) signal.
654 If any of the threads in a thread group performs an
656 then all threads other than the thread group leader are terminated,
657 and the new program is executed in the thread group leader.
659 If one of the threads in a thread group creates a child using
661 then any thread in the group can
673 Signals may be sent to a thread group as a whole (i.e., a TGID) using
675 or to a specific thread (i.e., TID) using
678 Signal dispositions and actions are process-wide:
679 if an unhandled signal is delivered to a thread, then
680 it will affect (terminate, stop, continue, be ignored in)
681 all members of the thread group.
683 Each thread has its own signal mask, as set by
685 but signals can be pending either: for the whole process
686 (i.e., deliverable to any member of the thread group),
689 or for an individual thread, when sent with
693 returns a signal set that is the union of the signals pending for the
694 whole process and the signals that are pending for the calling thread.
698 is used to send a signal to a thread group,
699 and the thread group has installed a handler for the signal, then
700 the handler will be invoked in exactly one, arbitrarily selected
701 member of the thread group that has not blocked the signal.
702 If multiple threads in a group are waiting to accept the same signal using
704 the kernel will arbitrarily select one of these threads
705 to receive a signal sent using
708 .BR CLONE_UNTRACED " (since Linux 2.5.46)"
711 is specified, then a tracing process cannot force
713 on this child process.
718 is set, the execution of the calling process is suspended
719 until the child releases its virtual memory
720 resources via a call to
729 is not set then both the calling process and the child are schedulable
730 after the call, and an application should not rely on execution occurring
731 in any particular order.
736 is set, the calling process and the child process run in the same memory
738 In particular, memory writes performed by the calling process
739 or by the child process are also visible in the other process.
740 Moreover, any memory mapping or unmapping performed with
744 by the child or calling process also affects the other process.
748 is not set, the child process runs in a separate copy of the memory
749 space of the calling process at the time of
751 Memory writes or file mappings/unmappings performed by one of the
752 processes do not affect the other, as with
757 system call corresponds more closely to
759 in that execution in the child continues from the point of the
767 arguments, which have the same meaning as for
769 (Note that the order of these arguments differs from
772 Another difference for
776 argument may be zero, in which case copy-on-write semantics ensure that the
777 child gets separate copies of stack pages when either process modifies
779 In this case, for correct operation, the
781 option should not be specified.
783 In Linux 2.4 and earlier,
785 does not take arguments
791 .\" gettid(2) returns current->pid;
792 .\" getpid(2) returns current->tgid;
793 On success, the thread ID of the child process is returned
794 in the caller's thread of execution.
795 On failure, \-1 is returned
796 in the caller's context, no child process will be created, and
798 will be set appropriately.
802 Too many processes are already running.
809 (Since Linux 2.6.0-test6.)
816 (Since Linux 2.5.35.)
820 .\" .B CLONE_DETACHED
824 .\" (Since Linux 2.6.0-test6.)
853 when a zero value is specified for
860 but the kernel was not configured with the
870 but the kernel was not configured with the
878 but the kernel was not configured with the
886 but the kernel was not configured with the
891 Cannot allocate sufficient memory to allocate a task structure for the
892 child, or to copy those parts of the caller's context that need to be
902 was specified by an unprivileged process (process without \fBCAP_SYS_ADMIN\fP).
906 was specified by a process other than process 0.
908 There is no entry for
913 as described in this manual page.
919 calls are Linux-specific and should not be used in programs
920 intended to be portable.
922 In the kernel 2.4.x series,
924 generally does not make the parent of the new thread the same
925 as the parent of the calling process.
926 However, for kernel versions 2.4.7 to 2.4.18 the
930 flag (as in kernel 2.6).
932 For a while there was
934 (introduced in 2.5.32):
935 parent wants no child-exit signal.
936 In 2.6.2 the need to give this
940 This flag is still defined, but has no effect.
944 should not be called through vsyscall, but directly through
947 On ia64, a different system call is used:
950 .BI "int __clone2(int (*" "fn" ")(void *), "
951 .BI " void *" child_stack_base ", size_t " stack_size ,
952 .BI " int " flags ", void *" "arg" ", ... "
953 .BI " /* pid_t *" ptid ", struct user_desc *" tls \
954 ", pid_t *" ctid " */ );"
959 system call operates in the same way as
963 points to the lowest address of the child's stack area,
966 specifies the size of the stack pointed to by
967 .IR child_stack_base .
969 Versions of the GNU C library that include the NPTL threading library
970 contain a wrapper function for
972 that performs caching of PIDs.
973 This caching relies on support in the glibc wrapper for
975 but as currently implemented,
976 the cache may not be up to date in some circumstances.
978 if a signal is delivered to the child immediately after the
982 in a handler for the signal may return the PID
983 of the calling process ("the parent"),
984 if the clone wrapper has not yet had a chance to update the PID
986 (This discussion ignores the case where the child was created using
991 return the same value in the child and in the process that called
993 since the caller and the child are in the same thread group.
994 The stale-cache problem also does not occur if the
998 To get the truth, it may be necessary to use code such as the following:
1001 #include <syscall.h>
1005 mypid = syscall(SYS_getpid);
1007 .\" See also the following bug reports
1008 .\" https://bugzilla.redhat.com/show_bug.cgi?id=417521
1009 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910
1015 .BR set_thread_area (2),
1016 .BR set_tid_address (2),
1020 .BR capabilities (7),