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