1 .\" Copyright (c) 1992 Drew Eckhardt <drew@cs.colorado.edu>, March 28, 1992
2 .\" and Copyright (c) Michael Kerrisk, 2001, 2002, 2005, 2013, 2019
4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
5 .\" May be distributed under the GNU General Public License.
8 .\" Modified by Michael Haardt <michael@moria.de>
9 .\" Modified 24 Jul 1993 by Rik Faith <faith@cs.unc.edu>
10 .\" Modified 21 Aug 1994 by Michael Chastain <mec@shell.portal.com>:
11 .\" New man page (copied from 'fork.2').
12 .\" Modified 10 June 1995 by Andries Brouwer <aeb@cwi.nl>
13 .\" Modified 25 April 1998 by Xavier Leroy <Xavier.Leroy@inria.fr>
14 .\" Modified 26 Jun 2001 by Michael Kerrisk
15 .\" Mostly upgraded to 2.4.x
16 .\" Added prototype for sys_clone() plus description
17 .\" Added CLONE_THREAD with a brief description of thread groups
18 .\" Added CLONE_PARENT and revised entire page remove ambiguity
19 .\" between "calling process" and "parent process"
20 .\" Added CLONE_PTRACE and CLONE_VFORK
21 .\" Added EPERM and EINVAL error codes
22 .\" Renamed "__clone" to "clone" (which is the prototype in <sched.h>)
23 .\" various other minor tidy ups and clarifications.
24 .\" Modified 26 Jun 2001 by Michael Kerrisk <mtk.manpages@gmail.com>
25 .\" Updated notes for 2.4.7+ behavior of CLONE_THREAD
26 .\" Modified 15 Oct 2002 by Michael Kerrisk <mtk.manpages@gmail.com>
27 .\" Added description for CLONE_NEWNS, which was added in 2.4.19
28 .\" Slightly rephrased, aeb.
29 .\" Modified 1 Feb 2003 - added CLONE_SIGHAND restriction, aeb.
30 .\" Modified 1 Jan 2004 - various updates, aeb
31 .\" Modified 2004-09-10 - added CLONE_PARENT_SETTID etc. - aeb.
32 .\" 2005-04-12, mtk, noted the PID caching behavior of NPTL's getpid()
33 .\" wrapper under BUGS.
34 .\" 2005-05-10, mtk, added CLONE_SYSVSEM, CLONE_UNTRACED, CLONE_STOPPED.
35 .\" 2005-05-17, mtk, Substantially enhanced discussion of CLONE_THREAD.
36 .\" 2008-11-18, mtk, order CLONE_* flags alphabetically
37 .\" 2008-11-18, mtk, document CLONE_NEWPID
38 .\" 2008-11-19, mtk, document CLONE_NEWUTS
39 .\" 2008-11-19, mtk, document CLONE_NEWIPC
40 .\" 2008-11-19, Jens Axboe, mtk, document CLONE_IO
42 .TH CLONE 2 2019-11-19 "Linux" "Linux Programmer's Manual"
44 clone, __clone2, clone3 \- create a child process
47 /* Prototype for the glibc wrapper function */
49 .B #define _GNU_SOURCE
52 .BI "int clone(int (*" "fn" ")(void *), void *" stack \
53 ", int " flags ", void *" "arg" ", ... "
54 .BI " /* pid_t *" parent_tid ", void *" tls \
55 ", pid_t *" child_tid " */ );"
57 /* For the prototype of the raw clone() system call, see NOTES */
59 .BI "long clone3(struct clone_args *" cl_args ", size_t " size );
63 There is not yet a glibc wrapper for
68 create a new ("child") process, in a manner similar to
73 these system calls provide more precise control over what pieces of execution
74 context are shared between the calling process and the child process.
75 For example, using these system calls, the caller can control whether
76 or not the two processes share the virtual address space,
77 the table of file descriptors, and the table of signal handlers.
78 These system calls also allow the new child process to be placed
82 Note that in this manual
83 page, "calling process" normally corresponds to "parent process".
84 But see the descriptions of
90 This page describes the following interfaces:
94 wrapper function and the underlying system call on which it is based.
95 The main text describes the wrapper function;
96 the differences for the raw system call
97 are described toward the end of this page.
103 In the remainder of this page, the terminology "the clone call" is used
104 when noting details that apply to all of these interfaces,
106 .SS The clone() wrapper function
108 When the child process is created with the
111 it commences execution by calling the function pointed to by the argument
115 where execution continues in the child from the point
121 argument is passed as the argument of the function
126 function returns, the child process terminates.
127 The integer returned by
129 is the exit status for the child process.
130 The child process may also terminate explicitly by calling
132 or after receiving a fatal signal.
136 argument specifies the location of the stack used by the child process.
137 Since the child and calling process may share memory,
138 it is not possible for the child process to execute in the
139 same stack as the calling process.
140 The calling process must therefore
141 set up memory space for the child stack and pass a pointer to this
144 Stacks grow downward on all processors that run Linux
145 (except the HP PA processors), so
147 usually points to the topmost address of the memory space set up for
151 does not provide a means whereby the caller can inform the kernel of the
152 size of the stack area.
154 The remaining arguments to
162 system call provides a superset of the functionality of the older
165 It also provides a number of API improvements, including:
166 space for additional flags bits;
167 cleaner separation in the use of various arguments;
168 and the ability to specify the size of the child's stack area.
173 returns in both the parent and the child.
174 It returns 0 in the child process and returns the PID of the child
181 is a structure of the following form:
186 u64 flags; /* Flags bit mask */
187 u64 pidfd; /* Where to store PID file descriptor
189 u64 child_tid; /* Where to store child TID,
190 in child's memory (\fIpid_t *\fP) */
191 u64 parent_tid; /* Where to store child TID,
192 in parent's memory (\fIint *\fP) */
193 u64 exit_signal; /* Signal to deliver to parent on
195 u64 stack; /* Pointer to lowest byte of stack */
196 u64 stack_size; /* Size of stack */
197 u64 tls; /* Location of new TLS */
198 u64 set_tid; /* Pointer to a \fIpid_t\fP array
200 u64 set_tid_size; /* Number of elements in \fIset_tid\fP
202 u64 cgroup; /* File descriptor for target cgroup
203 of child (since Linux 5.7) */
210 argument that is supplied to
212 should be initialized to the size of this structure.
213 (The existence of the
215 argument permits future extensions to the
219 The stack for the child process is specified via
221 which points to the lowest byte of the stack area,
223 .IR cl_args.stack_size ,
224 which specifies the size of the stack in bytes.
225 In the case where the
227 flag (see below) is specified, a stack must be explicitly allocated
229 Otherwise, these two fields can be specified as NULL and 0,
230 which causes the child to use the same stack area as the parent
231 (in the child's own virtual address space).
233 The remaining fields in the
235 argument are discussed below.
237 .SS Equivalence between clone() and clone3() arguments
241 interface, where arguments are passed individually, in the newer
243 interface the arguments are packaged into the
245 structure shown above.
246 This structure allows for a superset of the information passed via the
250 The following table shows the equivalence between the arguments of
252 and the fields in the
261 clone() clone3() Notes
263 flags & ~0xff flags For most flags; details below
264 parent_tid pidfd See CLONE_PIDFD
265 child_tid child_tid See CLONE_CHILD_SETTID
266 parent_tid parent_tid See CLONE_PARENT_SETTID
267 flags & 0xff exit_signal
270 tls tls See CLONE_SETTLS
271 \fP---\fP set_tid See below for details
272 \fP---\fP set_tid_size
273 \fP---\fP cgroup See CLONE_INTO_CGROUP
277 .SS The child termination signal
279 When the child process terminates, a signal may be sent to the parent.
280 The termination signal is specified in the low byte of
284 .I cl_args.exit_signal
286 If this signal is specified as anything other than
288 then the parent process must specify the
292 options when waiting for the child with
294 If no signal (i.e., zero) is specified, then the parent process is not signaled
295 when the child terminates.
297 .SS The set_tid array
299 By default, the kernel chooses the next sequential PID for the new
300 process in each of the PID namespaces where it is present.
301 When creating a process with
305 array (available since Linux 5.5)
306 can be used to select specific PIDs for the process in some
307 or all of the PID namespaces where it is present.
308 If the PID of the newly created process should be set only for the current
309 PID namespace or in the newly created PID namespace (if
313 then the first element in the
315 array has to be the desired PID and
319 If the PID of the newly created process should have a certain value in
320 multiple PID namespaces, then the
322 array can have multiple entries.
323 The first entry defines the PID in the most
324 deeply nested PID namespace and each of the following entries contains
326 corresponding ancestor PID namespace.
327 The number of PID namespaces in which a PID
328 should be set is defined by
330 which cannot be larger than the number of currently nested PID namespaces.
332 To create a process with the following PIDs in a PID namespace hierarchy:
337 PID NS level Requested PID Notes
338 0 31496 Outermost PID namespace
340 2 7 Innermost PID namespace
355 If only the PIDs in the two innermost PID namespaces
356 need to be specified, set the array to:
366 The PID in the PID namespaces outside the two innermost PID namespaces
367 will be selected the same way as any other PID is selected.
373 in all owning user namespaces of the target PID namespaces.
375 Callers may only choose a PID greater than 1 in a given PID namespace
378 process (i.e., a process with PID 1) already exists in that namespace.
380 entry for this PID namespace must be 1.
388 allow a flags bit mask that modifies their behavior
389 and allows the caller to specify what is shared between the calling process
390 and the child process.
401 mask in the remainder of this page.
405 mask is specified as a bitwise-OR of zero or more of
406 the constants listed below.
407 Except as noted below, these flags are available
408 (and have the same effect) in both
413 .BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)"
414 Clear (zero) the child thread ID at the location pointed to by
420 in child memory when the child exits, and do a wakeup on the futex
422 The address involved may be changed by the
423 .BR set_tid_address (2)
425 This is used by threading libraries.
427 .BR CLONE_CHILD_SETTID " (since Linux 2.5.49)"
428 Store the child thread ID at the location pointed to by
434 in the child's memory.
435 The store operation completes before the clone call
436 returns control to user space in the child process.
437 (Note that the store operation may not have completed before the clone call
438 returns in the parent process, which will be relevant if the
440 flag is also employed.)
442 .BR CLONE_CLEAR_SIGHAND " (since Linux 5.5)"
443 .\" commit b612e5df4587c934bd056bf05f4a1deca4de4f75
444 By default, signal dispositions in the child thread are the same as
446 If this flag is specified,
447 then all signals that are handled in the parent
448 are reset to their default dispositions
452 Specifying this flag together with
454 is nonsensical and disallowed.
456 .BR CLONE_DETACHED " (historical)"
457 For a while (during the Linux 2.5 development series)
458 .\" added in 2.5.32; removed in 2.6.0-test4
462 which caused the parent not to receive a signal when the child terminated.
463 Ultimately, the effect of this flag was subsumed under the
465 flag and by the time Linux 2.6.0 was released, this flag had no effect.
466 Starting in Linux 2.6.2, the need to give this flag together with
470 This flag is still defined, but it is usually ignored when calling
472 However, see the description of
476 .BR CLONE_FILES " (since Linux 2.0)"
479 is set, the calling process and the child process share the same file
481 Any file descriptor created by the calling process or by the child
482 process is also valid in the other process.
483 Similarly, if one of the processes closes a file descriptor,
484 or changes its associated flags (using the
487 operation), the other process is also affected.
488 If a process sharing a file descriptor table calls
490 its file descriptor table is duplicated (unshared).
494 is not set, the child process inherits a copy of all file descriptors
495 opened in the calling process at the time of the clone call.
496 Subsequent operations that open or close file descriptors,
497 or change file descriptor flags,
498 performed by either the calling
499 process or the child process do not affect the other process.
501 that the duplicated file descriptors in the child refer to the same
502 open file descriptions as the corresponding file descriptors
503 in the calling process,
504 and thus share file offsets and file status flags (see
507 .BR CLONE_FS " (since Linux 2.0)"
510 is set, the caller and the child process share the same filesystem
512 This includes the root of the filesystem, the current
513 working directory, and the umask.
519 performed by the calling process or the child process also affects the
524 is not set, the child process works on a copy of the filesystem
525 information of the calling process at the time of the clone call.
531 performed later by one of the processes do not affect the other process.
533 .BR CLONE_INTO_CGROUP " (since Linux 5.7)"
534 .\" commit ef2c41cf38a7559bbf91af42d5b6a4429db8fc68
535 By default, a child process is placed in the same version 2
536 cgroup as its parent.
539 flag allows the child process to be created in a different version 2 cgroup.
541 .BR CLONE_INTO_CGROUP
542 has effect only for version 2 cgroups.)
544 In order to place the child process in a different cgroup,
546 .BR CLONE_INTO_CGROUP
549 and passes a file descriptor that refers to a version 2 cgroup in the
552 (This file descriptor can be obtained by opening a cgroup v2 directory
558 Note that all of the usual restrictions (described in
560 on placing a process into a version 2 cgroup apply.
562 Spawning a process into a cgroup different from the parent's cgroup
563 makes it possible for a service manager to directly spawn new
564 services into dedicated cgroups.
565 This eliminates the accounting
566 jitter that would be caused if the child process was first created in the
567 same cgroup as the parent and then
568 moved into the target cgroup.
570 .BR CLONE_INTO_CGROUP
571 flag also allows the creation of
572 frozen child processes by spawning them into a frozen cgroup.
575 for a description of the freezer controller.)
576 For threaded applications (or even thread implementations which
577 make use of cgroups to limit individual threads), it is possible to
578 establish a fixed cgroup layout before spawning each thread
579 directly into its target cgroup.
581 .BR CLONE_IO " (since Linux 2.6.25)"
584 is set, then the new process shares an I/O context with
586 If this flag is not set, then (as with
588 the new process has its own I/O context.
590 .\" The following based on text from Jens Axboe
591 The I/O context is the I/O scope of the disk scheduler (i.e.,
592 what the I/O scheduler uses to model scheduling of a process's I/O).
593 If processes share the same I/O context,
594 they are treated as one by the I/O scheduler.
595 As a consequence, they get to share disk time.
596 For some I/O schedulers,
597 .\" the anticipatory and CFQ scheduler
598 if two processes share an I/O context,
599 they will be allowed to interleave their disk access.
600 If several threads are doing I/O on behalf of the same process
602 for instance), they should employ
604 to get better I/O performance.
607 If the kernel is not configured with the
609 option, this flag is a no-op.
611 .BR CLONE_NEWCGROUP " (since Linux 4.6)"
612 Create the process in a new cgroup namespace.
613 If this flag is not set, then (as with
615 the process is created in the same cgroup namespaces as the calling process.
617 For further information on cgroup namespaces, see
618 .BR cgroup_namespaces (7).
620 Only a privileged process
621 .RB ( CAP_SYS_ADMIN )
623 .BR CLONE_NEWCGROUP .
626 .BR CLONE_NEWIPC " (since Linux 2.6.19)"
629 is set, then create the process in a new IPC namespace.
630 If this flag is not set, then (as with
632 the process is created in the same IPC namespace as
635 For further information on IPC namespaces, see
636 .BR ipc_namespaces (7).
638 Only a privileged process
639 .RB ( CAP_SYS_ADMIN )
642 This flag can't be specified in conjunction with
645 .BR CLONE_NEWNET " (since Linux 2.6.24)"
646 (The implementation of this flag was completed only
647 by about kernel version 2.6.29.)
651 is set, then create the process in a new network namespace.
652 If this flag is not set, then (as with
654 the process is created in the same network namespace as
657 For further information on network namespaces, see
658 .BR network_namespaces (7).
660 Only a privileged process
661 .RB ( CAP_SYS_ADMIN )
665 .BR CLONE_NEWNS " (since Linux 2.4.19)"
668 is set, the cloned child is started in a new mount namespace,
669 initialized with a copy of the namespace of the parent.
672 is not set, the child lives in the same mount
673 namespace as the parent.
675 For further information on mount namespaces, see
678 .BR mount_namespaces (7).
680 Only a privileged process
681 .RB ( CAP_SYS_ADMIN )
684 It is not permitted to specify both
688 .\" See https://lwn.net/Articles/543273/
689 in the same clone call.
691 .BR CLONE_NEWPID " (since Linux 2.6.24)"
692 .\" This explanation draws a lot of details from
693 .\" http://lwn.net/Articles/259217/
694 .\" Authors: Pavel Emelyanov <xemul@openvz.org>
695 .\" and Kir Kolyshkin <kir@openvz.org>
697 .\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264
698 .\" Author: Pavel Emelyanov <xemul@openvz.org>
701 is set, then create the process in a new PID namespace.
702 If this flag is not set, then (as with
704 the process is created in the same PID namespace as
707 For further information on PID namespaces, see
710 .BR pid_namespaces (7).
712 Only a privileged process
713 .RB ( CAP_SYS_ADMIN )
716 This flag can't be specified in conjunction with
722 (This flag first became meaningful for
727 semantics were merged in Linux 3.5,
728 and the final pieces to make the user namespaces completely usable were
729 merged in Linux 3.8.)
733 is set, then create the process in a new user namespace.
734 If this flag is not set, then (as with
736 the process is created in the same user namespace as the calling process.
738 For further information on user namespaces, see
741 .BR user_namespaces (7).
743 Before Linux 3.8, use of
745 required that the caller have three capabilities:
750 .\" Before Linux 2.6.29, it appears that only CAP_SYS_ADMIN was needed
751 Starting with Linux 3.8,
752 no privileges are needed to create a user namespace.
754 This flag can't be specified in conjunction with
758 For security reasons,
759 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
760 .\" https://lwn.net/Articles/543273/
761 .\" The fix actually went into 3.9 and into 3.8.3. However, user namespaces
762 .\" were, for practical purposes, unusable in earlier 3.8.x because of the
763 .\" various filesystems that didn't support userns.
765 cannot be specified in conjunction with
768 .BR CLONE_NEWUTS " (since Linux 2.6.19)"
771 is set, then create the process in a new UTS namespace,
772 whose identifiers are initialized by duplicating the identifiers
773 from the UTS namespace of the calling process.
774 If this flag is not set, then (as with
776 the process is created in the same UTS namespace as
779 For further information on UTS namespaces, see
780 .BR uts_namespaces (7).
782 Only a privileged process
783 .RB ( CAP_SYS_ADMIN )
787 .BR CLONE_PARENT " (since Linux 2.3.12)"
790 is set, then the parent of the new child (as returned by
792 will be the same as that of the calling process.
796 is not set, then (as with
798 the child's parent is the calling process.
800 Note that it is the parent process, as returned by
802 which is signaled when the child terminates, so that
805 is set, then the parent of the calling process, rather than the
806 calling process itself, will be signaled.
810 flag can't be used in clone calls by the
811 global init process (PID 1 in the initial PID namespace)
812 and init processes in other PID namespaces.
813 This restriction prevents the creation of multi-rooted process trees
814 as well as the creation of unreapable zombies in the initial PID namespace.
816 .BR CLONE_PARENT_SETTID " (since Linux 2.5.49)"
817 Store the child thread ID at the location pointed to by
821 .I cl_args.parent_tid
823 in the parent's memory.
824 (In Linux 2.5.32-2.5.48 there was a flag
827 The store operation completes before the clone call
828 returns control to user space.
830 .BR CLONE_PID " (Linux 2.0 to 2.5.15)"
833 is set, the child process is created with the same process ID as
835 This is good for hacking the system, but otherwise
837 From Linux 2.3.21 onward, this flag could be
838 specified only by the system boot process (PID 0).
839 The flag disappeared completely from the kernel sources in Linux 2.5.16.
840 Subsequently, the kernel silently ignored this bit if it was specified in the
843 Much later, the same bit was recycled for use as the
847 .BR CLONE_PIDFD " (since Linux 5.2)"
848 .\" commit b3e5838252665ee4cfa76b82bdf1198dca81e5be
849 If this flag is specified,
850 a PID file descriptor referring to the child process is allocated
851 and placed at a specified location in the parent's memory.
852 The close-on-exec flag is set on this new file descriptor.
853 PID file descriptors can be used for the purposes described in
859 the PID file descriptor is placed at the location pointed to by
864 the PID file descriptor is placed at the location pointed to by
868 argument is used to return the PID file descriptor,
871 .B CLONE_PARENT_SETTID
876 It is currently not possible to use this flag together with
878 This means that the process identified by the PID file descriptor
879 will always be a thread group leader.
883 flag is specified alongside
887 an error is returned.
888 An error also results if
890 is specified when calling
892 This error behavior ensures that the bit corresponding to
894 can be reused for further PID file descriptor features in the future.
896 .BR CLONE_PTRACE " (since Linux 2.2)"
899 is specified, and the calling process is being traced,
900 then trace the child also (see
903 .BR CLONE_SETTLS " (since Linux 2.5.32)"
904 The TLS (Thread Local Storage) descriptor is set to
907 The interpretation of
909 and the resulting effect is architecture dependent.
913 .IR "struct user_desc\ *"
915 .BR set_thread_area (2)).
916 On x86-64 it is the new value to be set for the %fs base register
921 On architectures with a dedicated TLS register, it is the new value
924 Use of this flag requires detailed knowledge and generally it
925 should not be used except in libraries implementing threading.
927 .BR CLONE_SIGHAND " (since Linux 2.0)"
930 is set, the calling process and the child process share the same table of
932 If the calling process or child process calls
934 to change the behavior associated with a signal, the behavior is
935 changed in the other process as well.
936 However, the calling process and child
937 processes still have distinct signal masks and sets of pending
939 So, one of them may block or unblock signals using
941 without affecting the other process.
945 is not set, the child process inherits a copy of the signal handlers
946 of the calling process at the time of the clone call.
949 performed later by one of the processes have no effect on the other
953 .\" Precisely: Linux 2.6.0-test6
956 mask must also include
962 .BR CLONE_STOPPED " (since Linux 2.6.0)"
963 .\" Precisely: Linux 2.6.0-test2
966 is set, then the child is initially stopped (as though it was sent a
968 signal), and must be resumed by sending it a
974 from Linux 2.6.25 onward,
977 altogether in Linux 2.6.38.
978 Since then, the kernel silently ignores it without error.
979 .\" glibc 2.8 removed this defn from bits/sched.h
980 Starting with Linux 4.6, the same bit was reused for the
984 .BR CLONE_SYSVSEM " (since Linux 2.5.10)"
987 is set, then the child and the calling process share
988 a single list of System V semaphore adjustment
992 In this case, the shared list accumulates
994 values across all processes sharing the list,
995 and semaphore adjustments are performed only when the last process
996 that is sharing the list terminates (or ceases sharing the list using
998 If this flag is not set, then the child has a separate
1000 list that is initially empty.
1002 .BR CLONE_THREAD " (since Linux 2.4.0)"
1003 .\" Precisely: Linux 2.6.0-test8
1006 is set, the child is placed in the same thread group as the calling process.
1007 To make the remainder of the discussion of
1009 more readable, the term "thread" is used to refer to the
1010 processes within a thread group.
1012 Thread groups were a feature added in Linux 2.4 to support the
1013 POSIX threads notion of a set of threads that share a single PID.
1014 Internally, this shared PID is the so-called
1015 thread group identifier (TGID) for the thread group.
1016 Since Linux 2.4, calls to
1018 return the TGID of the caller.
1020 The threads within a group can be distinguished by their (system-wide)
1021 unique thread IDs (TID).
1022 A new thread's TID is available as the function result
1023 returned to the caller,
1024 and a thread can obtain
1028 When a clone call is made without specifying
1030 then the resulting thread is placed in a new thread group
1031 whose TGID is the same as the thread's TID.
1034 of the new thread group.
1036 A new thread created with
1038 has the same parent process as the process that made the clone call
1043 return the same value for all of the threads in a thread group.
1046 thread terminates, the thread that created it is not sent a
1048 (or other termination) signal;
1049 nor can the status of such a thread be obtained
1052 (The thread is said to be
1055 After all of the threads in a thread group terminate
1056 the parent process of the thread group is sent a
1058 (or other termination) signal.
1060 If any of the threads in a thread group performs an
1062 then all threads other than the thread group leader are terminated,
1063 and the new program is executed in the thread group leader.
1065 If one of the threads in a thread group creates a child using
1067 then any thread in the group can
1071 Since Linux 2.5.35, the
1073 mask must also include
1078 (and note that, since Linux 2.6.0,
1079 .\" Precisely: Linux 2.6.0-test6
1085 Signal dispositions and actions are process-wide:
1086 if an unhandled signal is delivered to a thread, then
1087 it will affect (terminate, stop, continue, be ignored in)
1088 all members of the thread group.
1090 Each thread has its own signal mask, as set by
1091 .BR sigprocmask (2).
1093 A signal may be process-directed or thread-directed.
1094 A process-directed signal is targeted at a thread group (i.e., a TGID),
1095 and is delivered to an arbitrarily selected thread from among those
1096 that are not blocking the signal.
1097 A signal may be process-directed because it was generated by the kernel
1098 for reasons other than a hardware exception, or because it was sent using
1102 A thread-directed signal is targeted at (i.e., delivered to)
1104 A signal may be thread directed because it was sent using
1107 .BR pthread_sigqueue (3),
1108 or because the thread executed a machine language instruction that triggered
1109 a hardware exception
1110 (e.g., invalid memory access triggering
1112 or a floating-point exception triggering
1117 returns a signal set that is the union of the pending process-directed
1118 signals and the signals that are pending for the calling thread.
1120 If a process-directed signal is delivered to a thread group,
1121 and the thread group has installed a handler for the signal, then
1122 the handler will be invoked in exactly one, arbitrarily selected
1123 member of the thread group that has not blocked the signal.
1124 If multiple threads in a group are waiting to accept the same signal using
1125 .BR sigwaitinfo (2),
1126 the kernel will arbitrarily select one of these threads
1127 to receive the signal.
1129 .BR CLONE_UNTRACED " (since Linux 2.5.46)"
1132 is specified, then a tracing process cannot force
1134 on this child process.
1136 .BR CLONE_VFORK " (since Linux 2.2)"
1139 is set, the execution of the calling process is suspended
1140 until the child releases its virtual memory
1141 resources via a call to
1150 is not set, then both the calling process and the child are schedulable
1151 after the call, and an application should not rely on execution occurring
1152 in any particular order.
1154 .BR CLONE_VM " (since Linux 2.0)"
1157 is set, the calling process and the child process run in the same memory
1159 In particular, memory writes performed by the calling process
1160 or by the child process are also visible in the other process.
1161 Moreover, any memory mapping or unmapping performed with
1165 by the child or calling process also affects the other process.
1169 is not set, the child process runs in a separate copy of the memory
1170 space of the calling process at the time of the clone call.
1171 Memory writes or file mappings/unmappings performed by one of the
1172 processes do not affect the other, as with
1175 .\" gettid(2) returns current->pid;
1176 .\" getpid(2) returns current->tgid;
1177 On success, the thread ID of the child process is returned
1178 in the caller's thread of execution.
1179 On failure, \-1 is returned
1180 in the caller's context, no child process will be created, and
1182 will be set appropriately.
1186 Too many processes are already running; see
1189 .BR EBUSY " (" clone3 "() only)"
1190 .B CLONE_INTO_CGROUP
1193 but the file descriptor specified in
1195 refers to a version 2 cgroup in which a domain controller is enabled.
1197 .BR EEXIST " (" clone3 "() only)"
1198 One (or more) of the PIDs specified in
1200 already exists in the corresponding PID namespace.
1206 .B CLONE_CLEAR_SIGHAND
1207 were specified in the
1213 was specified in the
1218 (Since Linux 2.6.0.)
1219 .\" Precisely: Linux 2.6.0-test6
1223 was specified in the
1228 (Since Linux 2.5.35.)
1231 .\" Precisely one of
1232 .\" .B CLONE_DETACHED
1236 .\" (Since Linux 2.6.0-test6.)
1240 was specified in the
1242 mask, but the current process previously called
1248 to reassociate itself with a PID namespace.
1251 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
1256 were specified in the
1260 .BR EINVAL " (since Linux 3.9)"
1265 were specified in the
1274 were specified in the
1283 and one (or both) of
1287 were specified in the
1291 .BR EINVAL " (since Linux 2.6.32)"
1292 .\" commit 123be07b0b399670a7cc3d82fef0cb4f93ef885c
1294 was specified, and the caller is an init process.
1297 Returned by the glibc
1299 wrapper function when
1303 is specified as NULL.
1307 was specified in the
1310 but the kernel was not configured with the
1318 was specified in the
1321 but the kernel was not configured with the
1327 was specified in the
1330 but the kernel was not configured with the
1336 was specified in the
1339 but the kernel was not configured with the
1345 was specified in the
1348 but the kernel was not configured with the
1354 is not aligned to a suitable boundary for this architecture.
1355 For example, on aarch64,
1357 must be a multiple of 16.
1359 .BR EINVAL " (" clone3 "() only)"
1361 was specified in the
1365 .BR EINVAL " (" clone "() only)"
1367 was specified together with
1375 was specified together with
1381 .BR "EINVAL " "(" clone "() only)"
1383 was specified together with
1384 .B CLONE_PARENT_SETTID
1389 .BR EINVAL " (" clone3 "() only)"
1391 is greater than the number of nested PID namespaces.
1393 .BR EINVAL " (" clone3 "() only)"
1394 One of the PIDs specified in
1398 .BR EINVAL " (AArch64 only, Linux 4.6 and earlier)"
1400 was not aligned to a 126-bit boundary.
1403 Cannot allocate sufficient memory to allocate a task structure for the
1404 child, or to copy those parts of the caller's context that need to be
1407 .BR ENOSPC " (since Linux 3.7)"
1408 .\" commit f2302505775fd13ba93f034206f1e2a587017929
1410 was specified in the
1413 but the limit on the nesting depth of PID namespaces
1414 would have been exceeded; see
1415 .BR pid_namespaces (7).
1417 .BR ENOSPC " (since Linux 4.9; beforehand " EUSERS )
1419 was specified in the
1421 mask, and the call would cause the limit on the number of
1422 nested user namespaces to be exceeded.
1424 .BR user_namespaces (7).
1426 From Linux 3.11 to Linux 4.8, the error diagnosed in this case was
1429 .BR ENOSPC " (since Linux 4.9)"
1430 One of the values in the
1432 mask specified the creation of a new user namespace,
1433 but doing so would have caused the limit defined by the corresponding file in
1436 For further details, see
1439 .BR EOPNOTSUP " (" clone3 "() only)"
1440 .B CLONE_INTO_CGROUP
1443 but the file descriptor specified in
1445 refers to a version 2 cgroup that is in the
1446 .IR "domain invalid"
1450 .BR CLONE_NEWCGROUP ,
1457 was specified by an unprivileged process (process without \fBCAP_SYS_ADMIN\fP).
1461 was specified by a process other than process 0.
1462 (This error occurs only on Linux 2.5.15 and earlier.)
1466 was specified in the
1469 but either the effective user ID or the effective group ID of the caller
1470 does not have a mapping in the parent namespace (see
1471 .BR user_namespaces (7)).
1473 .BR EPERM " (since Linux 3.9)"
1474 .\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d
1476 was specified in the
1478 mask and the caller is in a chroot environment
1479 .\" FIXME What is the rationale for this restriction?
1480 (i.e., the caller's root directory does not match the root directory
1481 of the mount namespace in which it resides).
1483 .BR EPERM " (" clone3 "() only)"
1485 was greater than zero, and the caller lacks the
1487 capability in one or more of the user namespaces that own the
1488 corresponding PID namespaces.
1490 .BR ERESTARTNOINTR " (since Linux 2.6.17)"
1491 .\" commit 4a2c7a7837da1b91468e50426066d988050e4d56
1492 System call was interrupted by a signal and will be restarted.
1493 (This can be seen only during a trace.)
1495 .BR EUSERS " (Linux 3.11 to Linux 4.8)"
1497 was specified in the
1500 and the limit on the number of nested user namespaces would be exceeded.
1501 See the discussion of the
1507 system call first appeared in Linux 5.3.
1508 .\" There is no entry for
1513 .\" as described in this manual page.
1516 are Linux-specific and should not be used in programs
1517 intended to be portable.
1520 One use of these systems calls
1521 is to implement threads: multiple flows of control in a program that
1522 run concurrently in a shared address space.
1524 Glibc does not provide a wrapper for
1531 wrapper function makes some changes
1532 in the memory pointed to by
1534 (changes required to set the stack up correctly for the child)
1541 is used to recursively create children,
1542 do not use the buffer employed for the parent's stack
1543 as the stack of the child.
1547 system call can be used to test whether two processes share various
1548 resources such as a file descriptor table,
1549 System V semaphore undo operations, or a virtual address space.
1552 Handlers registered using
1553 .BR pthread_atfork (3)
1554 are not executed during a clone call.
1556 In the Linux 2.4.x series,
1558 generally does not make the parent of the new thread the same
1559 as the parent of the calling process.
1560 However, for kernel versions 2.4.7 to 2.4.18 the
1564 flag (as in Linux 2.6.0 and later).
1568 should not be called through vsyscall, but directly through
1571 .SS C library/kernel differences
1574 system call corresponds more closely to
1576 in that execution in the child continues from the point of the
1584 wrapper function are omitted.
1586 In contrast to the glibc wrapper, the raw
1588 system call accepts NULL as a
1595 In this case, the child uses a duplicate of the parent's stack.
1596 (Copy-on-write semantics ensure that the child gets separate copies
1597 of stack pages when either process modifies the stack.)
1598 In this case, for correct operation, the
1600 option should not be specified.
1603 the parent's memory because of the use of the
1606 then no copy-on-write duplication occurs and chaos is likely to result.)
1608 The order of the arguments also differs in the raw system call,
1609 and there are variations in the arguments across architectures,
1610 as detailed in the following paragraphs.
1612 The raw system call interface on x86-64 and some other architectures
1613 (including sh, tile, and alpha) is:
1617 .BI "long clone(unsigned long " flags ", void *" stack ,
1618 .BI " int *" parent_tid ", int *" child_tid ,
1619 .BI " unsigned long " tls );
1623 On x86-32, and several other common architectures
1624 (including score, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa,
1626 .\" CONFIG_CLONE_BACKWARDS
1627 the order of the last two arguments is reversed:
1631 .BI "long clone(unsigned long " flags ", void *" stack ,
1632 .BI " int *" parent_tid ", unsigned long " tls ,
1633 .BI " int *" child_tid );
1637 On the cris and s390 architectures,
1638 .\" CONFIG_CLONE_BACKWARDS2
1639 the order of the first two arguments is reversed:
1643 .BI "long clone(void *" stack ", unsigned long " flags ,
1644 .BI " int *" parent_tid ", int *" child_tid ,
1645 .BI " unsigned long " tls );
1649 On the microblaze architecture,
1650 .\" CONFIG_CLONE_BACKWARDS3
1651 an additional argument is supplied:
1655 .BI "long clone(unsigned long " flags ", void *" stack ,
1656 .BI " int " stack_size , "\fR /* Size of stack */"
1657 .BI " int *" parent_tid ", int *" child_tid ,
1658 .BI " unsigned long " tls );
1662 .SS blackfin, m68k, and sparc
1663 .\" Mike Frysinger noted in a 2013 mail:
1664 .\" these arches don't define __ARCH_WANT_SYS_CLONE:
1665 .\" blackfin ia64 m68k sparc
1666 The argument-passing conventions on
1667 blackfin, m68k, and sparc are different from the descriptions above.
1668 For details, see the kernel (and glibc) source.
1670 On ia64, a different interface is used:
1674 .BI "int __clone2(int (*" "fn" ")(void *), "
1675 .BI " void *" stack_base ", size_t " stack_size ,
1676 .BI " int " flags ", void *" "arg" ", ... "
1677 .BI " /* pid_t *" parent_tid ", struct user_desc *" tls ,
1678 .BI " pid_t *" child_tid " */ );"
1682 The prototype shown above is for the glibc wrapper function;
1683 for the system call itself,
1684 the prototype can be described as follows (it is identical to the
1686 prototype on microblaze):
1690 .BI "long clone2(unsigned long " flags ", void *" stack_base ,
1691 .BI " int " stack_size , "\fR /* Size of stack */"
1692 .BI " int *" parent_tid ", int *" child_tid ,
1693 .BI " unsigned long " tls );
1698 operates in the same way as
1702 points to the lowest address of the child's stack area,
1705 specifies the size of the stack pointed to by
1707 .SS Linux 2.4 and earlier
1708 In Linux 2.4 and earlier,
1710 does not take arguments
1716 GNU C library versions 2.3.4 up to and including 2.24
1717 contained a wrapper function for
1719 that performed caching of PIDs.
1720 This caching relied on support in the glibc wrapper for
1722 but limitations in the implementation
1723 meant that the cache was not up to date in some circumstances.
1725 if a signal was delivered to the child immediately after the
1727 call, then a call to
1729 in a handler for the signal could return the PID
1730 of the calling process ("the parent"),
1731 if the clone wrapper had not yet had a chance to update the PID
1733 (This discussion ignores the case where the child was created using
1738 return the same value in the child and in the process that called
1740 since the caller and the child are in the same thread group.
1741 The stale-cache problem also does not occur if the
1745 To get the truth, it was sometimes necessary to use code such as the following:
1749 #include <syscall.h>
1753 mypid = syscall(SYS_getpid);
1756 .\" See also the following bug reports
1757 .\" https://bugzilla.redhat.com/show_bug.cgi?id=417521
1758 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910
1760 Because of the stale-cache problem, as well as other problems noted in
1762 the PID caching feature was removed in glibc 2.25.
1764 The following program demonstrates the use of
1766 to create a child process that executes in a separate UTS namespace.
1767 The child changes the hostname in its UTS namespace.
1768 Both parent and child then display the system hostname,
1769 making it possible to see that the hostname
1770 differs in the UTS namespaces of the parent and child.
1771 For an example of the use of this program, see
1774 Within the sample program, we allocate the memory that is to
1775 be used for the child's stack using
1779 for the following reasons:
1782 allocates a block of memory that starts on a page
1783 boundary and is a multiple of the page size.
1784 This is useful if we want to establish a guard page (a page with protection
1786 at the end of the stack using
1791 flag to request a mapping that is suitable for a stack.
1792 For the moment, this flag is a no-op on Linux,
1793 but it exists and has effect on some other systems,
1794 so we should include it for portability.
1798 #include <sys/wait.h>
1799 #include <sys/utsname.h>
1805 #include <sys/mman.h>
1807 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
1810 static int /* Start function for cloned child */
1811 childFunc(void *arg)
1815 /* Change hostname in UTS namespace of child */
1817 if (sethostname(arg, strlen(arg)) == \-1)
1818 errExit("sethostname");
1820 /* Retrieve and display hostname */
1822 if (uname(&uts) == \-1)
1824 printf("uts.nodename in child: %s\en", uts.nodename);
1826 /* Keep the namespace open for a while, by sleeping.
1827 This allows some experimentation\-\-for example, another
1828 process might join the namespace. */
1832 return 0; /* Child terminates now */
1835 #define STACK_SIZE (1024 * 1024) /* Stack size for cloned child */
1838 main(int argc, char *argv[])
1840 char *stack; /* Start of stack buffer */
1841 char *stackTop; /* End of stack buffer */
1846 fprintf(stderr, "Usage: %s <child\-hostname>\en", argv[0]);
1850 /* Allocate memory to be used for the stack of the child */
1852 stack = mmap(NULL, STACK_SIZE, PROT_READ | PROT_WRITE,
1853 MAP_PRIVATE | MAP_ANONYMOUS | MAP_STACK, \-1, 0);
1854 if (stack == MAP_FAILED)
1857 stackTop = stack + STACK_SIZE; /* Assume stack grows downward */
1859 /* Create child that has its own UTS namespace;
1860 child commences execution in childFunc() */
1862 pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]);
1865 printf("clone() returned %ld\en", (long) pid);
1867 /* Parent falls through to here */
1869 sleep(1); /* Give child time to change its hostname */
1871 /* Display hostname in parent\(aqs UTS namespace. This will be
1872 different from hostname in child\(aqs UTS namespace. */
1874 if (uname(&uts) == \-1)
1876 printf("uts.nodename in parent: %s\en", uts.nodename);
1878 if (waitpid(pid, NULL, 0) == \-1) /* Wait for child */
1880 printf("child has terminated\en");
1893 .BR set_thread_area (2),
1894 .BR set_tid_address (2),
1899 .BR capabilities (7),