From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 44902 invoked by alias); 24 Nov 2016 13:37:33 -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 44876 invoked by uid 89); 24 Nov 2016 13:37:32 -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=edition, 1990, Safety, establishing X-HELO: relay1.mentorg.com Date: Thu, 24 Nov 2016 13:37:00 -0000 From: Joseph Myers To: Rical Jasan CC: , Michael Kerrisk , Carlos O'Donell Subject: Re: [PATCH 3/3] manual: Add new header and standards annotations. In-Reply-To: <64fa1a5a-4af3-5e3f-b192-e79203c3e328@pacific.net> Message-ID: References: <20161123063807.14845-1-ricaljasan@pacific.net> <20161123063807.14845-4-ricaljasan@pacific.net> <64fa1a5a-4af3-5e3f-b192-e79203c3e328@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-11/txt/msg00898.txt.bz2 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? [1] 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 .". Where 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 one possibility: C90 (everything is a superset of this apart from gets obsoletion) C95 C99 C11 (note that these four are normally selected with -std, not with feature test macros, though glibc has _ISOC99_SOURCE and _ISOC11_SOURCE) TR 27431-2:2010 TS 18661-1:2014 TS 18661-4:2015 POSIX.1 (= 1990 edition) POSIX.2 POSIX.1-1993 POSIX.1-1995 POSIX.1-2001 XSI POSIX.1-2001 POSIX.1-2008 XSI POSIX.1-2008 DEFAULT GNU 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) UNIX98 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 joseph@codesourcery.com