Message ID | 20200918112755.21428-2-colomar.6.4.3@gmail.com |
---|---|
State | Not applicable |
Headers |
Return-Path: <libc-alpha-bounces@sourceware.org> X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 2A60D39540EC; Fri, 18 Sep 2020 11:28:28 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 2A60D39540EC DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1600428508; bh=NVNgTzoHX/BW0UXxRHn/k3P35d6msVWbommHDyYdhV8=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=P9SI37X2IZPb/lPGpfdwdY3WoorcRO3jv2MmNiEwjYz/uwKX2fNSaFXGcJWRHiiV5 og/dGI6eZSsTl/yqPEuYIG3tjYLX4MTkUIn4OMy5BCc2XfAdcKkqnpUTAWc0umG0+G 85QggBN/kXELflnyjLW/wSkdTOfeEkMKcq2xn/5o= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from mail-wm1-x341.google.com (mail-wm1-x341.google.com [IPv6:2a00:1450:4864:20::341]) by sourceware.org (Postfix) with ESMTPS id 0B77A3894C3B for <libc-alpha@sourceware.org>; Fri, 18 Sep 2020 11:28:25 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 0B77A3894C3B Received: by mail-wm1-x341.google.com with SMTP id k18so5185374wmj.5 for <libc-alpha@sourceware.org>; Fri, 18 Sep 2020 04:28:24 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=NVNgTzoHX/BW0UXxRHn/k3P35d6msVWbommHDyYdhV8=; b=GaeHXow+4caH23hiRYAFkP6xHp475BIJfUB+oavg/dl72esfmHRLkg2LLWTq6QRpxo dyqvc9Qw9Piag1a61kxQOAN/Pr5GEnkhFKMJMmLze04FBpO7e0W4ZioaVVGGTtpaeIhj xj9C6PgSVDrCikqO4O7RAoFBcxN4ZO3DVyv750xoC4htIsHZbPFlzqLYNGHDNpNYFlkl jZG+9OEwnqFeWTKm9fiXK+HoGpvBJmVcz7ijGBuGwzZdXExHrhGDu8l4DTNPQbFNUb7c 1Kv4B/C4IWCuWH9tNCpjsjiq8eyP7olwRtpdJUkd8qVMCmyK8R6GXQB9+5HBMg/FP3yr CCJQ== X-Gm-Message-State: AOAM532qgHBLDsUygCvF00/XIuSziO0SOD6v/2Te+Ff48vtDR+YQqLsk DeTcHaQbAxYbwVKQ7UdIODoHhD/v7QntqQ== X-Google-Smtp-Source: ABdhPJySgXr8aLpd1vmZXm5y0E1ytVOqwccMDestgF7vSwhH/TIc9x0HOxQMIqqK7gAdxr9nm5/gpg== X-Received: by 2002:a1c:7907:: with SMTP id l7mr14885886wme.89.1600428504185; Fri, 18 Sep 2020 04:28:24 -0700 (PDT) Received: from localhost.localdomain ([170.253.60.68]) by smtp.googlemail.com with ESMTPSA id s26sm4504962wmh.44.2020.09.18.04.28.23 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Sep 2020 04:28:23 -0700 (PDT) To: mtk.manpages@gmail.com Subject: [PATCH 1/2] system_data_types.7: Document size_t Date: Fri, 18 Sep 2020 13:27:55 +0200 Message-Id: <20200918112755.21428-2-colomar.6.4.3@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200918112755.21428-1-colomar.6.4.3@gmail.com> References: <20200918112755.21428-1-colomar.6.4.3@gmail.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-8.8 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_ENVFROM_END_DIGIT, FREEMAIL_FROM, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list <libc-alpha.sourceware.org> List-Unsubscribe: <https://sourceware.org/mailman/options/libc-alpha>, <mailto:libc-alpha-request@sourceware.org?subject=unsubscribe> List-Archive: <https://sourceware.org/pipermail/libc-alpha/> List-Post: <mailto:libc-alpha@sourceware.org> List-Help: <mailto:libc-alpha-request@sourceware.org?subject=help> List-Subscribe: <https://sourceware.org/mailman/listinfo/libc-alpha>, <mailto:libc-alpha-request@sourceware.org?subject=subscribe> From: Alejandro Colomar via Libc-alpha <libc-alpha@sourceware.org> Reply-To: Alejandro Colomar <colomar.6.4.3@gmail.com> Cc: Alejandro Colomar <colomar.6.4.3@gmail.com>, linux-man@vger.kernel.org, libc-alpha@sourceware.org Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" <libc-alpha-bounces@sourceware.org> |
Series |
Document size_t
|
|
Commit Message
Alejandro Colomar
Sept. 18, 2020, 11:27 a.m. UTC
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++--
1 file changed, 99 insertions(+), 4 deletions(-)
Comments
* Alejandro Colomar via Libc-alpha: > +Used for a count of bytes. It is the result of the > +.I sizeof > +operator. > +According to the C language standard, > +it shall be an unsigned integer type > +capable of storing values in the range [0, > +.BR SIZE_MAX ]. Thanks for working on this. Maybe add that this commonly maps to unsigned int or unsigned long, and that the length modifier for printf and scanf is z, commently used as %zu or %zx (%zd is for ssize_t). Florian
Hello Florian, On 2020-09-18 16:34, Florian Weimer wrote: > * Alejandro Colomar via Libc-alpha: > >> +Used for a count of bytes. It is the result of the >> +.I sizeof >> +operator. >> +According to the C language standard, >> +it shall be an unsigned integer type >> +capable of storing values in the range [0, >> +.BR SIZE_MAX ]. > > Thanks for working on this. :-) > Maybe add that this commonly maps to unsigned int or unsigned long, and I thought the same in the beginning, but then Michael convinced me to not do it. On 2020-09-13 22:20, Michael Kerrisk (man-pages) wrote: >>>> Is it a 32-bit or 64-bit or may vary? Is it signed or unsigned? >>> POSIX doesn't specify, I think.> >>> One other thing the page should show of course is definition of the >>> structure types. >> Yes. >> >> >> timer_t <time.h> or <sys/types.h> >> POSIX timer ID. >> >> typedef void *timer_t; > Here I would *not* show these kinds of typedefs. The point is > that these types should be treated as being somewhat unknown > (e.g., for casts in printf()). Here, I think instead maybe we > just have a statement that POSIX makes no specific requirements > for the representation of this type. I think I prefer to leave it opaque, showing only the requirements that POSIX and C make. There's really not much gain (basically uint and ulong cover most of the possibilities; and still it's not a guarantee). And readers might write non-portable code because of reading that. On 2020-09-18 16:34, Florian Weimer wrote: > that the length modifier for printf and scanf is z, commently used as > %zu or %zx (%zd is for ssize_t). Good idea. Would you prefer that, or just refer to printf(3) in See also?. > > Florian > Thanks, Alex
* Alejandro Colomar: > I think I prefer to leave it opaque, showing only the requirements > that POSIX and C make. > > There's really not much gain (basically uint and ulong cover most of the > possibilities; and still it's not a guarantee). > And readers might write non-portable code because of reading that. My idea was it that it stresses that you have to use %zu in order to be portable. %lu works almost everywhere, so that's any easy mistake to make because it still leads to -Werror build failures on s390 (31-bit). Likewise for %ld for ptrdiff_t, it should be %td. > On 2020-09-18 16:34, Florian Weimer wrote: >> that the length modifier for printf and scanf is z, commently used as >> %zu or %zx (%zd is for ssize_t). > > Good idea. > > Would you prefer that, or just refer to printf(3) in See also?. I think it makes sense to spell out %zu and %zx explicitly. Thanks, Florian
On 9/18/20 7:34 AM, Florian Weimer via Libc-alpha wrote: > the length modifier for printf and scanf is z, commently used as > %zu or %zx (%zd is for ssize_t). While %zd works for ssize_t in glibc, POSIX doesn't guarantee that it'll work, as ssize_t might not have the same width as size_t. (If memory serves this goes back to the bad old days when size_t was 64 bits and ssize_t 32 bits on some platforms.) So if we document %zd we should say it's a GNU extension to POSIX, or something like that.
* Paul Eggert: > On 9/18/20 7:34 AM, Florian Weimer via Libc-alpha wrote: >> the length modifier for printf and scanf is z, commently used as >> %zu or %zx (%zd is for ssize_t). > > While %zd works for ssize_t in glibc, POSIX doesn't guarantee that > it'll work, as ssize_t might not have the same width as size_t. (If > memory serves this goes back to the bad old days when size_t was 64 > bits and ssize_t 32 bits on some platforms.) So if we document %zd we > should say it's a GNU extension to POSIX, or something like that. I didn't know that. It's a good suggestion, thanks. Florian
On 9/18/20 1:27 PM, Alejandro Colomar wrote: > Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com> Merged. Thanks, Michael > --- > man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++-- > 1 file changed, 99 insertions(+), 4 deletions(-) > > diff --git a/man7/system_data_types.7 b/man7/system_data_types.7 > index 84fea85b9..041e7e243 100644 > --- a/man7/system_data_types.7 > +++ b/man7/system_data_types.7 > @@ -92,6 +92,101 @@ See also: > .\".I siginfo_t > .\"type in this page. > .TP > +.I size_t > +.IP > +Include: > +.I <stddef.h> > +or > +.IR <sys/types.h> ; > +or > +.I <aio.h> > +or > +.I <glob.h> > +or > +.I <grp.h> > +or > +.I <iconv.h> > +or > +.I <monetary.h> > +or > +.I <mqueue.h> > +or > +.I <ndbm.h> > +or > +.I <pwd.h> > +or > +.I <regex.h> > +or > +.I <search.h> > +or > +.I <signal.h> > +or > +.I <stdio.h> > +or > +.I <stdlib.h> > +or > +.I <string.h> > +or > +.I <strings.h> > +or > +.I <sys/mman.h> > +or > +.I <sys/msg.h> > +or > +.I <sys/sem.h> > +or > +.I <sys/shm.h> > +or > +.I <sys/socket.h> > +or > +.I <sys/uio.h> > +or > +.I <time.h> > +or > +.I <unistd.h> > +or > +.I <wchar.h> > +or > +.IR <wordexp.h> . > +.IP > +Used for a count of bytes. It is the result of the > +.I sizeof > +operator. > +According to the C language standard, > +it shall be an unsigned integer type > +capable of storing values in the range [0, > +.BR SIZE_MAX ]. > +.IP > +Conforming to: C99 and later; POSIX.1-2001 and later. > +.IP > +Notes: > +.IR <aio.h> , > +.IR <glob.h> , > +.IR <grp.h> , > +.IR <iconv.h> , > +.IR <mqueue.h> , > +.IR <pwd.h> , > +.IR <signal.h> > +and > +.IR <sys/socket.h> > +define > +.I size_t > +since POSIX.1-2008. > +.IP > +See also: > +.BR fread (3), > +.BR fwrite (3), > +.BR memcmp (3), > +.BR memcpy (3), > +.BR memset (3), > +.BR offsetof (3) > +.IP > +See also the > +.I ssize_t > +and > +.I ptrdiff_t > +types in this page. > +.TP > .I ssize_t > .IP > Include: > @@ -127,10 +222,10 @@ See also: > .BR recv (2), > .BR send (2), > .BR write (2) > -.\".IP FIXME: When size_t is added, uncomment > -.\"See also the > -.\".I size_t > -.\"type in this page. > +.IP > +See also the > +.I size_t > +type in this page. > .TP > .I suseconds_t > .IP >
On Fri, Sep 18, 2020 at 01:27:55PM +0200, Alejandro Colomar wrote: > Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com> > --- > man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++-- > 1 file changed, 99 insertions(+), 4 deletions(-) > > diff --git a/man7/system_data_types.7 b/man7/system_data_types.7 > index 84fea85b9..041e7e243 100644 > --- a/man7/system_data_types.7 > +++ b/man7/system_data_types.7 The distinction might not be worth highlighting here, but types like size_t are a bit special in that they come from the C standards and assumptions about them are really built into the compiler. The system can define its own size_t, but it had better be equivalent to the compiler's definition otherwise bad things will happen... > @@ -92,6 +92,101 @@ See also: > .\".I siginfo_t > .\"type in this page. > .TP > +.I size_t > +.IP > +Include: > +.I <stddef.h> > +or Where does this arbitrary-looking list of headers come from? From the C standards at least, <stddef.h> seems to be the canonical header for this type. > +.IR <sys/types.h> ; > +or > +.I <aio.h> > +or > +.I <glob.h> > +or > +.I <grp.h> > +or > +.I <iconv.h> > +or > +.I <monetary.h> > +or > +.I <mqueue.h> [...] Cheers ---Dave
Hi Dave, On 2020-09-28 15:41, Dave Martin wrote: > On Fri, Sep 18, 2020 at 01:27:55PM +0200, Alejandro Colomar wrote: >> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com> >> --- >> man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++-- >> 1 file changed, 99 insertions(+), 4 deletions(-) >> >> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7 >> index 84fea85b9..041e7e243 100644 >> --- a/man7/system_data_types.7 >> +++ b/man7/system_data_types.7 > > The distinction might not be worth highlighting here, but types like > size_t are a bit special in that they come from the C standards and > assumptions about them are really built into the compiler. > > The system can define its own size_t, but it had better be equivalent > to the compiler's definition otherwise bad things will > happen... > > >> @@ -92,6 +92,101 @@ See also: >> .\".I siginfo_t >> .\"type in this page. >> .TP >> +.I size_t >> +.IP >> +Include: >> +.I <stddef.h> >> +or > > Where does this arbitrary-looking list of headers come from? There are two parts: left to the ';', and right to the ';'. Left: The canonical C standard header, and the canonical POSIX header, in alphabetical order. Right: All other headers that shall define the header, according to either the C or the POSIX standards, in alphabetical order. Cheers, Alex > > From the C standards at least, <stddef.h> seems to be the canonical > header for this type. > > >> +.IR <sys/types.h> ; >> +or >> +.I <aio.h> >> +or >> +.I <glob.h> >> +or >> +.I <grp.h> >> +or >> +.I <iconv.h> >> +or >> +.I <monetary.h> >> +or >> +.I <mqueue.h> > > [...] > > Cheers > ---Dave >
Hi, Alex! At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote: > > Where does this arbitrary-looking list of headers come from? > > There are two parts: left to the ';', and right to the ';'. > > Left: The canonical C standard header, and the canonical POSIX header, > in alphabetical order. > > Right: All other headers that shall define the header, according to > either the C or the POSIX standards, in alphabetical order. That's not a bad scheme but it is not inferable from the current man page text; I almost commented on the inconsistency in one of my earlier messages but deemed it out of scope. Please document it, perhaps in an introductory paragraph at the top of the Description section. Or, you could spend a word to do the same work: gid_t Include: <sys/types.h>. Alternatively, <grp.h>, <pwd.h>, <signal.h>, <stropts.h>, <sys/ipc.h>, <sys/stat.h>, or <unistd.h>. Regards, Branden
On Mon, Sep 28, 2020 at 11:55:08PM +1000, G. Branden Robinson wrote: > Hi, Alex! > > At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote: > > > Where does this arbitrary-looking list of headers come from? > > > > There are two parts: left to the ';', and right to the ';'. > > > > Left: The canonical C standard header, and the canonical POSIX header, > > in alphabetical order. > > > > Right: All other headers that shall define the header, according to > > either the C or the POSIX standards, in alphabetical order. To clarify, does POSIX _guarantee_ that all of those headers define this type? (I admit I'm too lazy to search through the POSIX standard for an answer to this). If not, this list would serve only to legitimise bad habits and it may be better to leave it out. > That's not a bad scheme but it is not inferable from the current man > page text; I almost commented on the inconsistency in one of my earlier > messages but deemed it out of scope. Please document it, perhaps in an > introductory paragraph at the top of the Description section. Ack, I think it would be better to state this explicity rather than having some terse syntax that people need to understand. IIUC, a program intended to be fully portable between C implementations must include <stddef.h>, not rely on one of the others. (In practice it seems reasonable to include any header that is specified to declare types or function prototypes that themselves require a definition of size_t, but this is awkward to describe, and not explicit in the standard.) [...] Cheers ---Dave
Hi Branden, On 2020-09-28 15:55, G. Branden Robinson wrote: > Hi, Alex! > > At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote: >>> Where does this arbitrary-looking list of headers come from? >> >> There are two parts: left to the ';', and right to the ';'. >> >> Left: The canonical C standard header, and the canonical POSIX header, >> in alphabetical order. >> >> Right: All other headers that shall define the header, according to >> either the C or the POSIX standards, in alphabetical order. > > That's not a bad scheme but it is not inferable from the current man > page text; I almost commented on the inconsistency in one of my earlier > messages but deemed it out of scope. Please document it, perhaps in an > introductory paragraph at the top of the Description section. > > Or, you could spend a word to do the same work: > > gid_t Include: <sys/types.h>. Alternatively, <grp.h>, <pwd.h>, > <signal.h>, <stropts.h>, <sys/ipc.h>, <sys/stat.h>, or <unistd.h>. > > Regards, > Branden > Thanks! We talked about it. I wasn't convinced by my scheme, but we couldn't come up with a better solution, so we kept that. For the readers, it wasn't clear, but for the developers of the page, I wrote a comment at the beginning of the page, which I hope was clear enough: .\" Layout: .\" A list of type names (the struct/union keyword will be omitted). .\" Each entry will have the following parts: .\" * Include .\" The headers will be in the following order: .\" 1) The main header that shall define the type .\" according to the C Standard, .\" and .\" the main header that shall define the type .\" according to POSIX, .\" in alphabetical order. .\" ; .\" 2) All other headers that shall define the type .\" as described in the previous header(s) .\" according to the C Standard or POSIX, .\" in alphabetical order. .\" *) All headers that define the type .\" *if* the type is not defined by C nor POSIX, .\" in alphabetical order. .\" .\" * Definition (no "Definition" header) .\" Only struct/union types will have definition; .\" typedefs will remain opaque. .\" .\" * Description (no "Description" header) .\" A few lines describing the type. .\" .\" * Conforming to .\" Format: CXY and later; POSIX.1-XXXX and later. .\" Forget about pre-C99 C standards (i.e., C89/C90) .\" .\" * Notes (optional) .\" .\" * See also But I like very much your "Alternatively, " wording. I'll use it! Thanks, Alex
Hi Dave! On 2020-09-28 16:15, Dave Martin wrote: > On Mon, Sep 28, 2020 at 11:55:08PM +1000, G. Branden Robinson wrote: >> Hi, Alex! >> >> At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote: >>>> Where does this arbitrary-looking list of headers come from? >>> >>> There are two parts: left to the ';', and right to the ';'. >>> >>> Left: The canonical C standard header, and the canonical POSIX header, >>> in alphabetical order. >>> >>> Right: All other headers that shall define the header, according to >>> either the C or the POSIX standards, in alphabetical order. > > To clarify, does POSIX _guarantee_ that all of those headers define this > type? (I admit I'm too lazy to search through the POSIX standard for an > answer to this). Yes, POSIX does guarantee that all those headers define the type. > > If not, this list would serve only to legitimise bad habits and it may > be better to leave it out. > > >> That's not a bad scheme but it is not inferable from the current man >> page text; I almost commented on the inconsistency in one of my earlier >> messages but deemed it out of scope. Please document it, perhaps in an >> introductory paragraph at the top of the Description section. > > Ack, I think it would be better to state this explicity rather than > having some terse syntax that people need to understand. Would you like to propose something? > > > IIUC, a program intended to be fully portable between C implementations > must include <stddef.h>, not rely on one of the others. Yes, in principle, programmers should use the first header in the list. However, we listed all of them for completeness. We only listed headers that guarantee to define the type, thogh, either by C or POSIX: .\" Layout: .\" A list of type names (the struct/union keyword will be omitted). .\" Each entry will have the following parts: .\" * Include .\" The headers will be in the following order: .\" 1) The main header that shall define the type .\" according to the C Standard, .\" and .\" the main header that shall define the type .\" according to POSIX, .\" in alphabetical order. .\" ; .\" 2) All other headers that shall define the type .\" as described in the previous header(s) .\" according to the C Standard or POSIX, .\" in alphabetical order. .\" *) All headers that define the type .\" *if* the type is not defined by C nor POSIX, .\" in alphabetical order. .\" .\" * Definition (no "Definition" header) .\" Only struct/union types will have definition; .\" typedefs will remain opaque. .\" .\" * Description (no "Description" header) .\" A few lines describing the type. .\" .\" * Conforming to .\" Format: CXY and later; POSIX.1-XXXX and later. .\" Forget about pre-C99 C standards (i.e., C89/C90) .\" .\" * Notes (optional) .\" .\" * See also > > (In practice it seems reasonable to include any header that is specified > to declare types or function prototypes that themselves require a > definition of size_t, but this is awkward to describe, and not explicit > in the standard.) > > [...] > > Cheers > ---Dave > Cheers, Alex
Hi Dave, On Mon, 28 Sep 2020 at 16:15, Dave Martin <Dave.Martin@arm.com> wrote: > > On Mon, Sep 28, 2020 at 11:55:08PM +1000, G. Branden Robinson wrote: > > Hi, Alex! > > > > At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote: > > > > Where does this arbitrary-looking list of headers come from? > > > > > > There are two parts: left to the ';', and right to the ';'. > > > > > > Left: The canonical C standard header, and the canonical POSIX header, > > > in alphabetical order. > > > > > > Right: All other headers that shall define the header, according to > > > either the C or the POSIX standards, in alphabetical order. > > To clarify, does POSIX _guarantee_ that all of those headers define this > type? (I admit I'm too lazy to search through the POSIX standard for an > answer to this). > > If not, this list would serve only to legitimise bad habits and it may > be better to leave it out. As I think Alex has clarified, the info about headers is being taken from POSIX. > > That's not a bad scheme but it is not inferable from the current man > > page text; I almost commented on the inconsistency in one of my earlier > > messages but deemed it out of scope. Please document it, perhaps in an > > introductory paragraph at the top of the Description section. > > Ack, I think it would be better to state this explicity rather than > having some terse syntax that people need to understand. Yes, I think some more explanatory text is probably needed. This page is still very much a work in progress. > IIUC, a program intended to be fully portable between C implementations > must include <stddef.h>, not rely on one of the others. Just to note a point here: my main concern is portability across POSIX systems. Thanks, Michael
On Fri, 18 Sep 2020, Paul Eggert wrote: > On 9/18/20 7:34 AM, Florian Weimer via Libc-alpha wrote: > > the length modifier for printf and scanf is z, commently used as > > %zu or %zx (%zd is for ssize_t). > > While %zd works for ssize_t in glibc, POSIX doesn't guarantee that it'll work, > as ssize_t might not have the same width as size_t. (If memory serves this > goes back to the bad old days when size_t was 64 bits and ssize_t 32 bits on > some platforms.) So if we document %zd we should say it's a GNU extension to > POSIX, or something like that. %zd is for the signed type corresponding to size_t; that's in ISO C. The GNU extension would be a guarantee that ssize_t is the signed type corresponding to size_t (if we do guarantee that).
On Mon, 28 Sep 2020, Alejandro Colomar via Libc-alpha wrote: > > To clarify, does POSIX _guarantee_ that all of those headers define this > > type? (I admit I'm too lazy to search through the POSIX standard for an > > answer to this). > > Yes, POSIX does guarantee that all those headers define the type. For a lot of cases where a header contains a function using a type in its prototype, current POSIX requires that type to be defined in the header, but older POSIX permitted it (by virtue of the *_t reservation) but did not require it unless XSI extensions were enabled. The preferred glibc practice in such cases where older POSIX permitted the definition and included functions using the type is not to make the definition of the type in the header conditional on the POSIX version / XSI extensions, but to enable the definition for all standards that include the relevant function. (This simplifies the headers, and also simplifies the conform/ tests because they then don't need to handle testing for a declaration of a function without being able to write its type in the most straightforward way.) The headers still need to include feature test macro conditionals and special handling where a header is required by some standard to declare a function without defining the corresponding type name. (For example, ISO C does not permit <stdio.h> to define va_list, so the header has to use an implementation-namespace name for that type when declaring vprintf.)
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7 index 84fea85b9..041e7e243 100644 --- a/man7/system_data_types.7 +++ b/man7/system_data_types.7 @@ -92,6 +92,101 @@ See also: .\".I siginfo_t .\"type in this page. .TP +.I size_t +.IP +Include: +.I <stddef.h> +or +.IR <sys/types.h> ; +or +.I <aio.h> +or +.I <glob.h> +or +.I <grp.h> +or +.I <iconv.h> +or +.I <monetary.h> +or +.I <mqueue.h> +or +.I <ndbm.h> +or +.I <pwd.h> +or +.I <regex.h> +or +.I <search.h> +or +.I <signal.h> +or +.I <stdio.h> +or +.I <stdlib.h> +or +.I <string.h> +or +.I <strings.h> +or +.I <sys/mman.h> +or +.I <sys/msg.h> +or +.I <sys/sem.h> +or +.I <sys/shm.h> +or +.I <sys/socket.h> +or +.I <sys/uio.h> +or +.I <time.h> +or +.I <unistd.h> +or +.I <wchar.h> +or +.IR <wordexp.h> . +.IP +Used for a count of bytes. It is the result of the +.I sizeof +operator. +According to the C language standard, +it shall be an unsigned integer type +capable of storing values in the range [0, +.BR SIZE_MAX ]. +.IP +Conforming to: C99 and later; POSIX.1-2001 and later. +.IP +Notes: +.IR <aio.h> , +.IR <glob.h> , +.IR <grp.h> , +.IR <iconv.h> , +.IR <mqueue.h> , +.IR <pwd.h> , +.IR <signal.h> +and +.IR <sys/socket.h> +define +.I size_t +since POSIX.1-2008. +.IP +See also: +.BR fread (3), +.BR fwrite (3), +.BR memcmp (3), +.BR memcpy (3), +.BR memset (3), +.BR offsetof (3) +.IP +See also the +.I ssize_t +and +.I ptrdiff_t +types in this page. +.TP .I ssize_t .IP Include: @@ -127,10 +222,10 @@ See also: .BR recv (2), .BR send (2), .BR write (2) -.\".IP FIXME: When size_t is added, uncomment -.\"See also the -.\".I size_t -.\"type in this page. +.IP +See also the +.I size_t +type in this page. .TP .I suseconds_t .IP