Linux-man Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH v3] clone.2: added clone3() set_tid information
@ 2019-12-17 15:05 Adrian Reber
  2019-12-17 15:59 ` Christian Brauner
  2020-01-12 20:50 ` Michael Kerrisk (man-pages)
  0 siblings, 2 replies; 3+ messages in thread
From: Adrian Reber @ 2019-12-17 15:05 UTC (permalink / raw)
  To: mtk.manpages, Christian Brauner; +Cc: linux-man

Signed-off-by: Adrian Reber <areber@redhat.com>
---
 v2: applied changes from review (Michael and Christian)

 v3: added explanation about needing a PID 1 in a PID namespace
---
 man2/clone.2 | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)

diff --git a/man2/clone.2 b/man2/clone.2
index 076b9258e..15a1b56f6 100644
--- a/man2/clone.2
+++ b/man2/clone.2
@@ -195,6 +195,8 @@ struct clone_args {
     u64 stack;        /* Pointer to lowest byte of stack */
     u64 stack_size;   /* Size of stack */
     u64 tls;          /* Location of new TLS */
+    u64 set_tid;      /* Pointer to a \fIpid_t\fP array */
+    u64 set_tid_size; /* Number of elements in \fIset_tid\fP */
 };
 .EE
 .in
@@ -262,6 +264,8 @@ flags & 0xff	exit_signal
 stack	stack
 \fP---\fP	stack_size
 tls	tls	See CLONE_SETTLS
+\fP---\fP	set_tid	See below for details
+\fP---\fP	set_tid_size
 .TE
 .RE
 .\"
@@ -285,6 +289,80 @@ options when waiting for the child with
 If no signal (i.e., zero) is specified, then the parent process is not signaled
 when the child terminates.
 .\"
+.SS The set_tid array
+.PP
+By default, the kernel chooses the next sequential PID for the new
+process in each of the PID namespaces where it is present.
+When creating a process with
+.BR clone3 (),
+the
+.I set_tid
+array can be used to select specific PIDs for the process in some
+or all of the PID namespaces where it is present.
+If the PID of the newly created process should only be set for the current
+PID namespace or in the newly created PID namespace (if
+.I flags
+contains
+.BR CLONE_NEWPID )
+then the first element in the
+.I set_tid
+array has to be the desired PID and
+.I set_tid_size
+needs to be 1.
+.PP
+If the PID of the newly created process should have a certain value in
+multiple PID namespaces the
+.I set_tid
+array can have multiple entries. The first entry defines the PID in the most
+deeply nested PID namespace and all following entries contain the PID of the
+corresponding parent PID namespace. The number of PID namespaces in which a PID
+should be set is defined by
+.I set_tid_size
+which cannot be larger than the number of currently nested PID namespaces.
+.PP
+To create a process with the following PIDs in a PID namespace hierarchy:
+.RS
+.TS
+lb lb
+l l .
+PID NS level	Requested PID
+0 (host)	31496
+1	42
+2	7
+.TE
+.RE
+.PP
+Set the array to:
+.PP
+.EX
+	set_tid[0] = 7;
+	set_tid[1] = 42;
+	set_tid[2] = 31496;
+	set_tid_size = 3;
+.EE
+.PP
+If only the PIDs in the two innermost PID namespaces
+need to be specified, set the array to:
+.PP
+.EX
+	set_tid[0] = 7;
+	set_tid[1] = 42;
+	set_tid_size = 2;
+.EE
+.PP
+The PID in the PID namespaces outside the two innermost PID namespaces
+will be selected the same way as any other PID is selected.
+.PP
+The
+.I set_tid
+feature requires
+.RB CAP_SYS_ADMIN
+in all owning user namespaces of the target PID namespaces.
+.PP
+Callers may only choose a PID > 1 in a given PID namespace if an init
+process (i.e. a process with PID 1) already exists. Otherwise the PID
+entry for this PID namespace must be 1.
+.\"
 .SS The flags mask
 .PP
 Both
@@ -1201,6 +1279,11 @@ will be set appropriately.
 Too many processes are already running; see
 .BR fork (2).
 .TP
+.BR EEXIST " (" clone3 "() only)"
+One or more of the PIDs specified in
+.I set_tid
+already exists in the corresponding PID namespace.
+.TP
 .B EINVAL
 .B CLONE_SIGHAND
 was specified in the
