Skip to contentSkip to conversation

system_data_types.7: Add 'fexcept_t'

PATCH Superseded Alejandro Colomar 2 participants 11 messages Sep 22, 2020 – Sep 23, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/2 system_data_types.7: Add 'fexcept_t'

Note: I used this commit to fix the comment that separates with gid_t.

It wasn't aligned with the rest (col 72).

---

Hi Michael,

Would you prefer a separate patch for the cosmetic change? I put it in the same one, as it was in an adjacent line, and the diff looks good; to avoid noise in the log. But maybe a separate commit is better.

Thanks,

Alex

 man7/system_data_types.7 | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)
man7/system_data_types.7 +23 -1
index 59c64fb89..97411a193 100644
@@ -111,7 +111,29 @@ Conforming to: C99 and later; POSIX.1-2001 and later.
 .IP
 See also:
 .BR fenv (3)
-.\"------------------------------------- gid_t ----------------------/
+.\"------------------------------------- fexcept_t --------------------/
+.TP
+.I fexcept_t
+.IP
+Include:
+.IR <fenv.h> .
+.IP
+Represents the floating-point status flags collectively,
+including any status the implementation associates with the flags.
+A floating-point status flag is a system variable
+whose value is set (but never cleared)
+when a floating-point exception is raised,
+which occurs as a side-effect of
+exceptional floating-point arithmetic to provide auxiliary information.
+A floating-point control mode is a system variable whose
+value may be set by the user to affect
+the subsequent behavior of floating-point arithmetic.
+.IP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR fenv (3)
+.\"------------------------------------- gid_t ------------------------/
 .TP
 .I gid_t
 .IP
Signature · 1 line
2.28.0
#1 lore raw

PATCH 2/2 fexcept_t.3: New link to system_data_types(7)

---
 man3/fexcept_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/fexcept_t.3
man3/fexcept_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
Signature · 1 line
2.28.0
#2 lore raw

PATCH v2 1/2 system_data_types.7: Add 'fexcept_t'

---

Hi Michael,

Quoted 3 lines · Michael Kerrisk (man-pages)

[Thorsten, I have removed you from the CC because I get persistent bounce messages whenever I send you mail. Hopefully you see this reply via the list.]

Me too :(

Quoted 6 lines

While I'm pretty sure they would allow this without problem, I'm wondering if it's worth the effort. Ideally, we'd have text written by someone in their own words. Reproducing the text of the standard has limited value, since people can in any case consult the standard directly.

Quoted 6 lines

Alex, how about we just go much simpler, saying something like:

[[
This type represents floating-point status flags; for further details see fenv(3).
]]

Nice and simple.

Thanks,

Alex

 man7/system_data_types.7 | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)
man7/system_data_types.7 +16 -1
index 4352d6a6e..ea3e25175 100644
@@ -110,7 +110,22 @@ Conforming to: C99 and later; POSIX.1-2001 and later.
 .IP
 See also:
 .BR fenv (3)
-.\"------------------------------------- gid_t ----------------------/
+.\"------------------------------------- fexcept_t --------------------/
+.TP
+.I fexcept_t
+.IP
+Include:
+.IR <fenv.h> .
+.IP
+This type represents the floating-point status flags collectively;
+for further details see
+.BR fenv (3).
+.IP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR fenv (3)
+.\"------------------------------------- gid_t ------------------------/
 .TP
 .I gid_t
 .IP
Signature · 1 line
2.28.0
#3 lore raw

Hi Alex,

Quoted 25 lines · Alejandro Colomar

---

Hi Michael,

Quoted 3 lines · Michael Kerrisk (man-pages)

[Thorsten, I have removed you from the CC because I get persistent bounce messages whenever I send you mail. Hopefully you see this reply via the list.]

Me too :(

Quoted 6 lines

While I'm pretty sure they would allow this without problem, I'm wondering if it's worth the effort. Ideally, we'd have text written by someone in their own words. Reproducing the text of the standard has limited value, since people can in any case consult the standard directly.

Quoted 6 lines

Alex, how about we just go much simpler, saying something like:

[[
This type represents floating-point status flags; for further details see fenv(3).
]]

Quoted 5 lines

Nice and simple.

Thanks,

Alex

Thanks! Patch applied.

Cheers,

Michael

Quoted 32 lines
 man7/system_data_types.7 | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)
man7/system_data_types.7 +16 -1
index 4352d6a6e..ea3e25175 100644
@@ -110,7 +110,22 @@ Conforming to: C99 and later; POSIX.1-2001 and later.
 .IP
 See also:
 .BR fenv (3)
-.\"------------------------------------- gid_t ----------------------/
+.\"------------------------------------- fexcept_t --------------------/
+.TP
+.I fexcept_t
+.IP
+Include:
+.IR <fenv.h> .
+.IP
+This type represents the floating-point status flags collectively;
+for further details see
+.BR fenv (3).
+.IP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR fenv (3)
+.\"------------------------------------- gid_t ------------------------/
 .TP
 .I gid_t
 .IP
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#5 lore raw

Re: [PATCH v2 2/2] fexcept_t.3: New link to system_data_types(7)

