Man page issues: logb, significand, cbrt, log2, log10, exp10

Man page issues: logb, significand, cbrt, log2, log10, exp10

[Morten Welinder]

I came across some minor issues in some math man pages.

M.



logb:
The formula "floor(log2(x))" should be "floor(log2(fabs(x)))".  (Or
...abs(...) if it's meant to be math and not C.)

significand:
The range [1,2) should be [1,FLT_RADIX)

cbrt:
The phrase "every representable real value has a representable real
cube root" is wrong.  In fact, a representable cube root is quite
rare.  This should be something like "every representable real value
has a real cube root and rounding it to a representable value never
causes overflow or underflow."

log2, log10:
These use, e.g., "base 2 logarithm".  Compare that to exp2's "base-2
exponential" (with a hyphen).  I am leaning towards the hyphenated
version being correct, but I am not a native English speaker.

exp10:
The man page probably should come with a warning not to use the
function for the time being.  The implementation is pretty bad.  For
example, results for integer arguments 3, 4, 7, 8, 9, and 17 are
needlessly inaccurate.  pow(10,x) is much better, but not perfect.

Re: Man page issues: logb, significand, cbrt, log2, log10, exp10

[Alejandro Colomar]

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

Hi Morten,

On Thu, Feb 29, 2024 at 07:28:10PM -0500, Morten Welinder wrote:
> I came across some minor issues in some math man pages.
> 
> M.

I'll reply to the others separately.

[...]

> exp10:
> The man page probably should come with a warning not to use the
> function for the time being.  The implementation is pretty bad.  For
> example, results for integer arguments 3, 4, 7, 8, 9, and 17 are
> needlessly inaccurate.


I can't reproduce that.

	alx@debian:~/tmp$ cat exp10.c 
	#define _GNU_SOURCE
	#include <math.h>
	#include <stdio.h>

	int
	main(void)
	{
		printf("exp10(17): %lf\n", exp10(17));
		printf("pow(10, 17): %lf\n", pow(10, 17));
	}
	alx@debian:~/tmp$ gcc -Wall -Wextra exp10.c -lm
	alx@debian:~/tmp$ ./a.out 
	exp10(17): 100000000000000000.000000
	pow(10, 17): 100000000000000000.000000

I'm running libc6 2.37-15.

> pow(10,x) is much better, but not perfect.


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

Re: Man page issues: logb, significand, cbrt, log2, log10, exp10

[Morten Welinder]

I think what happens is that the compiler (not glibc) computes that
exp10 for you and that the compiler happens to be more accurate.
Here's what I get for the loop:

  for (int i = 1; i < 20; i++) {
    printf ("%.20g\n", exp10 (i));
  }

welinder@CarbonX1:~$ ./a.out
10
100
1000.0000000000001137
10000.000000000001819
100000
1000000
9999999.9999999981374
99999999.999999985099
999999999.99999988079
10000000000
100000000000
1000000000000
10000000000000
100000000000000
1000000000000000
10000000000000000
99999999999999984
1000000000000000000
10000000000000000000

Here's the bug report to go with this:
https://sourceware.org/bugzilla/show_bug.cgi?id=28472
Note comment 6.  It is clearly not a high-priority item for glibc.

M.

Re: Man page issues: logb, significand, cbrt, log2, log10, exp10

[Alejandro Colomar]

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

[CC += glibc, and those involved in the glibc bug report]

Hi Morten,

On Sat, Mar 02, 2024 at 04:17:36PM -0500, Morten Welinder wrote:
> I think what happens is that the compiler (not glibc) computes that
> exp10 for you and that the compiler happens to be more accurate.
> Here's what I get for the loop:
> 
>   for (int i = 1; i < 20; i++) {
>     printf ("%.20g\n", exp10 (i));
>   }
> 
> welinder@CarbonX1:~$ ./a.out
> 10
> 100
> 1000.0000000000001137
> 10000.000000000001819
> 100000
> 1000000
> 9999999.9999999981374
> 99999999.999999985099
> 999999999.99999988079
> 10000000000
> 100000000000
> 1000000000000
> 10000000000000
> 100000000000000
> 1000000000000000
> 10000000000000000
> 99999999999999984
> 1000000000000000000
> 10000000000000000000
> 
> Here's the bug report to go with this:
> https://sourceware.org/bugzilla/show_bug.cgi?id=28472
> Note comment 6.  It is clearly not a high-priority item for glibc.

Thanks for that link.

I agree with glibc that the standard specifies that these functions need
not be precise.  That lost precission probably results in better
performance.  Most programs won't care that these functions are
inaccurate.

If you need a correctly-rounded version of these functions, which is
perfectly reasonable, the right thing to ask is that libc implements
the cr_ version of these functions.

I also understand that adding functions to glibc isn't straightforward,
so glibc maintainers have reasons to not do it at the moment.  In fact,
lately I've been leaning towards thinking that libc is a huge monster to
which nothing more should be added, at all.

How about writing a new library --maybe call it libm-cr, maybe
libm-cr-pow, maybe libm-cr-exp10, depending on how extensive you want
it-- and add cr_exp10(3) to that library?  You could do that, and just
support the systems you need to support.  The effort would be certainly
smaller than adding the function to glibc.

Regarding the manual pages, I don't remember from the top of my head if
there's any page documenting that libm functions are imprecise.  I would
prefer documenting it in one place, rather than adding caveats to every
libm page.

> 
> M.

Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

Re: Man page issues: logb, significand, cbrt, log2, log10, exp10

[Morten Welinder]

Thanks.

There is (was?) already crlibm out there.
https://core-math.gitlabpages.inria.fr/  No particular need for wheel
reinvention here.

FWIW, it appears that the author of the glibc exp10 implementation
agrees with me that the implementation is sub-standard:

https://codebrowser.dev/glibc/glibc/math/e_exp10.c.html

/* This is a very stupid and inprecise implementation. It'll get
replaced sometime (soon?). */
return __ieee754_exp (M_LN10 * arg);


Compare with musl:

https://github.com/rofl0r/musl/blob/master/src/math/exp10.c

Re: Man page issues: logb, significand, cbrt, log2, log10, exp10

[Alejandro Colomar]

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

Hi Morten,

On Sat, Mar 02, 2024 at 09:02:24PM -0500, Morten Welinder wrote:
> Thanks.
> 
> There is (was?) already crlibm out there.
> https://core-math.gitlabpages.inria.fr/  No particular need for wheel
> reinvention here.

crlibm doesn't seem to exist anymore.  Maybe just add some headers to
core-math, and package it as a standalone library.

> FWIW, it appears that the author of the glibc exp10 implementation
> agrees with me that the implementation is sub-standard:
> 
> https://codebrowser.dev/glibc/glibc/math/e_exp10.c.html
> 
> /* This is a very stupid and inprecise implementation. It'll get
> replaced sometime (soon?). */
> return __ieee754_exp (M_LN10 * arg);

Hmmm.  Still, it's simple.  If pow(10, x) is strictly better, maybe one
can prove it and send a patch.  Or for something better, it'll take more
work.


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

Re: Man page issues: logb, significand, cbrt, log2, log10, exp10

[Vincent Lefevre]

On 2024-03-03 03:21:26 +0100, Alejandro Colomar wrote:
> Hi Morten,
> 
> On Sat, Mar 02, 2024 at 09:02:24PM -0500, Morten Welinder wrote:
> > Thanks.
> > 
> > There is (was?) already crlibm out there.
> > https://core-math.gitlabpages.inria.fr/  No particular need for wheel
> > reinvention here.
> 
> crlibm doesn't seem to exist anymore.

The sources are still available at more non-official mirror, but
it is no longer maintained.

> Maybe just add some headers to core-math, and package it as a
> standalone library.

The issue is that it is not portable yet.

> > FWIW, it appears that the author of the glibc exp10 implementation
> > agrees with me that the implementation is sub-standard:
> > 
> > https://codebrowser.dev/glibc/glibc/math/e_exp10.c.html
> > 
> > /* This is a very stupid and inprecise implementation. It'll get
> > replaced sometime (soon?). */
> > return __ieee754_exp (M_LN10 * arg);
> 
> Hmmm.  Still, it's simple.  If pow(10, x) is strictly better, maybe one
> can prove it and send a patch.  Or for something better, it'll take more
> work.

If by "strictly better", you mean that for each input, it returns a
result that is at least as accurate as the one returned by the above
expression, then, probably no. The reason is that the rounding errors
in the above expression may partly compensate on a random basis. So,
for some proportion of inputs, you'll actually get an accurate result.
And unless pow is designed to be almost correctly rounded, it will
probably be sometimes worse.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

Re: Man page issues: logb, significand, cbrt, log2, log10, exp10

[Alejandro Colomar]

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

Hi Vincent,

On Sun, Mar 03, 2024 at 12:46:00PM +0100, Vincent Lefevre wrote:
> On 2024-03-03 03:21:26 +0100, Alejandro Colomar wrote:
> > Maybe just add some headers to core-math, and package it as a
> > standalone library.
> 
> The issue is that it is not portable yet.

Well, one could package it just to the systems to which it is portable,
if that's useful.  That's why a standalone library has more chances of
being available soon than glibc.  You'd need to make it portable (and
other things) to put it in glibc; but if you say "here's libcore-math,
avaiable only in XXX systems", you could get distros to distribute it
already.  And then provide headers that don't clash with glibc, such as
<core-math/*.h> or whatever.

> 
> > > FWIW, it appears that the author of the glibc exp10 implementation
> > > agrees with me that the implementation is sub-standard:
> > > 
> > > https://codebrowser.dev/glibc/glibc/math/e_exp10.c.html
> > > 
> > > /* This is a very stupid and inprecise implementation. It'll get
> > > replaced sometime (soon?). */
> > > return __ieee754_exp (M_LN10 * arg);
> > 
> > Hmmm.  Still, it's simple.  If pow(10, x) is strictly better, maybe one
> > can prove it and send a patch.  Or for something better, it'll take more
> > work.
> 
> If by "strictly better", you mean that for each input, it returns a
> result that is at least as accurate as the one returned by the above
> expression, then, probably no. The reason is that the rounding errors
> in the above expression may partly compensate on a random basis. So,
> for some proportion of inputs, you'll actually get an accurate result.
> And unless pow is designed to be almost correctly rounded, it will
> probably be sometimes worse.