@@ -1379,6 +1462,15 @@ in the
 .I flags
 mask.
 .TP
+.BR EINVAL " (" clone3 "() only)"
+.I set_tid_size
+larger than current number of nested PID namespaces.
+.TP
+.BR EINVAL " (" clone3 "() only)"
+If one of the PIDs specified in
+.I set_tid
+was an invalid PID.
+.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
@@ -1450,6 +1542,13 @@ mask and the caller is in a chroot environment
 (i.e., the caller's root directory does not match the root directory
 of the mount namespace in which it resides).
 .TP
+.BR EPERM " (" clone3 "() only)"
+.I set_tid_size
+was greater than zero, and the caller lacks the
+.B CAP_SYS_ADMIN
+capability in one or more of the user namespaces that own the
+corresponding PID namespaces.
+.TP
 .BR ERESTARTNOINTR " (since Linux 2.6.17)"
 .\" commit 4a2c7a7837da1b91468e50426066d988050e4d56
 System call was interrupted by a signal and will be restarted.

base-commit: 5373f62f1e4352e665c24dfe49b7e3fe03721cab
-- 
2.23.0


^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [PATCH v3] clone.2: added clone3() set_tid information
  2019-12-17 15:05 [PATCH v3] clone.2: added clone3() set_tid information Adrian Reber
@ 2019-12-17 15:59 ` Christian Brauner
  2020-01-12 20:50 ` Michael Kerrisk (man-pages)
  1 sibling, 0 replies; 3+ messages in thread
From: Christian Brauner @ 2019-12-17 15:59 UTC (permalink / raw)
  To: Adrian Reber; +Cc: mtk.manpages, linux-man

On Tue, Dec 17, 2019 at 04:05:05PM +0100, Adrian Reber wrote:
> Signed-off-by: Adrian Reber <areber@redhat.com>

Acked-by: Christian Brauner <christian.brauner@ubuntu.com>

^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [PATCH v3] clone.2: added clone3() set_tid information
  2019-12-17 15:05 [PATCH v3] clone.2: added clone3() set_tid information Adrian Reber
  2019-12-17 15:59 ` Christian Brauner
@ 2020-01-12 20:50 ` Michael Kerrisk (man-pages)
  1 sibling, 0 replies; 3+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-01-12 20:50 UTC (permalink / raw)
  To: Adrian Reber; +Cc: Christian Brauner, linux-man

Hello Adrian, Christian,

On Tue, 17 Dec 2019 at 16:05, Adrian Reber <areber@redhat.com> wrote:
>
> Signed-off-by: Adrian Reber <areber@redhat.com>
> ---
>  v2: applied changes from review (Michael and Christian)
>
>  v3: added explanation about needing a PID 1 in a PID namespace
> ---
>  man2/clone.2 | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 99 insertions(+)

Thanks, Adrian. Patch applied (and a few tweaks added; see [1]).

Christian, thanks of the review.

Cheers,

Michael

[1] https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=ee8bb310d8d16792723b9f69fcb9c6797cb07e79

