Debian Codegraph @

upstream/fedora-44/man2/clone.2

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