* doc/gnulib-readme.texi (Other portability assumptions):
Mention the C23 function memalignment.
* doc/posix-functions/memalignment.texi: New file.
* doc/gnulib.texi (Functions in <stdlib.h>): Include it.
---
ChangeLog | 8 ++++++++
doc/gnulib-readme.texi | 16 +++++++++++-----
doc/gnulib.texi | 2 ++
doc/posix-functions/memalignment.texi | 23 +++++++++++++++++++++++
4 files changed, 44 insertions(+), 5 deletions(-)
create mode 100644 doc/posix-functions/memalignment.texi
diff --git a/ChangeLog b/ChangeLog
index a08e7a0220..7e0b8163a5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2025-02-08 Paul Eggert <egg...@cs.ucla.edu>
+
+ memalignment: document
+ * doc/gnulib-readme.texi (Other portability assumptions):
+ Mention the C23 function memalignment.
+ * doc/posix-functions/memalignment.texi: New file.
+ * doc/gnulib.texi (Functions in <stdlib.h>): Include it.
+
2025-02-07 Paul Eggert <egg...@cs.ucla.edu>
intprops: new macro INT_PROMOTE
diff --git a/doc/gnulib-readme.texi b/doc/gnulib-readme.texi
index 85affcd23f..737134edcd 100644
--- a/doc/gnulib-readme.texi
+++ b/doc/gnulib-readme.texi
@@ -535,15 +535,21 @@ A pointer @var{P} points within an object @var{O} if and
only if
Arithmetic on a valid pointer is equivalent to the same arithmetic on
the pointer converted to @code{uintptr_t}, except that offsets are
multiplied by the size of the pointed-to objects.
-For example, if @code{P + I} is a valid expression involving a pointer
-@var{P} and an integer @var{I}, then @code{(uintptr_t) (P + I) ==
-(uintptr_t) ((uintptr_t) P + I * sizeof *P)}.
+For example, if @code{@var{P} + @var{I}} is a valid expression
+involving a pointer @var{P} and an integer @var{I}, then
+@code{(uintptr_t) (@var{P} + @var{I}) == (uintptr_t) ((uintptr_t)
+@var{P} + @var{I} * sizeof *@var{P})}.
Similar arithmetic can be done with @code{intptr_t}, although more
care must be taken in case of integer overflow or negative integers.
@item
-A pointer @code{P} has alignment @code{A} if and only if
-@code{(uintptr_t) P % A} is zero, and similarly for @code{intptr_t}.
+A pointer @var{P} has alignment @var{A} if and only if
+@code{(uintptr_t) @var{P} % @var{A}} is zero, and similarly for
@code{intptr_t}.
+Although C23 says that portable code should instead test whether
+@code{memalignment (@var{P}) % @var{A}} is zero, @code{memalignment} is
+missing in many non-C23 systems, is not specified to work portably on
+pointers to atomic or volatile memory, and is likely a bit slower than
+the cast.
@item
If an existing object has size @var{S}, and if @var{T} is sufficiently
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index 851c8ae01c..4d0cfd26d5 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -3601,6 +3601,7 @@ This list of functions is sorted according to the header
that declares them.
* mblen::
* mbstowcs::
* mbtowc::
+* memalignment::
* mkdtemp::
* mkostemp::
* mkstemp::
@@ -3679,6 +3680,7 @@ This list of functions is sorted according to the header
that declares them.
@include posix-functions/mblen.texi
@include posix-functions/mbstowcs.texi
@include posix-functions/mbtowc.texi
+@include posix-functions/memalignment.texi
@include posix-functions/mkdtemp.texi
@include posix-functions/mkostemp.texi
@include posix-functions/mkstemp.texi
diff --git a/doc/posix-functions/memalignment.texi
b/doc/posix-functions/memalignment.texi
new file mode 100644
index 0000000000..c090f435b8
--- /dev/null
+++ b/doc/posix-functions/memalignment.texi
@@ -0,0 +1,23 @@
+@node memalignment
+@subsection @code{memalignment}
+@findex memalignment
+
+ISO C23 specification:@*
@url{https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf} section
7.24.9.1
+
+Gnulib module: ---
+
+Portability problems fixed by Gnulib:
+@itemize
+@end itemize
+
+Portability problems not fixed by Gnulib:
+@itemize
+@item
+This function is missing on most non-C23 platforms:
+glibc 2.41, macOS 14, FreeBSD 14.0, NetBSD 10.0, OpenBSD 7.5, Minix 3.3.0, AIX
7.3.1, HP-UX 11.31, Solaris 11.4, Cygwin 3.5.3, mingw, MSVC 14, Android 9.0.
+@end itemize
+
+To check whether a pointer @var{P} has alignment @var{A},
+Gnulib code typically tests @code{(uintptr_t) @var{P} % @var{A}}
+instead of @code{memalignment (@var{P}) % @var{A}}.
+@xref{Other portability assumptions}.
--
2.45.2
