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

[Zack Weinberg <zackw@panix.com>]

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
continue to document which lineage each item came from, as that is
still relevant to people trying to write portable code.

I also have corrections to a number of the annotations:

> diff --git a/manual/creature.texi b/manual/creature.texi
> index 257f871..babec55 100644
> --- a/manual/creature.texi
> +++ b/manual/creature.texi
> @@ -218,6 +218,8 @@ cause them to be disabled.
>  @comment (none)
>  @comment GNU
>  @defvr Macro _REENTRANT
> +@comment (none)
> +@comment ???
>  @defvrx Macro _THREAD_SAFE
>  If you define one of these macros, reentrant versions of several
functions get
>  declared.  Some of the functions are specified in POSIX.1c but many
others

_REENTRANT and _THREAD_SAFE were _not_ GNU inventions; they were both
invented by proprietary Unix vendors in the 1990-1995 timeframe.  I
*think* _REENTRANT was originally a Sun thing.  I don't know about
_THREAD_SAFE.

More to the point, though, they're so obsolete that there may not be
any point keeping them around either in the manual or the headers
anymore.  I'll send a separate message about that.

>  @vtable @code
> +@comment dirent.h
> +@comment MISC
>  @item DT_UNKNOWN
>  The type is unknown.  Only some filesystems have full support to
>  return the type of the file, others might always return this value.

The DT_* constants are all from BSD.

>  The item is a directory which cannot be read.
> +@comment ftw.h
> +@comment MISC || XPG4
...
> +@comment ftw.h
> +@comment XPG4 && GNU

Based on Issue 7's history annotations, I believe the correct
provenance annotations for the FTW_* constants are:

SVID: FTW_F, FTW_D, FTW_DNR, FTW_NS
XPG4.2: FTW_DP, FTW_SL, FTW_SLN
XPG4.2: FTW_PHYS, FTW_MOUNT, FTW_CHDIR, FTW_DEPTH
GNU: FTW_ACTIONRETVAL

(SVID1 had ftw(); XPG4.2 added nftw(); the second set of constants
only make sense for use with nftw().)

> @@ -478,6 +478,8 @@ of the same type.
>  @comment stdarg.h
>  @comment ISO
>  @deftypefn {Macro} void va_copy (va_list @var{dest}, va_list @var{src})
> +@comment stdarg.h
> +@comment GNU
>  @deftypefnx {Macro} void __va_copy (va_list @var{dest}, va_list
@var{src})
>  @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
>  @c This is no longer provided by glibc, but rather by the compiler.

Why are we documenting __va_copy at all?

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

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

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

> +@comment sys/mman.h
> +@comment BSD
>  @item MS_SYNC

Same as above.  msync() seems to have gone back and forth between XSI
and BASE depending on exactly which level of the standard you're
looking at, argh.

> +@comment sys/mman.h
> +@comment MISC
>  @item MADV_NORMAL
>  The region should receive no further special treatment.

Now these, these should be marked BSD.  (Functions that POSIX renamed
from 'foo' to 'posix_foo' upon standardization are *usually* from the
BSD lineage.
https://www.freebsd.org/cgi/man.cgi?query=madvise&apropos=0&sektion=0&manpath=FreeBSD+10.3-RELEASE+and+Ports&arch=default&format=html
confirms this case: "The madvise() system call first appeared in 4.4BSD.")

>  @comment TODO: @item M_CHECK_ACTION
>  @vtable @code
> +@comment malloc.h
> +@comment ???
>  @item M_MMAP_MAX

All of these M_* constants are specific to glibc's malloc
implementation and should therefore be marked GNU.

> --- a/manual/nss.texi
> +++ b/manual/nss.texi
> @@ -451,15 +451,23 @@ function returns a pointer to the result the
reentrant function return
>  an @code{enum nss_status} value:
>
>  @vtable @code
> +@comment nss.h
> +@comment ???
>  @item NSS_STATUS_TRYAGAIN
>  numeric value @code{-2}

The NSS mechanism was invented by Sun, but <nss.h> is not a documented
interface in Solaris 11, so I think these are properly GNU.

> 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
matter of the PowerPC maintainers having been more diligent than
average in the past.

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

>  @comment sys/vtimes.h
> +@comment ???
>  @deftypefun int vtimes (struct vtimes *@var{current}, struct vtimes
>                          *@var{child})

Oh wow, it's not often I trip over an interface that's so old I've
never heard of it.  This one isn't in the current FreeBSD manpages,
the 4.3BSD manpages, *or* the Solaris manpages, but it *is* in the
online AIX manpages, which means that SVID is probably the best
approximation.

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

>  @vtable @code
> +@comment fmtmsg.h
> +@comment ???

This entire header is from SVR4 and is XSI in Issue 7.
http://pubs.opengroup.org/onlinepubs/9699919799/functions/fmtmsg.html

>  @vtable @code
> +@comment mntent.h
> +@comment ???

BSD for all of these.

zw