featuretest man page?

[Alan Barrett <apb%cequrux.com@localhost>]

On Thu, 13 Mar 2008, Christos Zoulas wrote:
> The netsurf developer should not be defining _FOO_SOURCE if he intends
> to use symbols outside the scope of _FOO_SOURCE.

Is there a man page with the information that's in the comment block
near the top of <sys/featuretest.h>?  I'd suggest featuretest(3), with a
bunch of links so that "man _POSIX_C_SOURCE" finds the right man page.

It would be nice it such a man page contained a detailed explanation of
how we arrived at the rules about certain macros disabling features that
would have been available by default while other macros do not do that.

In the case of _POSIX_C_SOURCE (at least when the value is 200112L),
I found a definition at
<http://www.opengroup.org/onlinepubs/009695399/functions/xsh_chap02_02.html#tag_02_02_01_01>.
This says "Additional symbols not required or explicitly permitted
by IEEE Std 1003.1-2001 to be in that header shall not be made
visible, except when enabled by another feature test macro."

Close to the above-mentioned description of _POSIX_C_SOURCE is a
description of _XOPEN_SOURCE (at least when it has the value 600).  The
way it refers to "the functionality described in The _POSIX_C_SOURCE
feature test macro" implies that the clause about "additional symbols
... shall not be made visible" carries over to _XOPEN_SOURCE, but it's
not obvious on first glance.

I couldn't find any reference to __STDC_VERSION__, _ANSI_SOURCE, or
_ISOC99_SOURCE in the WG14/N1124 draft of the ISO C99 standard.  My
paper copy of the C89 standard is not close at hand, and I cou;dn;t find
an on-line copy.

--apb (Alan Barrett)