From: Peter Collingbourne <pcc@xxxxxxxxxx> Signed-off-by: Peter Collingbourne <pcc@xxxxxxxxxx> [alx: srcfix + ffix] Cowritten-by: Alejandro Colomar <alx.manpages@xxxxxxxxx> Signed-off-by: Alejandro Colomar <alx.manpages@xxxxxxxxx> --- 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
