+2025-02-08 Paul Eggert <eggert@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 <eggert@cs.ucla.edu>
intprops: new macro INT_PROMOTE
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
* mblen::
* mbstowcs::
* mbtowc::
+* memalignment::
* mkdtemp::
* mkostemp::
* mkstemp::
@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
--- /dev/null
+@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}.