[v2] system_data_types.7: Add note about length modifiers and conversions to [u]intmax_t, and corresponding example
Commit Message
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(+)
Comments
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)
>
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
@@ -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)