Debian Codegraph @

upstream/debian-unstable/man2/clone.2

raw
1 '\" t
2 .\" Copyright 1992, Drew Eckhardt <[email protected]>
3 .\" Copyright 2001-2019, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: GPL-1.0-or-later
7 .\"
8 .TH clone 2 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 clone, __clone2, clone3 \- create a child process
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 /* Prototype for the glibc wrapper function */
17 .P
18 .B #define _GNU_SOURCE
19 .B #include <sched.h>
20 .P
21 .BI "int clone(typeof(int (void *_Nullable)) *" fn ,
22 .BI " void *" stack ,
23 .BI " int " flags ,
24 .BI " void *_Nullable " arg ", ..."
25 .BI " \f[R]/*\f[] pid_t *_Nullable " parent_tid ,
26 .BI " void *_Nullable " tls ,
27 .BI " pid_t *_Nullable " child_tid " \f[R]*/\f[] );"
28 .P
29 /* For the prototype of the raw clone() system call, see VERSIONS. */
30 .P
31 .BR "#include <linux/sched.h>" " /* Definition of " "struct clone_args" " */"
32 .BR "#include <sched.h>" " /* Definition of " CLONE_* " constants */"
33 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
34 .B #include <unistd.h>
35 .P
36 .BI "long syscall(SYS_clone3, struct clone_args *" cl_args ", size_t " size );
37 .fi
38 .P
39 .IR Note :
40 glibc provides no wrapper for
41 .BR clone3 (),
42 necessitating the use of
43 .BR syscall (2).
44 .SH DESCRIPTION
45 These system calls
46 create a new ("child") process, in a manner similar to
47 .BR fork (2).
48 .P
49 By contrast with
50 .BR fork (2),
51 these system calls provide more precise control over what pieces of execution
52 context are shared between the calling process and the child process.
53 For example, using these system calls, the caller can control whether
54 or not the two processes share the virtual address space,
55 the table of file descriptors, and the table of signal handlers.
56 These system calls also allow the new child process to be placed
57 in separate
58 .BR namespaces (7).
59 .P
60 Note that in this manual
61 page, "calling process" normally corresponds to "parent process".
62 But see the descriptions of
63 .B CLONE_PARENT
64 and
65 .B CLONE_THREAD
66 below.
67 .P
68 This page describes the following interfaces:
69 .IP \[bu] 3
70 The glibc
71 .BR clone ()
72 wrapper function and the underlying system call on which it is based.
73 The main text describes the wrapper function;
74 the differences for the raw system call
75 are described toward the end of this page.
76 .IP \[bu]
77 The newer
78 .BR clone3 ()
79 system call.
80 .P
81 In the remainder of this page, the terminology "the clone call" is used
82 when noting details that apply to all of these interfaces.
83 .\"
84 .SS The clone() wrapper function
85 When the child process is created with the
86 .BR clone ()
87 wrapper function,
88 it commences execution by calling the function pointed to by the argument
89 .IR fn .
90 (This differs from
91 .BR fork (2),
92 where execution continues in the child from the point
93 of the
94 .BR fork (2)
95 call.)
96 The
97 .I arg
98 argument is passed as the argument of the function
99 .IR fn .
100 .P
101 When the
102 .IR fn ( arg )
103 function returns, the child process terminates.
104 The integer returned by
105 .I fn
106 is the exit status for the child process.
107 The child process may also terminate explicitly by calling
108 .BR exit (2)
109 or after receiving a fatal signal.
110 .P
111 The
112 .I stack
113 argument specifies the location of the stack used by the child process.
114 Since the child and calling process may share memory,
115 it is not possible for the child process to execute in the
116 same stack as the calling process.
117 The calling process must therefore
118 set up memory space for the child stack and pass a pointer to this
119 space to
120 .BR clone ().
121 Stacks grow downward on all processors that run Linux
122 (except the HP PA processors), so
123 .I stack
124 usually points to the topmost address of the memory space set up for
125 the child stack.
126 Note that
127 .BR clone ()
128 does not provide a means whereby the caller can inform the kernel of the
129 size of the stack area.
130 .P
131 The remaining arguments to
132 .BR clone ()
133 are discussed below.
134 .\"
135 .SS clone3()
136 The
137 .BR clone3 ()
138 system call provides a superset of the functionality of the older
139 .BR clone ()
140 interface.
141 It also provides a number of API improvements, including:
142 space for additional flags bits;
143 cleaner separation in the use of various arguments;
144 and the ability to specify the size of the child's stack area.
145 .P
146 As with
147 .BR fork (2),
148 .BR clone3 ()
149 returns in both the parent and the child.
150 It returns 0 in the child process and returns the PID of the child
151 in the parent.
152 .P
153 The
154 .I cl_args
155 argument of
156 .BR clone3 ()
157 is a structure of the following form:
158 .P
159 .in +4n
160 .EX
161 struct clone_args {
162 u64 flags; /* Flags bit mask */
163 u64 pidfd; /* Where to store PID file descriptor
164 (\f[I]int *\f[]) */
165 u64 child_tid; /* Where to store child TID,
166 in child\[aq]s memory (\f[I]pid_t *\f[]) */
167 u64 parent_tid; /* Where to store child TID,
168 in parent\[aq]s memory (\f[I]pid_t *\f[]) */
169 u64 exit_signal; /* Signal to deliver to parent on
170 child termination */
171 u64 stack; /* Pointer to lowest byte of stack */
172 u64 stack_size; /* Size of stack */
173 u64 tls; /* Location of new TLS */
174 u64 set_tid; /* Pointer to a \f[I]pid_t\f[] array
175 (since Linux 5.5) */
176 u64 set_tid_size; /* Number of elements in \f[I]set_tid\f[]
177 (since Linux 5.5) */
178 u64 cgroup; /* File descriptor for target cgroup
179 of child (since Linux 5.7) */
180 };
181 .EE
182 .in
183 .P
184 The
185 .I size
186 argument that is supplied to
187 .BR clone3 ()
188 should be initialized to the size of this structure.
189 (The existence of the
190 .I size
191 argument permits future extensions to the
192 .I clone_args
193 structure.)
194 .P
195 The stack for the child process is specified via
196 .IR cl_args.stack ,
197 which points to the lowest byte of the stack area,
198 and
199 .IR cl_args.stack_size ,
200 which specifies the size of the stack in bytes.
201 In the case where the
202 .B CLONE_VM
203 flag (see below) is specified, a stack must be explicitly allocated
204 and specified.
205 Otherwise, these two fields can be specified as NULL and 0,
206 which causes the child to use the same stack area as the parent
207 (in the child's own virtual address space).
208 .P
209 The remaining fields in the
210 .I cl_args
211 argument are discussed below.
212 .\"
213 .SS Equivalence between clone() and clone3() arguments
214 Unlike the older
215 .BR clone ()
216 interface, where arguments are passed individually, in the newer
217 .BR clone3 ()
218 interface the arguments are packaged into the
219 .I clone_args
220 structure shown above.
221 This structure allows for a superset of the information passed via the
222 .BR clone ()
223 arguments.
224 .P
225 The following table shows the equivalence between the arguments of
226 .BR clone ()
227 and the fields in the
228 .I clone_args
229 argument supplied to
230 .BR clone3 ():
231 .RS 4
232 .TS
233 lb lb lb
234 l l l
235 li li l.
236 clone() clone3() Notes
237 \f[I]cl_args\f[] field
238 flags & \[ti]0xff flags T{
239 For most flags;
240 details below
241 T}
242 parent_tid pidfd See CLONE_PIDFD
243 child_tid child_tid See CLONE_CHILD_SETTID
244 parent_tid parent_tid See CLONE_PARENT_SETTID
245 flags & 0xff exit_signal
246 stack stack
247 \f[R]---\f[] stack_size
248 tls tls See CLONE_SETTLS
249 \f[R]---\f[] set_tid See below for details
250 \f[R]---\f[] set_tid_size
251 \f[R]---\f[] cgroup See CLONE_INTO_CGROUP
252 .TE
253 .RE
254 .\"
255 .SS The child termination signal
256 When the child process terminates, a signal may be sent to the parent.
257 The termination signal is specified in the low byte of
258 .I flags
259 .RB ( clone ())
260 or in
261 .I cl_args.exit_signal
262 .RB ( clone3 ()).
263 If this signal is specified as anything other than
264 .BR SIGCHLD ,
265 then the parent process must specify the
266 .B __WALL
267 or
268 .B __WCLONE
269 options when waiting for the child with
270 .BR wait (2).
271 If no signal (i.e., zero) is specified, then the parent process is not signaled
272 when the child terminates.
273 .\"
274 .SS The set_tid array
275 By default, the kernel chooses the next sequential PID for the new
276 process in each of the PID namespaces where it is present.
277 When creating a process with
278 .BR clone3 (),
279 the
280 .I set_tid
281 array (available since Linux 5.5)
282 can be used to select specific PIDs for the process in some
283 or all of the PID namespaces where it is present.
284 If the PID of the newly created process should be set only for the current
285 PID namespace or in the newly created PID namespace (if
286 .I flags
287 contains
288 .BR CLONE_NEWPID )
289 then the first element in the
290 .I set_tid
291 array has to be the desired PID and
292 .I set_tid_size
293 needs to be 1.
294 .P
295 If the PID of the newly created process should have a certain value in
296 multiple PID namespaces, then the
297 .I set_tid
298 array can have multiple entries.
299 The first entry defines the PID in the most
300 deeply nested PID namespace and each of the following entries contains
301 the PID in the
302 corresponding ancestor PID namespace.
303 The number of PID namespaces in which a PID
304 should be set is defined by
305 .I set_tid_size
306 which cannot be larger than the number of currently nested PID namespaces.
307 .P
308 To create a process with the following PIDs in a PID namespace hierarchy:
309 .RS 4
310 .TS
311 lb lb lb
312 l l l.
313 PID NS level Requested PID Notes
314 0 31496 Outermost PID namespace
315 1 42
316 2 7 Innermost PID namespace
317 .TE
318 .RE
319 .P
320 Set the array to:
321 .P
322 .in +4n
323 .EX
324 set_tid[0] = 7;
325 set_tid[1] = 42;
326 set_tid[2] = 31496;
327 set_tid_size = 3;
328 .EE
329 .in
330 .P
331 If only the PIDs in the two innermost PID namespaces
332 need to be specified, set the array to:
333 .P
334 .in +4n
335 .EX
336 set_tid[0] = 7;
337 set_tid[1] = 42;
338 set_tid_size = 2;
339 .EE
340 .in
341 .P
342 The PID in the PID namespaces outside the two innermost PID namespaces
343 is selected the same way as any other PID is selected.
344 .P
345 The
346 .I set_tid
347 feature requires
348 .B CAP_SYS_ADMIN
349 or
350 (since Linux 5.9)
351 .\" commit 124ea650d3072b005457faed69909221c2905a1f
352 .\" commit 1caef81da05a84a40dbf02110e967ce6d1135ff6
353 .B CAP_CHECKPOINT_RESTORE
354 in all owning user namespaces of the target PID namespaces.
355 .P
356 Callers may only choose a PID greater than 1 in a given PID namespace
357 if an
358 .B init
359 process (i.e., a process with PID 1) already exists in that namespace.
360 Otherwise the PID
361 entry for this PID namespace must be 1.
362 .\"
363 .SS The flags mask
364 Both
365 .BR clone ()
366 and
367 .BR clone3 ()
368 allow a flags bit mask that modifies their behavior
369 and allows the caller to specify what is shared between the calling process
370 and the child process.
371 This bit mask\[em]the
372 .I flags
373 argument of
374 .BR clone ()
375 or the
376 .I cl_args.flags
377 field passed to
378 .BR clone3 ()\[em]is
379 referred to as the
380 .I flags
381 mask in the remainder of this page.
382 .P
383 The
384 .I flags
385 mask is specified as a bitwise OR of zero or more of
386 the constants listed below.
387 Except as noted below, these flags are available
388 (and have the same effect) in both
389 .BR clone ()
390 and
391 .BR clone3 ().
392 .TP
393 .BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)"
394 Clear (zero) the child thread ID at the location pointed to by
395 .I child_tid
396 .RB ( clone ())
397 or
398 .I cl_args.child_tid
399 .RB ( clone3 ())
400 in child memory when the child exits, and do a wakeup on the futex
401 at that address.
402 The address involved may be changed by the
403 .BR set_tid_address (2)
404 system call.
405 This is used by threading libraries.
406 .TP
407 .BR CLONE_CHILD_SETTID " (since Linux 2.5.49)"
408 Store the child thread ID at the location pointed to by
409 .I child_tid
410 .RB ( clone ())
411 or
412 .I cl_args.child_tid
413 .RB ( clone3 ())
414 in the child's memory.
415 The store operation completes before the clone call
416 returns control to user space in the child process.
417 (Note that the store operation may not have completed before the clone call
418 returns in the parent process, which is relevant if the
419 .B CLONE_VM
420 flag is also employed.)
421 .TP
422 .BR CLONE_CLEAR_SIGHAND " (since Linux 5.5)"
423 .\" commit b612e5df4587c934bd056bf05f4a1deca4de4f75
424 By default, signal dispositions in the child thread are the same as
425 in the parent.
426 If this flag is specified,
427 then all signals that are handled in the parent
428 (and not set to
429 .BR SIG_IGN )
430 are reset to their default dispositions
431 .RB ( SIG_DFL )
432 in the child.
433 .IP
434 Specifying this flag together with
435 .B CLONE_SIGHAND
436 is nonsensical and disallowed.
437 .TP
438 .BR CLONE_DETACHED " (historical)"
439 For a while (during the Linux 2.5 development series)
440 .\" added in Linux 2.5.32; removed in Linux 2.6.0-test4
441 there was a
442 .B CLONE_DETACHED
443 flag,
444 which caused the parent not to receive a signal when the child terminated.
445 Ultimately, the effect of this flag was subsumed under the
446 .B CLONE_THREAD
447 flag and by the time Linux 2.6.0 was released, this flag had no effect.
448 Since Linux 2.6.2,
449 the need to give this flag together with
450 .B CLONE_THREAD
451 disappeared.
452 .IP
453 This flag is still defined, but it is usually ignored when calling
454 .BR clone ().
455 However, see the description of
456 .B CLONE_PIDFD
457 for some exceptions.
458 .TP
459 .BR CLONE_FILES " (since Linux 2.0)"
460 If
461 .B CLONE_FILES
462 is set, the calling process and the child process share the same file
463 descriptor table.
464 Any file descriptor created by the calling process or by the child
465 process is also valid in the other process.
466 Similarly, if one of the processes closes a file descriptor,
467 or changes its associated flags (using the
468 .BR fcntl (2)
469 .B F_SETFD
470 operation), the other process is also affected.
471 If a process sharing a file descriptor table calls
472 .BR execve (2),
473 its file descriptor table is duplicated (unshared).
474 .IP
475 If
476 .B CLONE_FILES
477 is not set, the child process inherits a copy of all file descriptors
478 opened in the calling process at the time of the clone call.
479 Subsequent operations that open or close file descriptors,
480 or change file descriptor flags,
481 performed by either the calling
482 process or the child process do not affect the other process.
483 Note, however,
484 that the duplicated file descriptors in the child refer to the same
485 open file descriptions as the corresponding file descriptors
486 in the calling process,
487 and thus share file offsets and file status flags (see
488 .BR open (2)).
489 .TP
490 .BR CLONE_FS " (since Linux 2.0)"
491 If
492 .B CLONE_FS
493 is set, the caller and the child process share the same filesystem
494 information.
495 This includes the root of the filesystem, the current
496 working directory, and the umask.
497 Any call to
498 .BR chroot (2),
499 .BR chdir (2),
500 or
501 .BR umask (2)
502 performed by the calling process or the child process also affects the
503 other process.
504 .IP
505 If
506 .B CLONE_FS
507 is not set, the child process works on a copy of the filesystem
508 information of the calling process at the time of the clone call.
509 Calls to
510 .BR chroot (2),
511 .BR chdir (2),
512 or
513 .BR umask (2)
514 performed later by one of the processes do not affect the other process.
515 .TP
516 .BR CLONE_INTO_CGROUP " (since Linux 5.7)"
517 .\" commit ef2c41cf38a7559bbf91af42d5b6a4429db8fc68
518 By default, a child process is placed in the same version 2
519 cgroup as its parent.
520 The
521 .B CLONE_INTO_CGROUP
522 flag allows the child process to be created in a different version 2 cgroup.
523 (Note that
524 .B CLONE_INTO_CGROUP
525 has effect only for version 2 cgroups.)
526 .IP
527 In order to place the child process in a different cgroup,
528 the caller specifies
529 .B CLONE_INTO_CGROUP
530 in
531 .I cl_args.flags
532 and passes a file descriptor that refers to a version 2 cgroup in the
533 .I cl_args.cgroup
534 field.
535 (This file descriptor can be obtained by opening a cgroup v2 directory
536 using either the
537 .B O_RDONLY
538 or the
539 .B O_PATH
540 flag.)
541 Note that all of the usual restrictions (described in
542 .BR cgroups (7))
543 on placing a process into a version 2 cgroup apply.
544 .IP
545 Among the possible use cases for
546 .B CLONE_INTO_CGROUP
547 are the following:
548 .RS
549 .IP \[bu] 3
550 Spawning a process into a cgroup different from the parent's cgroup
551 makes it possible for a service manager to directly spawn new
552 services into dedicated cgroups.
553 This eliminates the accounting
554 jitter that would be caused if the child process was first created in the
555 same cgroup as the parent and then
556 moved into the target cgroup.
557 Furthermore, spawning the child process directly into a target cgroup
558 is significantly cheaper than moving the child process into
559 the target cgroup after it has been created.
560 .IP \[bu]
561 The
562 .B CLONE_INTO_CGROUP
563 flag also allows the creation of
564 frozen child processes by spawning them into a frozen cgroup.
565 (See
566 .BR cgroups (7)
567 for a description of the freezer controller.)
568 .IP \[bu]
569 For threaded applications (or even thread implementations which
570 make use of cgroups to limit individual threads), it is possible to
571 establish a fixed cgroup layout before spawning each thread
572 directly into its target cgroup.
573 .RE
574 .TP
575 .BR CLONE_IO " (since Linux 2.6.25)"
576 If
577 .B CLONE_IO
578 is set, then the new process shares an I/O context with
579 the calling process.
580 If this flag is not set, then (as with
581 .BR fork (2))
582 the new process has its own I/O context.
583 .IP
584 .\" The following based on text from Jens Axboe
585 The I/O context is the I/O scope of the disk scheduler (i.e.,
586 what the I/O scheduler uses to model scheduling of a process's I/O).
587 If processes share the same I/O context,
588 they are treated as one by the I/O scheduler.
589 As a consequence, they get to share disk time.
590 For some I/O schedulers,
591 .\" the anticipatory and CFQ scheduler
592 if two processes share an I/O context,
593 they will be allowed to interleave their disk access.
594 If several threads are doing I/O on behalf of the same process
595 .RB ( aio_read (3),
596 for instance), they should employ
597 .B CLONE_IO
598 to get better I/O performance.
599 .\" with CFQ and AS.
600 .IP
601 If the kernel is not configured with the
602 .B CONFIG_BLOCK
603 option, this flag is a no-op.
604 .TP
605 .BR CLONE_NEWCGROUP " (since Linux 4.6)"
606 Create the process in a new cgroup namespace.
607 If this flag is not set, then (as with
608 .BR fork (2))
609 the process is created in the same cgroup namespaces as the calling process.
610 .IP
611 For further information on cgroup namespaces, see
612 .BR cgroup_namespaces (7).
613 .IP
614 Only a privileged process
615 .RB ( CAP_SYS_ADMIN )
616 can employ
617 .BR CLONE_NEWCGROUP .
618 .\"
619 .TP
620 .BR CLONE_NEWIPC " (since Linux 2.6.19)"
621 If
622 .B CLONE_NEWIPC
623 is set, then create the process in a new IPC namespace.
624 If this flag is not set, then (as with
625 .BR fork (2)),
626 the process is created in the same IPC namespace as
627 the calling process.
628 .IP
629 For further information on IPC namespaces, see
630 .BR ipc_namespaces (7).
631 .IP
632 Only a privileged process
633 .RB ( CAP_SYS_ADMIN )
634 can employ
635 .BR CLONE_NEWIPC .
636 This flag can't be specified in conjunction with
637 .BR CLONE_SYSVSEM .
638 .TP
639 .BR CLONE_NEWNET " (since Linux 2.6.24)"
640 (The implementation of this flag was completed only
641 by about Linux 2.6.29.)
642 .IP
643 If
644 .B CLONE_NEWNET
645 is set, then create the process in a new network namespace.
646 If this flag is not set, then (as with
647 .BR fork (2))
648 the process is created in the same network namespace as
649 the calling process.
650 .IP
651 For further information on network namespaces, see
652 .BR network_namespaces (7).
653 .IP
654 Only a privileged process
655 .RB ( CAP_SYS_ADMIN )
656 can employ
657 .BR CLONE_NEWNET .
658 .TP
659 .BR CLONE_NEWNS " (since Linux 2.4.19)"
660 If
661 .B CLONE_NEWNS
662 is set, the cloned child is started in a new mount namespace,
663 initialized with a copy of the namespace of the parent.
664 If
665 .B CLONE_NEWNS
666 is not set, the child lives in the same mount
667 namespace as the parent.
668 .IP
669 For further information on mount namespaces, see
670 .BR namespaces (7)
671 and
672 .BR mount_namespaces (7).
673 .IP
674 Only a privileged process
675 .RB ( CAP_SYS_ADMIN )
676 can employ
677 .BR CLONE_NEWNS .
678 It is not permitted to specify both
679 .B CLONE_NEWNS
680 and
681 .B CLONE_FS
682 .\" See https://lwn.net/Articles/543273/
683 in the same clone call.
684 .TP
685 .BR CLONE_NEWPID " (since Linux 2.6.24)"
686 .\" This explanation draws a lot of details from
687 .\" http://lwn.net/Articles/259217/
688 .\" Authors: Pavel Emelyanov <[email protected]>
689 .\" and Kir Kolyshkin <[email protected]>
690 .\"
691 .\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264
692 .\" Author: Pavel Emelyanov <[email protected]>
693 If
694 .B CLONE_NEWPID
695 is set, then create the process in a new PID namespace.
696 If this flag is not set, then (as with
697 .BR fork (2))
698 the process is created in the same PID namespace as
699 the calling process.
700 .IP
701 For further information on PID namespaces, see
702 .BR namespaces (7)
703 and
704 .BR pid_namespaces (7).
705 .IP
706 Only a privileged process
707 .RB ( CAP_SYS_ADMIN )
708 can employ
709 .BR CLONE_NEWPID .
710 This flag can't be specified in conjunction with
711 .BR CLONE_THREAD .
712 .TP
713 .B CLONE_NEWUSER
714 (This flag first became meaningful for
715 .BR clone ()
716 in Linux 2.6.23,
717 the current
718 .BR clone ()
719 semantics were merged in Linux 3.5,
720 and the final pieces to make the user namespaces completely usable were
721 merged in Linux 3.8.)
722 .IP
723 If
724 .B CLONE_NEWUSER
725 is set, then create the process in a new user namespace.
726 If this flag is not set, then (as with
727 .BR fork (2))
728 the process is created in the same user namespace as the calling process.
729 .IP
730 For further information on user namespaces, see
731 .BR namespaces (7)
732 and
733 .BR user_namespaces (7).
734 .IP
735 Before Linux 3.8, use of
736 .B CLONE_NEWUSER
737 required that the caller have three capabilities:
738 .BR CAP_SYS_ADMIN ,
739 .BR CAP_SETUID ,
740 and
741 .BR CAP_SETGID .
742 .\" Before Linux 2.6.29, it appears that only CAP_SYS_ADMIN was needed
743 Starting with Linux 3.8,
744 no privileges are needed to create a user namespace.
745 .IP
746 This flag can't be specified in conjunction with
747 .B CLONE_THREAD
748 or
749 .BR CLONE_PARENT .
750 For security reasons,
751 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
752 .\" https://lwn.net/Articles/543273/
753 .\" The fix actually went into Linux 3.9 and into Linux 3.8.3.
754 .\" However, user namespaces were, for practical purposes,
755 .\" unusable in earlier Linux 3.8.x because of the various filesystems
756 .\" that didn't support userns.
757 .B CLONE_NEWUSER
758 cannot be specified in conjunction with
759 .BR CLONE_FS .
760 .TP
761 .BR CLONE_NEWUTS " (since Linux 2.6.19)"
762 If
763 .B CLONE_NEWUTS
764 is set, then create the process in a new UTS namespace,
765 whose identifiers are initialized by duplicating the identifiers
766 from the UTS namespace of the calling process.
767 If this flag is not set, then (as with
768 .BR fork (2))
769 the process is created in the same UTS namespace as
770 the calling process.
771 .IP
772 For further information on UTS namespaces, see
773 .BR uts_namespaces (7).
774 .IP
775 Only a privileged process
776 .RB ( CAP_SYS_ADMIN )
777 can employ
778 .BR CLONE_NEWUTS .
779 .TP
780 .BR CLONE_PARENT " (since Linux 2.3.12)"
781 If
782 .B CLONE_PARENT
783 is set, then the parent of the new child (as returned by
784 .BR getppid (2))
785 will be the same as that of the calling process.
786 .IP
787 If
788 .B CLONE_PARENT
789 is not set, then (as with
790 .BR fork (2))
791 the child's parent is the calling process.
792 .IP
793 Note that it is the parent process, as returned by
794 .BR getppid (2),
795 which is signaled when the child terminates, so that
796 if
797 .B CLONE_PARENT
798 is set, then the parent of the calling process, rather than the
799 calling process itself, is signaled.
800 .IP
801 The
802 .B CLONE_PARENT
803 flag can't be used in clone calls by the
804 global init process (PID 1 in the initial PID namespace)
805 and init processes in other PID namespaces.
806 This restriction prevents the creation of multi-rooted process trees
807 as well as the creation of unreapable zombies in the initial PID namespace.
808 .TP
809 .BR CLONE_PARENT_SETTID " (since Linux 2.5.49)"
810 Store the child thread ID at the location pointed to by
811 .I parent_tid
812 .RB ( clone ())
813 or
814 .I cl_args.parent_tid
815 .RB ( clone3 ())
816 in the parent's memory.
817 (In Linux 2.5.32-2.5.48 there was a flag
818 .B CLONE_SETTID
819 that did this.)
820 The store operation completes before the clone call
821 returns control to user space.
822 .TP
823 .BR CLONE_PID " (Linux 2.0 to Linux 2.5.15)"
824 If
825 .B CLONE_PID
826 is set, the child process is created with the same process ID as
827 the calling process.
828 This is good for hacking the system, but otherwise
829 of not much use.
830 From Linux 2.3.21 onward, this flag could be
831 specified only by the system boot process (PID 0).
832 The flag disappeared completely from the kernel sources in Linux 2.5.16.
833 Subsequently, the kernel silently ignored this bit if it was specified in the
834 .I flags
835 mask.
836 Much later, the same bit was recycled for use as the
837 .B CLONE_PIDFD
838 flag.
839 .TP
840 .BR CLONE_PIDFD " (since Linux 5.2)"
841 .\" commit b3e5838252665ee4cfa76b82bdf1198dca81e5be
842 If this flag is specified,
843 a PID file descriptor referring to the child process is allocated
844 and placed at a specified location in the parent's memory.
845 The close-on-exec flag is set on this new file descriptor.
846 PID file descriptors can be used for the purposes described in
847 .BR pidfd_open (2).
848 .RS
849 .IP \[bu] 3
850 When using
851 .BR clone3 (),
852 the PID file descriptor is placed at the location pointed to by
853 .IR cl_args.pidfd .
854 .IP \[bu]
855 When using
856 .BR clone (),
857 the PID file descriptor is placed at the location pointed to by
858 .IR parent_tid .
859 Since the
860 .I parent_tid
861 argument is used to return the PID file descriptor,
862 .B CLONE_PIDFD
863 cannot be used with
864 .B CLONE_PARENT_SETTID
865 when calling
866 .BR clone ().
867 .RE
868 .IP
869 If
870 .B CLONE_PIDFD
871 is specified together with
872 .BR CLONE_THREAD ,
873 the obtained PID file descriptor refers to a specific thread,
874 as opposed to a thread-group leader if
875 .B CLONE_THREAD
876 is not specified.
877 This feature is available since Linux 6.9.
878 .\" commit 83b290c9e3b5d95891f43a4aeadf6071cbff25d3
879 .IP
880 If the obsolete
881 .B CLONE_DETACHED
882 flag is specified alongside
883 .B CLONE_PIDFD
884 when calling
885 .BR clone (),
886 an error is returned.
887 An error also results if
888 .B CLONE_DETACHED
889 is specified when calling
890 .BR clone3 ().
891 This error behavior ensures that the bit corresponding to
892 .B CLONE_DETACHED
893 can be reused for further PID file descriptor features in the future.
894 .TP
895 .BR CLONE_PTRACE " (since Linux 2.2)"
896 If
897 .B CLONE_PTRACE
898 is specified, and the calling process is being traced,
899 then trace the child also (see
900 .BR ptrace (2)).
901 .TP
902 .BR CLONE_SETTLS " (since Linux 2.5.32)"
903 The TLS (Thread Local Storage) descriptor is set to
904 .IR tls .
905 .IP
906 The interpretation of
907 .I tls
908 and the resulting effect is architecture dependent.
909 On x86,
910 .I tls
911 is interpreted as a
912 .I struct user_desc\~*
913 (see
914 .BR set_thread_area (2)).
915 On x86-64 it is the new value to be set for the %fs base register
916 (see the
917 .B ARCH_SET_FS
918 argument to
919 .BR arch_prctl (2)).
920 On architectures with a dedicated TLS register, it is the new value
921 of that register.
922 .IP
923 Use of this flag requires detailed knowledge and generally it
924 should not be used except in libraries implementing threading.
925 .TP
926 .BR CLONE_SIGHAND " (since Linux 2.0)"
927 If
928 .B CLONE_SIGHAND
929 is set, the calling process and the child process share the same table of
930 signal handlers.
931 If the calling process or child process calls
932 .BR sigaction (2)
933 to change the behavior associated with a signal, the behavior is
934 changed in the other process as well.
935 However, the calling process and child
936 processes still have distinct signal masks and sets of pending
937 signals.
938 So, one of them may block or unblock signals using
939 .BR sigprocmask (2)
940 without affecting the other process.
941 .IP
942 If
943 .B CLONE_SIGHAND
944 is not set, the child process inherits a copy of the signal handlers
945 of the calling process at the time of the clone call.
946 Calls to
947 .BR sigaction (2)
948 performed later by one of the processes have no effect on the other
949 process.
950 .IP
951 Since Linux 2.6.0,
952 .\" Precisely: Linux 2.6.0-test6
953 the
954 .I flags
955 mask must also include
956 .B CLONE_VM
957 if
958 .B CLONE_SIGHAND
959 is specified.
960 .TP
961 .BR CLONE_STOPPED " (since Linux 2.6.0)"
962 .\" Precisely: Linux 2.6.0-test2
963 If
964 .B CLONE_STOPPED
965 is set, then the child is initially stopped (as though it was sent a
966 .B SIGSTOP
967 signal), and must be resumed by sending it a
968 .B SIGCONT
969 signal.
970 .IP
971 This flag was
972 .I deprecated
973 from Linux 2.6.25 onward,
974 and was
975 .I removed
976 altogether in Linux 2.6.38.
977 Since then, the kernel silently ignores it without error.
978 .\" glibc 2.8 removed this defn from bits/sched.h
979 Starting with Linux 4.6, the same bit was reused for the
980 .B CLONE_NEWCGROUP
981 flag.
982 .TP
983 .BR CLONE_SYSVSEM " (since Linux 2.5.10)"
984 If
985 .B CLONE_SYSVSEM
986 is set, then the child and the calling process share
987 a single list of System V semaphore adjustment
988 .RI ( semadj )
989 values (see
990 .BR semop (2)).
991 In this case, the shared list accumulates
992 .I semadj
993 values across all processes sharing the list,
994 and semaphore adjustments are performed only when the last process
995 that is sharing the list terminates (or ceases sharing the list using
996 .BR unshare (2)).
997 If this flag is not set, then the child has a separate
998 .I semadj
999 list that is initially empty.
1000 .TP
1001 .BR CLONE_THREAD " (since Linux 2.4.0)"
1002 .\" Precisely: Linux 2.6.0-test8
1003 If
1004 .B CLONE_THREAD
1005 is set, the child is placed in the same thread group as the calling process.
1006 To make the remainder of the discussion of
1007 .B CLONE_THREAD
1008 more readable, the term "thread" is used to refer to the
1009 processes within a thread group.
1010 .IP
1011 Thread groups were a feature added in Linux 2.4 to support the
1012 POSIX threads notion of a set of threads that share a single PID.
1013 Internally, this shared PID is the so-called
1014 thread group identifier (TGID) for the thread group.
1015 Since Linux 2.4, calls to
1016 .BR getpid (2)
1017 return the TGID of the caller.
1018 .IP
1019 The threads within a group can be distinguished by their (system-wide)
1020 unique thread IDs (TID).
1021 A new thread's TID is available as the function result
1022 returned to the caller,
1023 and a thread can obtain
1024 its own TID using
1025 .BR gettid (2).
1026 .IP
1027 When a clone call is made without specifying
1028 .BR CLONE_THREAD ,
1029 then the resulting thread is placed in a new thread group
1030 whose TGID is the same as the thread's TID.
1031 This thread is the
1032 .I leader
1033 of the new thread group.
1034 .IP
1035 A new thread created with
1036 .B CLONE_THREAD
1037 has the same parent process as the process that made the clone call
1038 (i.e., like
1039 .BR CLONE_PARENT ),
1040 so that calls to
1041 .BR getppid (2)
1042 return the same value for all of the threads in a thread group.
1043 When a
1044 .B CLONE_THREAD
1045 thread terminates, the thread that created it is not sent a
1046 .B SIGCHLD
1047 (or other termination) signal;
1048 nor can the status of such a thread be obtained
1049 using
1050 .BR wait (2).
1051 (The thread is said to be
1052 .IR detached .)
1053 .IP
1054 After all of the threads in a thread group terminate
1055 the parent process of the thread group is sent a
1056 .B SIGCHLD
1057 (or other termination) signal.
1058 .IP
1059 If any of the threads in a thread group performs an
1060 .BR execve (2),
1061 then all threads other than the thread group leader are terminated,
1062 and the new program is executed in the thread group leader.
1063 .IP
1064 If one of the threads in a thread group creates a child using
1065 .BR fork (2),
1066 then any thread in the group can
1067 .BR wait (2)
1068 for that child.
1069 .IP
1070 Since Linux 2.5.35, the
1071 .I flags
1072 mask must also include
1073 .B CLONE_SIGHAND
1074 if
1075 .B CLONE_THREAD
1076 is specified
1077 (and note that, since Linux 2.6.0,
1078 .\" Precisely: Linux 2.6.0-test6
1079 .B CLONE_SIGHAND
1080 also requires
1081 .B CLONE_VM
1082 to be included).
1083 .IP
1084 Signal dispositions and actions are process-wide:
1085 if an unhandled signal is delivered to a thread, then
1086 it will affect (terminate, stop, continue, be ignored in)
1087 all members of the thread group.
1088 .IP
1089 Each thread has its own signal mask, as set by
1090 .BR sigprocmask (2).
1091 .IP
1092 A signal may be process-directed or thread-directed.
1093 A process-directed signal is targeted at a thread group (i.e., a TGID),
1094 and is delivered to an arbitrarily selected thread from among those
1095 that are not blocking the signal.
1096 A signal may be process-directed because it was generated by the kernel
1097 for reasons other than a hardware exception, or because it was sent using
1098 .BR kill (2)
1099 or
1100 .BR sigqueue (3).
1101 A thread-directed signal is targeted at (i.e., delivered to)
1102 a specific thread.
1103 A signal may be thread directed because it was sent using
1104 .BR tgkill (2)
1105 or
1106 .BR pthread_sigqueue (3),
1107 or because the thread executed a machine language instruction that triggered
1108 a hardware exception
1109 (e.g., invalid memory access triggering
1110 .B SIGSEGV
1111 or a floating-point exception triggering
1112 .BR SIGFPE ).
1113 .IP
1114 A call to
1115 .BR sigpending (2)
1116 returns a signal set that is the union of the pending process-directed
1117 signals and the signals that are pending for the calling thread.
1118 .IP
1119 If a process-directed signal is delivered to a thread group,
1120 and the thread group has installed a handler for the signal, then
1121 the handler is invoked in exactly one, arbitrarily selected
1122 member of the thread group that has not blocked the signal.
1123 If multiple threads in a group are waiting to accept the same signal using
1124 .BR sigwaitinfo (2),
1125 the kernel will arbitrarily select one of these threads
1126 to receive the signal.
1127 .TP
1128 .BR CLONE_UNTRACED " (since Linux 2.5.46)"
1129 If
1130 .B CLONE_UNTRACED
1131 is specified, then a tracing process cannot force
1132 .B CLONE_PTRACE
1133 on this child process.
1134 .TP
1135 .BR CLONE_VFORK " (since Linux 2.2)"
1136 If
1137 .B CLONE_VFORK
1138 is set, the execution of the calling process is suspended
1139 until the child releases its virtual memory
1140 resources via a call to
1141 .BR execve (2)
1142 or
1143 .BR _exit (2)
1144 (as with
1145 .BR vfork (2)).
1146 .IP
1147 If
1148 .B CLONE_VFORK
1149 is not set, then both the calling process and the child are schedulable
1150 after the call, and an application should not rely on execution occurring
1151 in any particular order.
1152 .TP
1153 .BR CLONE_VM " (since Linux 2.0)"
1154 If
1155 .B CLONE_VM
1156 is set, the calling process and the child process run in the same memory
1157 space.
1158 In particular, memory writes performed by the calling process
1159 or by the child process are also visible in the other process.
1160 Moreover, any memory mapping or unmapping performed with
1161 .BR mmap (2)
1162 or
1163 .BR munmap (2)
1164 by the child or calling process also affects the other process.
1165 .IP
1166 If
1167 .B CLONE_VM
1168 is not set, the child process runs in a separate copy of the memory
1169 space of the calling process at the time of the clone call.
1170 Memory writes or file mappings/unmappings performed by one of the
1171 processes do not affect the other, as with
1172 .BR fork (2).
1173 .IP
1174 If the
1175 .B CLONE_VM
1176 flag is specified and the
1177 .B CLONE_VFORK
1178 flag is not specified,
1179 then any alternate signal stack that was established by
1180 .BR sigaltstack (2)
1181 is cleared in the child process.
1182 .SH RETURN VALUE
1183 .\" gettid(2) returns current->pid;
1184 .\" getpid(2) returns current->tgid;
1185 On success, the thread ID of the child process is returned
1186 in the caller's thread of execution.
1187 On failure, \-1 is returned
1188 in the caller's context, no child process is created, and
1189 .I errno
1190 is set to indicate the error.
1191 .SH ERRORS
1192 .TP
1193 .BR E2BIG " (" clone3 "() only)"
1194 The kernel does not support some functionality requested in this
1195 .BR clone3 ()
1196 call:
1197 The size argument is larger than what the kernel supports,
1198 and there are non-zero values in the struct after the kernel-supported size.
1199 .TP
1200 .BR E2BIG " (" clone3 "() only)"
1201 The size argument is larger than the page size.
1202 .TP
1203 .BR EACCES " (" clone3 "() only)"
1204 .B CLONE_INTO_CGROUP
1205 was specified in
1206 .IR cl_args.flags ,
1207 but the restrictions (described in
1208 .BR cgroups (7))
1209 on placing the child process into the version 2 cgroup referred to by
1210 .I cl_args.cgroup
1211 are not met.
1212 .TP
1213 .B EAGAIN
1214 Too many processes are already running;
1215 see
1216 .BR fork (2).
1217 .TP
1218 .BR EBUSY " (" clone3 "() only)"
1219 .B CLONE_INTO_CGROUP
1220 was specified in
1221 .IR cl_args.flags ,
1222 but the file descriptor specified in
1223 .I cl_args.cgroup
1224 refers to a version 2 cgroup in which a domain controller is enabled.
1225 .TP
1226 .BR EEXIST " (" clone3 "() only)"
1227 One (or more) of the PIDs specified in
1228 .I set_tid
1229 already exists in the corresponding PID namespace.
1230 .TP
1231 .B EINVAL
1232 Both
1233 .B CLONE_SIGHAND
1234 and
1235 .B CLONE_CLEAR_SIGHAND
1236 were specified in the
1237 .I flags
1238 mask.
1239 .TP
1240 .B EINVAL
1241 .B CLONE_SIGHAND
1242 was specified in the
1243 .I flags
1244 mask, but
1245 .B CLONE_VM
1246 was not.
1247 (Since Linux 2.6.0.)
1248 .\" Precisely: Linux 2.6.0-test6
1249 .TP
1250 .B EINVAL
1251 .B CLONE_THREAD
1252 was specified in the
1253 .I flags
1254 mask, but
1255 .B CLONE_SIGHAND
1256 was not.
1257 (Since Linux 2.5.35.)
1258 .\" .TP
1259 .\" .B EINVAL
1260 .\" Precisely one of
1261 .\" .B CLONE_DETACHED
1262 .\" and
1263 .\" .B CLONE_THREAD
1264 .\" was specified.
1265 .\" (Since Linux 2.6.0-test6.)
1266 .TP
1267 .B EINVAL
1268 .B CLONE_THREAD
1269 was specified in the
1270 .I flags
1271 mask, but the current process previously called
1272 .BR unshare (2)
1273 with the
1274 .B CLONE_NEWPID
1275 flag or used
1276 .BR setns (2)
1277 to reassociate itself with a PID namespace.
1278 .TP
1279 .B EINVAL
1280 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
1281 Both
1282 .B CLONE_FS
1283 and
1284 .B CLONE_NEWNS
1285 were specified in the
1286 .I flags
1287 mask.
1288 .TP
1289 .BR EINVAL " (since Linux 3.9)"
1290 Both
1291 .B CLONE_NEWUSER
1292 and
1293 .B CLONE_FS
1294 were specified in the
1295 .I flags
1296 mask.
1297 .TP
1298 .B EINVAL
1299 Both
1300 .B CLONE_NEWIPC
1301 and
1302 .B CLONE_SYSVSEM
1303 were specified in the
1304 .I flags
1305 mask.
1306 .TP
1307 .B EINVAL
1308 .B CLONE_NEWPID
1309 and one (or both) of
1310 .B CLONE_THREAD
1311 or
1312 .B CLONE_PARENT
1313 were specified in the
1314 .I flags
1315 mask.
1316 .TP
1317 .B EINVAL
1318 .B CLONE_NEWUSER
1319 and
1320 .B CLONE_THREAD
1321 were specified in the
1322 .I flags
1323 mask.
1324 .TP
1325 .BR EINVAL " (since Linux 2.6.32)"
1326 .\" commit 123be07b0b399670a7cc3d82fef0cb4f93ef885c
1327 .B CLONE_PARENT
1328 was specified, and the caller is an init process.
1329 .TP
1330 .B EINVAL
1331 Returned by the glibc
1332 .BR clone ()
1333 wrapper function when
1334 .I fn
1335 or
1336 .I stack
1337 is specified as NULL.
1338 .TP
1339 .B EINVAL
1340 .B CLONE_NEWIPC
1341 was specified in the
1342 .I flags
1343 mask,
1344 but the kernel was not configured with the
1345 .B CONFIG_SYSVIPC
1346 and
1347 .B CONFIG_IPC_NS
1348 options.
1349 .TP
1350 .B EINVAL
1351 .B CLONE_NEWNET
1352 was specified in the
1353 .I flags
1354 mask,
1355 but the kernel was not configured with the
1356 .B CONFIG_NET_NS
1357 option.
1358 .TP
1359 .B EINVAL
1360 .B CLONE_NEWPID
1361 was specified in the
1362 .I flags
1363 mask,
1364 but the kernel was not configured with the
1365 .B CONFIG_PID_NS
1366 option.
1367 .TP
1368 .B EINVAL
1369 .B CLONE_NEWUSER
1370 was specified in the
1371 .I flags
1372 mask,
1373 but the kernel was not configured with the
1374 .B CONFIG_USER_NS
1375 option.
1376 .TP
1377 .B EINVAL
1378 .B CLONE_NEWUTS
1379 was specified in the
1380 .I flags
1381 mask,
1382 but the kernel was not configured with the
1383 .B CONFIG_UTS_NS
1384 option.
1385 .TP
1386 .B EINVAL
1387 .I stack
1388 is not aligned to a suitable boundary for this architecture.
1389 For example, on aarch64,
1390 .I stack
1391 must be a multiple of 16.
1392 .TP
1393 .BR EINVAL " (" clone3 "() only)"
1394 .B CLONE_DETACHED
1395 was specified in the
1396 .I flags
1397 mask.
1398 .TP
1399 .BR EINVAL " (" clone "() only)"
1400 .B CLONE_PIDFD
1401 was specified together with
1402 .B CLONE_DETACHED
1403 in the
1404 .I flags
1405 mask.
1406 .TP
1407 .BR EINVAL " (before Linux 6.9)"
1408 .B CLONE_PIDFD
1409 was specified together with
1410 .B CLONE_THREAD
1411 in the
1412 .I flags
1413 mask.
1414 .TP
1415 .BR "EINVAL " "(" clone "() only)"
1416 .B CLONE_PIDFD
1417 was specified together with
1418 .B CLONE_PARENT_SETTID
1419 in the
1420 .I flags
1421 mask.
1422 .TP
1423 .BR EINVAL " (" clone3 "() only)"
1424 .I set_tid_size
1425 is greater than the number of nested PID namespaces.
1426 .TP
1427 .BR EINVAL " (" clone3 "() only)"
1428 One of the PIDs specified in
1429 .I set_tid
1430 was an invalid.
1431 .TP
1432 .BR EINVAL " (" clone3 "() only)"
1433 .\" commit 7f192e3cd316ba58c88dfa26796cf77789dd9872
1434 .B CLONE_THREAD
1435 or
1436 .B CLONE_PARENT
1437 was specified in the
1438 .I flags
1439 mask, but a signal was specified in
1440 .IR exit_signal .
1441 .TP
1442 .BR EINVAL " (AArch64 only, Linux 4.6 and earlier)"
1443 .I stack
1444 was not aligned to a 128-bit boundary.
1445 .TP
1446 .B ENOMEM
1447 Cannot allocate sufficient memory to allocate a task structure for the
1448 child, or to copy those parts of the caller's context that need to be
1449 copied.
1450 .TP
1451 .BR ENOSPC " (since Linux 3.7)"
1452 .\" commit f2302505775fd13ba93f034206f1e2a587017929
1453 .B CLONE_NEWPID
1454 was specified in the
1455 .I flags
1456 mask,
1457 but the limit on the nesting depth of PID namespaces
1458 would have been exceeded;
1459 see
1460 .BR pid_namespaces (7).
1461 .TP
1462 .BR ENOSPC " (since Linux 4.9; beforehand " EUSERS )
1463 .B CLONE_NEWUSER
1464 was specified in the
1465 .I flags
1466 mask, and the call would cause the limit on the number of
1467 nested user namespaces to be exceeded.
1468 See
1469 .BR user_namespaces (7).
1470 .IP
1471 From Linux 3.11 to Linux 4.8, the error diagnosed in this case was
1472 .BR EUSERS .
1473 .TP
1474 .BR ENOSPC " (since Linux 4.9)"
1475 One of the values in the
1476 .I flags
1477 mask specified the creation of a new user namespace,
1478 but doing so would have caused the limit defined by the corresponding file in
1479 .I /proc/sys/user
1480 to be exceeded.
1481 For further details, see
1482 .BR namespaces (7).
1483 .TP
1484 .BR EOPNOTSUPP " (" clone3 "() only)"
1485 .B CLONE_INTO_CGROUP
1486 was specified in
1487 .IR cl_args.flags ,
1488 but the file descriptor specified in
1489 .I cl_args.cgroup
1490 refers to a version 2 cgroup that is in the
1491 .I domain invalid
1492 state.
1493 .TP
1494 .B EPERM
1495 .BR CLONE_NEWCGROUP ,
1496 .BR CLONE_NEWIPC ,
1497 .BR CLONE_NEWNET ,
1498 .BR CLONE_NEWNS ,
1499 .BR CLONE_NEWPID ,
1500 or
1501 .B CLONE_NEWUTS
1502 was specified by an unprivileged process (process without
1503 .BR CAP_SYS_ADMIN ).
1504 .TP
1505 .B EPERM
1506 .B CLONE_PID
1507 was specified by a process other than process 0.
1508 (This error occurs only on Linux 2.5.15 and earlier.)
1509 .TP
1510 .B EPERM
1511 .B CLONE_NEWUSER
1512 was specified in the
1513 .I flags
1514 mask,
1515 but either the effective user ID or the effective group ID of the caller
1516 does not have a mapping in the parent namespace (see
1517 .BR user_namespaces (7)).
1518 .TP
1519 .BR EPERM " (since Linux 3.9)"
1520 .\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d
1521 .B CLONE_NEWUSER
1522 was specified in the
1523 .I flags
1524 mask and the caller is in a chroot environment
1525 .\" FIXME What is the rationale for this restriction?
1526 (i.e., the caller's root directory does not match the root directory
1527 of the mount namespace in which it resides).
1528 .TP
1529 .BR EPERM " (" clone3 "() only)"
1530 .I set_tid_size
1531 was greater than zero, and the caller lacks the
1532 .B CAP_SYS_ADMIN
1533 capability in one or more of the user namespaces that own the
1534 corresponding PID namespaces.
1535 .TP
1536 .BR ERESTARTNOINTR " (since Linux 2.6.17)"
1537 .\" commit 4a2c7a7837da1b91468e50426066d988050e4d56
1538 System call was interrupted by a signal and will be restarted.
1539 (This can be seen only during a trace.)
1540 .TP
1541 .BR EUSERS " (Linux 3.11 to Linux 4.8)"
1542 .B CLONE_NEWUSER
1543 was specified in the
1544 .I flags
1545 mask,
1546 and the limit on the number of nested user namespaces would be exceeded.
1547 See the discussion of the
1548 .B ENOSPC
1549 error above.
1550 .SH VERSIONS
1551 The glibc
1552 .BR clone ()
1553 wrapper function makes some changes
1554 in the memory pointed to by
1555 .I stack
1556 (changes required to set the stack up correctly for the child)
1557 .I before
1558 invoking the
1559 .BR clone ()
1560 system call.
1561 So, in cases where
1562 .BR clone ()
1563 is used to recursively create children,
1564 do not use the buffer employed for the parent's stack
1565 as the stack of the child.
1566 .P
1567 On i386,
1568 .BR clone ()
1569 should not be called through vsyscall, but directly through
1570 .IR "int $0x80" .
1571 .SS C library/kernel differences
1572 The raw
1573 .BR clone ()
1574 system call corresponds more closely to
1575 .BR fork (2)
1576 in that execution in the child continues from the point of the
1577 call.
1578 As such, the
1579 .I fn
1580 and
1581 .I arg
1582 arguments of the
1583 .BR clone ()
1584 wrapper function are omitted.
1585 .P
1586 In contrast to the glibc wrapper, the raw
1587 .BR clone ()
1588 system call accepts NULL as a
1589 .I stack
1590 argument (and
1591 .BR clone3 ()
1592 likewise allows
1593 .I cl_args.stack
1594 to be NULL).
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
1599 .B CLONE_VM
1600 option should not be specified.
1601 (If the child
1602 .I shares
1603 the parent's memory because of the use of the
1604 .B CLONE_VM
1605 flag,
1606 then no copy-on-write duplication occurs and chaos is likely to result.)
1607 .P
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.
1611 .P
1612 The raw system call interface on x86-64 and some other architectures
1613 (including sh, tile, and alpha) is:
1614 .P
1615 .in +4n
1616 .EX
1617 .BI "long clone(unsigned long " flags ", void *" stack ,
1618 .BI " int *" parent_tid ", int *" child_tid ,
1619 .BI " unsigned long " tls );
1620 .EE
1621 .in
1622 .P
1623 On x86-32, and several other common architectures
1624 (including score, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa,
1625 and MIPS),
1626 .\" CONFIG_CLONE_BACKWARDS
1627 the order of the last two arguments is reversed:
1628 .P
1629 .in +4n
1630 .EX
1631 .BI "long clone(unsigned long " flags ", void *" stack ,
1632 .BI " int *" parent_tid ", unsigned long " tls ,
1633 .BI " int *" child_tid );
1634 .EE
1635 .in
1636 .P
1637 On the cris and s390 architectures,
1638 .\" CONFIG_CLONE_BACKWARDS2
1639 the order of the first two arguments is reversed:
1640 .P
1641 .in +4n
1642 .EX
1643 .BI "long clone(void *" stack ", unsigned long " flags ,
1644 .BI " int *" parent_tid ", int *" child_tid ,
1645 .BI " unsigned long " tls );
1646 .EE
1647 .in
1648 .P
1649 On the microblaze architecture,
1650 .\" CONFIG_CLONE_BACKWARDS3
1651 an additional argument is supplied:
1652 .P
1653 .in +4n
1654 .EX
1655 .BI "long clone(unsigned long " flags ", void *" stack ,
1656 .BI " int " stack_size , "\f[R] /* Size of stack */\f[]"
1657 .BI " int *" parent_tid ", int *" child_tid ,
1658 .BI " unsigned long " tls );
1659 .EE
1660 .in
1661 .\"
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.
1669 .SH STANDARDS
1670 Linux.
1671 .SH HISTORY
1672 .TP
1673 .BR clone3 ()
1674 Linux 5.3.
1675 .\" There is no entry for
1676 .\" .BR clone ()
1677 .\" in libc5.
1678 .\" glibc2 provides
1679 .\" .BR clone ()
1680 .\" as described in this manual page.
1681 .SS Linux 2.4 and earlier
1682 In the Linux 2.4.x series,
1683 .B CLONE_THREAD
1684 generally does not make the parent of the new thread the same
1685 as the parent of the calling process.
1686 However, from Linux 2.4.7 to Linux 2.4.18 the
1687 .B CLONE_THREAD
1688 flag implied the
1689 .B CLONE_PARENT
1690 flag (as in Linux 2.6.0 and later).
1691 .P
1692 In Linux 2.4 and earlier,
1693 .BR clone ()
1694 does not take arguments
1695 .IR parent_tid ,
1696 .IR tls ,
1697 and
1698 .IR child_tid .
1699 .SS ia64
1700 On ia64, a different interface is used:
1701 .P
1702 .in +4n
1703 .EX
1704 .BI "int __clone2(typeof(int (void *)) *" fn ,
1705 .BI " void *" stack_base ", size_t " stack_size ,
1706 .BI " int " flags ", void *" "arg" ", ..."
1707 .BI " \f[R]/*\f[] pid_t *" parent_tid ", struct user_desc *" tls ,
1708 .BI " pid_t *" child_tid " \f[R]*/\f[] );"
1709 .EE
1710 .in
1711 .P
1712 The prototype shown above is for the glibc wrapper function;
1713 for the system call itself,
1714 the prototype can be described as follows (it is identical to the
1715 .BR clone ()
1716 prototype on microblaze):
1717 .P
1718 .in +4n
1719 .EX
1720 .BI "long clone2(unsigned long " flags ", void *" stack_base ,
1721 .BI " int " stack_size , "\f[R] /* Size of stack */\f[]"
1722 .BI " int *" parent_tid ", int *" child_tid ,
1723 .BI " unsigned long " tls );
1724 .EE
1725 .in
1726 .P
1727 .BR __clone2 ()
1728 operates in the same way as
1729 .BR clone (),
1730 except that
1731 .I stack_base
1732 points to the lowest address of the child's stack area,
1733 and
1734 .I stack_size
1735 specifies the size of the stack pointed to by
1736 .IR stack_base .
1737 .SH NOTES
1738 One use of these system calls
1739 is to implement threads: multiple flows of control in a program that
1740 run concurrently in a shared address space.
1741 .P
1742 The
1743 .BR kcmp (2)
1744 system call can be used to test whether two processes share various
1745 resources such as a file descriptor table,
1746 System V semaphore undo operations, or a virtual address space.
1747 .P
1748 Handlers registered using
1749 .BR pthread_atfork (3)
1750 are not executed during a clone call.
1751 .SH BUGS
1752 GNU C library versions 2.3.4 up to and including 2.24
1753 contained a wrapper function for
1754 .BR getpid (2)
1755 that performed caching of PIDs.
1756 This caching relied on support in the glibc wrapper for
1757 .BR clone (),
1758 but limitations in the implementation
1759 meant that the cache was not up to date in some circumstances.
1760 In particular,
1761 if a signal was delivered to the child immediately after the
1762 .BR clone ()
1763 call, then a call to
1764 .BR getpid (2)
1765 in a handler for the signal could return the PID
1766 of the calling process ("the parent"),
1767 if the clone wrapper had not yet had a chance to update the PID
1768 cache in the child.
1769 (This discussion ignores the case where the child was created using
1770 .BR CLONE_THREAD ,
1771 when
1772 .BR getpid (2)
1773 .I should
1774 return the same value in the child and in the process that called
1775 .BR clone (),
1776 since the caller and the child are in the same thread group.
1777 The stale-cache problem also does not occur if the
1778 .I flags
1779 argument includes
1780 .BR CLONE_VM .)
1781 To get the truth, it was sometimes necessary to use code such as the following:
1782 .P
1783 .in +4n
1784 .EX
1785 #include <syscall.h>
1786 \&
1787 pid_t mypid;
1788 \&
1789 mypid = syscall(SYS_getpid);
1790 .EE
1791 .in
1792 .\" See also the following bug reports
1793 .\" https://bugzilla.redhat.com/show_bug.cgi?id=417521
1794 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910
1795 .P
1796 Because of the stale-cache problem, as well as other problems noted in
1797 .BR getpid (2),
1798 the PID caching feature was removed in glibc 2.25.
1799 .SH EXAMPLES
1800 The following program demonstrates the use of
1801 .BR clone ()
1802 to create a child process that executes in a separate UTS namespace.
1803 The child changes the hostname in its UTS namespace.
1804 Both parent and child then display the system hostname,
1805 making it possible to see that the hostname
1806 differs in the UTS namespaces of the parent and child.
1807 For an example of the use of this program, see
1808 .BR setns (2).
1809 .P
1810 Within the sample program, we allocate the memory that is to
1811 be used for the child's stack using
1812 .BR mmap (2)
1813 rather than
1814 .BR malloc (3)
1815 for the following reasons:
1816 .IP \[bu] 3
1817 .BR mmap (2)
1818 allocates a block of memory that starts on a page
1819 boundary and is a multiple of the page size.
1820 This is useful if we want to establish a guard page (a page with protection
1821 .BR PROT_NONE )
1822 at the end of the stack using
1823 .BR mprotect (2).
1824 .IP \[bu]
1825 We can specify the
1826 .B MAP_STACK
1827 flag to request a mapping that is suitable for a stack.
1828 For the moment, this flag is a no-op on Linux,
1829 but it exists and has effect on some other systems,
1830 so we should include it for portability.
1831 .SS Program source
1832 .\" SRC BEGIN (clone.c)
1833 .EX
1834 #define _GNU_SOURCE
1835 #include <err.h>
1836 #include <sched.h>
1837 #include <signal.h>
1838 #include <stdint.h>
1839 #include <stdio.h>
1840 #include <stdlib.h>
1841 #include <string.h>
1842 #include <sys/mman.h>
1843 #include <sys/types.h>
1844 #include <sys/utsname.h>
1845 #include <sys/wait.h>
1846 #include <unistd.h>
1847 \&
1848 static int /* Start function for cloned child */
1849 childFunc(void *arg)
1850 {
1851 struct utsname uts;
1852 \&
1853 /* Change hostname in UTS namespace of child. */
1854 \&
1855 if (sethostname(arg, strlen(arg)) == \-1)
1856 err(EXIT_FAILURE, "sethostname");
1857 \&
1858 /* Retrieve and display hostname. */
1859 \&
1860 if (uname(&uts) == \-1)
1861 err(EXIT_FAILURE, "uname");
1862 printf("uts.nodename in child: %s\[rs]n", uts.nodename);
1863 \&
1864 /* Keep the namespace open for a while, by sleeping.
1865 This allows some experimentation\-\-for example, another
1866 process might join the namespace. */
1867 \&
1868 sleep(200);
1869 \&
1870 return 0; /* Child terminates now */
1871 }
1872 \&
1873 #define STACK_SIZE (1024 * 1024) /* Stack size for cloned child */
1874 \&
1875 int
1876 main(int argc, char *argv[])
1877 {
1878 char *stack; /* Start of stack buffer */
1879 char *stackTop; /* End of stack buffer */
1880 pid_t pid;
1881 struct utsname uts;
1882 \&
1883 if (argc < 2) {
1884 fprintf(stderr, "Usage: %s <child\-hostname>\[rs]n", argv[0]);
1885 exit(EXIT_SUCCESS);
1886 }
1887 \&
1888 /* Allocate memory to be used for the stack of the child. */
1889 \&
1890 stack = mmap(NULL, STACK_SIZE, PROT_READ | PROT_WRITE,
1891 MAP_PRIVATE | MAP_ANONYMOUS | MAP_STACK, \-1, 0);
1892 if (stack == MAP_FAILED)
1893 err(EXIT_FAILURE, "mmap");
1894 \&
1895 stackTop = stack + STACK_SIZE; /* Assume stack grows downward */
1896 \&
1897 /* Create child that has its own UTS namespace;
1898 child commences execution in childFunc(). */
1899 \&
1900 pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]);
1901 if (pid == \-1)
1902 err(EXIT_FAILURE, "clone");
1903 if (munmap(stack, STACK_SIZE))
1904 err(EXIT_FAILURE, "munmap");
1905 printf("clone() returned %jd\[rs]n", (intmax_t) pid);
1906 \&
1907 /* Parent falls through to here */
1908 \&
1909 sleep(1); /* Give child time to change its hostname */
1910 \&
1911 /* Display hostname in parent\[aq]s UTS namespace. This will be
1912 different from hostname in child\[aq]s UTS namespace. */
1913 \&
1914 if (uname(&uts) == \-1)
1915 err(EXIT_FAILURE, "uname");
1916 printf("uts.nodename in parent: %s\[rs]n", uts.nodename);
1917 \&
1918 if (waitpid(pid, NULL, 0) == \-1) /* Wait for child */
1919 err(EXIT_FAILURE, "waitpid");
1920 printf("child has terminated\[rs]n");
1921 \&
1922 exit(EXIT_SUCCESS);
1923 }
1924 .EE
1925 .\" SRC END
1926 .SH SEE ALSO
1927 .BR fork (2),
1928 .BR futex (2),
1929 .BR getpid (2),
1930 .BR gettid (2),
1931 .BR kcmp (2),
1932 .BR mmap (2),
1933 .BR pidfd_open (2),
1934 .BR set_thread_area (2),
1935 .BR set_tid_address (2),
1936 .BR setns (2),
1937 .BR tkill (2),
1938 .BR unshare (2),
1939 .BR wait (2),
1940 .BR capabilities (7),
1941 .BR namespaces (7),
1942 .BR pthreads (7)