man2/clone.2

   1 .\" Copyright (c) 1992 Drew Eckhardt <drew@cs.colorado.edu>, March 28, 1992
   2 .\" and Copyright (c) Michael Kerrisk, 2001, 2002, 2005, 2013
   3 .\"
   4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   5 .\" May be distributed under the GNU General Public License.
   6 .\" %%%LICENSE_END
   7 .\"
   8 .\" Modified by Michael Haardt <michael@moria.de>
   9 .\" Modified 24 Jul 1993 by Rik Faith <faith@cs.unc.edu>
  10 .\" Modified 21 Aug 1994 by Michael Chastain <mec@shell.portal.com>:
  11 .\"   New man page (copied from 'fork.2').
  12 .\" Modified 10 June 1995 by Andries Brouwer <aeb@cwi.nl>
  13 .\" Modified 25 April 1998 by Xavier Leroy <Xavier.Leroy@inria.fr>
  14 .\" Modified 26 Jun 2001 by Michael Kerrisk
  15 .\"     Mostly upgraded to 2.4.x
  16 .\"     Added prototype for sys_clone() plus description
  17 .\"     Added CLONE_THREAD with a brief description of thread groups
  18 .\"     Added CLONE_PARENT and revised entire page remove ambiguity
  19 .\"             between "calling process" and "parent process"
  20 .\"     Added CLONE_PTRACE and CLONE_VFORK
  21 .\"     Added EPERM and EINVAL error codes
  22 .\"     Renamed "__clone" to "clone" (which is the prototype in <sched.h>)
  23 .\"     various other minor tidy ups and clarifications.
  24 .\" Modified 26 Jun 2001 by Michael Kerrisk <mtk.manpages@gmail.com>
  25 .\"     Updated notes for 2.4.7+ behavior of CLONE_THREAD
  26 .\" Modified 15 Oct 2002 by Michael Kerrisk <mtk.manpages@gmail.com>
  27 .\"     Added description for CLONE_NEWNS, which was added in 2.4.19
  28 .\" Slightly rephrased, aeb.
  29 .\" Modified 1 Feb 2003 - added CLONE_SIGHAND restriction, aeb.
  30 .\" Modified 1 Jan 2004 - various updates, aeb
  31 .\" Modified 2004-09-10 - added CLONE_PARENT_SETTID etc. - aeb.
  32 .\" 2005-04-12, mtk, noted the PID caching behavior of NPTL's getpid()
  33 .\"     wrapper under BUGS.
  34 .\" 2005-05-10, mtk, added CLONE_SYSVSEM, CLONE_UNTRACED, CLONE_STOPPED.
  35 .\" 2005-05-17, mtk, Substantially enhanced discussion of CLONE_THREAD.
  36 .\" 2008-11-18, mtk, order CLONE_* flags alphabetically
  37 .\" 2008-11-18, mtk, document CLONE_NEWPID
  38 .\" 2008-11-19, mtk, document CLONE_NEWUTS
  39 .\" 2008-11-19, mtk, document CLONE_NEWIPC
  40 .\" 2008-11-19, Jens Axboe, mtk, document CLONE_IO
  41 .\"
  42 .TH CLONE 2 2016-07-17 "Linux" "Linux Programmer's Manual"
  43 .SH NAME
  44 clone, __clone2 \- create a child process
  45 .SH SYNOPSIS
  46 .nf
  47 /* Prototype for the glibc wrapper function */
  48
  49 .B #define _GNU_SOURCE
  50 .B #include <sched.h>
  51
  52 .BI "int clone(int (*" "fn" ")(void *), void *" child_stack ,
  53 .BI "          int " flags ", void *" "arg" ", ... "
  54 .BI "          /* pid_t *" ptid ", struct user_desc *" tls \
  55 ", pid_t *" ctid " */ );"
  56
  57 /* Prototype for the raw system call */
  58
  59 .BI "long clone(unsigned long " flags ", void *" child_stack ,
  60 .BI "          void *" ptid ", void *" ctid ,
  61 .BI "          struct pt_regs *" regs );
  62 .fi
  63 .SH DESCRIPTION
  64 .BR clone ()
  65 creates a new process, in a manner similar to
  66 .BR fork (2).
  67
  68 This page describes both the glibc
  69 .BR clone ()
  70 wrapper function and the underlying system call on which it is based.
  71 The main text describes the wrapper function;
  72 the differences for the raw system call
  73 are described toward the end of this page.
  74
  75 Unlike
  76 .BR fork (2),
  77 .BR clone ()
  78 allows 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 One 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 .IR fn ( arg ).
  96 (This differs from
  97 .BR fork (2),
  98 where execution continues in the child from the point
  99 of the
 100 .BR fork (2)
 101 call.)
 102 The
 103 .I fn
 104 argument is a pointer to a function that is called by the child
 105 process at the beginning of its execution.
 106 The
 107 .I arg
 108 argument is passed to the
 109 .I fn
 110 function.
 111
 112 When the
 113 .IR fn ( arg )
 114 function application returns, the child process terminates.
 115 The integer returned by
 116 .I fn
 117 is the exit code for the child process.
 118 The child process may also terminate explicitly by calling
 119 .BR exit (2)
 120 or after receiving a fatal signal.
 121
 122 The
 123 .I child_stack
 124 argument specifies the location of the stack used by the child process.
 125 Since the child and calling process may share memory,
 126 it is not possible for the child process to execute in the
 127 same stack as the calling process.
 128 The calling process must therefore
 129 set up memory space for the child stack and pass a pointer to this
 130 space to
 131 .BR clone ().
 132 Stacks grow downward on all processors that run Linux
 133 (except the HP PA processors), so
 134 .I child_stack
 135 usually points to the topmost address of the memory space set up for
 136 the child stack.
 137
 138 The low byte of
 139 .I flags
 140 contains the number of the
 141 .I "termination signal"
 142 sent to the parent when the child dies.
 143 If this signal is specified as anything other than
 144 .BR SIGCHLD ,
 145 then the parent process must specify the
 146 .B __WALL
 147 or
 148 .B __WCLONE
 149 options when waiting for the child with
 150 .BR wait (2).
 151 If no signal is specified, then the parent process is not signaled
 152 when the child terminates.
 153
 154 .I flags
 155 may also be bitwise-or'ed with zero or more of the following constants,
 156 in order to specify what is shared between the calling process
 157 and the child process:
 158 .TP
 159 .BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)"
 160 Erase the child thread ID at the location
 161 .I ctid
 162 in child memory when the child exits, and do a wakeup on the futex
 163 at that address.
 164 The address involved may be changed by the
 165 .BR set_tid_address (2)
 166 system call.
 167 This is used by threading libraries.
 168 .TP
 169 .BR CLONE_CHILD_SETTID " (since Linux 2.5.49)"
 170 Store the child thread ID at the location
 171 .I ctid
 172 in the child's memory.
 173 .TP
 174 .BR CLONE_FILES " (since Linux 2.0)"
 175 If
 176 .B CLONE_FILES
 177 is set, the calling process and the child process share the same file
 178 descriptor table.
 179 Any file descriptor created by the calling process or by the child
 180 process is also valid in the other process.
 181 Similarly, if one of the processes closes a file descriptor,
 182 or changes its associated flags (using the
 183 .BR fcntl (2)
 184 .B F_SETFD
 185 operation), the other process is also affected.
 186 If a process sharing a file descriptor table calls
 187 .BR execve (2),
 188 its file descriptor table is duplicated (unshared).
 189
 190 If
 191 .B CLONE_FILES
 192 is not set, the child process inherits a copy of all file descriptors
 193 opened in the calling process at the time of
 194 .BR clone ().
 195 Subsequent operations that open or close file descriptors,
 196 or change file descriptor flags,
 197 performed by either the calling
 198 process or the child process do not affect the other process.
 199 Note, however,
 200 that the duplicated file descriptors in the child refer to the same open file
 201 descriptions as the corresponding file descriptors in the calling process,
 202 and thus share file offsets and files status flags (see
 203 .BR open (2)).
 204 .TP
 205 .BR CLONE_FS " (since Linux 2.0)"
 206 If
 207 .B CLONE_FS
 208 is set, the caller and the child process share the same filesystem
 209 information.
 210 This includes the root of the filesystem, the current
 211 working directory, and the umask.
 212 Any call to
 213 .BR chroot (2),
 214 .BR chdir (2),
 215 or
 216 .BR umask (2)
 217 performed by the calling process or the child process also affects the
 218 other process.
 219
 220 If
 221 .B CLONE_FS
 222 is not set, the child process works on a copy of the filesystem
 223 information of the calling process at the time of the
 224 .BR clone ()
 225 call.
 226 Calls to
 227 .BR chroot (2),
 228 .BR chdir (2),
 229 .BR umask (2)
 230 performed later by one of the processes do not affect the other process.
 231 .TP
 232 .BR CLONE_IO " (since Linux 2.6.25)"
 233 If
 234 .B CLONE_IO
 235 is set, then the new process shares an I/O context with
 236 the calling process.
 237 If this flag is not set, then (as with
 238 .BR fork (2))
 239 the new process has its own I/O context.
 240
 241 .\" The following based on text from Jens Axboe
 242 The I/O context is the I/O scope of the disk scheduler (i.e.,
 243 what the I/O scheduler uses to model scheduling of a process's I/O).
 244 If processes share the same I/O context,
 245 they are treated as one by the I/O scheduler.
 246 As a consequence, they get to share disk time.
 247 For some I/O schedulers,
 248 .\" the anticipatory and CFQ scheduler
 249 if two processes share an I/O context,
 250 they will be allowed to interleave their disk access.
 251 If several threads are doing I/O on behalf of the same process
 252 .RB ( aio_read (3),
 253 for instance), they should employ
 254 .BR CLONE_IO
 255 to get better I/O performance.
 256 .\" with CFQ and AS.
 257
 258 If the kernel is not configured with the
 259 .B CONFIG_BLOCK
 260 option, this flag is a no-op.
 261 .TP
 262 .BR CLONE_NEWCGROUP " (since Linux 4.6)"
 263 Create the process in a new cgroup namespace.
 264 If this flag is not set, then (as with
 265 .BR fork (2))
 266 the process is created in the same cgroup namespaces as the calling process.
 267 This flag is intended for the implementation of containers.
 268
 269 For further information on cgroup namespaces, see
 270 .BR cgroup_namespaces (7).
 271
 272 Only a privileged process
 273 .RB ( CAP_SYS_ADMIN )
 274 can employ
 275 .BR CLONE_NEWCGROUP .
 276 .\"
 277 .TP
 278 .BR CLONE_NEWIPC " (since Linux 2.6.19)"
 279 If
 280 .B CLONE_NEWIPC
 281 is set, then create the process in a new IPC namespace.
 282 If this flag is not set, then (as with
 283 .BR fork (2)),
 284 the process is created in the same IPC namespace as
 285 the calling process.
 286 This flag is intended for the implementation of containers.
 287
 288 An IPC namespace provides an isolated view of System\ V IPC objects (see
 289 .BR svipc (7))
 290 and (since Linux 2.6.30)
 291 .\" commit 7eafd7c74c3f2e67c27621b987b28397110d643f
 292 .\" https://lwn.net/Articles/312232/
 293 POSIX message queues
 294 (see
 295 .BR mq_overview (7)).
 296 The common characteristic of these IPC mechanisms is that IPC
 297 objects are identified by mechanisms other than filesystem
 298 pathnames.
 299
 300 Objects created in an IPC namespace are visible to all other processes
 301 that are members of that namespace,
 302 but are not visible to processes in other IPC namespaces.
 303
 304 When an IPC namespace is destroyed
 305 (i.e., when the last process that is a member of the namespace terminates),
 306 all IPC objects in the namespace are automatically destroyed.
 307
 308 Only a privileged process
 309 .RB ( CAP_SYS_ADMIN )
 310 can employ
 311 .BR CLONE_NEWIPC .
 312 This flag can't be specified in conjunction with
 313 .BR CLONE_SYSVSEM .
 314
 315 For further information on IPC namespaces, see
 316 .BR namespaces (7).
 317 .TP
 318 .BR CLONE_NEWNET " (since Linux 2.6.24)"
 319 (The implementation of this flag was completed only
 320 by about kernel version 2.6.29.)
 321
 322 If
 323 .B CLONE_NEWNET
 324 is set, then create the process in a new network namespace.
 325 If this flag is not set, then (as with
 326 .BR fork (2))
 327 the process is created in the same network namespace as
 328 the calling process.
 329 This flag is intended for the implementation of containers.
 330
 331 A network namespace provides an isolated view of the networking stack
 332 (network device interfaces, IPv4 and IPv6 protocol stacks,
 333 IP routing tables, firewall rules, the
 334 .I /proc/net
 335 and
 336 .I /sys/class/net
 337 directory trees, sockets, etc.).
 338 A physical network device can live in exactly one
 339 network namespace.
 340 A virtual network device ("veth") pair provides a pipe-like abstraction
 341 .\" FIXME . Add pointer to veth(4) page when it is eventually completed
 342 that can be used to create tunnels between network namespaces,
 343 and can be used to create a bridge to a physical network device
 344 in another namespace.
 345
 346 When a network namespace is freed
 347 (i.e., when the last process in the namespace terminates),
 348 its physical network devices are moved back to the
 349 initial network namespace (not to the parent of the process).
 350 For further information on network namespaces, see
 351 .BR namespaces (7).
 352
 353 Only a privileged process
 354 .RB ( CAP_SYS_ADMIN )
 355 can employ
 356 .BR CLONE_NEWNET .
 357 .TP
 358 .BR CLONE_NEWNS " (since Linux 2.4.19)"
 359 If
 360 .B CLONE_NEWNS
 361 is set, the cloned child is started in a new mount namespace,
 362 initialized with a copy of the namespace of the parent.
 363 If
 364 .B CLONE_NEWNS
 365 is not set, the child lives in the same mount
 366 namespace as the parent.
 367
 368 Only a privileged process
 369 .RB ( CAP_SYS_ADMIN )
 370 can employ
 371 .BR CLONE_NEWNS .
 372 It is not permitted to specify both
 373 .B CLONE_NEWNS
 374 and
 375 .B CLONE_FS
 376 .\" See https://lwn.net/Articles/543273/
 377 in the same
 378 .BR clone ()
 379 call.
 380
 381 For further information on mount namespaces, see
 382 .BR namespaces (7)
 383 and
 384 .BR mount_namespaces (7).
 385 .TP
 386 .BR CLONE_NEWPID " (since Linux 2.6.24)"
 387 .\" This explanation draws a lot of details from
 388 .\" http://lwn.net/Articles/259217/
 389 .\" Authors: Pavel Emelyanov <xemul@openvz.org>
 390 .\" and Kir Kolyshkin <kir@openvz.org>
 391 .\"
 392 .\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264
 393 .\" Author: Pavel Emelyanov <xemul@openvz.org>
 394 If
 395 .B CLONE_NEWPID
 396 is set, then create the process in a new PID namespace.
 397 If this flag is not set, then (as with
 398 .BR fork (2))
 399 the process is created in the same PID namespace as
 400 the calling process.
 401 This flag is intended for the implementation of containers.
 402
 403 For further information on PID namespaces, see
 404 .BR namespaces (7)
 405 and
 406 .BR pid_namespaces (7).
 407
 408 Only a privileged process
 409 .RB ( CAP_SYS_ADMIN )
 410 can employ
 411 .BR CLONE_NEWPID .
 412 This flag can't be specified in conjunction with
 413 .BR CLONE_THREAD
 414 or
 415 .BR CLONE_PARENT .
 416 .TP
 417 .BR CLONE_NEWUSER
 418 (This flag first became meaningful for
 419 .BR clone ()
 420 in Linux 2.6.23,
 421 the current
 422 .BR clone ()
 423 semantics were merged in Linux 3.5,
 424 and the final pieces to make the user namespaces completely usable were
 425 merged in Linux 3.8.)
 426
 427 If
 428 .B CLONE_NEWUSER
 429 is set, then create the process in a new user namespace.
 430 If this flag is not set, then (as with
 431 .BR fork (2))
 432 the process is created in the same user namespace as the calling process.
 433
 434 For further information on user namespaces, see
 435 .BR namespaces (7)
 436 and
 437 .BR user_namespaces (7)
 438
 439 Before Linux 3.8, use of
 440 .BR CLONE_NEWUSER
 441 required that the caller have three capabilities:
 442 .BR CAP_SYS_ADMIN ,
 443 .BR CAP_SETUID ,
 444 and
 445 .BR CAP_SETGID .
 446 .\" Before Linux 2.6.29, it appears that only CAP_SYS_ADMIN was needed
 447 Starting with Linux 3.8,
 448 no privileges are needed to create a user namespace.
 449
 450 This flag can't be specified in conjunction with
 451 .BR CLONE_THREAD
 452 or
 453 .BR CLONE_PARENT .
 454 For security reasons,
 455 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
 456 .\" https://lwn.net/Articles/543273/
 457 .\" The fix actually went into 3.9 and into 3.8.3. However, user namespaces
 458 .\" were, for practical purposes, unusable in earlier 3.8.x because of the
 459 .\" various filesystems that didn't support userns.
 460 .BR CLONE_NEWUSER
 461 cannot be specified in conjunction with
 462 .BR CLONE_FS .
 463
 464 For further information on user namespaces, see
 465 .BR user_namespaces (7).
 466 .TP
 467 .BR CLONE_NEWUTS " (since Linux 2.6.19)"
 468 If
 469 .B CLONE_NEWUTS
 470 is set, then create the process in a new UTS namespace,
 471 whose identifiers are initialized by duplicating the identifiers
 472 from the UTS namespace of the calling process.
 473 If this flag is not set, then (as with
 474 .BR fork (2))
 475 the process is created in the same UTS namespace as
 476 the calling process.
 477 This flag is intended for the implementation of containers.
 478
 479 A UTS namespace is the set of identifiers returned by
 480 .BR uname (2);
 481 among these, the domain name and the hostname can be modified by
 482 .BR setdomainname (2)
 483 and
 484 .BR sethostname (2),
 485 respectively.
 486 Changes made to the identifiers in a UTS namespace
 487 are visible to all other processes in the same namespace,
 488 but are not visible to processes in other UTS namespaces.
 489
 490 Only a privileged process
 491 .RB ( CAP_SYS_ADMIN )
 492 can employ
 493 .BR CLONE_NEWUTS .
 494
 495 For further information on UTS namespaces, see
 496 .BR namespaces (7).
 497 .TP
 498 .BR CLONE_PARENT " (since Linux 2.3.12)"
 499 If
 500 .B CLONE_PARENT
 501 is set, then the parent of the new child (as returned by
 502 .BR getppid (2))
 503 will be the same as that of the calling process.
 504
 505 If
 506 .B CLONE_PARENT
 507 is not set, then (as with
 508 .BR fork (2))
 509 the child's parent is the calling process.
 510
 511 Note that it is the parent process, as returned by
 512 .BR getppid (2),
 513 which is signaled when the child terminates, so that
 514 if
 515 .B CLONE_PARENT
 516 is set, then the parent of the calling process, rather than the
 517 calling process itself, will be signaled.
 518 .TP
 519 .BR CLONE_PARENT_SETTID " (since Linux 2.5.49)"
 520 Store the child thread ID at the location
 521 .I ptid
 522 in the parent's memory.
 523 (In Linux 2.5.32-2.5.48 there was a flag
 524 .B CLONE_SETTID
 525 that did this.)
 526 .TP
 527 .BR CLONE_PID " (obsolete)"
 528 If
 529 .B CLONE_PID
 530 is set, the child process is created with the same process ID as
 531 the calling process.
 532 This is good for hacking the system, but otherwise
 533 of not much use.
 534 Since 2.3.21 this flag can be
 535 specified only by the system boot process (PID 0).
 536 It disappeared in Linux 2.5.16.
 537 Since then, the kernel silently ignores it without error.
 538 .TP
 539 .BR CLONE_PTRACE " (since Linux 2.2)"
 540 If
 541 .B CLONE_PTRACE
 542 is specified, and the calling process is being traced,
 543 then trace the child also (see
 544 .BR ptrace (2)).
 545 .TP
 546 .BR CLONE_SETTLS " (since Linux 2.5.32)"
 547 The
 548 .I newtls
 549 argument is the new TLS (Thread Local Storage) descriptor.
 550 (See
 551 .BR set_thread_area (2).)
 552 .TP
 553 .BR CLONE_SIGHAND " (since Linux 2.0)"
 554 If
 555 .B CLONE_SIGHAND
 556 is set, the calling process and the child process share the same table of
 557 signal handlers.
 558 If the calling process or child process calls
 559 .BR sigaction (2)
 560 to change the behavior associated with a signal, the behavior is
 561 changed in the other process as well.
 562 However, the calling process and child
 563 processes still have distinct signal masks and sets of pending
 564 signals.
 565 So, one of them may block or unblock some signals using
 566 .BR sigprocmask (2)
 567 without affecting the other process.
 568
 569 If
 570 .B CLONE_SIGHAND
 571 is not set, the child process inherits a copy of the signal handlers
 572 of the calling process at the time
 573 .BR clone ()
 574 is called.
 575 Calls to
 576 .BR sigaction (2)
 577 performed later by one of the processes have no effect on the other
 578 process.
 579
 580 Since Linux 2.6.0-test6,
 581 .I flags
 582 must also include
 583 .B CLONE_VM
 584 if
 585 .B CLONE_SIGHAND
 586 is specified
 587 .TP
 588 .BR CLONE_STOPPED " (since Linux 2.6.0-test2)"
 589 If
 590 .B CLONE_STOPPED
 591 is set, then the child is initially stopped (as though it was sent a
 592 .B SIGSTOP
 593 signal), and must be resumed by sending it a
 594 .B SIGCONT
 595 signal.
 596
 597 This flag was
 598 .I deprecated
 599 from Linux 2.6.25 onward,
 600 and was
 601 .I removed
 602 altogether in Linux 2.6.38.
 603 Since then, the kernel silently ignores it without error.
 604 .\" glibc 2.8 removed this defn from bits/sched.h
 605 Starting with Linux 4.6, the same bit was reused for the
 606 .BR CLONE_NEWCGROUP
 607 flag.
 608 .TP
 609 .BR CLONE_SYSVSEM " (since Linux 2.5.10)"
 610 If
 611 .B CLONE_SYSVSEM
 612 is set, then the child and the calling process share
 613 a single list of System V semaphore adjustment
 614 .RI ( semadj )
 615 values (see
 616 .BR semop (2)).
 617 In this case, the shared list accumulates
 618 .I semadj
 619 values across all processes sharing the list,
 620 and semaphore adjustments are performed only when the last process
 621 that is sharing the list terminates (or ceases sharing the list using
 622 .BR unshare (2)).
 623 If this flag is not set, then the child has a separate
 624 .I semadj
 625 list that is initially empty.
 626 .TP
 627 .BR CLONE_THREAD " (since Linux 2.4.0-test8)"
 628 If
 629 .B CLONE_THREAD
 630 is set, the child is placed in the same thread group as the calling process.
 631 To make the remainder of the discussion of
 632 .B CLONE_THREAD
 633 more readable, the term "thread" is used to refer to the
 634 processes within a thread group.
 635
 636 Thread groups were a feature added in Linux 2.4 to support the
 637 POSIX threads notion of a set of threads that share a single PID.
 638 Internally, this shared PID is the so-called
 639 thread group identifier (TGID) for the thread group.
 640 Since Linux 2.4, calls to
 641 .BR getpid (2)
 642 return the TGID of the caller.
 643
 644 The threads within a group can be distinguished by their (system-wide)
 645 unique thread IDs (TID).
 646 A new thread's TID is available as the function result
 647 returned to the caller of
 648 .BR clone (),
 649 and a thread can obtain
 650 its own TID using
 651 .BR gettid (2).
 652
 653 When a call is made to
 654 .BR clone ()
 655 without specifying
 656 .BR CLONE_THREAD ,
 657 then the resulting thread is placed in a new thread group
 658 whose TGID is the same as the thread's TID.
 659 This thread is the
 660 .I leader
 661 of the new thread group.
 662
 663 A new thread created with
 664 .B CLONE_THREAD
 665 has the same parent process as the caller of
 666 .BR clone ()
 667 (i.e., like
 668 .BR CLONE_PARENT ),
 669 so that calls to
 670 .BR getppid (2)
 671 return the same value for all of the threads in a thread group.
 672 When a
 673 .B CLONE_THREAD
 674 thread terminates, the thread that created it using
 675 .BR clone ()
 676 is not sent a
 677 .B SIGCHLD
 678 (or other termination) signal;
 679 nor can the status of such a thread be obtained
 680 using
 681 .BR wait (2).
 682 (The thread is said to be
 683 .IR detached .)
 684
 685 After all of the threads in a thread group terminate
 686 the parent process of the thread group is sent a
 687 .B SIGCHLD
 688 (or other termination) signal.
 689
 690 If any of the threads in a thread group performs an
 691 .BR execve (2),
 692 then all threads other than the thread group leader are terminated,
 693 and the new program is executed in the thread group leader.
 694
 695 If one of the threads in a thread group creates a child using
 696 .BR fork (2),
 697 then any thread in the group can
 698 .BR wait (2)
 699 for that child.
 700
 701 Since Linux 2.5.35,
 702 .I flags
 703 must also include
 704 .B CLONE_SIGHAND
 705 if
 706 .B CLONE_THREAD
 707 is specified
 708 (and note that, since Linux 2.6.0-test6,
 709 .BR CLONE_SIGHAND
 710 also requires
 711 .BR CLONE_VM
 712 to be included).
 713
 714 Signals may be sent to a thread group as a whole (i.e., a TGID) using
 715 .BR kill (2),
 716 or to a specific thread (i.e., TID) using
 717 .BR tgkill (2).
 718
 719 Signal dispositions and actions are process-wide:
 720 if an unhandled signal is delivered to a thread, then
 721 it will affect (terminate, stop, continue, be ignored in)
 722 all members of the thread group.
 723
 724 Each thread has its own signal mask, as set by
 725 .BR sigprocmask (2),
 726 but signals can be pending either: for the whole process
 727 (i.e., deliverable to any member of the thread group),
 728 when sent with
 729 .BR kill (2);
 730 or for an individual thread, when sent with
 731 .BR tgkill (2).
 732 A call to
 733 .BR sigpending (2)
 734 returns a signal set that is the union of the signals pending for the
 735 whole process and the signals that are pending for the calling thread.
 736
 737 If
 738 .BR kill (2)
 739 is used to send a signal to a thread group,
 740 and the thread group has installed a handler for the signal, then
 741 the handler will be invoked in exactly one, arbitrarily selected
 742 member of the thread group that has not blocked the signal.
 743 If multiple threads in a group are waiting to accept the same signal using
 744 .BR sigwaitinfo (2),
 745 the kernel will arbitrarily select one of these threads
 746 to receive a signal sent using
 747 .BR kill (2).
 748 .TP
 749 .BR CLONE_UNTRACED " (since Linux 2.5.46)"
 750 If
 751 .B CLONE_UNTRACED
 752 is specified, then a tracing process cannot force
 753 .B CLONE_PTRACE
 754 on this child process.
 755 .TP
 756 .BR CLONE_VFORK " (since Linux 2.2)"
 757 If
 758 .B CLONE_VFORK
 759 is set, the execution of the calling process is suspended
 760 until the child releases its virtual memory
 761 resources via a call to
 762 .BR execve (2)
 763 or
 764 .BR _exit (2)
 765 (as with
 766 .BR vfork (2)).
 767
 768 If
 769 .B CLONE_VFORK
 770 is not set, then both the calling process and the child are schedulable
 771 after the call, and an application should not rely on execution occurring
 772 in any particular order.
 773 .TP
 774 .BR CLONE_VM " (since Linux 2.0)"
 775 If
 776 .B CLONE_VM
 777 is set, the calling process and the child process run in the same memory
 778 space.
 779 In particular, memory writes performed by the calling process
 780 or by the child process are also visible in the other process.
 781 Moreover, any memory mapping or unmapping performed with
 782 .BR mmap (2)
 783 or
 784 .BR munmap (2)
 785 by the child or calling process also affects the other process.
 786
 787 If
 788 .B CLONE_VM
 789 is not set, the child process runs in a separate copy of the memory
 790 space of the calling process at the time of
 791 .BR clone ().
 792 Memory writes or file mappings/unmappings performed by one of the
 793 processes do not affect the other, as with
 794 .BR fork (2).
 795 .SS C library/kernel differences
 796 The raw
 797 .BR clone ()
 798 system call corresponds more closely to
 799 .BR fork (2)
 800 in that execution in the child continues from the point of the
 801 call.
 802 As such, the
 803 .I fn
 804 and
 805 .I arg
 806 arguments of the
 807 .BR clone ()
 808 wrapper function are omitted.
 809 Furthermore, the argument order changes.
 810 The raw system call interface on x86 and many other architectures is roughly:
 811 .in +4
 812 .nf
 813
 814 .BI "long clone(unsigned long " flags ", void *" child_stack ,
 815 .BI "           void *" ptid ", void *" ctid ,
 816 .BI "           struct pt_regs *" regs );
 817
 818 .fi
 819 .in
 820 Another difference for the raw system call is that the
 821 .I child_stack
 822 argument may be zero, in which case copy-on-write semantics ensure that the
 823 child gets separate copies of stack pages when either process modifies
 824 the stack.
 825 In this case, for correct operation, the
 826 .B CLONE_VM
 827 option should not be specified.
 828
 829 For some architectures, the order of the arguments for the system call
 830 differs from that shown above.
 831 On the score, microblaze, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa,
 832 and MIPS architectures,
 833 the order of the fourth and fifth arguments is reversed.
 834 On the cris and s390 architectures,
 835 the order of the first and second arguments is reversed.
 836 .SS blackfin, m68k, and sparc
 837 The argument-passing conventions on
 838 blackfin, m68k, and sparc are different from the descriptions above.
 839 For details, see the kernel (and glibc) source.
 840 .SS ia64
 841 On ia64, a different interface is used:
 842 .nf
 843
 844 .BI "int __clone2(int (*" "fn" ")(void *), "
 845 .BI "             void *" child_stack_base ", size_t " stack_size ,
 846 .BI "             int " flags ", void *" "arg" ", ... "
 847 .BI "          /* pid_t *" ptid ", struct user_desc *" tls \
 848 ", pid_t *" ctid " */ );"
 849 .fi
 850 .PP
 851 The prototype shown above is for the glibc wrapper function;
 852 the raw system call interface has no
 853 .I fn
 854 or
 855 .I arg
 856 argument, and changes the order of the arguments so that
 857 .I flags
 858 is the first argument, and
 859 .I tls
 860 is the last argument.
 861 .PP
 862 .BR __clone2 ()
 863 operates in the same way as
 864 .BR clone (),
 865 except that
 866 .I child_stack_base
 867 points to the lowest address of the child's stack area,
 868 and
 869 .I stack_size
 870 specifies the size of the stack pointed to by
 871 .IR child_stack_base .
 872 .SS Linux 2.4 and earlier
 873 In Linux 2.4 and earlier,
 874 .BR clone ()
 875 does not take arguments
 876 .IR ptid ,
 877 .IR tls ,
 878 and
 879 .IR ctid .
 880 .SH RETURN VALUE
 881 .\" gettid(2) returns current->pid;
 882 .\" getpid(2) returns current->tgid;
 883 On success, the thread ID of the child process is returned
 884 in the caller's thread of execution.
 885 On failure, \-1 is returned
 886 in the caller's context, no child process will be created, and
 887 .I errno
 888 will be set appropriately.
 889 .SH ERRORS
 890 .TP
 891 .B EAGAIN
 892 Too many processes are already running; see
 893 .BR fork (2).
 894 .TP
 895 .B EINVAL
 896 .B CLONE_SIGHAND
 897 was specified, but
 898 .B CLONE_VM
 899 was not.
 900 (Since Linux 2.6.0-test6.)
 901 .TP
 902 .B EINVAL
 903 .B CLONE_THREAD
 904 was specified, but
 905 .B CLONE_SIGHAND
 906 was not.
 907 (Since Linux 2.5.35.)
 908 .\" .TP
 909 .\" .B EINVAL
 910 .\" Precisely one of
 911 .\" .B CLONE_DETACHED
 912 .\" and
 913 .\" .B CLONE_THREAD
 914 .\" was specified.
 915 .\" (Since Linux 2.6.0-test6.)
 916 .TP
 917 .B EINVAL
 918 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
 919 Both
 920 .B CLONE_FS
 921 and
 922 .B CLONE_NEWNS
 923 were specified in
 924 .IR flags .
 925 .TP
 926 .BR EINVAL " (since Linux 3.9)"
 927 Both
 928 .B CLONE_NEWUSER
 929 and
 930 .B CLONE_FS
 931 were specified in
 932 .IR flags .
 933 .TP
 934 .B EINVAL
 935 Both
 936 .B CLONE_NEWIPC
 937 and
 938 .B CLONE_SYSVSEM
 939 were specified in
 940 .IR flags .
 941 .TP
 942 .B EINVAL
 943 One (or both) of
 944 .BR CLONE_NEWPID
 945 or
 946 .BR CLONE_NEWUSER
 947 and one (or both) of
 948 .BR CLONE_THREAD
 949 or
 950 .BR CLONE_PARENT
 951 were specified in
 952 .IR flags .
 953 .TP
 954 .B EINVAL
 955 Returned by the glibc
 956 .BR clone ()
 957 wrapper function when
 958 .IR fn
 959 or
 960 .IR child_stack
 961 is specified as NULL.
 962 .TP
 963 .B EINVAL
 964 .BR CLONE_NEWIPC
 965 was specified in
 966 .IR flags ,
 967 but the kernel was not configured with the
 968 .B CONFIG_SYSVIPC
 969 and
 970 .BR CONFIG_IPC_NS
 971 options.
 972 .TP
 973 .B EINVAL
 974 .BR CLONE_NEWNET
 975 was specified in
 976 .IR flags ,
 977 but the kernel was not configured with the
 978 .B CONFIG_NET_NS
 979 option.
 980 .TP
 981 .B EINVAL
 982 .BR CLONE_NEWPID
 983 was specified in
 984 .IR flags ,
 985 but the kernel was not configured with the
 986 .B CONFIG_PID_NS
 987 option.
 988 .TP
 989 .B EINVAL
 990 .BR CLONE_NEWUTS
 991 was specified in
 992 .IR flags ,
 993 but the kernel was not configured with the
 994 .B CONFIG_UTS
 995 option.
 996 .TP
 997 .B EINVAL
 998 .I child_stack
 999 is not aligned to a suitable boundary for this architecture.
