Re: aligned_alloc man page and restrictions on alignment values

[Alejandro Colomar <alx@kernel.org>]

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

On 2026-02-05T14:17:38+0100, Alejandro Colomar wrote:
> 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.

This one is also very relevant:

	commit a5342ef55f0a96790bf279a98c9d2a30b19fc9eb
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   Wed Dec 10 14:15:48 2025 +0100

	    man/man3/memalign.3: wfix
	    
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

	diff --git a/man/man3/memalign.3 b/man/man3/memalign.3
	index cc341be7b..12e8a5bb0 100644
	--- a/man/man3/memalign.3
	+++ b/man/man3/memalign.3
	@@ -19,8 +19,9 @@ .SH SYNOPSIS
	 .fi
	 .SH DESCRIPTION
	 .BR memalign ()
	-is the same as
	-.BR aligned_alloc (3).
	+is equivalent to
	+.BR aligned_alloc (3),
	+except for the CAVEATS documented below.
	 .\" The behavior of memalign() for size==0 is as for posix_memalign()
	 .\" but no standards govern this.
	 .SH ATTRIBUTES

> 
> 
> 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>



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

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