Skip to contentSkip to conversation

Document [u]int_leastN_t

PATCH In review Alejandro Colomar 4 participants 11 messages Oct 1, 2020 – Oct 2, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

v2 cover Document [u]int_leastN_t

This patches are the v2 of the patches 9 to 12 of a previous patchset:
https://lore.kernel.org/linux-man/[email protected]/T/#t

Alejandro Colomar (4):
system_data_types.7: Add int_leastN_t family of types int_least8_t.3, int_least16_t.3, int_least32_t.3, int_least64_t.3,
int_leastN_t.3: New links to system_data_types(7)
system_data_types.7: Add uint_leastN_t family of types uint_least8_t.3, uint_least16_t.3, uint_least32_t.3, uint_least64_t.3,
uint_leastN_t.3: New links to system_data_types(7)

 man3/int_least16_t.3     |   1 +
 man3/int_least32_t.3     |   1 +
 man3/int_least64_t.3     |   1 +
 man3/int_least8_t.3      |   1 +
 man3/int_leastN_t.3      |   1 +
 man3/uint_least16_t.3    |   1 +
 man3/uint_least32_t.3    |   1 +
 man3/uint_least64_t.3    |   1 +
 man3/uint_least8_t.3     |   1 +
 man3/uint_leastN_t.3     |   1 +
 man7/system_data_types.7 | 147 +++++++++++++++++++++++++++++++++++++++
 11 files changed, 157 insertions(+)
 create mode 100644 man3/int_least16_t.3
 create mode 100644 man3/int_least32_t.3
 create mode 100644 man3/int_least64_t.3
 create mode 100644 man3/int_least8_t.3
 create mode 100644 man3/int_leastN_t.3
 create mode 100644 man3/uint_least16_t.3
 create mode 100644 man3/uint_least32_t.3
 create mode 100644 man3/uint_least64_t.3
 create mode 100644 man3/uint_least8_t.3
 create mode 100644 man3/uint_leastN_t.3
Signature · 1 line
2.28.0
#1 lore raw

PATCH v2 1/4 system_data_types.7: Add int_leastN_t family of types

---
 man7/system_data_types.7 | 72 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
man7/system_data_types.7 +72 -0
index c130b7256..3336de463 100644
@@ -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
Signature · 1 line
2.28.0
#2 lore raw

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

man7/system_data_types.7 and · line 424

Quoted 2 lines · Alejandro Colomar via Libc-alpha
man7/system_data_types.7 +2 -0
+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.

#3 lore raw

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

Hi Paul,

Quoted 5 lines · Paul Eggert

man7/system_data_types.7 and · line 424

Quoted 2 lines · Alejandro Colomar via Libc-alpha
man7/system_data_types.7 +2 -0
+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.

Quoted 2 lines

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.

Quoted 2 lines

Similarly for int_fastN_t.

Same as above.

Thanks,

Alex

#4 lore raw

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

Quoted 10 lines · Alejandro Colomar via Gcc

Hi Paul,

Quoted 5 lines · Paul Eggert

man7/system_data_types.7 and · line 424

Quoted 2 lines · Alejandro Colomar via Libc-alpha
man7/system_data_types.7 +2 -0
+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?

Quoted 4 lines

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.

#5 lore raw

PATCH v2 2/4 int_least8_t.3, int_least16_t.3, int_least32_t.3, int_least64_t.3, int_leastN_t.3: New links to system_data_types(7)

In reply to Alejandro Colomar
---
 man3/int_least16_t.3 | 1 +
 man3/int_least32_t.3 | 1 +
 man3/int_least64_t.3 | 1 +
 man3/int_least8_t.3  | 1 +
 man3/int_leastN_t.3  | 1 +
 5 files changed, 5 insertions(+)
 create mode 100644 man3/int_least16_t.3
 create mode 100644 man3/int_least32_t.3
 create mode 100644 man3/int_least64_t.3
 create mode 100644 man3/int_least8_t.3
 create mode 100644 man3/int_leastN_t.3
