[PATCH] man/man2/seccomp_unotify.2: Document SECCOMP_IOCTL_NOTIF_SET_FLAGS and SECCOMP_USER_NOTIF_FD_SYNC_WAKE_UP

[PATCH] man/man2/seccomp_unotify.2: Document SECCOMP_IOCTL_NOTIF_SET_FLAGS and SECCOMP_USER_NOTIF_FD_SYNC_WAKE_UP

[funsafemath]

[-- Attachment #1: Type: text/plain, Size: 2321 bytes --]

Document the SECCOMP_IOCTL_NOTIF_SET_FLAGS ioctl(2) operation and its only flag,
SECCOMP_USER_NOTIF_FD_SYNC_WAKE_UP, which advises the scheduler to move the
supervisor to the CPU on which the target process is executing for faster
context switches.

<https://lore.kernel.org/r/20230308073201.3102738-5-avagin@google.com>

Signed-off-by: funsafemath <funsafemath@proton.me>
---
 man/man2/seccomp_unotify.2 | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/man/man2/seccomp_unotify.2 b/man/man2/seccomp_unotify.2
index a5c1a4423..70b2996a9 100644
--- a/man/man2/seccomp_unotify.2
+++ b/man/man2/seccomp_unotify.2
@@ -27,6 +27,7 @@ .SH SYNOPSIS
 .BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_ID_VALID, __u64 *" id );
 .BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_ADDFD,"
 .BI "          struct seccomp_notif_addfd *" addfd );
+.BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_SET_FLAGS, unsigned long " flags );
 .fi
 .SH DESCRIPTION
 This page describes the user-space notification mechanism provided by the
@@ -881,6 +882,41 @@ .SS SECCOMP_IOCTL_NOTIF_ADDFD
 ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_SEND, resp);
 .in
 .EE
+.\"
+.SS SECCOMP_IOCTL_NOTIF_SET_FLAGS
+The
+.B SECCOMP_IOCTL_NOTIF_SET_FLAGS
+operation (available since Linux 6.6)
+\." commit 48a1084a8b7423642b5f17ca6202f6f277c5392b
+is used to modify the behavior of the seccomp user-space notification mechanism.
+.P
+The third
+.BR ioctl (2)
+argument,
+.IR flags ,
+is a bit mask that includes zero or more of the following flags:
+.RS
+.TP
+.BR SECCOMP_USER_NOTIF_FD_SYNC_WAKE_UP " (since Linux 6.6)"
+\." commit 48a1084a8b7423642b5f17ca6202f6f277c5392b
+Advise the scheduler to move the supervisor to the current CPU.
+.IP
+In workflows where the target and supervisor wait for each other
+(do not execute in parallel),
+this flag makes the context switches a few times faster.
+.RE
+.P
+On success,
+this operation returns 0;
+on failure, \-1 is returned, and
+.I errno
+is set to indicate the error.
+This operation can fail with the following errors:
+.TP
+.B EINVAL
+An invalid value was specified in the
+.I flags
+argument.
 .SH NOTES
 One example use case for the user-space notification
 mechanism is to allow a container manager
-- 
2.52.0


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH] man/man2/seccomp_unotify.2: Document SECCOMP_IOCTL_NOTIF_SET_FLAGS and SECCOMP_USER_NOTIF_FD_SYNC_WAKE_UP

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3620 bytes --]

Hi,

On 2026-05-18T06:50:47+0100, funsafemath wrote:
> Document the SECCOMP_IOCTL_NOTIF_SET_FLAGS ioctl(2) operation and its only flag,
> SECCOMP_USER_NOTIF_FD_SYNC_WAKE_UP, which advises the scheduler to move the
> supervisor to the CPU on which the target process is executing for faster
> context switches.
> 
> <https://lore.kernel.org/r/20230308073201.3102738-5-avagin@google.com>
> 
> Signed-off-by: funsafemath <funsafemath@proton.me>

The patch looks mostly good.  See a minor comment below.


Have a lovely day!
Alex

