1CLONE(2) Linux Programmer's Manual CLONE(2)
2
6 clone, __clone2, clone3 - create a child process
7
9 /* Prototype for the glibc wrapper function */
10 #define _GNU_SOURCE
12 #include <sched.h>
13 int clone(int (*fn)(void *), void *stack, int flags, void *arg, ...
15 /* pid_t *parent_tid, void *tls, pid_t *child_tid */ );
16 /* For the prototype of the raw clone() system call, see NOTES */
18 #include <linux/sched.h> /* Definition of struct clone_args */
20 #include <sched.h> /* Definition of CLONE_* constants */
21 #include <sys/syscall.h> /* Definition of SYS_* constants */
22 #include <unistd.h>
23 long syscall(SYS_clone3, struct clone_args *cl_args, size_t size);
25 Note: glibc provides no wrapper for clone3(), necessitating the use of
27 syscall(2).
28
30 These system calls create a new ("child") process, in a manner similar
31 to fork(2).
32 By contrast with fork(2), these system calls provide more precise con‐
34 trol over what pieces of execution context are shared between the call‐
35 ing process and the child process. For example, using these system
36 calls, the caller can control whether or not the two processes share
37 the virtual address space, the table of file descriptors, and the table
38 of signal handlers. These system calls also allow the new child
39 process to be placed in separate namespaces(7).
40 Note that in this manual page, "calling process" normally corresponds
42 to "parent process". But see the descriptions of CLONE_PARENT and
43 CLONE_THREAD below.
44 This page describes the following interfaces:
46 * The glibc clone() wrapper function and the underlying system call on
48 which it is based. The main text describes the wrapper function;
49 the differences for the raw system call are described toward the end
50 of this page.
51 * The newer clone3() system call.
53 In the remainder of this page, the terminology "the clone call" is used
55 when noting details that apply to all of these interfaces,
56 The clone() wrapper function
58 When the child process is created with the clone() wrapper function, it
59 commences execution by calling the function pointed to by the argument
60 fn. (This differs from fork(2), where execution continues in the child
61 from the point of the fork(2) call.) The arg argument is passed as the
62 argument of the function fn.
63 When the fn(arg) function returns, the child process terminates. The
65 integer returned by fn is the exit status for the child process. The
66 child process may also terminate explicitly by calling exit(2) or after
67 receiving a fatal signal.
68 The stack argument specifies the location of the stack used by the
70 child process. Since the child and calling process may share memory,
71 it is not possible for the child process to execute in the same stack
72 as the calling process. The calling process must therefore set up mem‐
73 ory space for the child stack and pass a pointer to this space to
74 clone(). Stacks grow downward on all processors that run Linux (except
75 the HP PA processors), so stack usually points to the topmost address
76 of the memory space set up for the child stack. Note that clone() does
77 not provide a means whereby the caller can inform the kernel of the
78 size of the stack area.
79 The remaining arguments to clone() are discussed below.
81 clone3()
83 The clone3() system call provides a superset of the functionality of
84 the older clone() interface. It also provides a number of API improve‐
85 ments, including: space for additional flags bits; cleaner separation
86 in the use of various arguments; and the ability to specify the size of
87 the child's stack area.
88 As with fork(2), clone3() returns in both the parent and the child. It
90 returns 0 in the child process and returns the PID of the child in the
91 parent.
92 The cl_args argument of clone3() is a structure of the following form:
94 struct clone_args {
96 u64 flags; /* Flags bit mask */
97 u64 pidfd; /* Where to store PID file descriptor
98 (int *) */
99 u64 child_tid; /* Where to store child TID,
100 in child's memory (pid_t *) */
101 u64 parent_tid; /* Where to store child TID,
102 in parent's memory (pid_t *) */
103 u64 exit_signal; /* Signal to deliver to parent on
104 child termination */
105 u64 stack; /* Pointer to lowest byte of stack */
106 u64 stack_size; /* Size of stack */
107 u64 tls; /* Location of new TLS */
108 u64 set_tid; /* Pointer to a pid_t array
109 (since Linux 5.5) */
110 u64 set_tid_size; /* Number of elements in set_tid
111 (since Linux 5.5) */
112 u64 cgroup; /* File descriptor for target cgroup
113 of child (since Linux 5.7) */
114 };
115 The size argument that is supplied to clone3() should be initialized to
117 the size of this structure. (The existence of the size argument per‐
118 mits future extensions to the clone_args structure.)
119 The stack for the child process is specified via cl_args.stack, which
121 points to the lowest byte of the stack area, and cl_args.stack_size,
122 which specifies the size of the stack in bytes. In the case where the
123 CLONE_VM flag (see below) is specified, a stack must be explicitly al‐
124 located and specified. Otherwise, these two fields can be specified as
125 NULL and 0, which causes the child to use the same stack area as the
126 parent (in the child's own virtual address space).
127 The remaining fields in the cl_args argument are discussed below.
129 Equivalence between clone() and clone3() arguments
131 Unlike the older clone() interface, where arguments are passed individ‐
132 ually, in the newer clone3() interface the arguments are packaged into
133 the clone_args structure shown above. This structure allows for a su‐
134 perset of the information passed via the clone() arguments.
135 The following table shows the equivalence between the arguments of
137 clone() and the fields in the clone_args argument supplied to clone3():
138 clone() clone3() Notes
140 cl_args field
141 flags & ~0xff flags For most flags; details
142 below
143 parent_tid pidfd See CLONE_PIDFD
144 child_tid child_tid See CLONE_CHILD_SETTID
145 parent_tid parent_tid See CLONE_PARENT_SETTID
146 flags & 0xff exit_signal
147 stack stack
148 --- stack_size
149 tls tls See CLONE_SETTLS
150 --- set_tid See below for details
151 --- set_tid_size
152 --- cgroup See CLONE_INTO_CGROUP
153 The child termination signal
155 When the child process terminates, a signal may be sent to the parent.
156 The termination signal is specified in the low byte of flags (clone())
157 or in cl_args.exit_signal (clone3()). If this signal is specified as
158 anything other than SIGCHLD, then the parent process must specify the
159 __WALL or __WCLONE options when waiting for the child with wait(2). If
160 no signal (i.e., zero) is specified, then the parent process is not
161 signaled when the child terminates.
162 The set_tid array
164 By default, the kernel chooses the next sequential PID for the new
165 process in each of the PID namespaces where it is present. When creat‐
166 ing a process with clone3(), the set_tid array (available since Linux
167 5.5) can be used to select specific PIDs for the process in some or all
168 of the PID namespaces where it is present. If the PID of the newly
169 created process should be set only for the current PID namespace or in
170 the newly created PID namespace (if flags contains CLONE_NEWPID) then
171 the first element in the set_tid array has to be the desired PID and
172 set_tid_size needs to be 1.
173 If the PID of the newly created process should have a certain value in
175 multiple PID namespaces, then the set_tid array can have multiple en‐
176 tries. The first entry defines the PID in the most deeply nested PID
177 namespace and each of the following entries contains the PID in the
178 corresponding ancestor PID namespace. The number of PID namespaces in
179 which a PID should be set is defined by set_tid_size which cannot be
180 larger than the number of currently nested PID namespaces.
181 To create a process with the following PIDs in a PID namespace hierar‐
183 chy:
184 PID NS level Requested PID Notes
186 0 31496 Outermost PID namespace
187 1 42
188 2 7 Innermost PID namespace
189 Set the array to:
191 set_tid[0] = 7;
193 set_tid[1] = 42;
194 set_tid[2] = 31496;
195 set_tid_size = 3;
196 If only the PIDs in the two innermost PID namespaces need to be speci‐
198 fied, set the array to:
199 set_tid[0] = 7;
201 set_tid[1] = 42;
202 set_tid_size = 2;
203 The PID in the PID namespaces outside the two innermost PID namespaces
205 is selected the same way as any other PID is selected.
206 The set_tid feature requires CAP_SYS_ADMIN or (since Linux 5.9)
208 CAP_CHECKPOINT_RESTORE in all owning user namespaces of the target PID
209 namespaces.
210 Callers may only choose a PID greater than 1 in a given PID namespace
212 if an init process (i.e., a process with PID 1) already exists in that
213 namespace. Otherwise the PID entry for this PID namespace must be 1.
214 The flags mask
216 Both clone() and clone3() allow a flags bit mask that modifies their
217 behavior and allows the caller to specify what is shared between the
218 calling process and the child process. This bit mask—the flags argu‐
219 ment of clone() or the cl_args.flags field passed to clone3()—is re‐
220 ferred to as the flags mask in the remainder of this page.
221 The flags mask is specified as a bitwise-OR of zero or more of the con‐
223 stants listed below. Except as noted below, these flags are available
224 (and have the same effect) in both clone() and clone3().
225 CLONE_CHILD_CLEARTID (since Linux 2.5.49)
227 Clear (zero) the child thread ID at the location pointed to by
228 child_tid (clone()) or cl_args.child_tid (clone3()) in child
229 memory when the child exits, and do a wakeup on the futex at
230 that address. The address involved may be changed by the
231 set_tid_address(2) system call. This is used by threading li‐
232 braries.
233 CLONE_CHILD_SETTID (since Linux 2.5.49)
235 Store the child thread ID at the location pointed to by
236 child_tid (clone()) or cl_args.child_tid (clone3()) in the
237 child's memory. The store operation completes before the clone
238 call returns control to user space in the child process. (Note
239 that the store operation may not have completed before the clone
240 call returns in the parent process, which is relevant if the
241 CLONE_VM flag is also employed.)
242 CLONE_CLEAR_SIGHAND (since Linux 5.5)
244 By default, signal dispositions in the child thread are the same
245 as in the parent. If this flag is specified, then all signals
246 that are handled in the parent are reset to their default dispo‐
247 sitions (SIG_DFL) in the child.
248 Specifying this flag together with CLONE_SIGHAND is nonsensical
250 and disallowed.
251 CLONE_DETACHED (historical)
253 For a while (during the Linux 2.5 development series) there was
254 a CLONE_DETACHED flag, which caused the parent not to receive a
255 signal when the child terminated. Ultimately, the effect of
256 this flag was subsumed under the CLONE_THREAD flag and by the
257 time Linux 2.6.0 was released, this flag had no effect. Start‐
258 ing in Linux 2.6.2, the need to give this flag together with
259 CLONE_THREAD disappeared.
260 This flag is still defined, but it is usually ignored when call‐
262 ing clone(). However, see the description of CLONE_PIDFD for
263 some exceptions.
264 CLONE_FILES (since Linux 2.0)
266 If CLONE_FILES is set, the calling process and the child process
267 share the same file descriptor table. Any file descriptor cre‐
268 ated by the calling process or by the child process is also
269 valid in the other process. Similarly, if one of the processes
270 closes a file descriptor, or changes its associated flags (using
271 the fcntl(2) F_SETFD operation), the other process is also af‐
272 fected. If a process sharing a file descriptor table calls ex‐
273 ecve(2), its file descriptor table is duplicated (unshared).
274 If CLONE_FILES is not set, the child process inherits a copy of
276 all file descriptors opened in the calling process at the time
277 of the clone call. Subsequent operations that open or close
278 file descriptors, or change file descriptor flags, performed by
279 either the calling process or the child process do not affect
280 the other process. Note, however, that the duplicated file de‐
281 scriptors in the child refer to the same open file descriptions
282 as the corresponding file descriptors in the calling process,
283 and thus share file offsets and file status flags (see open(2)).
284 CLONE_FS (since Linux 2.0)
286 If CLONE_FS is set, the caller and the child process share the
287 same filesystem information. This includes the root of the
288 filesystem, the current working directory, and the umask. Any
289 call to chroot(2), chdir(2), or umask(2) performed by the call‐
290 ing process or the child process also affects the other process.
291 If CLONE_FS is not set, the child process works on a copy of the
293 filesystem information of the calling process at the time of the
294 clone call. Calls to chroot(2), chdir(2), or umask(2) performed
295 later by one of the processes do not affect the other process.
296 CLONE_INTO_CGROUP (since Linux 5.7)
298 By default, a child process is placed in the same version 2
299 cgroup as its parent. The CLONE_INTO_CGROUP flag allows the
300 child process to be created in a different version 2 cgroup.
301 (Note that CLONE_INTO_CGROUP has effect only for version 2
302 cgroups.)
303 In order to place the child process in a different cgroup, the
305 caller specifies CLONE_INTO_CGROUP in cl_args.flags and passes a
306 file descriptor that refers to a version 2 cgroup in the
307 cl_args.cgroup field. (This file descriptor can be obtained by
308 opening a cgroup v2 directory using either the O_RDONLY or the
309 O_PATH flag.) Note that all of the usual restrictions (de‐
310 scribed in cgroups(7)) on placing a process into a version 2
311 cgroup apply.
312 Among the possible use cases for CLONE_INTO_CGROUP are the fol‐
314 lowing:
315 * Spawning a process into a cgroup different from the parent's
317 cgroup makes it possible for a service manager to directly
318 spawn new services into dedicated cgroups. This eliminates
319 the accounting jitter that would be caused if the child
320 process was first created in the same cgroup as the parent
321 and then moved into the target cgroup. Furthermore, spawning
322 the child process directly into a target cgroup is signifi‐
323 cantly cheaper than moving the child process into the target
324 cgroup after it has been created.
325 * The CLONE_INTO_CGROUP flag also allows the creation of frozen
327 child processes by spawning them into a frozen cgroup. (See
328 cgroups(7) for a description of the freezer controller.)
329 * For threaded applications (or even thread implementations
331 which make use of cgroups to limit individual threads), it is
332 possible to establish a fixed cgroup layout before spawning
333 each thread directly into its target cgroup.
334 CLONE_IO (since Linux 2.6.25)
336 If CLONE_IO is set, then the new process shares an I/O context
337 with the calling process. If this flag is not set, then (as
338 with fork(2)) the new process has its own I/O context.
339 The I/O context is the I/O scope of the disk scheduler (i.e.,
341 what the I/O scheduler uses to model scheduling of a process's
342 I/O). If processes share the same I/O context, they are treated
343 as one by the I/O scheduler. As a consequence, they get to
344 share disk time. For some I/O schedulers, if two processes
345 share an I/O context, they will be allowed to interleave their
346 disk access. If several threads are doing I/O on behalf of the
347 same process (aio_read(3), for instance), they should employ
348 CLONE_IO to get better I/O performance.
349 If the kernel is not configured with the CONFIG_BLOCK option,
351 this flag is a no-op.
352 CLONE_NEWCGROUP (since Linux 4.6)
354 Create the process in a new cgroup namespace. If this flag is
355 not set, then (as with fork(2)) the process is created in the
356 same cgroup namespaces as the calling process.
357 For further information on cgroup namespaces, see cgroup_name‐
359 spaces(7).
360 Only a privileged process (CAP_SYS_ADMIN) can employ CLONE_NEWC‐
362 GROUP.
363 CLONE_NEWIPC (since Linux 2.6.19)
365 If CLONE_NEWIPC is set, then create the process in a new IPC
366 namespace. If this flag is not set, then (as with fork(2)), the
367 process is created in the same IPC namespace as the calling
368 process.
369 For further information on IPC namespaces, see ipc_name‐
371 spaces(7).
372 Only a privileged process (CAP_SYS_ADMIN) can employ
374 CLONE_NEWIPC. This flag can't be specified in conjunction with
375 CLONE_SYSVSEM.
376 CLONE_NEWNET (since Linux 2.6.24)
378 (The implementation of this flag was completed only by about
379 kernel version 2.6.29.)
380 If CLONE_NEWNET is set, then create the process in a new network
382 namespace. If this flag is not set, then (as with fork(2)) the
383 process is created in the same network namespace as the calling
384 process.
385 For further information on network namespaces, see network_name‐
387 spaces(7).
388 Only a privileged process (CAP_SYS_ADMIN) can employ
390 CLONE_NEWNET.
391 CLONE_NEWNS (since Linux 2.4.19)
393 If CLONE_NEWNS is set, the cloned child is started in a new
394 mount namespace, initialized with a copy of the namespace of the
395 parent. If CLONE_NEWNS is not set, the child lives in the same
396 mount namespace as the parent.
397 For further information on mount namespaces, see namespaces(7)
399 and mount_namespaces(7).
400 Only a privileged process (CAP_SYS_ADMIN) can employ
402 CLONE_NEWNS. It is not permitted to specify both CLONE_NEWNS
403 and CLONE_FS in the same clone call.
404 CLONE_NEWPID (since Linux 2.6.24)
406 If CLONE_NEWPID is set, then create the process in a new PID
407 namespace. If this flag is not set, then (as with fork(2)) the
408 process is created in the same PID namespace as the calling
409 process.
410 For further information on PID namespaces, see namespaces(7) and
412 pid_namespaces(7).
413 Only a privileged process (CAP_SYS_ADMIN) can employ CLONE_NEW‐
415 PID. This flag can't be specified in conjunction with
416 CLONE_THREAD or CLONE_PARENT.
417 CLONE_NEWUSER
419 (This flag first became meaningful for clone() in Linux 2.6.23,
420 the current clone() semantics were merged in Linux 3.5, and the
421 final pieces to make the user namespaces completely usable were
422 merged in Linux 3.8.)
423 If CLONE_NEWUSER is set, then create the process in a new user
425 namespace. If this flag is not set, then (as with fork(2)) the
426 process is created in the same user namespace as the calling
427 process.
428 For further information on user namespaces, see namespaces(7)
430 and user_namespaces(7).
431 Before Linux 3.8, use of CLONE_NEWUSER required that the caller
433 have three capabilities: CAP_SYS_ADMIN, CAP_SETUID, and CAP_SET‐
434 GID. Starting with Linux 3.8, no privileges are needed to cre‐
435 ate a user namespace.
436 This flag can't be specified in conjunction with CLONE_THREAD or
438 CLONE_PARENT. For security reasons, CLONE_NEWUSER cannot be
439 specified in conjunction with CLONE_FS.
440 CLONE_NEWUTS (since Linux 2.6.19)
442 If CLONE_NEWUTS is set, then create the process in a new UTS
443 namespace, whose identifiers are initialized by duplicating the
444 identifiers from the UTS namespace of the calling process. If
445 this flag is not set, then (as with fork(2)) the process is cre‐
446 ated in the same UTS namespace as the calling process.
447 For further information on UTS namespaces, see uts_name‐
449 spaces(7).
450 Only a privileged process (CAP_SYS_ADMIN) can employ
452 CLONE_NEWUTS.
453 CLONE_PARENT (since Linux 2.3.12)
455 If CLONE_PARENT is set, then the parent of the new child (as re‐
456 turned by getppid(2)) will be the same as that of the calling
457 process.
458 If CLONE_PARENT is not set, then (as with fork(2)) the child's
460 parent is the calling process.
461 Note that it is the parent process, as returned by getppid(2),
463 which is signaled when the child terminates, so that if
464 CLONE_PARENT is set, then the parent of the calling process,
465 rather than the calling process itself, is signaled.
466 The CLONE_PARENT flag can't be used in clone calls by the global
468 init process (PID 1 in the initial PID namespace) and init pro‐
469 cesses in other PID namespaces. This restriction prevents the
470 creation of multi-rooted process trees as well as the creation
471 of unreapable zombies in the initial PID namespace.
472 CLONE_PARENT_SETTID (since Linux 2.5.49)
474 Store the child thread ID at the location pointed to by par‐
475 ent_tid (clone()) or cl_args.parent_tid (clone3()) in the par‐
476 ent's memory. (In Linux 2.5.32-2.5.48 there was a flag
477 CLONE_SETTID that did this.) The store operation completes be‐
478 fore the clone call returns control to user space.
479 CLONE_PID (Linux 2.0 to 2.5.15)
481 If CLONE_PID is set, the child process is created with the same
482 process ID as the calling process. This is good for hacking the
483 system, but otherwise of not much use. From Linux 2.3.21 on‐
484 ward, this flag could be specified only by the system boot
485 process (PID 0). The flag disappeared completely from the ker‐
486 nel sources in Linux 2.5.16. Subsequently, the kernel silently
487 ignored this bit if it was specified in the flags mask. Much
488 later, the same bit was recycled for use as the CLONE_PIDFD
489 flag.
490 CLONE_PIDFD (since Linux 5.2)
492 If this flag is specified, a PID file descriptor referring to
493 the child process is allocated and placed at a specified loca‐
494 tion in the parent's memory. The close-on-exec flag is set on
495 this new file descriptor. PID file descriptors can be used for
496 the purposes described in pidfd_open(2).
497 * When using clone3(), the PID file descriptor is placed at the
499 location pointed to by cl_args.pidfd.
500 * When using clone(), the PID file descriptor is placed at the
502 location pointed to by parent_tid. Since the parent_tid ar‐
503 gument is used to return the PID file descriptor, CLONE_PIDFD
504 cannot be used with CLONE_PARENT_SETTID when calling clone().
505 It is currently not possible to use this flag together with
507 CLONE_THREAD. This means that the process identified by the PID
508 file descriptor will always be a thread group leader.
509 If the obsolete CLONE_DETACHED flag is specified alongside
511 CLONE_PIDFD when calling clone(), an error is returned. An er‐
512 ror also results if CLONE_DETACHED is specified when calling
513 clone3(). This error behavior ensures that the bit correspond‐
514 ing to CLONE_DETACHED can be reused for further PID file de‐
515 scriptor features in the future.
516 CLONE_PTRACE (since Linux 2.2)
518 If CLONE_PTRACE is specified, and the calling process is being
519 traced, then trace the child also (see ptrace(2)).
520 CLONE_SETTLS (since Linux 2.5.32)
522 The TLS (Thread Local Storage) descriptor is set to tls.
523 The interpretation of tls and the resulting effect is architec‐
525 ture dependent. On x86, tls is interpreted as a struct
526 user_desc * (see set_thread_area(2)). On x86-64 it is the new
527 value to be set for the %fs base register (see the ARCH_SET_FS
528 argument to arch_prctl(2)). On architectures with a dedicated
529 TLS register, it is the new value of that register.
530 Use of this flag requires detailed knowledge and generally it
532 should not be used except in libraries implementing threading.
533 CLONE_SIGHAND (since Linux 2.0)
535 If CLONE_SIGHAND is set, the calling process and the child
536 process share the same table of signal handlers. If the calling
537 process or child process calls sigaction(2) to change the behav‐
538 ior associated with a signal, the behavior is changed in the
539 other process as well. However, the calling process and child
540 processes still have distinct signal masks and sets of pending
541 signals. So, one of them may block or unblock signals using
542 sigprocmask(2) without affecting the other process.
543 If CLONE_SIGHAND is not set, the child process inherits a copy
545 of the signal handlers of the calling process at the time of the
546 clone call. Calls to sigaction(2) performed later by one of the
547 processes have no effect on the other process.
548 Since Linux 2.6.0, the flags mask must also include CLONE_VM if
550 CLONE_SIGHAND is specified.
551 CLONE_STOPPED (since Linux 2.6.0)
553 If CLONE_STOPPED is set, then the child is initially stopped (as
554 though it was sent a SIGSTOP signal), and must be resumed by
555 sending it a SIGCONT signal.
556 This flag was deprecated from Linux 2.6.25 onward, and was re‐
558 moved altogether in Linux 2.6.38. Since then, the kernel
559 silently ignores it without error. Starting with Linux 4.6, the
560 same bit was reused for the CLONE_NEWCGROUP flag.
561 CLONE_SYSVSEM (since Linux 2.5.10)
563 If CLONE_SYSVSEM is set, then the child and the calling process
564 share a single list of System V semaphore adjustment (semadj)
565 values (see semop(2)). In this case, the shared list accumu‐
566 lates semadj values across all processes sharing the list, and
567 semaphore adjustments are performed only when the last process
568 that is sharing the list terminates (or ceases sharing the list
569 using unshare(2)). If this flag is not set, then the child has
570 a separate semadj list that is initially empty.
571 CLONE_THREAD (since Linux 2.4.0)
573 If CLONE_THREAD is set, the child is placed in the same thread
574 group as the calling process. To make the remainder of the dis‐
575 cussion of CLONE_THREAD more readable, the term "thread" is used
576 to refer to the processes within a thread group.
577 Thread groups were a feature added in Linux 2.4 to support the
579 POSIX threads notion of a set of threads that share a single
580 PID. Internally, this shared PID is the so-called thread group
581 identifier (TGID) for the thread group. Since Linux 2.4, calls
582 to getpid(2) return the TGID of the caller.
583 The threads within a group can be distinguished by their (sys‐
585 tem-wide) unique thread IDs (TID). A new thread's TID is avail‐
586 able as the function result returned to the caller, and a thread
587 can obtain its own TID using gettid(2).
588 When a clone call is made without specifying CLONE_THREAD, then
590 the resulting thread is placed in a new thread group whose TGID
591 is the same as the thread's TID. This thread is the leader of
592 the new thread group.
593 A new thread created with CLONE_THREAD has the same parent
595 process as the process that made the clone call (i.e., like
596 CLONE_PARENT), so that calls to getppid(2) return the same value
597 for all of the threads in a thread group. When a CLONE_THREAD
598 thread terminates, the thread that created it is not sent a
599 SIGCHLD (or other termination) signal; nor can the status of
600 such a thread be obtained using wait(2). (The thread is said to
601 be detached.)
602 After all of the threads in a thread group terminate the parent
604 process of the thread group is sent a SIGCHLD (or other termina‐
605 tion) signal.
606 If any of the threads in a thread group performs an execve(2),
608 then all threads other than the thread group leader are termi‐
609 nated, and the new program is executed in the thread group
610 leader.
611 If one of the threads in a thread group creates a child using
613 fork(2), then any thread in the group can wait(2) for that
614 child.
615 Since Linux 2.5.35, the flags mask must also include CLONE_SIG‐
617 HAND if CLONE_THREAD is specified (and note that, since Linux
618 2.6.0, CLONE_SIGHAND also requires CLONE_VM to be included).
619 Signal dispositions and actions are process-wide: if an unhan‐
621 dled signal is delivered to a thread, then it will affect (ter‐
622 minate, stop, continue, be ignored in) all members of the thread
623 group.
624 Each thread has its own signal mask, as set by sigprocmask(2).
626 A signal may be process-directed or thread-directed. A process-
628 directed signal is targeted at a thread group (i.e., a TGID),
629 and is delivered to an arbitrarily selected thread from among
630 those that are not blocking the signal. A signal may be
631 process-directed because it was generated by the kernel for rea‐
632 sons other than a hardware exception, or because it was sent us‐
633 ing kill(2) or sigqueue(3). A thread-directed signal is tar‐
634 geted at (i.e., delivered to) a specific thread. A signal may
635 be thread directed because it was sent using tgkill(2) or
636 pthread_sigqueue(3), or because the thread executed a machine
637 language instruction that triggered a hardware exception (e.g.,
638 invalid memory access triggering SIGSEGV or a floating-point ex‐
639 ception triggering SIGFPE).
640 A call to sigpending(2) returns a signal set that is the union
642 of the pending process-directed signals and the signals that are
643 pending for the calling thread.
644 If a process-directed signal is delivered to a thread group, and
646 the thread group has installed a handler for the signal, then
647 the handler is invoked in exactly one, arbitrarily selected mem‐
648 ber of the thread group that has not blocked the signal. If
649 multiple threads in a group are waiting to accept the same sig‐
650 nal using sigwaitinfo(2), the kernel will arbitrarily select one
651 of these threads to receive the signal.
652 CLONE_UNTRACED (since Linux 2.5.46)
654 If CLONE_UNTRACED is specified, then a tracing process cannot
655 force CLONE_PTRACE on this child process.
656 CLONE_VFORK (since Linux 2.2)
658 If CLONE_VFORK is set, the execution of the calling process is
659 suspended until the child releases its virtual memory resources
660 via a call to execve(2) or _exit(2) (as with vfork(2)).
661 If CLONE_VFORK is not set, then both the calling process and the
663 child are schedulable after the call, and an application should
664 not rely on execution occurring in any particular order.
665 CLONE_VM (since Linux 2.0)
667 If CLONE_VM is set, the calling process and the child process
668 run in the same memory space. In particular, memory writes per‐
669 formed by the calling process or by the child process are also
670 visible in the other process. Moreover, any memory mapping or
671 unmapping performed with mmap(2) or munmap(2) by the child or
672 calling process also affects the other process.
673 If CLONE_VM is not set, the child process runs in a separate
675 copy of the memory space of the calling process at the time of
676 the clone call. Memory writes or file mappings/unmappings per‐
677 formed by one of the processes do not affect the other, as with
678 fork(2).
679 If the CLONE_VM flag is specified and the CLONE_VFORK flag is
681 not specified, then any alternate signal stack that was estab‐
682 lished by sigaltstack(2) is cleared in the child process.
683
685 On success, the thread ID of the child process is returned in the
686 caller's thread of execution. On failure, -1 is returned in the
687 caller's context, no child process is created, and errno is set to in‐
688 dicate the error.
689
691 EAGAIN Too many processes are already running; see fork(2).
692 EBUSY (clone3() only)
694 CLONE_INTO_CGROUP was specified in cl_args.flags, but the file
695 descriptor specified in cl_args.cgroup refers to a version 2
696 cgroup in which a domain controller is enabled.
697 EEXIST (clone3() only)
699 One (or more) of the PIDs specified in set_tid already exists in
700 the corresponding PID namespace.
701 EINVAL Both CLONE_SIGHAND and CLONE_CLEAR_SIGHAND were specified in the
703 flags mask.
704 EINVAL CLONE_SIGHAND was specified in the flags mask, but CLONE_VM was
706 not. (Since Linux 2.6.0.)
707 EINVAL CLONE_THREAD was specified in the flags mask, but CLONE_SIGHAND
709 was not. (Since Linux 2.5.35.)
710 EINVAL CLONE_THREAD was specified in the flags mask, but the current
712 process previously called unshare(2) with the CLONE_NEWPID flag
713 or used setns(2) to reassociate itself with a PID namespace.
714 EINVAL Both CLONE_FS and CLONE_NEWNS were specified in the flags mask.
716 EINVAL (since Linux 3.9)
718 Both CLONE_NEWUSER and CLONE_FS were specified in the flags
719 mask.
720 EINVAL Both CLONE_NEWIPC and CLONE_SYSVSEM were specified in the flags
722 mask.
723 EINVAL One (or both) of CLONE_NEWPID or CLONE_NEWUSER and one (or both)
725 of CLONE_THREAD or CLONE_PARENT were specified in the flags
726 mask.
727 EINVAL (since Linux 2.6.32)
729 CLONE_PARENT was specified, and the caller is an init process.
730 EINVAL Returned by the glibc clone() wrapper function when fn or stack
732 is specified as NULL.
733 EINVAL CLONE_NEWIPC was specified in the flags mask, but the kernel was
735 not configured with the CONFIG_SYSVIPC and CONFIG_IPC_NS op‐
736 tions.
737 EINVAL CLONE_NEWNET was specified in the flags mask, but the kernel was
739 not configured with the CONFIG_NET_NS option.
740 EINVAL CLONE_NEWPID was specified in the flags mask, but the kernel was
742 not configured with the CONFIG_PID_NS option.
743 EINVAL CLONE_NEWUSER was specified in the flags mask, but the kernel
745 was not configured with the CONFIG_USER_NS option.
746 EINVAL CLONE_NEWUTS was specified in the flags mask, but the kernel was
748 not configured with the CONFIG_UTS_NS option.
749 EINVAL stack is not aligned to a suitable boundary for this architec‐
751 ture. For example, on aarch64, stack must be a multiple of 16.
752 EINVAL (clone3() only)
754 CLONE_DETACHED was specified in the flags mask.
755 EINVAL (clone() only)
757 CLONE_PIDFD was specified together with CLONE_DETACHED in the
758 flags mask.
759 EINVAL CLONE_PIDFD was specified together with CLONE_THREAD in the
761 flags mask.
762 EINVAL (clone() only)
764 CLONE_PIDFD was specified together with CLONE_PARENT_SETTID in
765 the flags mask.
766 EINVAL (clone3() only)
768 set_tid_size is greater than the number of nested PID name‐
769 spaces.
770 EINVAL (clone3() only)
772 One of the PIDs specified in set_tid was an invalid.
773 EINVAL (AArch64 only, Linux 4.6 and earlier)
775 stack was not aligned to a 128-bit boundary.
776 ENOMEM Cannot allocate sufficient memory to allocate a task structure
778 for the child, or to copy those parts of the caller's context
779 that need to be copied.
780 ENOSPC (since Linux 3.7)
782 CLONE_NEWPID was specified in the flags mask, but the limit on
783 the nesting depth of PID namespaces would have been exceeded;
784 see pid_namespaces(7).
785 ENOSPC (since Linux 4.9; beforehand EUSERS)
787 CLONE_NEWUSER was specified in the flags mask, and the call
788 would cause the limit on the number of nested user namespaces to
789 be exceeded. See user_namespaces(7).
790 From Linux 3.11 to Linux 4.8, the error diagnosed in this case
792 was EUSERS.
793 ENOSPC (since Linux 4.9)
795 One of the values in the flags mask specified the creation of a
796 new user namespace, but doing so would have caused the limit de‐
797 fined by the corresponding file in /proc/sys/user to be ex‐
798 ceeded. For further details, see namespaces(7).
799 EOPNOTSUPP (clone3() only)
801 CLONE_INTO_CGROUP was specified in cl_args.flags, but the file
802 descriptor specified in cl_args.cgroup refers to a version 2
803 cgroup that is in the domain invalid state.
804 EPERM CLONE_NEWCGROUP, CLONE_NEWIPC, CLONE_NEWNET, CLONE_NEWNS,
806 CLONE_NEWPID, or CLONE_NEWUTS was specified by an unprivileged
807 process (process without CAP_SYS_ADMIN).
808 EPERM CLONE_PID was specified by a process other than process 0.
810 (This error occurs only on Linux 2.5.15 and earlier.)
811 EPERM CLONE_NEWUSER was specified in the flags mask, but either the
813 effective user ID or the effective group ID of the caller does
814 not have a mapping in the parent namespace (see user_name‐
815 spaces(7)).
816 EPERM (since Linux 3.9)
818 CLONE_NEWUSER was specified in the flags mask and the caller is
819 in a chroot environment (i.e., the caller's root directory does
820 not match the root directory of the mount namespace in which it
821 resides).
822 EPERM (clone3() only)
824 set_tid_size was greater than zero, and the caller lacks the
825 CAP_SYS_ADMIN capability in one or more of the user namespaces
826 that own the corresponding PID namespaces.
827 ERESTARTNOINTR (since Linux 2.6.17)
829 System call was interrupted by a signal and will be restarted.
830 (This can be seen only during a trace.)
831 EUSERS (Linux 3.11 to Linux 4.8)
833 CLONE_NEWUSER was specified in the flags mask, and the limit on
834 the number of nested user namespaces would be exceeded. See the
835 discussion of the ENOSPC error above.
836
838 The clone3() system call first appeared in Linux 5.3.
839
841 These system calls are Linux-specific and should not be used in pro‐
842 grams intended to be portable.
843
845 One use of these systems calls is to implement threads: multiple flows
846 of control in a program that run concurrently in a shared address
847 space.
848 Note that the glibc clone() wrapper function makes some changes in the
850 memory pointed to by stack (changes required to set the stack up cor‐
851 rectly for the child) before invoking the clone() system call. So, in
852 cases where clone() is used to recursively create children, do not use
853 the buffer employed for the parent's stack as the stack of the child.
854 The kcmp(2) system call can be used to test whether two processes share
856 various resources such as a file descriptor table, System V semaphore
857 undo operations, or a virtual address space.
858 Handlers registered using pthread_atfork(3) are not executed during a
860 clone call.
861 In the Linux 2.4.x series, CLONE_THREAD generally does not make the
863 parent of the new thread the same as the parent of the calling process.
864 However, for kernel versions 2.4.7 to 2.4.18 the CLONE_THREAD flag im‐
865 plied the CLONE_PARENT flag (as in Linux 2.6.0 and later).
866 On i386, clone() should not be called through vsyscall, but directly
868 through int $0x80.
869 C library/kernel differences
871 The raw clone() system call corresponds more closely to fork(2) in that
872 execution in the child continues from the point of the call. As such,
873 the fn and arg arguments of the clone() wrapper function are omitted.
874 In contrast to the glibc wrapper, the raw clone() system call accepts
876 NULL as a stack argument (and clone3() likewise allows cl_args.stack to
877 be NULL). In this case, the child uses a duplicate of the parent's
878 stack. (Copy-on-write semantics ensure that the child gets separate
879 copies of stack pages when either process modifies the stack.) In this
880 case, for correct operation, the CLONE_VM option should not be speci‐
881 fied. (If the child shares the parent's memory because of the use of
882 the CLONE_VM flag, then no copy-on-write duplication occurs and chaos
883 is likely to result.)
884 The order of the arguments also differs in the raw system call, and
886 there are variations in the arguments across architectures, as detailed
887 in the following paragraphs.
888 The raw system call interface on x86-64 and some other architectures
890 (including sh, tile, and alpha) is:
891 long clone(unsigned long flags, void *stack,
893 int *parent_tid, int *child_tid,
894 unsigned long tls);
895 On x86-32, and several other common architectures (including score,
897 ARM, ARM 64, PA-RISC, arc, Power PC, xtensa, and MIPS), the order of
898 the last two arguments is reversed:
899 long clone(unsigned long flags, void *stack,
901 int *parent_tid, unsigned long tls,
902 int *child_tid);
903 On the cris and s390 architectures, the order of the first two argu‐
905 ments is reversed:
906 long clone(void *stack, unsigned long flags,
908 int *parent_tid, int *child_tid,
909 unsigned long tls);
910 On the microblaze architecture, an additional argument is supplied:
912 long clone(unsigned long flags, void *stack,
914 int stack_size, /* Size of stack */
915 int *parent_tid, int *child_tid,
916 unsigned long tls);
917 blackfin, m68k, and sparc
919 The argument-passing conventions on blackfin, m68k, and sparc are dif‐
920 ferent from the descriptions above. For details, see the kernel (and
921 glibc) source.
922 ia64
924 On ia64, a different interface is used:
925 int __clone2(int (*fn)(void *),
927 void *stack_base, size_t stack_size,
928 int flags, void *arg, ...
929 /* pid_t *parent_tid, struct user_desc *tls,
930 pid_t *child_tid */ );
931 The prototype shown above is for the glibc wrapper function; for the
933 system call itself, the prototype can be described as follows (it is
934 identical to the clone() prototype on microblaze):
935 long clone2(unsigned long flags, void *stack_base,
937 int stack_size, /* Size of stack */
938 int *parent_tid, int *child_tid,
939 unsigned long tls);
940 __clone2() operates in the same way as clone(), except that stack_base
942 points to the lowest address of the child's stack area, and stack_size
943 specifies the size of the stack pointed to by stack_base.
944 Linux 2.4 and earlier
946 In Linux 2.4 and earlier, clone() does not take arguments parent_tid,
947 tls, and child_tid.
948
950 GNU C library versions 2.3.4 up to and including 2.24 contained a wrap‐
951 per function for getpid(2) that performed caching of PIDs. This
952 caching relied on support in the glibc wrapper for clone(), but limita‐
953 tions in the implementation meant that the cache was not up to date in
954 some circumstances. In particular, if a signal was delivered to the
955 child immediately after the clone() call, then a call to getpid(2) in a
956 handler for the signal could return the PID of the calling process
957 ("the parent"), if the clone wrapper had not yet had a chance to update
958 the PID cache in the child. (This discussion ignores the case where
959 the child was created using CLONE_THREAD, when getpid(2) should return
960 the same value in the child and in the process that called clone(),
961 since the caller and the child are in the same thread group. The
962 stale-cache problem also does not occur if the flags argument includes
963 CLONE_VM.) To get the truth, it was sometimes necessary to use code
964 such as the following:
965 #include <syscall.h>
967 pid_t mypid;
969 mypid = syscall(SYS_getpid);
971 Because of the stale-cache problem, as well as other problems noted in
973 getpid(2), the PID caching feature was removed in glibc 2.25.
974
976 The following program demonstrates the use of clone() to create a child
977 process that executes in a separate UTS namespace. The child changes
978 the hostname in its UTS namespace. Both parent and child then display
979 the system hostname, making it possible to see that the hostname dif‐
980 fers in the UTS namespaces of the parent and child. For an example of
981 the use of this program, see setns(2).
982 Within the sample program, we allocate the memory that is to be used
984 for the child's stack using mmap(2) rather than malloc(3) for the fol‐
985 lowing reasons:
986 * mmap(2) allocates a block of memory that starts on a page boundary
988 and is a multiple of the page size. This is useful if we want to
989 establish a guard page (a page with protection PROT_NONE) at the end
990 of the stack using mprotect(2).
991 * We can specify the MAP_STACK flag to request a mapping that is suit‐
993 able for a stack. For the moment, this flag is a no-op on Linux,
994 but it exists and has effect on some other systems, so we should in‐
995 clude it for portability.
996 Program source
998 #define _GNU_SOURCE
999 #include <sys/wait.h>
1000 #include <sys/utsname.h>
1001 #include <sched.h>
1002 #include <string.h>
1003 #include <stdint.h>
1004 #include <stdio.h>
1005 #include <stdlib.h>
1006 #include <unistd.h>
1007 #include <sys/mman.h>
1008 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \
1010 } while (0)
1011 static int /* Start function for cloned child */
1013 childFunc(void *arg)
1014 {
1015 struct utsname uts;
1016 /* Change hostname in UTS namespace of child. */
1018 if (sethostname(arg, strlen(arg)) == -1)
1020 errExit("sethostname");
1021 /* Retrieve and display hostname. */
1023 if (uname(&uts) == -1)
1025 errExit("uname");
1026 printf("uts.nodename in child: %s\n", uts.nodename);
1027 /* Keep the namespace open for a while, by sleeping.
1029 This allows some experimentation--for example, another
1030 process might join the namespace. */
1031 sleep(200);
1033 return 0; /* Child terminates now */
1035 }
1036 #define STACK_SIZE (1024 * 1024) /* Stack size for cloned child */
1038 int
1040 main(int argc, char *argv[])
1041 {
1042 char *stack; /* Start of stack buffer */
1043 char *stackTop; /* End of stack buffer */
1044 pid_t pid;
1045 struct utsname uts;
1046 if (argc < 2) {
1048 fprintf(stderr, "Usage: %s <child-hostname>\n", argv[0]);
1049 exit(EXIT_SUCCESS);
1050 }
1051 /* Allocate memory to be used for the stack of the child. */
1053 stack = mmap(NULL, STACK_SIZE, PROT_READ | PROT_WRITE,
1055 MAP_PRIVATE | MAP_ANONYMOUS | MAP_STACK, -1, 0);
1056 if (stack == MAP_FAILED)
1057 errExit("mmap");
1058 stackTop = stack + STACK_SIZE; /* Assume stack grows downward */
1060 /* Create child that has its own UTS namespace;
1062 child commences execution in childFunc(). */
1063 pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]);
1065 if (pid == -1)
1066 errExit("clone");
1067 printf("clone() returned %jd\n", (intmax_t) pid);
1068 /* Parent falls through to here */
1070 sleep(1); /* Give child time to change its hostname */
1072 /* Display hostname in parent's UTS namespace. This will be
1074 different from hostname in child's UTS namespace. */
1075 if (uname(&uts) == -1)
1077 errExit("uname");
1078 printf("uts.nodename in parent: %s\n", uts.nodename);
1079 if (waitpid(pid, NULL, 0) == -1) /* Wait for child */
1081 errExit("waitpid");
1082 printf("child has terminated\n");
1083 exit(EXIT_SUCCESS);
1085 }
1086
1088 fork(2), futex(2), getpid(2), gettid(2), kcmp(2), mmap(2),
1089 pidfd_open(2), set_thread_area(2), set_tid_address(2), setns(2),
1090 tkill(2), unshare(2), wait(2), capabilities(7), namespaces(7),
1091 pthreads(7)
1092
1094 This page is part of release 5.12 of the Linux man-pages project. A
1095 description of the project, information about reporting bugs, and the
1096 latest version of this page, can be found at
1097 https://www.kernel.org/doc/man-pages/.
1098Linux 2021-03-22 CLONE(2)