mirror of https://github.com/mkerrisk/man-pages
505 lines
14 KiB
Groff
505 lines
14 KiB
Groff
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
.\"
|
|
.\" Copyright (c) 1992 Drew Eckhardt <drew@cs.colorado.edu>, March 28, 1992
|
|
.\" and Michael Kerrisk, 2001, 2002
|
|
.\" May be distributed under the GNU General Public License.
|
|
.\" 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 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 protype in <sched.h>)
|
|
.\" various other minor tidy ups and clarifications.
|
|
.\" Modified 26 Jun 2001 by Michael Kerrisk <mtk-manpages@gmx.net>
|
|
.\" Updated notes for 2.4.7+ behaviour of CLONE_THREAD
|
|
.\" Modified 15 Oct 2002 by Michael Kerrisk <mtk-manpages@gmx.net>
|
|
.\" Added description for CLONE_NEWNS, which was added in 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.
|
|
.\"
|
|
.TH CLONE 2 2004-09-10 "Linux 2.6" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
clone \- create a child process
|
|
.SH SYNOPSIS
|
|
.B #include <sched.h>
|
|
.sp
|
|
.BI "int clone(int (*" "fn" ")(void *), void *" "child_stack" ", int " "flags" ", void *" "arg" );
|
|
.sp
|
|
.BI "_syscall2(int, " clone ", int, " flags ", void *, " child_stack )
|
|
.sp
|
|
.BI "_syscall5(int, " clone ", int, " flags ", void *, " child_stack ,
|
|
.br
|
|
.BI " int *, " parent_tidptr ", struct user_desc *, " newtls ,
|
|
.br
|
|
.BI " int *, " child_tidptr )
|
|
.SH DESCRIPTION
|
|
.B clone
|
|
creates a new process, just like
|
|
.BR fork (2).
|
|
.B clone
|
|
is a library function layered on top
|
|
of the underlying
|
|
.BR clone
|
|
system call, hereinafter referred to as
|
|
.BR sys_clone .
|
|
A description of
|
|
.BR sys_clone
|
|
is given towards the end of this page.
|
|
|
|
Unlike
|
|
.BR fork (2),
|
|
these calls
|
|
allow the child process to share parts of its execution context with
|
|
the calling process, such as the memory 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.)
|
|
|
|
The main use of
|
|
.B 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
|
|
.BR clone ,
|
|
it executes the function
|
|
application
|
|
.IR fn ( arg ).
|
|
(This differs from
|
|
.BR fork (2),
|
|
where execution continues in the child from the point
|
|
of the
|
|
.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.
|
|
|
|
When the
|
|
.IR fn ( arg )
|
|
function application returns, the child process terminates. The
|
|
integer returned by
|
|
.I fn
|
|
is the exit code for the child process. The child process may also
|
|
terminate explicitly by calling
|
|
.BR exit (2)
|
|
or after receiving a fatal signal.
|
|
|
|
The
|
|
.I 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
|
|
.BR clone .
|
|
Stacks grow downwards on all processors that run Linux
|
|
(except the HP PA processors), so
|
|
.I child_stack
|
|
usually points to the topmost address of the memory space set up for
|
|
the child stack.
|
|
|
|
The low byte of
|
|
.I flags
|
|
contains the number of the signal sent to the parent when the child
|
|
dies. 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 is specified, then the parent process is not signaled
|
|
when the child terminates.
|
|
|
|
.I 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:
|
|
|
|
.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.
|
|
|
|
If
|
|
.B CLONE_PARENT
|
|
is not set, then (as with
|
|
.BR fork (2))
|
|
the child's parent is the calling process.
|
|
|
|
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, will be signaled.
|
|
|
|
.TP
|
|
.B CLONE_FS
|
|
If
|
|
.B CLONE_FS
|
|
is set, the caller and the child processes share the same file system
|
|
information. This includes the root of the file system, 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 takes effect in the
|
|
other process.
|
|
|
|
If
|
|
.B CLONE_FS
|
|
is not set, the child process works on a copy of the file system
|
|
information of the calling process at the time of the
|
|
.BR clone
|
|
call.
|
|
Calls to
|
|
.BR chroot (2),
|
|
.BR chdir (2),
|
|
.BR umask (2)
|
|
performed later by one of the processes do not affect the other process.
|
|
|
|
.TP
|
|
.B CLONE_FILES
|
|
If
|
|
.B 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 process. 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, the other process is also affected.
|
|
|
|
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
|
|
.BR clone .
|
|
Operations on file descriptors performed later by either the calling process or
|
|
the child process do not affect the other process.
|
|
|
|
.TP
|
|
.BR CLONE_NEWNS " (since Linux 2.4.19)
|
|
Start the child in a new namespace.
|
|
|
|
Every process lives in a namespace. The
|
|
.I namespace
|
|
of a process is the data (the set of mounts) describing the file hierarchy
|
|
as seen by that process. After a
|
|
.BR fork (2)
|
|
or
|
|
.BR clone (2)
|
|
where the
|
|
.B CLONE_NEWNS
|
|
flag is not set, the child lives in the same namespace as the parent.
|
|
The system calls
|
|
.BR mount (2)
|
|
and
|
|
.BR umount (2)
|
|
change the namespace of the calling process, and hence affect
|
|
all processes that live in the same namespace, but do not affect
|
|
processes in a different namespace.
|
|
|
|
After a
|
|
.BR clone (2)
|
|
where the
|
|
.B CLONE_NEWNS
|
|
flag is set, the cloned child is started in a new namespace,
|
|
initialized with a copy of the namespace of the parent.
|
|
|
|
Only a privileged process (one having the CAP_SYS_ADMIN capability)
|
|
may specify the
|
|
.B CLONE_NEWNS
|
|
flag.
|
|
It is not permitted to specify both
|
|
.B CLONE_NEWNS
|
|
and
|
|
.B CLONE_FS
|
|
in the same
|
|
.BR clone
|
|
call.
|
|
|
|
.TP
|
|
.B CLONE_SIGHAND
|
|
If
|
|
.B 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
|
|
.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 some signals using
|
|
.BR sigprocmask (2)
|
|
without affecting the other process.
|
|
|
|
If
|
|
.B CLONE_SIGHAND
|
|
is not set, the child process inherits a copy of the signal handlers
|
|
of the calling process at the time
|
|
.B clone
|
|
is called. Calls to
|
|
.BR sigaction (2)
|
|
performed later by one of the processes have no effect on the other
|
|
process.
|
|
|
|
.TP
|
|
.B CLONE_PTRACE
|
|
If
|
|
.B CLONE_PTRACE
|
|
is specified, and the calling process is being traced, then trace the child also (see
|
|
.BR ptrace (2)).
|
|
|
|
.TP
|
|
.B CLONE_VFORK
|
|
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)).
|
|
|
|
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
|
|
.B CLONE_VM
|
|
If
|
|
.B CLONE_VM
|
|
is set, the calling process and the child processes 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.
|
|
|
|
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
|
|
.BR clone .
|
|
Memory writes or file mappings/unmappings performed by one of the
|
|
processes do not affect the other, as with
|
|
.BR fork (2).
|
|
|
|
.TP
|
|
.BR CLONE_PID " (obsolete)"
|
|
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
|
|
specified only by the system boot process (PID 0).
|
|
It disappeared in Linux 2.5.16.
|
|
|
|
.TP
|
|
.BR CLONE_THREAD " (since Linux 2.4.0-test8)"
|
|
If
|
|
.B CLONE_THREAD
|
|
is set, the child is placed in the same thread group as the calling process.
|
|
.\" For a while there was CLONE_DETACHED (introduced in 2.5.32):
|
|
.\" parent wants no child-exit signal. In 2.6.2 the need to give this
|
|
.\" together with CLONE_THREAD disappeared.
|
|
|
|
If
|
|
.B 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
|
|
since 2.4, calls to
|
|
.BR getpid (2)
|
|
return the thread group ID of the caller.)
|
|
|
|
.TP
|
|
.BR CLONE_SETTLS " (since Linux 2.5.32)"
|
|
The
|
|
.I newtls
|
|
parameter is the new TLS (Thread Local Storage) descriptor.
|
|
(See
|
|
.BR set_thread_area (2).)
|
|
|
|
.TP
|
|
.BR CLONE_PARENT_SETTID " (since Linux 2.5.49)"
|
|
Store child thread ID at location
|
|
.I parent_tidptr
|
|
in parent and child memory.
|
|
(In Linux 2.5.32-2.5.48 there was a flag CLONE_SETTID that did this.)
|
|
|
|
.TP
|
|
.BR CLONE_CHILD_SETTID " (since Linux 2.5.49)"
|
|
Store child thread ID at location
|
|
.I child_tidptr
|
|
in child memory.
|
|
|
|
.TP
|
|
.BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)"
|
|
Erase child thread ID at location
|
|
.I child_tidptr
|
|
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.
|
|
|
|
|
|
.SS "sys_clone"
|
|
The
|
|
.B sys_clone
|
|
system call corresponds more closely to
|
|
.BR fork (2)
|
|
in that execution in the child continues from the point of the
|
|
call. Thus,
|
|
.B sys_clone
|
|
only requires the
|
|
.I flags
|
|
and
|
|
.I child_stack
|
|
arguments, which have the same meaning as for
|
|
.BR clone .
|
|
(Note that the order of these arguments differs from
|
|
.BR clone .)
|
|
|
|
Another difference for
|
|
.B sys_clone
|
|
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.
|
|
|
|
Since Linux 2.5.49 the system call has five parameters.
|
|
The two new parameters are
|
|
.I parent_tidptr
|
|
which points to the location (in parent and child memory) where
|
|
the parent thread ID will be written in case CLONE_PARENT_SETTID
|
|
was specified, and
|
|
.I child_tidptr
|
|
which points to the location (in child memory) where the child thread ID
|
|
will be written in case CLONE_CHILD_SETTID was specified.
|
|
|
|
.SH "RETURN VALUE"
|
|
.\" gettid() returns current->pid;
|
|
.\" getpid() returns current->tgid;
|
|
On success, the thread ID 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
|
|
.I errno
|
|
will be set appropriately.
|
|
|
|
.SH ERRORS
|
|
.TP
|
|
.B EAGAIN
|
|
Too many processes are already running.
|
|
.TP
|
|
.B EINVAL
|
|
.B CLONE_SIGHAND
|
|
was specified, but
|
|
.B CLONE_VM
|
|
was not. (Since Linux 2.6.0-test6.)
|
|
.TP
|
|
.B EINVAL
|
|
.B CLONE_THREAD
|
|
was specified, 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
|
|
Both
|
|
.B CLONE_FS
|
|
and
|
|
.B CLONE_NEWNS
|
|
were specified in
|
|
.IR flags .
|
|
.TP
|
|
.B EINVAL
|
|
Returned by
|
|
.B clone
|
|
when a zero value is specified for
|
|
.IR child_stack .
|
|
.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
|
|
.B EPERM
|
|
.B CLONE_NEWNS
|
|
was specified by a non-root process (process without CAP_SYS_ADMIN).
|
|
.TP
|
|
.B EPERM
|
|
.B CLONE_PID
|
|
was specified by a process other than process 0.
|
|
|
|
.SH AVAILABILITY
|
|
There is no entry for
|
|
.B clone
|
|
in libc5. glibc2 provides
|
|
.B clone
|
|
as described in this manual page.
|
|
|
|
.SH NOTES
|
|
For kernel versions 2.4.7-2.4.18 the CLONE_THREAD flag implied the
|
|
CLONE_PARENT flag.
|
|
|
|
.SH "CONFORMING TO"
|
|
The
|
|
.B clone
|
|
and
|
|
.B sys_clone
|
|
calls are Linux-specific and should not be used in programs
|
|
intended to be portable.
|
|
|
|
.SH "SEE ALSO"
|
|
.BR fork (2),
|
|
.BR getpid (2),
|
|
.BR gettid (2),
|
|
.BR wait (2),
|
|
.BR capabilities (7)
|