[PATCH] system_data_types.7: Add note about length modifiers and conversions to [u]intmax_t, and corresponding example

[PATCH] system_data_types.7: Add note about length modifiers and conversions to [u]intmax_t, and corresponding example

[Alejandro Colomar]

Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
Hi Michael,

On 9/20/20 10:20 PM, Michael Kerrisk (man-pages) wrote:
> 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?

Sure.  Good idea!

Hope you like the patch :)

Cheers,

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 5128e1f01..1fcc09dae 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -626,6 +626,58 @@ See also:
 .SH NOTES
 The structures described in this manual page shall contain,
 at least, the members shown in their definition, in no particular order.
+.PP
+Most of the types described in this page don't have a corresponding
+length modifier for the
+.BR printf (3)
+and the
+.BR scanf (3)
+families of functions.
+To print a value of a type that doesn't have a length modifier,
+it should be converted to
+.I intmax_t
+or
+.I uintmax_t
+by an explicit cast.
+To scan into a variable of a type that doesn't have a length modifier,
+an intermediate temporary variable of type
+.I intmax_t
+or
+.I uintmax_t
+should be used.
+The example below shows how these conversions should be done.
+.SH EXAMPLES
+The program shown below scans from a string and prints a value stored in
+a variable of a type that doesn't have a length modifier.
+The appropriate conversions from and to
+.I intmax_t
+are used as explained in the notes section above:
+.PP
+.EX
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <time.h>
+
+int
+main (void)
+{
+    static const char *const str = "There are 60 s in an hour";
+    time_t   secs;
+    intmax_t tmp;
+
+    /* Scan the number from the string into the temporary variable */
+    sscanf(str, "There are %jd", &tmp);
+
+    /* Copy the value to the time_t variable secs */
+    secs = tmp;
+
+    /* Print the value */
+    printf("There are %jd seconds in an hour!\en", (intmax_t) secs);
+
+    exit(EXIT_SUCCESS);
+}
+.EE
 .SH SEE ALSO
 .BR feature_test_macros (7),
 .BR standards (7)
-- 
2.28.0

Re: [PATCH] system_data_types.7: Add note about length modifiers and conversions to [u]intmax_t, and corresponding example

[Michael Kerrisk (man-pages)]

Hi Alex,

On 9/20/20 11:40 PM, Alejandro Colomar wrote:
> Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
> Hi Michael,
> 
> On 9/20/20 10:20 PM, Michael Kerrisk (man-pages) wrote:
>> 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?
> 
> Sure.  Good idea!
> 
> Hope you like the patch :)

Good in principle, but some tweaks required.

>  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 5128e1f01..1fcc09dae 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -626,6 +626,58 @@ See also:
>  .SH NOTES
>  The structures described in this manual page shall contain,
>  at least, the members shown in their definition, in no particular order.
> +.PP
> +Most of the types described in this page don't have a corresponding

s/types/integer types/

> +length modifier for the
> +.BR printf (3)
> +and the
> +.BR scanf (3)
> +families of functions.
> +To print a value of a type that doesn't have a length modifier,
> +it should be converted to
> +.I intmax_t
> +or
> +.I uintmax_t
> +by an explicit cast.
> +To scan into a variable of a type that doesn't have a length modifier,

s/a type/an integer/

> +an intermediate temporary variable of type
> +.I intmax_t
> +or
> +.I uintmax_t
> +should be used.

