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