Quoted 1 line · Alejandro Colomar

Thanks, Alex. Patch applied.

Cheers,

Michael

Quoted 13 lines
---
 man3/fexcept_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/fexcept_t.3
man3/fexcept_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#6 lore raw
In reply to Alejandro Colomar

Hi Alex,

Quoted 3 lines · Alejandro Colomar

Note: I used this commit to fix the comment that separates with gid_t.

It wasn't aligned with the rest (col 72).

That's fine.

Quoted 10 lines

---

Hi Michael,

Would you prefer a separate patch for the cosmetic change? I put it in the same one, as it was in an adjacent line, and the diff looks good; to avoid noise in the log. But maybe a separate commit is better.

(It's fine as is.)

Quoted 21 lines

Thanks,

Alex

 man7/system_data_types.7 | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)
man7/system_data_types.7 +4 -1
index 59c64fb89..97411a193 100644
@@ -111,7 +111,29 @@ Conforming to: C99 and later; POSIX.1-2001 and later.
 .IP
 See also:
 .BR fenv (3)
-.\"------------------------------------- gid_t ----------------------/
+.\"------------------------------------- fexcept_t --------------------/
+.TP
+.I fexcept_t
+.IP

man7/system_data_types.7 Conforming to: C99 and later; POSIX.1-2001 and later. · line 127

Quoted 10 lines
man7/system_data_types.7 +10 -0
+Include:
+.IR <fenv.h> .
+.IP
+Represents the floating-point status flags collectively,
+including any status the implementation associates with the flags.
+A floating-point status flag is a system variable
+whose value is set (but never cleared)
+when a floating-point exception is raised,
+which occurs as a side-effect of
+exceptional floating-point arithmetic to provide auxiliary information.

The previous sentence is rather hard to parse. What (other) part of the sentence does "to provide auxiliary information" relate to. I suggest splitting the sentence in two and rewording.

man7/system_data_types.7 Conforming to: C99 and later; POSIX.1-2001 and later. · line 128

Quoted 1 line
man7/system_data_types.7 +1 -0
+A floating-point control mode is a system variable whose

You suddenly introduce "floating-point control mode" here. How does it relate to the preceding sentences? It's not clear.

Going off to look at the standard... I see that actually your sentences come pretty much straight from the standard. So, first, I think the standard could have been clearer here. Second, and more important, (for copyright reasons) we are on shaky ground if we just lift whole passages from the standard. The text does really need to be in your own words. Can you come up with something?

Alternatively, I guess we could explicitly quote the standard. Something like

    POSIX describes this type as follows:
    .RS
    .PP
    [The text]
    .RE

man7/system_data_types.7 Conforming to: C99 and later; POSIX.1-2001 and later. · line 139

Quoted 12 lines
man7/system_data_types.7 +8 -0
+value may be set by the user to affect
+the subsequent behavior of floating-point arithmetic.
+.IP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR fenv (3)
+.\"------------------------------------- gid_t ------------------------/
 .TP
 .I gid_t
 .IP

Thanks,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#7 lore raw

Hi Michael,

Quoted 20 lines · Michael Kerrisk (man-pages)

The previous sentence is rather hard to parse. What (other) part of the sentence does "to provide auxiliary information" relate to. I suggest splitting the sentence in two and rewording.

Quoted 1 line

+A floating-point control mode is a system variable whose

You suddenly introduce "floating-point control mode" here. How does it relate to the preceding sentences? It's not clear.

Going off to look at the standard... I see that actually your sentences come pretty much straight from the standard. So, first, I think the standard could have been clearer here. Second, and more important, (for copyright reasons) we are on shaky ground if we just lift whole passages from the standard. The text does really need to be in your own words. Can you come up with something?> Alternatively, I guess we could explicitly quote the standard. Something like

Quoted 5 lines
     POSIX describes this type as follows:
     .RS
     .PP
     [The text]
     .RE

Yes. A few patches ago I asked about that,
but you didn't answer to that specifically,
so I guessed that it was just fair use:

https://lore.kernel.org/linux-man/[email protected]/T/#mbfdcaf4fe625b4ff7ea90dc7396005fda1283612

But I guess explicitly quoting POSIX would be easy and better, as you proposed.

I never used that type, so I wouldn't dare to describe it in my own words.

Thanks,

Alex

#8 lore raw
Quoted 23 lines · Alejandro Colomar

Hi Michael,

Quoted 20 lines · Michael Kerrisk (man-pages)

The previous sentence is rather hard to parse. What (other) part of the sentence does "to provide auxiliary information" relate to. I suggest splitting the sentence in two and rewording.

Quoted 1 line

+A floating-point control mode is a system variable whose

You suddenly introduce "floating-point control mode" here. How does it relate to the preceding sentences? It's not clear.

Going off to look at the standard... I see that actually your sentences come pretty much straight from the standard. So, first, I think the standard could have been clearer here. Second, and more important, (for copyright reasons) we are on shaky ground if we just lift whole passages from the standard. The text does really need to be in your own words. Can you come up with something?> Alternatively, I guess we could explicitly quote the standard. Something like

