[PATCH] seccomp_unotify.2: Add doc for SECCOMP_ADDFD_FLAG_SEND

[PATCH] seccomp_unotify.2: Add doc for SECCOMP_ADDFD_FLAG_SEND

[Rodrigo Campos]

This flag was recently added to Linux 5.14 by a patch I wrote:
	https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0ae71c7720e3ae3aabd2e8a072d27f7bd173d25c

This patch adds documentation for the flag, the error code that the flag
added and explains in the caveat when it is useful.

Signed-off-by: Rodrigo Campos <rodrigo@kinvolk.io>
---
Hi! Here goes the documentation for the flag I just added. Please feel free to
amend as you want and let me know if something is not clear :)


 man2/seccomp_unotify.2 | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/man2/seccomp_unotify.2 b/man2/seccomp_unotify.2
index 2673d9bc7..9bd27214f 100644
--- a/man2/seccomp_unotify.2
+++ b/man2/seccomp_unotify.2
@@ -739,6 +739,17 @@ When allocating the file descriptor in the target,
 use the file descriptor number specified in the
 .I newfd
 field.
+.TP
+.BR SECCOMP_ADDFD_FLAG_SEND
+Available since Linux 5.14, combines the
+.B SECCOMP_IOCTL_NOTIF_ADDFD
+ioctl with
+.B SECCOMP_IOCTL_NOTIF_SEND
+into an atomic operation. On successful invocation, the target process's
+errno will be 0 and the return value will be the file descriptor number that was
+installed in the target. If allocating the file descriptor in the tatget fails,
+the target's syscall continues to be blocked until a successful response is
+sent.
 .RE
 .TP
 .I srcfd
@@ -801,6 +812,13 @@ Allocating the file descriptor in the target would cause the target's
 limit to be exceeded (see
 .BR getrlimit (2)).
 .TP
+.B EBUSY
+If the flag
+.B SECCOMP_IOCTL_NOTIF_SEND
+is used, this means the operation can't proceed until other
+.B SECCOMP_IOCTL_NOTIF_ADDFD
+requests are processed.
+.TP
 .B EINPROGRESS
 The user-space notification specified in the
 .I id
@@ -1131,6 +1149,14 @@ that would
 normally be restarted by the
 .BR SA_RESTART
 flag.
+.PP
+Furthermore, if the supervisor response is a file descriptor
+added with
+.B SECCOMP_IOCTL_NOTIF_ADDFD,
+then the flag
+.B SECCOMP_ADDFD_FLAG_SEND
+can be used to atomically add the file descriptor and return that value,
+making sure no file descriptors are inadvertently leaked into the target.
 .\" FIXME
 .\" About the above, Kees Cook commented:
 .\"
-- 
2.30.2

Re: [PATCH] seccomp_unotify.2: Add doc for SECCOMP_ADDFD_FLAG_SEND

[Alejandro Colomar (man-pages)]

Hi Rodrigo,

On 7/2/21 6:37 PM, Rodrigo Campos wrote:
> This flag was recently added to Linux 5.14 by a patch I wrote:
> 	https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0ae71c7720e3ae3aabd2e8a072d27f7bd173d25c
> 
> This patch adds documentation for the flag, the error code that the flag
> added and explains in the caveat when it is useful.
> 
> Signed-off-by: Rodrigo Campos <rodrigo@kinvolk.io>
> ---
> Hi! Here goes the documentation for the flag I just added. Please feel free to
> amend as you want and let me know if something is not clear :)

Thanks for documenting your own addition!
That makes things much easier :-)

It looks quite good to me.

There are a few minor changes that I applied in a following patch.  I'll
explain why in your patch inline.  And then you have the diff below your
patch.

Cheers,

Alex

> 
> 
>  man2/seccomp_unotify.2 | 26 ++++++++++++++++++++++++++
>  1 file changed, 26 insertions(+)
> 
> diff --git a/man2/seccomp_unotify.2 b/man2/seccomp_unotify.2
> index 2673d9bc7..9bd27214f 100644
> --- a/man2/seccomp_unotify.2
> +++ b/man2/seccomp_unotify.2
> @@ -739,6 +739,17 @@ When allocating the file descriptor in the target,
>  use the file descriptor number specified in the
>  .I newfd
>  field.
> +.TP
> +.BR SECCOMP_ADDFD_FLAG_SEND
> +Available since Linux 5.14, combines the

We usually append that info to the paragraph tag (i.e., the line just
after .TP), and with a common syntax, so that it's easier to read..

> +.B SECCOMP_IOCTL_NOTIF_ADDFD
> +ioctl with
> +.B SECCOMP_IOCTL_NOTIF_SEND
> +into an atomic operation. On successful invocation, the target process's
> +errno will be 0 and the return value will be the file descriptor number that was
> +installed in the target. If allocating the file descriptor in the tatget fails,
> +the target's syscall continues to be blocked until a successful response is
> +sent.

