[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/

man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on

[Alejandro Colomar]

Hello Michael,


Indentation of structure definitions, shell session logs, and so on

When  structure definitions, shell session logs, and so on are included
in running text, indent them by 4 spaces (i.e.,  a  block  enclosed  by
.in +4n and .in), format them using the .EX and EE macros, and surround
them with suitable paragraph markers (either .PP or .IP).  For example:

                .PP
                .in +4n
                .EX
                int
                main(int argc, char *argv[])
                {
                    return 0;
                }
                .EE
                .in
                .PP


That could be simplified to the following, right?:

                .IP
                .EX
                int
                main(int argc, char *argv[])
                {
                    return 0;
                }
                .EE
                .PP

Or is there any difference?


Thanks,

Alex

Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on

[Michael Kerrisk (man-pages)]

Hi Alex,

On Mon, 21 Sep 2020 at 09:32, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
>
> Hello Michael,
>
>
> Indentation of structure definitions, shell session logs, and so on
>
> When  structure definitions, shell session logs, and so on are included
> in running text, indent them by 4 spaces (i.e.,  a  block  enclosed  by
> .in +4n and .in), format them using the .EX and EE macros, and surround
> them with suitable paragraph markers (either .PP or .IP).  For example:
>
>                 .PP
>                 .in +4n
>                 .EX
>                 int
>                 main(int argc, char *argv[])
>                 {
>                     return 0;
>                 }
>                 .EE
>                 .in
>                 .PP
>
>
> That could be simplified to the following, right?:
>
>                 .IP
>                 .EX
>                 int
>                 main(int argc, char *argv[])
>                 {
>                     return 0;
>                 }
>                 .EE
>                 .PP
>
> Or is there any difference?

.IP indents by 8 spaces by default, I think. Also, .IP won't indent
further, if we are already in an area of indented paragraphs.

Thanks,

Michael


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

Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on

[G. Branden Robinson]

[-- Attachment #1.1: Type: text/plain, Size: 3523 bytes --]

At 2020-09-21T09:49:11+0200, Michael Kerrisk (man-pages) wrote:
> On Mon, 21 Sep 2020 at 09:32, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
> > Indentation of structure definitions, shell session logs, and so on
> >
> > When  structure definitions, shell session logs, and so on are included
> > in running text, indent them by 4 spaces (i.e.,  a  block  enclosed  by
> > .in +4n and .in), format them using the .EX and EE macros, and surround
> > them with suitable paragraph markers (either .PP or .IP).  For example:
> >
> >                 .PP
> >                 .in +4n
> >                 .EX
> >                 int
> >                 main(int argc, char *argv[])
> >                 {
> >                     return 0;
> >                 }
> >                 .EE
> >                 .in
> >                 .PP
> >
> >
> > That could be simplified to the following, right?:
> >
> >                 .IP
> >                 .EX
> >                 int
> >                 main(int argc, char *argv[])
> >                 {
> >                     return 0;
> >                 }
> >                 .EE
> >                 .PP
> >
> > Or is there any difference?
> 
> .IP indents by 8 spaces by default, I think.

7 "ens" on nroff devices (like terminals), 7.2n on troff devices.

An "en" is a traditional typesetting unit of measure, the width of a
letter "n" in the font being used.  For monospaced fonts, including
those used in character-cell terminals--barring the employment of CJK
"fullwidth" code points--this is the same width as a space.

> Also, .IP won't indent further, if we are already in an area of
> indented paragraphs.

This is true.  In my maintenance work on groff's man pages I have
devised an idiom of calling .RS twice, putting in the desired material,
and then calling .RE twice.

In membarrier(2), however, life is simple because no code examples are
being nested inside an indented paragraph (.IP).  I'm attaching a patch;
it produces no visible difference in output, not even white space
changes.

I should add that my suggestion is to _not_ specify precise indentation
amounts in man pages, as this is a presentation matter and readers may
prefer tighter or more generous indentation, which they can control via
the IN register; that is, passing -rIN to the groff command.  (Or, more
likely, by configuring it in their man.local file so all pages that
respect the user's wishes are consistent.)

I've been improving the groff_man(7) page over the past few years to
document all of this stuff much better, and recently in groff git[1]
I've split out a groff_man_style(7) page.  The latter is (as near as
makes no difference) a strict superset of the former.

Michael's site has a fairly recent snapshot of these pages:
  https://man7.org/linux/man-pages/man7/groff_man.7.html
  https://man7.org/linux/man-pages/man7/groff_man_style.7.html

Feedback is welcome.  For the latter page, I still need to write my
grand introduction where I explain the real typesetting basics: filling,
adjusting, breaking, and how these all relate to hyphenation.

In my opinion, .in requests are never necessary in idiomatic,
well-written man pages and I'm happy to offer technical advice for how
to achieve the desired result without using them.

I'm also happy to prepare patches for man-pages documents implementing
my recommendations.  :)

Regards,
Branden

[1] https://git.savannah.gnu.org/cgit/groff.git

[-- Attachment #1.2: membarrier.2.diff --]
[-- Type: text/x-diff, Size: 1063 bytes --]

Use .RS/.RE man macros instead of .in requests.

diff --git a/man2/membarrier.2 b/man2/membarrier.2
index f65c6be5c..526bb3819 100644
--- a/man2/membarrier.2
+++ b/man2/membarrier.2
@@ -60,11 +60,11 @@ The key idea is to replace, for these matching
 barriers, the fast-side memory barriers by simple compiler barriers,
 for example:
 .PP
-.in +4n
+.RS 4
 .EX
 asm volatile ("" : : : "memory")
 .EE
-.in
+.RE
 .PP
 and replace the slow-side memory barriers by calls to
 .BR membarrier ().
@@ -285,7 +285,7 @@ very frequently, and where "slow_path()" is executed infrequently, the
 following code (x86) can be transformed using
 .BR membarrier ():
 .PP
-.in +4n
+.RS
 .EX
 #include <stdlib.h>
 
@@ -332,13 +332,13 @@ main(int argc, char **argv)
     exit(EXIT_SUCCESS);
 }
 .EE
-.in
+.RE
 .PP
 The code above transformed to use
 .BR membarrier ()
 becomes:
 .PP
-.in +4n
+.RS
 .EX
 #define _GNU_SOURCE
 #include <stdlib.h>
@@ -421,4 +421,4 @@ main(int argc, char **argv)
     exit(EXIT_SUCCESS);
 }
 .EE