> ---
>  man/man2/seccomp_unotify.2 | 36 ++++++++++++++++++++++++++++++++++++
>  1 file changed, 36 insertions(+)
> 
> diff --git a/man/man2/seccomp_unotify.2 b/man/man2/seccomp_unotify.2
> index a5c1a4423..70b2996a9 100644
> --- a/man/man2/seccomp_unotify.2
> +++ b/man/man2/seccomp_unotify.2
> @@ -27,6 +27,7 @@ .SH SYNOPSIS
>  .BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_ID_VALID, __u64 *" id );
>  .BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_ADDFD,"
>  .BI "          struct seccomp_notif_addfd *" addfd );
> +.BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_SET_FLAGS, unsigned long " flags );
>  .fi
>  .SH DESCRIPTION
>  This page describes the user-space notification mechanism provided by the
> @@ -881,6 +882,41 @@ .SS SECCOMP_IOCTL_NOTIF_ADDFD
>  ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_SEND, resp);
>  .in
>  .EE
> +.\"
> +.SS SECCOMP_IOCTL_NOTIF_SET_FLAGS
> +The
> +.B SECCOMP_IOCTL_NOTIF_SET_FLAGS
> +operation (available since Linux 6.6)
> +\." commit 48a1084a8b7423642b5f17ca6202f6f277c5392b

Typo; you meant .\"
It's also repeated below.

Interestingly, this seems to also hide it as a comment, although
troff(1) prints a warning saying that something is wrong:

	alx@devuan:~/tmp$ cat comment.man 
	.TH comment 7 2026-05-18 experiments
	.SH Name
	comment \- trying different comments
	.SH Description
	Here goes one comment:
	.\" foo
	Comment ended.
	.P
	Here goes another comment?
	\." bar
	Comment ended.
	alx@devuan:~/tmp$ groff -Tutf8 -man -rCHECKSTYLE=3 -rLL=64n -ww comment.man 
	troff:comment.man:10: warning: name '"' not defined
	comment(7)      Miscellaneous Information Manual      comment(7)

	Name
	     comment - trying different comments

	Description
	     Here goes one comment: Comment ended.

	     Here goes another comment?  Comment ended.

	experiments                2026‐05‐18                 comment(7)

I'm curious about what happens in the roff(7) language for this to work
as a comment.

> +is used to modify the behavior of the seccomp user-space notification mechanism.
> +.P
> +The third
> +.BR ioctl (2)
> +argument,
> +.IR flags ,
> +is a bit mask that includes zero or more of the following flags:
> +.RS
> +.TP
> +.BR SECCOMP_USER_NOTIF_FD_SYNC_WAKE_UP " (since Linux 6.6)"
> +\." commit 48a1084a8b7423642b5f17ca6202f6f277c5392b
> +Advise the scheduler to move the supervisor to the current CPU.
> +.IP
> +In workflows where the target and supervisor wait for each other
> +(do not execute in parallel),
> +this flag makes the context switches a few times faster.
> +.RE
> +.P
> +On success,
> +this operation returns 0;
> +on failure, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +This operation can fail with the following errors:
> +.TP
> +.B EINVAL
> +An invalid value was specified in the
> +.I flags
> +argument.
>  .SH NOTES
>  One example use case for the user-space notification
>  mechanism is to allow a container manager
> -- 
> 2.52.0
> 



-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

weird but successful *roff comment syntax (was: [PATCH] man/man2/seccomp_unotify.2: Document SECCOMP_IOCTL_NOTIF_SET_FLAGS and SECCOMP_USER_NOTIF_FD_SYNC_WAKE_UP)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 4849 bytes --]

[looping in groff list]

Hi Alex,

At 2026-05-18T12:24:25+0200, Alejandro Colomar wrote:
> > +.\"
> > +.SS SECCOMP_IOCTL_NOTIF_SET_FLAGS
> > +The
> > +.B SECCOMP_IOCTL_NOTIF_SET_FLAGS
> > +operation (available since Linux 6.6)
> > +\." commit 48a1084a8b7423642b5f17ca6202f6f277c5392b
> 
> Typo; you meant .\"
> It's also repeated below.
> 
> Interestingly, this seems to also hide it as a comment, although
> troff(1) prints a warning saying that something is wrong:
> 
> 	alx@devuan:~/tmp$ cat comment.man 
> 	.TH comment 7 2026-05-18 experiments
> 	.SH Name
> 	comment \- trying different comments
> 	.SH Description
> 	Here goes one comment:
> 	.\" foo
> 	Comment ended.
> 	.P
> 	Here goes another comment?
> 	\." bar
> 	Comment ended.
> 	alx@devuan:~/tmp$ groff -Tutf8 -man -rCHECKSTYLE=3 -rLL=64n -ww comment.man 
> 	troff:comment.man:10: warning: name '"' not defined
> 	comment(7)      Miscellaneous Information Manual      comment(7)
> 
> 	Name
> 	     comment - trying different comments
> 
> 	Description
> 	     Here goes one comment: Comment ended.
> 
> 	     Here goes another comment?  Comment ended.
> 
> 	experiments                2026‐05‐18                 comment(7)
> 
> I'm curious about what happens in the roff(7) language for this to
> work as a comment.

