man2/clone.2

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