> diff --git a/man2/clone.2 b/man2/clone.2
> index 076b9258e..15a1b56f6 100644
> --- a/man2/clone.2
> +++ b/man2/clone.2
> @@ -195,6 +195,8 @@ struct clone_args {
>      u64 stack;        /* Pointer to lowest byte of stack */
>      u64 stack_size;   /* Size of stack */
>      u64 tls;          /* Location of new TLS */
> +    u64 set_tid;      /* Pointer to a \fIpid_t\fP array */
> +    u64 set_tid_size; /* Number of elements in \fIset_tid\fP */
>  };
>  .EE
>  .in
> @@ -262,6 +264,8 @@ flags & 0xff        exit_signal
>  stack  stack
>  \fP---\fP      stack_size
>  tls    tls     See CLONE_SETTLS
> +\fP---\fP      set_tid See below for details
> +\fP---\fP      set_tid_size
>  .TE
>  .RE
>  .\"
> @@ -285,6 +289,80 @@ options when waiting for the child with
>  If no signal (i.e., zero) is specified, then the parent process is not signaled
>  when the child terminates.
>  .\"
> +.SS The set_tid array
> +.PP
> +By default, the kernel chooses the next sequential PID for the new
> +process in each of the PID namespaces where it is present.
> +When creating a process with
> +.BR clone3 (),
> +the
> +.I set_tid
> +array can be used to select specific PIDs for the process in some
> +or all of the PID namespaces where it is present.
> +If the PID of the newly created process should only be set for the current
> +PID namespace or in the newly created PID namespace (if
> +.I flags
> +contains
> +.BR CLONE_NEWPID )
> +then the first element in the
> +.I set_tid
> +array has to be the desired PID and
> +.I set_tid_size
> +needs to be 1.
> +.PP
> +If the PID of the newly created process should have a certain value in
> +multiple PID namespaces the
> +.I set_tid
> +array can have multiple entries. The first entry defines the PID in the most
> +deeply nested PID namespace and all following entries contain the PID of the
> +corresponding parent PID namespace. The number of PID namespaces in which a PID
> +should be set is defined by
> +.I set_tid_size
> +which cannot be larger than the number of currently nested PID namespaces.
> +.PP
> +To create a process with the following PIDs in a PID namespace hierarchy:
> +.RS
> +.TS
> +lb lb
> +l l .
> +PID NS level   Requested PID
> +0 (host)       31496
> +1      42
> +2      7
> +.TE
> +.RE
> +.PP
> +Set the array to:
> +.PP
> +.EX
> +       set_tid[0] = 7;
> +       set_tid[1] = 42;
> +       set_tid[2] = 31496;
> +       set_tid_size = 3;
> +.EE
> +.PP
> +If only the PIDs in the two innermost PID namespaces
> +need to be specified, set the array to:
> +.PP
> +.EX
> +       set_tid[0] = 7;
> +       set_tid[1] = 42;
> +       set_tid_size = 2;
> +.EE
> +.PP
> +The PID in the PID namespaces outside the two innermost PID namespaces
> +will be selected the same way as any other PID is selected.
> +.PP
> +The
> +.I set_tid
> +feature requires
> +.RB CAP_SYS_ADMIN
> +in all owning user namespaces of the target PID namespaces.
> +.PP
> +Callers may only choose a PID > 1 in a given PID namespace if an init
> +process (i.e. a process with PID 1) already exists. Otherwise the PID
> +entry for this PID namespace must be 1.
> +.\"
>  .SS The flags mask
>  .PP
>  Both
> @@ -1201,6 +1279,11 @@ will be set appropriately.
>  Too many processes are already running; see
>  .BR fork (2).
>  .TP
> +.BR EEXIST " (" clone3 "() only)"
> +One or more of the PIDs specified in
> +.I set_tid
> +already exists in the corresponding PID namespace.
> +.TP
>  .B EINVAL
>  .B CLONE_SIGHAND
>  was specified in the
> @@ -1379,6 +1462,15 @@ in the
>  .I flags
>  mask.
>  .TP
> +.BR EINVAL " (" clone3 "() only)"
> +.I set_tid_size
> +larger than current number of nested PID namespaces.
> +.TP
> +.BR EINVAL " (" clone3 "() only)"
> +If one of the PIDs specified in
> +.I set_tid
> +was an invalid PID.
> +.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
> @@ -1450,6 +1542,13 @@ mask and the caller is in a chroot environment
>  (i.e., the caller's root directory does not match the root directory
>  of the mount namespace in which it resides).
>  .TP
> +.BR EPERM " (" clone3 "() only)"
> +.I set_tid_size
> +was greater than zero, and the caller lacks the
> +.B CAP_SYS_ADMIN
> +capability in one or more of the user namespaces that own the
> +corresponding PID namespaces.
> +.TP
>  .BR ERESTARTNOINTR " (since Linux 2.6.17)"
>  .\" commit 4a2c7a7837da1b91468e50426066d988050e4d56
>  System call was interrupted by a signal and will be restarted.
>
> base-commit: 5373f62f1e4352e665c24dfe49b7e3fe03721cab
> --
> 2.23.0
>


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, back to index

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-12-17 15:05 [PATCH v3] clone.2: added clone3() set_tid information Adrian Reber
2019-12-17 15:59 ` Christian Brauner
2020-01-12 20:50 ` Michael Kerrisk (man-pages)

Linux-man Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-man/0 linux-man/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-man linux-man/ https://lore.kernel.org/linux-man \
		linux-man@vger.kernel.org
	public-inbox-index linux-man

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-man


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git