See the following extract from man-pages(7):

$ man 7 man-pages | sed -n '/Use semantic newlines/,/^$/p';
   Use semantic newlines
       In the source of a manual page,  new  sentences  should  be
       started  on new lines, and long sentences should split into
       lines at clause breaks (commas, semicolons, colons, and  so
       on).   This  convention,  sometimes known as "semantic new‐
       lines", makes it easier to see the effect of patches, which
       often  operate at the level of individual sentences or sen‐
       tence clauses.

>  .RE
>  .TP
>  .I srcfd
> @@ -801,6 +812,13 @@ Allocating the file descriptor in the target would cause the target's
>  limit to be exceeded (see
>  .BR getrlimit (2)).
>  .TP
> +.B EBUSY
> +If the flag
> +.B SECCOMP_IOCTL_NOTIF_SEND
> +is used, this means the operation can't proceed until other
> +.B SECCOMP_IOCTL_NOTIF_ADDFD
> +requests are processed.
> +.TP
>  .B EINPROGRESS
>  The user-space notification specified in the
>  .I id
> @@ -1131,6 +1149,14 @@ that would
>  normally be restarted by the
>  .BR SA_RESTART
>  flag.
> +.PP
> +Furthermore, if the supervisor response is a file descriptor
> +added with
> +.B SECCOMP_IOCTL_NOTIF_ADDFD,
> +then the flag
> +.B SECCOMP_ADDFD_FLAG_SEND
> +can be used to atomically add the file descriptor and return that value,
> +making sure no file descriptors are inadvertently leaked into the target.

I moved your paragraph below the FIXME, as I the FIXME applies to the
previous paragraph ("About the above").

>  .\" FIXME
>  .\" About the above, Kees Cook commented:
>  .\"
> 


diff --git a/man2/seccomp_unotify.2 b/man2/seccomp_unotify.2
index 9bd27214f..ae449ae36 100644
--- a/man2/seccomp_unotify.2
+++ b/man2/seccomp_unotify.2
@@ -740,16 +740,18 @@ use the file descriptor number specified in the
 .I newfd
 field.
 .TP
-.BR SECCOMP_ADDFD_FLAG_SEND
-Available since Linux 5.14, combines the
+.BR SECCOMP_ADDFD_FLAG_SEND " (since Linux 5.14)"
+Combines the
 .B SECCOMP_IOCTL_NOTIF_ADDFD
 ioctl with
 .B SECCOMP_IOCTL_NOTIF_SEND
-into an atomic operation. On successful invocation, the target process's
-errno will be 0 and the return value will be the file descriptor number
that was
-installed in the target. If allocating the file descriptor in the
tatget fails,
-the target's syscall continues to be blocked until a successful response is
-sent.
+into an atomic operation.
+On successful invocation, the target process's errno will be 0
+and the return value will be the file descriptor number
+that was installed in the target.
+If allocating the file descriptor in the tatget fails,
+the target's syscall continues to be blocked
+until a successful response is sent.
 .RE
 .TP
 .I srcfd
@@ -1149,14 +1151,6 @@ that would
 normally be restarted by the
 .BR SA_RESTART
 flag.
-.PP
-Furthermore, if the supervisor response is a file descriptor
-added with
-.B SECCOMP_IOCTL_NOTIF_ADDFD,
-then the flag
-.B SECCOMP_ADDFD_FLAG_SEND
-can be used to atomically add the file descriptor and return that value,
-making sure no file descriptors are inadvertently leaked into the target.
 .\" FIXME
 .\" About the above, Kees Cook commented:
 .\"
@@ -1176,6 +1170,14 @@ making sure no file descriptors are inadvertently
leaked into the target.
 .\" calls because it's impossible for the kernel to restart the call
 .\" with the right timeout value. I wonder what happens when those
 .\" system calls are restarted in the scenario we're discussing.)
+.PP
+Furthermore, if the supervisor response is a file descriptor
+added with
+.B SECCOMP_IOCTL_NOTIF_ADDFD,
+then the flag
+.B SECCOMP_ADDFD_FLAG_SEND
+can be used to atomically add the file descriptor and return that value,
+making sure no file descriptors are inadvertently leaked into the target.
 .SH BUGS
 If a
 .BR SECCOMP_IOCTL_NOTIF_RECV


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH] seccomp_unotify.2: Add doc for SECCOMP_ADDFD_FLAG_SEND

[Alejandro Colomar (man-pages)]

