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

[RFC] 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>
---

Hi Florian and Paul,

Thanks for the input. (for completeness, the thread was here: https://lore.kernel.org/linux-man/87imcb0y53.fsf@oldenburg2.str.redhat.com/).

Would you maybe improve the wording?  Or is it OK like this?

Thanks,

Alex

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

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index b705ed5ae..4830a4a7d 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -107,6 +107,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
+.BR %ti
+for printing
+.I ptrdiff_t
+variables.
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
 .IP
 See also the
@@ -339,6 +355,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
+.BR %zx
+for printing
+.I size_t
+variables.
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
 .IP
 Notes:
@@ -396,6 +428,26 @@ 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 provides 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
+.BR %zi
+for printing
+.I ssize_t
+variables.
+Note that POSIX doesn't provide this length modifier,
+and therefore portable programs should avoid using it.
+Instead, such programs should cast the value to
+.IR intmax_t .
+.IP
 Conforming to: POSIX.1-2001 and later.
 .IP
 See also:
-- 
2.28.0

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

[Paul Eggert]

On 9/18/20 12:54 PM, Alejandro Colomar wrote:

> +for printing
> +.I ptrdiff_t
> +variables.

I suggest saying "values" instead of "variables", here and elsewhere, since 
variables need not be involved.

> +.BR %ti

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

> +Glibc provides 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
> +.BR %zi
> +for printing
> +.I ssize_t
> +variables.
> +Note that POSIX doesn't provide this length modifier,
> +and therefore portable programs should avoid using it.
> +Instead, such programs should cast the value to
> +.IR intmax_t .


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.