diff options
Diffstat (limited to 'man2/clone.2')
| -rw-r--r-- | man2/clone.2 | 1944 |
1 files changed, 0 insertions, 1944 deletions
diff --git a/man2/clone.2 b/man2/clone.2 deleted file mode 100644 index 4c5b4ac6b..000000000 --- a/man2/clone.2 +++ /dev/null @@ -1,1944 +0,0 @@ -'\" t -.\" Copyright (c) 1992 Drew Eckhardt <drew@cs.colorado.edu>, March 28, 1992 -.\" and Copyright (c) Michael Kerrisk, 2001, 2002, 2005, 2013, 2019 -.\" -.\" SPDX-License-Identifier: GPL-1.0-or-later -.\" -.\" Modified by Michael Haardt <michael@moria.de> -.\" Modified 24 Jul 1993 by Rik Faith <faith@cs.unc.edu> -.\" Modified 21 Aug 1994 by Michael Chastain <mec@shell.portal.com>: -.\" New man page (copied from 'fork.2'). -.\" Modified 10 June 1995 by Andries Brouwer <aeb@cwi.nl> -.\" Modified 25 April 1998 by Xavier Leroy <Xavier.Leroy@inria.fr> -.\" Modified 26 Jun 2001 by Michael Kerrisk -.\" Mostly upgraded to Linux 2.4.x -.\" Added prototype for sys_clone() plus description -.\" Added CLONE_THREAD with a brief description of thread groups -.\" Added CLONE_PARENT and revised entire page remove ambiguity -.\" between "calling process" and "parent process" -.\" Added CLONE_PTRACE and CLONE_VFORK -.\" Added EPERM and EINVAL error codes -.\" Renamed "__clone" to "clone" (which is the prototype in <sched.h>) -.\" various other minor tidy ups and clarifications. -.\" Modified 26 Jun 2001 by Michael Kerrisk <mtk.manpages@gmail.com> -.\" Updated notes for 2.4.7+ behavior of CLONE_THREAD -.\" Modified 15 Oct 2002 by Michael Kerrisk <mtk.manpages@gmail.com> -.\" Added description for CLONE_NEWNS, which was added in Linux 2.4.19 -.\" Slightly rephrased, aeb. -.\" Modified 1 Feb 2003 - added CLONE_SIGHAND restriction, aeb. -.\" Modified 1 Jan 2004 - various updates, aeb -.\" Modified 2004-09-10 - added CLONE_PARENT_SETTID etc. - aeb. -.\" 2005-04-12, mtk, noted the PID caching behavior of NPTL's getpid() -.\" wrapper under BUGS. -.\" 2005-05-10, mtk, added CLONE_SYSVSEM, CLONE_UNTRACED, CLONE_STOPPED. -.\" 2005-05-17, mtk, Substantially enhanced discussion of CLONE_THREAD. -.\" 2008-11-18, mtk, order CLONE_* flags alphabetically -.\" 2008-11-18, mtk, document CLONE_NEWPID -.\" 2008-11-19, mtk, document CLONE_NEWUTS -.\" 2008-11-19, mtk, document CLONE_NEWIPC -.\" 2008-11-19, Jens Axboe, mtk, document CLONE_IO -.\" -.TH clone 2 (date) "Linux man-pages (unreleased)" -.SH NAME -clone, __clone2, clone3 \- create a child process -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -/* Prototype for the glibc wrapper function */ -.PP -.B #define _GNU_SOURCE -.B #include <sched.h> -.PP -.BI "int clone(int (*" "fn" ")(void *_Nullable), void *" stack \ -", int " flags , -.BI " void *_Nullable " "arg" ", ..." \ -" \fR/*\fP" " pid_t *_Nullable " parent_tid , -.BI " void *_Nullable " tls , -.BI " pid_t *_Nullable " child_tid " \fR*/\fP );" -.PP -/* For the prototype of the raw clone() system call, see NOTES */ -.PP -.BR "#include <linux/sched.h>" " /* Definition of " "struct clone_args" " */" -.BR "#include <sched.h>" " /* Definition of " CLONE_* " constants */" -.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" -.B #include <unistd.h> -.PP -.BI "long syscall(SYS_clone3, struct clone_args *" cl_args ", size_t " size ); -.fi -.PP -.IR Note : -glibc provides no wrapper for -.BR clone3 (), -necessitating the use of -.BR syscall (2). -.SH DESCRIPTION -These system calls -create a new ("child") process, in a manner similar to -.BR fork (2). -.PP -By contrast with -.BR fork (2), -these system calls provide more precise control over what pieces of execution -context are shared between the calling process and the child process. -For example, using these system calls, the caller can control whether -or not the two processes share the virtual address space, -the table of file descriptors, and the table of signal handlers. -These system calls also allow the new child process to be placed -in separate -.BR namespaces (7). -.PP -Note that in this manual -page, "calling process" normally corresponds to "parent process". -But see the descriptions of -.B CLONE_PARENT -and -.B CLONE_THREAD -below. -.PP -This page describes the following interfaces: -.IP \[bu] 3 -The glibc -.BR clone () -wrapper function and the underlying system call on which it is based. -The main text describes the wrapper function; -the differences for the raw system call -are described toward the end of this page. -.IP \[bu] -The newer -.BR clone3 () -system call. -.PP -In the remainder of this page, the terminology "the clone call" is used -when noting details that apply to all of these interfaces, -.\" -.SS The clone() wrapper function -When the child process is created with the -.BR clone () -wrapper function, -it commences execution by calling the function pointed to by the argument -.IR fn . -(This differs from -.BR fork (2), -where execution continues in the child from the point -of the -.BR fork (2) -call.) -The -.I arg -argument is passed as the argument of the function -.IR fn . -.PP -When the -.IR fn ( arg ) -function returns, the child process terminates. -The integer returned by -.I fn -is the exit status for the child process. -The child process may also terminate explicitly by calling -.BR exit (2) -or after receiving a fatal signal. -.PP -The -.I stack -argument specifies the location of the stack used by the child process. -Since the child and calling process may share memory, -it is not possible for the child process to execute in the -same stack as the calling process. -The calling process must therefore -set up memory space for the child stack and pass a pointer to this -space to -.BR clone (). -Stacks grow downward on all processors that run Linux -(except the HP PA processors), so -.I stack -usually points to the topmost address of the memory space set up for -the child stack. -Note that -.BR clone () -does not provide a means whereby the caller can inform the kernel of the -size of the stack area. -.PP -The remaining arguments to -.BR clone () -are discussed below. -.\" -.SS clone3() -The -.BR clone3 () -system call provides a superset of the functionality of the older -.BR clone () -interface. -It also provides a number of API improvements, including: -space for additional flags bits; -cleaner separation in the use of various arguments; -and the ability to specify the size of the child's stack area. -.PP -As with -.BR fork (2), -.BR clone3 () -returns in both the parent and the child. -It returns 0 in the child process and returns the PID of the child -in the parent. -.PP -The -.I cl_args -argument of -.BR clone3 () -is a structure of the following form: -.PP -.in +4n -.EX -struct clone_args { - u64 flags; /* Flags bit mask */ - u64 pidfd; /* Where to store PID file descriptor - (\fIint *\fP) */ - u64 child_tid; /* Where to store child TID, - in child\[aq]s memory (\fIpid_t *\fP) */ - u64 parent_tid; /* Where to store child TID, - in parent\[aq]s memory (\fIpid_t *\fP) */ - u64 exit_signal; /* Signal to deliver to parent on - child termination */ - u64 stack; /* Pointer to lowest byte of stack */ - u64 stack_size; /* Size of stack */ - u64 tls; /* Location of new TLS */ - u64 set_tid; /* Pointer to a \fIpid_t\fP array - (since Linux 5.5) */ - u64 set_tid_size; /* Number of elements in \fIset_tid\fP - (since Linux 5.5) */ - u64 cgroup; /* File descriptor for target cgroup - of child (since Linux 5.7) */ -}; -.EE -.in -.PP -The -.I size -argument that is supplied to -.BR clone3 () -should be initialized to the size of this structure. -(The existence of the -.I size -argument permits future extensions to the -.I clone_args -structure.) -.PP -The stack for the child process is specified via -.IR cl_args.stack , -which points to the lowest byte of the stack area, -and -.IR cl_args.stack_size , -which specifies the size of the stack in bytes. -In the case where the -.B CLONE_VM -flag (see below) is specified, a stack must be explicitly allocated -and specified. -Otherwise, these two fields can be specified as NULL and 0, -which causes the child to use the same stack area as the parent -(in the child's own virtual address space). -.PP -The remaining fields in the -.I cl_args -argument are discussed below. -.\" -.SS Equivalence between clone() and clone3() arguments -Unlike the older -.BR clone () -interface, where arguments are passed individually, in the newer -.BR clone3 () -interface the arguments are packaged into the -.I clone_args -structure shown above. -This structure allows for a superset of the information passed via the -.BR clone () -arguments. -.PP -The following table shows the equivalence between the arguments of -.BR clone () -and the fields in the -.I clone_args -argument supplied to -.BR clone3 (): -.RS 4 -.TS -lb lb lb -l l l -li li l. -clone() clone3() Notes - \fIcl_args\fP field -flags & \[ti]0xff flags T{ -For most flags; details below -T} -parent_tid pidfd See CLONE_PIDFD -child_tid child_tid See CLONE_CHILD_SETTID -parent_tid parent_tid See CLONE_PARENT_SETTID -flags & 0xff exit_signal -stack stack -\fP---\fP stack_size -tls tls See CLONE_SETTLS -\fP---\fP set_tid See below for details -\fP---\fP set_tid_size -\fP---\fP cgroup See CLONE_INTO_CGROUP -.TE -.RE -.\" -.SS The child termination signal -When the child process terminates, a signal may be sent to the parent. -The termination signal is specified in the low byte of -.I flags -.RB ( clone ()) -or in -.I cl_args.exit_signal -.RB ( clone3 ()). -If this signal is specified as anything other than -.BR SIGCHLD , -then the parent process must specify the -.B __WALL -or -.B __WCLONE -options when waiting for the child with -.BR wait (2). -If no signal (i.e., zero) is specified, then the parent process is not signaled -when the child terminates. -.\" -.SS The set_tid array -By default, the kernel chooses the next sequential PID for the new -process in each of the PID namespaces where it is present. -When creating a process with -.BR clone3 (), -the -.I set_tid -array (available since Linux 5.5) -can be used to select specific PIDs for the process in some -or all of the PID namespaces where it is present. -If the PID of the newly created process should be set only for the current -PID namespace or in the newly created PID namespace (if -.I flags -contains -.BR CLONE_NEWPID ) -then the first element in the -.I set_tid -array has to be the desired PID and -.I set_tid_size -needs to be 1. -.PP -If the PID of the newly created process should have a certain value in -multiple PID namespaces, then the -.I set_tid -array can have multiple entries. -The first entry defines the PID in the most -deeply nested PID namespace and each of the following entries contains -the PID in the -corresponding ancestor PID namespace. -The number of PID namespaces in which a PID -should be set is defined by -.I set_tid_size -which cannot be larger than the number of currently nested PID namespaces. -.PP -To create a process with the following PIDs in a PID namespace hierarchy: -.RS 4 -.TS -lb lb lb -l l l. -PID NS level Requested PID Notes -0 31496 Outermost PID namespace -1 42 -2 7 Innermost PID namespace -.TE -.RE -.PP -Set the array to: -.PP -.in +4n -.EX -set_tid[0] = 7; -set_tid[1] = 42; -set_tid[2] = 31496; -set_tid_size = 3; -.EE -.in -.PP -If only the PIDs in the two innermost PID namespaces -need to be specified, set the array to: -.PP -.in +4n -.EX -set_tid[0] = 7; -set_tid[1] = 42; -set_tid_size = 2; -.EE -.in -.PP -The PID in the PID namespaces outside the two innermost PID namespaces -is selected the same way as any other PID is selected. -.PP -The -.I set_tid -feature requires -.B CAP_SYS_ADMIN -or -(since Linux 5.9) -.\" commit 124ea650d3072b005457faed69909221c2905a1f -.\" commit 1caef81da05a84a40dbf02110e967ce6d1135ff6 -.B CAP_CHECKPOINT_RESTORE -in all owning user namespaces of the target PID namespaces. -.PP -Callers may only choose a PID greater than 1 in a given PID namespace -if an -.B init -process (i.e., a process with PID 1) already exists in that namespace. -Otherwise the PID -entry for this PID namespace must be 1. -.\" -.SS The flags mask -Both -.BR clone () -and -.BR clone3 () -allow a flags bit mask that modifies their behavior -and allows the caller to specify what is shared between the calling process -and the child process. -This bit mask\[em]the -.I flags -argument of -.BR clone () -or the -.I cl_args.flags -field passed to -.BR clone3 ()\[em]is -referred to as the -.I flags -mask in the remainder of this page. -.PP -The -.I flags -mask is specified as a bitwise OR of zero or more of -the constants listed below. -Except as noted below, these flags are available -(and have the same effect) in both -.BR clone () -and -.BR clone3 (). -.TP -.BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)" -Clear (zero) the child thread ID at the location pointed to by -.I child_tid -.RB ( clone ()) -or -.I cl_args.child_tid -.RB ( clone3 ()) -in child memory when the child exits, and do a wakeup on the futex -at that address. -The address involved may be changed by the -.BR set_tid_address (2) -system call. -This is used by threading libraries. -.TP -.BR CLONE_CHILD_SETTID " (since Linux 2.5.49)" -Store the child thread ID at the location pointed to by -.I child_tid -.RB ( clone ()) -or -.I cl_args.child_tid -.RB ( clone3 ()) -in the child's memory. -The store operation completes before the clone call -returns control to user space in the child process. -(Note that the store operation may not have completed before the clone call -returns in the parent process, which is relevant if the -.B CLONE_VM -flag is also employed.) -.TP -.BR CLONE_CLEAR_SIGHAND " (since Linux 5.5)" -.\" commit b612e5df4587c934bd056bf05f4a1deca4de4f75 -By default, signal dispositions in the child thread are the same as -in the parent. -If this flag is specified, -then all signals that are handled in the parent -are reset to their default dispositions -.RB ( SIG_DFL ) -in the child. -.IP -Specifying this flag together with -.B CLONE_SIGHAND -is nonsensical and disallowed. -.TP -.BR CLONE_DETACHED " (historical)" -For a while (during the Linux 2.5 development series) -.\" added in Linux 2.5.32; removed in Linux 2.6.0-test4 -there was a -.B CLONE_DETACHED -flag, -which caused the parent not to receive a signal when the child terminated. -Ultimately, the effect of this flag was subsumed under the -.B CLONE_THREAD -flag and by the time Linux 2.6.0 was released, this flag had no effect. -Starting in Linux 2.6.2, the need to give this flag together with -.B CLONE_THREAD -disappeared. -.IP -This flag is still defined, but it is usually ignored when calling -.BR clone (). -However, see the description of -.B CLONE_PIDFD -for some exceptions. -.TP -.BR CLONE_FILES " (since Linux 2.0)" -If -.B CLONE_FILES -is set, the calling process and the child process share the same file -descriptor table. -Any file descriptor created by the calling process or by the child -process is also valid in the other process. -Similarly, if one of the processes closes a file descriptor, -or changes its associated flags (using the -.BR fcntl (2) -.B F_SETFD -operation), the other process is also affected. -If a process sharing a file descriptor table calls -.BR execve (2), -its file descriptor table is duplicated (unshared). -.IP -If -.B CLONE_FILES -is not set, the child process inherits a copy of all file descriptors -opened in the calling process at the time of the clone call. -Subsequent operations that open or close file descriptors, -or change file descriptor flags, -performed by either the calling -process or the child process do not affect the other process. -Note, however, -that the duplicated file descriptors in the child refer to the same -open file descriptions as the corresponding file descriptors -in the calling process, -and thus share file offsets and file status flags (see -.BR open (2)). -.TP -.BR CLONE_FS " (since Linux 2.0)" -If -.B CLONE_FS -is set, the caller and the child process share the same filesystem -information. -This includes the root of the filesystem, the current -working directory, and the umask. -Any call to -.BR chroot (2), -.BR chdir (2), -or -.BR umask (2) -performed by the calling process or the child process also affects the -other process. -.IP -If -.B CLONE_FS -is not set, the child process works on a copy of the filesystem -information of the calling process at the time of the clone call. -Calls to -.BR chroot (2), -.BR chdir (2), -or -.BR umask (2) -performed later by one of the processes do not affect the other process. -.TP -.BR CLONE_INTO_CGROUP " (since Linux 5.7)" -.\" commit ef2c41cf38a7559bbf91af42d5b6a4429db8fc68 -By default, a child process is placed in the same version 2 -cgroup as its parent. -The -.B CLONE_INTO_CGROUP -flag allows the child process to be created in a different version 2 cgroup. -(Note that -.B CLONE_INTO_CGROUP -has effect only for version 2 cgroups.) -.IP -In order to place the child process in a different cgroup, -the caller specifies -.B CLONE_INTO_CGROUP -in -.I cl_args.flags -and passes a file descriptor that refers to a version 2 cgroup in the -.I cl_args.cgroup -field. -(This file descriptor can be obtained by opening a cgroup v2 directory -using either the -.B O_RDONLY -or the -.B O_PATH -flag.) -Note that all of the usual restrictions (described in -.BR cgroups (7)) -on placing a process into a version 2 cgroup apply. -.IP -Among the possible use cases for -.B CLONE_INTO_CGROUP -are the following: -.RS -.IP \[bu] 3 -Spawning a process into a cgroup different from the parent's cgroup -makes it possible for a service manager to directly spawn new -services into dedicated cgroups. -This eliminates the accounting -jitter that would be caused if the child process was first created in the -same cgroup as the parent and then -moved into the target cgroup. -Furthermore, spawning the child process directly into a target cgroup -is significantly cheaper than moving the child process into -the target cgroup after it has been created. -.IP \[bu] -The -.B CLONE_INTO_CGROUP -flag also allows the creation of -frozen child processes by spawning them into a frozen cgroup. -(See -.BR cgroups (7) -for a description of the freezer controller.) -.IP \[bu] -For threaded applications (or even thread implementations which -make use of cgroups to limit individual threads), it is possible to -establish a fixed cgroup layout before spawning each thread -directly into its target cgroup. -.RE -.TP -.BR CLONE_IO " (since Linux 2.6.25)" -If -.B CLONE_IO -is set, then the new process shares an I/O context with -the calling process. -If this flag is not set, then (as with -.BR fork (2)) -the new process has its own I/O context. -.IP -.\" The following based on text from Jens Axboe -The I/O context is the I/O scope of the disk scheduler (i.e., -what the I/O scheduler uses to model scheduling of a process's I/O). -If processes share the same I/O context, -they are treated as one by the I/O scheduler. -As a consequence, they get to share disk time. -For some I/O schedulers, -.\" the anticipatory and CFQ scheduler -if two processes share an I/O context, -they will be allowed to interleave their disk access. -If several threads are doing I/O on behalf of the same process -.RB ( aio_read (3), -for instance), they should employ -.B CLONE_IO -to get better I/O performance. -.\" with CFQ and AS. -.IP -If the kernel is not configured with the -.B CONFIG_BLOCK -option, this flag is a no-op. -.TP -.BR CLONE_NEWCGROUP " (since Linux 4.6)" -Create the process in a new cgroup namespace. -If this flag is not set, then (as with -.BR fork (2)) -the process is created in the same cgroup namespaces as the calling process. -.IP -For further information on cgroup namespaces, see -.BR cgroup_namespaces (7). -.IP -Only a privileged process -.RB ( CAP_SYS_ADMIN ) -can employ -.BR CLONE_NEWCGROUP . -.\" -.TP -.BR CLONE_NEWIPC " (since Linux 2.6.19)" -If -.B CLONE_NEWIPC -is set, then create the process in a new IPC namespace. -If this flag is not set, then (as with -.BR fork (2)), -the process is created in the same IPC namespace as -the calling process. -.IP -For further information on IPC namespaces, see -.BR ipc_namespaces (7). -.IP -Only a privileged process -.RB ( CAP_SYS_ADMIN ) -can employ -.BR CLONE_NEWIPC . -This flag can't be specified in conjunction with -.BR CLONE_SYSVSEM . -.TP -.BR CLONE_NEWNET " (since Linux 2.6.24)" -(The implementation of this flag was completed only -by about Linux 2.6.29.) -.IP -If -.B CLONE_NEWNET -is set, then create the process in a new network namespace. -If this flag is not set, then (as with -.BR fork (2)) -the process is created in the same network namespace as -the calling process. -.IP -For further information on network namespaces, see -.BR network_namespaces (7). -.IP -Only a privileged process -.RB ( CAP_SYS_ADMIN ) -can employ -.BR CLONE_NEWNET . -.TP -.BR CLONE_NEWNS " (since Linux 2.4.19)" -If -.B CLONE_NEWNS -is set, the cloned child is started in a new mount namespace, -initialized with a copy of the namespace of the parent. -If -.B CLONE_NEWNS -is not set, the child lives in the same mount -namespace as the parent. -.IP -For further information on mount namespaces, see -.BR namespaces (7) -and -.BR mount_namespaces (7). -.IP -Only a privileged process -.RB ( CAP_SYS_ADMIN ) -can employ -.BR CLONE_NEWNS . -It is not permitted to specify both -.B CLONE_NEWNS -and -.B CLONE_FS -.\" See https://lwn.net/Articles/543273/ -in the same clone call. -.TP -.BR CLONE_NEWPID " (since Linux 2.6.24)" -.\" This explanation draws a lot of details from -.\" http://lwn.net/Articles/259217/ -.\" Authors: Pavel Emelyanov <xemul@openvz.org> -.\" and Kir Kolyshkin <kir@openvz.org> -.\" -.\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264 -.\" Author: Pavel Emelyanov <xemul@openvz.org> -If -.B CLONE_NEWPID -is set, then create the process in a new PID namespace. -If this flag is not set, then (as with -.BR fork (2)) -the process is created in the same PID namespace as -the calling process. -.IP -For further information on PID namespaces, see -.BR namespaces (7) -and -.BR pid_namespaces (7). -.IP -Only a privileged process -.RB ( CAP_SYS_ADMIN ) -can employ -.BR CLONE_NEWPID . -This flag can't be specified in conjunction with -.B CLONE_THREAD -or -.BR CLONE_PARENT . -.TP -.B CLONE_NEWUSER -(This flag first became meaningful for -.BR clone () -in Linux 2.6.23, -the current -.BR clone () -semantics were merged in Linux 3.5, -and the final pieces to make the user namespaces completely usable were -merged in Linux 3.8.) -.IP -If -.B CLONE_NEWUSER -is set, then create the process in a new user namespace. -If this flag is not set, then (as with -.BR fork (2)) -the process is created in the same user namespace as the calling process. -.IP -For further information on user namespaces, see -.BR namespaces (7) -and -.BR user_namespaces (7). -.IP -Before Linux 3.8, use of -.B CLONE_NEWUSER -required that the caller have three capabilities: -.BR CAP_SYS_ADMIN , -.BR CAP_SETUID , -and -.BR CAP_SETGID . -.\" Before Linux 2.6.29, it appears that only CAP_SYS_ADMIN was needed -Starting with Linux 3.8, -no privileges are needed to create a user namespace. -.IP -This flag can't be specified in conjunction with -.B CLONE_THREAD -or -.BR CLONE_PARENT . -For security reasons, -.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 -.\" https://lwn.net/Articles/543273/ -.\" The fix actually went into Linux 3.9 and into Linux 3.8.3. However, user namespaces -.\" were, for practical purposes, unusable in earlier Linux 3.8.x because of the -.\" various filesystems that didn't support userns. -.B CLONE_NEWUSER -cannot be specified in conjunction with -.BR CLONE_FS . -.TP -.BR CLONE_NEWUTS " (since Linux 2.6.19)" -If -.B CLONE_NEWUTS -is set, then create the process in a new UTS namespace, -whose identifiers are initialized by duplicating the identifiers -from the UTS namespace of the calling process. -If this flag is not set, then (as with -.BR fork (2)) -the process is created in the same UTS namespace as -the calling process. -.IP -For further information on UTS namespaces, see -.BR uts_namespaces (7). -.IP -Only a privileged process -.RB ( CAP_SYS_ADMIN ) -can employ -.BR CLONE_NEWUTS . -.TP -.BR CLONE_PARENT " (since Linux 2.3.12)" -If -.B CLONE_PARENT -is set, then the parent of the new child (as returned by -.BR getppid (2)) -will be the same as that of the calling process. -.IP -If -.B CLONE_PARENT -is not set, then (as with -.BR fork (2)) -the child's parent is the calling process. -.IP -Note that it is the parent process, as returned by -.BR getppid (2), -which is signaled when the child terminates, so that -if -.B CLONE_PARENT -is set, then the parent of the calling process, rather than the -calling process itself, is signaled. -.IP -The -.B CLONE_PARENT -flag can't be used in clone calls by the -global init process (PID 1 in the initial PID namespace) -and init processes in other PID namespaces. -This restriction prevents the creation of multi-rooted process trees -as well as the creation of unreapable zombies in the initial PID namespace. -.TP -.BR CLONE_PARENT_SETTID " (since Linux 2.5.49)" -Store the child thread ID at the location pointed to by -.I parent_tid -.RB ( clone ()) -or -.I cl_args.parent_tid -.RB ( clone3 ()) -in the parent's memory. -(In Linux 2.5.32-2.5.48 there was a flag -.B CLONE_SETTID -that did this.) -The store operation completes before the clone call -returns control to user space. -.TP -.BR CLONE_PID " (Linux 2.0 to Linux 2.5.15)" -If -.B CLONE_PID -is set, the child process is created with the same process ID as -the calling process. -This is good for hacking the system, but otherwise -of not much use. -From Linux 2.3.21 onward, this flag could be -specified only by the system boot process (PID 0). -The flag disappeared completely from the kernel sources in Linux 2.5.16. -Subsequently, the kernel silently ignored this bit if it was specified in the -.I flags -mask. -Much later, the same bit was recycled for use as the -.B CLONE_PIDFD -flag. -.TP -.BR CLONE_PIDFD " (since Linux 5.2)" -.\" commit b3e5838252665ee4cfa76b82bdf1198dca81e5be -If this flag is specified, -a PID file descriptor referring to the child process is allocated -and placed at a specified location in the parent's memory. -The close-on-exec flag is set on this new file descriptor. -PID file descriptors can be used for the purposes described in -.BR pidfd_open (2). -.RS -.IP \[bu] 3 -When using -.BR clone3 (), -the PID file descriptor is placed at the location pointed to by -.IR cl_args.pidfd . -.IP \[bu] -When using -.BR clone (), -the PID file descriptor is placed at the location pointed to by -.IR parent_tid . -Since the -.I parent_tid -argument is used to return the PID file descriptor, -.B CLONE_PIDFD -cannot be used with -.B CLONE_PARENT_SETTID -when calling -.BR clone (). -.RE -.IP -It is currently not possible to use this flag together with -.B CLONE_THREAD. -This means that the process identified by the PID file descriptor -will always be a thread group leader. -.IP -If the obsolete -.B CLONE_DETACHED -flag is specified alongside -.B CLONE_PIDFD -when calling -.BR clone (), -an error is returned. -An error also results if -.B CLONE_DETACHED -is specified when calling -.BR clone3 (). -This error behavior ensures that the bit corresponding to -.B CLONE_DETACHED -can be reused for further PID file descriptor features in the future. -.TP -.BR CLONE_PTRACE " (since Linux 2.2)" -If -.B CLONE_PTRACE -is specified, and the calling process is being traced, -then trace the child also (see -.BR ptrace (2)). -.TP -.BR CLONE_SETTLS " (since Linux 2.5.32)" -The TLS (Thread Local Storage) descriptor is set to -.IR tls . -.IP -The interpretation of -.I tls -and the resulting effect is architecture dependent. -On x86, -.I tls -is interpreted as a -.I struct user_desc\~* -(see -.BR set_thread_area (2)). -On x86-64 it is the new value to be set for the %fs base register -(see the -.B ARCH_SET_FS -argument to -.BR arch_prctl (2)). -On architectures with a dedicated TLS register, it is the new value -of that register. -.IP -Use of this flag requires detailed knowledge and generally it -should not be used except in libraries implementing threading. -.TP -.BR CLONE_SIGHAND " (since Linux 2.0)" -If -.B CLONE_SIGHAND -is set, the calling process and the child process share the same table of -signal handlers. -If the calling process or child process calls -.BR sigaction (2) -to change the behavior associated with a signal, the behavior is -changed in the other process as well. -However, the calling process and child -processes still have distinct signal masks and sets of pending -signals. -So, one of them may block or unblock signals using -.BR sigprocmask (2) -without affecting the other process. -.IP -If -.B CLONE_SIGHAND -is not set, the child process inherits a copy of the signal handlers -of the calling process at the time of the clone call. -Calls to -.BR sigaction (2) -performed later by one of the processes have no effect on the other -process. -.IP -Since Linux 2.6.0, -.\" Precisely: Linux 2.6.0-test6 -the -.I flags -mask must also include -.B CLONE_VM -if -.B CLONE_SIGHAND -is specified. -.TP -.BR CLONE_STOPPED " (since Linux 2.6.0)" -.\" Precisely: Linux 2.6.0-test2 -If -.B CLONE_STOPPED -is set, then the child is initially stopped (as though it was sent a -.B SIGSTOP -signal), and must be resumed by sending it a -.B SIGCONT -signal. -.IP -This flag was -.I deprecated -from Linux 2.6.25 onward, -and was -.I removed -altogether in Linux 2.6.38. -Since then, the kernel silently ignores it without error. -.\" glibc 2.8 removed this defn from bits/sched.h -Starting with Linux 4.6, the same bit was reused for the -.B CLONE_NEWCGROUP -flag. -.TP -.BR CLONE_SYSVSEM " (since Linux 2.5.10)" -If -.B CLONE_SYSVSEM -is set, then the child and the calling process share -a single list of System V semaphore adjustment -.RI ( semadj ) -values (see -.BR semop (2)). -In this case, the shared list accumulates -.I semadj -values across all processes sharing the list, -and semaphore adjustments are performed only when the last process -that is sharing the list terminates (or ceases sharing the list using -.BR unshare (2)). -If this flag is not set, then the child has a separate -.I semadj -list that is initially empty. -.TP -.BR CLONE_THREAD " (since Linux 2.4.0)" -.\" Precisely: Linux 2.6.0-test8 -If -.B CLONE_THREAD -is set, the child is placed in the same thread group as the calling process. -To make the remainder of the discussion of -.B CLONE_THREAD -more readable, the term "thread" is used to refer to the -processes within a thread group. -.IP -Thread groups were a feature added in Linux 2.4 to support the -POSIX threads notion of a set of threads that share a single PID. -Internally, this shared PID is the so-called -thread group identifier (TGID) for the thread group. -Since Linux 2.4, calls to -.BR getpid (2) -return the TGID of the caller. -.IP -The threads within a group can be distinguished by their (system-wide) -unique thread IDs (TID). -A new thread's TID is available as the function result -returned to the caller, -and a thread can obtain -its own TID using -.BR gettid (2). -.IP -When a clone call is made without specifying -.BR CLONE_THREAD , -then the resulting thread is placed in a new thread group -whose TGID is the same as the thread's TID. -This thread is the -.I leader -of the new thread group. -.IP -A new thread created with -.B CLONE_THREAD -has the same parent process as the process that made the clone call -(i.e., like -.BR CLONE_PARENT ), -so that calls to -.BR getppid (2) -return the same value for all of the threads in a thread group. -When a -.B CLONE_THREAD -thread terminates, the thread that created it is not sent a -.B SIGCHLD -(or other termination) signal; -nor can the status of such a thread be obtained -using -.BR wait (2). -(The thread is said to be -.IR detached .) -.IP -After all of the threads in a thread group terminate -the parent process of the thread group is sent a -.B SIGCHLD -(or other termination) signal. -.IP -If any of the threads in a thread group performs an -.BR execve (2), -then all threads other than the thread group leader are terminated, -and the new program is executed in the thread group leader. -.IP -If one of the threads in a thread group creates a child using -.BR fork (2), -then any thread in the group can -.BR wait (2) -for that child. -.IP -Since Linux 2.5.35, the -.I flags -mask must also include -.B CLONE_SIGHAND -if -.B CLONE_THREAD -is specified -(and note that, since Linux 2.6.0, -.\" Precisely: Linux 2.6.0-test6 -.B CLONE_SIGHAND -also requires -.B CLONE_VM -to be included). -.IP -Signal dispositions and actions are process-wide: -if an unhandled signal is delivered to a thread, then -it will affect (terminate, stop, continue, be ignored in) -all members of the thread group. -.IP -Each thread has its own signal mask, as set by -.BR sigprocmask (2). -.IP -A signal may be process-directed or thread-directed. -A process-directed signal is targeted at a thread group (i.e., a TGID), -and is delivered to an arbitrarily selected thread from among those -that are not blocking the signal. -A signal may be process-directed because it was generated by the kernel -for reasons other than a hardware exception, or because it was sent using -.BR kill (2) -or -.BR sigqueue (3). -A thread-directed signal is targeted at (i.e., delivered to) -a specific thread. -A signal may be thread directed because it was sent using -.BR tgkill (2) -or -.BR pthread_sigqueue (3), -or because the thread executed a machine language instruction that triggered -a hardware exception -(e.g., invalid memory access triggering -.B SIGSEGV -or a floating-point exception triggering -.BR SIGFPE ). -.IP -A call to -.BR sigpending (2) -returns a signal set that is the union of the pending process-directed -signals and the signals that are pending for the calling thread. -.IP -If a process-directed signal is delivered to a thread group, -and the thread group has installed a handler for the signal, then -the handler is invoked in exactly one, arbitrarily selected -member of the thread group that has not blocked the signal. -If multiple threads in a group are waiting to accept the same signal using -.BR sigwaitinfo (2), -the kernel will arbitrarily select one of these threads -to receive the signal. -.TP -.BR CLONE_UNTRACED " (since Linux 2.5.46)" -If -.B CLONE_UNTRACED -is specified, then a tracing process cannot force -.B CLONE_PTRACE -on this child process. -.TP -.BR CLONE_VFORK " (since Linux 2.2)" -If -.B CLONE_VFORK -is set, the execution of the calling process is suspended -until the child releases its virtual memory -resources via a call to -.BR execve (2) -or -.BR _exit (2) -(as with -.BR vfork (2)). -.IP -If -.B CLONE_VFORK -is not set, then both the calling process and the child are schedulable -after the call, and an application should not rely on execution occurring -in any particular order. -.TP -.BR CLONE_VM " (since Linux 2.0)" -If -.B CLONE_VM -is set, the calling process and the child process run in the same memory -space. -In particular, memory writes performed by the calling process -or by the child process are also visible in the other process. -Moreover, any memory mapping or unmapping performed with -.BR mmap (2) -or -.BR munmap (2) -by the child or calling process also affects the other process. -.IP -If -.B CLONE_VM -is not set, the child process runs in a separate copy of the memory -space of the calling process at the time of the clone call. -Memory writes or file mappings/unmappings performed by one of the -processes do not affect the other, as with -.BR fork (2). -.IP -If the -.B CLONE_VM -flag is specified and the -.B CLONE_VFORK -flag is not specified, -then any alternate signal stack that was established by -.BR sigaltstack (2) -is cleared in the child process. -.SH RETURN VALUE -.\" gettid(2) returns current->pid; -.\" getpid(2) returns current->tgid; -On success, the thread ID of the child process is returned -in the caller's thread of execution. -On failure, \-1 is returned -in the caller's context, no child process is created, and -.I errno -is set to indicate the error. -.SH ERRORS -.TP -.BR EACCES " (" clone3 "() only)" -.B CLONE_INTO_CGROUP -was specified in -.IR cl_args.flags , -but the restrictions (described in -.BR cgroups (7)) -on placing the child process into the version 2 cgroup referred to by -.I cl_args.cgroup -are not met. -.TP -.B EAGAIN -Too many processes are already running; see -.BR fork (2). -.TP -.BR EBUSY " (" clone3 "() only)" -.B CLONE_INTO_CGROUP -was specified in -.IR cl_args.flags , -but the file descriptor specified in -.I cl_args.cgroup -refers to a version 2 cgroup in which a domain controller is enabled. -.TP -.BR EEXIST " (" clone3 "() only)" -One (or more) of the PIDs specified in -.I set_tid -already exists in the corresponding PID namespace. -.TP -.B EINVAL -Both -.B CLONE_SIGHAND -and -.B CLONE_CLEAR_SIGHAND -were specified in the -.I flags -mask. -.TP -.B EINVAL -.B CLONE_SIGHAND -was specified in the -.I flags -mask, but -.B CLONE_VM -was not. -(Since Linux 2.6.0.) -.\" Precisely: Linux 2.6.0-test6 -.TP -.B EINVAL -.B CLONE_THREAD -was specified in the -.I flags -mask, but -.B CLONE_SIGHAND -was not. -(Since Linux 2.5.35.) -.\" .TP -.\" .B EINVAL -.\" Precisely one of -.\" .B CLONE_DETACHED -.\" and -.\" .B CLONE_THREAD -.\" was specified. -.\" (Since Linux 2.6.0-test6.) -.TP -.B EINVAL -.B CLONE_THREAD -was specified in the -.I flags -mask, but the current process previously called -.BR unshare (2) -with the -.B CLONE_NEWPID -flag or used -.BR setns (2) -to reassociate itself with a PID namespace. -.TP -.B EINVAL -.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 -Both -.B CLONE_FS -and -.B CLONE_NEWNS -were specified in the -.I flags -mask. -.TP -.BR EINVAL " (since Linux 3.9)" -Both -.B CLONE_NEWUSER -and -.B CLONE_FS -were specified in the -.I flags -mask. -.TP -.B EINVAL -Both -.B CLONE_NEWIPC -and -.B CLONE_SYSVSEM -were specified in the -.I flags -mask. -.TP -.B EINVAL -One (or both) of -.B CLONE_NEWPID -or -.B CLONE_NEWUSER -and one (or both) of -.B CLONE_THREAD -or -.B CLONE_PARENT -were specified in the -.I flags -mask. -.TP -.BR EINVAL " (since Linux 2.6.32)" -.\" commit 123be07b0b399670a7cc3d82fef0cb4f93ef885c -.B CLONE_PARENT -was specified, and the caller is an init process. -.TP -.B EINVAL -Returned by the glibc -.BR clone () -wrapper function when -.I fn -or -.I stack -is specified as NULL. -.TP -.B EINVAL -.B CLONE_NEWIPC -was specified in the -.I flags -mask, -but the kernel was not configured with the -.B CONFIG_SYSVIPC -and -.B CONFIG_IPC_NS -options. -.TP -.B EINVAL -.B CLONE_NEWNET -was specified in the -.I flags -mask, -but the kernel was not configured with the -.B CONFIG_NET_NS -option. -.TP -.B EINVAL -.B CLONE_NEWPID -was specified in the -.I flags -mask, -but the kernel was not configured with the -.B CONFIG_PID_NS -option. -.TP -.B EINVAL -.B CLONE_NEWUSER -was specified in the -.I flags -mask, -but the kernel was not configured with the -.B CONFIG_USER_NS -option. -.TP -.B EINVAL -.B CLONE_NEWUTS -was specified in the -.I flags -mask, -but the kernel was not configured with the -.B CONFIG_UTS_NS -option. -.TP -.B EINVAL -.I stack -is not aligned to a suitable boundary for this architecture. -For example, on aarch64, -.I stack -must be a multiple of 16. -.TP -.BR EINVAL " (" clone3 "() only)" -.B CLONE_DETACHED -was specified in the -.I flags -mask. -.TP -.BR EINVAL " (" clone "() only)" -.B CLONE_PIDFD -was specified together with -.B CLONE_DETACHED -in the -.I flags -mask. -.TP -.B EINVAL -.B CLONE_PIDFD -was specified together with -.B CLONE_THREAD -in the -.I flags -mask. -.TP -.BR "EINVAL " "(" clone "() only)" -.B CLONE_PIDFD -was specified together with -.B CLONE_PARENT_SETTID -in the -.I flags -mask. -.TP -.BR EINVAL " (" clone3 "() only)" -.I set_tid_size -is greater than the number of nested PID namespaces. -.TP -.BR EINVAL " (" clone3 "() only)" -One of the PIDs specified in -.I set_tid -was an invalid. -.TP -.BR EINVAL " (" clone3 "() only)" -.\" commit 7f192e3cd316ba58c88dfa26796cf77789dd9872 -.B CLONE_THREAD -or -.B CLONE_PARENT -was specified in the -.I flags -mask, but a signal was specified in -.I exit_signal. -.TP -.BR EINVAL " (AArch64 only, Linux 4.6 and earlier)" -.I stack -was not aligned to a 128-bit boundary. -.TP -.B ENOMEM -Cannot allocate sufficient memory to allocate a task structure for the -child, or to copy those parts of the caller's context that need to be -copied. -.TP -.BR ENOSPC " (since Linux 3.7)" -.\" commit f2302505775fd13ba93f034206f1e2a587017929 -.B CLONE_NEWPID -was specified in the -.I flags -mask, -but the limit on the nesting depth of PID namespaces -would have been exceeded; see -.BR pid_namespaces (7). -.TP -.BR ENOSPC " (since Linux 4.9; beforehand " EUSERS ) -.B CLONE_NEWUSER -was specified in the -.I flags -mask, and the call would cause the limit on the number of -nested user namespaces to be exceeded. -See -.BR user_namespaces (7). -.IP -From Linux 3.11 to Linux 4.8, the error diagnosed in this case was -.BR EUSERS . -.TP -.BR ENOSPC " (since Linux 4.9)" -One of the values in the -.I flags -mask specified the creation of a new user namespace, -but doing so would have caused the limit defined by the corresponding file in -.I /proc/sys/user -to be exceeded. -For further details, see -.BR namespaces (7). -.TP -.BR EOPNOTSUPP " (" clone3 "() only)" -.B CLONE_INTO_CGROUP -was specified in -.IR cl_args.flags , -but the file descriptor specified in -.I cl_args.cgroup -refers to a version 2 cgroup that is in the -.I domain invalid -state. -.TP -.B EPERM -.BR CLONE_NEWCGROUP , -.BR CLONE_NEWIPC , -.BR CLONE_NEWNET , -.BR CLONE_NEWNS , -.BR CLONE_NEWPID , -or -.B CLONE_NEWUTS -was specified by an unprivileged process (process without \fBCAP_SYS_ADMIN\fP). -.TP -.B EPERM -.B CLONE_PID -was specified by a process other than process 0. -(This error occurs only on Linux 2.5.15 and earlier.) -.TP -.B EPERM -.B CLONE_NEWUSER -was specified in the -.I flags -mask, -but either the effective user ID or the effective group ID of the caller -does not have a mapping in the parent namespace (see -.BR user_namespaces (7)). -.TP -.BR EPERM " (since Linux 3.9)" -.\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d -.B CLONE_NEWUSER -was specified in the -.I flags -mask and the caller is in a chroot environment -.\" FIXME What is the rationale for this restriction? -(i.e., the caller's root directory does not match the root directory -of the mount namespace in which it resides). -.TP -.BR EPERM " (" clone3 "() only)" -.I set_tid_size -was greater than zero, and the caller lacks the -.B CAP_SYS_ADMIN -capability in one or more of the user namespaces that own the -corresponding PID namespaces. -.TP -.BR ERESTARTNOINTR " (since Linux 2.6.17)" -.\" commit 4a2c7a7837da1b91468e50426066d988050e4d56 -System call was interrupted by a signal and will be restarted. -(This can be seen only during a trace.) -.TP -.BR EUSERS " (Linux 3.11 to Linux 4.8)" -.B CLONE_NEWUSER -was specified in the -.I flags -mask, -and the limit on the number of nested user namespaces would be exceeded. -See the discussion of the -.B ENOSPC -error above. -.SH VERSIONS -The glibc -.BR clone () -wrapper function makes some changes -in the memory pointed to by -.I stack -(changes required to set the stack up correctly for the child) -.I before -invoking the -.BR clone () -system call. -So, in cases where -.BR clone () -is used to recursively create children, -do not use the buffer employed for the parent's stack -as the stack of the child. -.PP -On i386, -.BR clone () -should not be called through vsyscall, but directly through -.IR "int $0x80" . -.SS C library/kernel differences -The raw -.BR clone () -system call corresponds more closely to -.BR fork (2) -in that execution in the child continues from the point of the -call. -As such, the -.I fn -and -.I arg -arguments of the -.BR clone () -wrapper function are omitted. -.PP -In contrast to the glibc wrapper, the raw -.BR clone () -system call accepts NULL as a -.I stack -argument (and -.BR clone3 () -likewise allows -.I cl_args.stack -to be NULL). -In this case, the child uses a duplicate of the parent's stack. -(Copy-on-write semantics ensure that the child gets separate copies -of stack pages when either process modifies the stack.) -In this case, for correct operation, the -.B CLONE_VM -option should not be specified. -(If the child -.I shares -the parent's memory because of the use of the -.B CLONE_VM -flag, -then no copy-on-write duplication occurs and chaos is likely to result.) -.PP -The order of the arguments also differs in the raw system call, -and there are variations in the arguments across architectures, -as detailed in the following paragraphs. -.PP -The raw system call interface on x86-64 and some other architectures -(including sh, tile, and alpha) is: -.PP -.in +4n -.EX -.BI "long clone(unsigned long " flags ", void *" stack , -.BI " int *" parent_tid ", int *" child_tid , -.BI " unsigned long " tls ); -.EE -.in -.PP -On x86-32, and several other common architectures -(including score, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa, -and MIPS), -.\" CONFIG_CLONE_BACKWARDS -the order of the last two arguments is reversed: -.PP -.in +4n -.EX -.BI "long clone(unsigned long " flags ", void *" stack , -.BI " int *" parent_tid ", unsigned long " tls , -.BI " int *" child_tid ); -.EE -.in -.PP -On the cris and s390 architectures, -.\" CONFIG_CLONE_BACKWARDS2 -the order of the first two arguments is reversed: -.PP -.in +4n -.EX -.BI "long clone(void *" stack ", unsigned long " flags , -.BI " int *" parent_tid ", int *" child_tid , -.BI " unsigned long " tls ); -.EE -.in -.PP -On the microblaze architecture, -.\" CONFIG_CLONE_BACKWARDS3 -an additional argument is supplied: -.PP -.in +4n -.EX -.BI "long clone(unsigned long " flags ", void *" stack , -.BI " int " stack_size , "\fR /* Size of stack */" -.BI " int *" parent_tid ", int *" child_tid , -.BI " unsigned long " tls ); -.EE -.in -.\" -.SS blackfin, m68k, and sparc -.\" Mike Frysinger noted in a 2013 mail: -.\" these arches don't define __ARCH_WANT_SYS_CLONE: -.\" blackfin ia64 m68k sparc -The argument-passing conventions on -blackfin, m68k, and sparc are different from the descriptions above. -For details, see the kernel (and glibc) source. -.SS ia64 -On ia64, a different interface is used: -.PP -.in +4n -.EX -.BI "int __clone2(int (*" "fn" ")(void *)," -.BI " void *" stack_base ", size_t " stack_size , -.BI " int " flags ", void *" "arg" ", ..." -.BI " /* pid_t *" parent_tid ", struct user_desc *" tls , -.BI " pid_t *" child_tid " */ );" -.EE -.in -.PP -The prototype shown above is for the glibc wrapper function; -for the system call itself, -the prototype can be described as follows (it is identical to the -.BR clone () -prototype on microblaze): -.PP -.in +4n -.EX -.BI "long clone2(unsigned long " flags ", void *" stack_base , -.BI " int " stack_size , "\fR /* Size of stack */" -.BI " int *" parent_tid ", int *" child_tid , -.BI " unsigned long " tls ); -.EE -.in -.PP -.BR __clone2 () -operates in the same way as -.BR clone (), -except that -.I stack_base -points to the lowest address of the child's stack area, -and -.I stack_size -specifies the size of the stack pointed to by -.IR stack_base . -.SH STANDARDS -Linux. -.SH HISTORY -.TP -.BR clone3 () -Linux 5.3. -.\" There is no entry for -.\" .BR clone () -.\" in libc5. -.\" glibc2 provides -.\" .BR clone () -.\" as described in this manual page. -.SS Linux 2.4 and earlier -In the Linux 2.4.x series, -.B CLONE_THREAD -generally does not make the parent of the new thread the same -as the parent of the calling process. -However, from Linux 2.4.7 to Linux 2.4.18 the -.B CLONE_THREAD -flag implied the -.B CLONE_PARENT -flag (as in Linux 2.6.0 and later). -.PP -In Linux 2.4 and earlier, -.BR clone () -does not take arguments -.IR parent_tid , -.IR tls , -and -.IR child_tid . -.SH NOTES -One use of these systems calls -is to implement threads: multiple flows of control in a program that -run concurrently in a shared address space. -.PP -The -.BR kcmp (2) -system call can be used to test whether two processes share various -resources such as a file descriptor table, -System V semaphore undo operations, or a virtual address space. -.PP -Handlers registered using -.BR pthread_atfork (3) -are not executed during a clone call. -.SH BUGS -GNU C library versions 2.3.4 up to and including 2.24 -contained a wrapper function for -.BR getpid (2) -that performed caching of PIDs. -This caching relied on support in the glibc wrapper for -.BR clone (), -but limitations in the implementation -meant that the cache was not up to date in some circumstances. -In particular, -if a signal was delivered to the child immediately after the -.BR clone () -call, then a call to -.BR getpid (2) -in a handler for the signal could return the PID -of the calling process ("the parent"), -if the clone wrapper had not yet had a chance to update the PID -cache in the child. -(This discussion ignores the case where the child was created using -.BR CLONE_THREAD , -when -.BR getpid (2) -.I should -return the same value in the child and in the process that called -.BR clone (), -since the caller and the child are in the same thread group. -The stale-cache problem also does not occur if the -.I flags -argument includes -.BR CLONE_VM .) -To get the truth, it was sometimes necessary to use code such as the following: -.PP -.in +4n -.EX -#include <syscall.h> -\& -pid_t mypid; -\& -mypid = syscall(SYS_getpid); -.EE -.in -.\" See also the following bug reports -.\" https://bugzilla.redhat.com/show_bug.cgi?id=417521 -.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910 -.PP -Because of the stale-cache problem, as well as other problems noted in -.BR getpid (2), -the PID caching feature was removed in glibc 2.25. -.SH EXAMPLES -The following program demonstrates the use of -.BR clone () -to create a child process that executes in a separate UTS namespace. -The child changes the hostname in its UTS namespace. -Both parent and child then display the system hostname, -making it possible to see that the hostname -differs in the UTS namespaces of the parent and child. -For an example of the use of this program, see -.BR setns (2). -.PP -Within the sample program, we allocate the memory that is to -be used for the child's stack using -.BR mmap (2) -rather than -.BR malloc (3) -for the following reasons: -.IP \[bu] 3 -.BR mmap (2) -allocates a block of memory that starts on a page -boundary and is a multiple of the page size. -This is useful if we want to establish a guard page (a page with protection -.BR PROT_NONE ) -at the end of the stack using -.BR mprotect (2). -.IP \[bu] -We can specify the -.B MAP_STACK -flag to request a mapping that is suitable for a stack. -For the moment, this flag is a no-op on Linux, -but it exists and has effect on some other systems, -so we should include it for portability. -.SS Program source -.\" SRC BEGIN (clone.c) -.EX -#define _GNU_SOURCE -#include <err.h> -#include <sched.h> -#include <signal.h> -#include <stdint.h> -#include <stdio.h> -#include <stdlib.h> -#include <string.h> -#include <sys/mman.h> -#include <sys/utsname.h> -#include <sys/wait.h> -#include <unistd.h> -\& -static int /* Start function for cloned child */ -childFunc(void *arg) -{ - struct utsname uts; -\& - /* Change hostname in UTS namespace of child. */ -\& - if (sethostname(arg, strlen(arg)) == \-1) - err(EXIT_FAILURE, "sethostname"); -\& - /* Retrieve and display hostname. */ -\& - if (uname(&uts) == \-1) - err(EXIT_FAILURE, "uname"); - printf("uts.nodename in child: %s\en", uts.nodename); -\& - /* Keep the namespace open for a while, by sleeping. - This allows some experimentation\-\-for example, another - process might join the namespace. */ -\& - sleep(200); -\& - return 0; /* Child terminates now */ -} -\& -#define STACK_SIZE (1024 * 1024) /* Stack size for cloned child */ -\& -int -main(int argc, char *argv[]) -{ - char *stack; /* Start of stack buffer */ - char *stackTop; /* End of stack buffer */ - pid_t pid; - struct utsname uts; -\& - if (argc < 2) { - fprintf(stderr, "Usage: %s <child\-hostname>\en", argv[0]); - exit(EXIT_SUCCESS); - } -\& - /* Allocate memory to be used for the stack of the child. */ -\& - stack = mmap(NULL, STACK_SIZE, PROT_READ | PROT_WRITE, - MAP_PRIVATE | MAP_ANONYMOUS | MAP_STACK, \-1, 0); - if (stack == MAP_FAILED) - err(EXIT_FAILURE, "mmap"); -\& - stackTop = stack + STACK_SIZE; /* Assume stack grows downward */ -\& - /* Create child that has its own UTS namespace; - child commences execution in childFunc(). */ -\& - pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]); - if (pid == \-1) - err(EXIT_FAILURE, "clone"); - printf("clone() returned %jd\en", (intmax_t) pid); -\& - /* Parent falls through to here */ -\& - sleep(1); /* Give child time to change its hostname */ -\& - /* Display hostname in parent\[aq]s UTS namespace. This will be - different from hostname in child\[aq]s UTS namespace. */ -\& - if (uname(&uts) == \-1) - err(EXIT_FAILURE, "uname"); - printf("uts.nodename in parent: %s\en", uts.nodename); -\& - if (waitpid(pid, NULL, 0) == \-1) /* Wait for child */ - err(EXIT_FAILURE, "waitpid"); - printf("child has terminated\en"); -\& - exit(EXIT_SUCCESS); -} -.EE -.\" SRC END -.SH SEE ALSO -.BR fork (2), -.BR futex (2), -.BR getpid (2), -.BR gettid (2), -.BR kcmp (2), -.BR mmap (2), -.BR pidfd_open (2), -.BR set_thread_area (2), -.BR set_tid_address (2), -.BR setns (2), -.BR tkill (2), -.BR unshare (2), -.BR wait (2), -.BR capabilities (7), -.BR namespaces (7), -.BR pthreads (7) |