Strictly, that input line is not treated as a comment.  The formatter
treats the line

  \." commit 48a1084a8b7423642b5f17ca6202f6f277c5392b

as a call of an undefined macro named '"'.  Yes, just the double quote.
In *roff, any printable character is valid in an identifier.

https://www.gnu.org/software/groff/manual/groff.html.node/Identifiers.html

(Using the *roff escape character in an identifier name requires a trick
or two, though.)

Arguments to undefined macros are discarded.  To be Hermes Conrad-grade
correct, not by the formatter itself, but by the automatically created
empty macro definition that does nothing with them.

https://www.gnu.org/software/groff/manual/groff.html.node/Writing-Macros.html

The input therefore operates much like the following.

  ."

Why didn't the leading backslash break this?

5.24.2 Copy Mode
----------------

...
 -- Escape sequence: \.
     '\.' quotes the control character.  It is used to permit nested
     macro definitions to end without a named macro call to conclude
     them.  Without a syntax for quoting the control character, this
     would not be possible.

          .de m1
          foo
          .  de m2
          bar
          \\..
          ..
          .m1
          .m2
              => foo bar
...

https://www.gnu.org/software/groff/manual/groff.html.node/Copy-Mode.html

(If you attempt a nested macro definition in a man(7) document, I cannot
offer any guarantee of your safety when Ingo Schwarze finds out.)

Because I endeavor always to reach greater heights of explanatory
precision, I must acknowledge that `\.` is not a true escape sequence.
It is _quotation_ syntax.  In a grammar that possesses context,
"escaping" and "quoting" move in opposite directions through nested
contextual scopes.  The founders of Unix pulled a sly trick on us all by
routinely using the same item of punctuation for both operations, like a
gear selector for an automatic transmission that uses the same position
for "drive" and "reverse".

But that's okay.  If you get something wrong while driving the PDP-11
Unixmobile, your car will either explode, stop, or an electrical relay
will loudly clunk and a giant amber "?" will appear on your otherwise
instrument-free dashboard.

In any case your journey is over.

In the patch you quoted, the line

  \." commit 48a1084a8b7423642b5f17ca6202f6f277c5392b

did _not_ occur in a copy mode context, so the formatter quietly
discarded the backslash and interpreted '.' as the control character
just as it does in "interpretation mode".

Should this discard be so quiet?  I think not.

I spitballed a relevant idea in Savannah #62776.[1]  In comment #27,
Dave Kemper helpfully summarized several that I had, some of which are
now at risk of being lost since the ticket is closed.  (Some have since
been implemented and are expected in 1.25.)

We see the following.

  `\.` encountered in interpretation mode (comment #17)

In fact, in *roff there are so many ways to "do nothing" that in 1970s
Bell Labs CSRC documents, and on into the next decade before groff
showed up, you'll find a variety of approaches to commenting.

You can see another once-popular approach to commenting in rn(1).

https://www.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Tahoe/usr/src/new/rn/rn.1

GNU troff, especially with warnings dialed up, is much more critical of
its input.

Regards,
Branden

[1] https://savannah.gnu.org/bugs/?62776

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: weird but successful *roff comment syntax (was: [PATCH] man/man2/seccomp_unotify.2: Document SECCOMP_IOCTL_NOTIF_SET_FLAGS and SECCOMP_USER_NOTIF_FD_SYNC_WAKE_UP)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 5295 bytes --]

Hi Branden,