man3/int_least16_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/int_least32_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/int_least64_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/int_least8_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/int_leastN_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
Signature · 1 line
2.28.0
#6 lore raw

Re: [PATCH v2 2/4] int_least8_t.3, int_least16_t.3, int_least32_t.3, int_least64_t.3, int_leastN_t.3: New links to system_data_types(7)

Thanks, Alex. Applied.

Quoted 50 lines · Alejandro Colomar
---
 man3/int_least16_t.3 | 1 +
 man3/int_least32_t.3 | 1 +
 man3/int_least64_t.3 | 1 +
 man3/int_least8_t.3  | 1 +
 man3/int_leastN_t.3  | 1 +
 5 files changed, 5 insertions(+)
 create mode 100644 man3/int_least16_t.3
 create mode 100644 man3/int_least32_t.3
 create mode 100644 man3/int_least64_t.3
 create mode 100644 man3/int_least8_t.3
 create mode 100644 man3/int_leastN_t.3
man3/int_least16_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/int_least32_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/int_least64_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/int_least8_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/int_leastN_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#7 lore raw

PATCH v2 3/4 system_data_types.7: Add uint_leastN_t family of types

In reply to Alejandro Colomar
---
 man7/system_data_types.7 | 75 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
man7/system_data_types.7 +75 -0
index 3336de463..e42cf2557 100644
@@ -1500,6 +1500,81 @@ and
 .IR uint N _t
 types in this page.
 .RE
+.\"------------------------------------- uint_leastN_t ----------------/
+.TP
+.IR uint_least N _t
+.RS
+Include:
+.IR <stdint.h> .
+Alternatively,
+.IR <inttypes.h> .
+.PP
+.IR uint_least8_t ,
+.IR uint_least16_t ,
+.IR uint_least32_t ,
+.I uint_least64_t
+.PP
+The narrowest unsigned 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 [0,
+.BR UINT_LEAST N _MAX ],
+substituting N by the appropriate number.
+.PP
+The length modifiers for the
+.IR uint_least N _t
+types for the
+.BR printf (3)
+family of functions
+are expanded by macros of the forms
+.BR PRIuLEST N,
+.BR PRIoLEAST N,
+.BR PRIxLEAST N
+and
+.BR PRIXLEAST N
+(defined in
+.IR <inttypes.h> );
+resulting for example in
+.B %"PRIuLEAST32"
+or
+.B %"PRIxLEAST32"
+for printing
+.I uint_least32_t
+values.
+The length modifiers for the
+.IR uint_least N _t
+types for the
+.BR scanf (3)
+family of functions
+are expanded by macros of the forms
+.BR SCNuLEAST N,
+.BR SCNoLEAST N,
+.BR SCNxLEAST N
+and
+.BR SCNXLEAST N
+(defined in
+.IR <inttypes.h> );
+resulting for example in
+.B %"SCNuLEAST16"
+or
+.B %"SCNxLEAST16"
+for scanning
+.I uint_least16_t
+values.
+.PP
+Conforming to:
+C99 and later; POSIX.1-2001 and later.
+.PP
+See also the
+.IR int_fast N _t ,
+.IR int_least N _t ,
+.IR int N _t ,
+.IR uint_fast N _t
+and
+.IR uint N _t
+types in this page.
+.RE
 .\"------------------------------------- uintmax_t --------------------/
 .TP
 .I uintmax_t
Signature · 1 line
2.28.0
#8 lore raw

Re: [PATCH v2 3/4] system_data_types.7: Add uint_leastN_t family of types

Thanks, Alex. Applied.

Quoted 92 lines · Alejandro Colomar
---
 man7/system_data_types.7 | 75 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
man7/system_data_types.7 +75 -0
index 3336de463..e42cf2557 100644
@@ -1500,6 +1500,81 @@ and
 .IR uint N _t
 types in this page.
 .RE