Then glibc's current code is good, I guess.  It's simple, and works for
most programs.

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

Re: Man page issues: logb, significand, cbrt, log2, log10, exp10

[Morten Welinder]

Sorry to be a bit of a pain.

Some testing says that the average error from exp10 is 300-500 times
bigger than the average error from pow(10,.). This is consistent
across a large range of arguments.

The maximum error from pow(10,.) in the samples is 1ulp (relative to a
reference rounded value, so the true error is likely less). The
maximum error from exp10 in the samples is 2ulp.

This is not surprising given that exp10 starts out by introducing a
rounding error due to the multiplication before the call to exp.

I didn't bother looking, but it is almost certainly true that there
are arguments for which exp10 is better than pow(10,.).  However, the
numbers below imply that such arguments are very rare compared to the
other way around.


-------------------------- average ----- max
Binade -7      exp10: 0.3378           1
Binade -7  pow(10,.): 0.0007           1
Binade -6      exp10: 0.3429           2
Binade -6  pow(10,.): 0.0007           1
Binade -5      exp10: 0.3532           2
Binade -5  pow(10,.): 0.0008           1
Binade -4      exp10: 0.3774           2
Binade -4  pow(10,.): 0.0008           1
Binade -3      exp10: 0.4402           2
Binade -3  pow(10,.): 0.0010           1
Binade -2      exp10: 0.4118           2
Binade -2  pow(10,.): 0.0009           1
Binade -1      exp10: 0.4228           2
Binade -1  pow(10,.): 0.0009           1
Binade  0      exp10: 0.4204           2
Binade  0  pow(10,.): 0.0009           1
Binade  1      exp10: 0.4221           2
Binade  1  pow(10,.): 0.0009           1
Binade  2      exp10: 0.4204           2
Binade  2  pow(10,.): 0.0009           1
Binade  3      exp10: 0.4222           2
Binade  3  pow(10,.): 0.0009           1
Binade  4      exp10: 0.4209           2
Binade  4  pow(10,.): 0.0009           1
Binade  5      exp10: 0.4200           2
Binade  5  pow(10,.): 0.0009           1
Binade  6      exp10: 0.4210           2
Binade  6  pow(10,.): 0.0009           1
Binade  7      exp10: 0.4210           2
Binade  7  pow(10,.): 0.0009           1

