-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\"
.\" Copyright (c) 1992 Drew Eckhardt <drew@cs.colorado.edu>, March 28, 1992
-.\" and Copyright (c) Michael Kerrisk, 2001, 2002, 2005
+.\" and Copyright (c) Michael Kerrisk, 2001, 2002, 2005, 2013
+.\"
+.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
.\" May be distributed under the GNU General Public License.
+.\" %%%LICENSE_END
+.\"
.\" 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>:
.\" wrapper under BUGS.
.\" 2005-05-10, mtk, added CLONE_SYSVSEM, CLONE_UNTRACED, CLONE_STOPPED.
.\" 2005-05-17, mtk, Substantially enhanced discussion of CLONE_THREAD.
-.\" 2008-11-18, mtk, order CLONE_* flags alphabetically
+.\" 2008-11-18, mtk, order CLONE_* flags alphabetically
.\" 2008-11-18, mtk, document CLONE_NEWPID
.\" 2008-11-19, mtk, document CLONE_NEWUTS
.\" 2008-11-19, mtk, document CLONE_NEWIPC
.\"
.\" FIXME Document CLONE_NEWUSER, which is new in 2.6.23
.\" (also supported for unshare()?)
-.\" FIXME . 2.6.25 marks the unused CLONE_STOPPED as obsolete, and it will
-.\" probably be removed in the future.
.\"
-.TH CLONE 2 2009-07-18 "Linux" "Linux Programmer's Manual"
+.TH CLONE 2 2014-02-27 "Linux" "Linux Programmer's Manual"
.SH NAME
clone, __clone2 \- create a child process
.SH SYNOPSIS
.nf
-.B #define _GNU_SOURCE
-.\" Actually _BSD_SOURCE || _SVID_SOURCE
-.\" See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749
+/* Prototype for the glibc wrapper function */
+
.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 \
", 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 );
.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
.BR fork (2).
-It is actually a library function layered on top of the underlying
+
+This page describes both the glibc
.BR clone ()
-system call, hereinafter referred to as
-.BR sys_clone .
-A description of
-.B sys_clone
-is given towards the end of this page.
+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.
Unlike
.BR fork (2),
-these calls
-allow the child process to share parts of its execution context with
+.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
descriptors, and the table of signal handlers.
(Note that on this manual
When the child process is created with
.BR clone (),
it executes the function
-application
.IR fn ( arg ).
(This differs from
.BR fork (2),
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
+Stacks grow downward 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
.I ctid
in child memory.
.TP
-.B CLONE_FILES
+.BR CLONE_FILES " (since Linux 2.0)"
If
.B CLONE_FILES
is set, the calling process and the child process share the same file
performed by either the calling
process or the child process do not affect the other process.
.TP
-.B CLONE_FS
+.BR CLONE_FS " (since Linux 2.0)"
If
.B CLONE_FS
-is set, the caller and the child process share the same file system
+is set, the caller and the child process share the same filesystem
information.
-This includes the root of the file system, the current
+This includes the root of the filesystem, the current
working directory, and the umask.
Any call to
.BR chroot (2),
If
.B CLONE_FS
-is not set, the child process works on a copy of the file system
+is not set, the child process works on a copy of the filesystem
information of the calling process at the time of the
.BR clone ()
call.
the calling process.
This flag is intended for the implementation of containers.
-An IPC namespace consists of the set of identifiers for
-System V IPC objects.
-(These objects are created using
-.BR msgctl (2),
-.BR semctl (2),
-and
-.BR shmctl (2)).
+An IPC namespace provides an isolated view of System V IPC objects (see
+.BR svipc (7))
+and (since Linux 2.6.30)
+.\" commit 7eafd7c74c3f2e67c27621b987b28397110d643f
+.\" https://lwn.net/Articles/312232/
+POSIX message queues
+(see
+.BR mq_overview (7)).
+The common characteristic of these IPC mechanisms is that IPC
+objects are identified by mechanisms other than filesystem
+pathnames.
+
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.
When an IPC namespace is destroyed
-(i.e, when the last process that is a member of the namespace terminates),
+(i.e., when the last process that is a member of the namespace terminates),
all IPC objects in the namespace are automatically destroyed.
Use of this flag requires: a kernel configured with the
.BR CLONE_SYSVSEM .
.TP
.BR CLONE_NEWNET " (since Linux 2.6.24)"
-(The implementation of this flag is not yet complete,
-but probably will be mostly complete by about Linux 2.6.28.)
+.\" FIXME Check when the implementation was completed
+(The implementation of this flag was completed only
+by about kernel version 2.6.29.)
If
.B CLONE_NEWNET
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
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),
.BR vfork (2),
or
-.BR clone (2)
+.BR clone ()
will produce processes with PIDs that are unique within the namespace.
The first process created in a new namespace
A UTS namespace is the set of identifiers returned by
.BR uname (2);
-among these, the domain name and the host name can be modified by
+among these, the domain name and the hostname can be modified by
.BR setdomainname (2)
and
-.BR
.BR sethostname (2),
respectively.
Changes made to the identifiers in a UTS namespace
specified only by the system boot process (PID 0).
It disappeared in Linux 2.5.16.
.TP
-.B CLONE_PTRACE
+.BR CLONE_PTRACE " (since Linux 2.2)"
If
.B CLONE_PTRACE
is specified, and the calling process is being traced,
(See
.BR set_thread_area (2).)
.TP
-.B CLONE_SIGHAND
+.BR CLONE_SIGHAND " (since Linux 2.0)"
If
.B CLONE_SIGHAND
is set, the calling process and the child process share the same table of
.B SIGCONT
signal.
-.I "From Linux 2.6.25 this flag is deprecated."
-You probably never wanted to use it,
-you certainly shouldn't be using it, and soon it will go away.
+This flag was
+.I deprecated
+from Linux 2.6.25 onward,
+and was
+.I removed
+altogether in Linux 2.6.38.
.\" glibc 2.8 removed this defn from bits/sched.h
.TP
.BR CLONE_SYSVSEM " (since Linux 2.5.10)"
.B CLONE_SIGHAND
if
.B CLONE_THREAD
-is specified.
+is specified
+(and note that, since 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),
.B CLONE_PTRACE
on this child process.
.TP
-.B CLONE_VFORK
+.BR CLONE_VFORK " (since Linux 2.2)"
If
.B CLONE_VFORK
is set, the execution of the calling process is suspended
If
.B CLONE_VFORK
-is not set then both the calling process and the child are schedulable
+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
+.BR CLONE_VM " (since Linux 2.0)"
If
.B CLONE_VM
is set, the calling process and the child process run in the same memory
Memory writes or file mappings/unmappings performed by one of the
processes do not affect the other, as with
.BR fork (2).
-.SS "sys_clone"
-The
-.B sys_clone
+.SS The raw system call interface
+The raw
+.BR 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
+As such, the
+.I fn
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 ().)
+.I arg
+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 );
-Another difference for
-.B sys_clone
-is that the
+.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
child gets separate copies of stack pages when either process modifies
.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
+The argument-passing conventions on
+blackfin, m68k, and sparc are different from descriptions above.
+For details, see the kernel (and glibc) source.
+.SS ia64
+On ia64, a different interface is used:
+.nf
+
+.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
+.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.
+.PP
+.BR __clone2 ()
+operates in the same way as
+.BR clone (),
+except that
+.I child_stack_base
+points to the lowest address of the child's stack area,
+and
+.I stack_size
+specifies the size of the stack pointed to by
+.IR child_stack_base .
+.SS Linux 2.4 and earlier
In Linux 2.4 and earlier,
.BR clone ()
does not take arguments
.IR tls ,
and
.IR ctid .
-.SH "RETURN VALUE"
+.SH RETURN VALUE
.\" gettid(2) returns current->pid;
.\" getpid(2) returns current->tgid;
On success, the thread ID of the child process is returned
glibc2 provides
.BR clone ()
as described in this manual page.
-.SH "CONFORMING TO"
-The
+.SH CONFORMING TO
.BR clone ()
-and
-.B sys_clone
-calls are Linux-specific and should not be used in programs
+is Linux-specific and should not be used in programs
intended to be portable.
.SH NOTES
In the kernel 2.4.x series,
.BR clone ()
should not be called through vsyscall, but directly through
.IR "int $0x80" .
-
-On ia64, a different system call is used:
-.nf
-
-.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
-.PP
-The
-.BR __clone2 ()
-system call operates in the same way as
-.BR clone (),
-except that
-.I child_stack_base
-points to the lowest address of the child's stack area,
-and
-.I stack_size
-specifies the size of the stack pointed to by
-.IR child_stack_base .
.SH BUGS
Versions of the GNU C library that include the NPTL threading library
contain a wrapper function for
if a signal is delivered to the child immediately after the
.BR clone ()
call, then a call to
-.BR getpid ()
+.BR getpid (2)
in a handler for the signal may return the PID
of the calling process ("the parent"),
if the clone wrapper has not yet had a chance to update the PID
(This discussion ignores the case where the child was created using
.BR CLONE_THREAD ,
when
-.BR getpid ()
+.BR getpid (2)
.I should
return the same value in the child and in the process that called
.BR clone (),
.\" See also the following bug reports
.\" https://bugzilla.redhat.com/show_bug.cgi?id=417521
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910
-.SH "SEE ALSO"
+.SH EXAMPLE
+The following program demonstrates the use of
+.BR clone ()
+to create a child process that executes in a separate UTS namespace.
+The child changes the hostname in its UTS namespace.
+Both parent and child then display the system hostname,
+making it possible to see that the hostname
+differs in the UTS namespaces of the parent and child.
+For an example of the use of this program, see
+.BR setns (2).
+.SS Program source
+.nf
+#define _GNU_SOURCE
+#include <sys/wait.h>
+#include <sys/utsname.h>
+#include <sched.h>
+#include <string.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
+ } while (0)
+
+static int /* Start function for cloned child */
+childFunc(void *arg)
+{
+ struct utsname uts;
+
+ /* Change hostname in UTS namespace of child */
+
+ if (sethostname(arg, strlen(arg)) == \-1)
+ errExit("sethostname");
+
+ /* Retrieve and display hostname */
+
+ if (uname(&uts) == \-1)
+ errExit("uname");
+ printf("uts.nodename in child: %s\\n", uts.nodename);
+
+ /* Keep the namespace open for a while, by sleeping.
+ This allows some experimentation\-\-for example, another
+ process might join the namespace. */
+
+ sleep(200);
+
+ return 0; /* Child terminates now */
+}
+
+#define STACK_SIZE (1024 * 1024) /* Stack size for cloned child */
+
+int
+main(int argc, char *argv[])
+{
+ char *stack; /* Start of stack buffer */
+ char *stackTop; /* End of stack buffer */
+ pid_t pid;
+ struct utsname uts;
+
+ if (argc < 2) {
+ fprintf(stderr, "Usage: %s <child\-hostname>\\n", argv[0]);
+ exit(EXIT_SUCCESS);
+ }
+
+ /* Allocate stack for child */
+
+ stack = malloc(STACK_SIZE);
+ if (stack == NULL)
+ errExit("malloc");
+ stackTop = stack + STACK_SIZE; /* Assume stack grows downward */
+
+ /* Create child that has its own UTS namespace;
+ child commences execution in childFunc() */
+
+ pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]);
+ if (pid == \-1)
+ errExit("clone");
+ printf("clone() returned %ld\\n", (long) pid);
+
+ /* Parent falls through to here */
+
+ sleep(1); /* Give child time to change its hostname */
+
+ /* Display hostname in parent\(aqs UTS namespace. This will be
+ different from hostname in child\(aqs UTS namespace. */
+
+ if (uname(&uts) == \-1)
+ errExit("uname");
+ printf("uts.nodename in parent: %s\\n", uts.nodename);
+
+ if (waitpid(pid, NULL, 0) == \-1) /* Wait for child */
+ errExit("waitpid");
+ printf("child has terminated\\n");
+
+ exit(EXIT_SUCCESS);
+}
+.fi
+.SH SEE ALSO
.BR fork (2),
.BR futex (2),
.BR getpid (2),
.BR gettid (2),
+.BR kcmp (2),
.BR set_thread_area (2),
.BR set_tid_address (2),
+.BR setns (2),
.BR tkill (2),
.BR unshare (2),
.BR wait (2),
.BR capabilities (7),
.BR pthreads (7)
+.SH COLOPHON
+This page is part of release 3.65 of the Linux
+.I man-pages
+project.
+A description of the project,
+and information about reporting bugs,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
