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

[Zack Weinberg <zackw at panix dot com>]

On 12/06/2016 11:23 AM, Joseph Myers wrote:
> 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.

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?

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

Oh, OK, never mind then.

>>> +@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.

Concur.

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

So, how useful do you think the older POSIX/XPG/whatever conformance
modes actually are nowadays?  Could we conceivably get away with pruning
the list down to

 * C90 and nothing more
 * C99 and nothing more
 * C11 and nothing more

 * Cxx + POSIX.1-2001
 * Cxx + POSIX.1-2001 + XSI
 * Cxx + POSIX.1-2008
 * Cxx + POSIX.1-2008 + XSI

 * _DEFAULT_SOURCE
 * _GNU_SOURCE

plus the semi-orthogonal LFS and ATFILE toggles?

(I think POSIX.1-2001 is a good cutoff point because it's the first
unified POSIX/XPG standard and basically ubiquitous in my experience,
because there are still widely-used systems that haven't adopted all the
new stuff in -2008 (e.g. OSX.latest still doesn't have the _l
functions), and because -2008 removed a number of functions that are
still heavily used, e.g. gettimeofday, setcontext.)

(This is *largely* an independent issue from what should be in the
manual - I personally value detailed provenance information in the
manual, but verifying the history back into the early nineties gets
difficult, can involve spending money, and it's unclear to me how useful
it is to people who aren't history nerds.)

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

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?

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

Hmm.  Spelunking around in http://minnie.tuhs.org/cgi-bin/utree.pl, the
oldest thing I can find that is recognizably <sys/wait.h> is from
4.3BSD-Reno,
http://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Reno/src/sys/sys/wait.h,
and it does have the WAIT_ANY, WAIT_MYPGRP constants.  (4.2BSD has
http://minnie.tuhs.org/cgi-bin/utree.pl?file=4.2BSD/usr/src/sys/h/wait.h
which is related but clearly not the same file, and does not have those
macros.)  That site doesn't have the System V lineage, but I can't
really see those macros _not_ getting standardized if they were from
that lineage, so that's good enough for me to agree they were from BSD.

>> ("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.

I'm for such an obsoletions pass, but it's probably 2.26 material at
this point, and let's not tie it up with the manual work.

zw