Document the turbulent past of aligned_alloc(), and how libraries have actually implemented it.
Fixes: 7fd1e0f2be21 (2023-05-20; "posix_memalign.3: Update aligned_alloc(3) to match C17") Reported-by: Eugene Syromyatnikov <[email protected]> Cc: Seth McDonald <[email protected]> Cc: DJ Delorie <[email protected]> Cc: John Scott <[email protected]> Cc: Paul Floyd <[email protected]> Cc: <[email protected]> Cc: Ingo Schwarze <[email protected]> Signed-off-by: Alejandro Colomar <[email protected]> --- man/man3/aligned_alloc.3 | 60 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/man/man3/aligned_alloc.3 b/man/man3/aligned_alloc.3 index cdc9ba1a2..820582f35 100644 --- a/man/man3/aligned_alloc.3 +++ b/man/man3/aligned_alloc.3 @@ -76,6 +76,66 @@ .SH HISTORY glibc 2.16. C11, POSIX.1-2024. +.SS C11 +In C11, +the specification of this function had +.UR https://port70.net/~nsz/c/c11/n1570.html#7.22.3.1p2 +several issues +.UE . +.IP \[bu] 3 +.I size +had to be a multiple of +.IR alignment . +Otherwise, +the behavior was undefined. +.IP \[bu] +If +.I alignment +was not a power of two, +the behavior was undefined. +.P +.UR https://www.open-std.org/jtc1/sc22/wg14/www/docs/summary.htm#dr_460 +DR460 +.UE +reported both cases of UB as unnecessarily dangerous, +and fixed them with a Technical Corrigendum +that transformed them into errors. +.P +.UR https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2072.htm +N2072 +.UE +reported that the requirement +that +.I size +is a multiple of +.I alignment +is superfluous, +and removed it with a Technical Corrigendum. +.P +C17 incorporates both technical corrigenda. +The API has been stable since C17. +.P +glibc originally implemented it as silently aligning as +.I stdc_bit_ceil(alignment) +instead of +.IR alignment . +Since glibc 2.38, +it implements the C17 specification. +.P +Some implementations, +such as FreeBSD/jemalloc, +implement the C17 specification, +even though their documentation claims the C11 specification. +.P +Some implementations, +such as OpenBSD, +implement C11 amended with DR460, +even though their documentation claims having undefined behavior. +.P +No known implementations +have exploited the undefined behavior +in a more dangerous way. +This function should be safe to use. .SH NOTES On many systems there are alignment restrictions, for example, on buffers used for direct block device I/O. -- 2.51.0
