This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH v2 3/5] manual: Add new header and standards annotations.
On Tue, 6 Dec 2016, Zack Weinberg wrote:
> > But actually I expect plenty of __USE_MISC declarations came from other
> > sources, including GNU-invented things that happen to be declared by
> > default (in headers that aren't themselves GNU-invented) rather than just
> > with _GNU_SOURCE.
>
> Yeah, I've noticed cases like that myself.
>
> So the rationale I gave was wrong, but I think the point - MISC is not a
> useful thing to say in the manual - is only underlined by your
> observations. Yes?
It gives the information that something is declared by default. It might
be refined to give more information about the origin of the interface, but
it's still useful information.
> So, how useful do you think the older POSIX/XPG/whatever conformance
> modes actually are nowadays? Could we conceivably get away with pruning
I don't have a clear notion of how people use the conformance modes (any
of them) in general. Those modes aren't problematic to support the way
pre-ISO-C standards are (and we exclude the odd feature from them that's
problematic to support).
> plus the semi-orthogonal LFS and ATFILE toggles?
It's not clear to me that ATFILE is a useful toggle now (it's a subset of
_POSIX_C_SOURCE=200809L). (For that matter, _LARGEFILE_SOURCE, as opposed
to __LARGEFILE64_SOURCE, only enables declarations of fseeko / ftello,
which are also in POSIX.1-2001 as well as UNIX 98. And features.h defines
a macro _ISOC95_SOURCE which is never used at all.)
> > The __aeabi_* functions don't have header declarations, just an ABI.
> > (There are ARM extension APIs with headers - defined in ACLE - but those
> > are generally pure header / compiler intrinsic APIs with no corresponding
> > library functions.)
>
> Does that mean they shouldn't be documented, in your opinion? / Does
> that mean we don't need the "defined by the base ABI for the CPU"
> annotation that I suggested, in your opinion?
I think we should document APIs (things declared in headers), not ABIs.
That primarily means APIs in glibc's headers, though documenting features
from standard headers provided by GCC seems reasonable.
I don't think we should document ABI-only interfaces with no API. And I
don't think we should document architecture-specific APIs from headers
provided by GCC such as arm_acle.h or x86 *intrin.h (there are huge
numbers of such APIs).
The PowerPC examples you gave are however APIs from a header provided by
glibc, so should be documented.
--
Joseph S. Myers
joseph@codesourcery.com