-.in
+.RE

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on

[Michael Kerrisk (man-pages)]

Hi Branden,

On 9/21/20 4:15 PM, G. Branden Robinson wrote:
> At 2020-09-21T09:49:11+0200, Michael Kerrisk (man-pages) wrote:
>> On Mon, 21 Sep 2020 at 09:32, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
>>> Indentation of structure definitions, shell session logs, and so on
>>>
>>> When  structure definitions, shell session logs, and so on are included
>>> in running text, indent them by 4 spaces (i.e.,  a  block  enclosed  by
>>> .in +4n and .in), format them using the .EX and EE macros, and surround
>>> them with suitable paragraph markers (either .PP or .IP).  For example:
>>>
>>>                 .PP
>>>                 .in +4n
>>>                 .EX
>>>                 int
>>>                 main(int argc, char *argv[])
>>>                 {
>>>                     return 0;
>>>                 }
>>>                 .EE
>>>                 .in
>>>                 .PP
>>>
>>>
>>> That could be simplified to the following, right?:
>>>
>>>                 .IP
>>>                 .EX
>>>                 int
>>>                 main(int argc, char *argv[])
>>>                 {
>>>                     return 0;
>>>                 }
>>>                 .EE
>>>                 .PP
>>>
>>> Or is there any difference?
>>
>> .IP indents by 8 spaces by default, I think.
> 
> 7 "ens" on nroff devices (like terminals), 7.2n on troff devices.

D'oh, yes. 7!

> An "en" is a traditional typesetting unit of measure, the width of a
> letter "n" in the font being used.  For monospaced fonts, including
> those used in character-cell terminals--barring the employment of CJK
> "fullwidth" code points--this is the same width as a space.
> 
>> Also, .IP won't indent further, if we are already in an area of
>> indented paragraphs.
> 
> This is true.  In my maintenance work on groff's man pages I have
> devised an idiom of calling .RS twice, putting in the desired material,
> and then calling .RE twice.
> 
> In membarrier(2), however, life is simple because no code examples are
> being nested inside an indented paragraph (.IP).  I'm attaching a patch;
> it produces no visible difference in output, not even white space
> changes.
> 
> I should add that my suggestion is to _not_ specify precise indentation
> amounts in man pages, as this is a presentation matter and readers may
> prefer tighter or more generous indentation, which they can control via
> the IN register; that is, passing -rIN to the groff command.  (Or, more
> likely, by configuring it in their man.local file so all pages that
> respect the user's wishes are consistent.)
> 
> I've been improving the groff_man(7) page over the past few years to
> document all of this stuff much better, and recently in groff git[1]
> I've split out a groff_man_style(7) page.  The latter is (as near as
> makes no difference) a strict superset of the former.
> 
> Michael's site has a fairly recent snapshot of these pages:
>   https://man7.org/linux/man-pages/man7/groff_man.7.html
>   https://man7.org/linux/man-pages/man7/groff_man_style.7.html
> 
> Feedback is welcome.  For the latter page, I still need to write my
> grand introduction where I explain the real typesetting basics: filling,
> adjusting, breaking, and how these all relate to hyphenation.
> 
> In my opinion, .in requests are never necessary in idiomatic,
> well-written man pages and I'm happy to offer technical advice for how
> to achieve the desired result without using them.

