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 (The implementation of this flag was only completed
 290 by about kernel version 2.6.29.)
 291
 292 If
 293 .B CLONE_NEWNET
 294 is set, then create the process in a new network namespace.
 295 If this flag is not set, then (as with
 296 .BR fork (2)),
 297 the process is created in the same network namespace as
 298 the calling process.
 299 This flag is intended for the implementation of containers.
 300
 301 A network namespace provides an isolated view of the networking stack
 302 (network device interfaces, IPv4 and IPv6 protocol stacks,
 303 IP routing tables, firewall rules, the
 304 .I /proc/net
 305 and
 306 .I /sys/class/net
 307 directory trees, sockets, etc.).
 308 A physical network device can live in exactly one
 309 network namespace.
 310 A virtual network device ("veth") pair provides a pipe-like abstraction
 311 that can be used to create tunnels between network namespaces,
 312 and can be used to create a bridge to a physical network device
 313 in another namespace.
 314
 315 When a network namespace is freed
 316 (i.e., when the last process in the namespace terminates),
 317 its physical network devices are moved back to the
 318 initial network namespace (not to the parent of the process).
 319
 320 Use of this flag requires: a kernel configured with the
 321 .B CONFIG_NET_NS
 322 option and that the process be privileged
 323 .RB ( CAP_SYS_ADMIN ).
 324 .TP
 325 .BR CLONE_NEWNS " (since Linux 2.4.19)"
 326 Start the child in a new mount namespace.
 327
 328 Every process lives in a mount namespace.
 329 The
 330 .I namespace
 331 of a process is the data (the set of mounts) describing the file hierarchy
 332 as seen by that process.
 333 After a
 334 .BR fork (2)
 335 or
 336 .BR clone ()
 337 where the
 338 .B CLONE_NEWNS
 339 flag is not set, the child lives in the same mount
 340 namespace as the parent.
 341 The system calls
 342 .BR mount (2)
 343 and
 344 .BR umount (2)
 345 change the mount namespace of the calling process, and hence affect
 346 all processes that live in the same namespace, but do not affect
 347 processes in a different mount namespace.
 348
 349 After a
 350 .BR clone ()
 351 where the
 352 .B CLONE_NEWNS
 353 flag is set, the cloned child is started in a new mount namespace,
 354 initialized with a copy of the namespace of the parent.
 355
 356 Only a privileged process (one having the \fBCAP_SYS_ADMIN\fP capability)
 357 may specify the
 358 .B CLONE_NEWNS
 359 flag.
 360 It is not permitted to specify both
 361 .B CLONE_NEWNS
 362 and
 363 .B CLONE_FS
 364 in the same
 365 .BR clone ()
 366 call.
 367 .TP
 368 .BR CLONE_NEWPID " (since Linux 2.6.24)"
 369 .\" This explanation draws a lot of details from
 370 .\" http://lwn.net/Articles/259217/
 371 .\" Authors: Pavel Emelyanov <xemul@openvz.org>
 372 .\" and Kir Kolyshkin <kir@openvz.org>
 373 .\"
 374 .\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264
 375 .\" Author: Pavel Emelyanov <xemul@openvz.org>
 376 If
 377 .B CLONE_NEWPID
 378 is set, then create the process in a new PID namespace.
 379 If this flag is not set, then (as with
 380 .BR fork (2)),
 381 the process is created in the same PID namespace as
 382 the calling process.
 383 This flag is intended for the implementation of containers.
 384
 385 A PID namespace provides an isolated environment for PIDs:
 386 PIDs in a new namespace start at 1,
 387 somewhat like a standalone system, and calls to
 388 .BR fork (2),
 389 .BR vfork (2),
 390 or
 391 .BR clone ()
 392 will produce processes with PIDs that are unique within the namespace.
 393
 394 The first process created in a new namespace
 395 (i.e., the process created using the
 396 .BR CLONE_NEWPID
 397 flag) has the PID 1, and is the "init" process for the namespace.
 398 Children that are orphaned within the namespace will be reparented
 399 to this process rather than
 400 .BR init (8).
 401 Unlike the traditional
 402 .B init
 403 process, the "init" process of a PID namespace can terminate,
 404 and if it does, all of the processes in the namespace are terminated.
 405
 406 PID namespaces form a hierarchy.
 407 When a new PID namespace is created,
 408 the processes in that namespace are visible
 409 in the PID namespace of the process that created the new namespace;
 410 analogously, if the parent PID namespace is itself
 411 the child of another PID namespace,
 412 then processes in the child and parent PID namespaces will both be
 413 visible in the grandparent PID namespace.
 414 Conversely, the processes in the "child" PID namespace do not see
 415 the processes in the parent namespace.
 416 The existence of a namespace hierarchy means that each process
 417 may now have multiple PIDs:
 418 one for each namespace in which it is visible;
 419 each of these PIDs is unique within the corresponding namespace.
 420 (A call to
 421 .BR getpid (2)
 422 always returns the PID associated with the namespace in which
 423 the process lives.)
 424
 425 After creating the new namespace,
 426 it is useful for the child to change its root directory
 427 and mount a new procfs instance at
 428 .I /proc
 429 so that tools such as
 430 .BR ps (1)
 431 work correctly.
 432 .\" mount -t proc proc /proc
 433 (If
 434 .BR CLONE_NEWNS
 435 is also included in
 436 .IR flags ,
 437 then it isn't necessary to change the root directory:
 438 a new procfs instance can be mounted directly over
 439 .IR /proc .)
 440
 441 Use of this flag requires: a kernel configured with the
 442 .B CONFIG_PID_NS
 443 option and that the process be privileged
 444 .RB ( CAP_SYS_ADMIN ).
 445 This flag can't be specified in conjunction with
 446 .BR CLONE_THREAD .
 447 .TP
 448 .BR CLONE_NEWUTS " (since Linux 2.6.19)"
 449 If
 450 .B CLONE_NEWUTS
 451 is set, then create the process in a new UTS namespace,
 452 whose identifiers are initialized by duplicating the identifiers
 453 from the UTS namespace of the calling process.
 454 If this flag is not set, then (as with
 455 .BR fork (2)),
 456 the process is created in the same UTS namespace as
 457 the calling process.
 458 This flag is intended for the implementation of containers.
 459
 460 A UTS namespace is the set of identifiers returned by
 461 .BR uname (2);
 462 among these, the domain name and the host name can be modified by
 463 .BR setdomainname (2)
 464 and
 465 .BR
 466 .BR sethostname (2),
 467 respectively.
 468 Changes made to the identifiers in a UTS namespace
 469 are visible to all other processes in the same namespace,
 470 but are not visible to processes in other UTS namespaces.
 471
 472 Use of this flag requires: a kernel configured with the
 473 .B CONFIG_UTS_NS
 474 option and that the process be privileged
 475 .RB ( CAP_SYS_ADMIN ).
 476 .TP
 477 .BR CLONE_PARENT " (since Linux 2.3.12)"
 478 If
 479 .B CLONE_PARENT
 480 is set, then the parent of the new child (as returned by
 481 .BR getppid (2))
 482 will be the same as that of the calling process.
 483
 484 If
 485 .B CLONE_PARENT
 486 is not set, then (as with
 487 .BR fork (2))
 488 the child's parent is the calling process.
 489
 490 Note that it is the parent process, as returned by
 491 .BR getppid (2),
 492 which is signaled when the child terminates, so that
 493 if
 494 .B CLONE_PARENT
 495 is set, then the parent of the calling process, rather than the
 496 calling process itself, will be signaled.
 497 .TP
 498 .BR CLONE_PARENT_SETTID " (since Linux 2.5.49)"
 499 Store child thread ID at location
 500 .I ptid
 501 in parent and child memory.
 502 (In Linux 2.5.32-2.5.48 there was a flag
 503 .B CLONE_SETTID
 504 that did this.)
 505 .TP
 506 .BR CLONE_PID " (obsolete)"
 507 If
 508 .B CLONE_PID
 509 is set, the child process is created with the same process ID as
 510 the calling process.
 511 This is good for hacking the system, but otherwise
 512 of not much use.
 513 Since 2.3.21 this flag can be
 514 specified only by the system boot process (PID 0).
 515 It disappeared in Linux 2.5.16.
 516 .TP
 517 .B CLONE_PTRACE
 518 If
 519 .B CLONE_PTRACE
 520 is specified, and the calling process is being traced,
 521 then trace the child also (see
 522 .BR ptrace (2)).
 523 .TP
 524 .BR CLONE_SETTLS " (since Linux 2.5.32)"
 525 The
 526 .I newtls
 527 argument is the new TLS (Thread Local Storage) descriptor.
 528 (See
 529 .BR set_thread_area (2).)
 530 .TP
 531 .B CLONE_SIGHAND
 532 If
 533 .B CLONE_SIGHAND
 534 is set, the calling process and the child process share the same table of
 535 signal handlers.
 536 If the calling process or child process calls
 537 .BR sigaction (2)
 538 to change the behavior associated with a signal, the behavior is
 539 changed in the other process as well.
 540 However, the calling process and child
 541 processes still have distinct signal masks and sets of pending
 542 signals.
 543 So, one of them may block or unblock some signals using
 544 .BR sigprocmask (2)
 545 without affecting the other process.
 546
 547 If
 548 .B CLONE_SIGHAND
 549 is not set, the child process inherits a copy of the signal handlers
 550 of the calling process at the time
 551 .BR clone ()
 552 is called.
 553 Calls to
 554 .BR sigaction (2)
 555 performed later by one of the processes have no effect on the other
 556 process.
 557
 558 Since Linux 2.6.0-test6,
 559 .I flags
 560 must also include
 561 .B CLONE_VM
 562 if
 563 .B CLONE_SIGHAND
 564 is specified
 565 .TP
 566 .BR CLONE_STOPPED " (since Linux 2.6.0-test2)"
 567 If
 568 .B CLONE_STOPPED
 569 is set, then the child is initially stopped (as though it was sent a
 570 .B SIGSTOP
 571 signal), and must be resumed by sending it a
 572 .B SIGCONT
 573 signal.
 574
 575 This flag was
 576 .I deprecated
 577 from Linux 2.6.25 onward,
 578 and was
 579 .I removed
 580 altogether in Linux 2.6.38.
 581 .\" glibc 2.8 removed this defn from bits/sched.h
 582 .TP
 583 .BR CLONE_SYSVSEM " (since Linux 2.5.10)"
 584 If
 585 .B CLONE_SYSVSEM
 586 is set, then the child and the calling process share
 587 a single list of System V semaphore undo values (see
 588 .BR semop (2)).
 589 If this flag is not set, then the child has a separate undo list,
 590 which is initially empty.
 591 .TP
 592 .BR CLONE_THREAD " (since Linux 2.4.0-test8)"
 593 If
 594 .B CLONE_THREAD
 595 is set, the child is placed in the same thread group as the calling process.
 596 To make the remainder of the discussion of
 597 .B CLONE_THREAD
 598 more readable, the term "thread" is used to refer to the
 599 processes within a thread group.
 600
 601 Thread groups were a feature added in Linux 2.4 to support the
 602 POSIX threads notion of a set of threads that share a single PID.
 603 Internally, this shared PID is the so-called
 604 thread group identifier (TGID) for the thread group.
 605 Since Linux 2.4, calls to
 606 .BR getpid (2)
 607 return the TGID of the caller.
 608
 609 The threads within a group can be distinguished by their (system-wide)
 610 unique thread IDs (TID).
 611 A new thread's TID is available as the function result
 612 returned to the caller of
 613 .BR clone (),
 614 and a thread can obtain
 615 its own TID using
 616 .BR gettid (2).
 617
 618 When a call is made to
 619 .BR clone ()
 620 without specifying
 621 .BR CLONE_THREAD ,
 622 then the resulting thread is placed in a new thread group
 623 whose TGID is the same as the thread's TID.
 624 This thread is the
 625 .I leader
 626 of the new thread group.
 627
 628 A new thread created with
 629 .B CLONE_THREAD
 630 has the same parent process as the caller of
 631 .BR clone ()
 632 (i.e., like
 633 .BR CLONE_PARENT ),
 634 so that calls to
 635 .BR getppid (2)
 636 return the same value for all of the threads in a thread group.
 637 When a
 638 .B CLONE_THREAD
 639 thread terminates, the thread that created it using
 640 .BR clone ()
 641 is not sent a
 642 .B SIGCHLD
 643 (or other termination) signal;
 644 nor can the status of such a thread be obtained
 645 using
 646 .BR wait (2).
 647 (The thread is said to be
 648 .IR detached .)
 649
 650 After all of the threads in a thread group terminate
 651 the parent process of the thread group is sent a
 652 .B SIGCHLD
 653 (or other termination) signal.
 654
 655 If any of the threads in a thread group performs an
 656 .BR execve (2),
 657 then all threads other than the thread group leader are terminated,
 658 and the new program is executed in the thread group leader.
 659
 660 If one of the threads in a thread group creates a child using
 661 .BR fork (2),
 662 then any thread in the group can
 663 .BR wait (2)
 664 for that child.
 665
 666 Since Linux 2.5.35,
 667 .I flags
 668 must also include
 669 .B CLONE_SIGHAND
 670 if
 671 .B CLONE_THREAD
 672 is specified.
 673
 674 Signals may be sent to a thread group as a whole (i.e., a TGID) using
 675 .BR kill (2),
 676 or to a specific thread (i.e., TID) using
 677 .BR tgkill (2).
 678
 679 Signal dispositions and actions are process-wide:
 680 if an unhandled signal is delivered to a thread, then
 681 it will affect (terminate, stop, continue, be ignored in)
 682 all members of the thread group.
 683
 684 Each thread has its own signal mask, as set by
 685 .BR sigprocmask (2),
 686 but signals can be pending either: for the whole process
 687 (i.e., deliverable to any member of the thread group),
 688 when sent with
 689 .BR kill (2);
 690 or for an individual thread, when sent with
 691 .BR tgkill (2).
 692 A call to
 693 .BR sigpending (2)
 694 returns a signal set that is the union of the signals pending for the
 695 whole process and the signals that are pending for the calling thread.
 696
 697 If
 698 .BR kill (2)
 699 is used to send a signal to a thread group,
 700 and the thread group has installed a handler for the signal, then
 701 the handler will be invoked in exactly one, arbitrarily selected
 702 member of the thread group that has not blocked the signal.
 703 If multiple threads in a group are waiting to accept the same signal using
 704 .BR sigwaitinfo (2),
 705 the kernel will arbitrarily select one of these threads
 706 to receive a signal sent using
 707 .BR kill (2).
 708 .TP
 709 .BR CLONE_UNTRACED " (since Linux 2.5.46)"
 710 If
 711 .B CLONE_UNTRACED
 712 is specified, then a tracing process cannot force
 713 .B CLONE_PTRACE
 714 on this child process.
 715 .TP
 716 .B CLONE_VFORK
 717 If
 718 .B CLONE_VFORK
 719 is set, the execution of the calling process is suspended
 720 until the child releases its virtual memory
 721 resources via a call to
 722 .BR execve (2)
 723 or
 724 .BR _exit (2)
 725 (as with
 726 .BR vfork (2)).
 727
 728 If
 729 .B CLONE_VFORK
 730 is not set then both the calling process and the child are schedulable
 731 after the call, and an application should not rely on execution occurring
 732 in any particular order.
 733 .TP
 734 .B CLONE_VM
 735 If
 736 .B CLONE_VM
 737 is set, the calling process and the child process run in the same memory
 738 space.
 739 In particular, memory writes performed by the calling process
 740 or by the child process are also visible in the other process.
 741 Moreover, any memory mapping or unmapping performed with
 742 .BR mmap (2)
 743 or
 744 .BR munmap (2)
 745 by the child or calling process also affects the other process.
 746
 747 If
 748 .B CLONE_VM
 749 is not set, the child process runs in a separate copy of the memory
 750 space of the calling process at the time of
 751 .BR clone ().
 752 Memory writes or file mappings/unmappings performed by one of the
 753 processes do not affect the other, as with
 754 .BR fork (2).
 755 .SS "sys_clone"
 756 The
 757 .B sys_clone
 758 system call corresponds more closely to
 759 .BR fork (2)
 760 in that execution in the child continues from the point of the
 761 call.
 762 Thus,
 763 .B sys_clone
 764 only requires the
 765 .I flags
 766 and
 767 .I child_stack
 768 arguments, which have the same meaning as for
 769 .BR clone ().
 770 (Note that the order of these arguments differs from
 771 .BR clone ().)
 772
 773 Another difference for
 774 .B sys_clone
 775 is that the
 776 .I child_stack
 777 argument may be zero, in which case copy-on-write semantics ensure that the
 778 child gets separate copies of stack pages when either process modifies
 779 the stack.
 780 In this case, for correct operation, the
 781 .B CLONE_VM
 782 option should not be specified.
 783
 784 In Linux 2.4 and earlier,
 785 .BR clone ()
 786 does not take arguments
 787 .IR ptid ,
 788 .IR tls ,
 789 and
 790 .IR ctid .
 791 .SH "RETURN VALUE"
 792 .\" gettid(2) returns current->pid;
 793 .\" getpid(2) returns current->tgid;
 794 On success, the thread ID of the child process is returned
 795 in the caller's thread of execution.
 796 On failure, \-1 is returned
 797 in the caller's context, no child process will be created, and
 798 .I errno
 799 will be set appropriately.
 800 .SH ERRORS
 801 .TP
 802 .B EAGAIN
 803 Too many processes are already running.
 804 .TP
 805 .B EINVAL
 806 .B CLONE_SIGHAND
 807 was specified, but
 808 .B CLONE_VM
 809 was not.
 810 (Since Linux 2.6.0-test6.)
 811 .TP
 812 .B EINVAL
 813 .B CLONE_THREAD
 814 was specified, but
 815 .B CLONE_SIGHAND
 816 was not.
 817 (Since Linux 2.5.35.)
 818 .\" .TP
 819 .\" .B EINVAL
 820 .\" Precisely one of
 821 .\" .B CLONE_DETACHED
 822 .\" and
 823 .\" .B CLONE_THREAD
 824 .\" was specified.
 825 .\" (Since Linux 2.6.0-test6.)
 826 .TP
 827 .B EINVAL
 828 Both
 829 .B CLONE_FS
 830 and
 831 .B CLONE_NEWNS
 832 were specified in
 833 .IR flags .
 834 .TP
 835 .B EINVAL
 836 Both
 837 .B CLONE_NEWIPC
 838 and
 839 .B CLONE_SYSVSEM
 840 were specified in
 841 .IR flags .
 842 .TP
 843 .B EINVAL
 844 Both
 845 .BR CLONE_NEWPID
 846 and
 847 .BR CLONE_THREAD
 848 were specified in
 849 .IR flags .
 850 .TP
 851 .B EINVAL
 852 Returned by
 853 .BR clone ()
 854 when a zero value is specified for
 855 .IR child_stack .
 856 .TP
 857 .B EINVAL
 858 .BR CLONE_NEWIPC
 859 was specified in
 860 .IR flags ,
 861 but the kernel was not configured with the
 862 .B CONFIG_SYSVIPC
 863 and
 864 .BR CONFIG_IPC_NS
 865 options.
 866 .TP
 867 .B EINVAL
 868 .BR CLONE_NEWNET
 869 was specified in
 870 .IR flags ,
 871 but the kernel was not configured with the
 872 .B CONFIG_NET_NS
 873 option.
 874 .TP
 875 .B EINVAL
 876 .BR CLONE_NEWPID
 877 was specified in
 878 .IR flags ,
 879 but the kernel was not configured with the
 880 .B CONFIG_PID_NS
 881 option.
 882 .TP
 883 .B EINVAL
 884 .BR CLONE_NEWUTS
 885 was specified in
 886 .IR flags ,
 887 but the kernel was not configured with the
 888 .B CONFIG_UTS
 889 option.
 890 .TP
 891 .B ENOMEM
 892 Cannot allocate sufficient memory to allocate a task structure for the
 893 child, or to copy those parts of the caller's context that need to be
 894 copied.
 895 .TP
 896 .B EPERM
 897 .BR CLONE_NEWIPC ,
 898 .BR CLONE_NEWNET ,
 899 .BR CLONE_NEWNS ,
 900 .BR CLONE_NEWPID ,
 901 or
 902 .BR CLONE_NEWUTS
 903 was specified by an unprivileged process (process without \fBCAP_SYS_ADMIN\fP).
 904 .TP
 905 .B EPERM
 906 .B CLONE_PID
 907 was specified by a process other than process 0.
 908 .SH VERSIONS
 909 There is no entry for
 910 .BR clone ()
 911 in libc5.
 912 glibc2 provides
 913 .BR clone ()
 914 as described in this manual page.
 915 .SH "CONFORMING TO"
 916 The
 917 .BR clone ()
 918 and
 919 .B sys_clone
 920 calls are Linux-specific and should not be used in programs
 921 intended to be portable.
 922 .SH NOTES
 923 In the kernel 2.4.x series,
 924 .B CLONE_THREAD
 925 generally does not make the parent of the new thread the same
 926 as the parent of the calling process.
 927 However, for kernel versions 2.4.7 to 2.4.18 the
 928 .B CLONE_THREAD
 929 flag implied the
 930 .B CLONE_PARENT
 931 flag (as in kernel 2.6).
 932
 933 For a while there was
 934 .B CLONE_DETACHED
 935 (introduced in 2.5.32):
 936 parent wants no child-exit signal.
 937 In 2.6.2 the need to give this
 938 together with
 939 .B CLONE_THREAD
 940 disappeared.
 941 This flag is still defined, but has no effect.
 942
 943 On i386,
 944 .BR clone ()
 945 should not be called through vsyscall, but directly through
 946 .IR "int $0x80" .
 947
 948 On ia64, a different system call is used:
 949 .nf
 950
 951 .BI "int __clone2(int (*" "fn" ")(void *), "
 952 .BI "             void *" child_stack_base ", size_t " stack_size ,
 953 .BI "             int " flags ", void *" "arg" ", ... "
 954 .BI "          /* pid_t *" ptid ", struct user_desc *" tls \
 955 ", pid_t *" ctid " */ );"
 956 .fi
 957 .PP
 958 The
 959 .BR __clone2 ()
 960 system call operates in the same way as
 961 .BR clone (),
 962 except that
 963 .I child_stack_base
 964 points to the lowest address of the child's stack area,
 965 and
 966 .I stack_size
 967 specifies the size of the stack pointed to by
 968 .IR child_stack_base .
 969 .SH BUGS
 970 Versions of the GNU C library that include the NPTL threading library
 971 contain a wrapper function for
 972 .BR getpid (2)
 973 that performs caching of PIDs.
 974 This caching relies on support in the glibc wrapper for
 975 .BR clone (),
 976 but as currently implemented,
 977 the cache may not be up to date in some circumstances.
 978 In particular,
 979 if a signal is delivered to the child immediately after the
 980 .BR clone ()
 981 call, then a call to
 982 .BR getpid (2)
 983 in a handler for the signal may return the PID
 984 of the calling process ("the parent"),
 985 if the clone wrapper has not yet had a chance to update the PID
 986 cache in the child.
 987 (This discussion ignores the case where the child was created using
 988 .BR CLONE_THREAD ,
 989 when
 990 .BR getpid (2)
 991 .I should
 992 return the same value in the child and in the process that called
 993 .BR clone (),
 994 since the caller and the child are in the same thread group.
 995 The stale-cache problem also does not occur if the
 996 .I flags
 997 argument includes
 998 .BR CLONE_VM .)
 999 To get the truth, it may be necessary to use code such as the following:
1000 .nf
1001
1002     #include <syscall.h>
1003
1004     pid_t mypid;
1005
1006     mypid = syscall(SYS_getpid);
1007 .fi
1008 .\" See also the following bug reports
1009 .\" https://bugzilla.redhat.com/show_bug.cgi?id=417521
1010 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910
1011 .SH "SEE ALSO"
1012 .BR fork (2),
1013 .BR futex (2),
1014 .BR getpid (2),
1015 .BR gettid (2),
1016 .BR set_thread_area (2),
1017 .BR set_tid_address (2),
1018 .BR tkill (2),
1019 .BR unshare (2),
1020 .BR wait (2),
1021 .BR capabilities (7),
1022 .BR pthreads (7)