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

[Joseph Myers <joseph at codesourcery dot com>]

On Tue, 6 Dec 2016, Zack Weinberg wrote:

> On 12/06/2016 05:55 AM, Rical Jasan wrote:
> >       This commit completes header and standard annotations for all
> >       @def*-commands and @vtable @items.
> 
> A high-level observation: I don't think MISC should appear in these
> annotations.  MISC is an artifact of <features.h> having collapsed
> _BSD_SOURCE and _SVID_SOURCE together, IIUC.  The manual should

__USE_MISC long predates that.  The old comment before that consolidation 
was "Define things common to BSD and System V Unix." (now "Define things 
from 4.3BSD or System V Unix.", reflecting the change from "BSD intersect 
SysV" to "BSD union SysV").

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.

> > @@ -1109,6 +1111,8 @@ where @code{radix} appears @code{FLT_MANT_DIG}
> times.
> >  @comment float.h
> >  @comment ISO
> >  @item DBL_MANT_DIG
> > +@comment float.h
> > +@comment ISO
> >  @itemx LDBL_MANT_DIG
> 
> Wasn't `long double` added in C99?  If so, all of the LDBL_* constants
> are properly marked C99, not ISO.  (GCC's <float.h> defines them
> unconditionally, but it supports `long double` as an extension in C90
> mode.)

The FLT_* and LDBL_* constants are C90.  The float and long double 
functions in math.h (and strtof and strtold) were introduced in C99.

> > +@comment stdio.h unistd.h fcntl.h
> > +@comment C90, POSIX.1, XOPEN || POSIX.1-2008
> >  @item SEEK_SET
> 
> This is going to be really confusing.  I suspect it means "C90 puts
> this macro in stdio.h, POSIX.1 additionally in unistd.h, and XOPEN in
> fcntl.h" but I do hope we find a less ambiguous way to express that.

I hope the syntax gets replaced by macros that take both header and 
standards as arguments, so they are always clearly paired.

> >  @vtable @code
> > +@comment sys/mman.h
> > +@comment BSD
> >  @item MAP_PRIVATE
> 
> mmap() itself was invented in SVR4, and the MAP_SHARED, MAP_PRIVATE,
> MAP_FIXED constants were there from the beginning.
> http://pubs.opengroup.org/onlinepubs/9699919799/functions/mmap.html
> says "First released in Issue 4, Version 2" under CHANGE HISTORY.
> I'm not sure exactly what annotations that corresponds to, but BSD is
> definitely not right.

POSIX.1-1993 (otherwise known as POSIX.1b; available as a 40 MB PDF from 
IEEE Xplore if you have a site license for that) adds sys/mman.h with 
contents MAP_FAILED MAP_FIXED MAP_PRIVATE MAP_SHARED MCL_CURRENT 
MCL_FUTURE MS_ASYNC MS_INVALIDATE MS_SYNC PROT_EXEC PROT_NONE PROT_READ 
PROT_WRITE mlock mlockall mmap mprotect msync munlock munlockall munmap 
shm_open shm_unlink.  XPG4.2 has a subset of that, which indicates 
documenting some interfaces as POSIX.1-1993 and some as POSIX.1-1993 || 
XPG4.2 (see bug 17663 for the headers failing to reflect that not all are 
in XPG4.2, with the conform/ data having a matching bug).

> > diff --git a/manual/platform.texi b/manual/platform.texi
> > index cb16664..ccbe73c 100644
> > --- a/manual/platform.texi
> > +++ b/manual/platform.texi
> > @@ -14,6 +14,8 @@
> >  Facilities specific to PowerPC that are not specific to a particular
> >  operating system are declared in @file{sys/platform/ppc.h}.
> >
> > +@comment sys/platform/ppc.h
> > +@comment ???
> >  @deftypefun {uint64_t} __ppc_get_timebase (void)
> 
> We need an annotation for "defined by the base ABI for the CPU."
> I know there are similar functions for ARM (__aeabi_*) and IA64, and
> probably others - that we only document the PowerPC ones is just a

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.)

> >  @comment Extra blank lines make it look better.
> >  @vtable @code
> > +@comment sys/wait.h
> > +@comment MISC
> >  @item WAIT_ANY
> ...
> > +@comment sys/wait.h
> > +@comment MISC
> >  @item WAIT_MYPGRP
> 
> These constants do not appear in the FreeBSD manpage for waitpid, so
> they are probably SVID.

SVID (fourth edition) is available from 
<http://www.sco.com/developers/devspecs/>.  I don't see them there.  They 
were __USE_BSD before commit 498afc54dfee41d33ba519f496e96480badace8e 
unified things in the headers.

> ("This function is obsolete" would be another good thing to have a
> machine-parseable annotation for.)

It was certainly noted when we did the unification that we should consider 
properly obsoleting some of the __USE_MISC functions (making them into 
compat symbols so not included for new architectures or available for new 
links, with or without a period of being declared as deprecated in the 
headers first).  Much the same no doubt applies to non-function interfaces 
as well.

-- 
Joseph S. Myers
joseph@codesourcery.com