Notes:
1. Only positive arguments tested.
2. powl (long double version of pow) is used as a reference.  I
double-checked with a double-double version of pow (good to about
100ish bits) that this does not matter.




#define _GNU_SOURCE   1
#include <stdio.h>
#include <math.h>
#include <stdint.h>


static uint64_t
murmur64 (uint64_t h)
{
  h ^= h >> 33;
  h *= 0xff51afd7ed558ccdll;
  h ^= h >> 33;
  h *= 0xc4ceb9fe1a85ec53ll;
  h ^= h >> 33;
  return h;
}

static double
exp10ref (double x)
{
  volatile double y = (double)(powl (10.0l, x));
  return y;
}

static double
exp10viapow (double x)
{
  return pow (10, x);
}


static void
test_binade (int b, double (*f) (double), const char *funcname)
{
  uint64_t h = 0x0123456701234567ll;

  double ulps = 0;
  double mulp = 0;
  int N = 1000000;

  for (int i = 0; i < N; i++) {
    h = murmur64 (h);

    double x = ldexp ((h & 0xfffffffffffffll) | 0x10000000000000ll, b - 52);

    double y = f (x);
    double yref = exp10ref (x);
    double dy = fabs (y - yref);

    double ulp = dy / (nextafter (yref, INFINITY) - yref);
    ulps += ulp;
    if (ulp > mulp) mulp = ulp;
  }

  printf ("Binade %2d %10s: %6.4f  %10.0f\n",
      b, funcname, ulps / N, mulp);
}


