Re: Feedback for n3704 - Clean up frexp, ldexp, and scalbn prototypes

[Alejandro Colomar <une+c@alejandro-colomar.es>]

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

Hi Mark,

On Sat, Jan 17, 2026 at 02:23:39PM -0800, Mark Harris wrote:
> "e" seems like a particularly poor choice, given that it is used in
> documentation with the well-established meaning of the base of the
> natural logarithm (e.g., in exp(3)).

I don't expect anyone to confuse a variable 'e' with the base of the
natural logarithm (M_E from <math.h>), since the base of the natural
logarithm is not something variable, and thus it wouldn't make sense to
pass it as a function argument.

Maybe a second of wondering, and reading the documentation carefully,
but nothing important.  Once the base of the natural logarithm is
discarded the meaning is then clear.  On the other hand, I would
consistently wonder what 'p' is, as it has no mnemonics.

>  - Mark


Have a lovely night!
Alex

> Alejandro Colomar wrote:
> >
> > Hi!
> >
> >
> > I see n3704 attempts to fix the issues reported by Vincent; that's good.
> > <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3704.pdf>
> >
> > However, the paper renames the pointer to 'p', which doesn't seem to
> > have good mnemonics nor relate to what it is.  'p' seems to just be
> > for 'pointer'?  We can and should do better.
> >
> > I think alx-0051 was better, in using a parameter name that relates to
> > what the parameter means: 'e' for exponent.  Names matter.
> >
> > I think we should discuss the name in the meeting.  Also, I think n3704
> > should have included a rationaly for the name; especially, when a better
> > name has been proposed, and for some reason the proposal decided to use
> > a different one; that should certainly have been discussed.
> >
> > I think we can discuss the name in meeting without having to officially
> > present alx-0051 with an N-document number.  Please let me know if I
> > should formally present alx-0051 for the next meeting.
> >
> >
> > Have a lovely night!
> > Alex
> >
> > On Tue, Jul 15, 2025 at 12:24:29AM +0200, Alejandro Colomar wrote:
> > > Hi!
> > >
> > > Vincent reported this issue to me in the Linux man-pages mailing list
> > > (as the manual pages also had the same issue, so he reported the issue
> > > in both the manual pages and the ISO C standard).  I think this can be
> > > fixed editorially without going through an official N-document.  Please
> > > find the proposal below.
> > >
> > >
> > > Have a lovely night!
> > > Alex
> > >
> > > ---
> > > Name
> > >       alx-0051r0 - don't misuse reserved identifier 'exp'
> > >
> > > Category
> > >       Editorial.
> > >
> > > Author
> > >       Reported-by: Vincent Lefevre <vincent@vinc17.net>
> > >       Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > >
> > > History
> > >       <https://www.alejandro-colomar.es/src/alx/alx/wg14/alx-0051.git/>
> > >
> > >       r0 (2025-07-15):
> > >       -  Initial draft.
> > >
> > > Rationale
> > >       Since 'exp' is a library function, it is a reserved identifier,
> > >       which should not be used as a variable / parameter name.
> > >
> > >       7.1.3p1 says
> > >
> > >               All potentially reserved identifiers (...) that are
> > >               provided by an implementation with an external
> > >               definition are reserved for any use.
> > >
> > > Proposed wording
> > >       Based on N3550.
> > >
> > >     7.17.7.5  The atomic_compare_exchange generic functions
> > >       @@ Description, p7 EXAMPLE
> > >       -       exp = atomic_load(&cur);
> > >       +       e = atomic_load(&cur);
> > >               do {
> > >       -               des = function(exp);
> > >       +               des = function(e);
> > >       -       } while (!atomic_compare_exchange_weak(&cur, &exp, des));
> > >       +       } while (!atomic_compare_exchange_weak(&cur, &e, des));
> > >
> > >     B.11  Mathematics <math.h>
> > >       @@
> > >       ...
> > >       -_FloatN frexpfN(_FloatN value, int *exp);
> > >       -_FloatNx frexpfNx(_FloatNx value, int *exp);
> > >       -_DecimalN frexpdN(_DecimalN value, int *exp);
> > >       -_DecimalNx frexpdNx(_DecimalNx value, int *exp);
> > >       +_FloatN frexpfN(_FloatN value, int *e);
> > >       +_FloatNx frexpfNx(_FloatNx value, int *e);
> > >       +_DecimalN frexpdN(_DecimalN value, int *e);
> > >       +_DecimalNx frexpdNx(_DecimalNx value, int *e);
> > >       ...
> > >
> > >       @@
> > >       ...
> > >       -_FloatN ldexpfN(_FloatN value, int *exp);
> > >       -_FloatNx ldexpfNx(_FloatNx value, int *exp);
> > >       -_DecimalN ldexpdN(_DecimalN value, int *exp);
> > >       -_DecimalNx ldexpdNx(_DecimalNx value, int *exp);
> > >       +_FloatN ldexpfN(_FloatN value, int *e);
> > >       +_FloatNx ldexpfNx(_FloatNx value, int *e);
> > >       +_DecimalN ldexpdN(_DecimalN value, int *e);
> > >       +_DecimalNx ldexpdNx(_DecimalNx value, int *e);
> > >       ...
> > >
> > >       @@
> > >       ...
> > >       -_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 scalbnfN(_FloatN value, int *e);
> > >       +_FloatNx scalbnfNx(_FloatNx value, int *e);
> > >       +_DecimalN scalbndN(_DecimalN value, int *e);
> > >       +_DecimalNx scalbndNx(_DecimalNx value, int *e);
> > >       -_FloatN scalblnfN(_FloatN value, int *exp);
> > >       -_FloatNx scalblnfNx(_FloatNx value, int *exp);
> > >       -_DecimalN scalblndN(_DecimalN value, int *exp);
> > >       -_DecimalNx scalblndNx(_DecimalNx value, int *exp);
> > >       +_FloatN scalblnfN(_FloatN value, int *e);
> > >       +_FloatNx scalblnfNx(_FloatNx value, int *e);
> > >       +_DecimalN scalblndN(_DecimalN value, int *e);
> > >       +_DecimalNx scalblndNx(_DecimalNx value, int *e);
> > >       ...
> > >
> > >     F.10.4.9  The ldexp functions
> > >       @@ p1
> > >        On a binary system,
> > >       -ldexp(x, exp)
> > >       +ldexp(x, e)
> > >        is equivalent to
> > >       -scalbn(x, exp).
> > >       +scalbn(x, e).
> > >
> > >       ## And remove bold from 'exp' in the paragraph above.  This is
> > >       ## probably present due to exp being considered as a reserved
> > >       ## identifier by some script, which is part of the consequences
> > >       ## of undefined behavior: UB might format your standard!  :)
> > >
> > >     H.11.3  Functions
> > >       @@ 7.12.7  Exponential and logarithmic functions
> > >       ## Apply same changes as in B.11 (see above).
> > >
> > >       @@ F.10.14  Payload functions, p2
> > >       ...
> > >        the exponent is an integral power of 2 and,
> > >        when applicable,
> > >       -value equals x × 2*exp.
> > >       +value equals x × 2*e.
> > >
> > > --
> > > <https://www.alejandro-colomar.es/>
> >
> >
> >
> > --
> > <https://www.alejandro-colomar.es>

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

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