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()?)
43 .TH CLONE 2 2011-09-08 "Linux" "Linux Programmer's Manual"
45 clone, __clone2 \- create a child process
48 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
49 .\" Actually _BSD_SOURCE || _SVID_SOURCE
50 .\" See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749
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 " */ );"
60 creates a new process, in a manner similar to
62 It is actually a library function layered on top of the underlying
64 system call, hereinafter referred to as
68 is given toward the end of this page.
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
84 is to implement threads: multiple threads of control in a program that
85 run concurrently in a shared memory space.
87 When the child process is created with
89 it executes the function
94 where execution continues in the child from the point
100 argument is a pointer to a function that is called by the child
101 process at the beginning of its execution.
104 argument is passed to the
110 function application returns, the child process terminates.
111 The integer returned by
113 is the exit code for the child process.
114 The child process may also terminate explicitly by calling
116 or after receiving a fatal signal.
120 argument specifies the location of the stack used by the child process.
121 Since the child and calling process may share memory,
122 it is not possible for the child process to execute in the
123 same stack as the calling process.
124 The calling process must therefore
125 set up memory space for the child stack and pass a pointer to this
128 Stacks grow downward on all processors that run Linux
129 (except the HP PA processors), so
131 usually points to the topmost address of the memory space set up for
136 contains the number of the
137 .I "termination signal"
138 sent to the parent when the child dies.
139 If this signal is specified as anything other than
141 then the parent process must specify the
145 options when waiting for the child with
147 If no signal is specified, then the parent process is not signaled
148 when the child terminates.
151 may also be bitwise-or'ed with zero or more of the following constants,
152 in order to specify what is shared between the calling process
153 and the child process:
155 .BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)"
156 Erase child thread ID at location
158 in child memory when the child exits, and do a wakeup on the futex
160 The address involved may be changed by the
161 .BR set_tid_address (2)
163 This is used by threading libraries.
165 .BR CLONE_CHILD_SETTID " (since Linux 2.5.49)"
166 Store child thread ID at location
173 is set, the calling process and the child process share the same file
175 Any file descriptor created by the calling process or by the child
176 process is also valid in the other process.
177 Similarly, if one of the processes closes a file descriptor,
178 or changes its associated flags (using the
181 operation), the other process is also affected.
185 is not set, the child process inherits a copy of all file descriptors
186 opened in the calling process at the time of
188 (The duplicated file descriptors in the child refer to the
189 same open file descriptions (see
191 as the corresponding file descriptors in the calling process.)
192 Subsequent operations that open or close file descriptors,
193 or change file descriptor flags,
194 performed by either the calling
195 process or the child process do not affect the other process.
200 is set, the caller and the child process share the same file system
202 This includes the root of the file system, the current
203 working directory, and the umask.
209 performed by the calling process or the child process also affects the
214 is not set, the child process works on a copy of the file system
215 information of the calling process at the time of the
222 performed later by one of the processes do not affect the other process.
224 .BR CLONE_IO " (since Linux 2.6.25)"
227 is set, then the new process shares an I/O context with
229 If this flag is not set, then (as with
231 the new process has its own I/O context.
233 .\" The following based on text from Jens Axboe
234 The I/O context is the I/O scope of the disk scheduler (i.e,
235 what the I/O scheduler uses to model scheduling of a process's I/O).
236 If processes share the same I/O context,
237 they are treated as one by the I/O scheduler.
238 As a consequence, they get to share disk time.
239 For some I/O schedulers,
240 .\" the anticipatory and CFQ scheduler
241 if two processes share an I/O context,
242 they will be allowed to interleave their disk access.
243 If several threads are doing I/O on behalf of the same process
245 for instance), they should employ
247 to get better I/O performance.
250 If the kernel is not configured with the
252 option, this flag is a no-op.
254 .BR CLONE_NEWIPC " (since Linux 2.6.19)"
257 is set, then create the process in a new IPC namespace.
258 If this flag is not set, then (as with
260 the process is created in the same IPC namespace as
262 This flag is intended for the implementation of containers.
264 An IPC namespace consists of the set of identifiers for
265 System V IPC objects.
266 (These objects are created using
271 Objects created in an IPC namespace are visible to all other processes
272 that are members of that namespace,
273 but are not visible to processes in other IPC namespaces.
275 When an IPC namespace is destroyed
276 (i.e, when the last process that is a member of the namespace terminates),
277 all IPC objects in the namespace are automatically destroyed.
279 Use of this flag requires: a kernel configured with the
283 options and that the process be privileged
284 .RB ( CAP_SYS_ADMIN ).
285 This flag can't be specified in conjunction with
288 .BR CLONE_NEWNET " (since Linux 2.6.24)"
289 .\" FIXME Check when the implementation was completed
290 (The implementation of this flag was only completed
291 by about kernel version 2.6.29.)
295 is set, then create the process in a new network namespace.
296 If this flag is not set, then (as with
298 the process is created in the same network namespace as
300 This flag is intended for the implementation of containers.
302 A network namespace provides an isolated view of the networking stack
303 (network device interfaces, IPv4 and IPv6 protocol stacks,
304 IP routing tables, firewall rules, the
308 directory trees, sockets, etc.).
309 A physical network device can live in exactly one
311 A virtual network device ("veth") pair provides a pipe-like abstraction
312 that can be used to create tunnels between network namespaces,
313 and can be used to create a bridge to a physical network device
314 in another namespace.
316 When a network namespace is freed
317 (i.e., when the last process in the namespace terminates),
318 its physical network devices are moved back to the
319 initial network namespace (not to the parent of the process).
321 Use of this flag requires: a kernel configured with the
323 option and that the process be privileged
324 .RB ( CAP_SYS_ADMIN ).
326 .BR CLONE_NEWNS " (since Linux 2.4.19)"
327 Start the child in a new mount namespace.
329 Every process lives in a mount namespace.
332 of a process is the data (the set of mounts) describing the file hierarchy
333 as seen by that process.
340 flag is not set, the child lives in the same mount
341 namespace as the parent.
346 change the mount namespace of the calling process, and hence affect
347 all processes that live in the same namespace, but do not affect
348 processes in a different mount namespace.
354 flag is set, the cloned child is started in a new mount namespace,
355 initialized with a copy of the namespace of the parent.
357 Only a privileged process (one having the \fBCAP_SYS_ADMIN\fP capability)
361 It is not permitted to specify both
369 .BR CLONE_NEWPID " (since Linux 2.6.24)"
370 .\" This explanation draws a lot of details from
371 .\" http://lwn.net/Articles/259217/
372 .\" Authors: Pavel Emelyanov <xemul@openvz.org>
373 .\" and Kir Kolyshkin <kir@openvz.org>
375 .\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264
376 .\" Author: Pavel Emelyanov <xemul@openvz.org>
379 is set, then create the process in a new PID namespace.
380 If this flag is not set, then (as with
382 the process is created in the same PID namespace as
384 This flag is intended for the implementation of containers.
386 A PID namespace provides an isolated environment for PIDs:
387 PIDs in a new namespace start at 1,
388 somewhat like a standalone system, and calls to
393 will produce processes with PIDs that are unique within the namespace.
395 The first process created in a new namespace
396 (i.e., the process created using the
398 flag) has the PID 1, and is the "init" process for the namespace.
399 Children that are orphaned within the namespace will be reparented
400 to this process rather than
402 Unlike the traditional
404 process, the "init" process of a PID namespace can terminate,
405 and if it does, all of the processes in the namespace are terminated.
407 PID namespaces form a hierarchy.
408 When a new PID namespace is created,
409 the processes in that namespace are visible
410 in the PID namespace of the process that created the new namespace;
411 analogously, if the parent PID namespace is itself
412 the child of another PID namespace,
413 then processes in the child and parent PID namespaces will both be
414 visible in the grandparent PID namespace.
415 Conversely, the processes in the "child" PID namespace do not see
416 the processes in the parent namespace.
417 The existence of a namespace hierarchy means that each process
418 may now have multiple PIDs:
419 one for each namespace in which it is visible;
420 each of these PIDs is unique within the corresponding namespace.
423 always returns the PID associated with the namespace in which
426 After creating the new namespace,
427 it is useful for the child to change its root directory
428 and mount a new procfs instance at
430 so that tools such as
433 .\" mount -t proc proc /proc
438 then it isn't necessary to change the root directory:
439 a new procfs instance can be mounted directly over
442 Use of this flag requires: a kernel configured with the
444 option and that the process be privileged
445 .RB ( CAP_SYS_ADMIN ).
446 This flag can't be specified in conjunction with
449 .BR CLONE_NEWUTS " (since Linux 2.6.19)"
452 is set, then create the process in a new UTS namespace,
453 whose identifiers are initialized by duplicating the identifiers
454 from the UTS namespace of the calling process.
455 If this flag is not set, then (as with
457 the process is created in the same UTS namespace as
459 This flag is intended for the implementation of containers.
461 A UTS namespace is the set of identifiers returned by
463 among these, the domain name and the host name can be modified by
464 .BR setdomainname (2)
469 Changes made to the identifiers in a UTS namespace
470 are visible to all other processes in the same namespace,
471 but are not visible to processes in other UTS namespaces.
473 Use of this flag requires: a kernel configured with the
475 option and that the process be privileged
476 .RB ( CAP_SYS_ADMIN ).
478 .BR CLONE_PARENT " (since Linux 2.3.12)"
481 is set, then the parent of the new child (as returned by
483 will be the same as that of the calling process.
487 is not set, then (as with
489 the child's parent is the calling process.
491 Note that it is the parent process, as returned by
493 which is signaled when the child terminates, so that
496 is set, then the parent of the calling process, rather than the
497 calling process itself, will be signaled.
499 .BR CLONE_PARENT_SETTID " (since Linux 2.5.49)"
500 Store child thread ID at location
502 in parent and child memory.
503 (In Linux 2.5.32-2.5.48 there was a flag
507 .BR CLONE_PID " (obsolete)"
510 is set, the child process is created with the same process ID as
512 This is good for hacking the system, but otherwise
514 Since 2.3.21 this flag can be
515 specified only by the system boot process (PID 0).
516 It disappeared in Linux 2.5.16.
521 is specified, and the calling process is being traced,
522 then trace the child also (see
525 .BR CLONE_SETTLS " (since Linux 2.5.32)"
528 argument is the new TLS (Thread Local Storage) descriptor.
530 .BR set_thread_area (2).)
535 is set, the calling process and the child process share the same table of
537 If the calling process or child process calls
539 to change the behavior associated with a signal, the behavior is
540 changed in the other process as well.
541 However, the calling process and child
542 processes still have distinct signal masks and sets of pending
544 So, one of them may block or unblock some signals using
546 without affecting the other process.
550 is not set, the child process inherits a copy of the signal handlers
551 of the calling process at the time
556 performed later by one of the processes have no effect on the other
559 Since Linux 2.6.0-test6,
567 .BR CLONE_STOPPED " (since Linux 2.6.0-test2)"
570 is set, then the child is initially stopped (as though it was sent a
572 signal), and must be resumed by sending it a
578 from Linux 2.6.25 onward,
581 altogether in Linux 2.6.38.
582 .\" glibc 2.8 removed this defn from bits/sched.h
584 .BR CLONE_SYSVSEM " (since Linux 2.5.10)"
587 is set, then the child and the calling process share
588 a single list of System V semaphore undo values (see
590 If this flag is not set, then the child has a separate undo list,
591 which is initially empty.
593 .BR CLONE_THREAD " (since Linux 2.4.0-test8)"
596 is set, the child is placed in the same thread group as the calling process.
597 To make the remainder of the discussion of
599 more readable, the term "thread" is used to refer to the
600 processes within a thread group.
602 Thread groups were a feature added in Linux 2.4 to support the
603 POSIX threads notion of a set of threads that share a single PID.
604 Internally, this shared PID is the so-called
605 thread group identifier (TGID) for the thread group.
606 Since Linux 2.4, calls to
608 return the TGID of the caller.
610 The threads within a group can be distinguished by their (system-wide)
611 unique thread IDs (TID).
612 A new thread's TID is available as the function result
613 returned to the caller of
615 and a thread can obtain
619 When a call is made to
623 then the resulting thread is placed in a new thread group
624 whose TGID is the same as the thread's TID.
627 of the new thread group.
629 A new thread created with
631 has the same parent process as the caller of
637 return the same value for all of the threads in a thread group.
640 thread terminates, the thread that created it using
644 (or other termination) signal;
645 nor can the status of such a thread be obtained
648 (The thread is said to be
651 After all of the threads in a thread group terminate
652 the parent process of the thread group is sent a
654 (or other termination) signal.
656 If any of the threads in a thread group performs an
658 then all threads other than the thread group leader are terminated,
659 and the new program is executed in the thread group leader.
661 If one of the threads in a thread group creates a child using
663 then any thread in the group can
675 Signals may be sent to a thread group as a whole (i.e., a TGID) using
677 or to a specific thread (i.e., TID) using
680 Signal dispositions and actions are process-wide:
681 if an unhandled signal is delivered to a thread, then
682 it will affect (terminate, stop, continue, be ignored in)
683 all members of the thread group.
685 Each thread has its own signal mask, as set by
687 but signals can be pending either: for the whole process
688 (i.e., deliverable to any member of the thread group),
691 or for an individual thread, when sent with
695 returns a signal set that is the union of the signals pending for the
696 whole process and the signals that are pending for the calling thread.
700 is used to send a signal to a thread group,
701 and the thread group has installed a handler for the signal, then
702 the handler will be invoked in exactly one, arbitrarily selected
703 member of the thread group that has not blocked the signal.
704 If multiple threads in a group are waiting to accept the same signal using
706 the kernel will arbitrarily select one of these threads
707 to receive a signal sent using
710 .BR CLONE_UNTRACED " (since Linux 2.5.46)"
713 is specified, then a tracing process cannot force
715 on this child process.
720 is set, the execution of the calling process is suspended
721 until the child releases its virtual memory
722 resources via a call to
731 is not set then both the calling process and the child are schedulable
732 after the call, and an application should not rely on execution occurring
733 in any particular order.
738 is set, the calling process and the child process run in the same memory
740 In particular, memory writes performed by the calling process
741 or by the child process are also visible in the other process.
742 Moreover, any memory mapping or unmapping performed with
746 by the child or calling process also affects the other process.
750 is not set, the child process runs in a separate copy of the memory
751 space of the calling process at the time of
753 Memory writes or file mappings/unmappings performed by one of the
754 processes do not affect the other, as with
759 system call corresponds more closely to
761 in that execution in the child continues from the point of the
769 arguments, which have the same meaning as for
771 (Note that the order of these arguments differs from
774 Another difference for
778 argument may be zero, in which case copy-on-write semantics ensure that the
779 child gets separate copies of stack pages when either process modifies
781 In this case, for correct operation, the
783 option should not be specified.
785 In Linux 2.4 and earlier,
787 does not take arguments
793 .\" gettid(2) returns current->pid;
794 .\" getpid(2) returns current->tgid;
795 On success, the thread ID of the child process is returned
796 in the caller's thread of execution.
797 On failure, \-1 is returned
798 in the caller's context, no child process will be created, and
800 will be set appropriately.
804 Too many processes are already running.
811 (Since Linux 2.6.0-test6.)
818 (Since Linux 2.5.35.)
822 .\" .B CLONE_DETACHED
826 .\" (Since Linux 2.6.0-test6.)
855 when a zero value is specified for
862 but the kernel was not configured with the
872 but the kernel was not configured with the
880 but the kernel was not configured with the
888 but the kernel was not configured with the
893 Cannot allocate sufficient memory to allocate a task structure for the
894 child, or to copy those parts of the caller's context that need to be
904 was specified by an unprivileged process (process without \fBCAP_SYS_ADMIN\fP).
908 was specified by a process other than process 0.
910 There is no entry for
915 as described in this manual page.
921 calls are Linux-specific and should not be used in programs
922 intended to be portable.
924 In the kernel 2.4.x series,
926 generally does not make the parent of the new thread the same
927 as the parent of the calling process.
928 However, for kernel versions 2.4.7 to 2.4.18 the
932 flag (as in kernel 2.6).
934 For a while there was
936 (introduced in 2.5.32):
937 parent wants no child-exit signal.
938 In 2.6.2 the need to give this
942 This flag is still defined, but has no effect.
946 should not be called through vsyscall, but directly through
949 On ia64, a different system call is used:
952 .BI "int __clone2(int (*" "fn" ")(void *), "
953 .BI " void *" child_stack_base ", size_t " stack_size ,
954 .BI " int " flags ", void *" "arg" ", ... "
955 .BI " /* pid_t *" ptid ", struct user_desc *" tls \
956 ", pid_t *" ctid " */ );"
961 system call operates in the same way as
965 points to the lowest address of the child's stack area,
968 specifies the size of the stack pointed to by
969 .IR child_stack_base .
971 Versions of the GNU C library that include the NPTL threading library
972 contain a wrapper function for
974 that performs caching of PIDs.
975 This caching relies on support in the glibc wrapper for
977 but as currently implemented,
978 the cache may not be up to date in some circumstances.
980 if a signal is delivered to the child immediately after the
984 in a handler for the signal may return the PID
985 of the calling process ("the parent"),
986 if the clone wrapper has not yet had a chance to update the PID
988 (This discussion ignores the case where the child was created using
993 return the same value in the child and in the process that called
995 since the caller and the child are in the same thread group.
996 The stale-cache problem also does not occur if the
1000 To get the truth, it may be necessary to use code such as the following:
1003 #include <syscall.h>
1007 mypid = syscall(SYS_getpid);
1009 .\" See also the following bug reports
1010 .\" https://bugzilla.redhat.com/show_bug.cgi?id=417521
1011 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910
1017 .BR set_thread_area (2),
1018 .BR set_tid_address (2),
1022 .BR capabilities (7),