All of lore.kernel.org
 help / color / mirror / Atom feed
From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: Alejandro Colomar <alx.manpages@gmail.com>
Cc: mtk.manpages@gmail.com, Peter Collingbourne <pcc@google.com>,
	linux-man@vger.kernel.org
Subject: Re: [PATCH 02/23] sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection protocol
Date: Mon, 9 Aug 2021 02:29:16 +0200	[thread overview]
Message-ID: <8156082d-5a61-e240-4954-85e55dcc1e5f@gmail.com> (raw)
In-Reply-To: <20210808084133.734274-3-alx.manpages@gmail.com>

Hello Peter and Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: Peter Collingbourne <pcc@google.com>
> 
> Signed-off-by: Peter Collingbourne <pcc@google.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks for this patch Peter. Applied.

Cheers,

Michael

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


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

  reply	other threads:[~2021-08-09  0:29 UTC|newest]

Thread overview: 60+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-08-08  8:41 [PATCH 00/23] More patches from others Alejandro Colomar
2021-08-08  8:41 ` [PATCH 01/23] pipe.7: also mention writev(2) in atomicity section Alejandro Colomar
2021-08-08 13:20   ` Alejandro Colomar (man-pages)
2021-08-08 20:06     ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 02/23] sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection protocol Alejandro Colomar
2021-08-09  0:29   ` Michael Kerrisk (man-pages) [this message]
2021-08-08  8:41 ` [PATCH 03/23] sigaction.2: Apply minor tweaks to Peter's patch Alejandro Colomar
2021-08-09  0:34   ` Michael Kerrisk (man-pages)
2021-08-09  6:36     ` Alejandro Colomar (man-pages)
2021-08-08  8:41 ` [PATCH 04/23] namespaces.7: ffix Alejandro Colomar
2021-08-08 20:08   ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 05/23] unix.7: tfix Alejandro Colomar
2021-08-08 20:23   ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 06/23] futex.2: Document FUTEX_LOCK_PI2 Alejandro Colomar
2021-08-09  0:06   ` Michael Kerrisk (man-pages)
2021-08-09  8:14     ` Kurt Kanzenbach
2021-08-09  9:01       ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 07/23] futex.2: Minor tweaks to Kurt's patch Alejandro Colomar
2021-08-09  0:05   ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 08/23] man2: new page describing memfd_secret() system call Alejandro Colomar
2021-08-09  2:00   ` Michael Kerrisk (man-pages)
2021-08-10  8:53     ` Mike Rapoport
2021-08-08  8:41 ` [PATCH 09/23] termios.3: Document missing baudrate constants Alejandro Colomar
2021-08-08 20:30   ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 10/23] getopt.3: Further clarification of optstring Alejandro Colomar
2021-08-08 22:11   ` Michael Kerrisk (man-pages)
2021-08-09  6:40     ` Alejandro Colomar (man-pages)
2021-08-08  8:41 ` [PATCH 11/23] getopt.3: Minor tweak to James's patch Alejandro Colomar
2021-08-08 22:12   ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 12/23] termios.3: Use bold style for Bnn and EXTn macro constants Alejandro Colomar
2021-08-08 20:31   ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 13/23] ioctl_tty.2: Document ioctls: TCGETS2, TCSETS2, TCSETSW2, TCSETSF2 Alejandro Colomar
2021-08-08 20:37   ` Michael Kerrisk (man-pages)
2021-08-08 20:56   ` Michael Kerrisk (man-pages)
2021-08-08 21:15     ` Pali Rohár
2021-08-08 21:30       ` Michael Kerrisk (man-pages)
2021-08-10 19:11     ` Pali Rohár
2021-08-10 20:40       ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 14/23] ioctl_tty.2: Update DTR example Alejandro Colomar
2021-08-08 20:12   ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 15/23] termios.3: Add information how to set baud rate to any other value Alejandro Colomar
2021-08-08 20:34   ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 16/23] man-pages.7: wfix Alejandro Colomar
2021-08-08 20:09   ` Michael Kerrisk (man-pages)
2021-10-17 19:42   ` Alejandro Colomar (man-pages)
2021-08-08  8:41 ` [PATCH 17/23] termios.3: ffix Alejandro Colomar
2021-08-08 20:35   ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 18/23] termios.3: SPARC architecture has 4 different Bnnn constants Alejandro Colomar
2021-08-08 20:36   ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 19/23] regex.3: wfix Alejandro Colomar
2021-08-08 20:11   ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 20/23] mount_setattr.2: New manual page documenting the mount_setattr() system call Alejandro Colomar
2021-08-10  1:34   ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 21/23] mount_setattr.2: Minor tweaks to Chirstian's patch Alejandro Colomar
2021-08-10  1:35   ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 22/23] ldd.1: Fix example command Alejandro Colomar
2021-08-08 22:32   ` Michael Kerrisk (man-pages)
2021-08-08  8:41 ` [PATCH 23/23] close_range.2: Glibc added a wrapper recently Alejandro Colomar
2021-08-08 20:58   ` Michael Kerrisk (man-pages)
2021-08-10  1:39 ` [PATCH 00/23] More patches from others Michael Kerrisk (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=8156082d-5a61-e240-4954-85e55dcc1e5f@gmail.com \
    --to=mtk.manpages@gmail.com \
    --cc=alx.manpages@gmail.com \
    --cc=linux-man@vger.kernel.org \
    --cc=pcc@google.com \
    /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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.