Skip to contentSkip to conversation

SA_RESTART and friends as XSI extensions to POSIX.1-2001 < XOPEN_SOURCE >= 600

PATCH In review Thomas Orgis 2 participants 8 messages Feb 14, 2024 – Feb 27, 2024 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

Hi,

I had trouble compiling code with -std=c99 and needed some time to figure out why the use of SA_RESTART did not work with

#define _POSIX_C_SOURCE 200112L

despite the man page of sigaction suggesting that this would be the correct feature test macro. Searching around the net reveals that this is a known discrepancy between man pages and glibc since at least 11 years. People stumble over this, learn, forget. Please let's document it this time;-)

sigaction(2) claims this:

POSIX.1-2001 added
.BR SA_NOCLDSTOP ,
.BR SA_NOCLDWAIT ,
.BR SA_NODEFER ,
.BR SA_ONSTACK ,
.BR SA_RESETHAND ,
.BR SA_RESTART ,
and
.BR SA_SIGINFO .

All of these are extensions (XSI) to POSIX and need _XOPEN_SOURCE 600.

Quoting https://pubs.opengroup.org/onlinepubs/009695399/basedefs/signal.h.html
(thanks to https://unix.stackexchange.com/questions/613139/sigaction-sa-flags-and-posix-1-2001-base-spec):

The following shall be declared as constants:

SA_NOCLDSTOP
[CX] [Option Start] Do not generate SIGCHLD when children stop [Option End]
[XSI] [Option Start] or stopped children continue. [Option End]
[...]
SA_ONSTACK
[XSI] [Option Start] Causes signal delivery to occur on an alternate stack. [Option End]
SA_RESETHAND
[XSI] [Option Start] Causes signal dispositions to be set to SIG_DFL on entry to signal handlers. [Option End]
SA_RESTART
[XSI] [Option Start] Causes certain functions to become restartable. [Option End]
SA_SIGINFO
[XSI] [Option Start] Causes extra information to be passed to signal handlers at the time of receipt of a signal. [Option End]
SA_NOCLDWAIT
[XSI] [Option Start] Causes implementations not to create zombie processes on child death. [Option End]
SA_NODEFER
[XSI] [Option Start] Causes signal not to be automatically blocked on entry to signal handler. [Option End]

[and not mentioned in the man page, not relevant?]

SS_ONSTACK
[XSI] [Option Start] Process is executing on an alternate signal stack. [Option End]
SS_DISABLE
[XSI] [Option Start] Alternate signal stack is disabled. [Option End]
MINSIGSTKSZ
[XSI] [Option Start] Minimum stack size for a signal handler. [Option End]
SIGSTKSZ
[XSI] [Option Start] Default size in bytes for the alternate signal stack. [Option End]

As a related bit, I noticed that feature_test_macros(7) is a bit misleading here:

.IP \[bu]
Defining
.B _XOPEN_SOURCE
with a value of 600 or greater produces the same effects as defining .B _POSIX_C_SOURCE
with a value of 200112L or greater.

As written later on the same page, X_OPEN_SOURCE 600 triggers a superset of POSIX, not the same effects.

I hope these rather small changes can be made by a committer without lengthy discussion of patches. I suggest something along this, without formatting details that I'd get wrong:

sigaction(2):

POSIX.1-2001 added
.BR SA_NOCLDSTOP ,
.BR SA_NOCLDWAIT ,
.BR SA_NODEFER ,
.BR SA_ONSTACK ,
.BR SA_RESETHAND ,
.BR SA_RESTART ,
and
.BR SA_SIGINFO ,
as XSI extensions (define _XOPEN_SOURCE to at least 600 to use).

feature_test_macros(7):

.IP \[bu]
Defining
.B _XOPEN_SOURCE
with a value of 600 or greater includes the effects of defining
.B _POSIX_C_SOURCE
with a value of 200112L or greater, adding the X/Open System Interfaces Extension (XSI).

Alrighty then,

Thomas

Signature · 3 lines
GPG public key 60D5CAFE: https://thomas.orgis.org/public_key
Fingerprint: D021 FF8E CF4B E097 19D6  1A27 231C 4CBC 60D5 CAFE
And despite all of you, I'm still doing it. Yes, I do write Perl code.
#1 lore raw

Status of SA_NOCLDWAIT in POSIX.1 (was: SA_RESTART and friends as XSI extensions to POSIX.1-2001 < XOPEN_SOURCE >= 600)

Hi Eric,

I received a bug report for the Linux man-pages' sigaction(2) HISTORY section, regarding some constants being XSI extensions in POSIX.1-2001 while the manual page was silent about it (so the user didn't understand why their feature test macros weren't being enough.

While trying to write correct HISTORY for those constants, I realized about an inconsistency in POSIX.1-2008 (2017 revision), in
<https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html>.

The DESCRIPTION (normative) section of signal.h says SA_NOCLDWAIT is an XSI extension:

SA_NOCLDWAIT
[XSI] [Option Start] Causes implementations not to create zombie processes or status information on child termination. See sigaction. [Option End]

But then, the CHANGE HISTORY (informative) section says about Issue 7:

The SA_RESETHAND, SA_RESTART, SA_SIGINFO, SA_NOCLDWAIT, and SA_NODEFER constants are moved from the XSI option to the Base.

That seems like an accident, since 'SA_NOCLDWAIT' wasn't moved to base, right?

Please forward this to the Austin group if you find it appropriate.

Have a lovely day!
Alex

Signature · 2 lines
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.
#2 lore raw

cover sigaction.2: HISTORY: Document history of POSIX constants more accurately

In reply to Thomas Orgis

Hi Thomas,

Thanks for your bug report in
<https://lore.kernel.org/linux-man/20240214095707.1824c25c@plasteblaster/T/#m9dfdb5e0362404de9e720afda72d181b14a93159>
I've prepared the following two patches. Please review.

Have a lovely day!
Alex

Alejandro Colomar (2):
sigaction.2: HISTORY: SA_NOCLDSTOP wasn't added in POSIX.1-2001 sigaction.2: HISTORY: Some constants are or were XSI extensions

 man2/sigaction.2 | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)
