Re: [PATCH v2 3/5] manual: Add new header and standards annotations.

[Joseph Myers <joseph@codesourcery.com>]

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