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