Signature · 1 line
2.43.0
#3 lore raw

PATCH 1/2 sigaction.2: HISTORY: SA_NOCLDSTOP wasn't added in POSIX.1-2001

It already existed in POSIX.1-1996, according to just a few lines above.

---
 man2/sigaction.2 | 1 -
 1 file changed, 1 deletion(-)
man2/sigaction.2 +0 -1
index 0bbc44bd5..b64dcaf2b 100644
@@ -1020,7 +1020,6 @@ .SH HISTORY
 POSIX.1-1990 specified only
 .BR SA_NOCLDSTOP .
 POSIX.1-2001 added
-.BR SA_NOCLDSTOP ,
 .BR SA_NOCLDWAIT ,
 .BR SA_NODEFER ,
 .BR SA_ONSTACK ,
Signature · 1 line
2.43.0
#4 lore raw

Re: [PATCH 1/2] sigaction.2: HISTORY: SA_NOCLDSTOP wasn't added in POSIX.1-2001

Hi,

apart from

Am 25. Februar 2024 12:53:15 MEZ schrieb Alejandro Colomar <[email protected]>:

Quoted 1 line

It already existed in POSIX.1-1996, according to just a few lines above.

... it existing in 1990, not 1996? Or is

Quoted 2 lines
(quoted diff) +0 -0
@@ -1020,7 +1020,6 @@ .SH HISTORY

POSIX.1-1990 specified only

a typo? I am by no means an expert on POSIX revisions. More interesting in this context seems to be the subtle change in SA_NOCLDSTOP behaviour with XSI enabled noted in the spec

https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaction.html

SA_NOCLDSTOP[CX] Do not generate SIGCHLD when children stop [XSI] or stopped children continue.

Should this detail be documented, too, for this flag? Get SIGCHLD only if continuing, not when stopping unless with XSI?

Alrighty then,

Thomas

Signature · 1 line
sent from mobile device, trustworthy or not
#5 lore raw

Re: [PATCH 1/2] sigaction.2: HISTORY: SA_NOCLDSTOP wasn't added in POSIX.1-2001

Hi Thomas,

Quoted 4 lines · Thomas Orgis

Am 25. Februar 2024 12:53:15 MEZ schrieb Alejandro Colomar <[email protected]>:

Quoted 1 line

It already existed in POSIX.1-1996, according to just a few lines above.

... it existing in 1990, not 1996? Or is

Oops, I misread. It's my accident in the commit message. :)

Quoted 8 lines
Quoted 3 lines
(quoted diff) +0 -0
@@ -1020,7 +1020,6 @@ .SH HISTORY

POSIX.1-1990 specified only

a typo? I am by no means an expert on POSIX revisions. More interesting in this context seems to be the subtle change in SA_NOCLDSTOP behaviour with XSI enabled noted in the spec

Quoted 7 lines

https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaction.html

SA_NOCLDSTOP[CX] Do not generate SIGCHLD when children stop [XSI] or stopped children continue.

Should this detail be documented, too, for this flag? Get SIGCHLD only if continuing, not when stopping unless with XSI?

Yup, I also noticed that. I'm no expert in that, so I would be more comfortable if you or someone else send a patch.

Have a lovely night!
Alex

Signature · 2 lines
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.
#6 lore raw

PATCH 2/2 sigaction.2: HISTORY: Some constants are or were XSI extensions

In reply to Alejandro Colomar
---
 man2/sigaction.2 | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)
man2/sigaction.2 +9 -1
index b64dcaf2b..daca34a27 100644
@@ -1026,7 +1026,15 @@ .SH HISTORY
 .BR SA_RESETHAND ,
 .BR SA_RESTART ,
 and
-.BR SA_SIGINFO .
+.B SA_SIGINFO
+as XSI extensions.
+POSIX.1-2008 moved
+.BR SA_NODEFER ,
+.BR SA_RESETHAND ,
+.BR SA_RESTART ,
+and
+.B SA_SIGINFO
+to the base specifications.
 Use of these latter values in
 .I sa_flags
 may be less portable in applications intended for older
Signature · 1 line
2.43.0
#7 lore raw

Re: [PATCH 2/2] sigaction.2: HISTORY: Some constants are or were XSI extensions

Looks fine to me, thanks. Now one can deduce that an additional feature test macro might be needed.

Am 25. Februar 2024 12:53:19 MEZ schrieb Alejandro Colomar <[email protected]>:

Quoted 28 lines

---
man2/sigaction.2 | 10 +++++++++-

1 file changed, 9 insertions(+), 1 deletion(-)
man2/sigaction.2 +0 -0
index b64dcaf2b..daca34a27 100644
@@ -1026,7 +1026,15 @@ .SH HISTORY
 .BR SA_RESETHAND ,
 .BR SA_RESTART ,

and
-.BR SA_SIGINFO .
+.B SA_SIGINFO

man2/sigaction.2 +8 -0
+as XSI extensions.
+POSIX.1-2008 moved
+.BR SA_NODEFER ,
+.BR SA_RESETHAND ,
+.BR SA_RESTART ,
+and
+.B SA_SIGINFO
+to the base specifications.

Use of these latter values in
.I sa_flags
may be less portable in applications intended for older

Signature · 1 line
sent from mobile device, trustworthy or not