On 7/3/21 11:25 PM, Alejandro Colomar (man-pages) wrote:
> Hi Rodrigo,
> 
> On 7/2/21 6:37 PM, Rodrigo Campos wrote:
>> This flag was recently added to Linux 5.14 by a patch I wrote:
>> 	https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0ae71c7720e3ae3aabd2e8a072d27f7bd173d25c
>>
>> This patch adds documentation for the flag, the error code that the flag
>> added and explains in the caveat when it is useful.
>>
>> Signed-off-by: Rodrigo Campos <rodrigo@kinvolk.io>
>> ---
>> Hi! Here goes the documentation for the flag I just added. Please feel free to
>> amend as you want and let me know if something is not clear :)
> 
> Thanks for documenting your own addition!
> That makes things much easier :-)
> 
> It looks quite good to me.
> 
> There are a few minor changes that I applied in a following patch.  I'll
> explain why in your patch inline.  And then you have the diff below your

And I meant: patch applied!

Thanks,

Alex

> patch.
> 
> Cheers,
> 
> Alex
> 
>>
>>
>>  man2/seccomp_unotify.2 | 26 ++++++++++++++++++++++++++
>>  1 file changed, 26 insertions(+)
>>
>> diff --git a/man2/seccomp_unotify.2 b/man2/seccomp_unotify.2
>> index 2673d9bc7..9bd27214f 100644
>> --- a/man2/seccomp_unotify.2
>> +++ b/man2/seccomp_unotify.2
>> @@ -739,6 +739,17 @@ When allocating the file descriptor in the target,
>>  use the file descriptor number specified in the
>>  .I newfd
>>  field.
>> +.TP
>> +.BR SECCOMP_ADDFD_FLAG_SEND
>> +Available since Linux 5.14, combines the
> 
> We usually append that info to the paragraph tag (i.e., the line just
> after .TP), and with a common syntax, so that it's easier to read..
> 
>> +.B SECCOMP_IOCTL_NOTIF_ADDFD
>> +ioctl with
>> +.B SECCOMP_IOCTL_NOTIF_SEND
>> +into an atomic operation. On successful invocation, the target process's
>> +errno will be 0 and the return value will be the file descriptor number that was
>> +installed in the target. If allocating the file descriptor in the tatget fails,
>> +the target's syscall continues to be blocked until a successful response is
>> +sent.
> 
> See the following extract from man-pages(7):
> 
> $ man 7 man-pages | sed -n '/Use semantic newlines/,/^$/p';
>    Use semantic newlines
>        In the source of a manual page,  new  sentences  should  be
>        started  on new lines, and long sentences should split into
>        lines at clause breaks (commas, semicolons, colons, and  so
>        on).   This  convention,  sometimes known as "semantic new‐
>        lines", makes it easier to see the effect of patches, which
>        often  operate at the level of individual sentences or sen‐
>        tence clauses.
> 
>>  .RE
>>  .TP
>>  .I srcfd
>> @@ -801,6 +812,13 @@ Allocating the file descriptor in the target would cause the target's
>>  limit to be exceeded (see
>>  .BR getrlimit (2)).
>>  .TP
>> +.B EBUSY
>> +If the flag
>> +.B SECCOMP_IOCTL_NOTIF_SEND
>> +is used, this means the operation can't proceed until other
>> +.B SECCOMP_IOCTL_NOTIF_ADDFD
>> +requests are processed.
>> +.TP
>>  .B EINPROGRESS
>>  The user-space notification specified in the
>>  .I id
>> @@ -1131,6 +1149,14 @@ that would
>>  normally be restarted by the
>>  .BR SA_RESTART
>>  flag.
>> +.PP
>> +Furthermore, if the supervisor response is a file descriptor
>> +added with
>> +.B SECCOMP_IOCTL_NOTIF_ADDFD,
>> +then the flag
>> +.B SECCOMP_ADDFD_FLAG_SEND
>> +can be used to atomically add the file descriptor and return that value,
>> +making sure no file descriptors are inadvertently leaked into the target.
> 
> I moved your paragraph below the FIXME, as I the FIXME applies to the
> previous paragraph ("About the above").
> 
>>  .\" FIXME
>>  .\" About the above, Kees Cook commented:
>>  .\"
>>
> 
> 
> diff --git a/man2/seccomp_unotify.2 b/man2/seccomp_unotify.2
> index 9bd27214f..ae449ae36 100644
> --- a/man2/seccomp_unotify.2
> +++ b/man2/seccomp_unotify.2
> @@ -740,16 +740,18 @@ use the file descriptor number specified in the
>  .I newfd
>  field.
>  .TP
> -.BR SECCOMP_ADDFD_FLAG_SEND
> -Available since Linux 5.14, combines the
> +.BR SECCOMP_ADDFD_FLAG_SEND " (since Linux 5.14)"
> +Combines the
>  .B SECCOMP_IOCTL_NOTIF_ADDFD
>  ioctl with
>  .B SECCOMP_IOCTL_NOTIF_SEND
> -into an atomic operation. On successful invocation, the target process's
> -errno will be 0 and the return value will be the file descriptor number
> that was
> -installed in the target. If allocating the file descriptor in the
> tatget fails,
> -the target's syscall continues to be blocked until a successful response is
> -sent.
> +into an atomic operation.
> +On successful invocation, the target process's errno will be 0
> +and the return value will be the file descriptor number
> +that was installed in the target.
> +If allocating the file descriptor in the tatget fails,
> +the target's syscall continues to be blocked
> +until a successful response is sent.
>  .RE
>  .TP
>  .I srcfd
> @@ -1149,14 +1151,6 @@ that would
>  normally be restarted by the
>  .BR SA_RESTART
>  flag.
> -.PP
> -Furthermore, if the supervisor response is a file descriptor
> -added with
> -.B SECCOMP_IOCTL_NOTIF_ADDFD,
> -then the flag
> -.B SECCOMP_ADDFD_FLAG_SEND
> -can be used to atomically add the file descriptor and return that value,
> -making sure no file descriptors are inadvertently leaked into the target.
>  .\" FIXME
>  .\" About the above, Kees Cook commented:
>  .\"
> @@ -1176,6 +1170,14 @@ making sure no file descriptors are inadvertently
> leaked into the target.
>  .\" calls because it's impossible for the kernel to restart the call
>  .\" with the right timeout value. I wonder what happens when those
>  .\" system calls are restarted in the scenario we're discussing.)
> +.PP
> +Furthermore, if the supervisor response is a file descriptor
> +added with
> +.B SECCOMP_IOCTL_NOTIF_ADDFD,
> +then the flag
> +.B SECCOMP_ADDFD_FLAG_SEND
> +can be used to atomically add the file descriptor and return that value,
> +making sure no file descriptors are inadvertently leaked into the target.
>  .SH BUGS
>  If a
>  .BR SECCOMP_IOCTL_NOTIF_RECV
> 
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH] seccomp_unotify.2: Add doc for SECCOMP_ADDFD_FLAG_SEND

