lib/libc: implement C23 memalignment()

This new function computes the alignment of a pointer.
It is part of ISO/IEC 9899:2024, the new C standard.
If the pointer is a null pointer, null is returned.
I have tried to write an implementation that can cope
with traditional address-based architectures, even if
size_t and uintptr_t are of different length.  Adjustments
may be needed for CHERI though.

A man page is provided, too.  No unit test for now.

Reviewed by:	kib, imp, ziaee (manpages), pauamma@gundo.com
Approved by:	markj (mentor)
MFC after:	1 month
Relnotes:	yes
Differential Revision:	https://reviews.freebsd.org/D53673

1 files changed, 53 insertions, 0 deletions

diff --git a/lib/libc/stdlib/memalignment.3 b/lib/libc/stdlib/memalignment.3
new file mode 100644
index 000000000000..4a2269a82c81
--- /dev/null
+++ b/lib/libc/stdlib/memalignment.3
@@ -0,0 +1,53 @@
+.\"
+.\" Copyright (c) 2025 Robert Clausecker <fuz@FreeBSD.org>
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.Dd November 10, 2025
+.Dt MEMALIGNMENT 3
+.Os
+.Sh NAME
+.Nm memalignment
+.Nd find the memory alignment of an object
+.Sh SYNOPSIS
+.Lb libc
+.In stdlib.h
+.Ft size_t
+.Fn memalignment "const void *ptr"
+.Sh DESCRIPTION
+The
+.Fn memalignment
+function determines the alignment of the object pointed to by
+.Fa ptr .
+This alignment is a power of\~2, and may be larger than the range
+supported by the
+.Sy alignof
+operator.
+The value returned can be compared to the result of
+.Sy alignof ,
+and if it is greater or equal, the alignment requirement of the operand
+is satisfied.
+.Sh RETURN VALUES
+Returns the alignment of
+.Fa ptr
+as a power of\~2.
+If
+.Fa ptr
+is a null pointer, an alignment of zero is returned.
+An alignment of zero indicates that the tested pointer cannot be used to
+access an object of any type.
+.Sh SEE ALSO
+.Xr aligned_alloc 3 ,
+.Xr posix_memalign 3
+.Sh STANDARDS
+The
+.Fn memalignment
+function conforms to
+.St -isoC-2023 .
+.Sh HISTORY
+The
+.Fn memalignment
+function was added in
+.Fx 15.1.
+.Sh AUTHOR
+.An Robert Clausecker Aq Mt fuz@FreeBSD.org