SA_ONSTACK: man page and glibc reference manual in conflict

[Florian Weimer]

* Alejandro Colomar:

> Hi all,
>
> On 1/31/22 10:29, Ivan Zuboff wrote:
>> Hello!
>> 
>> Man page says:
>> SA_ONSTACK
>>               Call the signal handler on an alternate signal stack
>>               provided by sigaltstack(2).  *If an alternate stack is not
>>               available, the default stack will be used.*  This flag is
>>               meaningful only when establishing a signal handler.
>> https://man7.org/linux/man-pages/man2/sigaction.2.html
>> 
>> glibc reference manual says:
>> Macro: int SA_ONSTACK
>> If this flag is set for a particular signal number, the system uses
>> the signal stack when delivering that kind of signal. See Signal
>> Stack. *If a signal with this flag arrives and you have not set a
>> signal stack, the system terminates the program with SIGILL.*
>> https://www.gnu.org/software/libc/manual/html_node/Flags-for-Sigaction.html
>> 
>> As far as I understand, statements in *stars* are in conflict. glibc
>> documentation says that "While the glibc manual remains the canonical
>> source for API descriptions, the man-pages are an excellent
>> reference.", so I decided to mail you supposing that man page is
>> incorrect in this regard.
>> https://www.gnu.org/software/libc/documentation.html
>> 
>> Please correct me if I'm wrong. Also, sorry for my bad English, this
>> is not my native language.
>> 
>> Best regards,
>> Ivan
>
> I received this bug report on linux-man@.  The report is about a text
> that predates git in the man-pages.  Could you please confirm the bug,
> and check if anything else needs to be fixed too?

It's a bug in the glibc documentation.  POSIX says:

| SA_ONSTACK
|     [XSI] [Option Start] If set and an alternate signal stack has been
|     declared with sigaltstack(), the signal shall be delivered to the
|     calling process on that stack. Otherwise, the signal shall be
|     delivered on the current stack. [Option End]

And that's also the Linux behavior.

Thanks,
Florian