[PATCH] sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection protocol

[Alejandro Colomar <alx.manpages@gmail.com>]

From: Peter Collingbourne <pcc@google.com>

Signed-off-by: Peter Collingbourne <pcc@google.com>
[alx: srcfix + ffix]
Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---

Hi Michael,

as Peter noted, this patch is not ready
(code hasn't been merged into the kernel yet).

And a spin-off question:
How would you prefer it?:
[
.B SA_*
] (there are 79 similar cases in the pages [1])
or
[
.BR SA_ *
] (there are 3 similar cases in the pages [2])


Hi Peter,

I improved a few minor things in your patch:

- Use semantic newlines (see man-pages(7)).
- Change explicit blank lines to [.PP]
  (see 'Formatting conventions(general)' in man-pages(7)).
- Use Oxford comma.


Thanks,

Alex


[1](grep -r "_\*" man? | wc -l)
[2](grep -r "_ \*" man? | wc -l)

 man2/sigaction.2 | 65 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/man2/sigaction.2 b/man2/sigaction.2
index 22da658d0..91c46f3e3 100644
--- a/man2/sigaction.2
+++ b/man2/sigaction.2
@@ -251,6 +251,19 @@ This flag is meaningful only when establishing a signal handler.
 .\" .I sa_sigaction
 .\" field was added in Linux 2.1.86.)
 .\"
+.TP
+.BR SA_UNSUPPORTED " (since Linux 5.??)"
+This flag bit will never be supported by the kernel.
+It is used as part of the flag support detection protocol described below.
+.TP
+.BR SA_EXPOSE_TAGBITS " (since Linux 5.??)"
+Normally, when delivering a signal,
+an architecture-specific set of tag bits are cleared from the
+.I si_addr
+field of
+.IR siginfo_t .
+If this flag is set, the tag bits will be preserved in
+.IR si_addr .
 .SS The siginfo_t argument to a SA_SIGINFO handler
 When the
 .B SA_SIGINFO
@@ -834,6 +847,58 @@ Triggered by a
 .BR seccomp (2)
 filter rule.
 .RE
+.SS Detecting flag support in sa_flags
+The Linux kernel supports a mechanism for programs to
+detect kernel support for
+.B SA_*
+flags in
+.IR sa_flags .
+This mechanism is quite subtle for backwards compatibility reasons
+related to the historical behavior of the kernel.
+.PP
+Starting with Linux 5.??,
+the kernel will clear any unrecognized bits from the
+.I sa_flags
+value returned via
+.I oldact
+if those bits were set when the signal handler was originally installed.
+Therefore, a program that only needs to be compatible with
+Linux 5.?? and above
+may test for flag bit support by issuing a second call to
+.BR sigaction ()
+and testing whether the bit remains set in
+.IR oldact.sa_flags .
+.PP
+Prior to Linux 5.x, unrecognized flag bits were preserved in
+.I oldact.sa_flags
+so this protocol on its own would not be sufficient to allow a
+userspace program to test for flag bit support
+if it needs to be compatible with kernel versions older than 5.??.
+Therefore, the
+.B SA_UNSUPPORTED
+flag bit was defined,
+which the kernel will always consider to be unknown.
+A userspace program that sets this flag bit in
+.I act.sa_flags
+and finds that it has been cleared in
+.I oldact.sa_flags
+in a subsequent call to
+.BR sigaction ()
+may trust that any other unknown flag bits have been cleared.
+.PP
+A reasonably modern program may trust that the flags
+.BR SA_NOCLDSTOP ,
+.BR SA_NOCLDWAIT ,
+.BR SA_SIGINFO ,
+.BR SA_ONSTACK ,
+.BR SA_RESTART ,
+.BR SA_NODEFER ,
+.BR SA_RESETHAND ,
+and, if defined by the architecture,
+.B SA_RESTORER
+are supported by the kernel,
+without relying on the flag bit support detection protocol,
+since these flags have all been supported since Linux 2.6.
 .SH RETURN VALUE
 .BR sigaction ()
 returns 0 on success; on error, \-1 is returned, and
-- 
2.28.0