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