Hmmm -- I wonder if we need to say something about range checking.
I mean, what if time_t is narrower than intmax_t in the example below?
(It's not, on my x86-64 system.) The problem of course is how to
construct such a range check in the absence of any appropriate
POSIX constants (e.g., there is no TIME_T_MAX).

> +The example below shows how these conversions should be done.
> +.SH EXAMPLES
> +The program shown below scans from a string and prints a value stored in
> +a variable of a type that doesn't have a length modifier.
> +The appropriate conversions from and to
> +.I intmax_t
> +are used as explained in the notes section above:
> +.PP
> +.EX
> +#include <stdint.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <time.h>
> +
> +int
> +main (void)
> +{
> +    static const char *const str = "There are 60 s in an hour";

Either "60" needs to be 3600 or "hour" needs to be "minute".

> +    time_t   secs;
> +    intmax_t tmp;
> +
> +    /* Scan the number from the string into the temporary variable */
> +    sscanf(str, "There are %jd", &tmp);
> +
> +    /* Copy the value to the time_t variable secs */
> +    secs = tmp;
> +
> +    /* Print the value */
> +    printf("There are %jd seconds in an hour!\en", (intmax_t) secs);

See my previous comment. A change may be required in the line above.

> +
> +    exit(EXIT_SUCCESS);
> +}
> +.EE
>  .SH SEE ALSO
>  .BR feature_test_macros (7),
>  .BR standards (7)

Thanks,

Michael


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

[PATCH v2] system_data_types.7: Add note about length modifiers and conversions to [u]intmax_t, and corresponding example

[Alejandro Colomar]

Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---

Hi Michael,

I added the part about range checking, and used a type with defined
limits to show a complete example.

Thanks,

Alex


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

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index dd1d01aab..ba1338179 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -629,6 +629,68 @@ See also:
 .SH NOTES
 The structures described in this manual page shall contain,
 at least, the members shown in their definition, in no particular order.
+.PP
+Most of the integer types described in this page don't have
+a corresponding length modifier for the
+.BR printf (3)
+and the
+.BR scanf (3)
+families of functions.
+To print a value of an integer type that doesn't have a length modifier,
+it should be converted to
+.I intmax_t
+or
+.I uintmax_t
+by an explicit cast.
+To scan into a variable of a type that doesn't have a length modifier,
+an intermediate temporary variable of type
+.I intmax_t
+or
+.I uintmax_t
+should be used.
+When copying from the temporary variable to the actual variable,
+the value could overflow.
+If POSIX provides lower and upper limits to the type,
+the user should check that the value is within those limits,
+before actually copying the value.
+The example below shows how these conversions should be done.
+.SH EXAMPLES
+The program shown below scans from a string and prints a value stored in
+a variable of an integer type that doesn't have a length modifier.
+The appropriate conversions from and to
+.IR intmax_t ,
+and the appropriate range checkings,
+are used as explained in the notes section above:
+.PP
+.EX
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/types.h>
+
+int
+main (void)
+{
+    static const char *const str = "500000 us in half a second";
+    suseconds_t us;
+    intmax_t    tmp;
+
+    /* Scan the number from the string into the temporary variable */
+    sscanf(str, "%jd", &tmp);
+
+    /* Check that the value is within the valid range */
+    if (tmp < -1 || tmp > 1000000)
+        exit(EXIT_FAILURE);
+
+    /* Copy the value to the suseconds_t variable 'us' */
+    us = tmp;
+
+    /* Print the value */
+    printf("There are %jd us in half a second.\en", (intmax_t) us);
+
+    exit(EXIT_SUCCESS);
+}
+.EE
 .SH SEE ALSO
 .BR feature_test_macros (7),
 .BR standards (7)
-- 
2.28.0

Re: [PATCH v2] system_data_types.7: Add note about length modifiers and conversions to [u]intmax_t, and corresponding example

[Alejandro Colomar]

Corrections below:

On 2020-09-21 10:19, Alejandro Colomar wrote:
> Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
> 
> Hi Michael,
> 
> I added the part about range checking, and used a type with defined
> limits to show a complete example.
> 
> Thanks,
> 
> Alex
> 
> 
>   man7/system_data_types.7 | 62 ++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 62 insertions(+)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index dd1d01aab..ba1338179 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -629,6 +629,68 @@ See also:
>   .SH NOTES
>   The structures described in this manual page shall contain,
>   at least, the members shown in their definition, in no particular order.
> +.PP
> +Most of the integer types described in this page don't have
> +a corresponding length modifier for the
> +.BR printf (3)
> +and the
> +.BR scanf (3)
> +families of functions.
> +To print a value of an integer type that doesn't have a length modifier,
> +it should be converted to
> +.I intmax_t
> +or
> +.I uintmax_t
> +by an explicit cast.
> +To scan into a variable of a type that doesn't have a length modifier,
> +an intermediate temporary variable of type
> +.I intmax_t
> +or
> +.I uintmax_t
> +should be used.
> +When copying from the temporary variable to the actual variable,
> +the value could overflow.
> +If POSIX provides lower and upper limits to the type,


Actually, I should have said:

If the type has upper and lower limits,

or something like that.


> +the user should check that the value is within those limits,
> +before actually copying the value.
> +The example below shows how these conversions should be done.
> +.SH EXAMPLES
> +The program shown below scans from a string and prints a value stored in
> +a variable of an integer type that doesn't have a length modifier.
> +The appropriate conversions from and to
> +.IR intmax_t ,
> +and the appropriate range checkings,
> +are used as explained in the notes section above:
> +.PP
> +.EX
> +#include <stdint.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/types.h>
> +
> +int
> +main (void)
> +{
> +    static const char *const str = "500000 us in half a second";
> +    suseconds_t us;
> +    intmax_t    tmp;
> +
> +    /* Scan the number from the string into the temporary variable */
> +    sscanf(str, "%jd", &tmp);
> +
> +    /* Check that the value is within the valid range */
> +    if (tmp < -1 || tmp > 1000000)
> +        exit(EXIT_FAILURE);
> +
> +    /* Copy the value to the suseconds_t variable 'us' */
> +    us = tmp;
> +
> +    /* Print the value */
> +    printf("There are %jd us in half a second.\en", (intmax_t) us);
> +
> +    exit(EXIT_SUCCESS);
> +}
> +.EE
>   .SH SEE ALSO
>   .BR feature_test_macros (7),
>   .BR standards (7)
> 

Re: [PATCH v2] system_data_types.7: Add note about length modifiers and conversions to [u]intmax_t, and corresponding example

[Michael Kerrisk (man-pages)]

Hello Alex,

On 9/21/20 10:19 AM, Alejandro Colomar wrote:
> Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
> 
> Hi Michael,
> 
> I added the part about range checking, and used a type with defined
> limits to show a complete example.

Thanks! Still a few coments.

> Thanks,
> 
> Alex
> 
> 
>  man7/system_data_types.7 | 62 ++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 62 insertions(+)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index dd1d01aab..ba1338179 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -629,6 +629,68 @@ See also:
>  .SH NOTES
>  The structures described in this manual page shall contain,
>  at least, the members shown in their definition, in no particular order.
> +.PP
> +Most of the integer types described in this page don't have
> +a corresponding length modifier for the
> +.BR printf (3)
> +and the
> +.BR scanf (3)
> +families of functions.
> +To print a value of an integer type that doesn't have a length modifier,
> +it should be converted to
> +.I intmax_t
> +or
> +.I uintmax_t
> +by an explicit cast.
> +To scan into a variable of a type that doesn't have a length modifier,

s/a type/an integer type/

> +an intermediate temporary variable of type
> +.I intmax_t
> +or
> +.I uintmax_t
> +should be used.
> +When copying from the temporary variable to the actual variable,

s/actual/destination/

> +the value could overflow.
> +If POSIX provides lower and upper limits to the type,
> +the user should check that the value is within those limits,
> +before actually copying the value.
> +The example below shows how these conversions should be done.
> +.SH EXAMPLES
> +The program shown below scans from a string and prints a value stored in
> +a variable of an integer type that doesn't have a length modifier.
> +The appropriate conversions from and to
> +.IR intmax_t ,
> +and the appropriate range checkings,
> +are used as explained in the notes section above:
> +.PP
> +.EX
> +#include <stdint.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/types.h>
> +
> +int
> +main (void)
> +{
> +    static const char *const str = "500000 us in half a second";
> +    suseconds_t us;
> +    intmax_t    tmp;
> +
> +    /* Scan the number from the string into the temporary variable */
> +    sscanf(str, "%jd", &tmp);
> +
> +    /* Check that the value is within the valid range */
> +    if (tmp < -1 || tmp > 1000000)

I think the first part of the check here should be 'tmp < 0'.
(Yes, the defined range for the type must allow -1, but speaking
of -1 microseconds is nonsensical, right?

> +        exit(EXIT_FAILURE);
> +
> +    /* Copy the value to the suseconds_t variable 'us' */
> +    us = tmp;
> +
> +    /* Print the value */
> +    printf("There are %jd us in half a second.\en", (intmax_t) us);
> +
> +    exit(EXIT_SUCCESS);
> +}
> +.EE
>  .SH SEE ALSO
>  .BR feature_test_macros (7),
>  .BR standards (7)

Thanks,

Michael


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

[PATCH v3] system_data_types.7: Add note about length modifiers and conversions to [u]intmax_t, and corresponding example

[Alejandro Colomar]

Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---

Hi Michael,

wfix +

I thought that checking between 0 and 1M might create confusion,
so I kept that check, and added another one
to differentiate the error code from normal values.

Cheers,

Alex


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

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index dd1d01aab..da57deffa 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -629,6 +629,79 @@ See also:
 .SH NOTES
 The structures described in this manual page shall contain,
 at least, the members shown in their definition, in no particular order.
+.PP
+Most of the integer types described in this page don't have
+a corresponding length modifier for the
+.BR printf (3)
+and the
+.BR scanf (3)
+families of functions.
+To print a value of an integer type that doesn't have a length modifier,
+it should be converted to
+.I intmax_t
+or
+.I uintmax_t
+by an explicit cast.
+To scan into a variable of an integer type
+that doesn't have a length modifier,
+an intermediate temporary variable of type
+.I intmax_t
+or
+.I uintmax_t
+should be used.
+When copying from the temporary variable to the destination variable,
+the value could overflow.
+If POSIX provides lower and upper limits to the type,
+the user should check that the value is within those limits,
+before actually copying the value.
+The example below shows how these conversions should be done.
+.SH EXAMPLES
+The program shown below scans from a string and prints a value stored in
+a variable of an integer type that doesn't have a length modifier.
+The appropriate conversions from and to
+.IR intmax_t ,
+and the appropriate range checkings,
+are used as explained in the notes section above:
+.PP
+.EX
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/types.h>
+
+
+int
+main (void)
+{
+    static const char *const str = "500000 us in half a second";
+    suseconds_t us;
+    intmax_t    tmp;
+
+    /* Scan the number from the string into the temporary variable */
+    sscanf(str, "%jd", &tmp);
+
+    /* Check that the value is within the valid range of suseconds_t */
+    if (tmp < -1 || tmp > 1000000) {
+        fprintf(stderr, "Scaned value might overflow!\en");
+        exit(EXIT_FAILURE);
+    }
+
+    /* Copy the value to the suseconds_t variable 'us' */
+    us = tmp;
+
+    /* Even though suseconds_t can hold the value -1,
+       it represents an error code */
+    if (us < 0) {
+        fprintf(stderr, "Scanned an error code!\en");
+        exit(EXIT_FAILURE);
+    }
+
+    /* Print the value */
+    printf("There are %jd us in half a second.\en", (intmax_t) us);
+
+    exit(EXIT_SUCCESS);
+}
+.EE
 .SH SEE ALSO
 .BR feature_test_macros (7),
 .BR standards (7)
-- 
2.28.0

Re: [PATCH v3] system_data_types.7: Add note about length modifiers and conversions to [u]intmax_t, and corresponding example

[Michael Kerrisk (man-pages)]

Hi Alex,

On 9/21/20 3:32 PM, Alejandro Colomar wrote:
> Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
> 
> Hi Michael,
> 
> wfix +
> 
> I thought that checking between 0 and 1M might create confusion,
> so I kept that check, and added another one
> to differentiate the error code from normal values.

Thanks. I've applied this, and done some light editing. Please
let me know if anyting in commit 89c6c2bdd2ea doesn't look okay.

Thanks,

Michael

>  man7/system_data_types.7 | 73 ++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 73 insertions(+)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index dd1d01aab..da57deffa 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -629,6 +629,79 @@ See also:
>  .SH NOTES
>  The structures described in this manual page shall contain,
>  at least, the members shown in their definition, in no particular order.
> +.PP
> +Most of the integer types described in this page don't have
> +a corresponding length modifier for the
> +.BR printf (3)
> +and the
> +.BR scanf (3)
> +families of functions.
> +To print a value of an integer type that doesn't have a length modifier,
> +it should be converted to
> +.I intmax_t
> +or
> +.I uintmax_t
> +by an explicit cast.
> +To scan into a variable of an integer type
> +that doesn't have a length modifier,
> +an intermediate temporary variable of type
> +.I intmax_t
> +or
> +.I uintmax_t
> +should be used.
> +When copying from the temporary variable to the destination variable,
> +the value could overflow.
> +If POSIX provides lower and upper limits to the type,
> +the user should check that the value is within those limits,
> +before actually copying the value.
> +The example below shows how these conversions should be done.
> +.SH EXAMPLES
> +The program shown below scans from a string and prints a value stored in
> +a variable of an integer type that doesn't have a length modifier.
> +The appropriate conversions from and to
> +.IR intmax_t ,
> +and the appropriate range checkings,
> +are used as explained in the notes section above:
> +.PP
> +.EX
> +#include <stdint.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/types.h>
> +
> +
> +int
> +main (void)
> +{
> +    static const char *const str = "500000 us in half a second";
> +    suseconds_t us;
> +    intmax_t    tmp;
> +
> +    /* Scan the number from the string into the temporary variable */
> +    sscanf(str, "%jd", &tmp);
> +
> +    /* Check that the value is within the valid range of suseconds_t */
> +    if (tmp < -1 || tmp > 1000000) {
> +        fprintf(stderr, "Scaned value might overflow!\en");
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    /* Copy the value to the suseconds_t variable 'us' */
> +    us = tmp;
> +
> +    /* Even though suseconds_t can hold the value -1,
> +       it represents an error code */
> +    if (us < 0) {
> +        fprintf(stderr, "Scanned an error code!\en");
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    /* Print the value */
> +    printf("There are %jd us in half a second.\en", (intmax_t) us);
> +
> +    exit(EXIT_SUCCESS);
> +}
> +.EE
>  .SH SEE ALSO
>  .BR feature_test_macros (7),
>  .BR standards (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 v3] system_data_types.7: Add note about length modifiers and conversions to [u]intmax_t, and corresponding example

[Alejandro Colomar]

On 2020-09-21 16:13, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> Thanks. I've applied this, and done some light editing. Please
> let me know if anyting in commit 89c6c2bdd2ea doesn't look okay.
> 
> Thanks,
> 
> Michael

Hi Michael,

It looks good :)

Thanks,

Alex