.\" 2008-11-19, mtk, document CLONE_NEWIPC
.\" 2008-11-19, Jens Axboe, mtk, document CLONE_IO
.\"
-.TH CLONE 2 2016-07-17 "Linux" "Linux Programmer's Manual"
+.TH CLONE 2 2019-08-02 "Linux" "Linux Programmer's Manual"
.SH NAME
clone, __clone2 \- create a child process
.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 *), void *" child_stack ,
.BI " int " flags ", void *" "arg" ", ... "
-.BI " /* pid_t *" ptid ", struct user_desc *" tls \
+.BI " /* pid_t *" ptid ", void *" newtls \
", pid_t *" ctid " */ );"
-
-/* Prototype for the raw system call */
-
-.BI "long clone(unsigned long " flags ", void *" child_stack ,
-.BI " void *" ptid ", void *" ctid ,
-.BI " struct pt_regs *" regs );
+.PP
+/* For the prototype of the raw system call, see NOTES */
.fi
.SH DESCRIPTION
.BR clone ()
creates a new process, in a manner similar to
.BR fork (2).
-
+.PP
This page describes both 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.
-
+.PP
Unlike
.BR fork (2),
.BR clone ()
allows the child process to share parts of its execution context with
-the calling process, such as the memory space, the table of file
+the calling process, such as the virtual address space, the table of file
descriptors, and the table of signal handlers.
(Note that on this manual
page, "calling process" normally corresponds to "parent process".
But see the description of
.B CLONE_PARENT
below.)
-
+.PP
One use of
.BR clone ()
-is to implement threads: multiple threads of control in a program that
-run concurrently in a shared memory space.
-
+is to implement threads: multiple flows of control in a program that
+run concurrently in a shared address space.
+.PP
When the child process is created with
.BR clone (),
-it executes the function
-.IR fn ( arg ).
+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
.BR fork (2)
call.)
The
-.I fn
-argument is a pointer to a function that is called by the child
-process at the beginning of its execution.
-The
.I arg
-argument is passed to the
-.I fn
-function.
-
+argument is passed as the argument of the function
+.IR fn .
+.PP
When the
.IR fn ( arg )
-function application returns, the child process terminates.
+function returns, the child process terminates.
The integer returned by
.I fn
-is the exit code for the child process.
+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 child_stack
argument specifies the location of the stack used by the child process.
.I child_stack
usually points to the topmost address of the memory space set up for
the child stack.
-
+.PP
The low byte of
.I flags
contains the number of the
.BR wait (2).
If no signal is specified, then the parent process is not signaled
when the child terminates.
-
+.PP
.I flags
-may also be bitwise-or'ed with zero or more of the following constants,
+may also be bitwise-ORed with zero or more of the following constants,
in order to specify what is shared between the calling process
and the child process:
.TP
.BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)"
-Erase the child thread ID at the location
+Clear (zero) the child thread ID at the location
.I ctid
in child memory when the child exits, and do a wakeup on the futex
at that address.
Store the child thread ID at the location
.I ctid
in the child's memory.
+The store operation completes before
+.BR clone ()
+returns control to user space in the child process.
+(Note that the store operation may not have completed before
+.BR clone ()
+returns in the parent process, which will be relevant if the
+.BR CLONE_VM
+flag is also employed.)
.TP
.BR CLONE_FILES " (since Linux 2.0)"
If
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
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 files status flags (see
+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)"
.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
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
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).
.BR 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.
.BR fork (2))
the process is created in the same cgroup namespaces as the calling process.
This flag is intended for the implementation of containers.
-
+.IP
For further information on cgroup namespaces, see
.BR cgroup_namespaces (7).
-
+.IP
Only a privileged process
.RB ( CAP_SYS_ADMIN )
can employ
the process is created in the same IPC namespace as
the calling process.
This flag is intended for the implementation of containers.
-
+.IP
An IPC namespace provides an isolated view of System\ V IPC objects (see
-.BR svipc (7))
+.BR sysvipc (7))
and (since Linux 2.6.30)
.\" commit 7eafd7c74c3f2e67c27621b987b28397110d643f
.\" https://lwn.net/Articles/312232/
The common characteristic of these IPC mechanisms is that IPC
objects are identified by mechanisms other than filesystem
pathnames.
-
+.IP
Objects created in an IPC namespace are visible to all other processes
that are members of that namespace,
but are not visible to processes in other IPC namespaces.
-
+.IP
When an IPC namespace is destroyed
(i.e., when the last process that is a member of the namespace terminates),
all IPC objects in the namespace are automatically destroyed.
-
+.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 .
-
+.IP
For further information on IPC namespaces, see
.BR namespaces (7).
.TP
.BR CLONE_NEWNET " (since Linux 2.6.24)"
(The implementation of this flag was completed only
by about kernel version 2.6.29.)
-
+.IP
If
.B CLONE_NEWNET
is set, then create the process in a new network namespace.
the process is created in the same network namespace as
the calling process.
This flag is intended for the implementation of containers.
-
+.IP
A network namespace provides an isolated view of the networking stack
(network device interfaces, IPv4 and IPv6 protocol stacks,
IP routing tables, firewall rules, the
directory trees, sockets, etc.).
A physical network device can live in exactly one
network namespace.
-A virtual network device ("veth") pair provides a pipe-like abstraction
-.\" FIXME . Add pointer to veth(4) page when it is eventually completed
+A virtual network
+.RB ( veth (4))
+device pair provides a pipe-like abstraction
that can be used to create tunnels between network namespaces,
and can be used to create a bridge to a physical network device
in another namespace.
-
+.IP
When a network namespace is freed
(i.e., when the last process in the namespace terminates),
its physical network devices are moved back to the
initial network namespace (not to the parent of the process).
For further information on network namespaces, see
.BR namespaces (7).
-
+.IP
Only a privileged process
.RB ( CAP_SYS_ADMIN )
can employ
.B CLONE_NEWNS
is not set, the child lives in the same mount
namespace as the parent.
-
+.IP
Only a privileged process
.RB ( CAP_SYS_ADMIN )
can employ
in the same
.BR clone ()
call.
-
+.IP
For further information on mount namespaces, see
.BR namespaces (7)
and
the process is created in the same PID namespace as
the calling process.
This flag is intended for the implementation of containers.
-
+.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
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.
-
-For further information on user namespaces, see
-.BR namespaces (7)
-and
-.BR user_namespaces (7)
-
+.IP
Before Linux 3.8, use of
.BR CLONE_NEWUSER
required that the caller have three capabilities:
.\" 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
.BR CLONE_THREAD
or
.BR CLONE_NEWUSER
cannot be specified in conjunction with
.BR CLONE_FS .
-
+.IP
For further information on user namespaces, see
+.BR namespaces (7)
+and
.BR user_namespaces (7).
.TP
.BR CLONE_NEWUTS " (since Linux 2.6.19)"
the process is created in the same UTS namespace as
the calling process.
This flag is intended for the implementation of containers.
-
+.IP
A UTS namespace is the set of identifiers returned by
.BR uname (2);
among these, the domain name and the hostname can be modified by
Changes made to the identifiers in a UTS namespace
are visible to all other processes in the same namespace,
but are not visible to processes in other UTS namespaces.
-
+.IP
Only a privileged process
.RB ( CAP_SYS_ADMIN )
can employ
.BR CLONE_NEWUTS .
-
+.IP
For further information on UTS namespaces, see
.BR namespaces (7).
.TP
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
(In Linux 2.5.32-2.5.48 there was a flag
.B CLONE_SETTID
that did this.)
+The store operation completes before
+.BR clone ()
+returns control to user space.
.TP
-.BR CLONE_PID " (obsolete)"
+.BR CLONE_PID " (Linux 2.0 to 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.
-Since 2.3.21 this flag can be
+From Linux 2.3.21 onward, this flag could be
specified only by the system boot process (PID 0).
-It disappeared in Linux 2.5.16.
-Since then, the kernel silently ignores it without error.
+The flag disappeared completely from the kernel sources in Linux 2.5.16.
+Since then, the kernel silently ignores this bit if it is specified in
+.IR flags .
.TP
.BR CLONE_PTRACE " (since Linux 2.2)"
If
.BR ptrace (2)).
.TP
.BR CLONE_SETTLS " (since Linux 2.5.32)"
-The
+The TLS (Thread Local Storage) descriptor is set to
+.IR newtls .
+.IP
+The interpretation of
+.I newtls
+and the resulting effect is architecture dependent.
+On x86,
.I newtls
-argument is the new TLS (Thread Local Storage) descriptor.
-(See
-.BR set_thread_area (2).)
+is interpreted as a
+.IR "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.
.TP
.BR CLONE_SIGHAND " (since Linux 2.0)"
If
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 some signals using
+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
.BR sigaction (2)
performed later by one of the processes have no effect on the other
process.
-
-Since Linux 2.6.0-test6,
+.IP
+Since Linux 2.6.0,
+.\" Precisely: Linux 2.6.0-test6
.I flags
must also include
.B CLONE_VM
.B CLONE_SIGHAND
is specified
.TP
-.BR CLONE_STOPPED " (since Linux 2.6.0-test2)"
+.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
signal), and must be resumed by sending it a
.B SIGCONT
signal.
-
+.IP
This flag was
.I deprecated
from Linux 2.6.25 onward,
.I semadj
list that is initially empty.
.TP
-.BR CLONE_THREAD " (since Linux 2.4.0-test8)"
+.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.
.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
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
and a thread can obtain
its own TID using
.BR gettid (2).
-
+.IP
When a call is made to
.BR clone ()
without specifying
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 caller of
.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,
.I flags
must also include
if
.B CLONE_THREAD
is specified
-(and note that, since Linux 2.6.0-test6,
+(and note that, since Linux 2.6.0,
+.\" Precisely: Linux 2.6.0-test6
.BR CLONE_SIGHAND
also requires
.BR CLONE_VM
to be included).
-
-Signals may be sent to a thread group as a whole (i.e., a TGID) using
-.BR kill (2),
-or to a specific thread (i.e., TID) using
-.BR tgkill (2).
-
+.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),
-but signals can be pending either: for the whole process
-(i.e., deliverable to any member of the thread group),
-when sent with
-.BR kill (2);
-or for an individual thread, when sent with
-.BR tgkill (2).
+.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
+.BR 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 signals pending for the
-whole process and the signals that are pending for the calling thread.
-
-If
-.BR kill (2)
-is used to send a signal to a thread group,
+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 will be 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 a signal sent using
-.BR kill (2).
+to receive the signal.
.TP
.BR CLONE_UNTRACED " (since Linux 2.5.46)"
If
.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
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
Memory writes or file mappings/unmappings performed by one of the
processes do not affect the other, as with
.BR fork (2).
+.SH NOTES
+Note that the glibc
+.BR clone ()
+wrapper function makes some changes
+in the memory pointed to by
+.I child_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.
+.\"
.SS C library/kernel differences
The raw
.BR clone ()
arguments of the
.BR clone ()
wrapper function are omitted.
-Furthermore, the argument order changes.
-The raw system call interface on x86 and many other architectures is roughly:
-.in +4
-.nf
-
-.BI "long clone(unsigned long " flags ", void *" child_stack ,
-.BI " void *" ptid ", void *" ctid ,
-.BI " struct pt_regs *" regs );
-
-.fi
-.in
-Another difference for the raw system call is that the
+.PP
+Another difference for the raw
+.BR clone ()
+system call is that the
.I child_stack
-argument may be zero, in which case copy-on-write semantics ensure that the
-child gets separate copies of stack pages when either process modifies
-the stack.
+argument may be NULL,
+in which 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.
-
-For some architectures, the order of the arguments for the system call
-differs from that shown above.
-On the score, microblaze, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa,
-and MIPS architectures,
-the order of the fourth and fifth arguments is reversed.
+(If the child
+.I shares
+the parent's memory because of the use of the
+.BR 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, ia-64, and alpha) is:
+.PP
+.in +4
+.EX
+.BI "long clone(unsigned long " flags ", void *" child_stack ,
+.BI " int *" ptid ", int *" ctid ,
+.BI " unsigned long " newtls );
+.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 +4
+.EX
+.BI "long clone(unsigned long " flags ", void *" child_stack ,
+.BI " int *" ptid ", unsigned long " newtls ,
+.BI " int *" ctid );
+.EE
+.in
+.PP
On the cris and s390 architectures,
-the order of the first and second arguments is reversed.
+.\" CONFIG_CLONE_BACKWARDS2
+the order of the first two arguments is reversed:
+.PP
+.in +4
+.EX
+.BI "long clone(void *" child_stack ", unsigned long " flags ,
+.BI " int *" ptid ", int *" ctid ,
+.BI " unsigned long " newtls );
+.EE
+.in
+.PP
+On the microblaze architecture,
+.\" CONFIG_CLONE_BACKWARDS3
+an additional argument is supplied:
+.PP
+.in +4
+.EX
+.BI "long clone(unsigned long " flags ", void *" child_stack ,
+.BI " int " stack_size , "\fR /* Size of stack */"
+.BI " int *" ptid ", int *" ctid ,
+.BI " unsigned long " newtls );
+.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:
-.nf
-
+.PP
+.in +4
+.EX
.BI "int __clone2(int (*" "fn" ")(void *), "
.BI " void *" child_stack_base ", size_t " stack_size ,
.BI " int " flags ", void *" "arg" ", ... "
.BI " /* pid_t *" ptid ", struct user_desc *" tls \
", pid_t *" ctid " */ );"
-.fi
+.EE
+.in
.PP
The prototype shown above is for the glibc wrapper function;
-the raw system call interface has no
-.I fn
-or
-.I arg
-argument, and changes the order of the arguments so that
-.I flags
-is the first argument, and
-.I tls
-is the last argument.
+for the system call itself,
+the prototype can be described as follows (it is identical to the
+.BR clone ()
+prototype on microblaze):
+.PP
+.in +4
+.EX
+.BI "long clone2(unsigned long " flags ", void *" child_stack_base ,
+.BI " int " stack_size , "\fR /* Size of stack */"
+.BI " int *" ptid ", int *" ctid ,
+.BI " unsigned long " tls );
+.EE
+.in
.PP
.BR __clone2 ()
operates in the same way as
was specified, but
.B CLONE_VM
was not.
-(Since Linux 2.6.0-test6.)
+(Since Linux 2.6.0.)
+.\" Precisely: Linux 2.6.0-test6
.TP
.B EINVAL
.B CLONE_THREAD
.\" (Since Linux 2.6.0-test6.)
.TP
.B EINVAL
+.B CLONE_THREAD
+was specified, 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
option.
.TP
.B EINVAL
+.BR CLONE_NEWUSER
+was specified in
+.IR flags ,
+but the kernel was not configured with the
+.B CONFIG_USER_NS
+option.
+.TP
+.B EINVAL
.BR CLONE_NEWUTS
was specified in
.IR flags ,
but the kernel was not configured with the
-.B CONFIG_UTS
+.B CONFIG_UTS_NS
option.
.TP
.B EINVAL
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 flags,
+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
+.IR flags ,
+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
+.I flags
+specified the creation of a new user namespace,
+but doing so would have caused the limit defined by the corresponding file in
+.IR /proc/sys/user
+to be exceeded.
+For further details, see
+.BR namespaces (7).
+.TP
.B EPERM
+.BR CLONE_NEWCGROUP ,
.BR CLONE_NEWIPC ,
.BR CLONE_NEWNET ,
.BR CLONE_NEWNS ,
.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
.BR CLONE_NEWUSER
System call was interrupted by a signal and will be restarted.
(This can be seen only during a trace.)
.TP
-.BR EUSERS " (since Linux 3.11)"
+.BR EUSERS " (Linux 3.11 to Linux 4.8)"
.B CLONE_NEWUSER
was specified in
.IR flags ,
-and the call would cause the limit on the number of
-nested user namespaces to be exceeded.
-See
-.BR user_namespaces (7).
-.SH VERSIONS
-There is no entry for
-.BR clone ()
-in libc5.
-glibc2 provides
-.BR clone ()
-as described in this manual page.
+and the limit on the number of nested user namespaces would be exceeded.
+See the discussion of the
+.BR ENOSPC
+error above.
+.\" .SH VERSIONS
+.\" There is no entry for
+.\" .BR clone ()
+.\" in libc5.
+.\" glibc2 provides
+.\" .BR clone ()
+.\" as described in this manual page.
.SH CONFORMING TO
.BR clone ()
is Linux-specific and should not be used in programs
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.
-
-In the kernel 2.4.x series,
+.PP
+.PP
+Handlers registered using
+.BR pthread_atfork (3)
+are not executed during a call to
+.BR clone ().
+.PP
+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.
.B CLONE_THREAD
flag implied the
.B CLONE_PARENT
-flag (as in kernel 2.6).
-
+flag (as in Linux 2.6.0 and later).
+.PP
For a while there was
.B CLONE_DETACHED
(introduced in 2.5.32):
parent wants no child-exit signal.
-In Linux 2.6.2, the need to give this flag ogether with
+In Linux 2.6.2, the need to give this flag together with
.B CLONE_THREAD
disappeared.
This flag is still defined, but has no effect.
-
+.PP
On i386,
.BR clone ()
should not be called through vsyscall, but directly through
.IR "int $0x80" .
.SH BUGS
-Versions of the GNU C library that include the NPTL threading library
-contain a wrapper function for
+GNU C library versions 2.3.4 up to and including 2.24
+contained a wrapper function for
.BR getpid (2)
-that performs caching of PIDs.
-This caching relies on support in the glibc wrapper for
+that performed caching of PIDs.
+This caching relied on support in the glibc wrapper for
.BR clone (),
-but as currently implemented,
-the cache may not be up to date in some circumstances.
+but limitations in the implementation
+meant that the cache was not up to date in some circumstances.
In particular,
-if a signal is delivered to the child immediately after the
+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 may return the PID
+in a handler for the signal could return the PID
of the calling process ("the parent"),
-if the clone wrapper has not yet had a chance to update the PID
+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 ,
.I flags
argument includes
.BR CLONE_VM .)
-To get the truth, it may be necessary to use code such as the following:
-.nf
-
- #include <syscall.h>
+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;
+pid_t mypid;
- mypid = syscall(SYS_getpid);
-.fi
+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 EXAMPLE
The following program demonstrates the use of
.BR clone ()
For an example of the use of this program, see
.BR setns (2).
.SS Program source
-.nf
+.EX
#define _GNU_SOURCE
#include <sys/wait.h>
#include <sys/utsname.h>
#include <stdlib.h>
#include <unistd.h>
-#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
+#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
} while (0)
static int /* Start function for cloned child */
if (uname(&uts) == \-1)
errExit("uname");
- printf("uts.nodename in child: %s\\n", uts.nodename);
+ 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
struct utsname uts;
if (argc < 2) {
- fprintf(stderr, "Usage: %s <child\-hostname>\\n", argv[0]);
+ fprintf(stderr, "Usage: %s <child\-hostname>\en", argv[0]);
exit(EXIT_SUCCESS);
}
pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]);
if (pid == \-1)
errExit("clone");
- printf("clone() returned %ld\\n", (long) pid);
+ printf("clone() returned %ld\en", (long) pid);
/* Parent falls through to here */
if (uname(&uts) == \-1)
errExit("uname");
- printf("uts.nodename in parent: %s\\n", uts.nodename);
+ printf("uts.nodename in parent: %s\en", uts.nodename);
if (waitpid(pid, NULL, 0) == \-1) /* Wait for child */
errExit("waitpid");
- printf("child has terminated\\n");
+ printf("child has terminated\en");
exit(EXIT_SUCCESS);
}
-.fi
+.EE
.SH SEE ALSO
.BR fork (2),
.BR futex (2),
projects / thirdparty / man-pages.git / blobdiff