[PATCH v2] system_data_types.7: Specify the length modifiers for the variables that have them

[PATCH v2] system_data_types.7: Specify the length modifiers for the variables that have them

[Alejandro Colomar]

Reported-by: Florian Weimer <fweimer@redhat.com>
Reported-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---

Hello Paul,

On 9/18/20 10:24 PM, Paul Eggert wrote:
> I suggest saying "values" instead of "variables", here and elsewhere,
> since variables need not be involved.

Yes.

> This sort of thing should use ".B" not ".BR". There are multiple
> instances of this.

Oops. A few typos.

> POSIX does provide that length modifier; however, it doesn't say it
> works with ssize_t. I suggest rewording "Glibc provides a length
> modifier" to "Glibc and most other implementations provide a length
> modifier", and changing the last two sentences to:
> 
> 
> Although
> .B z
> works
> for
> .I ssize_t
> on Glibc and most other implementations, portable POSIX programs should
> avoid it, e.g., by converting to
> .I intmax_t
> and using its length modifier.

Much better wording.  Check the new one, please.

Thanks,

Alex

 man7/system_data_types.7 | 56 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 080f0057f..5128e1f01 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -108,6 +108,22 @@ capable of storing values in the range
 .BR "" [ PTRDIFF_MIN ,
 .BR PTRDIFF_MAX ].
 .IP
+The length modifier for
+.I ptrdiff_t
+for the
+.BR printf (3)
+and the
+.BR scanf (3)
+families of functions is
+.BR t ;
+resulting commonly in
+.B %td
+or
+.B %ti
+for printing
+.I ptrdiff_t
+values.
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
 .IP
 See also the
@@ -343,6 +359,22 @@ it shall be an unsigned integer type
 capable of storing values in the range [0,
 .BR SIZE_MAX ].
 .IP
+The length modifier for
+.I size_t
+for the
+.BR printf (3)
+and the
+.BR scanf (3)
+families of functions is
+.BR z ;
+resulting commonly in
+.B %zu
+or
+.B %zx
+for printing
+.I size_t
+values.
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
 .IP
 Notes:
@@ -403,6 +435,30 @@ According to POSIX, it shall be a signed integer type
 capable of storing values at least in the range [-1,
 .BR SSIZE_MAX ].
 .IP
+Glibc and most other implementations provide a length modifier for
+.I ssize_t
+for the
+.BR printf (3)
+and the
+.BR scanf (3)
+families of functions, which is
+.BR z ;
+resulting commonly in
+.B %zd
+or
+.B %zi
+for printing
+.I ssize_t
+values.
+Although
+.B z
+works for
+.I ssize_t
+on most implementations, portable POSIX programs should avoid using it,
+e.g., by converting the value to
+.I intmax_t
+and using its length modifier.
+.IP
 Conforming to: POSIX.1-2001 and later.
 .IP
 See also:
-- 
2.28.0

Re: [PATCH v2] system_data_types.7: Specify the length modifiers for the variables that have them

[Paul Eggert]

Thanks, that looks good.

Re: [PATCH v2] system_data_types.7: Specify the length modifiers for the variables that have them

[Michael Kerrisk (man-pages)]

Hi Alex,

On 9/20/20 8:14 PM, Alejandro Colomar wrote:
> Reported-by: Florian Weimer <fweimer@redhat.com>
> Reported-by: Paul Eggert <eggert@cs.ucla.edu>
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---

Thanks. Patch applied. Paul, thanks for reviewing; I added a 
Reviewed-by tag in your name.

Thanks,

Michael

PS It occurs to me that this manual page is a suitable place 
to explain the general technique of casting integral system
data types to [u]intmax_t for the purpose of printf(). Would
you like to add this, Alex?

> Hello Paul,
> 
> On 9/18/20 10:24 PM, Paul Eggert wrote:
>> I suggest saying "values" instead of "variables", here and elsewhere,
>> since variables need not be involved.
> 
> Yes.
> 
>> This sort of thing should use ".B" not ".BR". There are multiple
>> instances of this.
> 
> Oops. A few typos.
> 
>> POSIX does provide that length modifier; however, it doesn't say it
>> works with ssize_t. I suggest rewording "Glibc provides a length
>> modifier" to "Glibc and most other implementations provide a length
>> modifier", and changing the last two sentences to:
>>
>>
>> Although
>> .B z
>> works
>> for
>> .I ssize_t
>> on Glibc and most other implementations, portable POSIX programs should
>> avoid it, e.g., by converting to
>> .I intmax_t
>> and using its length modifier.
> 
> Much better wording.  Check the new one, please.
> 
> Thanks,
> 
> Alex
> 
>  man7/system_data_types.7 | 56 ++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 56 insertions(+)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 080f0057f..5128e1f01 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -108,6 +108,22 @@ capable of storing values in the range
>  .BR "" [ PTRDIFF_MIN ,
>  .BR PTRDIFF_MAX ].
>  .IP
> +The length modifier for
> +.I ptrdiff_t
> +for the
> +.BR printf (3)
> +and the
> +.BR scanf (3)
> +families of functions is
> +.BR t ;
> +resulting commonly in
> +.B %td
> +or
> +.B %ti
> +for printing
> +.I ptrdiff_t
> +values.
> +.IP
>  Conforming to: C99 and later; POSIX.1-2001 and later.
>  .IP
>  See also the
> @@ -343,6 +359,22 @@ it shall be an unsigned integer type
>  capable of storing values in the range [0,
>  .BR SIZE_MAX ].
>  .IP
> +The length modifier for
> +.I size_t
> +for the
> +.BR printf (3)
> +and the
> +.BR scanf (3)
> +families of functions is
> +.BR z ;
> +resulting commonly in
> +.B %zu
> +or
> +.B %zx
> +for printing
> +.I size_t
> +values.
> +.IP
>  Conforming to: C99 and later; POSIX.1-2001 and later.
>  .IP
>  Notes:
> @@ -403,6 +435,30 @@ According to POSIX, it shall be a signed integer type
>  capable of storing values at least in the range [-1,
>  .BR SSIZE_MAX ].
>  .IP
> +Glibc and most other implementations provide a length modifier for
> +.I ssize_t
> +for the
> +.BR printf (3)
> +and the
> +.BR scanf (3)
> +families of functions, which is
> +.BR z ;
> +resulting commonly in
> +.B %zd
> +or
> +.B %zi
> +for printing
> +.I ssize_t
> +values.
> +Although
> +.B z
> +works for
> +.I ssize_t
> +on most implementations, portable POSIX programs should avoid using it,
> +e.g., by converting the value to
> +.I intmax_t
> +and using its length modifier.
> +.IP
>  Conforming to: POSIX.1-2001 and later.
>  .IP
>  See also:
> 


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