original/man2/clone.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (c) 1992 Drew Eckhardt <drew@cs.colorado.edu>, March 28, 1992
   4 .\" and Copyright (c) Michael Kerrisk, 2001, 2002, 2005
   5 .\" May be distributed under the GNU General Public License.
   6 .\" Modified by Michael Haardt <michael@moria.de>
   7 .\" Modified 24 Jul 1993 by Rik Faith <faith@cs.unc.edu>
   8 .\" Modified 21 Aug 1994 by Michael Chastain <mec@shell.portal.com>:
   9 .\"   New man page (copied from 'fork.2').
  10 .\" Modified 10 June 1995 by Andries Brouwer <aeb@cwi.nl>
  11 .\" Modified 25 April 1998 by Xavier Leroy <Xavier.Leroy@inria.fr>
  12 .\" Modified 26 Jun 2001 by Michael Kerrisk
  13 .\"     Mostly upgraded to 2.4.x
  14 .\"     Added prototype for sys_clone() plus description
  15 .\"     Added CLONE_THREAD with a brief description of thread groups
  16 .\"     Added CLONE_PARENT and revised entire page remove ambiguity
  17 .\"             between "calling process" and "parent process"
  18 .\"     Added CLONE_PTRACE and CLONE_VFORK
  19 .\"     Added EPERM and EINVAL error codes
  20 .\"     Renamed "__clone" to "clone" (which is the prototype in <sched.h>)
  21 .\"     various other minor tidy ups and clarifications.
  22 .\" Modified 26 Jun 2001 by Michael Kerrisk <mtk.manpages@gmail.com>
  23 .\"     Updated notes for 2.4.7+ behavior of CLONE_THREAD
  24 .\" Modified 15 Oct 2002 by Michael Kerrisk <mtk.manpages@gmail.com>
  25 .\"     Added description for CLONE_NEWNS, which was added in 2.4.19
  26 .\" Slightly rephrased, aeb.
  27 .\" Modified 1 Feb 2003 - added CLONE_SIGHAND restriction, aeb.
  28 .\" Modified 1 Jan 2004 - various updates, aeb
  29 .\" Modified 2004-09-10 - added CLONE_PARENT_SETTID etc. - aeb.
  30 .\" 2005-04-12, mtk, noted the PID caching behavior of NPTL's getpid()
  31 .\"     wrapper under BUGS.
  32 .\" 2005-05-10, mtk, added CLONE_SYSVSEM, CLONE_UNTRACED, CLONE_STOPPED.
  33 .\" 2005-05-17, mtk, Substantially enhanced discussion of CLONE_THREAD.
  34 .\" 2008-11-18, mtk, order CLONE_* flags alphabetically
  35 .\" 2008-11-18, mtk, document CLONE_NEWPID
  36 .\" 2008-11-19, mtk, document CLONE_NEWUTS
  37 .\" 2008-11-19, mtk, document CLONE_NEWIPC
  38 .\" 2008-11-19, Jens Axboe, mtk, document CLONE_IO
  39 .\"
  40 .\" FIXME Document CLONE_NEWUSER, which is new in 2.6.23
  41 .\"       (also supported for unshare()?)
  42 .\"
  43 .TH CLONE 2 2011-09-08 "Linux" "Linux Programmer's Manual"
  44 .SH NAME
  45 clone, __clone2 \- create a child process
  46 .SH SYNOPSIS
  47 .nf
  48 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  49 .\" Actually _BSD_SOURCE || _SVID_SOURCE
  50 .\" See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749
  51 .B #include <sched.h>
  52
  53 .BI "int clone(int (*" "fn" ")(void *), void *" child_stack ,
  54 .BI "          int " flags ", void *" "arg" ", ... "
  55 .BI "          /* pid_t *" ptid ", struct user_desc *" tls \
  56 ", pid_t *" ctid " */ );"
  57 .fi
  58 .SH DESCRIPTION
  59 .BR clone ()
  60 creates a new process, in a manner similar to
  61 .BR fork (2).
  62 It is actually a library function layered on top of the underlying
  63 .BR clone ()
  64 system call, hereinafter referred to as
  65 .BR sys_clone .
  66 A description of
  67 .B sys_clone
  68 is given toward the end of this page.
  69
  70 Unlike
  71 .BR fork (2),
  72 these calls
  73 allow the child process to share parts of its execution context with
  74 the calling process, such as the memory space, the table of file
  75 descriptors, and the table of signal handlers.
  76 (Note that on this manual
  77 page, "calling process" normally corresponds to "parent process".
  78 But see the description of
  79 .B CLONE_PARENT
  80 below.)
  81
  82 The main use of
  83 .BR clone ()
  84 is to implement threads: multiple threads of control in a program that
  85 run concurrently in a shared memory space.
  86
  87 When the child process is created with
  88 .BR clone (),
  89 it executes the function
  90 application
  91 .IR fn ( arg ).
  92 (This differs from
  93 .BR fork (2),
  94 where execution continues in the child from the point
  95 of the
  96 .BR fork (2)
  97 call.)
  98 The
  99 .I fn
 100 argument is a pointer to a function that is called by the child
 101 process at the beginning of its execution.
 102 The
 103 .I arg
 104 argument is passed to the
 105 .I fn
 106 function.
 107
 108 When the
 109 .IR fn ( arg )
 110 function application returns, the child process terminates.
 111 The integer returned by
 112 .I fn
 113 is the exit code for the child process.
 114 The child process may also terminate explicitly by calling
 115 .BR exit (2)
 116 or after receiving a fatal signal.
 117
 118 The
 119 .I child_stack
 120 argument specifies the location of the stack used by the child process.
 121 Since the child and calling process may share memory,
 122 it is not possible for the child process to execute in the
 123 same stack as the calling process.
 124 The calling process must therefore
 125 set up memory space for the child stack and pass a pointer to this
 126 space to
 127 .BR clone ().
 128 Stacks grow downward on all processors that run Linux
 129 (except the HP PA processors), so
 130 .I child_stack
 131 usually points to the topmost address of the memory space set up for
 132 the child stack.
 133
 134 The low byte of
 135 .I flags
 136 contains the number of the
 137 .I "termination signal"
 138 sent to the parent when the child dies.
 139 If this signal is specified as anything other than
 140 .BR SIGCHLD ,
 141 then the parent process must specify the
 142 .B __WALL
 143 or
 144 .B __WCLONE
 145 options when waiting for the child with
 146 .BR wait (2).
 147 If no signal is specified, then the parent process is not signaled
 148 when the child terminates.
 149
 150 .I flags
 151 may also be bitwise-or'ed with zero or more of the following constants,
 152 in order to specify what is shared between the calling process
 153 and the child process:
 154 .TP
 155 .BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)"
 156 Erase child thread ID at location
 157 .I ctid
 158 in child memory when the child exits, and do a wakeup on the futex
 159 at that address.
 160 The address involved may be changed by the
 161 .BR set_tid_address (2)
 162 system call.
 163 This is used by threading libraries.
 164 .TP
 165 .BR CLONE_CHILD_SETTID " (since Linux 2.5.49)"
 166 Store child thread ID at location
 167 .I ctid
 168 in child memory.
 169 .TP
 170 .B CLONE_FILES
 171 If
 172 .B CLONE_FILES
 173 is set, the calling process and the child process share the same file
 174 descriptor table.
 175 Any file descriptor created by the calling process or by the child
 176 process is also valid in the other process.
 177 Similarly, if one of the processes closes a file descriptor,
 178 or changes its associated flags (using the
 179 .BR fcntl (2)
 180 .B F_SETFD
 181 operation), the other process is also affected.
 182
 183 If
 184 .B CLONE_FILES
 185 is not set, the child process inherits a copy of all file descriptors
 186 opened in the calling process at the time of
 187 .BR clone ().
 188 (The duplicated file descriptors in the child refer to the
 189 same open file descriptions (see
 190 .BR open (2))
 191 as the corresponding file descriptors in the calling process.)
 192 Subsequent operations that open or close file descriptors,
 193 or change file descriptor flags,
 194 performed by either the calling
 195 process or the child process do not affect the other process.
 196 .TP
 197 .B CLONE_FS
 198 If
 199 .B CLONE_FS
 200 is set, the caller and the child process share the same file system
 201 information.
 202 This includes the root of the file system, the current
 203 working directory, and the umask.
 204 Any call to
 205 .BR chroot (2),
 206 .BR chdir (2),
 207 or
 208 .BR umask (2)
 209 performed by the calling process or the child process also affects the
 210 other process.
 211
 212 If
 213 .B CLONE_FS
 214 is not set, the child process works on a copy of the file system
 215 information of the calling process at the time of the
 216 .BR clone ()
 217 call.
 218 Calls to
 219 .BR chroot (2),
 220 .BR chdir (2),
 221 .BR umask (2)
 222 performed later by one of the processes do not affect the other process.
 223 .TP
 224 .BR CLONE_IO " (since Linux 2.6.25)"
 225 If
 226 .B CLONE_IO
 227 is set, then the new process shares an I/O context with
 228 the calling process.
 229 If this flag is not set, then (as with
 230 .BR fork (2))
 231 the new process has its own I/O context.
 232
 233 .\" The following based on text from Jens Axboe
 234 The I/O context is the I/O scope of the disk scheduler (i.e,
 235 what the I/O scheduler uses to model scheduling of a process's I/O).
 236 If processes share the same I/O context,
 237 they are treated as one by the I/O scheduler.
 238 As a consequence, they get to share disk time.
 239 For some I/O schedulers,
 240 .\" the anticipatory and CFQ scheduler
 241 if two processes share an I/O context,
 242 they will be allowed to interleave their disk access.
 243 If several threads are doing I/O on behalf of the same process
 244 .RB ( aio_read (3),
 245 for instance), they should employ
 246 .BR CLONE_IO
 247 to get better I/O performance.
 248 .\" with CFQ and AS.
 249
 250 If the kernel is not configured with the
 251 .B CONFIG_BLOCK
 252 option, this flag is a no-op.
 253 .TP
 254 .BR CLONE_NEWIPC " (since Linux 2.6.19)"
 255 If
 256 .B CLONE_NEWIPC
 257 is set, then create the process in a new IPC namespace.
 258 If this flag is not set, then (as with
 259 .BR fork (2)),
 260 the process is created in the same IPC namespace as
 261 the calling process.
 262 This flag is intended for the implementation of containers.
 263
 264 An IPC namespace consists of the set of identifiers for
 265 System V IPC objects.
 266 (These objects are created using
 267 .BR msgctl (2),
 268 .BR semctl (2),
 269 and
 270 .BR shmctl (2)).
 271 Objects created in an IPC namespace are visible to all other processes
 272 that are members of that namespace,
 273 but are not visible to processes in other IPC namespaces.
 274
 275 When an IPC namespace is destroyed
 276 (i.e, when the last process that is a member of the namespace terminates),
 277 all IPC objects in the namespace are automatically destroyed.
 278
 279 Use of this flag requires: a kernel configured with the
 280 .B CONFIG_SYSVIPC
 281 and
 282 .B CONFIG_IPC_NS
 283 options and that the process be privileged
 284 .RB ( CAP_SYS_ADMIN ).
 285 This flag can't be specified in conjunction with
 286 .BR CLONE_SYSVSEM .
 287 .TP
 288 .BR CLONE_NEWNET " (since Linux 2.6.24)"
 289 .\" FIXME Check when the implementation was completed
 290 (The implementation of this flag was only completed
 291 by about kernel version 2.6.29.)
 292
 293 If
 294 .B CLONE_NEWNET
 295 is set, then create the process in a new network namespace.
 296 If this flag is not set, then (as with
 297 .BR fork (2)),
 298 the process is created in the same network namespace as
 299 the calling process.
 300 This flag is intended for the implementation of containers.
 301
 302 A network namespace provides an isolated view of the networking stack
 303 (network device interfaces, IPv4 and IPv6 protocol stacks,
 304 IP routing tables, firewall rules, the
 305 .I /proc/net
 306 and
 307 .I /sys/class/net
 308 directory trees, sockets, etc.).
 309 A physical network device can live in exactly one
 310 network namespace.
 311 A virtual network device ("veth") pair provides a pipe-like abstraction
 312 that can be used to create tunnels between network namespaces,
 313 and can be used to create a bridge to a physical network device
 314 in another namespace.
 315
 316 When a network namespace is freed
 317 (i.e., when the last process in the namespace terminates),
 318 its physical network devices are moved back to the
 319 initial network namespace (not to the parent of the process).
 320
 321 Use of this flag requires: a kernel configured with the
 322 .B CONFIG_NET_NS
 323 option and that the process be privileged
 324 .RB ( CAP_SYS_ADMIN ).
 325 .TP
 326 .BR CLONE_NEWNS " (since Linux 2.4.19)"
 327 Start the child in a new mount namespace.
 328
 329 Every process lives in a mount namespace.
 330 The
 331 .I namespace
 332 of a process is the data (the set of mounts) describing the file hierarchy
 333 as seen by that process.
 334 After a
 335 .BR fork (2)
 336 or
 337 .BR clone ()
 338 where the
 339 .B CLONE_NEWNS
 340 flag is not set, the child lives in the same mount
 341 namespace as the parent.
 342 The system calls
 343 .BR mount (2)
 344 and
 345 .BR umount (2)
 346 change the mount namespace of the calling process, and hence affect
 347 all processes that live in the same namespace, but do not affect
 348 processes in a different mount namespace.
 349
 350 After a
 351 .BR clone ()
 352 where the
 353 .B CLONE_NEWNS
 354 flag is set, the cloned child is started in a new mount namespace,
 355 initialized with a copy of the namespace of the parent.
 356
 357 Only a privileged process (one having the \fBCAP_SYS_ADMIN\fP capability)
 358 may specify the
 359 .B CLONE_NEWNS
 360 flag.
 361 It is not permitted to specify both
 362 .B CLONE_NEWNS
 363 and
 364 .B CLONE_FS
 365 in the same
 366 .BR clone ()
 367 call.
 368 .TP
 369 .BR CLONE_NEWPID " (since Linux 2.6.24)"
 370 .\" This explanation draws a lot of details from
 371 .\" http://lwn.net/Articles/259217/
 372 .\" Authors: Pavel Emelyanov <xemul@openvz.org>
 373 .\" and Kir Kolyshkin <kir@openvz.org>
 374 .\"
 375 .\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264
 376 .\" Author: Pavel Emelyanov <xemul@openvz.org>
 377 If
 378 .B CLONE_NEWPID
 379 is set, then create the process in a new PID namespace.
 380 If this flag is not set, then (as with
 381 .BR fork (2)),
 382 the process is created in the same PID namespace as
 383 the calling process.
 384 This flag is intended for the implementation of containers.
 385
 386 A PID namespace provides an isolated environment for PIDs:
 387 PIDs in a new namespace start at 1,
 388 somewhat like a standalone system, and calls to
 389 .BR fork (2),
 390 .BR vfork (2),
 391 or
 392 .BR clone ()
 393 will produce processes with PIDs that are unique within the namespace.
 394
 395 The first process created in a new namespace
 396 (i.e., the process created using the
 397 .BR CLONE_NEWPID
 398 flag) has the PID 1, and is the "init" process for the namespace.
 399 Children that are orphaned within the namespace will be reparented
 400 to this process rather than
 401 .BR init (8).
 402 Unlike the traditional
 403 .B init
 404 process, the "init" process of a PID namespace can terminate,
 405 and if it does, all of the processes in the namespace are terminated.
 406
 407 PID namespaces form a hierarchy.
 408 When a new PID namespace is created,
 409 the processes in that namespace are visible
 410 in the PID namespace of the process that created the new namespace;
 411 analogously, if the parent PID namespace is itself
 412 the child of another PID namespace,
 413 then processes in the child and parent PID namespaces will both be
 414 visible in the grandparent PID namespace.
 415 Conversely, the processes in the "child" PID namespace do not see
 416 the processes in the parent namespace.
 417 The existence of a namespace hierarchy means that each process
 418 may now have multiple PIDs:
 419 one for each namespace in which it is visible;
 420 each of these PIDs is unique within the corresponding namespace.
 421 (A call to
 422 .BR getpid (2)
 423 always returns the PID associated with the namespace in which
 424 the process lives.)
 425
 426 After creating the new namespace,
 427 it is useful for the child to change its root directory
 428 and mount a new procfs instance at
 429 .I /proc
 430 so that tools such as
 431 .BR ps (1)
 432 work correctly.
 433 .\" mount -t proc proc /proc
 434 (If
 435 .BR CLONE_NEWNS
 436 is also included in
 437 .IR flags ,
 438 then it isn't necessary to change the root directory:
 439 a new procfs instance can be mounted directly over
 440 .IR /proc .)
 441
 442 Use of this flag requires: a kernel configured with the
 443 .B CONFIG_PID_NS
 444 option and that the process be privileged
 445 .RB ( CAP_SYS_ADMIN ).
 446 This flag can't be specified in conjunction with
 447 .BR CLONE_THREAD .
 448 .TP
 449 .BR CLONE_NEWUTS " (since Linux 2.6.19)"
 450 If
 451 .B CLONE_NEWUTS
 452 is set, then create the process in a new UTS namespace,
 453 whose identifiers are initialized by duplicating the identifiers
 454 from the UTS namespace of the calling process.
 455 If this flag is not set, then (as with
 456 .BR fork (2)),
 457 the process is created in the same UTS namespace as
 458 the calling process.
 459 This flag is intended for the implementation of containers.
 460
 461 A UTS namespace is the set of identifiers returned by
 462 .BR uname (2);
 463 among these, the domain name and the host name can be modified by
 464 .BR setdomainname (2)
 465 and
 466 .BR
 467 .BR sethostname (2),
 468 respectively.
 469 Changes made to the identifiers in a UTS namespace
 470 are visible to all other processes in the same namespace,
 471 but are not visible to processes in other UTS namespaces.
 472
 473 Use of this flag requires: a kernel configured with the
 474 .B CONFIG_UTS_NS
 475 option and that the process be privileged
 476 .RB ( CAP_SYS_ADMIN ).
 477 .TP
 478 .BR CLONE_PARENT " (since Linux 2.3.12)"
 479 If
 480 .B CLONE_PARENT
 481 is set, then the parent of the new child (as returned by
 482 .BR getppid (2))
 483 will be the same as that of the calling process.
 484
 485 If
 486 .B CLONE_PARENT
 487 is not set, then (as with
 488 .BR fork (2))
 489 the child's parent is the calling process.
 490
 491 Note that it is the parent process, as returned by
 492 .BR getppid (2),
 493 which is signaled when the child terminates, so that
 494 if
 495 .B CLONE_PARENT
 496 is set, then the parent of the calling process, rather than the
 497 calling process itself, will be signaled.
 498 .TP
 499 .BR CLONE_PARENT_SETTID " (since Linux 2.5.49)"
 500 Store child thread ID at location
 501 .I ptid
 502 in parent and child memory.
 503 (In Linux 2.5.32-2.5.48 there was a flag
 504 .B CLONE_SETTID
 505 that did this.)
 506 .TP
 507 .BR CLONE_PID " (obsolete)"
 508 If
 509 .B CLONE_PID
 510 is set, the child process is created with the same process ID as
 511 the calling process.
 512 This is good for hacking the system, but otherwise
 513 of not much use.
 514 Since 2.3.21 this flag can be
 515 specified only by the system boot process (PID 0).
 516 It disappeared in Linux 2.5.16.
 517 .TP
 518 .B CLONE_PTRACE
 519 If
 520 .B CLONE_PTRACE
 521 is specified, and the calling process is being traced,
 522 then trace the child also (see
 523 .BR ptrace (2)).
 524 .TP
 525 .BR CLONE_SETTLS " (since Linux 2.5.32)"
 526 The
 527 .I newtls
 528 argument is the new TLS (Thread Local Storage) descriptor.
 529 (See
 530 .BR set_thread_area (2).)
 531 .TP
 532 .B CLONE_SIGHAND
 533 If
 534 .B CLONE_SIGHAND
 535 is set, the calling process and the child process share the same table of
 536 signal handlers.
 537 If the calling process or child process calls
 538 .BR sigaction (2)
 539 to change the behavior associated with a signal, the behavior is
 540 changed in the other process as well.
 541 However, the calling process and child
 542 processes still have distinct signal masks and sets of pending
 543 signals.
 544 So, one of them may block or unblock some signals using
 545 .BR sigprocmask (2)
 546 without affecting the other process.
 547
 548 If
 549 .B CLONE_SIGHAND
 550 is not set, the child process inherits a copy of the signal handlers
 551 of the calling process at the time
 552 .BR clone ()
 553 is called.
 554 Calls to
 555 .BR sigaction (2)
 556 performed later by one of the processes have no effect on the other
 557 process.
 558
 559 Since Linux 2.6.0-test6,
 560 .I flags
 561 must also include
 562 .B CLONE_VM
 563 if
 564 .B CLONE_SIGHAND
 565 is specified
 566 .TP
 567 .BR CLONE_STOPPED " (since Linux 2.6.0-test2)"
 568 If
 569 .B CLONE_STOPPED
 570 is set, then the child is initially stopped (as though it was sent a
 571 .B SIGSTOP
 572 signal), and must be resumed by sending it a
 573 .B SIGCONT
 574 signal.
 575
 576 This flag was
 577 .I deprecated
 578 from Linux 2.6.25 onward,
 579 and was
 580 .I removed
 581 altogether in Linux 2.6.38.
 582 .\" glibc 2.8 removed this defn from bits/sched.h
 583 .TP
 584 .BR CLONE_SYSVSEM " (since Linux 2.5.10)"
 585 If
 586 .B CLONE_SYSVSEM
 587 is set, then the child and the calling process share
 588 a single list of System V semaphore undo values (see
 589 .BR semop (2)).
 590 If this flag is not set, then the child has a separate undo list,
 591 which is initially empty.
 592 .TP
 593 .BR CLONE_THREAD " (since Linux 2.4.0-test8)"
 594 If
 595 .B CLONE_THREAD
 596 is set, the child is placed in the same thread group as the calling process.
 597 To make the remainder of the discussion of
 598 .B CLONE_THREAD
 599 more readable, the term "thread" is used to refer to the
 600 processes within a thread group.
 601
 602 Thread groups were a feature added in Linux 2.4 to support the
 603 POSIX threads notion of a set of threads that share a single PID.
 604 Internally, this shared PID is the so-called
 605 thread group identifier (TGID) for the thread group.
 606 Since Linux 2.4, calls to
 607 .BR getpid (2)
 608 return the TGID of the caller.
 609
 610 The threads within a group can be distinguished by their (system-wide)
 611 unique thread IDs (TID).
 612 A new thread's TID is available as the function result
 613 returned to the caller of
 614 .BR clone (),
 615 and a thread can obtain
 616 its own TID using
 617 .BR gettid (2).
 618
 619 When a call is made to
 620 .BR clone ()
 621 without specifying
 622 .BR CLONE_THREAD ,
 623 then the resulting thread is placed in a new thread group
 624 whose TGID is the same as the thread's TID.
 625 This thread is the
 626 .I leader
 627 of the new thread group.
 628
 629 A new thread created with
 630 .B CLONE_THREAD
 631 has the same parent process as the caller of
 632 .BR clone ()
 633 (i.e., like
 634 .BR CLONE_PARENT ),
 635 so that calls to
 636 .BR getppid (2)
 637 return the same value for all of the threads in a thread group.
 638 When a
 639 .B CLONE_THREAD
 640 thread terminates, the thread that created it using
 641 .BR clone ()
 642 is not sent a
 643 .B SIGCHLD
 644 (or other termination) signal;
 645 nor can the status of such a thread be obtained
 646 using
 647 .BR wait (2).
 648 (The thread is said to be
 649 .IR detached .)
 650
 651 After all of the threads in a thread group terminate
 652 the parent process of the thread group is sent a
 653 .B SIGCHLD
 654 (or other termination) signal.
 655
 656 If any of the threads in a thread group performs an
 657 .BR execve (2),
 658 then all threads other than the thread group leader are terminated,
 659 and the new program is executed in the thread group leader.
 660
 661 If one of the threads in a thread group creates a child using
 662 .BR fork (2),
 663 then any thread in the group can
 664 .BR wait (2)
 665 for that child.
 666
 667 Since Linux 2.5.35,
 668 .I flags
 669 must also include
 670 .B CLONE_SIGHAND
 671 if
 672 .B CLONE_THREAD
 673 is specified.
 674
 675 Signals may be sent to a thread group as a whole (i.e., a TGID) using
 676 .BR kill (2),
 677 or to a specific thread (i.e., TID) using
 678 .BR tgkill (2).
 679
 680 Signal dispositions and actions are process-wide:
 681 if an unhandled signal is delivered to a thread, then
 682 it will affect (terminate, stop, continue, be ignored in)
 683 all members of the thread group.
 684
 685 Each thread has its own signal mask, as set by
 686 .BR sigprocmask (2),
 687 but signals can be pending either: for the whole process
 688 (i.e., deliverable to any member of the thread group),
 689 when sent with
 690 .BR kill (2);
 691 or for an individual thread, when sent with
 692 .BR tgkill (2).
 693 A call to
 694 .BR sigpending (2)
 695 returns a signal set that is the union of the signals pending for the
 696 whole process and the signals that are pending for the calling thread.
 697
 698 If
 699 .BR kill (2)
 700 is used to send a signal to a thread group,
 701 and the thread group has installed a handler for the signal, then
 702 the handler will be invoked in exactly one, arbitrarily selected
 703 member of the thread group that has not blocked the signal.
 704 If multiple threads in a group are waiting to accept the same signal using
 705 .BR sigwaitinfo (2),
 706 the kernel will arbitrarily select one of these threads
 707 to receive a signal sent using
 708 .BR kill (2).
 709 .TP
 710 .BR CLONE_UNTRACED " (since Linux 2.5.46)"
 711 If
 712 .B CLONE_UNTRACED
 713 is specified, then a tracing process cannot force
 714 .B CLONE_PTRACE
 715 on this child process.
 716 .TP
 717 .B CLONE_VFORK
 718 If
 719 .B CLONE_VFORK
 720 is set, the execution of the calling process is suspended
 721 until the child releases its virtual memory
 722 resources via a call to
 723 .BR execve (2)
 724 or
 725 .BR _exit (2)
 726 (as with
 727 .BR vfork (2)).
 728
 729 If
 730 .B CLONE_VFORK
 731 is not set then both the calling process and the child are schedulable
 732 after the call, and an application should not rely on execution occurring
 733 in any particular order.
 734 .TP
 735 .B CLONE_VM
 736 If
 737 .B CLONE_VM
 738 is set, the calling process and the child process run in the same memory
 739 space.
 740 In particular, memory writes performed by the calling process
 741 or by the child process are also visible in the other process.
 742 Moreover, any memory mapping or unmapping performed with
 743 .BR mmap (2)
 744 or
 745 .BR munmap (2)
 746 by the child or calling process also affects the other process.
 747
 748 If
 749 .B CLONE_VM
 750 is not set, the child process runs in a separate copy of the memory
 751 space of the calling process at the time of
 752 .BR clone ().
 753 Memory writes or file mappings/unmappings performed by one of the
 754 processes do not affect the other, as with
 755 .BR fork (2).
 756 .SS "sys_clone"
 757 The
 758 .B sys_clone
 759 system call corresponds more closely to
 760 .BR fork (2)
 761 in that execution in the child continues from the point of the
 762 call.
 763 Thus,
 764 .B sys_clone
 765 only requires the
 766 .I flags
 767 and
 768 .I child_stack
 769 arguments, which have the same meaning as for
 770 .BR clone ().
 771 (Note that the order of these arguments differs from
 772 .BR clone ().)
 773
 774 Another difference for
 775 .B sys_clone
 776 is that the
 777 .I child_stack
 778 argument may be zero, in which case copy-on-write semantics ensure that the
 779 child gets separate copies of stack pages when either process modifies
 780 the stack.
 781 In this case, for correct operation, the
 782 .B CLONE_VM
 783 option should not be specified.
 784
 785 In Linux 2.4 and earlier,
 786 .BR clone ()
 787 does not take arguments
 788 .IR ptid ,
 789 .IR tls ,
 790 and
 791 .IR ctid .
 792 .SH "RETURN VALUE"
 793 .\" gettid(2) returns current->pid;
 794 .\" getpid(2) returns current->tgid;
 795 On success, the thread ID of the child process is returned
 796 in the caller's thread of execution.
 797 On failure, \-1 is returned
 798 in the caller's context, no child process will be created, and
 799 .I errno
 800 will be set appropriately.
 801 .SH ERRORS
 802 .TP
 803 .B EAGAIN
 804 Too many processes are already running.
 805 .TP
 806 .B EINVAL
 807 .B CLONE_SIGHAND
 808 was specified, but
 809 .B CLONE_VM
 810 was not.
 811 (Since Linux 2.6.0-test6.)
 812 .TP
 813 .B EINVAL
 814 .B CLONE_THREAD
 815 was specified, but
 816 .B CLONE_SIGHAND
 817 was not.
 818 (Since Linux 2.5.35.)
 819 .\" .TP
 820 .\" .B EINVAL
 821 .\" Precisely one of
 822 .\" .B CLONE_DETACHED
 823 .\" and
 824 .\" .B CLONE_THREAD
 825 .\" was specified.
 826 .\" (Since Linux 2.6.0-test6.)
 827 .TP
 828 .B EINVAL
 829 Both
 830 .B CLONE_FS
 831 and
 832 .B CLONE_NEWNS
 833 were specified in
 834 .IR flags .
 835 .TP
 836 .B EINVAL
 837 Both
 838 .B CLONE_NEWIPC
 839 and
 840 .B CLONE_SYSVSEM
 841 were specified in
 842 .IR flags .
 843 .TP
 844 .B EINVAL
 845 Both
 846 .BR CLONE_NEWPID
 847 and
 848 .BR CLONE_THREAD
 849 were specified in
 850 .IR flags .
 851 .TP
 852 .B EINVAL
 853 Returned by
 854 .BR clone ()
 855 when a zero value is specified for
 856 .IR child_stack .
 857 .TP
 858 .B EINVAL
 859 .BR CLONE_NEWIPC
 860 was specified in
 861 .IR flags ,
 862 but the kernel was not configured with the
 863 .B CONFIG_SYSVIPC
 864 and
 865 .BR CONFIG_IPC_NS
 866 options.
 867 .TP
 868 .B EINVAL
 869 .BR CLONE_NEWNET
 870 was specified in
 871 .IR flags ,
 872 but the kernel was not configured with the
 873 .B CONFIG_NET_NS
 874 option.
 875 .TP
 876 .B EINVAL
 877 .BR CLONE_NEWPID
 878 was specified in
 879 .IR flags ,
 880 but the kernel was not configured with the
 881 .B CONFIG_PID_NS
 882 option.
 883 .TP
 884 .B EINVAL
 885 .BR CLONE_NEWUTS
 886 was specified in
 887 .IR flags ,
 888 but the kernel was not configured with the
 889 .B CONFIG_UTS
 890 option.
 891 .TP
 892 .B ENOMEM
 893 Cannot allocate sufficient memory to allocate a task structure for the
 894 child, or to copy those parts of the caller's context that need to be
 895 copied.
 896 .TP
 897 .B EPERM
 898 .BR CLONE_NEWIPC ,
 899 .BR CLONE_NEWNET ,
 900 .BR CLONE_NEWNS ,
 901 .BR CLONE_NEWPID ,
 902 or
 903 .BR CLONE_NEWUTS
 904 was specified by an unprivileged process (process without \fBCAP_SYS_ADMIN\fP).
 905 .TP
 906 .B EPERM
 907 .B CLONE_PID
 908 was specified by a process other than process 0.
 909 .SH VERSIONS
 910 There is no entry for
 911 .BR clone ()
 912 in libc5.
 913 glibc2 provides
 914 .BR clone ()
 915 as described in this manual page.
 916 .SH "CONFORMING TO"
 917 The
 918 .BR clone ()
 919 and
 920 .B sys_clone
 921 calls are Linux-specific and should not be used in programs
 922 intended to be portable.
 923 .SH NOTES
 924 In the kernel 2.4.x series,
 925 .B CLONE_THREAD
 926 generally does not make the parent of the new thread the same
 927 as the parent of the calling process.
 928 However, for kernel versions 2.4.7 to 2.4.18 the
 929 .B CLONE_THREAD
 930 flag implied the
 931 .B CLONE_PARENT
 932 flag (as in kernel 2.6).
 933
 934 For a while there was
 935 .B CLONE_DETACHED
 936 (introduced in 2.5.32):
 937 parent wants no child-exit signal.
 938 In 2.6.2 the need to give this
 939 together with
 940 .B CLONE_THREAD
 941 disappeared.
 942 This flag is still defined, but has no effect.
 943
 944 On i386,
 945 .BR clone ()
 946 should not be called through vsyscall, but directly through
 947 .IR "int $0x80" .
 948
 949 On ia64, a different system call is used:
 950 .nf
 951
 952 .BI "int __clone2(int (*" "fn" ")(void *), "
 953 .BI "             void *" child_stack_base ", size_t " stack_size ,
 954 .BI "             int " flags ", void *" "arg" ", ... "
 955 .BI "          /* pid_t *" ptid ", struct user_desc *" tls \
 956 ", pid_t *" ctid " */ );"
 957 .fi
 958 .PP
 959 The
 960 .BR __clone2 ()
 961 system call operates in the same way as
 962 .BR clone (),
 963 except that
 964 .I child_stack_base
 965 points to the lowest address of the child's stack area,
 966 and
 967 .I stack_size
 968 specifies the size of the stack pointed to by
 969 .IR child_stack_base .
 970 .SH BUGS
 971 Versions of the GNU C library that include the NPTL threading library
 972 contain a wrapper function for
 973 .BR getpid (2)
 974 that performs caching of PIDs.
 975 This caching relies on support in the glibc wrapper for
 976 .BR clone (),
 977 but as currently implemented,
 978 the cache may not be up to date in some circumstances.
 979 In particular,
 980 if a signal is delivered to the child immediately after the
 981 .BR clone ()
 982 call, then a call to
 983 .BR getpid (2)
 984 in a handler for the signal may return the PID
 985 of the calling process ("the parent"),
 986 if the clone wrapper has not yet had a chance to update the PID
 987 cache in the child.
 988 (This discussion ignores the case where the child was created using
 989 .BR CLONE_THREAD ,
 990 when
 991 .BR getpid (2)
 992 .I should
 993 return the same value in the child and in the process that called
 994 .BR clone (),
 995 since the caller and the child are in the same thread group.
 996 The stale-cache problem also does not occur if the
 997 .I flags
 998 argument includes
 999 .BR CLONE_VM .)
1000 To get the truth, it may be necessary to use code such as the following:
1001 .nf
1002
1003     #include <syscall.h>
1004
1005     pid_t mypid;
1006
1007     mypid = syscall(SYS_getpid);
1008 .fi
1009 .\" See also the following bug reports
1010 .\" https://bugzilla.redhat.com/show_bug.cgi?id=417521
1011 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910
1012 .SH "SEE ALSO"
1013 .BR fork (2),
1014 .BR futex (2),
1015 .BR getpid (2),
1016 .BR gettid (2),
1017 .BR set_thread_area (2),
1018 .BR set_tid_address (2),
1019 .BR tkill (2),
1020 .BR unshare (2),
1021 .BR wait (2),
1022 .BR capabilities (7),
1023 .BR pthreads (7)