diff mbox series

[v2,1/4] system_data_types.7: Add int_leastN_t family of types

Message ID 20201001143535.98990-2-colomar.6.4.3@gmail.com
State Not Applicable
Headers show
Series Document [u]int_leastN_t | expand

Commit Message

Alejandro Colomar Oct. 1, 2020, 2:35 p.m. UTC
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 72 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

Comments

Paul Eggert Oct. 1, 2020, 5:38 p.m. UTC | #1
On 10/1/20 7:35 AM, Alejandro Colomar via Libc-alpha wrote:
> +The narrowest signed integer type
> +of a width of at least N bits,

Motivation is missing here. Why is there an int_leastN_t type at all? Also, on 
all glibc platforms, int_leastN_t is equivalent to intN_t; this should probably 
be mentioned.

Similarly for int_fastN_t.
Alejandro Colomar Oct. 2, 2020, 8:35 a.m. UTC | #2
Hi Paul,

On 2020-10-01 19:38, Paul Eggert wrote:
 > On 10/1/20 7:35 AM, Alejandro Colomar via Libc-alpha wrote:
 >> +The narrowest signed integer type
 >> +of a width of at least N bits,
 >
 > Motivation is missing here. Why is there an int_leastN_t type at all?

Well, I'd say the motivation is for the standard to allow
unicorn implementations that have types that are not of normal widths
For example, this allows an implementation to have an int of 33 bits,
have int_least32_t be that int, and then not provide int32_t.

But, I'd say that writing this information in the man would only confuse
readers, would not be helpful because those are actually unicorns.

The few programmers that may need that info might better go to the standard.

 > Also, on all glibc platforms, int_leastN_t is equivalent to intN_t; this
 > should probably be mentioned.

We deliberately decided to not give any information on this.
Unless there's a strict requirement by the standard,
or there's some very good reason for it,
the programmer should treat typedefs as what they actaully are:
opaque types with some width, signedness and other requirements,
which we document here.

 >
 > Similarly for int_fastN_t.

Same as above.

Thanks,

Alex
Jonathan Wakely Oct. 2, 2020, 1:09 p.m. UTC | #3
On Fri, 2 Oct 2020 at 09:36, Alejandro Colomar via Gcc <gcc@gcc.gnu.org> wrote:
>
> Hi Paul,
>
> On 2020-10-01 19:38, Paul Eggert wrote:
>  > On 10/1/20 7:35 AM, Alejandro Colomar via Libc-alpha wrote:
>  >> +The narrowest signed integer type
>  >> +of a width of at least N bits,
>  >
>  > Motivation is missing here. Why is there an int_leastN_t type at all?
>
> Well, I'd say the motivation is for the standard to allow
> unicorn implementations that have types that are not of normal widths
> For example, this allows an implementation to have an int of 33 bits,
> have int_least32_t be that int, and then not provide int32_t.

C allows that, but POSIX says int32_t is required.
diff mbox series

Patch

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index c130b7256..3336de463 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -406,6 +406,78 @@  and
 .IR uint N _t
 types in this page.
 .RE
+.\"------------------------------------- int_leastN_t -----------------/
+.TP
+.IR int_least N _t
+.RS
+Include:
+.IR <stdint.h> .
+Alternatively,
+.IR <inttypes.h> .
+.PP
+.IR int_least8_t ,
+.IR int_least16_t ,
+.IR int_least32_t ,
+.I int_least64_t
+.PP
+The narrowest 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_LEAST N _MIN ,
+.BR INT_LEAST N _MAX ],
+substituting N by the appropriate number.
+.PP
+The length modifiers for the
+.IR int_least N _t
+types for the
+.BR printf (3)
+family of functions
+are expanded by macros of the forms
+.BR PRIdLEAST N
+and
+.BR PRIiLEAST N
+(defined in
+.IR <inttypes.h> );
+resulting for example in
+.B %"PRIdLEAST64"
+or
+.B %"PRIiLEAST64"
+for printing
+.I int_least64_t
+values.
+The length modifiers for the
+.IR int_least N _t
+types for the
+.BR scanf (3)
+family of functions
+are expanded by macros of the forms
+.BR SCNdLEAST N
+and
+.BR SCNiLEAST N,
+(defined in
+.IR <inttypes.h> );
+resulting for example in
+.B %"SCNdLEAST8"
+or
+.B %"SCNiLEAST8"
+for scanning
+.I int_least8_t
+values.
+.PP
+Conforming to:
+C99 and later; POSIX.1-2001 and later.
+.PP
+See also the
+.IR int_fast 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