Documentation for CLONE_NEWPID

[Michael Kerrisk <mtk.manpages-gM/Ye1E23mwN+BqQ9rBEUg@public.gmane.org>]

Pavel, Kir,

Drawing fairly heavily on your LWN.net article (http://lwn.net/Articles/259217/), plus the kernel source and some experimentation, I created the patch below to document CLONE_NEWPID for the clone(2) manual page.  Could you please review and let me know of any improvements or inaccuracies.

Thanks,

Michael

--- a/man2/clone.2
+++ b/man2/clone.2
@@ -266,6 +268,78 @@ in the same
 .BR clone ()
 call.
 .TP
+.BR CLONE_NEWPID " (since Linux 2.6.24)"
+.\" This explanation draws a lot of details from
+.\" http://lwn.net/Articles/259217/
+.\" Authors: Pavel Emelyanov <xemul-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org>
+.\" and Kir Kolyshkin <kir-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org>
+.\"
+.\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264
+.\" Author: Pavel Emelyanov <xemul-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org>
+If
+.B CLONE_PID
+is set, then create the process in a new PID namespace.
+If this flag is not set, then (as with
+.BR fork (2)),
+the process is created in the same PID namespace as
+the calling process.
+This flag is intended for the implementation of control groups.
+
+A PID namespace provides an isolated environment for PIDs:
+PIDs in a new namespace start at 1,
+somewhat like a standalone system, and calls to
+.BR fork (2),
+.BR vfork (2),
+or
+.BR clone (2)
+will produce processes whose PIDs within the namespace
+are only guaranteed to be unique within that namespace.
+
+The first process created in a new namespace
+(i.e., the process created using the
+.BR CLONE_NEWPID
+flag) has the PID 1, and is the "init" process for the namespace.
+Children that are orphaned within the namespace will be reparented
+to this process rather than
+.BR init (8).
+Unlike the traditional
+.B init
+process, the "init" process of a PID namespace can terminate,
+and if it does, all of the processes in the namespace are terminated.
+
+PID namespaces form a hierarchy.
+When a PID new namespace is created,
+the PIDs of the processes in that namespace are visible
+in the PID namespace of the process that created the new namespace;
+analogously, if the parent PID namespace is itself
+the child of another PID namespace,
+then PIDs of the child and parent PID namespaces will both be
+visible in the grandparent PID namespace.
+Conversely, the processes in the "child" PID namespace do not see
+the PIDs of the processes in the parent namespace.
+The existence of a namespace hierarchy means that each process
+may now have multiple PIDs:
+one for each namespace in which it is visible.
+(A call to
+.BR getpid (2)
+always returns the PID associated with the namespace in which
+the process was created.)
+
+After creating the new namespace,
+it is useful for the child to change its root directory
+and mount a new procfs instance at
+.I /proc
+so that tools such as
+.BR ps (1)
+work correctly.
+
+Use of this flag requires: a kernel configured with the
+.B CONFIG_PID_NS
+configuration option and requires that the process be privileged
+.RB (CAP_SYS_ADMIN ).
+This flag can't be specified in conjunction with
+.BR CLONE_THREAD .
+.TP
 .BR CLONE_PARENT " (since Linux 2.3.12)"
 If
 .B CLONE_PARENT
@@ -627,6 +701,14 @@ were specified in
 .IR flags .
 .TP
 .B EINVAL
+Both
+.BR CLONE_NEWPID
+and
+.BR CLONE_THREAD
+were specified in
+.IR flags .
+.TP
+.B EINVAL
 Returned by
 .BR clone ()
 when a zero value is specified for
@@ -639,6 +721,8 @@ copied.
 .TP
 .B EPERM
 .B CLONE_NEWNS
+or
+.B CLONE_NEWPID
 was specified by a non-root process (process without \fBCAP_SYS_ADMIN\fP).
 .TP
 .B EPERM
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html