From: Peter Collingbourne <pcc@google.com>
To: Catalin Marinas <catalin.marinas@arm.com>,
Evgenii Stepanov <eugenis@google.com>,
Kostya Serebryany <kcc@google.com>,
Vincenzo Frascino <vincenzo.frascino@arm.com>,
Dave Martin <Dave.Martin@arm.com>, Will Deacon <will@kernel.org>,
Oleg Nesterov <oleg@redhat.com>,
"Eric W. Biederman" <ebiederm@xmission.com>,
"James E.J. Bottomley" <James.Bottomley@hansenpartnership.com>,
Michael Kerrisk <mtk.manpages@gmail.com>,
Alejandro Colomar <alx.manpages@gmail.com>
Cc: Peter Collingbourne <pcc@google.com>,
Linux ARM <linux-arm-kernel@lists.infradead.org>,
Kevin Brodsky <kevin.brodsky@arm.com>,
Andrey Konovalov <andreyknvl@gmail.com>,
linux-api@vger.kernel.org, Helge Deller <deller@gmx.de>,
David Spickett <david.spickett@linaro.org>,
linux-man@vger.kernel.org
Subject: [PATCH v4] sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection protocol
Date: Thu, 15 Jul 2021 13:46:10 -0700 [thread overview]
Message-ID: <20210715204610.575999-1-pcc@google.com> (raw)
Signed-off-by: Peter Collingbourne <pcc@google.com>
---
v4:
- s/.BR/.BR/ in one location
- 4 space indentation
- raise(SIGSEGV) instead of manual SIGSEGV
- use C99 initialization
v3:
- s/5.x/5.11/g
- s/.IR/.I/ in one location
v2:
- fix formatting
- address feedback from Dave
man2/sigaction.2 | 123 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 123 insertions(+)
diff --git a/man2/sigaction.2 b/man2/sigaction.2
index 57ad6418c..4bf6f095e 100644
--- a/man2/sigaction.2
+++ b/man2/sigaction.2
@@ -261,6 +261,44 @@ This flag is meaningful only when establishing a signal handler.
.\" .I sa_sigaction
.\" field was added in Linux 2.1.86.)
.\"
+.TP
+.B SA_UNSUPPORTED
+Used to dynamically probe for flag bit support.
+.IP
+If an attempt to register a handler succeeds with this flag set in
+.I act->sa_flags
+alongside other flags that are potentially unsupported by the kernel,
+and an immediately subsequent
+.BR sigaction ()
+call specifying the same signal number n and with non-NULL
+.I oldact
+yields
+.B SA_UNSUPPORTED
+.I clear
+in
+.IR oldact->sa_flags ,
+then
+.I oldact->sa_flags
+may be used as a bitmask
+describing which of the potentially unsupported flags are,
+in fact, supported.
+See the section "Dynamically probing for flag bit support"
+below for more details.
+.TP
+.BR SA_EXPOSE_TAGBITS " (since Linux 5.11)"
+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,
+an architecture-specific subset of the tag bits will be preserved in
+.IR si_addr .
+.IP
+Programs that need to be compatible with Linux versions older than 5.11
+must use
+.B SA_UNSUPPORTED
+to probe for support.
.SS The siginfo_t argument to a SA_SIGINFO handler
When the
.B SA_SIGINFO
@@ -846,6 +884,91 @@ Triggered by a
.BR seccomp (2)
filter rule.
.RE
+.SS Dynamically probing for flag bit support
+The
+.BR sigaction ()
+call on Linux accepts unknown bits set in
+.I act->sa_flags
+without error.
+The behavior of the kernel starting with Linux 5.11 is that a second
+.BR sigaction ()
+will clear unknown bits from
+.IR oldact->sa_flags .
+However, historically, a second
+.BR sigaction ()
+call would typically leave those bits set in
+.IR oldact->sa_flags .
+.PP
+This means that support for new flags cannot be detected
+simply by testing for a flag in
+.IR sa_flags ,
+and a program must test that
+.B SA_UNSUPPORTED
+has been cleared before relying on the contents of
+.IR sa_flags .
+.PP
+Since the behavior of the signal handler cannot be guaranteed
+unless the check passes,
+it is wise to either block the affected signal
+while registering the handler and performing the check in this case,
+or where this is not possible,
+for example if the signal is synchronous, to issue the second
+.BR sigaction ()
+in the signal handler itself.
+.PP
+In kernels that do not support a specific flag,
+the kernel's behavior is as if the flag was not set,
+even if the flag was set in
+.IR act->sa_flags .
+.PP
+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
+may not be reliably probed for using this mechanism,
+because they were introduced before Linux 5.11.
+However, in general, programs may assume that these flags are supported,
+since they have all been supported since Linux 2.6,
+which was released in the year 2003.
+.PP
+The following example program exits with status 0 if
+.B SA_EXPOSE_TAGBITS
+is determined to be supported, and 1 otherwise.
+.PP
+.EX
+#include <signal.h>
+#include <stdio.h>
+#include <unistd.h>
+
+void handler(int signo, siginfo_t *info, void *context) {
+ struct sigaction oldact;
+ if (sigaction(SIGSEGV, 0, &oldact) == 0 &&
+ !(oldact.sa_flags & SA_UNSUPPORTED) &&
+ (oldact.sa_flags & SA_EXPOSE_TAGBITS)) {
+ _exit(0);
+ } else {
+ _exit(1);
+ }
+}
+
+int main(void) {
+ struct sigaction act = {0};
+ act.sa_flags = SA_SIGINFO | SA_UNSUPPORTED | SA_EXPOSE_TAGBITS;
+ act.sa_sigaction = handler;
+ if (sigaction(SIGSEGV, &act, 0) != 0) {
+ perror("sigaction");
+ return 1;
+ }
+
+ raise(SIGSEGV);
+}
+.EE
.SH RETURN VALUE
.BR sigaction ()
returns 0 on success; on error, \-1 is returned, and
--
2.32.0.402.g57bb445576-goog
next reply other threads:[~2021-07-15 20:46 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-07-15 20:46 Peter Collingbourne [this message]
2021-07-28 20:13 ` [PATCH v4] sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection protocol Alejandro Colomar (man-pages)
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210715204610.575999-1-pcc@google.com \
--to=pcc@google.com \
--cc=Dave.Martin@arm.com \
--cc=James.Bottomley@hansenpartnership.com \
--cc=alx.manpages@gmail.com \
--cc=andreyknvl@gmail.com \
--cc=catalin.marinas@arm.com \
--cc=david.spickett@linaro.org \
--cc=deller@gmx.de \
--cc=ebiederm@xmission.com \
--cc=eugenis@google.com \
--cc=kcc@google.com \
--cc=kevin.brodsky@arm.com \
--cc=linux-api@vger.kernel.org \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-man@vger.kernel.org \
--cc=mtk.manpages@gmail.com \
--cc=oleg@redhat.com \
--cc=vincenzo.frascino@arm.com \
--cc=will@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).