int
main ()
{
  for (int b = -7; b <= 7; b++) {
    test_binade (b, exp10, "exp10");
    test_binade (b, exp10viapow, "pow(10,.)");
  }

  return 0;
}

Re: Man page issues: logb, significand, cbrt, log2, log10, exp10

[Adhemerval Zanella Netto]

On 02/03/24 23:02, Morten Welinder wrote:
> Thanks.
> 
> There is (was?) already crlibm out there.
> https://core-math.gitlabpages.inria.fr/  No particular need for wheel
> reinvention here.
> 
> FWIW, it appears that the author of the glibc exp10 implementation
> agrees with me that the implementation is sub-standard:
> 
> https://codebrowser.dev/glibc/glibc/math/e_exp10.c.html

This code was not used by any port and we recently removed to avoid this
very issue [1]. The exp10 implementation used by all ports
is at sysdeps/ieee754/dbl-64/e_exp10.c (i386/m68k are exceptions and my
plan to eventually remove this implementation in favor the generic
one [2]).

And the exp10 implementation was recently improved [3], with the
author suggesting the worst-case error in round-to- should be
nearest to 0.513 ULP (I am not sure if he did some empirical testing
to verify this value, at least with libm-test-ulps the resuts are
bounded to 2 ulp max).

> 
> /* This is a very stupid and inprecise implementation. It'll get
> replaced sometime (soon?). */
> return __ieee754_exp (M_LN10 * arg);
> 
> 
> Compare with musl:
> 
> https://github.com/rofl0r/musl/blob/master/src/math/exp10.c
> 

[1] https://sourceware.org/git/?p=glibc.git;a=commit;h=9c61303ebbdc6e727c89591bff3229c9fbfa438b
[2] https://sourceware.org/pipermail/libc-alpha/2024-January/154107.html
[3] https://sourceware.org/git/?p=glibc.git;a=commit;h=63d0a35d5f223a3f4b68190567b7d4d44545bce5

logb() vs floor(log2()) (was: Man page issues: logb, significand, cbrt, log2, log10, exp10)

[Alejandro Colomar]

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

Hi Morten,

On Thu, Feb 29, 2024 at 07:28:10PM -0500, Morten Welinder wrote:
> I came across some minor issues in some math man pages.
> 
> M.
> 
> 
> 
> logb:
> The formula "floor(log2(x))" should be "floor(log2(fabs(x)))".  (Or
> ...abs(...) if it's meant to be math and not C.)

Confirmed.  This is a bug in glibc too, BTW.  That text seems to be
copied from their manual.

ISO C says this function is specified in ANSI/IEEE 854, but I don't have
access to that document, so I'm not sure what's the specification of the
function.  I'm not sure if it should fail for negative values (like
log2(3)) or not; although the standard mentions the behavior for
negative infinity, so it probably is specified to work for negative
values too.

