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
   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 2016-03-15 "Linux" "Linux Programmer's Manual"
  43 .SH NAME
  44 clone, __clone2 \- create a child process
  45 .SH SYNOPSIS
  46 .nf
  47 /* Prototype for the glibc wrapper function */
  48
  49 .B #define _GNU_SOURCE
  50 .B #include <sched.h>
  51
  52 .BI "int clone(int (*" "fn" ")(void *), void *" child_stack ,
  53 .BI "          int " flags ", void *" "arg" ", ... "
  54 .BI "          /* pid_t *" ptid ", struct user_desc *" tls \
  55 ", pid_t *" ctid " */ );"
  56
  57 /* Prototype for the raw system call */
  58
  59 .BI "long clone(unsigned long " flags ", void *" child_stack ,
  60 .BI "          void *" ptid ", void *" ctid ,
  61 .BI "          struct pt_regs *" regs );
  62 .fi
  63 .SH DESCRIPTION
  64 .BR clone ()
  65 creates a new process, in a manner similar to
  66 .BR fork (2).
  67
  68 This page describes both the glibc
  69 .BR clone ()
  70 wrapper function and the underlying system call on which it is based.
  71 The main text describes the wrapper function;
  72 the differences for the raw system call
  73 are described toward the end of this page.
  74
  75 Unlike
  76 .BR fork (2),
  77 .BR clone ()
  78 allows the child process to share parts of its execution context with
  79 the calling process, such as the memory space, the table of file
  80 descriptors, and the table of signal handlers.
  81 (Note that on this manual
  82 page, "calling process" normally corresponds to "parent process".
  83 But see the description of
  84 .B CLONE_PARENT
  85 below.)
  86
  87 One use of
  88 .BR clone ()
  89 is to implement threads: multiple threads of control in a program that
  90 run concurrently in a shared memory space.
  91
  92 When the child process is created with
  93 .BR clone (),
  94 it executes the function
  95 .IR fn ( arg ).
  96 (This differs from
  97 .BR fork (2),
  98 where execution continues in the child from the point
  99 of the
 100 .BR fork (2)
 101 call.)
 102 The
 103 .I fn
 104 argument is a pointer to a function that is called by the child
 105 process at the beginning of its execution.
 106 The
 107 .I arg
 108 argument is passed to the
 109 .I fn
 110 function.
 111
 112 When the
 113 .IR fn ( arg )
 114 function application returns, the child process terminates.
 115 The integer returned by
 116 .I fn
 117 is the exit code for the child process.
 118 The child process may also terminate explicitly by calling
 119 .BR exit (2)
 120 or after receiving a fatal signal.
 121
 122 The
 123 .I child_stack
 124 argument specifies the location of the stack used by the child process.
 125 Since the child and calling process may share memory,
 126 it is not possible for the child process to execute in the
 127 same stack as the calling process.
 128 The calling process must therefore
 129 set up memory space for the child stack and pass a pointer to this
 130 space to
 131 .BR clone ().
 132 Stacks grow downward on all processors that run Linux
 133 (except the HP PA processors), so
 134 .I child_stack
 135 usually points to the topmost address of the memory space set up for
 136 the child stack.
 137
 138 The low byte of
 139 .I flags
 140 contains the number of the
 141 .I "termination signal"
 142 sent to the parent when the child dies.
 143 If this signal is specified as anything other than
 144 .BR SIGCHLD ,
 145 then the parent process must specify the
 146 .B __WALL
 147 or
 148 .B __WCLONE
 149 options when waiting for the child with
 150 .BR wait (2).
 151 If no signal is specified, then the parent process is not signaled
 152 when the child terminates.
 153
 154 .I flags
 155 may also be bitwise-or'ed with zero or more of the following constants,
 156 in order to specify what is shared between the calling process
 157 and the child process:
 158 .TP
 159 .BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)"
 160 Erase the child thread ID at the location
 161 .I ctid
 162 in child memory when the child exits, and do a wakeup on the futex
 163 at that address.
 164 The address involved may be changed by the
 165 .BR set_tid_address (2)
 166 system call.
 167 This is used by threading libraries.
 168 .TP
 169 .BR CLONE_CHILD_SETTID " (since Linux 2.5.49)"
 170 Store the child thread ID at the location
 171 .I ctid
 172 in the child's memory.
 173 .TP
 174 .BR CLONE_FILES " (since Linux 2.0)"
 175 If
 176 .B CLONE_FILES
 177 is set, the calling process and the child process share the same file
 178 descriptor table.
 179 Any file descriptor created by the calling process or by the child
 180 process is also valid in the other process.
 181 Similarly, if one of the processes closes a file descriptor,
 182 or changes its associated flags (using the
 183 .BR fcntl (2)
 184 .B F_SETFD
 185 operation), the other process is also affected.
 186 If a process sharing a file descriptor table calls
 187 .BR execve (2),
 188 its file descriptor table is duplicated (unshared).
 189
 190 If
 191 .B CLONE_FILES
 192 is not set, the child process inherits a copy of all file descriptors
 193 opened in the calling process at the time of
 194 .BR clone ().
 195 (The duplicated file descriptors in the child refer to the
 196 same open file descriptions (see
 197 .BR open (2))
 198 as the corresponding file descriptors in the calling process.)
 199 Subsequent operations that open or close file descriptors,
 200 or change file descriptor flags,
 201 performed by either the calling
 202 process or the child process do not affect the other process.
 203 .TP
 204 .BR CLONE_FS " (since Linux 2.0)"
 205 If
 206 .B CLONE_FS
 207 is set, the caller and the child process share the same filesystem
 208 information.
 209 This includes the root of the filesystem, the current
 210 working directory, and the umask.
 211 Any call to
 212 .BR chroot (2),
 213 .BR chdir (2),
 214 or
 215 .BR umask (2)
 216 performed by the calling process or the child process also affects the
 217 other process.
 218
 219 If
 220 .B CLONE_FS
 221 is not set, the child process works on a copy of the filesystem
 222 information of the calling process at the time of the
 223 .BR clone ()
 224 call.
 225 Calls to
 226 .BR chroot (2),
 227 .BR chdir (2),
 228 .BR umask (2)
 229 performed later by one of the processes do not affect the other process.
 230 .TP
 231 .BR CLONE_IO " (since Linux 2.6.25)"
 232 If
 233 .B CLONE_IO
 234 is set, then the new process shares an I/O context with
 235 the calling process.
 236 If this flag is not set, then (as with
 237 .BR fork (2))
 238 the new process has its own I/O context.
 239
 240 .\" The following based on text from Jens Axboe
 241 The I/O context is the I/O scope of the disk scheduler (i.e,
 242 what the I/O scheduler uses to model scheduling of a process's I/O).
 243 If processes share the same I/O context,
 244 they are treated as one by the I/O scheduler.
 245 As a consequence, they get to share disk time.
 246 For some I/O schedulers,
 247 .\" the anticipatory and CFQ scheduler
 248 if two processes share an I/O context,
 249 they will be allowed to interleave their disk access.
 250 If several threads are doing I/O on behalf of the same process
 251 .RB ( aio_read (3),
 252 for instance), they should employ
 253 .BR CLONE_IO
 254 to get better I/O performance.
 255 .\" with CFQ and AS.
 256
 257 If the kernel is not configured with the
 258 .B CONFIG_BLOCK
 259 option, this flag is a no-op.
 260 .TP
 261 .BR CLONE_NEWCGROUP " (since Linux 4.6)"
 262 Create the process in a new cgroup namespace.
 263 If this flag is not set, then (as with
 264 .BR fork (2))
 265 the process is created in the same cgroup namespaces as the calling process.
 266 This flag is intended for the implementation of containers.
 267
 268 For further information on cgroup namespaces, see
 269 .BR cgroup_namespaces (7).
 270
 271 Only a privileged process
 272 .RB ( CAP_SYS_ADMIN )
 273 can employ
 274 .BR CLONE_NEWCGROUP .
 275 .\"
 276 .TP
 277 .BR CLONE_NEWIPC " (since Linux 2.6.19)"
 278 If
 279 .B CLONE_NEWIPC
 280 is set, then create the process in a new IPC namespace.
 281 If this flag is not set, then (as with
 282 .BR fork (2)),
 283 the process is created in the same IPC namespace as
 284 the calling process.
 285 This flag is intended for the implementation of containers.
 286
 287 An IPC namespace provides an isolated view of System\ V IPC objects (see
 288 .BR svipc (7))
 289 and (since Linux 2.6.30)
 290 .\" commit 7eafd7c74c3f2e67c27621b987b28397110d643f
 291 .\" https://lwn.net/Articles/312232/
 292 POSIX message queues
 293 (see
 294 .BR mq_overview (7)).
 295 The common characteristic of these IPC mechanisms is that IPC
 296 objects are identified by mechanisms other than filesystem
 297 pathnames.
 298
 299 Objects created in an IPC namespace are visible to all other processes
 300 that are members of that namespace,
 301 but are not visible to processes in other IPC namespaces.
 302
 303 When an IPC namespace is destroyed
 304 (i.e., when the last process that is a member of the namespace terminates),
 305 all IPC objects in the namespace are automatically destroyed.
 306
 307 Only a privileged process
 308 .RB ( CAP_SYS_ADMIN )
 309 can employ
 310 .BR CLONE_NEWIPC .
 311 This flag can't be specified in conjunction with
 312 .BR CLONE_SYSVSEM .
 313
 314 For further information on IPC namespaces, see
 315 .BR namespaces (7).
 316 .TP
 317 .BR CLONE_NEWNET " (since Linux 2.6.24)"
 318 (The implementation of this flag was completed only
 319 by about kernel version 2.6.29.)
 320
 321 If
 322 .B CLONE_NEWNET
 323 is set, then create the process in a new network namespace.
 324 If this flag is not set, then (as with
 325 .BR fork (2))
 326 the process is created in the same network namespace as
 327 the calling process.
 328 This flag is intended for the implementation of containers.
 329
 330 A network namespace provides an isolated view of the networking stack
 331 (network device interfaces, IPv4 and IPv6 protocol stacks,
 332 IP routing tables, firewall rules, the
 333 .I /proc/net
 334 and
 335 .I /sys/class/net
 336 directory trees, sockets, etc.).
 337 A physical network device can live in exactly one
 338 network namespace.
 339 A virtual network device ("veth") pair provides a pipe-like abstraction
 340 .\" FIXME . Add pointer to veth(4) page when it is eventually completed
 341 that can be used to create tunnels between network namespaces,
 342 and can be used to create a bridge to a physical network device
 343 in another namespace.
 344
 345 When a network namespace is freed
 346 (i.e., when the last process in the namespace terminates),
 347 its physical network devices are moved back to the
 348 initial network namespace (not to the parent of the process).
 349 For further information on network namespaces, see
 350 .BR namespaces (7).
 351
 352 Only a privileged process
 353 .RB ( CAP_SYS_ADMIN )
 354 can employ
 355 .BR CLONE_NEWNET .
 356 .TP
 357 .BR CLONE_NEWNS " (since Linux 2.4.19)"
 358 If
 359 .B CLONE_NEWNS
 360 is set, the cloned child is started in a new mount namespace,
 361 initialized with a copy of the namespace of the parent.
 362 If
 363 .B CLONE_NEWNS
 364 is not set, the child lives in the same mount
 365 namespace as the parent.
 366
 367 For further information on mount namespaces, see
 368 .BR namespaces (7).
 369
 370 Only a privileged process
 371 .RB ( CAP_SYS_ADMIN )
 372 can employ
 373 .BR CLONE_NEWNS .
 374 It is not permitted to specify both
 375 .B CLONE_NEWNS
 376 and
 377 .B CLONE_FS
 378 .\" See https://lwn.net/Articles/543273/
 379 in the same
 380 .BR clone ()
 381 call.
 382 .TP
 383 .BR CLONE_NEWPID " (since Linux 2.6.24)"
 384 .\" This explanation draws a lot of details from
 385 .\" http://lwn.net/Articles/259217/
 386 .\" Authors: Pavel Emelyanov <xemul@openvz.org>
 387 .\" and Kir Kolyshkin <kir@openvz.org>
 388 .\"
 389 .\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264
 390 .\" Author: Pavel Emelyanov <xemul@openvz.org>
 391 If
 392 .B CLONE_NEWPID
 393 is set, then create the process in a new PID namespace.
 394 If this flag is not set, then (as with
 395 .BR fork (2))
 396 the process is created in the same PID namespace as
 397 the calling process.
 398 This flag is intended for the implementation of containers.
 399
 400 For further information on PID namespaces, see
 401 .BR namespaces (7)
 402 and
 403 .BR pid_namespaces (7)
 404
 405 Only a privileged process
 406 .RB ( CAP_SYS_ADMIN )
 407 can employ
 408 .BR CLONE_NEWPID .
 409 This flag can't be specified in conjunction with
 410 .BR CLONE_THREAD
 411 or
 412 .BR CLONE_PARENT .
 413 .TP
 414 .BR CLONE_NEWUSER
 415 (This flag first became meaningful for
 416 .BR clone ()
 417 in Linux 2.6.23,
 418 the current
 419 .BR clone ()
 420 semantics were merged in Linux 3.5,
 421 and the final pieces to make the user namespaces completely usable were
 422 merged in Linux 3.8.)
 423
 424 If
 425 .B CLONE_NEWUSER
 426 is set, then create the process in a new user namespace.
 427 If this flag is not set, then (as with
 428 .BR fork (2))
 429 the process is created in the same user namespace as the calling process.
 430
 431 For further information on user namespaces, see
 432 .BR namespaces (7)
 433 and
 434 .BR user_namespaces (7)
 435
 436 Before Linux 3.8, use of
 437 .BR CLONE_NEWUSER
 438 required that the caller have three capabilities:
 439 .BR CAP_SYS_ADMIN ,
 440 .BR CAP_SETUID ,
 441 and
 442 .BR CAP_SETGID .
 443 .\" Before Linux 2.6.29, it appears that only CAP_SYS_ADMIN was needed
 444 Starting with Linux 3.8,
 445 no privileges are needed to create a user namespace.
 446
 447 This flag can't be specified in conjunction with
 448 .BR CLONE_THREAD
 449 or
 450 .BR CLONE_PARENT .
 451 For security reasons,
 452 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
 453 .\" https://lwn.net/Articles/543273/
 454 .\" The fix actually went into 3.9 and into 3.8.3. However, user namespaces
 455 .\" were, for practical purposes, unusable in earlier 3.8.x because of the
 456 .\" various filesystems that didn't support userns.
 457 .BR CLONE_NEWUSER
 458 cannot be specified in conjunction with
 459 .BR CLONE_FS .
 460
 461 For further information on user namespaces, see
 462 .BR user_namespaces (7).
 463 .TP
 464 .BR CLONE_NEWUTS " (since Linux 2.6.19)"
 465 If
 466 .B CLONE_NEWUTS
 467 is set, then create the process in a new UTS namespace,
 468 whose identifiers are initialized by duplicating the identifiers
 469 from the UTS namespace of the calling process.
 470 If this flag is not set, then (as with
 471 .BR fork (2))
 472 the process is created in the same UTS namespace as
 473 the calling process.
 474 This flag is intended for the implementation of containers.
 475
 476 A UTS namespace is the set of identifiers returned by
 477 .BR uname (2);
 478 among these, the domain name and the hostname can be modified by
 479 .BR setdomainname (2)
 480 and
 481 .BR sethostname (2),
 482 respectively.
 483 Changes made to the identifiers in a UTS namespace
 484 are visible to all other processes in the same namespace,
 485 but are not visible to processes in other UTS namespaces.
 486
 487 Only a privileged process
 488 .RB ( CAP_SYS_ADMIN )
 489 can employ
 490 .BR CLONE_NEWUTS .
 491
 492 For further information on UTS namespaces, see
 493 .BR namespaces (7).
 494 .TP
 495 .BR CLONE_PARENT " (since Linux 2.3.12)"
 496 If
 497 .B CLONE_PARENT
 498 is set, then the parent of the new child (as returned by
 499 .BR getppid (2))
 500 will be the same as that of the calling process.
 501
 502 If
 503 .B CLONE_PARENT
 504 is not set, then (as with
 505 .BR fork (2))
 506 the child's parent is the calling process.
 507
 508 Note that it is the parent process, as returned by
 509 .BR getppid (2),
 510 which is signaled when the child terminates, so that
 511 if
 512 .B CLONE_PARENT
 513 is set, then the parent of the calling process, rather than the
 514 calling process itself, will be signaled.
 515 .TP
 516 .BR CLONE_PARENT_SETTID " (since Linux 2.5.49)"
 517 Store the child thread ID at the location
 518 .I ptid
 519 in the parent's memory.
 520 (In Linux 2.5.32-2.5.48 there was a flag
 521 .B CLONE_SETTID
 522 that did this.)
 523 .TP
 524 .BR CLONE_PID " (obsolete)"
 525 If
 526 .B CLONE_PID
 527 is set, the child process is created with the same process ID as
 528 the calling process.
 529 This is good for hacking the system, but otherwise
 530 of not much use.
 531 Since 2.3.21 this flag can be
 532 specified only by the system boot process (PID 0).
 533 It disappeared in Linux 2.5.16.
 534 Since then, the kernel silently ignores it without error.
 535 .TP
 536 .BR CLONE_PTRACE " (since Linux 2.2)"
 537 If
 538 .B CLONE_PTRACE
 539 is specified, and the calling process is being traced,
 540 then trace the child also (see
 541 .BR ptrace (2)).
 542 .TP
 543 .BR CLONE_SETTLS " (since Linux 2.5.32)"
 544 The
 545 .I newtls
 546 argument is the new TLS (Thread Local Storage) descriptor.
 547 (See
 548 .BR set_thread_area (2).)
 549 .TP
 550 .BR CLONE_SIGHAND " (since Linux 2.0)"
 551 If
 552 .B CLONE_SIGHAND
 553 is set, the calling process and the child process share the same table of
 554 signal handlers.
 555 If the calling process or child process calls
 556 .BR sigaction (2)
 557 to change the behavior associated with a signal, the behavior is
 558 changed in the other process as well.
 559 However, the calling process and child
 560 processes still have distinct signal masks and sets of pending
 561 signals.
 562 So, one of them may block or unblock some signals using
 563 .BR sigprocmask (2)
 564 without affecting the other process.
 565
 566 If
 567 .B CLONE_SIGHAND
 568 is not set, the child process inherits a copy of the signal handlers
 569 of the calling process at the time
 570 .BR clone ()
 571 is called.
 572 Calls to
 573 .BR sigaction (2)
 574 performed later by one of the processes have no effect on the other
 575 process.
 576
 577 Since Linux 2.6.0-test6,
 578 .I flags
 579 must also include
 580 .B CLONE_VM
 581 if
 582 .B CLONE_SIGHAND
 583 is specified
 584 .TP
 585 .BR CLONE_STOPPED " (since Linux 2.6.0-test2)"
 586 If
 587 .B CLONE_STOPPED
 588 is set, then the child is initially stopped (as though it was sent a
 589 .B SIGSTOP
 590 signal), and must be resumed by sending it a
 591 .B SIGCONT
 592 signal.
 593
 594 This flag was
 595 .I deprecated
 596 from Linux 2.6.25 onward,
 597 and was
 598 .I removed
 599 altogether in Linux 2.6.38.
 600 Since then, the kernel silently ignores it without error.
 601 .\" glibc 2.8 removed this defn from bits/sched.h
 602 Starting with Linux 4.6, the same bit was reused for the
 603 .BR CLONE_NEWCGROUP
 604 flag.
 605 .TP
 606 .BR CLONE_SYSVSEM " (since Linux 2.5.10)"
 607 If
 608 .B CLONE_SYSVSEM
 609 is set, then the child and the calling process share
 610 a single list of System V semaphore adjustment
 611 .RI ( semadj )
 612 values (see
 613 .BR semop (2)).
 614 In this case, the shared list accumulates
 615 .I semadj
 616 values across all processes sharing the list,
 617 and semaphore adjustments are performed only when the last process
 618 that is sharing the list terminates (or ceases sharing the list using
 619 .BR unshare (2)).
 620 If this flag is not set, then the child has a separate
 621 .I semadj
 622 list that is initially empty.
 623 .TP
 624 .BR CLONE_THREAD " (since Linux 2.4.0-test8)"
 625 If
 626 .B CLONE_THREAD
 627 is set, the child is placed in the same thread group as the calling process.
 628 To make the remainder of the discussion of
 629 .B CLONE_THREAD
 630 more readable, the term "thread" is used to refer to the
 631 processes within a thread group.
 632
 633 Thread groups were a feature added in Linux 2.4 to support the
 634 POSIX threads notion of a set of threads that share a single PID.
 635 Internally, this shared PID is the so-called
 636 thread group identifier (TGID) for the thread group.
 637 Since Linux 2.4, calls to
 638 .BR getpid (2)
 639 return the TGID of the caller.
 640
 641 The threads within a group can be distinguished by their (system-wide)
 642 unique thread IDs (TID).
 643 A new thread's TID is available as the function result
 644 returned to the caller of
 645 .BR clone (),
 646 and a thread can obtain
 647 its own TID using
 648 .BR gettid (2).
 649
 650 When a call is made to
 651 .BR clone ()
 652 without specifying
 653 .BR CLONE_THREAD ,
 654 then the resulting thread is placed in a new thread group
 655 whose TGID is the same as the thread's TID.
 656 This thread is the
 657 .I leader
 658 of the new thread group.
 659
 660 A new thread created with
 661 .B CLONE_THREAD
 662 has the same parent process as the caller of
 663 .BR clone ()
 664 (i.e., like
 665 .BR CLONE_PARENT ),
 666 so that calls to
 667 .BR getppid (2)
 668 return the same value for all of the threads in a thread group.
 669 When a
 670 .B CLONE_THREAD
 671 thread terminates, the thread that created it using
 672 .BR clone ()
 673 is not sent a
 674 .B SIGCHLD
 675 (or other termination) signal;
 676 nor can the status of such a thread be obtained
 677 using
 678 .BR wait (2).
 679 (The thread is said to be
 680 .IR detached .)
 681
 682 After all of the threads in a thread group terminate
 683 the parent process of the thread group is sent a
 684 .B SIGCHLD
 685 (or other termination) signal.
 686
 687 If any of the threads in a thread group performs an
 688 .BR execve (2),
 689 then all threads other than the thread group leader are terminated,
 690 and the new program is executed in the thread group leader.
 691
 692 If one of the threads in a thread group creates a child using
 693 .BR fork (2),
 694 then any thread in the group can
 695 .BR wait (2)
 696 for that child.
 697
 698 Since Linux 2.5.35,
 699 .I flags
 700 must also include
 701 .B CLONE_SIGHAND
 702 if
 703 .B CLONE_THREAD
 704 is specified
 705 (and note that, since Linux 2.6.0-test6,
 706 .BR CLONE_SIGHAND
 707 also requires
 708 .BR CLONE_VM
 709 to be included).
 710
 711 Signals may be sent to a thread group as a whole (i.e., a TGID) using
 712 .BR kill (2),
 713 or to a specific thread (i.e., TID) using
 714 .BR tgkill (2).
 715
 716 Signal dispositions and actions are process-wide:
 717 if an unhandled signal is delivered to a thread, then
 718 it will affect (terminate, stop, continue, be ignored in)
 719 all members of the thread group.
 720
 721 Each thread has its own signal mask, as set by
 722 .BR sigprocmask (2),
 723 but signals can be pending either: for the whole process
 724 (i.e., deliverable to any member of the thread group),
 725 when sent with
 726 .BR kill (2);
 727 or for an individual thread, when sent with
 728 .BR tgkill (2).
 729 A call to
 730 .BR sigpending (2)
 731 returns a signal set that is the union of the signals pending for the
 732 whole process and the signals that are pending for the calling thread.
 733
 734 If
 735 .BR kill (2)
 736 is used to send a signal to a thread group,
 737 and the thread group has installed a handler for the signal, then
 738 the handler will be invoked in exactly one, arbitrarily selected
 739 member of the thread group that has not blocked the signal.
 740 If multiple threads in a group are waiting to accept the same signal using
 741 .BR sigwaitinfo (2),
 742 the kernel will arbitrarily select one of these threads
 743 to receive a signal sent using
 744 .BR kill (2).
 745 .TP
 746 .BR CLONE_UNTRACED " (since Linux 2.5.46)"
 747 If
 748 .B CLONE_UNTRACED
 749 is specified, then a tracing process cannot force
 750 .B CLONE_PTRACE
 751 on this child process.
 752 .TP
 753 .BR CLONE_VFORK " (since Linux 2.2)"
 754 If
 755 .B CLONE_VFORK
 756 is set, the execution of the calling process is suspended
 757 until the child releases its virtual memory
 758 resources via a call to
 759 .BR execve (2)
 760 or
 761 .BR _exit (2)
 762 (as with
 763 .BR vfork (2)).
 764
 765 If
 766 .B CLONE_VFORK
 767 is not set, then both the calling process and the child are schedulable
 768 after the call, and an application should not rely on execution occurring
 769 in any particular order.
 770 .TP
 771 .BR CLONE_VM " (since Linux 2.0)"
 772 If
 773 .B CLONE_VM
 774 is set, the calling process and the child process run in the same memory
 775 space.
 776 In particular, memory writes performed by the calling process
 777 or by the child process are also visible in the other process.
 778 Moreover, any memory mapping or unmapping performed with
 779 .BR mmap (2)
 780 or
 781 .BR munmap (2)
 782 by the child or calling process also affects the other process.
 783
 784 If
 785 .B CLONE_VM
 786 is not set, the child process runs in a separate copy of the memory
 787 space of the calling process at the time of
 788 .BR clone ().
 789 Memory writes or file mappings/unmappings performed by one of the
 790 processes do not affect the other, as with
 791 .BR fork (2).
 792 .SS C library/kernel differences
 793 The raw
 794 .BR clone ()
 795 system call corresponds more closely to
 796 .BR fork (2)
 797 in that execution in the child continues from the point of the
 798 call.
 799 As such, the
 800 .I fn
 801 and
 802 .I arg
 803 arguments of the
 804 .BR clone ()
 805 wrapper function are omitted.
 806 Furthermore, the argument order changes.
 807 The raw system call interface on x86 and many other architectures is roughly:
 808 .in +4
 809 .nf
 810
 811 .BI "long clone(unsigned long " flags ", void *" child_stack ,
 812 .BI "           void *" ptid ", void *" ctid ,
 813 .BI "           struct pt_regs *" regs );
 814
 815 .fi
 816 .in
 817 Another difference for the raw system call is that the
 818 .I child_stack
 819 argument may be zero, in which case copy-on-write semantics ensure that the
 820 child gets separate copies of stack pages when either process modifies
 821 the stack.
 822 In this case, for correct operation, the
 823 .B CLONE_VM
 824 option should not be specified.
 825
 826 For some architectures, the order of the arguments for the system call
 827 differs from that shown above.
 828 On the score, microblaze, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa,
 829 and MIPS architectures,
 830 the order of the fourth and fifth arguments is reversed.
 831 On the cris and s390 architectures,
 832 the order of the first and second arguments is reversed.
 833 .SS blackfin, m68k, and sparc
 834 The argument-passing conventions on
 835 blackfin, m68k, and sparc are different from the descriptions above.
 836 For details, see the kernel (and glibc) source.
 837 .SS ia64
 838 On ia64, a different interface is used:
 839 .nf
 840
 841 .BI "int __clone2(int (*" "fn" ")(void *), "
 842 .BI "             void *" child_stack_base ", size_t " stack_size ,
 843 .BI "             int " flags ", void *" "arg" ", ... "
 844 .BI "          /* pid_t *" ptid ", struct user_desc *" tls \
 845 ", pid_t *" ctid " */ );"
 846 .fi
 847 .PP
 848 The prototype shown above is for the glibc wrapper function;
 849 the raw system call interface has no
 850 .I fn
 851 or
 852 .I arg
 853 argument, and changes the order of the arguments so that
 854 .I flags
 855 is the first argument, and
 856 .I tls
 857 is the last argument.
 858 .PP
 859 .BR __clone2 ()
 860 operates in the same way as
 861 .BR clone (),
 862 except that
 863 .I child_stack_base
 864 points to the lowest address of the child's stack area,
 865 and
 866 .I stack_size
 867 specifies the size of the stack pointed to by
 868 .IR child_stack_base .
 869 .SS Linux 2.4 and earlier
 870 In Linux 2.4 and earlier,
 871 .BR clone ()
 872 does not take arguments
 873 .IR ptid ,
 874 .IR tls ,
 875 and
 876 .IR ctid .
 877 .SH RETURN VALUE
 878 .\" gettid(2) returns current->pid;
 879 .\" getpid(2) returns current->tgid;
 880 On success, the thread ID of the child process is returned
 881 in the caller's thread of execution.
 882 On failure, \-1 is returned
 883 in the caller's context, no child process will be created, and
 884 .I errno
 885 will be set appropriately.
 886 .SH ERRORS
 887 .TP
 888 .B EAGAIN
 889 Too many processes are already running; see
 890 .BR fork (2).
 891 .TP
 892 .B EINVAL
 893 .B CLONE_SIGHAND
 894 was specified, but
 895 .B CLONE_VM
 896 was not.
 897 (Since Linux 2.6.0-test6.)
 898 .TP
 899 .B EINVAL
 900 .B CLONE_THREAD
 901 was specified, but
 902 .B CLONE_SIGHAND
 903 was not.
 904 (Since Linux 2.5.35.)
 905 .\" .TP
 906 .\" .B EINVAL
 907 .\" Precisely one of
 908 .\" .B CLONE_DETACHED
 909 .\" and
 910 .\" .B CLONE_THREAD
 911 .\" was specified.
 912 .\" (Since Linux 2.6.0-test6.)
 913 .TP
 914 .B EINVAL
 915 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
 916 Both
 917 .B CLONE_FS
 918 and
 919 .B CLONE_NEWNS
 920 were specified in
 921 .IR flags .
 922 .TP
 923 .BR EINVAL " (since Linux 3.9)"
 924 Both
 925 .B CLONE_NEWUSER
 926 and
 927 .B CLONE_FS
 928 were specified in
 929 .IR flags .
 930 .TP
 931 .B EINVAL
 932 Both
 933 .B CLONE_NEWIPC
 934 and
 935 .B CLONE_SYSVSEM
 936 were specified in
 937 .IR flags .
 938 .TP
 939 .B EINVAL
 940 One (or both) of
 941 .BR CLONE_NEWPID
 942 or
 943 .BR CLONE_NEWUSER
 944 and one (or both) of
 945 .BR CLONE_THREAD
 946 or
 947 .BR CLONE_PARENT
 948 were specified in
 949 .IR flags .
 950 .TP
 951 .B EINVAL
 952 Returned by
 953 .BR clone ()
 954 when a zero value is specified for
 955 .IR child_stack .
 956 .TP
 957 .B EINVAL
 958 .BR CLONE_NEWIPC
 959 was specified in
 960 .IR flags ,
 961 but the kernel was not configured with the
 962 .B CONFIG_SYSVIPC
 963 and
 964 .BR CONFIG_IPC_NS
 965 options.
 966 .TP
 967 .B EINVAL
 968 .BR CLONE_NEWNET
 969 was specified in
 970 .IR flags ,
 971 but the kernel was not configured with the
 972 .B CONFIG_NET_NS
 973 option.
 974 .TP
 975 .B EINVAL
 976 .BR CLONE_NEWPID
 977 was specified in
 978 .IR flags ,
 979 but the kernel was not configured with the
 980 .B CONFIG_PID_NS
 981 option.
 982 .TP
 983 .B EINVAL
 984 .BR CLONE_NEWUTS
 985 was specified in
 986 .IR flags ,
 987 but the kernel was not configured with the
 988 .B CONFIG_UTS
 989 option.
 990 .TP
 991 .B EINVAL
 992 .I child_stack
 993 is not aligned to a suitable boundary for this architecture.
 994 For example, on aarch64,
 995 .I child_stack
 996 must be a multiple of 16.
 997 .TP
 998 .B ENOMEM
 999 Cannot allocate sufficient memory to allocate a task structure for the
