Re: aligned_alloc man page and restrictions on alignment values

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 3982 bytes --]

Hi Jonathan,

On 2026-02-05T10:05:08+0000, Jonathan Wakely wrote:
> Hi,
> 
> I don't understand what "except for the added restriction" means in
> aligned_alloc(3) here:
> 
>       The  obsolete  function  memalign()  allocates  size bytes and returns a
>       pointer to the allocated memory.  The memory address will be a  multiple
>       of alignment, which must be a power of two.
> 
>       aligned_alloc() is the same as memalign(), except for the added restric‐
>       tion that alignment must be a power of two.

That was fixed (removed) in

	commit 90f18b452a7113f42ea4e222f819257e692ce57b
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   Wed Dec 10 12:14:01 2025 +0100

	    man/man3/posix_memalign.3: Remove confusing exception
	    
	    This is already a requirement of memalign(3).  aligned_alloc(3)
	    is indeed exactly equivalent to memalign(3), since ISO C17.
	    
	    Fixes: 7fd1e0f2be21 (2023-05-20; "posix_memalign.3: Update aligned_alloc(3) to match C17")
	    Reported-by: Seth McDonald <sethmcmail@pm.me>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

	diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
	index 397f65aec..9c4a0bff9 100644
	--- a/man/man3/posix_memalign.3
	+++ b/man/man3/posix_memalign.3
	@@ -83,10 +83,7 @@ .SH DESCRIPTION
	 .P
	 .BR aligned_alloc ()
	 is the same as
	-.BR memalign (),
	-except for the added restriction that
	-.I alignment
	-must be a power of two.
	+.BR memalign ().
	 .P
	 The obsolete function
	 .BR valloc ()


I'm planning to do a release this or next week, FWIW.

You may also be interested in checking the diff from

	commit 5695edc7e9a3b301403aa7773b316c8d51af650c
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   Mon Dec 15 15:14:48 2025 +0100

	    man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
	    
	    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 <evgsyr@gmail.com>
	    Reviewed-by: "G. Branden Robinson" <branden@debian.org>
	    Cc: Seth McDonald <sethmcmail@pm.me>
	    Cc: DJ Delorie <dj@redhat.com>
	    Cc: John Scott <jscott@posteo.net>
	    Cc: Paul Floyd <pjfloyd@wanadoo.fr>
	    Cc: <misc@openbsd.org>
	    Cc: Ingo Schwarze <schwarze@openbsd.org>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

(I haven't pasted the diff because it's large.)

And you may also want to check other patches applied near those two.


Have a lovely day!
Alex

> 
> 
> Does it mean that aligned_alloc doesn't have the power of two
> restriction? If so, describing that as an "added" restriction is very
> confusing. What was it added to? It's not added to aligned_alloc if
> it's absent from aligned_alloc.
> 
> Does it mean "aligned_alloc() is the same as memalign(), except that
> alignment need not be a power of two"? That would match my
> understanding of the C standard, which says that aligned_alloc() has
> well-defined behaviour for invalid alignments, failing by returning a
> null pointer.
> 
> But posix_memalign also has well-defined behaviour for invalid
> alignments. POSIX requires that posix_memalign handles invalid
> alignments by returning NULL and setting errno to EINVAL. Which is
> what aligned_alloc does too. So what exactly is the restriction here?
> Does memalign have UB for invalid alignments, or does it fail and set
> EINVAL? How is that different from aligned_alloc and posix_memalign?
> 
> Wording the linux man page in terms of "must be" and wording POSIX in
> terms of "shall be" makes it sound like you get UB if you fail to meet
> it, but as far as I can tell you just get a null pointer. The APIs are
> well-defined for invalid alignment arguments.
> 
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]