1000 For example, on aarch64,
1001 .I child_stack
1002 must be a multiple of 16.
1003 .TP
1004 .B ENOMEM
1005 Cannot allocate sufficient memory to allocate a task structure for the
1006 child, or to copy those parts of the caller's context that need to be
1007 copied.
1008 .TP
1009 .B EPERM
1010 .BR CLONE_NEWIPC ,
1011 .BR CLONE_NEWNET ,
1012 .BR CLONE_NEWNS ,
1013 .BR CLONE_NEWPID ,
1014 or
1015 .BR CLONE_NEWUTS
1016 was specified by an unprivileged process (process without \fBCAP_SYS_ADMIN\fP).
1017 .TP
1018 .B EPERM
1019 .B CLONE_PID
1020 was specified by a process other than process 0.
1021 .TP
1022 .B EPERM
1023 .BR CLONE_NEWUSER
1024 was specified in
1025 .IR flags ,
1026 but either the effective user ID or the effective group ID of the caller
1027 does not have a mapping in the parent namespace (see
1028 .BR user_namespaces (7)).
1029 .TP
1030 .BR EPERM " (since Linux 3.9)"
1031 .\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d
1032 .B CLONE_NEWUSER
1033 was specified in
1034 .I flags
1035 and the caller is in a chroot environment
1036 .\" FIXME What is the rationale for this restriction?
1037 (i.e., the caller's root directory does not match the root directory
1038 of the mount namespace in which it resides).
1039 .TP
1040 .BR ERESTARTNOINTR " (since Linux 2.6.17)"
1041 .\" commit 4a2c7a7837da1b91468e50426066d988050e4d56
1042 System call was interrupted by a signal and will be restarted.
1043 (This can be seen only during a trace.)
1044 .TP
1045 .BR EUSERS " (since Linux 3.11)"
1046 .B CLONE_NEWUSER
1047 was specified in
1048 .IR flags ,
1049 and the call would cause the limit on the number of
1050 nested user namespaces to be exceeded.
1051 See
1052 .BR user_namespaces (7).
1053 .SH VERSIONS
1054 There is no entry for
1055 .BR clone ()
1056 in libc5.
1057 glibc2 provides
1058 .BR clone ()
1059 as described in this manual page.
1060 .SH CONFORMING TO
1061 .BR clone ()
1062 is Linux-specific and should not be used in programs
1063 intended to be portable.
1064 .SH NOTES
1065 The
1066 .BR kcmp (2)
1067 system call can be used to test whether two processes share various
1068 resources such as a file descriptor table,
1069 System V semaphore undo operations, or a virtual address space.
1070
1071 In the kernel 2.4.x series,
1072 .B CLONE_THREAD
1073 generally does not make the parent of the new thread the same
1074 as the parent of the calling process.
1075 However, for kernel versions 2.4.7 to 2.4.18 the
1076 .B CLONE_THREAD
1077 flag implied the
1078 .B CLONE_PARENT
1079 flag (as in kernel 2.6).
1080
1081 For a while there was
1082 .B CLONE_DETACHED
1083 (introduced in 2.5.32):
1084 parent wants no child-exit signal.
1085 In Linux 2.6.2, the need to give this flag ogether with
1086 .B CLONE_THREAD
1087 disappeared.
1088 This flag is still defined, but has no effect.
1089
1090 On i386,
1091 .BR clone ()
1092 should not be called through vsyscall, but directly through
1093 .IR "int $0x80" .
1094 .SH BUGS
1095 Versions of the GNU C library that include the NPTL threading library
1096 contain a wrapper function for
1097 .BR getpid (2)
1098 that performs caching of PIDs.
1099 This caching relies on support in the glibc wrapper for
1100 .BR clone (),
1101 but as currently implemented,
1102 the cache may not be up to date in some circumstances.
1103 In particular,
1104 if a signal is delivered to the child immediately after the
1105 .BR clone ()
1106 call, then a call to
1107 .BR getpid (2)
1108 in a handler for the signal may return the PID
1109 of the calling process ("the parent"),
1110 if the clone wrapper has not yet had a chance to update the PID
1111 cache in the child.
1112 (This discussion ignores the case where the child was created using
1113 .BR CLONE_THREAD ,
1114 when
1115 .BR getpid (2)
1116 .I should
1117 return the same value in the child and in the process that called
1118 .BR clone (),
1119 since the caller and the child are in the same thread group.
1120 The stale-cache problem also does not occur if the
1121 .I flags
1122 argument includes
1123 .BR CLONE_VM .)
1124 To get the truth, it may be necessary to use code such as the following:
1125 .nf
1126
1127     #include <syscall.h>
1128
1129     pid_t mypid;
1130
1131     mypid = syscall(SYS_getpid);
1132 .fi
1133 .\" See also the following bug reports
1134 .\" https://bugzilla.redhat.com/show_bug.cgi?id=417521
1135 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910
1136 .SH EXAMPLE
1137 The following program demonstrates the use of
1138 .BR clone ()
1139 to create a child process that executes in a separate UTS namespace.
1140 The child changes the hostname in its UTS namespace.
1141 Both parent and child then display the system hostname,
1142 making it possible to see that the hostname
1143 differs in the UTS namespaces of the parent and child.
1144 For an example of the use of this program, see
1145 .BR setns (2).
1146 .SS Program source
1147 .nf
1148 #define _GNU_SOURCE
1149 #include <sys/wait.h>
1150 #include <sys/utsname.h>
1151 #include <sched.h>
1152 #include <string.h>
1153 #include <stdio.h>
1154 #include <stdlib.h>
1155 #include <unistd.h>
1156
1157 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \\
1158                         } while (0)
1159
1160 static int              /* Start function for cloned child */
1161 childFunc(void *arg)
1162 {
1163     struct utsname uts;
1164
1165     /* Change hostname in UTS namespace of child */
1166
1167     if (sethostname(arg, strlen(arg)) == \-1)
1168         errExit("sethostname");
1169
1170     /* Retrieve and display hostname */
1171
1172     if (uname(&uts) == \-1)
1173         errExit("uname");
1174     printf("uts.nodename in child:  %s\\n", uts.nodename);
1175
1176     /* Keep the namespace open for a while, by sleeping.
1177        This allows some experimentation\-\-for example, another
1178        process might join the namespace. */
1179
1180     sleep(200);
1181
1182     return 0;           /* Child terminates now */
1183 }
1184
1185 #define STACK_SIZE (1024 * 1024)    /* Stack size for cloned child */
1186
1187 int
1188 main(int argc, char *argv[])
1189 {
1190     char *stack;                    /* Start of stack buffer */
1191     char *stackTop;                 /* End of stack buffer */
1192     pid_t pid;
1193     struct utsname uts;
1194
1195     if (argc < 2) {
1196         fprintf(stderr, "Usage: %s <child\-hostname>\\n", argv[0]);
1197         exit(EXIT_SUCCESS);
1198     }
1199
1200     /* Allocate stack for child */
1201
1202     stack = malloc(STACK_SIZE);
1203     if (stack == NULL)
1204         errExit("malloc");
1205     stackTop = stack + STACK_SIZE;  /* Assume stack grows downward */
1206
1207     /* Create child that has its own UTS namespace;
1208        child commences execution in childFunc() */
1209
1210     pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]);
1211     if (pid == \-1)
1212         errExit("clone");
1213     printf("clone() returned %ld\\n", (long) pid);
1214
1215     /* Parent falls through to here */
1216
1217     sleep(1);           /* Give child time to change its hostname */
1218
1219     /* Display hostname in parent\(aqs UTS namespace. This will be
1220        different from hostname in child\(aqs UTS namespace. */
1221
1222     if (uname(&uts) == \-1)
1223         errExit("uname");
1224     printf("uts.nodename in parent: %s\\n", uts.nodename);
1225
1226     if (waitpid(pid, NULL, 0) == \-1)    /* Wait for child */
1227         errExit("waitpid");
1228     printf("child has terminated\\n");
1229
1230     exit(EXIT_SUCCESS);
1231 }
1232 .fi
1233 .SH SEE ALSO
1234 .BR fork (2),
1235 .BR futex (2),
1236 .BR getpid (2),
1237 .BR gettid (2),
1238 .BR kcmp (2),
1239 .BR set_thread_area (2),
1240 .BR set_tid_address (2),
1241 .BR setns (2),
1242 .BR tkill (2),
1243 .BR unshare (2),
1244 .BR wait (2),
1245 .BR capabilities (7),
1246 .BR namespaces (7),
1247 .BR pthreads (7)