On 2025-12-10 12:51, Alejandro Colomar wrote:

On Wed, Dec 10, 2025 at 08:24:03AM +0000, Seth McDonald wrote:

quoted

Hello all,

Hi Seth,

quoted

Reading the GNU/Linux manual pages for aligned_alloc(3), I think the
documentation is ambiguous about the function's usage requirements in two ways.
As of man-pages 6.16, the relevant description states:

quoted

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 restriction
that alignment must be a power of two.

First, I am unsure how the man page is attempting to distinguish
aligned_alloc() from memalign(). The stated difference - alignment must be a
power of two - is also said to be required of memalign().

Agree; the current text is self-inconsistent.

My comments are based on the glibc 2.42 code on elixir.bootlin.com. If 
there have been more changes or my reading of the code is wrong please 
ignore me.

aligned_alloc will fail and set errno to EINVAL if the alignment is not 
a power of two.

memalign will bump up the alignment to the next highest power of 2 if is 
isn't already a power of 2.

Both will fail if alignment is above SIZE_MAX / 2 + 1.

quoted

It is possible this
is a typo or copy-paste error, but I cannot tell what the intended distinction
is. It would be beneficial if this was fixed/clarified in the document.

The text was changed in

	commit 7fd1e0f2be216a5e7f7aef0d03304bdf81bca9e0
	Author: DJ Delorie [off-list ref]
	Date:   Mon May 8 20:43:35 2023 -0400

	    posix_memalign.3: Update aligned_alloc(3) to match C17
	
	    Link: <https://sourceware.org/pipermail/libc-alpha/2023-May/147810.html>
	    Link: <https://patchwork.sourceware.org/project/glibc/patch/33ec9e0c1e587813b90e8aa771c2c8e6e379dd48.camel@posteo.net/>
	    Link: <https://lore.kernel.org/linux-man/d79b505c-5b19-331c-5b25-d40adc9cc843@wanadoo.fr/ (local)>
	    Cc: John Scott [off-list ref]
	    Cc: Paul Floyd [off-list ref]
	    Signed-off-by: DJ Delorie [off-list ref]
	    Signed-off-by: Alejandro Colomar [off-list ref]

	diff --git a/man3/posix_memalign.3 b/man3/posix_memalign.3
	index 9bc6eb9a4..88e4a8b63 100644
	--- a/man3/posix_memalign.3
	+++ b/man3/posix_memalign.3
	@@ -91,9 +91,8 @@ .SH DESCRIPTION
	 is the same as
	 .BR memalign (),
	 except for the added restriction that
	-.I size
	-should be a multiple of
	-.IR alignment .
	+.I alignment
	+must be a power of two.
	 .PP
	 The obsolete function
	 .BR valloc ()

Following the links in that commit message, it seems the commit was
wrong.  It should have just removed the exception entirely.
C17 lifted the restriction.

I propose the following fix:

	commit 90f18b452a7113f42ea4e222f819257e692ce57b
	Author: Alejandro Colomar [off-list ref]
	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 [off-list ref]
	    Signed-off-by: Alejandro Colomar [off-list ref]

	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 think that exact opposite is the case.

memalign and aligned_alloc used to be the same (aligned_alloc was a weak 
alias for memalign).

Now aligned_alloc is a separate function. It does a power-of-two check 
on the alignment and then calls _mid_memalign, which is also the 
implementation function for memalign.

Regards

Paul