Message ID | 20201001101559.77163-6-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 8DDB83987C00; Thu, 1 Oct 2020 10:16:42 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 8DDB83987C00 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1601547402; bh=DUxvt3f3o57blBzUF8i4CGd9blKLoO6bLEUyvf4IIOM=; 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=VXGGX+cntXVVeODXL2byKZknZbZEXedKmaByU9fnaDfDV6BdnGaqgDaWm8Gh2xj5v GX/hSQrr2Yk/nfhJzb2WNnGbkZbB6JtP9PJ0Y58P4dGW0Al3QNBaS2MqH4smcwe19+ JDJR1qiybazh+T5K2lJS06to86VkGZg/x02RdKe0= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from mail-wr1-x442.google.com (mail-wr1-x442.google.com [IPv6:2a00:1450:4864:20::442]) by sourceware.org (Postfix) with ESMTPS id 32F8C398541B for <libc-alpha@sourceware.org>; Thu, 1 Oct 2020 10:16:35 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 32F8C398541B Received: by mail-wr1-x442.google.com with SMTP id x14so4993742wrl.12 for <libc-alpha@sourceware.org>; Thu, 01 Oct 2020 03:16:35 -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=DUxvt3f3o57blBzUF8i4CGd9blKLoO6bLEUyvf4IIOM=; b=IX89/uexgZi73EcNGQ+DlzCxE8F4Ow9GVX/QGksfVaVa4hMxfMXYX3sXruhSPIqK84 pCYSbH+2S5MgIY9qQz86yes7Vb3zAl48wjx3wGwUkTFPmSCAnOYkXsSSeM3PwoypCxDl zqprb74j9zQRKni4HSFpeMX2lJpXDmguL/AA5NTX0c4VY+mrK0BfwGXm96GEsOyWb3aX BZAcB5CCmwhpGU16Ej2crJnIJHkz4FOXzSfWhj4oUEOeknyM+M+PfiLEeN7K9MsnaUGu CS3mhtCgycSCgfRp945wFPOf5264g0/5ql0szYSNdJmiMDcWJsSNNW0s8kq1JLPFz249 5vQQ== X-Gm-Message-State: AOAM5325Q10/+ficB1iAWklE+61EfBodeO9g5aiWdJSNiochGgCgXz8S oPtXeX7OJKHxhFcVE9cf4AY= X-Google-Smtp-Source: ABdhPJybt41Ch8Tt5m8t9NrJ7UPEshrksFE9YVUuVYnanf6hFFbDbvQbYNmXml5XVwMwVId5APJ1Ig== X-Received: by 2002:adf:f10a:: with SMTP id r10mr7755742wro.86.1601547394299; Thu, 01 Oct 2020 03:16:34 -0700 (PDT) Received: from localhost.localdomain ([170.253.60.68]) by smtp.googlemail.com with ESMTPSA id i15sm8671922wrb.91.2020.10.01.03.16.33 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 01 Oct 2020 03:16:33 -0700 (PDT) To: mtk.manpages@gmail.com Subject: [PATCH 05/16] system_data_types.7: Add int_fastN_t family of types Date: Thu, 1 Oct 2020 12:15:49 +0200 Message-Id: <20201001101559.77163-6-colomar.6.4.3@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20201001101559.77163-1-colomar.6.4.3@gmail.com> References: <20201001101559.77163-1-colomar.6.4.3@gmail.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-11.2 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: colomar.6.4.3@gmail.com, linux-man@vger.kernel.org, libc-alpha@sourceware.org, gcc@gcc.gnu.org Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" <libc-alpha-bounces@sourceware.org> |
Series |
Fixes; Document remaining stdint.h types
|
|
Commit Message
Alejandro Colomar
Oct. 1, 2020, 10:15 a.m. UTC
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man7/system_data_types.7 | 76 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 76 insertions(+)
Comments
On Thu, 1 Oct 2020 at 11:25, Alejandro Colomar via Gcc <gcc@gcc.gnu.org> wrote: > > Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com> > --- > man7/system_data_types.7 | 76 ++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 76 insertions(+) > > diff --git a/man7/system_data_types.7 b/man7/system_data_types.7 > index a301c2309..07de6417f 100644 > --- a/man7/system_data_types.7 > +++ b/man7/system_data_types.7 > @@ -329,6 +329,82 @@ C99 and later; POSIX.1-2001 and later. > See also: > .BR imaxdiv (3) > .RE > +.\"------------------------------------- int_fastN_t ------------------/ > +.TP > +.IR int_fast N _t > +.RS > +Include: > +.IR <stdint.h> . > +Alternatively, > +.IR <inttypes.h> . > +.PP > +.IR int_fast8_t , > +.IR int_fast16_t , > +.IR int_fast32_t , > +.I int_fast64_t > +.PP > +The fastest signed integer type > +of a width of at least N bits, > +N being the value specified in its type name. > +According to the C language standard, they shall be > +capable of storing values in the range > +.RB [ INT_FAST N _MIN , > +.BR INT_FAST N _MAX ], > +substituting N by the appropriate number. > +.PP > +The length modifiers for the > +.IR int_fast N _t > +types for the > +.BR printf (3) > +family of functions > +are expanded by macros of the forms > +.BR PRIdFAST N > +and > +.BR PRIiFAST N > +(defined in > +.IR <inttypes.h> ); > +resulting for example in > +.B %"PRIdFAST64" > +or > +.B %"PRIiFAST64" > +for printing > +.I int_fast64_t > +values. > +The length modifiers for the > +.IR int_fast N _t > +types for the > +.BR scanf (3) > +family of functions > +are expanded by macros of the forms > +.BR SCNdFAST N > +and > +.BR SCNiFAST N, > +(defined in > +.IR <inttypes.h> ); > +resulting for example in > +.B %"SCNdFAST8" > +or > +.B %"SCNiFAST8" > +for scanning > +.I int_fast8_t > +values. > +.PP > +Conforming to: > +C99 and later; POSIX.1-2001 and later. > +.PP > +Notes: > +Some of these types may be optimized for size > +instead of raw performance. I'm not sure what this tells me as a programmer. What does "raw performance" means exactly? The text above says it's "the fastest", but then it says "may be optimized for size". I don't know how to interpret this. Is it fast or is it small, or something else? Is it optimized for small size? Natural word size? Cacheline size? I prefer the phrasing of the caveats in the C and POSIX standards which just say it might not be fastest for all purposes. How about "Where there is no single type that is fastest for all purposes, the implementation may choose any type with the required signedness and at least the minimum width." I don't see anything in this man page saying that the <stdint.h> types are all typedefs, rather than new types that are distinct from the standard integer types. That seems like useful information.
On 2020-10-01 13:07, Jonathan Wakely wrote: [...] >> +Notes: >> +Some of these types may be optimized for size >> +instead of raw performance. > > I'm not sure what this tells me as a programmer. What does "raw > performance" means exactly? The text above says it's "the fastest", > but then it says "may be optimized for size". I don't know how to > interpret this. Is it fast or is it small, or something else? Is it > optimized for small size? Natural word size? Cacheline size? > > I prefer the phrasing of the caveats in the C and POSIX standards > which just say it might not be fastest for all purposes. > > How about "Where there is no single type that is fastest for all > purposes, the implementation may choose any type with the required > signedness and at least the minimum width." > > I don't see anything in this man page saying that the <stdint.h> types > are all typedefs, rather than new types that are distinct from the > standard integer types. That seems like useful information. > Hi Jonathan, I wasn't sure about how to word it. In theory, they should be the fastest types; just that. But then, for some reason, GCC decided that int_fast8_t should be int8_t instead of int64_t, because when using arrays of int_fast8_t, it will create smaller arrays, which will be faster (less cache, etc.). (I remember having read that a long time ago, but I don't remember the source, or if it's the actual reason). How would you word that? Thanks, Alex
On Thu, 1 Oct 2020 at 12:15, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote: > > > > On 2020-10-01 13:07, Jonathan Wakely wrote: > [...] > >> +Notes: > >> +Some of these types may be optimized for size > >> +instead of raw performance. > > > > I'm not sure what this tells me as a programmer. What does "raw > > performance" means exactly? The text above says it's "the fastest", > > but then it says "may be optimized for size". I don't know how to > > interpret this. Is it fast or is it small, or something else? Is it > > optimized for small size? Natural word size? Cacheline size? > > > > I prefer the phrasing of the caveats in the C and POSIX standards > > which just say it might not be fastest for all purposes. > > > > How about "Where there is no single type that is fastest for all > > purposes, the implementation may choose any type with the required > > signedness and at least the minimum width." > > > > I don't see anything in this man page saying that the <stdint.h> types > > are all typedefs, rather than new types that are distinct from the > > standard integer types. That seems like useful information. > > > > Hi Jonathan, > > I wasn't sure about how to word it. > > In theory, they should be the fastest types; just that. > But then, for some reason, GCC decided that > int_fast8_t should be int8_t instead of int64_t, > because when using arrays of int_fast8_t, > it will create smaller arrays, which will be faster (less cache, etc.). > > (I remember having read that a long time ago, but I don't remember the > source, or if it's the actual reason). So then that's still optimized for "raw performance", isn't it? The "raw performance" of copying an array of bytes is better than the "raw performance" of copying an array of 64-bit types. The meaning of "raw performance" depends on what you're doing, so I don't think it's a useful term without context. > How would you word that? I gave a suggestion above. Don't use terms like "raw performance" that are meaningless without context. Using "no single type that is fastest for all purposes" makes it clearer that "fastest" isn't something universally true, it might be fastest for some purposes and not others.
On 2020-10-01 13:27, Jonathan Wakely wrote: >> How would you word that? > > I gave a suggestion above. Oops, I missed that. Thanks, Alex
On 2020-10-01 13:07, Jonathan Wakely wrote: > > I don't see anything in this man page saying that the <stdint.h> types > are all typedefs, rather than new types that are distinct from the > standard integer types. That seems like useful information. > Hello Jonathan, I almost missed this. We (Michael and I) chose not to give any information about typedefs in this page. So the reader should not assume that any type at all, unless explicitly specified, is a typedef. Any type could be defined however the implementation chooses to do, and this page will only give the requirements for the implementation. However, if you still think we should be clearer in this point, we might create a NOTE about this in the end of the page. Your thoughts? Thanks, Alex
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7 index a301c2309..07de6417f 100644 --- a/man7/system_data_types.7 +++ b/man7/system_data_types.7 @@ -329,6 +329,82 @@ C99 and later; POSIX.1-2001 and later. See also: .BR imaxdiv (3) .RE +.\"------------------------------------- int_fastN_t ------------------/ +.TP +.IR int_fast N _t +.RS +Include: +.IR <stdint.h> . +Alternatively, +.IR <inttypes.h> . +.PP +.IR int_fast8_t , +.IR int_fast16_t , +.IR int_fast32_t , +.I int_fast64_t +.PP +The fastest signed integer type +of a width of at least N bits, +N being the value specified in its type name. +According to the C language standard, they shall be +capable of storing values in the range +.RB [ INT_FAST N _MIN , +.BR INT_FAST N _MAX ], +substituting N by the appropriate number. +.PP +The length modifiers for the +.IR int_fast N _t +types for the +.BR printf (3) +family of functions +are expanded by macros of the forms +.BR PRIdFAST N +and +.BR PRIiFAST N +(defined in +.IR <inttypes.h> ); +resulting for example in +.B %"PRIdFAST64" +or +.B %"PRIiFAST64" +for printing +.I int_fast64_t +values. +The length modifiers for the +.IR int_fast N _t +types for the +.BR scanf (3) +family of functions +are expanded by macros of the forms +.BR SCNdFAST N +and +.BR SCNiFAST N, +(defined in +.IR <inttypes.h> ); +resulting for example in +.B %"SCNdFAST8" +or +.B %"SCNiFAST8" +for scanning +.I int_fast8_t +values. +.PP +Conforming to: +C99 and later; POSIX.1-2001 and later. +.PP +Notes: +Some of these types may be optimized for size +instead of raw performance. +.PP +See also the +.IR int_least N _t , +.IR int N _t , +.IR uint_fast N _t , +.IR uint_least N _t +and +.IR uint N _t +types in this page. +.RE .\"------------------------------------- intmax_t ---------------------/ .TP .I intmax_t