This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: RFC: handling ISO C feature test macros
- From: Michael Kerrisk <mtk dot manpages at gmail dot com>
- To: Roland McGrath <roland at hack dot frob dot com>
- Cc: Joseph Myers <joseph at codesourcery dot com>, libc-alpha <libc-alpha at sourceware dot org>, Michael Kerrisk-manpages <mtk dot manpages at gmail dot com>
- Date: Fri, 10 Jun 2016 16:51:17 +0200
- Subject: Re: RFC: handling ISO C feature test macros
- Authentication-results: sourceware.org; auth=none
- References: <alpine dot DEB dot 2 dot 20 dot 1605202135440 dot 24104 at digraph dot polyomino dot org dot uk> <20160528030332 dot E4DD12C3D10 at topped-with-meat dot com>
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