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