SA_ONSTACK: man page and glibc reference manual in conflict

SA_ONSTACK: man page and glibc reference manual in conflict

[Ivan Zuboff]

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

Re: SA_ONSTACK: man page and glibc reference manual in conflict

[Alejandro Colomar (man-pages)]

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?

Thanks,

Alex

Ivan:  Thanks for the report!  In non-trivial cases such as this one,
it's useful to CC the glibc mailing list, since they probably know more
than I about details such as this one. ;)

Cheers,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

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