Implement C23 memalignment

[Zack Weinberg]

On Thu, Oct 2, 2025, at 2:52 PM, Paul Eggert wrote:
> On 2025-10-02 10:15, Zack Weinberg wrote:
>> I don't like the "<alternative> suffices on all but theoretical
>> platforms" wording at all.  It reminds me of all the passive
>> aggressive language about how C89 allows for weird possibilities
>> that Will Not Happen On The GNU SystemTM, elsewhere in the manual.
>
> Although that *is* what's going on here, we can drop the wording if
> it's unlikable.

I didn't like it then and I don't like it now.  YMMV.

>> The performance issues can and should be addressed by making this
>> function into a compiler intrinsic.
>
> Although eventually that should happen, the issues are more subtle
> than one might think at first. Possibly memalignment will never be
> quite as efficient, depending on the compiler.

Having rechecked the spec, _arbitrary_ use of memalignment does seem
to require an efficient count-trailing-zeros instruction, but, as has
been pointed out elsethread, the expected usage is `memalignment(p) >= k`,
where k is a power of two, and this can be compiled efficiently with
only the basic set of bitwise operations.

>> I suggest this wording instead:
>
> Something like that should be fine, though as Joseph noted the
> wording you used wasn't quite right as it mishandled null and
> over-aligned pointers.

Yeah, my bad on that.  Corrected wording below.  However, I'm going to
insist on including both of these:

> Also, there's no need for the "presently", or for the "power
> of two" as all alignments are powers of two.

I think there's a real chance that we *will*, in the near future, have
glibc support for an architecture where pointers *aren't* so directly
interconvertible with integers as we're all used to; a CHERI-based
architecture, for instance.  (NB I haven't checked whether CheriBSD
provides `uintptr_t` or what its ABI says is the result of casting a
pointer to a suitably large integer type.)

And I think we *do* want to reiterate here that "an alignment" has to
be a power of two, because this is reference documentation and repeating
little reminders like that makes reading reference docs go much smoother.

> |The latter expression is likely more efficient,
> |and is portable to implementations that lack @code{memalignment}.

Mentioning portability is good, because people are likely to be using
compilers that don't support C2023 for quite some time; but I still
don't like mentioning efficiency at all here, because this is a really
obvious thing for the compiler to recognize and open-code, so I expect
that compilers that *do* advertise C2023 support are going to emit
optimal code for expressions involving this function in short order.

My proposed revised documentation (fully replaces the chunk of
Joseph's v2 patch that touches memory.texi):

---
The @dfn{alignment} of a pointer is the largest power of two that
evenly divides the pointer's numeric value.  You can determine the
alignment of a pointer with the @code{memalignment} function.

@deftypefun size_t memalignment (void *@var{p})
@standards{C23, stdlib.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns the alignment of the pointer @var{p}.  If @var{p} is a null
pointer, returns zero.

This function was added to the C standard in its 2023 revision.
C23 requires @var{p} to be either a valid pointer to an object,
or a null pointer.  As a GNU extension, @theglibc{} guarantees
to return the mathematically correct result for any input,
whether or not it is a valid pointer.

@strong{Portability Note:} There is no simple formula that can replace
all uses of this function.  However, the most common reason to want to
know the alignment of a pointer, is to compare it to the alignment
required by some data type.  On almost all current CPU architectures,
when @var{a} is a power of two, these expressions are equivalent:

@example
    memalignment (p) >= a
    p && ((uintptr_t) p & (a - 1)) == 0
@end example

Architectures where the second of these expressions doesn't work might
become more common in the future, which is one of the reasons
@code{memalignment} was added to the C standard.
@end deftypefun
---

It would probably also be a good idea to add some discussion of
<stdalign.h>, _Alignof, and _Alignas, but that should be a separate
patch.

zw