On 2026-05-18T06:24:19-0500, G. Branden Robinson wrote:
> [looping in groff list]
> 
> Hi Alex,
> 
> At 2026-05-18T12:24:25+0200, Alejandro Colomar wrote:
> > > +.\"
> > > +.SS SECCOMP_IOCTL_NOTIF_SET_FLAGS
> > > +The
> > > +.B SECCOMP_IOCTL_NOTIF_SET_FLAGS
> > > +operation (available since Linux 6.6)
> > > +\." commit 48a1084a8b7423642b5f17ca6202f6f277c5392b
> > 
> > Typo; you meant .\"
> > It's also repeated below.
> > 
> > Interestingly, this seems to also hide it as a comment, although
> > troff(1) prints a warning saying that something is wrong:
> > 
> > 	alx@devuan:~/tmp$ cat comment.man 
> > 	.TH comment 7 2026-05-18 experiments
> > 	.SH Name
> > 	comment \- trying different comments
> > 	.SH Description
> > 	Here goes one comment:
> > 	.\" foo
> > 	Comment ended.
> > 	.P
> > 	Here goes another comment?
> > 	\." bar
> > 	Comment ended.
> > 	alx@devuan:~/tmp$ groff -Tutf8 -man -rCHECKSTYLE=3 -rLL=64n -ww comment.man 
> > 	troff:comment.man:10: warning: name '"' not defined
> > 	comment(7)      Miscellaneous Information Manual      comment(7)
> > 
> > 	Name
> > 	     comment - trying different comments
> > 
> > 	Description
> > 	     Here goes one comment: Comment ended.
> > 
> > 	     Here goes another comment?  Comment ended.
> > 
> > 	experiments                2026‐05‐18                 comment(7)
> > 
> > I'm curious about what happens in the roff(7) language for this to
> > work as a comment.
> 
> Strictly, that input line is not treated as a comment.  The formatter
> treats the line
> 
>   \." commit 48a1084a8b7423642b5f17ca6202f6f277c5392b
> 
> as a call of an undefined macro named '"'.  Yes, just the double quote.
> In *roff, any printable character is valid in an identifier.
> 
> https://www.gnu.org/software/groff/manual/groff.html.node/Identifiers.html
> 
> (Using the *roff escape character in an identifier name requires a trick
> or two, though.)
> 
> Arguments to undefined macros are discarded.  To be Hermes Conrad-grade
> correct, not by the formatter itself, but by the automatically created
> empty macro definition that does nothing with them.
> 
> https://www.gnu.org/software/groff/manual/groff.html.node/Writing-Macros.html
> 
> The input therefore operates much like the following.
> 
>   ."
> 
> Why didn't the leading backslash break this?
> 
> 5.24.2 Copy Mode
> ----------------
> 
> ...
>  -- Escape sequence: \.
>      '\.' quotes the control character.  It is used to permit nested
>      macro definitions to end without a named macro call to conclude
>      them.  Without a syntax for quoting the control character, this
>      would not be possible.
> 
>           .de m1
>           foo
>           .  de m2
>           bar
>           \\..
>           ..
>           .m1
>           .m2
>               => foo bar
> ...
> 
> https://www.gnu.org/software/groff/manual/groff.html.node/Copy-Mode.html
> 
> (If you attempt a nested macro definition in a man(7) document, I cannot
> offer any guarantee of your safety when Ingo Schwarze finds out.)
> 
> Because I endeavor always to reach greater heights of explanatory
> precision, I must acknowledge that `\.` is not a true escape sequence.
> It is _quotation_ syntax.  In a grammar that possesses context,
> "escaping" and "quoting" move in opposite directions through nested
> contextual scopes.  The founders of Unix pulled a sly trick on us all by
> routinely using the same item of punctuation for both operations, like a
> gear selector for an automatic transmission that uses the same position
> for "drive" and "reverse".
> 
> But that's okay.  If you get something wrong while driving the PDP-11
> Unixmobile, your car will either explode, stop, or an electrical relay
> will loudly clunk and a giant amber "?" will appear on your otherwise
> instrument-free dashboard.
> 
> In any case your journey is over.
> 
> In the patch you quoted, the line
> 
>   \." commit 48a1084a8b7423642b5f17ca6202f6f277c5392b
> 
> did _not_ occur in a copy mode context, so the formatter quietly
> discarded the backslash and interpreted '.' as the control character
> just as it does in "interpretation mode".
> 
> Should this discard be so quiet?  I think not.
> 
> I spitballed a relevant idea in Savannah #62776.[1]  In comment #27,
> Dave Kemper helpfully summarized several that I had, some of which are
> now at risk of being lost since the ticket is closed.  (Some have since
> been implemented and are expected in 1.25.)
> 
> We see the following.
> 
>   `\.` encountered in interpretation mode (comment #17)
> 
> In fact, in *roff there are so many ways to "do nothing" that in 1970s
> Bell Labs CSRC documents, and on into the next decade before groff
> showed up, you'll find a variety of approaches to commenting.
> 
> You can see another once-popular approach to commenting in rn(1).
> 
> https://www.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Tahoe/usr/src/new/rn/rn.1
> 
> GNU troff, especially with warnings dialed up, is much more critical of
> its input.
> 
> Regards,
> Branden
> 
> [1] https://savannah.gnu.org/bugs/?62776

Thanks!  :-)


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]