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@gmx.net>
  23 .\"     Updated notes for 2.4.7+ behavior of CLONE_THREAD
  24 .\" Modified 15 Oct 2002 by Michael Kerrisk <mtk-manpages@gmx.net>
  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 .\"
  35 .TH CLONE 2 2007-06-01 "Linux" "Linux Programmer's Manual"
  36 .SH NAME
  37 clone \- create a child process
  38 .SH SYNOPSIS
  39 .nf
  40 .B #include <sched.h>
  41
  42 .BI "int clone(int (*" "fn" ")(void *), void *" child_stack ,
  43 .BI "          int " flags ", void *" "arg" ", ... "
  44 .BI "          /* pid_t *" pid ", struct user_desc *" tls \
  45 ", pid_t *" ctid " */ );"
  46 .fi
  47 .SH DESCRIPTION
  48 .BR clone ()
  49 creates a new process, in a manner similar to
  50 .BR fork (2).
  51 It is actually a library function layered on top of the underlying
  52 .BR clone ()
  53 system call, hereinafter referred to as
  54 .BR sys_clone .
  55 A description of
  56 .BR sys_clone
  57 is given towards the end of this page.
  58
  59 Unlike
  60 .BR fork (2),
  61 these calls
  62 allow the child process to share parts of its execution context with
  63 the calling process, such as the memory space, the table of file
  64 descriptors, and the table of signal handlers.
  65 (Note that on this manual
  66 page, "calling process" normally corresponds to "parent process".
  67 But see the description of
  68 .B CLONE_PARENT
  69 below.)
  70
  71 The main use of
  72 .BR clone ()
  73 is to implement threads: multiple threads of control in a program that
  74 run concurrently in a shared memory space.
  75
  76 When the child process is created with
  77 .BR clone (),
  78 it executes the function
  79 application
  80 .IR fn ( arg ).
  81 (This differs from
  82 .BR fork (2),
  83 where execution continues in the child from the point
  84 of the
  85 .BR fork (2)
  86 call.)
  87 The
  88 .I fn
  89 argument is a pointer to a function that is called by the child
  90 process at the beginning of its execution.
  91 The
  92 .I arg
  93 argument is passed to the
  94 .I fn
  95 function.
  96
  97 When the
  98 .IR fn ( arg )
  99 function application returns, the child process terminates.
 100 The integer returned by
 101 .I fn
 102 is the exit code for the child process.
 103 The child process may also terminate explicitly by calling
 104 .BR exit (2)
 105 or after receiving a fatal signal.
 106
 107 The
 108 .I child_stack
 109 argument specifies the location of the stack used by the child process.
 110 Since the child and calling process may share memory,
 111 it is not possible for the child process to execute in the
 112 same stack as the calling process.
 113 The calling process must therefore
 114 set up memory space for the child stack and pass a pointer to this
 115 space to
 116 .BR clone ().
 117 Stacks grow downwards on all processors that run Linux
 118 (except the HP PA processors), so
 119 .I child_stack
 120 usually points to the topmost address of the memory space set up for
 121 the child stack.
 122
 123 The low byte of
 124 .I flags
 125 contains the number of the
 126 .I "termination signal"
 127 sent to the parent when the child dies.
 128 If this signal is specified as anything other than
 129 .BR SIGCHLD ,
 130 then the parent process must specify the
 131 .B __WALL
 132 or
 133 .B __WCLONE
 134 options when waiting for the child with
 135 .BR wait (2).
 136 If no signal is specified, then the parent process is not signaled
 137 when the child terminates.
 138
 139 .I flags
 140 may also be bitwise-or'ed with zero or more of the following constants,
 141 in order to specify what is shared between the calling process
 142 and the child process:
 143 .TP
 144 .BR CLONE_PARENT " (since Linux 2.3.12)"
 145 If
 146 .B CLONE_PARENT
 147 is set, then the parent of the new child (as returned by
 148 .BR getppid (2))
 149 will be the same as that of the calling process.
 150
 151 If
 152 .B CLONE_PARENT
 153 is not set, then (as with
 154 .BR fork (2))
 155 the child's parent is the calling process.
 156
 157 Note that it is the parent process, as returned by
 158 .BR getppid (2),
 159 which is signaled when the child terminates, so that
 160 if
 161 .B CLONE_PARENT
 162 is set, then the parent of the calling process, rather than the
 163 calling process itself, will be signaled.
 164 .TP
 165 .B CLONE_FS
 166 If
 167 .B CLONE_FS
 168 is set, the caller and the child processes share the same file system
 169 information.
 170 This includes the root of the file system, the current
 171 working directory, and the umask.
 172 Any call to
 173 .BR chroot (2),
 174 .BR chdir (2),
 175 or
 176 .BR umask (2)
 177 performed by the calling process or the child process also affects the
 178 other process.
 179
 180 If
 181 .B CLONE_FS
 182 is not set, the child process works on a copy of the file system
 183 information of the calling process at the time of the
 184 .BR clone ()
 185 call.
 186 Calls to
 187 .BR chroot (2),
 188 .BR chdir (2),
 189 .BR umask (2)
 190 performed later by one of the processes do not affect the other process.
 191 .TP
 192 .B CLONE_FILES
 193 If
 194 .B CLONE_FILES
 195 is set, the calling process and the child processes share the same file
 196 descriptor table.
 197 Any file descriptor created by the calling process or by the child
 198 process is also valid in the other process.
 199 Similarly, if one of the processes closes a file descriptor,
 200 or changes its associated flags (using the
 201 .BR fcntl (2)
 202 .B F_SETFD
 203 operation), the other process is also affected.
 204
 205 If
 206 .B CLONE_FILES
 207 is not set, the child process inherits a copy of all file descriptors
 208 opened in the calling process at the time of
 209 .BR clone ().
 210 (The duplicated file descriptors in the child refer to the
 211 same open file descriptions (see
 212 .BR open (2))
 213 as the corresponding file descriptors in the calling process.)
 214 Subsequent operations that open or close file descriptors,
 215 or change file descriptor flags,
 216 performed by either the calling
 217 process or the child process do not affect the other process.
 218 .TP
 219 .BR CLONE_NEWNS " (since Linux 2.4.19)"
 220 Start the child in a new namespace.
 221
 222 Every process lives in a namespace.
 223 The
 224 .I namespace
 225 of a process is the data (the set of mounts) describing the file hierarchy
 226 as seen by that process.
 227 After a
 228 .BR fork (2)
 229 or
 230 .BR clone (2)
 231 where the
 232 .B CLONE_NEWNS
 233 flag is not set, the child lives in the same namespace as the parent.
 234 The system calls
 235 .BR mount (2)
 236 and
 237 .BR umount (2)
 238 change the namespace of the calling process, and hence affect
 239 all processes that live in the same namespace, but do not affect
 240 processes in a different namespace.
 241
 242 After a
 243 .BR clone (2)
 244 where the
 245 .B CLONE_NEWNS
 246 flag is set, the cloned child is started in a new namespace,
 247 initialized with a copy of the namespace of the parent.
 248
 249 Only a privileged process (one having the CAP_SYS_ADMIN capability)
 250 may specify the
 251 .B CLONE_NEWNS
 252 flag.
 253 It is not permitted to specify both
 254 .B CLONE_NEWNS
 255 and
 256 .B CLONE_FS
 257 in the same
 258 .BR clone ()
 259 call.
 260 .TP
 261 .B CLONE_SIGHAND
 262 If
 263 .B CLONE_SIGHAND
 264 is set, the calling process and the child processes share the same table of
 265 signal handlers.
 266 If the calling process or child process calls
 267 .BR sigaction (2)
 268 to change the behavior associated with a signal, the behavior is
 269 changed in the other process as well.
 270 However, the calling process and child
 271 processes still have distinct signal masks and sets of pending
 272 signals.
 273 So, one of them may block or unblock some signals using
 274 .BR sigprocmask (2)
 275 without affecting the other process.
 276
 277 If
 278 .B CLONE_SIGHAND
 279 is not set, the child process inherits a copy of the signal handlers
 280 of the calling process at the time
 281 .BR clone ()
 282 is called.
 283 Calls to
 284 .BR sigaction (2)
 285 performed later by one of the processes have no effect on the other
 286 process.
 287
 288 Since Linux 2.6.0-test6,
 289 .I flags
 290 must also include
 291 .B CLONE_VM
 292 if
 293 .B CLONE_SIGHAND
 294 is specified
 295 .TP
 296 .B CLONE_PTRACE
 297 If
 298 .B CLONE_PTRACE
 299 is specified, and the calling process is being traced,
 300 then trace the child also (see
 301 .BR ptrace (2)).
 302 .TP
 303 .BR CLONE_UNTRACED " (since Linux 2.5.46)"
 304 If
 305 .B CLONE_UNTRACED
 306 is specified, then a tracing process cannot force
 307 .B CLONE_PTRACE
 308 on this child process.
 309 .TP
 310 .BR CLONE_STOPPED " (since Linux 2.6.0-test2)"
 311 If
 312 .B CLONE_STOPPED
 313 is set, then the child is initially stopped (as though it was sent a
 314 .B SIGSTOP
 315 signal), and must be resumed by sending it a
 316 .B SIGCONT
 317 signal.
 318 .TP
 319 .B CLONE_VFORK
 320 If
 321 .B CLONE_VFORK
 322 is set, the execution of the calling process is suspended
 323 until the child releases its virtual memory
 324 resources via a call to
 325 .BR execve (2)
 326 or
 327 .BR _exit (2)
 328 (as with
 329 .BR vfork (2)).
 330
 331 If
 332 .B CLONE_VFORK
 333 is not set then both the calling process and the child are schedulable
 334 after the call, and an application should not rely on execution occurring
 335 in any particular order.
 336 .TP
 337 .B CLONE_VM
 338 If
 339 .B CLONE_VM
 340 is set, the calling process and the child processes run in the same memory
 341 space.
 342 In particular, memory writes performed by the calling process
 343 or by the child process are also visible in the other process.
 344 Moreover, any memory mapping or unmapping performed with
 345 .BR mmap (2)
 346 or
 347 .BR munmap (2)
 348 by the child or calling process also affects the other process.
 349
 350 If
 351 .B CLONE_VM
 352 is not set, the child process runs in a separate copy of the memory
 353 space of the calling process at the time of
 354 .BR clone ().
 355 Memory writes or file mappings/unmappings performed by one of the
 356 processes do not affect the other, as with
 357 .BR fork (2).
 358 .TP
 359 .BR CLONE_PID " (obsolete)"
 360 If
 361 .B CLONE_PID
 362 is set, the child process is created with the same process ID as
 363 the calling process.
 364 This is good for hacking the system, but otherwise
 365 of not much use.
 366 Since 2.3.21 this flag can be
 367 specified only by the system boot process (PID 0).
 368 It disappeared in Linux 2.5.16.
 369 .TP
 370 .BR CLONE_THREAD " (since Linux 2.4.0-test8)"
 371 If
 372 .B CLONE_THREAD
 373 is set, the child is placed in the same thread group as the calling process.
 374 To make the remainder of the discussion of
 375 .B CLONE_THREAD
 376 more readable, the term "thread" is used to refer to the
 377 processes within a thread group.
 378
 379 Thread groups were a feature added in Linux 2.4 to support the
 380 POSIX threads notion of a set of threads that share a single PID.
 381 Internally, this shared PID is the so-called
 382 thread group identifier (TGID) for the thread group.
 383 Since Linux 2.4, calls to
 384 .BR getpid (2)
 385 return the TGID of the caller.
 386
 387 The threads within a group can be distinguished by their (system-wide)
 388 unique thread IDs (TID).
 389 A new thread's TID is available as the function result
 390 returned to the caller of
 391 .BR clone (),
 392 and a thread can obtain
 393 its own TID using
 394 .BR gettid (2).
 395
 396 When a call is made to
 397 .BR clone ()
 398 without specifying
 399 .BR CLONE_THREAD ,
 400 then the resulting thread is placed in a new thread group
 401 whose TGID is the same as the thread's TID.
 402 This thread is the
 403 .I leader
 404 of the new thread group.
 405
 406 A new thread created with
 407 .B CLONE_THREAD
 408 has the same parent process as the caller of
 409 .BR clone ()
 410 (i.e., like
 411 .BR CLONE_PARENT ),
 412 so that calls to
 413 .BR getppid (2)
 414 return the same value for all of the threads in a thread group.
 415 When a
 416 .B CLONE_THREAD
 417 thread terminates, the thread that created it using
 418 .BR clone ()
 419 is not sent a
 420 .B SIGCHLD
 421 (or other termination) signal;
 422 nor can the status of such a thread be obtained
 423 using
 424 .BR wait (2).
 425 (The thread is said to be
 426 .IR detached .)
 427
 428 After all of the threads in a thread group terminate
 429 the parent process of the thread group is sent a
 430 .B SIGCHLD
 431 (or other termination) signal.
 432
 433 If any of the threads in a thread group performs an
 434 .BR execve (2),
 435 then all threads other than the thread group leader are terminated,
 436 and the new program is executed in the thread group leader.
 437
 438 If one of the threads in a thread group creates a child using
 439 .BR fork (2),
 440 then any thread in the group can
 441 .BR wait (2)
 442 for that child.
 443
 444 Since Linux 2.5.35,
 445 .I flags
 446 must also include
 447 .B CLONE_SIGHAND
 448 if
 449 .B CLONE_THREAD
 450 is specified.
 451
 452 Signals may be sent to a thread group as a whole (i.e., a TGID) using
 453 .BR kill (2),
 454 or to a specific thread (i.e., TID) using
 455 .BR tgkill (2).
 456
 457 Signal dispositions and actions are process-wide:
 458 if an unhandled signal is delivered to a thread, then
 459 it will affect (terminate, stop, continue, be ignored in)
 460 all members of the thread group.
 461
 462 Each thread has its own signal mask, as set by
 463 .BR sigprocmask (2),
 464 but signals can be pending either: for the whole process
 465 (i.e., deliverable to any member of the thread group),
 466 when sent with
 467 .BR kill (2);
 468 or for an individual thread, when sent with
 469 .BR tgkill (2).
 470 A call to
 471 .BR sigpending (2)
 472 returns a signal set that is the union of the signals pending for the
 473 whole process and the signals that are pending for the calling thread.
 474
 475 If
 476 .BR kill (2)
 477 is used to send a signal to a thread group,
 478 and the thread group has installed a handler for the signal, then
 479 the handler will be invoked in exactly one, arbitrarily selected
 480 member of the thread group that has not blocked the signal.
 481 If multiple threads in a group are waiting to accept the same signal using
 482 .BR sigwaitinfo (2),
 483 the kernel will arbitrarily select one of these threads
 484 to receive a signal sent using
 485 .BR kill (2).
 486 .TP
 487 .BR CLONE_SYSVSEM " (since Linux 2.5.10)"
 488 If
 489 .B CLONE_SYSVSEM
 490 is set, then the child and the calling process share
 491 a single list of System V semaphore undo values (see
 492 .BR semop (2)).
 493 If this flag is not set, then the child has a separate undo list,
 494 which is initially empty.
 495 .TP
 496 .BR CLONE_SETTLS " (since Linux 2.5.32)"
 497 The
 498 .I newtls
 499 parameter is the new TLS (Thread Local Storage) descriptor.
 500 (See
 501 .BR set_thread_area (2).)
 502 .TP
 503 .BR CLONE_PARENT_SETTID " (since Linux 2.5.49)"
 504 Store child thread ID at location
 505 .I parent_tidptr
 506 in parent and child memory.
 507 (In Linux 2.5.32-2.5.48 there was a flag CLONE_SETTID that did this.)
 508 .TP
 509 .BR CLONE_CHILD_SETTID " (since Linux 2.5.49)"
 510 Store child thread ID at location
 511 .I child_tidptr
 512 in child memory.
 513 .TP
 514 .BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)"
 515 Erase child thread ID at location
 516 .I child_tidptr
 517 in child memory when the child exits, and do a wakeup on the futex
 518 at that address.
 519 The address involved may be changed by the
 520 .BR set_tid_address (2)
 521 system call.
 522 This is used by threading libraries.
 523 .SS "sys_clone"
 524 The
 525 .B sys_clone
 526 system call corresponds more closely to
 527 .BR fork (2)
 528 in that execution in the child continues from the point of the
 529 call.
 530 Thus,
 531 .B sys_clone
 532 only requires the
 533 .I flags
 534 and
 535 .I child_stack
 536 arguments, which have the same meaning as for
 537 .BR clone ().
 538 (Note that the order of these arguments differs from
 539 .BR clone ().)
 540
 541 Another difference for
 542 .B sys_clone
 543 is that the
 544 .I child_stack
 545 argument may be zero, in which case copy-on-write semantics ensure that the
 546 child gets separate copies of stack pages when either process modifies
 547 the stack.
 548 In this case, for correct operation, the
 549 .B CLONE_VM
 550 option should not be specified.
 551
 552 Since Linux 2.5.49 the system call has five parameters.
 553 The two new parameters are
 554 .I parent_tidptr
 555 which points to the location (in parent and child memory) where
 556 the child thread ID will be written in case CLONE_PARENT_SETTID
 557 was specified, and
 558 .I child_tidptr
 559 which points to the location (in child memory) where the child thread ID
 560 will be written in case CLONE_CHILD_SETTID was specified.
 561 .SH "RETURN VALUE"
 562 .\" gettid(2) returns current->pid;
 563 .\" getpid(2) returns current->tgid;
 564 On success, the thread ID of the child process is returned
 565 in the caller's thread of execution.
 566 On failure, a \-1 will be returned
 567 in the caller's context, no child process will be created, and
 568 .I errno
 569 will be set appropriately.
 570 .SH ERRORS
 571 .TP
 572 .B EAGAIN
 573 Too many processes are already running.
 574 .TP
 575 .B EINVAL
 576 .B CLONE_SIGHAND
 577 was specified, but
 578 .B CLONE_VM
 579 was not.
 580 (Since Linux 2.6.0-test6.)
 581 .TP
 582 .B EINVAL
 583 .B CLONE_THREAD
 584 was specified, but
 585 .B CLONE_SIGHAND
 586 was not. (Since Linux 2.5.35.)
 587 .\" .TP
 588 .\" .B EINVAL
 589 .\" Precisely one of
 590 .\" .B CLONE_DETACHED
 591 .\" and
 592 .\" .B CLONE_THREAD
 593 .\" was specified. (Since Linux 2.6.0-test6.)
 594 .TP
 595 .B EINVAL
 596 Both
 597 .B CLONE_FS
 598 and
 599 .B CLONE_NEWNS
 600 were specified in
 601 .IR flags .
 602 .TP
 603 .B EINVAL
 604 Returned by
 605 .BR clone ()
 606 when a zero value is specified for
 607 .IR child_stack .
 608 .TP
 609 .B ENOMEM
 610 Cannot allocate sufficient memory to allocate a task structure for the
 611 child, or to copy those parts of the caller's context that need to be
 612 copied.
 613 .TP
 614 .B EPERM
 615 .B CLONE_NEWNS
 616 was specified by a non-root process (process without CAP_SYS_ADMIN).
 617 .TP
 618 .B EPERM
 619 .B CLONE_PID
 620 was specified by a process other than process 0.
 621 .SH VERSIONS
 622 There is no entry for
 623 .BR clone ()
 624 in libc5.
 625 glibc2 provides
 626 .BR clone ()
 627 as described in this manual page.
 628 .SH "CONFORMING TO"
 629 The
 630 .BR clone ()
 631 and
 632 .B sys_clone
 633 calls are Linux specific and should not be used in programs
 634 intended to be portable.
 635 .SH NOTES
 636 In the kernel 2.4.x series,
 637 .B CLONE_THREAD
 638 generally does not make the parent of the new thread the same
 639 as the parent of the calling process.
 640 However, for kernel versions 2.4.7 to 2.4.18 the
 641 .B CLONE_THREAD
 642 flag implied the
 643 .B CLONE_PARENT
 644 flag (as in kernel 2.6).
 645
 646 For a while there was
 647 .B CLONE_DETACHED
 648 (introduced in 2.5.32):
 649 parent wants no child-exit signal.
 650 In 2.6.2 the need to give this
 651 together with
 652 .B CLONE_THREAD
 653 disappeared.
 654 This flag is still defined, but has no effect.
 655
 656 On x86,
 657 .BR clone ()
 658 should not be called through vsyscall, but directly through
 659 .IR "int $0x80" .
 660
 661 On IA-64, a different system call is used:
 662 .nf
 663
 664 .BI "int clone2(int (*" "fn" ")(void *), "
 665 .BI "           void *" child_stack_base ", size_t " stack_size ,
 666 .BI "           int " flags ", void *" "arg" ", ... "
 667 .BI "           /* pid_t *" pid ", struct user_desc *" tls \
 668 ", pid_t *" ctid " */ );"
 669 .fi
 670 .PP
 671 The
 672 .BR clone2 ()
 673 system call operates in the same way as
 674 .BR clone (),
 675 except that
 676 .I child_stack_base
 677 points to the lowest address of the child's stack area,
 678 and
 679 .I stack_size
 680 specifies the size of the stack pointed to by
 681 .IR child_stack_base .
 682 .SH BUGS
 683 Versions of the GNU C library that include the NPTL threading library
 684 contain a wrapper function for
 685 .BR getpid (2)
 686 that performs caching of PIDs.
 687 In programs linked against such libraries, calls to
 688 .BR getpid (2)
 689 may return the same value, even when the threads were not created using
 690 .B CLONE_THREAD
 691 (and thus are not in the same thread group).
 692 To get the truth, it may be necessary to use code such as the following
 693 .nf
 694
 695     #include <syscall.h>
 696
 697     pid_t mypid;
 698
 699     mypid = syscall(SYS_getpid);
 700 .fi
 701 .SH "SEE ALSO"
 702 .BR fork (2),
 703 .BR futex (2),
 704 .BR getpid (2),
 705 .BR gettid (2),
 706 .BR set_thread_area (2),
 707 .BR set_tid_address (2),
 708 .BR tkill (2),
 709 .BR unshare (2),
 710 .BR wait (2),
 711 .BR capabilities (7),
 712 .BR pthreads (7)