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

[Alejandro Colomar <colomar.6.4.3@gmail.com>]

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