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