RFC: handling ISO C feature test macros

[Michael Kerrisk]

On Sat, May 28, 2016 at 5:03 AM, Roland McGrath <roland@hack.frob.com> wrote:

> While I'm stating relevant principles, I also want to point out that
> features.h and __USE_* macros were always intended as internal
> implementation details.  Unfortunately, they have leaked out to where
> some application and library code does '#include <features.h>' itself
> and even looks at __USE_* macros.  In whatever we do for the future, we
> should avoid providing more of such ammunition for users to point at
> their feet (and for library maintainers to point at their users' feet).

I can't resist pointing out here that this problem is surely almost
100% attributable to the failure of the glibc manual to document the
FTM requirements of the various APIs. Therefore users do what they
always do in the absence of documentation: try to puzzle out the
details by looking at the source, and in the headers they quickly
discover the __USE_* macros that seem to solve their problem.

I started trying to stem this tide about 10 years ago, when man-pages
added http://man7.org/linux/man-pages/man7/feature_test_macros.7.html
and over the subsequent years I've steadily added annotations to each
man page on the FTM requirements for each API. (I'd say that we might
be at 80 to 90% coverage by now.) But, I imagine much of the damage
was already done before I first created feature_test_macros(7).

So, I'd say that whatever is done in the future should include good
documentation.

Cheers,

Michael