This is the mail archive of the
mailing list for the glibc project.
Re: [PATCH 3/3] manual: Add new header and standards annotations.
On Thu, 24 Nov 2016, Rical Jasan wrote:
> > XOPEN2K is generically an unhelpful name. In the headers it actually
> > means POSIX.1-2001; the X/Open version is __USE_XOPEN2KXSI. Likewise
> > __USE_XOPEN2K8 means POSIX.1-2008 and the X/Open version is
> > __USE_XOPEN2K8XSI. So anywhere you say XOPEN2K because the headers use
> > __USE_XOPEN2K, say POSIX.1-2001 in the manual instead; likewise
> > POSIX.1-2008 for XOPEN2K8.
> I'm glad you mention this. Have you seen the related discussion on
> libc-help?  I'm interested in your thoughts on converting standards
> to feature test macros (or vice versa).
I'm not on libc-help. libc-help is for user questions. It's not an
appropriate place for development discussions and is not relevant to
establishing consensus on development directions.
> Also, if we want long-form standards in the manual, where would we put
> the feature test macros? It seems more appropriate to document the
> feature test macros in the Summary, and the current framework uses the
> standard @comment verbatim there. (There is also the issue that, e.g.,
> XOPEN2K or _USE_XOPEN2K aren't the actual feature test macros one would
> even use...)
My assumption is that creature.texi (which is very out of date regarding
what's enabled by default, values of _POSIX_C_SOURCE, etc.) would, where
it describes support for a standard and any associated feature test
macros, say something like: "Functions enabled with this feature test
macro / from this standard are listed as POSIX.1-2008 in <summary>.".
Where <summary> could be a link to the existing summary. Or it could say
"in the Standards information in the individual function description", if
we use macros to generate explicit Standards information in each function
description alongside the Safety information. Or both.
That is, creature.texi would explain the notation just like intro.texi has
an explanation of the safety annotations. The summary currently says "the
standard or other source from which each facility is derived", not "the
feature test macro".
There's an open question of whether we wish to continue to document BSD /
SVID / ... sources not corresponding to feature test macros, or just make
the annotations say MISC or DEFAULT and leave information about BSD etc.
origins to free-text descriptions.
As for names corresponding to standards / feature test macros, I suggest
C90 (everything is a superset of this apart from gets obsoletion)
(note that these four are normally selected with -std, not with feature
test macros, though glibc has _ISOC99_SOURCE and _ISOC11_SOURCE)
POSIX.1 (= 1990 edition)
XOPEN (= __USE_XOPEN; listed as XPG3 in conform/ tests; corresponds to
functions in C435 that are not UX-shaded)
XPG4 (= __USE_XOPEN_EXTENDED; corresponds to everything in C435)
LFS (= __USE_LARGEFILE64, i.e. *64 functions)
(which doesn't cover _LARGEFILE_SOURCE / _ATFILE_SOURCE / _REENTRANT, but
should be enough anyway to provide a sufficient indication of where
functions come from, at least if you can handle "standard 1 || standard
2", "standard 1 && ! standard 2", or similar).
Joseph S. Myers