.\" 2008-11-19, mtk, document CLONE_NEWIPC
.\" 2008-11-19, Jens Axboe, mtk, document CLONE_IO
.\"
-.TH CLONE 2 2017-05-03 "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
.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".
.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.
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
in the child's memory.
The store operation completes before
.BR clone ()
-returns control to user space.
+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
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,
+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
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
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/
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.
.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
.BR CLONE_NEWUSER
required that the caller have three capabilities:
.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)"
.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
.TP
.BR CLONE_SETTLS " (since Linux 2.5.32)"
The TLS (Thread Local Storage) descriptor is set to
-.I newtls.
+.IR newtls .
.IP
The interpretation of
.I newtls
On x86,
.I newtls
is interpreted as a
-.IR "struct user_desc *"
-(See
+.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
-.I ARCH_SET_FS
+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
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
performed later by one of the processes have no effect on the other
process.
.IP
-Since Linux 2.6.0-test6,
+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
.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.
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).
.IP
-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.
+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
-.BR kill (2)
-is used to send a signal to a thread group,
+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
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.
-In addition, there are variations across architectures.
+.PP
+Another difference for the raw
+.BR clone ()
+system call is that the
+.I child_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.
+(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, and alpha) is roughly:
+(including sh, tile, ia-64, and alpha) is:
.PP
.in +4
.EX
.BI " unsigned long " newtls );
.EE
.in
-.PP
-Another difference for the raw 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.
-In this case, for correct operation, the
-.B CLONE_VM
-option should not be specified.
.\"
.SS blackfin, m68k, and sparc
.\" Mike Frysinger noted in a 2013 mail:
.SS ia64
On ia64, a different interface is used:
.PP
-.nf
+.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
.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
#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);
}
projects / thirdparty / man-pages.git / blobdiff