Quoted 7 lines
Quoted 5 lines
     POSIX describes this type as follows:
     .RS
     .PP
     [The text]
     .RE

Yes. A few patches ago I asked about that,

Sorry -- there was so much mail from you that I missed it!

Quoted 4 lines

but you didn't answer to that specifically,
so I guessed that it was just fair use:

https://lore.kernel.org/linux-man/[email protected]/T/#mbfdcaf4fe625b4ff7ea90dc7396005fda1283612

Thanks for the pointer.

Quoted 2 lines

But I guess explicitly quoting POSIX would be easy and better, as you proposed.

Yes, I think it''s simplest. (And a patch for 'fenv_t' may be a good idea here as well.)

Quoted 1 line

I never used that type, so I wouldn't dare to describe it in my own words.

Okay.

Thanks,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#9 lore raw

Actually, POSIX already ripped (part of) the description from the C standard:

Quoted 2 lines

Represents the floating-point status flags collectively, including any status the implementation associates with the flags.

This part is in the C standard (and POSIX also has it).

Quoted 8 lines

A floating-point status flag is a system variable
whose value is set (but never cleared)
when a floating-point exception is raised,
which occurs as a side-effect of
exceptional floating-point arithmetic to provide auxiliary information. A floating-point control mode is a system variable whose value may be set by the user to affect
the subsequent behavior of floating-point arithmetic.

And this is from POSIX only.

How would you go about it?

Quoted 2 lines

Represents the floating-point status flags collectively, including any status the implementation associates with the flags.

POSIX describes a

Quoted 5 lines

[s/A//] floating-point status flag [s/is/as] a system variable whose value is set (but never cleared)
when a floating-point exception is raised,
which occurs as a side-effect of
exceptional floating-point arithmetic to provide auxiliary information.

According to POSIX,

Quoted 3 lines

[s/A/a/] floating-point control mode is a system variable whose value may be set by the user to affect
the subsequent behavior of floating-point arithmetic.

Like this?

Thanks,

Alex

Quoted 56 lines · Michael Kerrisk (man-pages)
Quoted 23 lines · Alejandro Colomar

Hi Michael,

Quoted 20 lines · Michael Kerrisk (man-pages)

The previous sentence is rather hard to parse. What (other) part of the sentence does "to provide auxiliary information" relate to. I suggest splitting the sentence in two and rewording.

Quoted 1 line

+A floating-point control mode is a system variable whose

You suddenly introduce "floating-point control mode" here. How does it relate to the preceding sentences? It's not clear.

Going off to look at the standard... I see that actually your sentences come pretty much straight from the standard. So, first, I think the standard could have been clearer here. Second, and more important, (for copyright reasons) we are on shaky ground if we just lift whole passages from the standard. The text does really need to be in your own words. Can you come up with something?> Alternatively, I guess we could explicitly quote the standard. Something like

Quoted 7 lines
Quoted 5 lines
     POSIX describes this type as follows:
     .RS
     .PP
     [The text]
     .RE

Yes. A few patches ago I asked about that,

Sorry -- there was so much mail from you that I missed it!

Quoted 4 lines

but you didn't answer to that specifically,
so I guessed that it was just fair use:

https://lore.kernel.org/linux-man/[email protected]/T/#mbfdcaf4fe625b4ff7ea90dc7396005fda1283612

Thanks for the pointer.

Quoted 2 lines

But I guess explicitly quoting POSIX would be easy and better, as you proposed.

Yes, I think it''s simplest. (And a patch for 'fenv_t' may be a good idea here as well.)

Quoted 1 line

I never used that type, so I wouldn't dare to describe it in my own words.

Okay.

Thanks,

Michael

#10 lore raw
Quoted 7 lines · Alejandro Colomar

Actually, POSIX already ripped (part of) the description from the C standard:

Quoted 2 lines

Represents the floating-point status flags collectively, including any status the implementation associates with the flags.

This part is in the C standard (and POSIX also has it).

I think they probably have an agreement for this :-).

Quoted 9 lines
Quoted 8 lines

A floating-point status flag is a system variable
whose value is set (but never cleared)
when a floating-point exception is raised,
which occurs as a side-effect of
exceptional floating-point arithmetic to provide auxiliary information. A floating-point control mode is a system variable whose value may be set by the user to affect
the subsequent behavior of floating-point arithmetic.

Quoted 3 lines

And this is from POSIX only.

How would you go about it?

Just quote POSIX (no need to mention the C standard when quoting, I think).

Quoted 12 lines
Quoted 2 lines

Represents the floating-point status flags collectively, including any status the implementation associates with the flags.

POSIX describes a

Quoted 5 lines

[s/A//] floating-point status flag [s/is/as] a system variable whose value is set (but never cleared)
when a floating-point exception is raised,
which occurs as a side-effect of
exceptional floating-point arithmetic to provide auxiliary information.

According to POSIX,

Quoted 3 lines

[s/A/a/] floating-point control mode is a system variable whose value may be set by the user to affect
the subsequent behavior of floating-point arithmetic.

I think so.

Thanks,

Michael

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