[Rodrigo Campos]

On Sat, Jul 3, 2021 at 11:25 PM Alejandro Colomar (man-pages)
<alx.manpages@gmail.com> wrote:
>
> Hi Rodrigo,
>
> On 7/2/21 6:37 PM, Rodrigo Campos wrote:
> > This flag was recently added to Linux 5.14 by a patch I wrote:
> >       https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0ae71c7720e3ae3aabd2e8a072d27f7bd173d25c
> >
> > This patch adds documentation for the flag, the error code that the flag
> > added and explains in the caveat when it is useful.
> >
> > Signed-off-by: Rodrigo Campos <rodrigo@kinvolk.io>
> > ---
> > Hi! Here goes the documentation for the flag I just added. Please feel free to
> > amend as you want and let me know if something is not clear :)
>
> Thanks for documenting your own addition!
> That makes things much easier :-)

No problem, thank you! :)

>
> It looks quite good to me.

Thanks! It helps to know that the explanation makes sense for others too :)

>
> There are a few minor changes that I applied in a following patch.  I'll
> explain why in your patch inline.  And then you have the diff below your
> patch.

Thanks very much for the explanations, I will try to remember for the
next time. And thanks for sending the patch here :)


Best,

Rodrigo Campos
---
Kinvolk GmbH | Adalbertstr.6a, 10999 Berlin | tel: +491755589364
Geschäftsführer/Directors: Benjamin Owen Orndorff
Registergericht/Court of registration: Amtsgericht Charlottenburg
Registernummer/Registration number: HRB 171414 B
Ust-ID-Nummer/VAT ID number: DE302207000

Re: [PATCH] seccomp_unotify.2: Add doc for SECCOMP_ADDFD_FLAG_SEND

[Rodrigo Campos]

On Sun, Jul 4, 2021 at 1:25 PM Alejandro Colomar (man-pages)
<alx.manpages@gmail.com> wrote:
> On 7/3/21 11:25 PM, Alejandro Colomar (man-pages) wrote:
> > It looks quite good to me.
> >
> > There are a few minor changes that I applied in a following patch.  I'll
> > explain why in your patch inline.  And then you have the diff below your
>
> And I meant: patch applied!

Oh, thanks!

Rodrigo Campos
---
Kinvolk GmbH | Adalbertstr.6a, 10999 Berlin | tel: +491755589364
Geschäftsführer/Directors: Benjamin Owen Orndorff
Registergericht/Court of registration: Amtsgericht Charlottenburg
Registernummer/Registration number: HRB 171414 B
Ust-ID-Nummer/VAT ID number: DE302207000