So, I don't disagree with you. (And as ever, thank you for your
detailed input.) The pattern I use above (with ".in +4n/.in" was a
hack that I cam up with to get code blocks with a "suitable"
indent. Your suggestion of ".RS 4/.RE" (in your patch, which I've
quoted inline below), does seem better. I'm not averse to changing
things. But, there is a related question. I use a similar hack in
the SYNOPSIS of many pages (e.g., chmod.2), to undent a single
line:

[[
.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
.PP
]]

Presumably, that could be replaced with ".RS -4/.RE", but is
there something even better?

Thanks,

Michael
> 
> I'm also happy to prepare patches for man-pages documents implementing
> my recommendations.  :)
> 
> Regards,
> Branden
> 
> [1] https://git.savannah.gnu.org/cgit/groff.git
> 

======

Use .RS/.RE man macros instead of .in requests.

diff --git a/man2/membarrier.2 b/man2/membarrier.2
index f65c6be5c..526bb3819 100644
--- a/man2/membarrier.2
+++ b/man2/membarrier.2
@@ -60,11 +60,11 @@ The key idea is to replace, for these matching
 barriers, the fast-side memory barriers by simple compiler barriers,
 for example:
 .PP
-.in +4n
+.RS 4
 .EX
 asm volatile ("" : : : "memory")
 .EE
-.in
+.RE
 .PP
 and replace the slow-side memory barriers by calls to
 .BR membarrier ().
@@ -285,7 +285,7 @@ very frequently, and where "slow_path()" is executed infrequently, the
 following code (x86) can be transformed using
 .BR membarrier ():
 .PP
-.in +4n
+.RS
 .EX
 #include <stdlib.h>
 
@@ -332,13 +332,13 @@ main(int argc, char **argv)
     exit(EXIT_SUCCESS);
 }
 .EE
-.in
+.RE
 .PP
 The code above transformed to use
 .BR membarrier ()
 becomes:
 .PP
-.in +4n
+.RS
 .EX
 #define _GNU_SOURCE
 #include <stdlib.h>
@@ -421,4 +421,4 @@ main(int argc, char **argv)
     exit(EXIT_SUCCESS);
 }
 .EE
-.in
+.RE

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

Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2524 bytes --]

At 2020-09-24T10:15:31+0200, Michael Kerrisk (man-pages) wrote:
> On 9/21/20 4:15 PM, G. Branden Robinson wrote:
[much snippage]
> > In my opinion, .in requests are never necessary in idiomatic,
> > well-written man pages and I'm happy to offer technical advice for
> > how to achieve the desired result without using them.
> 
> So, I don't disagree with you. (And as ever, thank you for your
> detailed input.) The pattern I use above (with ".in +4n/.in" was a
> hack that I cam up with to get code blocks with a "suitable"
> indent. Your suggestion of ".RS 4/.RE" (in your patch, which I've
> quoted inline below), does seem better. I'm not averse to changing
> things. But, there is a related question. I use a similar hack in
> the SYNOPSIS of many pages (e.g., chmod.2), to undent a single
> line:
> 
> [[
> .PP
> .in -4n
> Feature Test Macro Requirements for glibc (see
> .BR feature_test_macros (7)):
> .in
> .PP
> ]]
> 
> Presumably, that could be replaced with ".RS -4/.RE", but is
> there something even better?

You're correct; .RS honors a negative indentation argument.  So you
could do this and I would consider it an improvement because it reduces
the number of lexemes that man page readers--human and machine
alike--have to comprehend.

I noticed something about "Feature Test Macro Requirements for glibc",
however...

Because of the negative indent, it's within one en of the indentation of
a subsection (.SS) heading; in fact it's an exact match on nroff devices
(terminals).  I'm guessing that wasn't an accident.  You're even already
title-casing it like a heading.

If you used .SS, it look much the same but end up in bold.

Admittedly the parenthetical man page cross-reference fits poorly with a
subsection heading, in part because the font style change would be
obscured.  However, I think that could be moved to the _end_ of the
synopsis with little loss.  It doesn't take seasoned readers of section
2 and 3 man-pages documents long to internalize this knowledge about
feature_test_macros(7), so repeating it by rote in the current
pseudo-heading may not be helping much.  Inexperienced readers need to
read closely anyway, and experienced ones already know this information.

I notice that in these feature test macro areas you're making heavy use
of .ad and .br requests, as well as the deprecated .PD macro to set the
inter-paragraph spacing to zero.  However, that's probably a digression
for another thread... :)

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on

