clone - create a child process
SYNOPSIS
#include <sched.h>
int clone(int (*fn) (void *), void *child_stack, int
flags, void *arg)
_syscall2(int, clone, int, flags, void *, child_stack);
DESCRIPTION
clone creates a new process, just like fork(2). clone is
a library function layered on top of the underlying clone
system call, hereinafter referred to as sys_clone. A
description of sys_clone is given towards the end of this
page.
Unlike fork(2), these calls allow the child process to
share parts of its execution context with the calling pro
cess, such as the memory space, the table of file descrip
tors, and the table of signal handlers. (Note that on
this manual page, "calling process" normally corresponds
to "parent process". But see the description of
CLONE_PARENT below.)
The main use of clone is to implement threads: multiple
threads of control in a program that run concurrently in a
shared memory space.
When the child process is created with clone, it executes
the function application fn(arg). (This differs from
fork(2), where execution continues in the child from the
point of the fork(2) call.) The fn argument is a pointer
to a function that is called by the child process at the
beginning of its execution. The arg argument is passed to
the fn function.
When the fn(arg) function application returns, the child
process terminates. The integer returned by fn is the
exit code for the child process. The child process may
also terminate explicitely by calling exit(2) or after
receiving a fatal signal.
The child_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 clone. Stacks grow downwards on all proces
sors that run Linux (except the HP PA processors), so
child_stack usually points to the topmost address of the
The low byte of flags contains the number of the signal
sent to the parent when the child dies. If this signal is
specified as anything other than SIGCHLD, then the parent
process must specify the __WALL or __WCLONE options when
waiting for the child with wait(2). If no signal is spec
ified, then the parent process is not signaled when the
child terminates.
flags may also be bitwise-or'ed with one or several of the
following constants, in order to specify what is shared
between the calling process and the child process:
CLONE_PARENT
(Linux 2.4 onwards) If CLONE_PARENT is set, then
the parent of the new child (as returned by getp
pid(2)) will be the same as that of the calling
process.
If CLONE_PARENT is not set, then (as with fork(2))
the child's parent is the calling process.
Note that it is the parent process, as returned by
getppid(2), which is signaled when the child termi
nates, so that if CLONE_PARENT is set, then the
parent of the calling process, rather than the
calling process itself, will be signaled.
CLONE_FS
If CLONE_FS is set, the caller and the child pro
cesses share the same file system information.
This includes the root of the file system, the cur
rent working directory, and the umask. Any call to
chroot(2), chdir(2), or umask(2) performed by the
callng process or the child process also takes
effect in the other process.
If CLONE_FS is not set, the child process works on
a copy of the file system information of the call
ing process at the time of the clone call. Calls
to chroot(2), chdir(2), umask(2) performed later by
one of the processes do not affect the other pro
cess.
CLONE_FILES
If CLONE_FILES is set, the calling process and the
child processes share the same file descriptor
table. File descriptors always refer to the same
files in the calling process and in the child pro
cess. Any file descriptor created by the calling
the other process. Similarly, if one of the pro
cesses closes a file descriptor, or changes its
associated flags, the other process is also
affected.
If CLONE_FILES is not set, the child process inher
its a copy of all file descriptors opened in the
calling process at the time of clone. Operations
on file descriptors performed later by either the
calling process or the child process do not affect
the other process.
CLONE_SIGHAND
If CLONE_SIGHAND is set, the calling process and
the child processes share the same table of signal
handlers. If the calling process or child process
calls sigaction(2) to change the behavior associ
ated with a signal, the behavior is changed in the
other process as well. However, the calling pro
cess and child processes still have distinct signal
masks and sets of pending signals. So, one of them
may block or unblock some signals using sigproc
mask(2) without affecting the other process.
If CLONE_SIGHAND is not set, the child process
inherits a copy of the signal handlers of the call
ing process at the time clone is called. Calls to
sigaction(2) performed later by one of the pro
cesses have no effect on the other process.
CLONE_PTRACE
If CLONE_PTRACE is specified, and the calling pro
cess is being traced, then trace the child also
(see ptrace(2)).
CLONE_VFORK
If CLONE_VFORK is set, the execution of the calling
process is suspended until the child releases its
virtual memory resources via a call to execve(2) or
_exit(2) (as with vfork(2)).
If 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 execu
tion occurring in any particular order.
CLONE_VM
If CLONE_VM is set, the calling process and the
child processes run in the same memory space. In
process or by the child process are also visible in
the other process. Moreover, any memory mapping or
unmapping performed with mmap(2) or munmap(2) by
the child or calling process also affects the other
process.
If 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 clone. Memory writes or
file mappings/unmappings performed by one of the
processes do not affect the other, as with fork(2).
CLONE_PID
If CLONE_PID is set, the child process is created
with the same process ID as the calling process.
If CLONE_PID is not set, the child process pos
sesses a unique process ID, distinct from that of
the calling process.
This flag can only be specified by the system boot
process (PID 0).
CLONE_THREAD
(Linux 2.4 onwards) If CLONE_THREAD is set, the
child is placed in the same thread group as the
calling process.
If CLONE_THREAD is not set, then the child is
placed in its own (new) thread group, whose ID is
the same as the process ID.
(Thread groups are feature added in Linux 2.4 to
support the POSIX threads notion of a set of
threads sharing a single PID. In Linux 2.4, calls
to getpid(2) return the thread group ID of the
caller.)
The sys_clone system call corresponds more closely to
fork(2) in that execution in the child continues from the
point of the call. Thus, sys_clone only requires the
flags and child_stack arguments, which have the same mean
ing as for clone. (Note that the order of these arguments
differs from clone.)
Another difference for sys_clone is that the child_stack
argument may be zero, in which case copy-on-write seman
tics ensure that the child gets separate copies of stack
pages when either process modifies the stack. In this
case, for correct operation, the CLONE_VM option should
not be specified.
On success, the PID of the child process is returned in
the caller's thread of execution. On failure, a -1 will
be returned in the caller's context, no child process will
be created, and errno will be set appropriately.
ERRORS
EAGAIN Too many processes are already running.
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.
EINVAL Returned by clone when a zero value is specified
for child_stack.
EPERM CLONE_PID was specified by a process with a non-
zero PID.
BUGS
As of version 2.1.97 of the kernel, the CLONE_PID flag
should not be used, since other parts of the kernel and
most system software still assume that process IDs are
unique.
There is no entry for clone in libc version 5. libc 6
(a.k.a. glibc 2) provides clone as described in this man
ual page.
CONFORMING TO
The clone and sys_clone calls are Linux-specific and
should not be used in programs intended to be portable.
For programming threaded applications (multiple threads of
control in the same memory space), it is better to use a
library implementing the POSIX 1003.1c thread API, such as
the LinuxThreads library (included in glibc2). See
pthread_create(3thr).
This manual page corresponds to kernels 2.0.x, 2.1.x,
2.2.x, 2.4.x, and to glibc 2.0.x and 2.1.x.
SEE ALSO
fork(2), wait(2), pthread_create(3thr)
Man(1) output converted with
man2html