From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 59137 invoked by alias); 6 Dec 2016 16:24:00 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Received: (qmail 58797 invoked by uid 89); 6 Dec 2016 16:23:59 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.9 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,SPF_PASS,URIBL_RED autolearn=ham version=3.3.2 spammy=consolidation, CHANGE, artifact, PDF X-HELO: relay1.mentorg.com Date: Tue, 06 Dec 2016 16:24:00 -0000 From: Joseph Myers To: Zack Weinberg CC: Subject: Re: [PATCH v2 3/5] manual: Add new header and standards annotations. In-Reply-To: Message-ID: References: <20161206105525.21117-1-ricaljasan@pacific.net> <20161206105525.21117-4-ricaljasan@pacific.net> User-Agent: Alpine 2.20 (DEB 67 2015-01-07) MIME-Version: 1.0 Content-Type: text/plain; charset="US-ASCII" X-ClientProxiedBy: svr-ies-mbx-01.mgc.mentorg.com (139.181.222.1) To svr-ies-mbx-01.mgc.mentorg.com (139.181.222.1) X-SW-Source: 2016-12/txt/msg00183.txt.bz2 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 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 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 . 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