[Michael Kerrisk (man-pages)]

On 9/27/20 8:03 AM, G. Branden Robinson wrote:
> At 2020-09-24T10:15:31+0200, Michael Kerrisk (man-pages) wrote:
>> On 9/21/20 4:15 PM, G. Branden Robinson wrote:
> [much snippage]
>>> In my opinion, .in requests are never necessary in idiomatic,
>>> well-written man pages and I'm happy to offer technical advice for
>>> how to achieve the desired result without using them.
>>
>> So, I don't disagree with you. (And as ever, thank you for your
>> detailed input.) The pattern I use above (with ".in +4n/.in" was a
>> hack that I cam up with to get code blocks with a "suitable"
>> indent. Your suggestion of ".RS 4/.RE" (in your patch, which I've
>> quoted inline below), does seem better. I'm not averse to changing
>> things. But, there is a related question. I use a similar hack in
>> the SYNOPSIS of many pages (e.g., chmod.2), to undent a single
>> line:
>>
>> [[
>> .PP
>> .in -4n
>> Feature Test Macro Requirements for glibc (see
>> .BR feature_test_macros (7)):
>> .in
>> .PP
>> ]]
>>
>> Presumably, that could be replaced with ".RS -4/.RE", but is
>> there something even better?
> 
> You're correct; .RS honors a negative indentation argument.  So you
> could do this and I would consider it an improvement because it reduces
> the number of lexemes that man page readers--human and machine
> alike--have to comprehend.

I've done it.

> 
> I noticed something about "Feature Test Macro Requirements for glibc",
> however...
> 
> Because of the negative indent, it's within one en of the indentation of
> a subsection (.SS) heading; in fact it's an exact match on nroff devices
> (terminals).  I'm guessing that wasn't an accident.  You're even already
> title-casing it like a heading.
> 
> If you used .SS, it look much the same but end up in bold.
> 
> Admittedly the parenthetical man page cross-reference fits poorly with a
> subsection heading, in part because the font style change would be
> obscured.  

(Yes, I'm not so keen on that.)

> However, I think that could be moved to the _end_ of the
> synopsis with little loss.  It doesn't take seasoned readers of section
> 2 and 3 man-pages documents long to internalize this knowledge about
> feature_test_macros(7), so repeating it by rote in the current
> pseudo-heading may not be helping much.  Inexperienced readers need to
> read closely anyway, and experienced ones already know this information.

Possibly you are right, but that's a bigger global edit that I 
won't attempt for now.

> I notice that in these feature test macro areas you're making heavy use
> of .ad and .br requests, as well as the deprecated .PD macro to set the
> inter-paragraph spacing to zero.  However, that's probably a digression
> for another thread... :)

I think the words you were looking for are "disgusting hack" :-).
Feel free to start another thread...

Thanks,

Michael

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

Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on

[Michael Kerrisk (man-pages)]

Hi Branden,

I want to circle back to a point you raised...