+.\"------------------------------------- uint_leastN_t ----------------/
+.TP
+.IR uint_least N _t
+.RS
+Include:
+.IR <stdint.h> .
+Alternatively,
+.IR <inttypes.h> .
+.PP
+.IR uint_least8_t ,
+.IR uint_least16_t ,
+.IR uint_least32_t ,
+.I uint_least64_t
+.PP
+The narrowest unsigned 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 [0,
+.BR UINT_LEAST N _MAX ],
+substituting N by the appropriate number.
+.PP
+The length modifiers for the
+.IR uint_least N _t
+types for the
+.BR printf (3)
+family of functions
+are expanded by macros of the forms
+.BR PRIuLEST N,
+.BR PRIoLEAST N,
+.BR PRIxLEAST N
+and
+.BR PRIXLEAST N
+(defined in
+.IR <inttypes.h> );
+resulting for example in
+.B %"PRIuLEAST32"
+or
+.B %"PRIxLEAST32"
+for printing
+.I uint_least32_t
+values.
+The length modifiers for the
+.IR uint_least N _t
+types for the
+.BR scanf (3)
+family of functions
+are expanded by macros of the forms
+.BR SCNuLEAST N,
+.BR SCNoLEAST N,
+.BR SCNxLEAST N
+and
+.BR SCNXLEAST N
+(defined in
+.IR <inttypes.h> );
+resulting for example in
+.B %"SCNuLEAST16"
+or
+.B %"SCNxLEAST16"
+for scanning
+.I uint_least16_t
+values.
+.PP
+Conforming to:
+C99 and later; POSIX.1-2001 and later.
+.PP
+See also the
+.IR int_fast N _t ,
+.IR int_least N _t ,
+.IR int N _t ,
+.IR uint_fast N _t
+and
+.IR uint N _t
+types in this page.
+.RE
 .\"------------------------------------- uintmax_t --------------------/
 .TP
 .I uintmax_t
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#9 lore raw

PATCH v2 4/4 uint_least8_t.3, uint_least16_t.3, uint_least32_t.3, uint_least64_t.3, uint_leastN_t.3: New links to system_data_types(7)

In reply to Alejandro Colomar
---
 man3/uint_least16_t.3 | 1 +
 man3/uint_least32_t.3 | 1 +
 man3/uint_least64_t.3 | 1 +
 man3/uint_least8_t.3  | 1 +
 man3/uint_leastN_t.3  | 1 +
 5 files changed, 5 insertions(+)
 create mode 100644 man3/uint_least16_t.3
 create mode 100644 man3/uint_least32_t.3
 create mode 100644 man3/uint_least64_t.3
 create mode 100644 man3/uint_least8_t.3
 create mode 100644 man3/uint_leastN_t.3
man3/uint_least16_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/uint_least32_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/uint_least64_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/uint_least8_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/uint_leastN_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
Signature · 1 line
2.28.0
#10 lore raw

Re: [PATCH v2 4/4] uint_least8_t.3, uint_least16_t.3, uint_least32_t.3, uint_least64_t.3, uint_leastN_t.3: New links to system_data_types(7)

Thanks, Alex. Applied.

Quoted 50 lines · Alejandro Colomar
---
 man3/uint_least16_t.3 | 1 +
 man3/uint_least32_t.3 | 1 +
 man3/uint_least64_t.3 | 1 +
 man3/uint_least8_t.3  | 1 +
 man3/uint_leastN_t.3  | 1 +
 5 files changed, 5 insertions(+)
 create mode 100644 man3/uint_least16_t.3
 create mode 100644 man3/uint_least32_t.3
 create mode 100644 man3/uint_least64_t.3
 create mode 100644 man3/uint_least8_t.3
 create mode 100644 man3/uint_leastN_t.3
man3/uint_least16_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/uint_least32_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/uint_least64_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/uint_least8_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
man3/uint_leastN_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/