[PATCH v2 0/4] Document [u]int_leastN_t

[PATCH v2 0/4] Document [u]int_leastN_t

[Alejandro Colomar]

This patches are the v2 of the patches 9 to 12 of a previous patchset:
https://lore.kernel.org/linux-man/886f5647-2911-951a-b62a-4f9b1ed8850f@gmail.com/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

-- 
2.28.0

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

[Alejandro Colomar]

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

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
-- 
2.28.0

[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)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 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

diff --git a/man3/int_least16_t.3 b/man3/int_least16_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/int_least16_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/int_least32_t.3 b/man3/int_least32_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/int_least32_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/int_least64_t.3 b/man3/int_least64_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/int_least64_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/int_least8_t.3 b/man3/int_least8_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/int_least8_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/int_leastN_t.3 b/man3/int_leastN_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/int_leastN_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

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

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 75 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 3336de463..e42cf2557 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -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
-- 
2.28.0

[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)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 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

diff --git a/man3/uint_least16_t.3 b/man3/uint_least16_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/uint_least16_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/uint_least32_t.3 b/man3/uint_least32_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/uint_least32_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/uint_least64_t.3 b/man3/uint_least64_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/uint_least64_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/uint_least8_t.3 b/man3/uint_least8_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/uint_least8_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/uint_leastN_t.3 b/man3/uint_leastN_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/uint_leastN_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

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)

[Michael Kerrisk (man-pages)]

Thanks, Alex. Applied.

On 10/1/20 4:35 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  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
> 
> diff --git a/man3/int_least16_t.3 b/man3/int_least16_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/int_least16_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/int_least32_t.3 b/man3/int_least32_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/int_least32_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/int_least64_t.3 b/man3/int_least64_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/int_least64_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/int_least8_t.3 b/man3/int_least8_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/int_least8_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/int_leastN_t.3 b/man3/int_leastN_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/int_leastN_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

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

[Michael Kerrisk (man-pages)]

Thanks, Alex. Applied.

On 10/1/20 4:35 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  man7/system_data_types.7 | 75 ++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 75 insertions(+)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 3336de463..e42cf2557 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -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
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

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)

[Michael Kerrisk (man-pages)]

Thanks, Alex. Applied.

On 10/1/20 4:35 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  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
> 
> diff --git a/man3/uint_least16_t.3 b/man3/uint_least16_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/uint_least16_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/uint_least32_t.3 b/man3/uint_least32_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/uint_least32_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/uint_least64_t.3 b/man3/uint_least64_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/uint_least64_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/uint_least8_t.3 b/man3/uint_least8_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/uint_least8_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/uint_leastN_t.3 b/man3/uint_leastN_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/uint_leastN_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

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

[Paul Eggert]

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.

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

[Alejandro Colomar]

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

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

[Jonathan Wakely]

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.