1000 child, or to copy those parts of the caller's context that need to be
1001 copied.
1002 .TP
1003 .B EPERM
1004 .BR CLONE_NEWIPC ,
1005 .BR CLONE_NEWNET ,
1006 .BR CLONE_NEWNS ,
1007 .BR CLONE_NEWPID ,
1008 or
1009 .BR CLONE_NEWUTS
1010 was specified by an unprivileged process (process without \fBCAP_SYS_ADMIN\fP).
1011 .TP
1012 .B EPERM
1013 .B CLONE_PID
1014 was specified by a process other than process 0.
1015 .TP
1016 .B EPERM
1017 .BR CLONE_NEWUSER
1018 was specified in
1019 .IR flags ,
1020 but either the effective user ID or the effective group ID of the caller
1021 does not have a mapping in the parent namespace (see
1022 .BR user_namespaces (7)).
1023 .TP
1024 .BR EPERM " (since Linux 3.9)"
1025 .\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d
1026 .B CLONE_NEWUSER
1027 was specified in
1028 .I flags
1029 and the caller is in a chroot environment
1030 .\" FIXME What is the rationale for this restriction?
1031 (i.e., the caller's root directory does not match the root directory
1032 of the mount namespace in which it resides).
1033 .TP
1034 .BR EUSERS " (since Linux 3.11)"
1035 .B CLONE_NEWUSER
1036 was specified in
1037 .IR flags ,
1038 and the call would cause the limit on the number of
1039 nested user namespaces to be exceeded.
1040 See
1041 .BR user_namespaces (7).
1042 .TP
1043 .BR ERESTARTNOINTR " (since Linux 2.6.17)"
1044 .\" commit 4a2c7a7837da1b91468e50426066d988050e4d56
1045 System call was interrupted by a signal and will be restarted.
1046 (This can be seen only during a trace.)
1047 .SH VERSIONS
1048 There is no entry for
1049 .BR clone ()
1050 in libc5.
1051 glibc2 provides
1052 .BR clone ()
1053 as described in this manual page.
1054 .SH CONFORMING TO
1055 .BR clone ()
1056 is Linux-specific and should not be used in programs
1057 intended to be portable.
1058 .SH NOTES
1059 In the kernel 2.4.x series,
1060 .B CLONE_THREAD
1061 generally does not make the parent of the new thread the same
1062 as the parent of the calling process.
1063 However, for kernel versions 2.4.7 to 2.4.18 the
1064 .B CLONE_THREAD
1065 flag implied the
1066 .B CLONE_PARENT
1067 flag (as in kernel 2.6).
1068
1069 For a while there was
1070 .B CLONE_DETACHED
1071 (introduced in 2.5.32):
1072 parent wants no child-exit signal.
1073 In 2.6.2 the need to give this
1074 together with
1075 .B CLONE_THREAD
1076 disappeared.
1077 This flag is still defined, but has no effect.
1078
1079 On i386,
1080 .BR clone ()
1081 should not be called through vsyscall, but directly through
1082 .IR "int $0x80" .
1083 .SH BUGS
1084 Versions of the GNU C library that include the NPTL threading library
1085 contain a wrapper function for
1086 .BR getpid (2)
1087 that performs caching of PIDs.
1088 This caching relies on support in the glibc wrapper for
1089 .BR clone (),
1090 but as currently implemented,
1091 the cache may not be up to date in some circumstances.
1092 In particular,
1093 if a signal is delivered to the child immediately after the
1094 .BR clone ()
1095 call, then a call to
1096 .BR getpid (2)
1097 in a handler for the signal may return the PID
1098 of the calling process ("the parent"),
1099 if the clone wrapper has not yet had a chance to update the PID
1100 cache in the child.
1101 (This discussion ignores the case where the child was created using
1102 .BR CLONE_THREAD ,
1103 when
1104 .BR getpid (2)
1105 .I should
1106 return the same value in the child and in the process that called
1107 .BR clone (),
1108 since the caller and the child are in the same thread group.
1109 The stale-cache problem also does not occur if the
1110 .I flags
1111 argument includes
1112 .BR CLONE_VM .)
1113 To get the truth, it may be necessary to use code such as the following:
1114 .nf
1115
1116     #include <syscall.h>
1117
1118     pid_t mypid;
1119
1120     mypid = syscall(SYS_getpid);
1121 .fi
1122 .\" See also the following bug reports
1123 .\" https://bugzilla.redhat.com/show_bug.cgi?id=417521
1124 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910
1125 .SH EXAMPLE
1126 The following program demonstrates the use of
1127 .BR clone ()
1128 to create a child process that executes in a separate UTS namespace.
1129 The child changes the hostname in its UTS namespace.
1130 Both parent and child then display the system hostname,
1131 making it possible to see that the hostname
1132 differs in the UTS namespaces of the parent and child.
1133 For an example of the use of this program, see
1134 .BR setns (2).
1135 .SS Program source
1136 .nf
1137 #define _GNU_SOURCE
1138 #include <sys/wait.h>
1139 #include <sys/utsname.h>
1140 #include <sched.h>
1141 #include <string.h>
1142 #include <stdio.h>
1143 #include <stdlib.h>
1144 #include <unistd.h>
1145
1146 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \\
1147                         } while (0)
1148
1149 static int              /* Start function for cloned child */
1150 childFunc(void *arg)
1151 {
1152     struct utsname uts;
1153
1154     /* Change hostname in UTS namespace of child */
1155
1156     if (sethostname(arg, strlen(arg)) == \-1)
1157         errExit("sethostname");
1158
1159     /* Retrieve and display hostname */
1160
1161     if (uname(&uts) == \-1)
1162         errExit("uname");
1163     printf("uts.nodename in child:  %s\\n", uts.nodename);
1164
1165     /* Keep the namespace open for a while, by sleeping.
1166        This allows some experimentation\-\-for example, another
1167        process might join the namespace. */
1168
1169     sleep(200);
1170
1171     return 0;           /* Child terminates now */
1172 }
1173
1174 #define STACK_SIZE (1024 * 1024)    /* Stack size for cloned child */
1175
1176 int
1177 main(int argc, char *argv[])
1178 {
1179     char *stack;                    /* Start of stack buffer */
1180     char *stackTop;                 /* End of stack buffer */
1181     pid_t pid;
1182     struct utsname uts;
1183
1184     if (argc < 2) {
1185         fprintf(stderr, "Usage: %s <child\-hostname>\\n", argv[0]);
1186         exit(EXIT_SUCCESS);
1187     }
1188
1189     /* Allocate stack for child */
1190
1191     stack = malloc(STACK_SIZE);
1192     if (stack == NULL)
1193         errExit("malloc");
1194     stackTop = stack + STACK_SIZE;  /* Assume stack grows downward */
1195
1196     /* Create child that has its own UTS namespace;
1197        child commences execution in childFunc() */
1198
1199     pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]);
1200     if (pid == \-1)
1201         errExit("clone");
1202     printf("clone() returned %ld\\n", (long) pid);
1203
1204     /* Parent falls through to here */
1205
1206     sleep(1);           /* Give child time to change its hostname */
1207
1208     /* Display hostname in parent\(aqs UTS namespace. This will be
1209        different from hostname in child\(aqs UTS namespace. */
1210
1211     if (uname(&uts) == \-1)
1212         errExit("uname");
1213     printf("uts.nodename in parent: %s\\n", uts.nodename);
1214
1215     if (waitpid(pid, NULL, 0) == \-1)    /* Wait for child */
1216         errExit("waitpid");
1217     printf("child has terminated\\n");
1218
1219     exit(EXIT_SUCCESS);
1220 }
1221 .fi
1222 .SH SEE ALSO
1223 .BR fork (2),
1224 .BR futex (2),
1225 .BR getpid (2),
1226 .BR gettid (2),
1227 .BR kcmp (2),
1228 .BR set_thread_area (2),
1229 .BR set_tid_address (2),
1230 .BR setns (2),
1231 .BR tkill (2),
1232 .BR unshare (2),
1233 .BR wait (2),
1234 .BR capabilities (7),
1235 .BR namespaces (7),
1236 .BR pthreads (7)