On 9/21/20 4:15 PM, G. Branden Robinson wrote:
> At 2020-09-21T09:49:11+0200, Michael Kerrisk (man-pages) wrote:
>> On Mon, 21 Sep 2020 at 09:32, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
>>> Indentation of structure definitions, shell session logs, and so on
>>>
>>> When  structure definitions, shell session logs, and so on are included
>>> in running text, indent them by 4 spaces (i.e.,  a  block  enclosed  by
>>> .in +4n and .in), format them using the .EX and EE macros, and surround
>>> them with suitable paragraph markers (either .PP or .IP).  For example:
>>>
>>>                 .PP
>>>                 .in +4n
>>>                 .EX
>>>                 int
>>>                 main(int argc, char *argv[])
>>>                 {
>>>                     return 0;
>>>                 }
>>>                 .EE
>>>                 .in
>>>                 .PP
>>>
>>>
>>> That could be simplified to the following, right?:
>>>
>>>                 .IP
>>>                 .EX
>>>                 int
>>>                 main(int argc, char *argv[])
>>>                 {
>>>                     return 0;
>>>                 }
>>>                 .EE
>>>                 .PP
>>>
>>> Or is there any difference?
>>
>> .IP indents by 8 spaces by default, I think.
> 
> 7 "ens" on nroff devices (like terminals), 7.2n on troff devices.
> 
> An "en" is a traditional typesetting unit of measure, the width of a
> letter "n" in the font being used.  For monospaced fonts, including
> those used in character-cell terminals--barring the employment of CJK
> "fullwidth" code points--this is the same width as a space.
> 
>> Also, .IP won't indent further, if we are already in an area of
>> indented paragraphs.
> 
> This is true.  In my maintenance work on groff's man pages I have
> devised an idiom of calling .RS twice, putting in the desired material,
> and then calling .RE twice.

If I understand what you are saying, then iif we are at an indented
level (.TP, .IP), then we can use your idiom:

.RS
.RS n
...
.RE
.RE


But, this idiom won't work if we're not at an indented level (?).
In other words, at .PP level we should not use .RS/.RS n/.RE/.RE, 
right?

By contrast, ".in +n/.in" works regardless of whether we 
are at an indented level, right? (I'm not saying this recommend
the use of .in; I just want to clarify my understanding.)

Thanks,

Michael

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

Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1912 bytes --]

At 2020-09-29T22:15:18+0200, Michael Kerrisk (man-pages) wrote:
> Hi Branden,
> 
> I want to circle back to a point you raised...
> If I understand what you are saying, then iif we are at an indented
> level (.TP, .IP), then we can use your idiom:
> 
> .RS
> .RS n
> ...
> .RE
> .RE
> 
> 
> But, this idiom won't work if we're not at an indented level (?).
> In other words, at .PP level we should not use .RS/.RS n/.RE/.RE, 
> right?

Not true.  You can use .RS/.RE "almost everywhere", as topologists say.

> By contrast, ".in +n/.in" works regardless of whether we 
> are at an indented level, right? (I'm not saying this recommend
> the use of .in; I just want to clarify my understanding.)

.RS and .RE are wrappers around .in.  .RS applies a default indentation
if one is not given, and in any case stores the indentation amount in a
register named for the indentation "level" (roughly[2], how many times
you've called .RS since the last .SH or .SS).  That way you can call .RE
without arguments, or as ".RE 2" to say "go back two indentation levels"
without having to track or remember any indentation measurements.

Does this help?  If you can think of any place in groff_man(7) or
groff_man_style(7) I can make this clearer, please tell me.  Until today
the only two "FAQ"s I had in (what is now) the style page dealt with
relative insets.

And you're not alone in misunderstanding .RS/.RE.  My frustration
with it back in August 2017 it is a major part of what sucked me into
the groff project in the first place[1].

Regards,
Branden

[1] I wouldn't try it inside one of the macros that uses an "input
    trap".  I don't think it would occur to most people to even try, so
    I'll save my experiments for _after_ I've sent this mail.  :)
[2] .RS and .RE work like nested parentheses.
[3] https://lists.gnu.org/archive/html/groff/2017-08/msg00028.html

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 599 bytes --]

At 2020-09-30T22:02:43+1000, G. Branden Robinson wrote:
> [...] you can call .RE [...] as ".RE 2" to say "go back two
> indentation levels"

Nope, that's wrong.  Forget I said that; I think I might now see
something I can further improve in the documentation.

You can see I'm still bedeviled by relative insets.  :-|

I tend to never use the argument to .RE; I just call .RE multiple times
to balance out my .RS calls, just like parentheses.  When I do that, I
don't get surprised.

> without having to track or remember any indentation measurements.

This part remains true.  :)

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on

[Michael Kerrisk (man-pages)]

Hi Branden,

Sorry -- I think I'm still not getting it.

