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

[Peter Collingbourne]

---
These features are implemented in this patch series:
  https://lore.kernel.org/linux-arm-kernel/cover.1605235762.git.pcc@google.com/
which is still under review, so the patch should not be applied
yet.

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

diff --git a/man2/sigaction.2 b/man2/sigaction.2
index 6a8142324..82fb69e26 100644
--- a/man2/sigaction.2
+++ b/man2/sigaction.2
@@ -250,6 +250,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.x)"
+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.x)"
+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
@@ -833,6 +846,55 @@ 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.
+
+Starting with Linux 5.x, 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.x
+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 .
+
+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.x. 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.
+
+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 ,
+.B 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.29.2.299.gdc1121823c-goog