Re: [PATCH] man/: Replaced reserved exp identifier

[Vincent Lefevre <vincent@vinc17.net>]

Hi Alejandro,

On 2025-07-03 04:58:03 +0200, Alejandro Colomar wrote:
> Hi Vincent,
> 
> On Thu, Jul 03, 2025 at 04:34:51AM +0200, Vincent Lefevre wrote:
> > On 2025-07-02 16:41:28 +0200, Alejandro Colomar wrote:
> > > On Wed, Jul 02, 2025 at 11:25:16AM +0200, Vincent Lefevre wrote:
> > [...]
> > > > --- a/man/man2/timerfd_create.2
> > > > +++ b/man/man2/timerfd_create.2
> > > > @@ -639,12 +639,12 @@ main(int argc, char *argv[])
> > > >  {
> > > >      int                fd;
> > > >      ssize_t            s;
> > > > -    uint64_t           exp, tot_exp, max_exp;
> > > > +    uint64_t           ex, tot_ex, max_ex;
> > > 
> > > How about using 'to' for timeout?  Do you think it makes sense?
> > 
> > As described by the man page, this is more a timer expiration
> > (many occurrences of words starting with "expir") than a timeout
> > (a single occurrence - shouldn't this be "expiration time"?).
> > So, for these 3 variables, instead of "exp", perhaps "te" for
> > "timer expiration"?
> 
> I still think to or te (or ex) are too unreadable (and I tend to prefer
> one-letter variables when it is clear from the context, to be clear).
> How about expir?

OK for expir (with the reformatting of a line that would become
too long as a consequence). That's even clearer than exp.

> > > >      struct timespec    now;
> > > >      struct itimerspec  new_value;
> > > >  \&
> > > >      if (argc != 2 && argc != 4) {
> > > > -        fprintf(stderr, "%s init\-secs [interval\-secs max\-exp]\[rs]n",
> > > > +        fprintf(stderr, "%s init\-secs [interval\-secs max\-ex]\[rs]n",
> > > 
> > > And here saying max\-timeout.
> > 
> > One could actually let max\-exp. Or say max\-timer\-exp (the line
> > would not be too large).
> 
> Or timer_exp and max\-timer\-exp as you propose here.  That sounds quite
> readable.

The use of "max" in the name is important as there are several
timer expirations and one gives here the maximum number of such
expirations. It could also be "max\-expir" or "max\-#expir"[*].
What do you think?

[*] https://academia.stackexchange.com/questions/90816/abbreviation-of-number-of-in-a-table-heading

> > [...]
> > > > --- a/man/man3/frexp.3
> > > > +++ b/man/man3/frexp.3
> > > > @@ -14,9 +14,9 @@ Math library
> > > >  .nf
> > > >  .B #include <math.h>
> > > >  .P
> > > > -.BI "double frexp(double " x ", int *" exp );
> > > > -.BI "float frexpf(float " x ", int *" exp );
> > > > -.BI "long double frexpl(long double " x ", int *" exp );
> > > > +.BI "double frexp(double " x ", int *" p );
> > > > +.BI "float frexpf(float " x ", int *" p );
> > > > +.BI "long double frexpl(long double " x ", int *" p );
> > > 
> > > Here I think I'd use 'e' for exponent.  What do you think?
> > 
> > One could do that (this was more or less my initial idea,
> > and I'm wondering why the committee chose p).
> 
> The committee has chosen many bad names.  Let's not follow them.
> Indeed, now that I'm member of the committee, I'm trying to fix that
> among other things.

Great. FYI, here's what I sent to the CFP list yesterday, as there
are also remaining "exp" in the standard:

────────────────────────────────────────────────────────────────────────
In ISO C23 and still in the N3550 C2y draft, B.11 (<math.h>)
and H.11.3p1:

_FloatN frexpfN(_FloatN value, int *exp);
_FloatNx frexpfNx(_FloatNx value, int *exp);
_DecimalN frexpdN(_DecimalN value, int *exp);
_DecimalNx frexpdNx(_DecimalNx value, int *exp);

and

_FloatN ldexpfN(_FloatN value, int exp);
_FloatNx ldexpfNx(_FloatNx value, int exp);
_DecimalN ldexpdN(_DecimalN value, int exp);
_DecimalNx ldexpdNx(_DecimalNx value, int exp);

and

_FloatN scalbnfN(_FloatN value, int exp);
_FloatNx scalbnfNx(_FloatNx value, int exp);
_DecimalN scalbndN(_DecimalN value, int exp);
_DecimalNx scalbndNx(_DecimalNx value, int exp);
_FloatN scalblnfN(_FloatN value, long int exp);
_FloatNx scalblnfNx(_FloatNx value, long int exp);
_DecimalN scalblndN(_DecimalN value, long int exp);
_DecimalNx scalblndNx(_DecimalNx value, long int exp);

However, exp is a standard library function, thus the exp identifier
is reserved for any use. So the above prototypes are incorrect.

Earlier, one has:

double frexp(double value, int *p);
float frexpf(float value, int *p);
long double frexpl(long double value, int *p);

double ldexp(double x, int p);
float ldexpf(float x, int p);
long double ldexpl(long double x, int p);

double scalbn(double x, int n);
float scalbnf(float x, int n);
long double scalbnl(long double x, int n);
double scalbln(double x, long int n);
float scalblnf(float x, long int n);
long double scalblnl(long double x, long int n);

So, for consistency, p and n could be used respectively,
instead of exp.

H.11.3p2 and H.11.3p3 would also need to be updated.

Also in F.10.4.9:

"On a binary system, ldexp(x, exp) is equivalent to scalbn(x, exp)."

BTW, there is a similar issue in 7.17.7.5p7, which contains the
following example:

  exp = atomic_load(&cur);
  do {
        des = function(exp);
  } while (!atomic_compare_exchange_weak(&cur, &exp, des));
────────────────────────────────────────────────────────────────────────

> > BTW, for frexp, this is a pointer, while for ldexp, this is
> > an integer. So, should there be a difference (e.g. pe for
> > the pointer to the exponent, and e for the exponent)?
> 
> Hmmmm, I think not.  From the context it should be obvious.

So, OK for "e".

Regards,

-- 
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 / Pascaline project (LIP, ENS-Lyon)