So, the behavior of the function seems to be correct, and it's just the
manual that needs to be fixed.

I've CCed glibc, in case they want to comment.  But yeah, your
suggestion seems correct.

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

Re: logb() vs floor(log2())

[Adhemerval Zanella Netto]

On 04/03/24 14:52, Alejandro Colomar wrote:
> Hi Morten,
> 
> On Thu, Feb 29, 2024 at 07:28:10PM -0500, Morten Welinder wrote:
>> I came across some minor issues in some math man pages.
>>
>> M.
>>
>>
>>
>> logb:
>> The formula "floor(log2(x))" should be "floor(log2(fabs(x)))".  (Or
>> ...abs(...) if it's meant to be math and not C.)
> 
> Confirmed.  This is a bug in glibc too, BTW.  That text seems to be
> copied from their manual.
> 
> ISO C says this function is specified in ANSI/IEEE 854, but I don't have
> access to that document, so I'm not sure what's the specification of the
> function.  I'm not sure if it should fail for negative values (like
> log2(3)) or not; although the standard mentions the behavior for
> negative infinity, so it probably is specified to work for negative
> values too.
> 
> So, the behavior of the function seems to be correct, and it's just the
> manual that needs to be fixed.
> 
> I've CCed glibc, in case they want to comment.  But yeah, your
> suggestion seems correct.

It does seems to be an error on manual, could you send a patch to fix it?

Re: logb() vs floor(log2())

[Alejandro Colomar]

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

Hi Adhemerval,

On Mon, Mar 04, 2024 at 03:47:26PM -0300, Adhemerval Zanella Netto wrote:
> It does seems to be an error on manual, could you send a patch to fix it?

Sure!

Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

Re: logb() vs floor(log2()) (was: Man page issues: logb, significand, cbrt, log2, log10, exp10)

[Alejandro Colomar]

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

Hi Morten,

On Mon, Mar 04, 2024 at 06:52:10PM +0100, Alejandro Colomar wrote:
> > logb:
> > The formula "floor(log2(x))" should be "floor(log2(fabs(x)))".  (Or
> > ...abs(...) if it's meant to be math and not C.)

I've applied thge following patch:

commit 1d83ce827aac984a26430b4f6107182f4b076874 (HEAD -> contrib, alx/contrib)
Author: Alejandro Colomar <alx@kernel.org>
Date:   Tue Mar 5 00:20:09 2024 +0100

    logb.3: logb(x) is floor(log2(fabs(x)))
    
    log2(3) doesn't accept negative input, but it seems logb(3) does accept
    it.
    
    Link: <https://lore.kernel.org/linux-man/ZeYKUOKYS7G90SaV@debian/T/#u>
    Reported-by: Morten Welinder <mwelinder@gmail.com>
    Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org>
    Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man3/logb.3 b/man3/logb.3
index 7cbb2470a..7a1ad2f4a 100644
--- a/man3/logb.3
+++ b/man3/logb.3
@@ -58,7 +58,7 @@ .SH DESCRIPTION
 is 2,
 .BI logb( x )
 is equal to
-.BI floor(log2( x ))\fR,
+.BI floor(log2(fabs( x )))\f[R],\f[]
 except that it is probably faster.
 .P
 If



I'll push it tomorrow.

Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

Re: Man page issues: logb, significand, cbrt, log2, log10, exp10

[Alejandro Colomar]

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

On Thu, Feb 29, 2024 at 07:28:10PM -0500, Morten Welinder wrote:
> significand:
> The range [1,2) should be [1,FLT_RADIX)

Hi Morten,

I've fixed this with the following commit.  Thanks for the report!

Have a lovely night!
Alex

---
commit 6003cc006de65d8798a3324605c8b9d5abeef231 (HEAD -> contrib)
Author: Alejandro Colomar <alx@kernel.org>
Date:   Tue Mar 5 01:44:44 2024 +0100

    significand.3: significand uses FLT_RADIX, not 2
    
    It's implemented using scalb(), which uses FLT_RADIX.
    
    Reported-by: Morten Welinder <mwelinder@gmail.com>
    Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man3/significand.3 b/man3/significand.3
index e991a822a..f835f5511 100644
--- a/man3/significand.3
+++ b/man3/significand.3
@@ -36,7 +36,8 @@ .SH SYNOPSIS
 .SH DESCRIPTION
 These functions return the mantissa of
 .I x
-scaled to the range [1,2).
+scaled to the range
+.RB [ 1 ,\~ FLT_RADIX ).
 They are equivalent to
 .P
 .in +4n


-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

Re: Man page issues: logb, significand, cbrt, log2, log10, exp10

[Alejandro Colomar]

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

Hi Morten,

On Thu, Feb 29, 2024 at 07:28:10PM -0500, Morten Welinder wrote:
> cbrt:
> The phrase "every representable real value has a representable real
> cube root" is wrong.  In fact, a representable cube root is quite
> rare.  This should be something like "every representable real value
> has a real cube root and rounding it to a representable value never
> causes overflow or underflow."

Thanks for the report!  I've fixed it with the following commit (your
wording, except for a 'nor' instead of 'or').

