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