Issue in man page fma.3

Issue in man page fma.3

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    According to above, a domain error also occurs when I<z> is a NaN?

"Domain error: \\f[I]x * y + z\\fR, or \\f[I]x * y\\fR is invalid and \\f[I]z\\fR is not a NaN"

"Domain error: I<x> * I<y> + I<z>, or I<x> * I<y> is invalid and I<z> is not a NaN"

Re: Issue in man page fma.3

[Alejandro Colomar]

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

Hi Helge,

On Sun, Aug 24, 2025 at 02:48:39PM +0000, Helge Kreutzmann wrote:
> Without further ado, the following was found:
> 
> Issue:    According to above, a domain error also occurs when I<z> is a NaN?

According to what exactly?  I don't understand this report.


Have a lovely day!
Alex

> "Domain error: \\f[I]x * y + z\\fR, or \\f[I]x * y\\fR is invalid and \\f[I]z\\fR is not a NaN"
> 
> "Domain error: I<x> * I<y> + I<z>, or I<x> * I<y> is invalid and I<z> is not a NaN"

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

Re: Issue in man page fma.3

[Adam Sampson]

Alejandro Colomar <alx@kernel.org> writes:

>> Issue:    According to above, a domain error also occurs when I<z> is a NaN?
> According to what exactly?  I don't understand this report.

fma.3's RETURN VALUE section currently says:

| If one of x or y is an infinity, the other is 0, and z is not a NaN, a
| domain error occurs, and a NaN is returned.
|
| If one of x or y is an infinity, and the other is 0, and z is a NaN, a
| domain error occurs, and a NaN is returned.

But the ERRORS section only says a domain error occurs in the first
case. If I'm understanding the glibc code for _FP_FMA in
soft-fp/op-common.h correctly, it looks like it raises the error
regardless of the value of z, so in both sections the "and z is ..."
part could be removed, making the two sentences above identical?

-- 
Adam Sampson <ats@offog.org>                         <http://offog.org/>

Re: Issue in man page fma.3

[Alejandro Colomar]

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

Hi Adam,

On Mon, Sep 01, 2025 at 04:06:34PM +0100, Adam Sampson wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> 
> >> Issue:    According to above, a domain error also occurs when I<z> is a NaN?
> > According to what exactly?  I don't understand this report.
> 
> fma.3's RETURN VALUE section currently says:
> 
> | If one of x or y is an infinity, the other is 0, and z is not a NaN, a
> | domain error occurs, and a NaN is returned.
> |
> | If one of x or y is an infinity, and the other is 0, and z is a NaN, a
> | domain error occurs, and a NaN is returned.
> 
> But the ERRORS section only says a domain error occurs in the first
> case. If I'm understanding the glibc code for _FP_FMA in
> soft-fp/op-common.h correctly, it looks like it raises the error
> regardless of the value of z, so in both sections the "and z is ..."
> part could be removed, making the two sentences above identical?

Ahh, now I see.  The source code of the manual page says:

	.P
	.\" POSIX.1-2008 allows some possible differences for the following two
	.\" domain error cases, but on Linux they are treated the same (AFAICS).
	.\" Nevertheless, we'll mirror POSIX.1 and describe the two cases
	.\" separately.
	If one of
	.I x
	or
	.I y
	is an infinity, the other is 0, and
	.I z
	is not a NaN,
	a domain error occurs, and
	a NaN is returned.
	.\" POSIX.1 says that a NaN or an implementation-defined value shall
	.\" be returned for this case.
	.P
	If one of
	.I x
	or
	.I y
	is an infinity, and the other is 0, and
	.I z
	is a NaN,
	.\" POSIX.1 makes the domain error optional for this case.
	a domain error occurs, and
	a NaN is returned.

I think I'll keep that separate, as a reminder that this is weird.  If
anyone shows that all implementations that one would care about behave
the same, it would be a case for going to POSIX and asking them to
simplify the specification.  (And we could also simplify it, of course.)

For now, how about this diff?

	diff --git i/man/man3/fma.3 w/man/man3/fma.3
	index fa0562858..433f1e2ee 100644
	--- i/man/man3/fma.3
	+++ w/man/man3/fma.3
	@@ -107,8 +107,8 @@ .SH ERRORS
	 .P
	 The following errors can occur:
	 .TP
	-Domain error: \f[I]x * y + z\f[], \
	-or \f[I]x * y\f[] is invalid and \f[I]z\f[] is not a NaN
	+Domain error: \f[I]x * y + z\f[] \
	+or \f[I]x * y\f[] is invalid.
	 .\" .I errno
	 .\" is set to
	 .\" .BR EDOM .

Which does this:

	$ diffman-git 
	--- HEAD:man/man3/fma.3
	+++ ./man/man3/fma.3
	@@ -58,8 +58,7 @@ ERRORS
	 
		The following errors can occur:
	 
	-       Domain error: x * y + z, or x * y is invalid and z is
	-       not a NaN
	+       Domain error: x * y + z or x * y is invalid.
		       An invalid floating-point exception (FE_IN‐
		       VALID) is raised.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

Issue in man page fma.3

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    According to above, a domain error also occurs when I<z> is a NaN?

"Domain error: I<x> * I<y> + I<z>, or I<x> * I<y> is invalid and I<z> is not a NaN"

Re: Issue in man page fma.3

[Alejandro Colomar]

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

Hi Helge,

On Wed, Dec 24, 2025 at 02:38:25PM +0000, Helge Kreutzmann wrote:
> Without further ado, the following was found:
> 
> Issue:    According to above, a domain error also occurs when I<z> is a NaN?
> 
> "Domain error: I<x> * I<y> + I<z>, or I<x> * I<y> is invalid and I<z> is not a NaN"

I think this was fixed in

	$ git show e86f9fd0c279f593242969a2fbb5ef379272d89d
	commit e86f9fd0c279f593242969a2fbb5ef379272d89d
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   Wed Sep 3 16:14:10 2025 +0200

	    man/man3/fma.3: ERRORS: Add missing error
	    
	    There's also a domain error if z is a NaN, so let's simplify wording.
	    See the comments in the source code, which remind that POSIX doesn't
	    mandate some of this, so this is GNU-specific.
	    
	    Reported-by: Helge Kreutzmann <debian@helgefjell.de>
	    Suggested-by: Adam Sampson <ats@offog.org>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

	diff --git a/man/man3/fma.3 b/man/man3/fma.3
	index fa0562858..433f1e2ee 100644
	--- a/man/man3/fma.3
	+++ b/man/man3/fma.3
	@@ -107,8 +107,8 @@ .SH ERRORS
	 .P
	 The following errors can occur:
	 .TP
	-Domain error: \f[I]x * y + z\f[], \
	-or \f[I]x * y\f[] is invalid and \f[I]z\f[] is not a NaN
	+Domain error: \f[I]x * y + z\f[] \
	+or \f[I]x * y\f[] is invalid.
	 .\" .I errno
	 .\" is set to
	 .\" .BR EDOM .

but please revise in case there's still anything that needs to be fixed.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

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

Re: Issue in man page fma.3

[Helge Kreutzmann]

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

Hello Alex,
Am Thu, Dec 25, 2025 at 02:29:08PM +0100 schrieb Alejandro Colomar:
> but please revise in case there's still anything that needs to be fixed.

Apologies, I missed to filter this out. It is fixed.

Greetings

         Helge

-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

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