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@xxxxxxxxxx> >> --- >> 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/
