man/man2/seccomp_unotify.2: Document SECCOMP_IOCTL_NOTIF_SET_FLAGS and SECCOMP_USER_NOTIF_FD_SYNC_WAKE_UP

PATCH In review funsafemath 3 participants 4 messages May 18 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

funsafemath

author

2026-05-18 05:51 UTC #0 lore raw

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

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/[email protected]>

Signed-off-by funsafemath <[email protected]>

---
 man/man2/seccomp_unotify.2 | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

man/man2/seccomp_unotify.2 +36 -0

index a5c1a4423..70b2996a9 100644
@@ -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

Signature · 1 line

2.52.0

Alejandro Colomar

maintainer

2026-05-18 10:24 UTC #1 lore raw

Hi,

Quoted 8 lines · funsafemath

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/[email protected]>
Signed-off-by funsafemath <[email protected]>

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

Have a lovely day!
Alex

Quoted 17 lines

---
 man/man2/seccomp_unotify.2 | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

man/man2/seccomp_unotify.2 +1 -0

index a5c1a4423..70b2996a9 100644
@@ -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

man/man2/seccomp_unotify.2 .SS SECCOMP_IOCTL_NOTIF_ADDFD · line 890

Quoted 9 lines

man/man2/seccomp_unotify.2 +6 -0

@@ -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.

Quoted 35 lines

man/man2/seccomp_unotify.2 +29 -0

+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

Signature · 1 line

2.52.0

Signature · 1 line

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

G. Branden Robinson

2026-05-18 11:24 UTC #2 lore raw

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)

[looping in groff list]

Hi Alex,

Quoted 35 lines · Alejandro Colomar

man/man2/seccomp_unotify.2 .SS SECCOMP_IOCTL_NOTIF_ADDFD · line 890
Quoted 6 lines
+.\"
+.SS SECCOMP_IOCTL_NOTIF_SET_FLAGS
man/man2/seccomp_unotify.2 +4 -0
+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.

Quoted 6 lines

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

Alejandro Colomar

maintainer

2026-05-18 12:16 UTC #3 lore raw

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)

Hi Branden,

Quoted 141 lines · G. Branden Robinson

[looping in groff list]
Hi Alex,
Quoted 35 lines · Alejandro Colomar
man/man2/seccomp_unotify.2 .SS SECCOMP_IOCTL_NOTIF_ADDFD · line 890
Quoted 6 lines
+.\"
+.SS SECCOMP_IOCTL_NOTIF_SET_FLAGS
man/man2/seccomp_unotify.2 +4 -0
+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.
Quoted 6 lines
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

Quoted 7 lines

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

Signature · 1 line

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