This one is also present in the glibc manual, so I'll also send a fix
for it, Adhemerval.

Have a lovely night!
Alex

---
commit da7bb7434ce8b20deaed58cac9e942c3531a5db3 (HEAD -> contrib)
Author: Alejandro Colomar <alx@kernel.org>
Date:   Tue Mar 5 02:01:34 2024 +0100

    cbrt.3: wfix
    
    On Thu, Feb 29, 2024 at 07:28:10PM -0500, Morten Welinder wrote:
    > The phrase "every representable real value has a representable real
    > cube root" is wrong.  In fact, a representable cube root is quite
    > rare.
    
    Reported-by: Morten Welinder <mwelinder@gmail.com>
    Cowritten-by: Morten Welinder <mwelinder@gmail.com>
    Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org>
    Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man3/cbrt.3 b/man3/cbrt.3
index cf9c41771..64fc3c072 100644
--- a/man3/cbrt.3
+++ b/man3/cbrt.3
@@ -47,8 +47,11 @@ .SH SYNOPSIS
 .SH DESCRIPTION
 These functions return the (real) cube root of
 .IR x .
-This function cannot fail; every representable real value has a
-representable real cube root.
+This function cannot fail;
+every representable real value
+has a real cube root,
+and rounding it to a representable value
+never causes overflow nor underflow.
 .SH RETURN VALUE
 These functions return the cube root of
 .IR x .


-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

Re: Man page issues: logb, significand, cbrt, log2, log10, exp10

[Alejandro Colomar]

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

On Thu, Feb 29, 2024 at 07:28:10PM -0500, Morten Welinder wrote:
> log2, log10:
> These use, e.g., "base 2 logarithm".  Compare that to exp2's "base-2
> exponential" (with a hyphen).  I am leaning towards the hyphenated
> version being correct, but I am not a native English speaker.

Agree.

Have a lovely night,
Alex

commit daffbd4861cfd0534802dbed3122e2f95d9afcd0 (HEAD -> contrib, alx/contrib)
Author: Alejandro Colomar <alx@kernel.org>
Date:   Tue Mar 5 02:15:14 2024 +0100

    log2.3, log10.3: wfix
    
    Reported-by: Morten Welinder <mwelinder@gmail.com>
    Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man3/log10.3 b/man3/log10.3
index 415a77c5a..40e43117a 100644
--- a/man3/log10.3
+++ b/man3/log10.3
@@ -42,10 +42,10 @@ .SH SYNOPSIS
         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
 .fi
 .SH DESCRIPTION
-These functions return the base 10 logarithm of
+These functions return the base-10 logarithm of
 .IR x .
 .SH RETURN VALUE
-On success, these functions return the base 10 logarithm of
+On success, these functions return the base-10 logarithm of
 .IR x .
 .P
 For special cases, including where
diff --git a/man3/log2.3 b/man3/log2.3
index 62103fe46..11d8c3cc2 100644
--- a/man3/log2.3
+++ b/man3/log2.3
@@ -41,10 +41,10 @@ .SH SYNOPSIS
     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
 .fi
 .SH DESCRIPTION
-These functions return the base 2 logarithm of
+These functions return the base-2 logarithm of
 .IR x .
 .SH RETURN VALUE
-On success, these functions return the base 2 logarithm of
+On success, these functions return the base-2 logarithm of
 .IR x .
 .P
 For special cases, including where


-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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