.\" 2008-11-19, mtk, document CLONE_NEWIPC
.\" 2008-11-19, Jens Axboe, mtk, document CLONE_IO
.\"
-.TH CLONE 2 2014-09-21 "Linux" "Linux Programmer's Manual"
+.TH CLONE 2 2016-12-12 "Linux" "Linux Programmer's Manual"
.SH NAME
clone, __clone2 \- create a child process
.SH SYNOPSIS
.nf
/* Prototype for the glibc wrapper function */
+.B #define _GNU_SOURCE
.B #include <sched.h>
.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 );
+/* For the prototype of the raw system call, see NOTES */
.fi
-.sp
-.in -4n
-Feature Test Macro Requirements for glibc wrapper function (see
-.BR feature_test_macros (7)):
-.in
-.sp
-.BR clone ():
-.ad l
-.RS 4
-.PD 0
-.TP 4
-Since glibc 2.14:
-_GNU_SOURCE
-.TP 4
-.\" See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749
-Before glibc 2.14:
-_BSD_SOURCE || _SVID_SOURCE
- /* _GNU_SOURCE also suffices */
-.PD
-.RE
-.ad b
.SH DESCRIPTION
.BR clone ()
creates a new process, in a manner similar to
.B CLONE_PARENT
below.)
-The main use of
+One use of
.BR clone ()
is to implement threads: multiple threads of control in a program that
run concurrently in a shared memory space.
and the child process:
.TP
.BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)"
-Erase child thread ID at 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.
This is used by threading libraries.
.TP
.BR CLONE_CHILD_SETTID " (since Linux 2.5.49)"
-Store child thread ID at location
+Store the child thread ID at the location
.I ctid
-in child memory.
+in the child's memory.
+The store operation completes before
+.BR clone ()
+returns control to user space.
.TP
.BR CLONE_FILES " (since Linux 2.0)"
If
.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).
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 ().
-(The duplicated file descriptors in the child refer to the
-same open file descriptions (see
-.BR open (2))
-as the corresponding file descriptors in the calling process.)
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
the new process has its own I/O context.
.\" The following based on text from Jens Axboe
-The I/O context is the I/O scope of the disk scheduler (i.e,
+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.
.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.
+This flag is intended for the implementation of containers.
+
+For further information on cgroup namespaces, see
+.BR cgroup_namespaces (7).
+
+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 not set, the child lives in the same mount
namespace as the parent.
-For further information on mount namespaces, see
-.BR namespaces (7).
-
Only a privileged process
.RB ( CAP_SYS_ADMIN )
can employ
in the same
.BR clone ()
call.
+
+For further information on mount namespaces, see
+.BR namespaces (7)
+and
+.BR mount_namespaces (7).
.TP
.BR CLONE_NEWPID " (since Linux 2.6.24)"
.\" This explanation draws a lot of details from
For further information on PID namespaces, see
.BR namespaces (7)
and
-.BR pid_namespaces (7)
+.BR pid_namespaces (7).
Only a privileged process
.RB ( CAP_SYS_ADMIN )
.BR clone ()
in Linux 2.6.23,
the current
-.BR clone()
+.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.)
calling process itself, will be signaled.
.TP
.BR CLONE_PARENT_SETTID " (since Linux 2.5.49)"
-Store child thread ID at location
+Store the child thread ID at the location
.I ptid
-in parent and child memory.
+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
+.BR clone ()
+returns control to user space.
.TP
.BR CLONE_PID " (obsolete)"
If
Since 2.3.21 this flag can 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.
.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
+.I newtls.
+
+The interpretation of
.I newtls
-argument is the new TLS (Thread Local Storage) descriptor.
+and the resulting effect is architecture dependent.
+On x86,
+.I newtls
+is interpreted as a
+.IR "struct user_desc *"
(See
-.BR set_thread_area (2).)
+.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
+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
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
+.BR CLONE_NEWCGROUP
+flag.
.TP
.BR CLONE_SYSVSEM " (since Linux 2.5.10)"
If
Memory writes or file mappings/unmappings performed by one of the
processes do not affect the other, as with
.BR fork (2).
-.SS C library/kernel ABI differences
+.SS C library/kernel differences
The raw
.BR clone ()
system call corresponds more closely to
.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 addition, there are variations across architectures.
+
+The raw system call interface on x86-64 and some other architectures
+(including sh, tile, and alpha) is roughly:
+
.in +4
.nf
+.BI "long clone(unsigned long " flags ", void *" child_stack ,
+.BI " int *" ptid ", int *" ctid ,
+.BI " unsigned long " newtls );
+.fi
+.in
+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:
+
+.in +4
+.nf
.BI "long clone(unsigned long " flags ", void *" child_stack ,
-.BI " void *" ptid ", void *" ctid ,
-.BI " struct pt_regs *" regs );
+.BI " int *" ptid ", unsigned long " newtls ,
+.BI " int *" ctid );
+.fi
+.in
+
+On the cris and s390 architectures,
+.\" CONFIG_CLONE_BACKWARDS2
+the order of the first two arguments is reversed:
+
+.in +4
+.nf
+.BI "long clone(void *" child_stack ", unsigned long " flags ,
+.BI " int *" ptid ", int *" ctid ,
+.BI " unsigned long " newtls );
+.fi
+.in
+On the microblaze architecture,
+.\" CONFIG_CLONE_BACKWARDS3
+an additional argument is supplied:
+
+.in +4
+.nf
+.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 );
.fi
.in
+
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
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.
-On the cris and s390 architectures,
-the order of the first and second arguments is reversed.
+.\"
.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.
.IR flags .
.TP
.B EINVAL
-Returned by
+Returned by the glibc
.BR clone ()
-when a zero value is specified for
-.IR child_stack .
+wrapper function when
+.IR fn
+or
+.IR child_stack
+is specified as NULL.
.TP
.B EINVAL
.BR CLONE_NEWIPC
.B CONFIG_UTS
option.
.TP
+.B EINVAL
+.I child_stack
+is not aligned to a suitable boundary for this architecture.
+For example, on aarch64,
+.I child_stack
+must be a multiple of 16.
+.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
.TP
.BR EPERM " (since Linux 3.9)"
.\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d
-.B CLONE_NEWUSER was specified in
+.B CLONE_NEWUSER
+was specified in
.I flags
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 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 " (since Linux 3.11)"
.B CLONE_NEWUSER
was specified in
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.
+.\" .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
intended to be portable.
.SH NOTES
-In the kernel 2.4.x series,
+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.
+
+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).
For a while there was
.B CLONE_DETACHED
(introduced in 2.5.32):
parent wants no child-exit signal.
-In 2.6.2 the need to give this
-together 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.
projects / thirdparty / man-pages.git / blobdiff