On Wed, 30 Sep 2020 at 14:54, G. Branden Robinson
<g.branden.robinson@gmail.com> wrote:
>
> At 2020-09-30T22:02:43+1000, G. Branden Robinson wrote:
> > [...] you can call .RE [...] as ".RE 2" to say "go back two
> > indentation levels"
>
> Nope, that's wrong.  Forget I said that; I think I might now see
> something I can further improve in the documentation.
>
> You can see I'm still bedeviled by relative insets.  :-|
>
> I tend to never use the argument to .RE; I just call .RE multiple times
> to balance out my .RS calls, just like parentheses.  When I do that, I
> don't get surprised.
>
> > without having to track or remember any indentation measurements.
>
> This part remains true.  :)

Currently, I use the idiom

.PP
.in +4n
.EX
<code>
.EE
.in
.PP

or, if we're in indented paragraph territory:

.IP
.in +4n
.EX
<code>
.EE
.in
.IP

This is of course hacky, and of course in order to get it right, I
need to know where to use .IP vs .PP.

I'd happily replace this with the use of ".RS 4/.EX/.EE/.RE", but
what, if anything do I surround it with? And can I do it in a way that
I don't need to care whether I'm currently in an indented zone of
text?

I mean, if I use:

.RS
.RS 4
.PP
.EX
int
main(void)
{
    printf("Hello world\n");
}
.EE
.PP
.RE
.RE

That produces the desired results (4-space indent) if I am currently
in an indented zone (.TP or .IP). (But it starts to get even more
horribly verbose, in terms of markup, than what I currently use.)

But if I use that same form in an unindented zone, then <code> is
massively (12 spaces) indented. Instead, seem to need to say just:

.RS +4
.PP
.EX
int
main(void)
{
    printf("Hello world\n");
}
.EE
.PP
.RE

What I'd *ideally* like is a solution for indented code blocks that
(in order or priority):

1) is not more verbose than the current solution
2) uses more idiomatic mark-up than the current solution
3) uses exactly the same form, regardless of whether I'm currently in
an indented region of text.

So far, I don't see such a solution.

Thanks,

Michael

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

Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on

[Michael Kerrisk (man-pages)]

Hi Brnaden,

A ping on the below, in case you have some thoughts.

Thanks,

Michael

On Thu, 1 Oct 2020 at 09:33, Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
>
> Hi Branden,
>
> Sorry -- I think I'm still not getting it.
>
> On Wed, 30 Sep 2020 at 14:54, G. Branden Robinson
> <g.branden.robinson@gmail.com> wrote:
> >
> > At 2020-09-30T22:02:43+1000, G. Branden Robinson wrote:
> > > [...] you can call .RE [...] as ".RE 2" to say "go back two
> > > indentation levels"
> >
> > Nope, that's wrong.  Forget I said that; I think I might now see
> > something I can further improve in the documentation.
> >
> > You can see I'm still bedeviled by relative insets.  :-|
> >
> > I tend to never use the argument to .RE; I just call .RE multiple times
> > to balance out my .RS calls, just like parentheses.  When I do that, I
> > don't get surprised.
> >
> > > without having to track or remember any indentation measurements.
> >
> > This part remains true.  :)
>
> Currently, I use the idiom
>
> .PP
> .in +4n
> .EX
> <code>
> .EE
> .in
> .PP
>
> or, if we're in indented paragraph territory:
>
> .IP
> .in +4n
> .EX
> <code>
> .EE
> .in
> .IP
>
> This is of course hacky, and of course in order to get it right, I
> need to know where to use .IP vs .PP.
>
> I'd happily replace this with the use of ".RS 4/.EX/.EE/.RE", but
> what, if anything do I surround it with? And can I do it in a way that
> I don't need to care whether I'm currently in an indented zone of
> text?
>
> I mean, if I use:
>
> .RS
> .RS 4
> .PP
> .EX
> int
> main(void)
> {
>     printf("Hello world\n");
> }
> .EE
> .PP
> .RE
> .RE
>
> That produces the desired results (4-space indent) if I am currently
> in an indented zone (.TP or .IP). (But it starts to get even more
> horribly verbose, in terms of markup, than what I currently use.)
>
> But if I use that same form in an unindented zone, then <code> is
> massively (12 spaces) indented. Instead, seem to need to say just:
>
> .RS +4
> .PP
> .EX
> int
> main(void)
> {
>     printf("Hello world\n");
> }
> .EE
> .PP
> .RE
>
> What I'd *ideally* like is a solution for indented code blocks that
> (in order or priority):
>
> 1) is not more verbose than the current solution
> 2) uses more idiomatic mark-up than the current solution
> 3) uses exactly the same form, regardless of whether I'm currently in
> an indented region of text.
>
> So far, I don't see such a solution.
>
> Thanks,
>
> Michael
>
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/



-- 
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