aligned_alloc man page and restrictions on alignment values

aligned_alloc man page and restrictions on alignment values

[Jonathan Wakely]

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.


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.

Re: aligned_alloc man page and restrictions on alignment values

[Alejandro Colomar]

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

Re: aligned_alloc man page and restrictions on alignment values

[Alejandro Colomar]

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

Re: aligned_alloc man page and restrictions on alignment values

[Jonathan Wakely]

On Thu, 5 Feb 2026 at 13:26, Alejandro Colomar <alx@kernel.org> 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

Oh great, thanks! I was only looking at the Fedora man-pages, I should
have checked git first.

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

Re: aligned_alloc man page and restrictions on alignment values

[Alejandro Colomar]

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

Hi Jonathan,

On 2026-02-05T13:55:47+0000, Jonathan Wakely wrote:
> On Thu, 5 Feb 2026 at 13:26, Alejandro Colomar <alx@kernel.org> 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
> 
> Oh great, thanks! I was only looking at the Fedora man-pages, I should
> have checked git first.

No problems at all!

I believe asking can sometimes be more efficient than checking, and it
triggers discussion, which may sometimes uncover unresolved issues.
So thanks for asking!  :-)


Cheers,
Alex


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

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

Re: aligned_alloc man page and restrictions on alignment values

[Carlos O'Donell]

On 2/5/26 8:55 AM, Jonathan Wakely wrote:
> On Thu, 5 Feb 2026 at 13:26, Alejandro Colomar <alx@kernel.org> 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
> 
> Oh great, thanks! I was only looking at the Fedora man-pages, I should
> have checked git first.
As the Fedora man-pages maintainer I'll chime in here briefly.

Fedora man-pages is currently pinned to 6.13, which is the last
release that contains the required copyright notices.

Will the next release of man-pages include the changes discussed
here to restore copyright notices?

https://lore.kernel.org/linux-man/b6prio6ck56jekesw5v5gmmzrkfqdtjqwaq5jzgugkhy7tznc6@jhag73ju3qq3/

-- 
Cheers,
Carlos.

Re: aligned_alloc man page and restrictions on alignment values

[Alejandro Colomar]

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

Hi Carlos,

On Thu, Feb 05, 2026 at 10:23:54AM -0500, Carlos O'Donell wrote:
> On 2/5/26 8:55 AM, Jonathan Wakely wrote:
> > On Thu, 5 Feb 2026 at 13:26, Alejandro Colomar <alx@kernel.org> 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
> > 
> > Oh great, thanks! I was only looking at the Fedora man-pages, I should
> > have checked git first.
> As the Fedora man-pages maintainer I'll chime in here briefly.
> 
> Fedora man-pages is currently pinned to 6.13, which is the last
> release that contains the required copyright notices.
> 
> Will the next release of man-pages include the changes discussed
> here to restore copyright notices?

Yup; I'm working on that, and expect to finish it this or next week,
which is why I plan to release this or next week.


Have a lovely day!
Alex


P.S.:  Carlos, I remember needing you to review a patch from a guy that
discussed with you.  Do you have that in your TODO list?  That was a few
months ago.


> 
> https://lore.kernel.org/linux-man/b6prio6ck56jekesw5v5gmmzrkfqdtjqwaq5jzgugkhy7tznc6@jhag73ju3qq3/
> 
> -- 
> Cheers,
> Carlos.
> 
> 

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

Re: aligned_alloc man page and restrictions on alignment values

[Carlos O'Donell]

On 2/5/26 10:53 AM, Alejandro Colomar wrote:
> P.S.:  Carlos, I remember needing you to review a patch from a guy that
> discussed with you.  Do you have that in your TODO list?  That was a few
> months ago.
No, I might have missed that. URL? I can review today.

-- 
Cheers,
Carlos.

Re: aligned_alloc man page and restrictions on alignment values

[Alejandro Colomar]

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

Hi Carlos,

On 2026-02-06T09:09:21-0500, Carlos O'Donell wrote:
> On 2/5/26 10:53 AM, Alejandro Colomar wrote:
> > P.S.:  Carlos, I remember needing you to review a patch from a guy that
> > discussed with you.  Do you have that in your TODO list?  That was a few
> > months ago.
> No, I might have missed that. URL? I can review today.

<https://lore.kernel.org/linux-man/frpbzpltwr34qs3v4mluajb2czznm3ebog34uhuj4a4qi7yft3@h6rj3y7c32qu/>

Cheers,
Alex

> 
> -- 
> Cheers,
> Carlos.
> 

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

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