Re: [PATCH] clone.2: Document CLONE_INTO_CGROUP

Hi Christian,

Ping!

Cheers,

Michael

On Fri, 10 Apr 2020 at 22:18, Michael Kerrisk (man-pages)
[off-list ref] wrote:

Hi Christian,

Thank you for writing this!

On 4/10/20 12:41 PM, Christian Brauner wrote:

quoted

From: Christian Brauner <redacted>

Signed-off-by: Christian Brauner <redacted>
---
 man2/clone.2 | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/man2/clone.2 b/man2/clone.2
index 39cec4c86..8d9aa9f99 100644
--- a/man2/clone.2
+++ b/man2/clone.2

@@ -197,6 +197,7 @@ struct clone_args {
     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 */
+    u64 cgroup;       /* Target cgroup file descriptor for the child process */
 };
 .EE
 .in

@@ -448,6 +449,25 @@ Specifying this flag together with
 .B CLONE_SIGHAND
 is nonsensical and disallowed.
 .TP
+.BR CLONE_INTO_CGROUP " (since Linux 5.7)"
+.\" commit ef2c41cf38a7559bbf91af42d5b6a4429db8fc68
+By default, the child process will belong to the same cgroup as its parent.

s/belong to/be placed in/

s/cgroup/version 2 cgroup/

quoted

+If this flag is specified the child process will be created in a
+different cgroup than its parent.
+
+When using
+.RB clone3 ()
+the target cgroup can be specified by setting the
+.I cl_args.cgroup
+member to the file descriptor of the target cgroup. The cgroup file

We need to say something about how this file descriptor is
obtained. Is it by opening a directory in the v2 cgroup hierarchy?
With what flags? O_RDONLY? or is O_PATH also possible? Yes, these
are some rhetorical questions (I read your nice commit message);
these things need to be explicit in the manual page though.

Also, your commit message mentions a nice list of use cases.
I think it would be well worth capturing those in a paragraph
in the manual page text.

quoted

+descriptor must refer to a cgroup in a cgroup v2 hierarchy
+(see
+.BR cgroup (2)).

s/cgroup/cgroups/
s/2/7/

quoted

+
+Note that all usual cgroup v2 process migration restrictions apply. See
+.BR cgroup (2)

s/cgroup/cgroups/
s/2/7/

Thanks,

Michael

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

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