[PATCH v1 00/12] man/man3/posix_memalign.3: Several fixes, and split the page

[PATCH v1 00/12] man/man3/posix_memalign.3: Several fixes, and split the page

[Alejandro Colomar]

Hi!

After Seth's bug report(s), I've applied several fixes to
posix_memalign.3.  While and after doing that, I've also applied other
patches for improving the page, including a split.

From all of these functions, ISO C's aligned_alloc(3) is the only one
that programmers should be using.  Let's have a page dedicated
exclusively for that function, which documents it well, without noise.

Secondarily, let's have one page for posix_memalign(3), which is still
not officially deprecated, where it is well documented, but point out
that aligned_alloc(3) is preferable.

Then, have one page per each of the other functions, documenting that
they are deprecated, documenting their flaws and subtleties, and
referring to aligned_alloc(3) for the main documentation, as they are
essentially just flawed versions of it.


Have a lovely day!
Alex

Alejandro Colomar (12):
  man/man3/posix_memalign.3: Remove confusing exception
  man/man3/posix_memalign.3: wfix
  man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to ISO
    C17, not C11
  man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to C23
  man/man3/posix_memalign.3: STANDARDS: aligned_alloc() and
    posix_memalign() conform to POSIX.1-2024
  man/man3/{posix_,}memalign.3: Split memalign() from posix_memalign(3)
  man/man3/{posix_memalign,pvalloc}.3: Split pvalloc() from
    posix_memalign(3)
  man/man3/{posix_memalign,valloc}.3: Split valloc() from
    posix_memalign(3)
  man/man3/{aligned_alloc,posix_memalign}.3: Split aligned_alloc() from
    posix_memalign(3)
  man/man3/posix_memalign.3: CAVEATS: Add section, and move paragraph to
    it
  man/man3/posix_memalign.3: Remove redundant text
  man/man3/posix_memalign.3: NOTES: Remove superfluous section

 man/man3/aligned_alloc.3  |  99 +++++++++++++++++-
 man/man3/memalign.3       |  77 +++++++++++++-
 man/man3/posix_memalign.3 | 211 +++-----------------------------------
 man/man3/pvalloc.3        |  49 ++++++++-
 man/man3/valloc.3         |  89 +++++++++++++++-
 5 files changed, 326 insertions(+), 199 deletions(-)

Range-diff against v0:
 -:  --------- >  1:  90f18b452 man/man3/posix_memalign.3: Remove confusing exception
 -:  --------- >  2:  19b5ea61e man/man3/posix_memalign.3: wfix
 -:  --------- >  3:  95f523f48 man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to ISO C17, not C11
 -:  --------- >  4:  9db9d670c man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to C23
 -:  --------- >  5:  032768ed7 man/man3/posix_memalign.3: STANDARDS: aligned_alloc() and posix_memalign() conform to POSIX.1-2024
 -:  --------- >  6:  de49191b8 man/man3/{posix_,}memalign.3: Split memalign() from posix_memalign(3)
 -:  --------- >  7:  af29aac57 man/man3/{posix_memalign,pvalloc}.3: Split pvalloc() from posix_memalign(3)
 -:  --------- >  8:  03408db2f man/man3/{posix_memalign,valloc}.3: Split valloc() from posix_memalign(3)
 -:  --------- >  9:  6da397d5c man/man3/{aligned_alloc,posix_memalign}.3: Split aligned_alloc() from posix_memalign(3)
 -:  --------- > 10:  213710d2c man/man3/posix_memalign.3: CAVEATS: Add section, and move paragraph to it
 -:  --------- > 11:  7960911fc man/man3/posix_memalign.3: Remove redundant text
 -:  --------- > 12:  54e7d20ee man/man3/posix_memalign.3: NOTES: Remove superfluous section
-- 
2.51.0

[PATCH v1 01/12] man/man3/posix_memalign.3: Remove confusing exception

[Alejandro Colomar]

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>
---
 man/man3/posix_memalign.3 | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

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 ()
-- 
2.51.0

[PATCH v1 02/12] man/man3/posix_memalign.3: wfix

[Alejandro Colomar]

Document aligned_alloc(3), and then say memalign(3) is equivalent,
instead of the other way around.  aligned_alloc(3) is the important one.

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index 9c4a0bff9..4cf63d283 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -70,8 +70,7 @@ .SH DESCRIPTION
 .\" glibc does this:
 or a unique pointer value.
 .P
-The obsolete function
-.BR memalign ()
+.BR aligned_alloc ()
 allocates
 .I size
 bytes and returns a pointer to the allocated memory.
@@ -81,9 +80,10 @@ .SH DESCRIPTION
 .\" The behavior of memalign() for size==0 is as for posix_memalign()
 .\" but no standards govern this.
 .P
-.BR aligned_alloc ()
+The obsolete function
+.BR memalign ()
 is the same as
-.BR memalign ().
+.BR aligned_alloc ().
 .P
 The obsolete function
 .BR valloc ()
-- 
2.51.0

[PATCH v1 03/12] man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to ISO C17, not C11

[Alejandro Colomar]

ISO C17 removed a restriction that was in place in C11.  This
documentation doesn't conform to C11; it conforms to 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>
---
 man/man3/posix_memalign.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index 4cf63d283..d0adaab01 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -162,7 +162,7 @@ .SH ATTRIBUTES
 .SH STANDARDS
 .TP
 .BR aligned_alloc ()
-C11.
+C17.
 .TP
 .BR posix_memalign ()
 POSIX.1-2008.
-- 
2.51.0

[PATCH v1 04/12] man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to C23

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index d0adaab01..ba99f0c6a 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -162,7 +162,7 @@ .SH ATTRIBUTES
 .SH STANDARDS
 .TP
 .BR aligned_alloc ()
-C17.
+C23.
 .TP
 .BR posix_memalign ()
 POSIX.1-2008.
-- 
2.51.0

[PATCH v1 05/12] man/man3/posix_memalign.3: STANDARDS: aligned_alloc() and posix_memalign() conform to POSIX.1-2024

[Alejandro Colomar]

Cc: Seth McDonald <sethmcmail@pm.me>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index ba99f0c6a..ecbbd3e7a 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -162,10 +162,11 @@ .SH ATTRIBUTES
 .SH STANDARDS
 .TP
 .BR aligned_alloc ()
-C23.
+C23,
+POSIX.1-2024.
 .TP
 .BR posix_memalign ()
-POSIX.1-2008.
+POSIX.1-2024.
 .TP
 .BR memalign ()
 .TQ
@@ -178,7 +179,8 @@ .SH HISTORY
 .TP
 .BR aligned_alloc ()
 glibc 2.16.
-C11.
+C11,
+POSIX.1-2024.
 .TP
 .BR posix_memalign ()
 glibc 2.1.91.
-- 
2.51.0

[PATCH v1 06/12] man/man3/{posix_,}memalign.3: Split memalign() from posix_memalign(3)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/memalign.3       | 77 ++++++++++++++++++++++++++++++++++++++-
 man/man3/posix_memalign.3 | 46 ++---------------------
 2 files changed, 79 insertions(+), 44 deletions(-)

diff --git a/man/man3/memalign.3 b/man/man3/memalign.3
index 791d4c801..48f25a09b 100644
--- a/man/man3/memalign.3
+++ b/man/man3/memalign.3
@@ -1 +1,76 @@
-.so man3/posix_memalign.3
+'\" t
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH memalign 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+memalign
+\-
+allocate aligned memory
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <malloc.h>
+.P
+.BI "[[deprecated]] void *memalign(size_t " alignment ", size_t " size );
+.fi
+.SH DESCRIPTION
+.BR memalign ()
+is the same as
+.BR aligned_alloc ().
+Use that instead.
+.\" The behavior of memalign() for size==0 is as for posix_memalign()
+.\" but no standards govern this.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR memalign ()
+T}	Thread safety	MT-Safe
+.TE
+.SH VERSIONS
+On some systems
+.BR memalign ()
+is declared in
+.I <stdlib.h>
+instead of
+.IR <malloc.h> .
+.SH STANDARDS
+None.
+.SH HISTORY
+glibc 2.0.
+SunOS 4.1.3.
+.SH CAVEATS
+.BR memalign ()
+may not check that the
+.I alignment
+argument is correct.
+.P
+Some systems provide no way to reclaim memory allocated with
+.BR memalign ()
+(because one can pass to
+.BR free (3)
+only a pointer obtained from
+.BR malloc (3),
+while, for example,
+.BR memalign ()
+would call
+.BR malloc (3)
+and then align the obtained value).
+The glibc implementation
+allows memory obtained from
+.BR memalign ()
+to be reclaimed with
+.BR free (3).
+.SH SEE ALSO
+.BR aligned_alloc (3)
diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index ecbbd3e7a..3271292b7 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -5,7 +5,7 @@
 .\"
 .TH posix_memalign 3 (date) "Linux man-pages (unreleased)"
 .SH NAME
-posix_memalign, aligned_alloc, memalign, valloc, pvalloc \-
+posix_memalign, aligned_alloc, valloc, pvalloc \-
 allocate aligned memory
 .SH LIBRARY
 Standard C library
@@ -20,7 +20,6 @@ .SH SYNOPSIS
 .P
 .B #include <malloc.h>
 .P
-.BI "[[deprecated]] void *memalign(size_t " alignment ", size_t " size );
 .BI "[[deprecated]] void *pvalloc(size_t " size );
 .fi
 .P
@@ -77,13 +76,6 @@ .SH DESCRIPTION
 The memory address will be a multiple of
 .IR alignment ,
 which must be a power of two.
-.\" The behavior of memalign() for size==0 is as for posix_memalign()
-.\" but no standards govern this.
-.P
-The obsolete function
-.BR memalign ()
-is the same as
-.BR aligned_alloc ().
 .P
 The obsolete function
 .BR valloc ()
@@ -104,7 +96,6 @@ .SH DESCRIPTION
 For all of these functions, the memory is not zeroed.
 .SH RETURN VALUE
 .BR aligned_alloc (),
-.BR memalign (),
 .BR valloc (),
 and
 .BR pvalloc ()
@@ -149,7 +140,6 @@ .SH ATTRIBUTES
 .na
 .nh
 .BR aligned_alloc (),
-.BR memalign (),
 .BR posix_memalign ()
 T}	Thread safety	MT-Safe
 T{
@@ -168,8 +158,6 @@ .SH STANDARDS
 .BR posix_memalign ()
 POSIX.1-2024.
 .TP
-.BR memalign ()
-.TQ
 .BR valloc ()
 None.
 .TP
@@ -186,10 +174,6 @@ .SH HISTORY
 glibc 2.1.91.
 POSIX.1d, POSIX.1-2001.
 .TP
-.BR memalign ()
-glibc 2.0.
-SunOS 4.1.3.
-.TP
 .BR valloc ()
 glibc 2.0.
 3.0BSD.
@@ -205,13 +189,6 @@ .SS Headers
 is declared in
 .IR <stdlib.h> .
 .P
-On some systems
-.BR memalign ()
-is declared in
-.I <stdlib.h>
-instead of
-.IR <malloc.h> .
-.P
 According to SUSv2,
 .BR valloc ()
 is declared in
@@ -236,38 +213,21 @@ .SH NOTES
 verifies that
 .I alignment
 matches the requirements detailed above.
-.BR memalign ()
-may not check that the
-.I alignment
-argument is correct.
 .P
 POSIX requires that memory obtained from
 .BR posix_memalign ()
 can be freed using
 .BR free (3).
 Some systems provide no way to reclaim memory allocated with
-.BR memalign ()
-or
 .BR valloc ()
-(because one can pass to
-.BR free (3)
-only a pointer obtained from
-.BR malloc (3),
-while, for example,
-.BR memalign ()
-would call
-.BR malloc (3)
-and then align the obtained value).
+(see
+.BR memalign (3)).
 .\" Other systems allow passing the result of
 .\" .IR valloc ()
 .\" to
 .\" .IR free (3),
 .\" but not to
 .\" .IR realloc (3).
-The glibc implementation
-allows memory obtained from any of these functions to be
-reclaimed with
-.BR free (3).
 .P
 The glibc
 .BR malloc (3)
-- 
2.51.0

[PATCH v1 07/12] man/man3/{posix_memalign,pvalloc}.3: Split pvalloc() from posix_memalign(3)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 26 ++++-----------------
 man/man3/pvalloc.3        | 49 ++++++++++++++++++++++++++++++++++++++-
 2 files changed, 52 insertions(+), 23 deletions(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index 3271292b7..b3b27e5bb 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -5,7 +5,8 @@
 .\"
 .TH posix_memalign 3 (date) "Linux man-pages (unreleased)"
 .SH NAME
-posix_memalign, aligned_alloc, valloc, pvalloc \-
+posix_memalign, aligned_alloc, valloc
+\-
 allocate aligned memory
 .SH LIBRARY
 Standard C library
@@ -17,10 +18,6 @@ .SH SYNOPSIS
 .BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size );
 .BI "void *aligned_alloc(size_t " alignment ", size_t " size );
 .BI "[[deprecated]] void *valloc(size_t " size );
-.P
-.B #include <malloc.h>
-.P
-.BI "[[deprecated]] void *pvalloc(size_t " size );
 .fi
 .P
 .RS -4
@@ -86,19 +83,11 @@ .SH DESCRIPTION
 It is equivalent to
 .IR "memalign(sysconf(_SC_PAGESIZE),size)" .
 .P
-The obsolete function
-.BR pvalloc ()
-is similar to
-.BR valloc (),
-but rounds the size of the allocation up to
-the next multiple of the system page size.
-.P
 For all of these functions, the memory is not zeroed.
 .SH RETURN VALUE
 .BR aligned_alloc (),
-.BR valloc (),
 and
-.BR pvalloc ()
+.BR valloc ()
 return a pointer to the allocated memory on success.
 On error, NULL is returned, and
 .I errno
@@ -145,8 +134,7 @@ .SH ATTRIBUTES
 T{
 .na
 .nh
-.BR valloc (),
-.BR pvalloc ()
+.BR valloc ()
 T}	Thread safety	MT-Unsafe init
 .TE
 .SH STANDARDS
@@ -160,9 +148,6 @@ .SH STANDARDS
 .TP
 .BR valloc ()
 None.
-.TP
-.BR pvalloc ()
-GNU.
 .SH HISTORY
 .TP
 .BR aligned_alloc ()
@@ -179,9 +164,6 @@ .SH HISTORY
 3.0BSD.
 Documented as obsolete in 4.3BSD,
 and as legacy in SUSv2.
-.TP
-.BR pvalloc ()
-glibc 2.0.
 .\"
 .SS Headers
 Everybody agrees that
diff --git a/man/man3/pvalloc.3 b/man/man3/pvalloc.3
index 791d4c801..2f6e21813 100644
--- a/man/man3/pvalloc.3
+++ b/man/man3/pvalloc.3
@@ -1 +1,48 @@
-.so man3/posix_memalign.3
+'\" t
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pvalloc 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+pvalloc
+\-
+page-sized page-aligned memory allocation
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <malloc.h>
+.P
+.BI "[[deprecated]] void *pvalloc(size_t " size );
+.fi
+.SH DESCRIPTION
+.BR pvalloc ()
+is similar to
+.BR valloc (),
+but rounds the size of the allocation up to
+the next multiple of the system page size.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR pvalloc ()
+T}	Thread safety	MT-Unsafe init
+.TE
+.SH STANDARDS
+GNU.
+.SH HISTORY
+glibc 2.0.
+.SH CAVEATS
+See
+.BR valloc (3).
+.SH SEE ALSO
+.BR valloc (3)
-- 
2.51.0

[PATCH v1 08/12] man/man3/{posix_memalign,valloc}.3: Split valloc() from posix_memalign(3)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 64 ++--------------------------
 man/man3/valloc.3         | 89 ++++++++++++++++++++++++++++++++++++++-
 2 files changed, 91 insertions(+), 62 deletions(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index b3b27e5bb..2f664eb4e 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -5,7 +5,7 @@
 .\"
 .TH posix_memalign 3 (date) "Linux man-pages (unreleased)"
 .SH NAME
-posix_memalign, aligned_alloc, valloc
+posix_memalign, aligned_alloc
 \-
 allocate aligned memory
 .SH LIBRARY
@@ -17,7 +17,6 @@ .SH SYNOPSIS
 .P
 .BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size );
 .BI "void *aligned_alloc(size_t " alignment ", size_t " size );
-.BI "[[deprecated]] void *valloc(size_t " size );
 .fi
 .P
 .RS -4
@@ -34,17 +33,6 @@ .SH SYNOPSIS
 .nf
     _ISOC11_SOURCE
 .fi
-.P
-.BR valloc ():
-.nf
-    Since glibc 2.12:
-        (_XOPEN_SOURCE >= 500) && !(_POSIX_C_SOURCE >= 200112L)
-            || /* glibc >= 2.19: */ _DEFAULT_SOURCE
-            || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
-    Before glibc 2.12:
-        _BSD_SOURCE || _XOPEN_SOURCE >= 500
-.\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
-.fi
 .SH DESCRIPTION
 .BR posix_memalign ()
 allocates
@@ -74,21 +62,10 @@ .SH DESCRIPTION
 .IR alignment ,
 which must be a power of two.
 .P
-The obsolete function
-.BR valloc ()
-allocates
-.I size
-bytes and returns a pointer to the allocated memory.
-The memory address will be a multiple of the page size.
-It is equivalent to
-.IR "memalign(sysconf(_SC_PAGESIZE),size)" .
-.P
 For all of these functions, the memory is not zeroed.
 .SH RETURN VALUE
-.BR aligned_alloc (),
-and
-.BR valloc ()
-return a pointer to the allocated memory on success.
+.BR aligned_alloc ()
+returns a pointer to the allocated memory on success.
 On error, NULL is returned, and
 .I errno
 is set
@@ -131,11 +108,6 @@ .SH ATTRIBUTES
 .BR aligned_alloc (),
 .BR posix_memalign ()
 T}	Thread safety	MT-Safe
-T{
-.na
-.nh
-.BR valloc ()
-T}	Thread safety	MT-Unsafe init
 .TE
 .SH STANDARDS
 .TP
@@ -145,9 +117,6 @@ .SH STANDARDS
 .TP
 .BR posix_memalign ()
 POSIX.1-2024.
-.TP
-.BR valloc ()
-None.
 .SH HISTORY
 .TP
 .BR aligned_alloc ()
@@ -158,29 +127,12 @@ .SH HISTORY
 .BR posix_memalign ()
 glibc 2.1.91.
 POSIX.1d, POSIX.1-2001.
-.TP
-.BR valloc ()
-glibc 2.0.
-3.0BSD.
-Documented as obsolete in 4.3BSD,
-and as legacy in SUSv2.
 .\"
 .SS Headers
 Everybody agrees that
 .BR posix_memalign ()
 is declared in
 .IR <stdlib.h> .
-.P
-According to SUSv2,
-.BR valloc ()
-is declared in
-.IR <stdlib.h> .
-.\" Libc4,5 and
-glibc declares it in
-.IR <malloc.h> ,
-and also in
-.I <stdlib.h>
-if suitable feature test macros are defined (see above).
 .SH NOTES
 On many systems there are alignment restrictions, for example, on buffers
 used for direct block device I/O.
@@ -200,16 +152,6 @@ .SH NOTES
 .BR posix_memalign ()
 can be freed using
 .BR free (3).
-Some systems provide no way to reclaim memory allocated with
-.BR valloc ()
-(see
-.BR memalign (3)).
-.\" Other systems allow passing the result of
-.\" .IR valloc ()
-.\" to
-.\" .IR free (3),
-.\" but not to
-.\" .IR realloc (3).
 .P
 The glibc
 .BR malloc (3)
diff --git a/man/man3/valloc.3 b/man/man3/valloc.3
index 791d4c801..cc3543612 100644
--- a/man/man3/valloc.3
+++ b/man/man3/valloc.3
@@ -1 +1,88 @@
-.so man3/posix_memalign.3
+'\" t
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH valloc 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+valloc
+\-
+page-aligned memory allocation
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdlib.h>
+.P
+.BI "[[deprecated]] void *valloc(size_t " size );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR valloc ():
+.nf
+    Since glibc 2.12:
+        (_XOPEN_SOURCE >= 500) && !(_POSIX_C_SOURCE >= 200112L)
+            || /* glibc >= 2.19: */ _DEFAULT_SOURCE
+            || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
+    Before glibc 2.12:
+        _BSD_SOURCE || _XOPEN_SOURCE >= 500
+.\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
+.fi
+.SH DESCRIPTION
+.BR valloc ()
+allocates
+.I size
+bytes and returns a pointer to the allocated memory.
+The memory address will be a multiple of the page size.
+.P
+It is equivalent to
+.IR "memalign(sysconf(_SC_PAGESIZE),size)" .
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR valloc ()
+T}	Thread safety	MT-Unsafe init
+.TE
+.SH VERSIONS
+According to SUSv2,
+.BR valloc ()
+is declared in
+.IR <stdlib.h> .
+.\" Libc4,5 and
+glibc declares it in
+.IR <malloc.h> ,
+and also in
+.I <stdlib.h>
+if suitable feature test macros are defined (see above).
+.SH STANDARDS
+BSD, GNU.
+.SH HISTORY
+glibc 2.0.
+3.0BSD.
+Documented as obsolete in 4.3BSD,
+and as legacy in SUSv2.
+.\"
+.SH CAVEATS
+See
+.BR memalign (3).
+.\" Other systems allow passing the result of
+.\" .IR valloc ()
+.\" to
+.\" .IR free (3),
+.\" but not to
+.\" .IR realloc (3).
+.SH SEE ALSO
+.BR memalign (3)
-- 
2.51.0

[PATCH v1 09/12] man/man3/{aligned_alloc,posix_memalign}.3: Split aligned_alloc() from posix_memalign(3)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/aligned_alloc.3  | 99 ++++++++++++++++++++++++++++++++++++++-
 man/man3/posix_memalign.3 | 56 +++-------------------
 2 files changed, 105 insertions(+), 50 deletions(-)

diff --git a/man/man3/aligned_alloc.3 b/man/man3/aligned_alloc.3
index 791d4c801..cdc9ba1a2 100644
--- a/man/man3/aligned_alloc.3
+++ b/man/man3/aligned_alloc.3
@@ -1 +1,98 @@
-.so man3/posix_memalign.3
+'\" t
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH aligned_alloc 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+aligned_alloc
+\-
+allocate aligned memory
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdlib.h>
+.P
+.BI "void *aligned_alloc(size_t " alignment ", size_t " size );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR aligned_alloc ():
+.nf
+    _ISOC11_SOURCE
+.fi
+.SH DESCRIPTION
+.BR aligned_alloc ()
+allocates
+.I size
+bytes and returns a pointer to the allocated memory.
+The memory address will be a multiple of
+.IR alignment ,
+which must be a power of two.
+This address can later be successfully passed to
+.BR free (3).
+.P
+The memory is not zeroed.
+.SH RETURN VALUE
+.BR aligned_alloc ()
+returns a pointer to the allocated memory on success.
+On error, NULL is returned, and
+.I errno
+is set
+to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+The
+.I alignment
+argument was not a power of two.
+.TP
+.B ENOMEM
+Out of memory.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR aligned_alloc ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+C23,
+POSIX.1-2024.
+.SH HISTORY
+glibc 2.16.
+C11,
+POSIX.1-2024.
+.SH NOTES
+On many systems there are alignment restrictions, for example, on buffers
+used for direct block device I/O.
+POSIX specifies the
+.I "pathconf(path,_PC_REC_XFER_ALIGN)"
+call that tells what alignment is needed.
+Now one can use
+.BR aligned_alloc ()
+to satisfy this requirement.
+.P
+The glibc
+.BR malloc (3)
+always returns 8-byte aligned memory addresses,
+so this function is needed
+only if you require larger alignment values.
+.SH SEE ALSO
+.BR brk (2),
+.BR getpagesize (2),
+.BR free (3),
+.BR malloc (3)
diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index 2f664eb4e..8b3258dc2 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -5,7 +5,7 @@
 .\"
 .TH posix_memalign 3 (date) "Linux man-pages (unreleased)"
 .SH NAME
-posix_memalign, aligned_alloc
+posix_memalign
 \-
 allocate aligned memory
 .SH LIBRARY
@@ -16,7 +16,6 @@ .SH SYNOPSIS
 .B #include <stdlib.h>
 .P
 .BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size );
-.BI "void *aligned_alloc(size_t " alignment ", size_t " size );
 .fi
 .P
 .RS -4
@@ -28,11 +27,6 @@ .SH SYNOPSIS
 .nf
     _POSIX_C_SOURCE >= 200112L
 .fi
-.P
-.BR aligned_alloc ():
-.nf
-    _ISOC11_SOURCE
-.fi
 .SH DESCRIPTION
 .BR posix_memalign ()
 allocates
@@ -54,23 +48,13 @@ .SH DESCRIPTION
 .\" glibc does this:
 or a unique pointer value.
 .P
-.BR aligned_alloc ()
-allocates
-.I size
-bytes and returns a pointer to the allocated memory.
-The memory address will be a multiple of
-.IR alignment ,
-which must be a power of two.
+The memory is not zeroed.
 .P
-For all of these functions, the memory is not zeroed.
+.BR aligned_alloc (3)
+is a standard function that provides the same functionality,
+and has a more ergonomic prototype.
+Use that instead.
 .SH RETURN VALUE
-.BR aligned_alloc ()
-returns a pointer to the allocated memory on success.
-On error, NULL is returned, and
-.I errno
-is set
-to indicate the error.
-.P
 .BR posix_memalign ()
 returns zero on success, or one of the error values listed in the
 next section on failure.
@@ -105,26 +89,12 @@ .SH ATTRIBUTES
 T{
 .na
 .nh
-.BR aligned_alloc (),
 .BR posix_memalign ()
 T}	Thread safety	MT-Safe
 .TE
 .SH STANDARDS
-.TP
-.BR aligned_alloc ()
-C23,
-POSIX.1-2024.
-.TP
-.BR posix_memalign ()
 POSIX.1-2024.
 .SH HISTORY
-.TP
-.BR aligned_alloc ()
-glibc 2.16.
-C11,
-POSIX.1-2024.
-.TP
-.BR posix_memalign ()
 glibc 2.1.91.
 POSIX.1d, POSIX.1-2001.
 .\"
@@ -134,15 +104,6 @@ .SS Headers
 is declared in
 .IR <stdlib.h> .
 .SH NOTES
-On many systems there are alignment restrictions, for example, on buffers
-used for direct block device I/O.
-POSIX specifies the
-.I "pathconf(path,_PC_REC_XFER_ALIGN)"
-call that tells what alignment is needed.
-Now one can use
-.BR posix_memalign ()
-to satisfy this requirement.
-.P
 .BR posix_memalign ()
 verifies that
 .I alignment
@@ -158,7 +119,4 @@ .SH NOTES
 always returns 8-byte aligned memory addresses, so these functions are
 needed only if you require larger alignment values.
 .SH SEE ALSO
-.BR brk (2),
-.BR getpagesize (2),
-.BR free (3),
-.BR malloc (3)
+.BR aligned_alloc (3)
-- 
2.51.0

[PATCH v1 10/12] man/man3/posix_memalign.3: CAVEATS: Add section, and move paragraph to it

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index 8b3258dc2..c2816e1d4 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -61,13 +61,6 @@ .SH RETURN VALUE
 The value of
 .I errno
 is not set.
-On Linux (and other systems),
-.BR posix_memalign ()
-does not modify
-.I memptr
-on failure.
-A requirement standardizing this behavior was added in POSIX.1-2008 TC2.
-.\" http://austingroupbugs.net/view.php?id=520
 .SH ERRORS
 .TP
 .B EINVAL
@@ -118,5 +111,13 @@ .SH NOTES
 .BR malloc (3)
 always returns 8-byte aligned memory addresses, so these functions are
 needed only if you require larger alignment values.
+.SH CAVEATS
+On Linux (and other systems),
+.BR posix_memalign ()
+does not modify
+.I memptr
+on failure.
+A requirement standardizing this behavior was added in POSIX.1-2008 TC2.
+.\" http://austingroupbugs.net/view.php?id=520
 .SH SEE ALSO
 .BR aligned_alloc (3)
-- 
2.51.0

[PATCH v1 11/12] man/man3/posix_memalign.3: Remove redundant text

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 16 ----------------
 1 file changed, 16 deletions(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index c2816e1d4..fd76895a9 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -90,23 +90,7 @@ .SH STANDARDS
 .SH HISTORY
 glibc 2.1.91.
 POSIX.1d, POSIX.1-2001.
-.\"
-.SS Headers
-Everybody agrees that
-.BR posix_memalign ()
-is declared in
-.IR <stdlib.h> .
 .SH NOTES
-.BR posix_memalign ()
-verifies that
-.I alignment
-matches the requirements detailed above.
-.P
-POSIX requires that memory obtained from
-.BR posix_memalign ()
-can be freed using
-.BR free (3).
-.P
 The glibc
 .BR malloc (3)
 always returns 8-byte aligned memory addresses, so these functions are
-- 
2.51.0

[PATCH v1 12/12] man/man3/posix_memalign.3: NOTES: Remove superfluous section

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index fd76895a9..5600f7978 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -90,11 +90,6 @@ .SH STANDARDS
 .SH HISTORY
 glibc 2.1.91.
 POSIX.1d, POSIX.1-2001.
-.SH NOTES
-The glibc
-.BR malloc (3)
-always returns 8-byte aligned memory addresses, so these functions are
-needed only if you require larger alignment values.
 .SH CAVEATS
 On Linux (and other systems),
 .BR posix_memalign ()
-- 
2.51.0

Re: [PATCH v1 00/12] man/man3/posix_memalign.3: Several fixes, and split the page

[Eugene Syromyatnikov]

On Wed, Dec 10, 2025 at 1:40 PM Alejandro Colomar <alx@kernel.org> wrote:
> From all of these functions, ISO C's aligned_alloc(3) is the only one
> that programmers should be using.

I strongly disagree with this assessment; moreover,  I'd argue that
this is the function that people should avoid, due to its
inconsistent;y defined behavior in various versions of the standard,
and due to its limitation of size being multiple of alignment, that
renders it useless for the vast majority of use cases.

-- 
Eugene Syromyatnikov
mailto:evgsyr@gmail.com
xmpp:esyr@jabber.{ru|org}

Re: [PATCH v1 00/12] man/man3/posix_memalign.3: Several fixes, and split the page

[Alejandro Colomar]

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

Hi Eugene,

On Wed, Dec 10, 2025 at 05:29:39PM +0100, Eugene Syromyatnikov wrote:
> On Wed, Dec 10, 2025 at 1:40 PM Alejandro Colomar <alx@kernel.org> wrote:
> > From all of these functions, ISO C's aligned_alloc(3) is the only one
> > that programmers should be using.
> 
> I strongly disagree with this assessment; moreover,  I'd argue that
> this is the function that people should avoid, due to its
> inconsistent;y defined behavior in various versions of the standard,

The only standard that was different was C11, but C17 --which is a bug
fix, and thus, the same standard-- fixed that, and the standard has been
consistent ever since.

All known implementations conform to C17 and C23.

posix_memalign(3) is terrible, because it takes a void**, which requires
a cast.

memalign(3) is okay, except that it need not report invalid alignments.

> and due to its limitation of size being multiple of alignment, that
> renders it useless for the vast majority of use cases.

That limitation doesn't exist.  It was a bug in C11.

Both musl and glibc seem okay:

	alx@devuan:~$ grepc -tfd aligned_alloc ~/src/gnu/glibc/master/
	/home/alx/src/gnu/glibc/master/malloc/malloc.c:void *
	weak_function
	aligned_alloc (size_t alignment, size_t bytes)
	{
	/* Similar to memalign, but starting with ISO C17 the standard
	   requires an error for alignments that are not supported by the
	   implementation.  Valid alignments for the current implementation
	   are non-negative powers of two.  */
	  if (!powerof2 (alignment) || alignment == 0)
	    {
	      __set_errno (EINVAL);
	      return NULL;
	    }

	  return _mid_memalign (alignment, bytes);
	}
	alx@devuan:~$ grepc -tfd memalign ~/src/musl/libc/master/
	/home/alx/src/musl/libc/master/src/malloc/memalign.c:void *memalign(size_t align, size_t len)
	{
		return aligned_alloc(align, len);
	}

Prior to that implementation, glibc had aligned_alloc(3) as an alias for
memalign(3).


Have a lovely night!
Alex

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

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

Re: [PATCH v1 00/12] man/man3/posix_memalign.3: Several fixes, and split the page

[Eugene Syromyatnikov]

On Wed, Dec 10, 2025 at 6:12 PM Alejandro Colomar <alx@kernel.org> wrote:
>
> Hi Eugene,
>
> On Wed, Dec 10, 2025 at 05:29:39PM +0100, Eugene Syromyatnikov wrote:
> > On Wed, Dec 10, 2025 at 1:40 PM Alejandro Colomar <alx@kernel.org> wrote:
> > > From all of these functions, ISO C's aligned_alloc(3) is the only one
> > > that programmers should be using.
> >
> > I strongly disagree with this assessment; moreover,  I'd argue that
> > this is the function that people should avoid, due to its
> > inconsistent;y defined behavior in various versions of the standard,
>
> The only standard that was different was C11, but C17 --which is a bug
> fix, and thus, the same standard-- fixed that, and the standard has been
> consistent ever since.
>
> All known implementations conform to C17 and C23.

So, you see, here lies a problem, conforming to which standard? As an
application developer, I don't know whether requesting a large
alignment would lead to success, failure, or rm-rf-ing my whole system
(as the standard specified UB in that case before DR460[1]) by a
"conforming" libc implementation, because libc, generally, is out of
my control;  so, in reality, I'm only limited to alignments that are
divisors of the object size for "safe" use, which renders the function
useless for practical purposes. The fact that the definition of
restrictions has changed so many times and so wildly renders it so
toxic that I'd advise against using it in the foreseeable future and
just stick to posix_memalign, despite its peculiarities in terms of
argument handling. The other aspect (which is irrelevant to this
discussion, but doesn't adds points to aligned_alloc in terms of
practical usability) is that MS CRT doesn't support it at all because
it is oh so special in terms of aligned allocations.

[1] https://open-std.org/JTC1/SC22/WG14/www/docs/summary.htm#dr_460

> posix_memalign(3) is terrible, because it takes a void**, which requires
> a cast.
>
> memalign(3) is okay, except that it need not report invalid alignments.
>
> > and due to its limitation of size being multiple of alignment, that
> > renders it useless for the vast majority of use cases.
>
> That limitation doesn't exist.  It was a bug in C11.
>
> Both musl and glibc seem okay:
>
>         alx@devuan:~$ grepc -tfd aligned_alloc ~/src/gnu/glibc/master/
>         /home/alx/src/gnu/glibc/master/malloc/malloc.c:void *
>         weak_function
>         aligned_alloc (size_t alignment, size_t bytes)
>         {
>         /* Similar to memalign, but starting with ISO C17 the standard
>            requires an error for alignments that are not supported by the
>            implementation.  Valid alignments for the current implementation
>            are non-negative powers of two.  */
>           if (!powerof2 (alignment) || alignment == 0)
>             {
>               __set_errno (EINVAL);
>               return NULL;
>             }
>
>           return _mid_memalign (alignment, bytes);
>         }
>         alx@devuan:~$ grepc -tfd memalign ~/src/musl/libc/master/
>         /home/alx/src/musl/libc/master/src/malloc/memalign.c:void *memalign(size_t align, size_t len)
>         {
>                 return aligned_alloc(align, len);
>         }

OpenBSD's libc isn't:
https://github.com/openbsd/src/blob/master/lib/libc/stdlib/malloc.c#L2336

And it is understandable, since at some point it was *mandated* to
fail in this case, and not be permissive.

I know it's likely outside linux-man's purview, but it's definitely
something to consider for portable application developers.

> Prior to that implementation, glibc had aligned_alloc(3) as an alias for
> memalign(3).
>
>
> Have a lovely night!
> Alex
>
> --
> <https://www.alejandro-colomar.es>



-- 
Eugene Syromyatnikov
mailto:evgsyr@gmail.com
xmpp:esyr@jabber.{ru|org}

Re: [PATCH v1 00/12] man/man3/posix_memalign.3: Several fixes, and split the page

[Alejandro Colomar]

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

[CC += Ingo]

Hi Eugene, Ingo,

On Wed, Dec 10, 2025 at 11:50:33PM +0100, Eugene Syromyatnikov wrote:
> On Wed, Dec 10, 2025 at 6:12 PM Alejandro Colomar <alx@kernel.org> wrote:
[...]

> > posix_memalign(3) is terrible, because it takes a void**, which requires
> > a cast.
> >
> > memalign(3) is okay, except that it need not report invalid alignments.
> >
> > > and due to its limitation of size being multiple of alignment, that
> > > renders it useless for the vast majority of use cases.
> >
> > That limitation doesn't exist.  It was a bug in C11.
> >
> > Both musl and glibc seem okay:
> >
> >         alx@devuan:~$ grepc -tfd aligned_alloc ~/src/gnu/glibc/master/
> >         /home/alx/src/gnu/glibc/master/malloc/malloc.c:void *
> >         weak_function
> >         aligned_alloc (size_t alignment, size_t bytes)
> >         {
> >         /* Similar to memalign, but starting with ISO C17 the standard
> >            requires an error for alignments that are not supported by the
> >            implementation.  Valid alignments for the current implementation
> >            are non-negative powers of two.  */
> >           if (!powerof2 (alignment) || alignment == 0)
> >             {
> >               __set_errno (EINVAL);
> >               return NULL;
> >             }
> >
> >           return _mid_memalign (alignment, bytes);
> >         }
> >         alx@devuan:~$ grepc -tfd memalign ~/src/musl/libc/master/
> >         /home/alx/src/musl/libc/master/src/malloc/memalign.c:void *memalign(size_t align, size_t len)
> >         {
> >                 return aligned_alloc(align, len);
> >         }
> 
> OpenBSD's libc isn't:
> https://github.com/openbsd/src/blob/master/lib/libc/stdlib/malloc.c#L2336
> 
> And it is understandable, since at some point it was *mandated* to
> fail in this case, and not be permissive.
> 
> I know it's likely outside linux-man's purview, but it's definitely
> something to consider for portable application developers.

Hmmm, we didn't know of that.  I asked back when the page was patched if
anyone knew of any system that implemented the C11 behavior, and nobody
knew about any such.  Thanks!

That is definitely something that we should document in this project.
I'll prepare a patch.

> > Prior to that implementation, glibc had aligned_alloc(3) as an alias for
> > memalign(3).

[...]
[Reordered]

> > On Wed, Dec 10, 2025 at 05:29:39PM +0100, Eugene Syromyatnikov wrote:
> > > On Wed, Dec 10, 2025 at 1:40 PM Alejandro Colomar <alx@kernel.org> wrote:
> > > > From all of these functions, ISO C's aligned_alloc(3) is the only one
> > > > that programmers should be using.
> > >
> > > I strongly disagree with this assessment; moreover,  I'd argue that
> > > this is the function that people should avoid, due to its
> > > inconsistent;y defined behavior in various versions of the standard,
> >
> > The only standard that was different was C11, but C17 --which is a bug
> > fix, and thus, the same standard-- fixed that, and the standard has been
> > consistent ever since.
> >
> > All known implementations conform to C17 and C23.
> 
> So, you see, here lies a problem, conforming to which standard? As an
> application developer, I don't know whether requesting a large
> alignment would lead to success, failure, or rm-rf-ing my whole system
> (as the standard specified UB in that case before DR460[1]) by a
> "conforming" libc implementation, because libc, generally, is out of
> my control;

If noone had ever implemented C11, we could have treated it as
hypothetical UB.  But since you showed that OpenBSD has implemented it,
we do have a problem.

The good news is that it just fails.  So far, no implementation has UB;
it's only theoretical, and after the DR fixes, no new implementation
should ever implement it with UB.

Ingo, OpenBSD seems to be implementing C11's aligned_alloc(3).  Would
you mind checking if implementing the latest revision of
aligned_alloc(3) is a possibility in OpenBSD?  C17 had important
changes, which remain in C23, and have also been standardized by
POSIX.1-2024.

>  so, in reality, I'm only limited to alignments that are
> divisors of the object size for "safe" use, which renders the function
> useless for practical purposes. The fact that the definition of
> restrictions has changed so many times and so wildly renders it so
> toxic that I'd advise against using it in the foreseeable future and
> just stick to posix_memalign, despite its peculiarities in terms of
> argument handling.

After seeing this new information, I agree with you that
posix_memalign(3) seems more portable.

Maybe the manual page could show a wrapper to workaround the ugly API of
posix_memalign(3):

	static inline void *
	my_posix_memalign(size_t alignment, size_t size)
	{
		int   e;
		void  *p;

		e = posix_memalign(&p, alignment, size);
		if (e != 0) {
			errno = e;
			return NULL;
		}

		return p;
	}

> The other aspect (which is irrelevant to this
> discussion, but doesn't adds points to aligned_alloc in terms of
> practical usability) is that MS CRT doesn't support it at all because
> it is oh so special in terms of aligned allocations.

Does MS support posix_memalign(3)?  What's the problem with
aligned_alloc(3)?

> 
> [1] https://open-std.org/JTC1/SC22/WG14/www/docs/summary.htm#dr_460
> 


Have a lovely night!
Alex

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

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

Re: [PATCH v1 00/12] man/man3/posix_memalign.3: Several fixes, and split the page

[Eugene Syromyatnikov]

On Thu, Dec 11, 2025 at 1:04 AM Alejandro Colomar <alx@kernel.org> wrote:
>
> [CC += Ingo]
>
> Hi Eugene, Ingo,
>
> The good news is that it just fails.  So far, no implementation has UB;
> it's only theoretical, and after the DR fixes, no new implementation
> should ever implement it with UB.

I do recognise your point (and, from a practical point of view,
aligned_alloc() is most likely fine on Linux), but still think (and
thus want to re-iterate) that the fact that at some point in time it
was, in accordance with standard, UB and, consequently, there could be
an optimising compiler that treated it as such, warrants a portability
note.

> Maybe the manual page could show a wrapper to workaround the ugly API of
> posix_memalign(3):
>
>         static inline void *
>         my_posix_memalign(size_t alignment, size_t size)
>         {
>                 int   e;
>                 void  *p;
>
>                 e = posix_memalign(&p, alignment, size);
>                 if (e != 0) {
>                         errno = e;
>                         return NULL;
>                 }
>
>                 return p;
>         }

Uff, in terms of wrappers, it's difficult for me to advocate for
something, as there are many aspects in that:
 - To some, returning an error can be a preferable interface.
 - Some may want a bit more fool-proofing (like allowing alignments
less than sizeof(void *) or guaranteed upper bound for possible
alignments).
 - Some may want some fallback built-in, and that fallback also may
differ based on whether alignment is seen as a hint or as a
requirement.

For example, OpenSSL implements its own wrapper,
OPENSSL_aligned_alloc()[1], which is, well, some mix of the above
(with the spice of non-POSIX-platform support).

Personally, I don't see the choices made for posix_memalign() as
outright bad (for example, pthread has generally the similar
interface), just peculiar in the overarching context of other existing
memory allocating functions; however, if you want to suggest some
minimal wrapper to make it in line with the rest, I don't see any
particular flaws in the proposed code right away, looks good to me.

> > The other aspect (which is irrelevant to this
> > discussion, but doesn't adds points to aligned_alloc in terms of
> > practical usability) is that MS CRT doesn't support it at all because
> > it is oh so special in terms of aligned allocations.
>
> Does MS support posix_memalign(3)?

No.

> What's the problem with aligned_alloc(3)?

As far as I'm aware, MS CRT does not implement it;  there is
_aligned_malloc()[2], which returns pointers that are supposed to be
freed with _aligned_free()[3], and, I guess, it hints at the ways it
is implemented and the reasons aligned_alloc() is not provided.

[1] https://docs.openssl.org/master/man3/OPENSSL_malloc/
    Also, check the HISTORY section there.
[2] https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/aligned-malloc?view=msvc-170
[3] https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/aligned-free?view=msvc-170

-- 
Eugene Syromyatnikov
mailto:evgsyr@gmail.com
xmpp:esyr@jabber.{ru|org}

Re: [PATCH v1 00/12] man/man3/posix_memalign.3: Several fixes, and split the page

[Alejandro Colomar]

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

Hi Eugene,

On Thu, Dec 11, 2025 at 04:46:03AM +0100, Eugene Syromyatnikov wrote:
> On Thu, Dec 11, 2025 at 1:04 AM Alejandro Colomar <alx@kernel.org> wrote:
> >
> > [CC += Ingo]
> >
> > Hi Eugene, Ingo,
> >
> > The good news is that it just fails.  So far, no implementation has UB;
> > it's only theoretical, and after the DR fixes, no new implementation
> > should ever implement it with UB.
> 
> I do recognise your point (and, from a practical point of view,
> aligned_alloc() is most likely fine on Linux), but still think (and
> thus want to re-iterate) that the fact that at some point in time it
> was, in accordance with standard, UB and, consequently, there could be
> an optimising compiler that treated it as such, warrants a portability
> note.

Makes sense.  Although I expect such an optimizer to come directly from
Hell.  :)

> > Maybe the manual page could show a wrapper to workaround the ugly API of
> > posix_memalign(3):
> >
> >         static inline void *
> >         my_posix_memalign(size_t alignment, size_t size)
> >         {
> >                 int   e;
> >                 void  *p;
> >
> >                 e = posix_memalign(&p, alignment, size);
> >                 if (e != 0) {
> >                         errno = e;
> >                         return NULL;
> >                 }
> >
> >                 return p;
> >         }
> 
> Uff, in terms of wrappers, it's difficult for me to advocate for
> something, as there are many aspects in that:
>  - To some, returning an error can be a preferable interface.
>  - Some may want a bit more fool-proofing (like allowing alignments
> less than sizeof(void *) or guaranteed upper bound for possible
> alignments).
>  - Some may want some fallback built-in, and that fallback also may
> differ based on whether alignment is seen as a hint or as a
> requirement.
> 
> For example, OpenSSL implements its own wrapper,
> OPENSSL_aligned_alloc()[1], which is, well, some mix of the above
> (with the spice of non-POSIX-platform support).

Hmmm.

> 
> Personally, I don't see the choices made for posix_memalign() as
> outright bad (for example, pthread has generally the similar
> interface), just peculiar in the overarching context of other existing
> memory allocating functions; however, if you want to suggest some
> minimal wrapper to make it in line with the rest, I don't see any
> particular flaws in the proposed code right away, looks good to me.

Or maybe better say nothing.  I think I'll imply that aligned_alloc(3)
is the right API to use, without explicitly stating it.

After all, it should be fine; it will have spurious errors in OpenBSD
and maybe others, but I don't expect it to be worse than that.

> > > The other aspect (which is irrelevant to this
> > > discussion, but doesn't adds points to aligned_alloc in terms of
> > > practical usability) is that MS CRT doesn't support it at all because
> > > it is oh so special in terms of aligned allocations.
> >
> > Does MS support posix_memalign(3)?
> 
> No.
> 
> > What's the problem with aligned_alloc(3)?
> 
> As far as I'm aware, MS CRT does not implement it;  there is
> _aligned_malloc()[2], which returns pointers that are supposed to be
> freed with _aligned_free()[3], and, I guess, it hints at the ways it
> is implemented and the reasons aligned_alloc() is not provided.

Ughh, I see.  MS is indeed oh so special.  :)

> 
> [1] https://docs.openssl.org/master/man3/OPENSSL_malloc/
>     Also, check the HISTORY section there.
> [2] https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/aligned-malloc?view=msvc-170
> [3] https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/aligned-free?view=msvc-170

Thanks!


Have a lovely day!
Alex

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

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

[PATCH v2 00/14] man/man3/posix_memalign.3: Several fixes, and split the page

[Alejandro Colomar]

Hi!

In v2, I've removed the explicit sentence saying that one should use
aligned_alloc(3) instead of memalign(3).

I've also documented that C11 had a bogus specification for
aligned_alloc(3), and that OpenBSD still implements that (although at
least, they don't exploit the UB).  I've CCed them, in case they're not
aware that C17 fixed those issues.

I've documented that while the C11 specification had a lot of UB, no
implementation has ever implemented that, and so it's just theoretical
(and thankfully extinct) UB.

Apart from that, there are minor wording tweaks.

See the range-diff below.


Have a lovely day!
Alex


Alejandro Colomar (14):
  man/man3/posix_memalign.3: Remove confusing exception
  man/man3/posix_memalign.3: wfix
  man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to C17,
    not C11
  man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to C23
  man/man3/posix_memalign.3: STANDARDS: aligned_alloc() and
    posix_memalign() conform to POSIX.1-2024
  man/man3/{posix_,}memalign.3: Split memalign() from posix_memalign(3)
  man/man3/{posix_memalign,pvalloc}.3: Split pvalloc() from
    posix_memalign(3)
  man/man3/{posix_memalign,valloc}.3: Split valloc() from
    posix_memalign(3)
  man/man3/{aligned_alloc,posix_memalign}.3: Split aligned_alloc() from
    posix_memalign(3)
  man/man3/posix_memalign.3: CAVEATS: Add section, and move paragraph to
    it
  man/man3/posix_memalign.3: Remove redundant text
  man/man3/posix_memalign.3: NOTES: Remove superfluous section
  man/man3/memalign.3: wfix
  man/man3/aligned_alloc.3: HISTORY: Document bogus specification from
    C11

 man/man3/aligned_alloc.3  | 128 ++++++++++++++++++++++-
 man/man3/memalign.3       |  77 +++++++++++++-
 man/man3/posix_memalign.3 | 211 +++-----------------------------------
 man/man3/pvalloc.3        |  49 ++++++++-
 man/man3/valloc.3         |  89 +++++++++++++++-
 5 files changed, 355 insertions(+), 199 deletions(-)

Range-diff against v1:
 1:  90f18b452 =  1:  90f18b452 man/man3/posix_memalign.3: Remove confusing exception
 2:  19b5ea61e =  2:  19b5ea61e man/man3/posix_memalign.3: wfix
 3:  95f523f48 !  3:  82bcf3b0f man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to ISO C17, not C11
    @@ Metadata
     Author: Alejandro Colomar <alx@kernel.org>
     
      ## Commit message ##
    -    man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to ISO C17, not C11
    +    man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to C17, not C11
     
         ISO C17 removed a restriction that was in place in C11.  This
         documentation doesn't conform to C11; it conforms to C17.
 4:  9db9d670c =  4:  04f5087e5 man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to C23
 5:  032768ed7 =  5:  c8ffb2124 man/man3/posix_memalign.3: STANDARDS: aligned_alloc() and posix_memalign() conform to POSIX.1-2024
 6:  de49191b8 !  6:  51b7f9f43 man/man3/{posix_,}memalign.3: Split memalign() from posix_memalign(3)
    @@ man/man3/memalign.3
     +.SH DESCRIPTION
     +.BR memalign ()
     +is the same as
    -+.BR aligned_alloc ().
    -+Use that instead.
    ++.BR aligned_alloc (3).
     +.\" The behavior of memalign() for size==0 is as for posix_memalign()
     +.\" but no standards govern this.
     +.SH ATTRIBUTES
 7:  af29aac57 =  7:  a60d6283f man/man3/{posix_memalign,pvalloc}.3: Split pvalloc() from posix_memalign(3)
 8:  03408db2f =  8:  126c39d0f man/man3/{posix_memalign,valloc}.3: Split valloc() from posix_memalign(3)
 9:  6da397d5c =  9:  b23cb7bc6 man/man3/{aligned_alloc,posix_memalign}.3: Split aligned_alloc() from posix_memalign(3)
10:  213710d2c = 10:  1e5a0260e man/man3/posix_memalign.3: CAVEATS: Add section, and move paragraph to it
11:  7960911fc = 11:  c0b9fd96a man/man3/posix_memalign.3: Remove redundant text
12:  54e7d20ee = 12:  34d984534 man/man3/posix_memalign.3: NOTES: Remove superfluous section
 -:  --------- > 13:  a5342ef55 man/man3/memalign.3: wfix
 -:  --------- > 14:  cdfc42078 man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
-- 
2.51.0

[PATCH v2 01/14] man/man3/posix_memalign.3: Remove confusing exception

[Alejandro Colomar]

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>
---
 man/man3/posix_memalign.3 | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

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 ()
-- 
2.51.0

[PATCH v2 02/14] man/man3/posix_memalign.3: wfix

[Alejandro Colomar]

Document aligned_alloc(3), and then say memalign(3) is equivalent,
instead of the other way around.  aligned_alloc(3) is the important one.

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index 9c4a0bff9..4cf63d283 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -70,8 +70,7 @@ .SH DESCRIPTION
 .\" glibc does this:
 or a unique pointer value.
 .P
-The obsolete function
-.BR memalign ()
+.BR aligned_alloc ()
 allocates
 .I size
 bytes and returns a pointer to the allocated memory.
@@ -81,9 +80,10 @@ .SH DESCRIPTION
 .\" The behavior of memalign() for size==0 is as for posix_memalign()
 .\" but no standards govern this.
 .P
-.BR aligned_alloc ()
+The obsolete function
+.BR memalign ()
 is the same as
-.BR memalign ().
+.BR aligned_alloc ().
 .P
 The obsolete function
 .BR valloc ()
-- 
2.51.0

[PATCH v2 03/14] man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to C17, not C11

[Alejandro Colomar]

ISO C17 removed a restriction that was in place in C11.  This
documentation doesn't conform to C11; it conforms to 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>
---
 man/man3/posix_memalign.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index 4cf63d283..d0adaab01 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -162,7 +162,7 @@ .SH ATTRIBUTES
 .SH STANDARDS
 .TP
 .BR aligned_alloc ()
-C11.
+C17.
 .TP
 .BR posix_memalign ()
 POSIX.1-2008.
-- 
2.51.0

[PATCH v2 04/14] man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to C23

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index d0adaab01..ba99f0c6a 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -162,7 +162,7 @@ .SH ATTRIBUTES
 .SH STANDARDS
 .TP
 .BR aligned_alloc ()
-C17.
+C23.
 .TP
 .BR posix_memalign ()
 POSIX.1-2008.
-- 
2.51.0

[PATCH v2 05/14] man/man3/posix_memalign.3: STANDARDS: aligned_alloc() and posix_memalign() conform to POSIX.1-2024

[Alejandro Colomar]

Cc: Seth McDonald <sethmcmail@pm.me>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index ba99f0c6a..ecbbd3e7a 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -162,10 +162,11 @@ .SH ATTRIBUTES
 .SH STANDARDS
 .TP
 .BR aligned_alloc ()
-C23.
+C23,
+POSIX.1-2024.
 .TP
 .BR posix_memalign ()
-POSIX.1-2008.
+POSIX.1-2024.
 .TP
 .BR memalign ()
 .TQ
@@ -178,7 +179,8 @@ .SH HISTORY
 .TP
 .BR aligned_alloc ()
 glibc 2.16.
-C11.
+C11,
+POSIX.1-2024.
 .TP
 .BR posix_memalign ()
 glibc 2.1.91.
-- 
2.51.0

[PATCH v2 06/14] man/man3/{posix_,}memalign.3: Split memalign() from posix_memalign(3)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/memalign.3       | 76 ++++++++++++++++++++++++++++++++++++++-
 man/man3/posix_memalign.3 | 46 ++----------------------
 2 files changed, 78 insertions(+), 44 deletions(-)

diff --git a/man/man3/memalign.3 b/man/man3/memalign.3
index 791d4c801..cc341be7b 100644
--- a/man/man3/memalign.3
+++ b/man/man3/memalign.3
@@ -1 +1,75 @@
-.so man3/posix_memalign.3
+'\" t
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH memalign 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+memalign
+\-
+allocate aligned memory
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <malloc.h>
+.P
+.BI "[[deprecated]] void *memalign(size_t " alignment ", size_t " size );
+.fi
+.SH DESCRIPTION
+.BR memalign ()
+is the same as
+.BR aligned_alloc (3).
+.\" The behavior of memalign() for size==0 is as for posix_memalign()
+.\" but no standards govern this.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR memalign ()
+T}	Thread safety	MT-Safe
+.TE
+.SH VERSIONS
+On some systems
+.BR memalign ()
+is declared in
+.I <stdlib.h>
+instead of
+.IR <malloc.h> .
+.SH STANDARDS
+None.
+.SH HISTORY
+glibc 2.0.
+SunOS 4.1.3.
+.SH CAVEATS
+.BR memalign ()
+may not check that the
+.I alignment
+argument is correct.
+.P
+Some systems provide no way to reclaim memory allocated with
+.BR memalign ()
+(because one can pass to
+.BR free (3)
+only a pointer obtained from
+.BR malloc (3),
+while, for example,
+.BR memalign ()
+would call
+.BR malloc (3)
+and then align the obtained value).
+The glibc implementation
+allows memory obtained from
+.BR memalign ()
+to be reclaimed with
+.BR free (3).
+.SH SEE ALSO
+.BR aligned_alloc (3)
diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index ecbbd3e7a..3271292b7 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -5,7 +5,7 @@
 .\"
 .TH posix_memalign 3 (date) "Linux man-pages (unreleased)"
 .SH NAME
-posix_memalign, aligned_alloc, memalign, valloc, pvalloc \-
+posix_memalign, aligned_alloc, valloc, pvalloc \-
 allocate aligned memory
 .SH LIBRARY
 Standard C library
@@ -20,7 +20,6 @@ .SH SYNOPSIS
 .P
 .B #include <malloc.h>
 .P
-.BI "[[deprecated]] void *memalign(size_t " alignment ", size_t " size );
 .BI "[[deprecated]] void *pvalloc(size_t " size );
 .fi
 .P
@@ -77,13 +76,6 @@ .SH DESCRIPTION
 The memory address will be a multiple of
 .IR alignment ,
 which must be a power of two.
-.\" The behavior of memalign() for size==0 is as for posix_memalign()
-.\" but no standards govern this.
-.P
-The obsolete function
-.BR memalign ()
-is the same as
-.BR aligned_alloc ().
 .P
 The obsolete function
 .BR valloc ()
@@ -104,7 +96,6 @@ .SH DESCRIPTION
 For all of these functions, the memory is not zeroed.
 .SH RETURN VALUE
 .BR aligned_alloc (),
-.BR memalign (),
 .BR valloc (),
 and
 .BR pvalloc ()
@@ -149,7 +140,6 @@ .SH ATTRIBUTES
 .na
 .nh
 .BR aligned_alloc (),
-.BR memalign (),
 .BR posix_memalign ()
 T}	Thread safety	MT-Safe
 T{
@@ -168,8 +158,6 @@ .SH STANDARDS
 .BR posix_memalign ()
 POSIX.1-2024.
 .TP
-.BR memalign ()
-.TQ
 .BR valloc ()
 None.
 .TP
@@ -186,10 +174,6 @@ .SH HISTORY
 glibc 2.1.91.
 POSIX.1d, POSIX.1-2001.
 .TP
-.BR memalign ()
-glibc 2.0.
-SunOS 4.1.3.
-.TP
 .BR valloc ()
 glibc 2.0.
 3.0BSD.
@@ -205,13 +189,6 @@ .SS Headers
 is declared in
 .IR <stdlib.h> .
 .P
-On some systems
-.BR memalign ()
-is declared in
-.I <stdlib.h>
-instead of
-.IR <malloc.h> .
-.P
 According to SUSv2,
 .BR valloc ()
 is declared in
@@ -236,38 +213,21 @@ .SH NOTES
 verifies that
 .I alignment
 matches the requirements detailed above.
-.BR memalign ()
-may not check that the
-.I alignment
-argument is correct.
 .P
 POSIX requires that memory obtained from
 .BR posix_memalign ()
 can be freed using
 .BR free (3).
 Some systems provide no way to reclaim memory allocated with
-.BR memalign ()
-or
 .BR valloc ()
-(because one can pass to
-.BR free (3)
-only a pointer obtained from
-.BR malloc (3),
-while, for example,
-.BR memalign ()
-would call
-.BR malloc (3)
-and then align the obtained value).
+(see
+.BR memalign (3)).
 .\" Other systems allow passing the result of
 .\" .IR valloc ()
 .\" to
 .\" .IR free (3),
 .\" but not to
 .\" .IR realloc (3).
-The glibc implementation
-allows memory obtained from any of these functions to be
-reclaimed with
-.BR free (3).
 .P
 The glibc
 .BR malloc (3)
-- 
2.51.0

[PATCH v2 07/14] man/man3/{posix_memalign,pvalloc}.3: Split pvalloc() from posix_memalign(3)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 26 ++++-----------------
 man/man3/pvalloc.3        | 49 ++++++++++++++++++++++++++++++++++++++-
 2 files changed, 52 insertions(+), 23 deletions(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index 3271292b7..b3b27e5bb 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -5,7 +5,8 @@
 .\"
 .TH posix_memalign 3 (date) "Linux man-pages (unreleased)"
 .SH NAME
-posix_memalign, aligned_alloc, valloc, pvalloc \-
+posix_memalign, aligned_alloc, valloc
+\-
 allocate aligned memory
 .SH LIBRARY
 Standard C library
@@ -17,10 +18,6 @@ .SH SYNOPSIS
 .BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size );
 .BI "void *aligned_alloc(size_t " alignment ", size_t " size );
 .BI "[[deprecated]] void *valloc(size_t " size );
-.P
-.B #include <malloc.h>
-.P
-.BI "[[deprecated]] void *pvalloc(size_t " size );
 .fi
 .P
 .RS -4
@@ -86,19 +83,11 @@ .SH DESCRIPTION
 It is equivalent to
 .IR "memalign(sysconf(_SC_PAGESIZE),size)" .
 .P
-The obsolete function
-.BR pvalloc ()
-is similar to
-.BR valloc (),
-but rounds the size of the allocation up to
-the next multiple of the system page size.
-.P
 For all of these functions, the memory is not zeroed.
 .SH RETURN VALUE
 .BR aligned_alloc (),
-.BR valloc (),
 and
-.BR pvalloc ()
+.BR valloc ()
 return a pointer to the allocated memory on success.
 On error, NULL is returned, and
 .I errno
@@ -145,8 +134,7 @@ .SH ATTRIBUTES
 T{
 .na
 .nh
-.BR valloc (),
-.BR pvalloc ()
+.BR valloc ()
 T}	Thread safety	MT-Unsafe init
 .TE
 .SH STANDARDS
@@ -160,9 +148,6 @@ .SH STANDARDS
 .TP
 .BR valloc ()
 None.
-.TP
-.BR pvalloc ()
-GNU.
 .SH HISTORY
 .TP
 .BR aligned_alloc ()
@@ -179,9 +164,6 @@ .SH HISTORY
 3.0BSD.
 Documented as obsolete in 4.3BSD,
 and as legacy in SUSv2.
-.TP
-.BR pvalloc ()
-glibc 2.0.
 .\"
 .SS Headers
 Everybody agrees that
diff --git a/man/man3/pvalloc.3 b/man/man3/pvalloc.3
index 791d4c801..2f6e21813 100644
--- a/man/man3/pvalloc.3
+++ b/man/man3/pvalloc.3
@@ -1 +1,48 @@
-.so man3/posix_memalign.3
+'\" t
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pvalloc 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+pvalloc
+\-
+page-sized page-aligned memory allocation
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <malloc.h>
+.P
+.BI "[[deprecated]] void *pvalloc(size_t " size );
+.fi
+.SH DESCRIPTION
+.BR pvalloc ()
+is similar to
+.BR valloc (),
+but rounds the size of the allocation up to
+the next multiple of the system page size.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR pvalloc ()
+T}	Thread safety	MT-Unsafe init
+.TE
+.SH STANDARDS
+GNU.
+.SH HISTORY
+glibc 2.0.
+.SH CAVEATS
+See
+.BR valloc (3).
+.SH SEE ALSO
+.BR valloc (3)
-- 
2.51.0

[PATCH v2 08/14] man/man3/{posix_memalign,valloc}.3: Split valloc() from posix_memalign(3)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 64 ++--------------------------
 man/man3/valloc.3         | 89 ++++++++++++++++++++++++++++++++++++++-
 2 files changed, 91 insertions(+), 62 deletions(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index b3b27e5bb..2f664eb4e 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -5,7 +5,7 @@
 .\"
 .TH posix_memalign 3 (date) "Linux man-pages (unreleased)"
 .SH NAME
-posix_memalign, aligned_alloc, valloc
+posix_memalign, aligned_alloc
 \-
 allocate aligned memory
 .SH LIBRARY
@@ -17,7 +17,6 @@ .SH SYNOPSIS
 .P
 .BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size );
 .BI "void *aligned_alloc(size_t " alignment ", size_t " size );
-.BI "[[deprecated]] void *valloc(size_t " size );
 .fi
 .P
 .RS -4
@@ -34,17 +33,6 @@ .SH SYNOPSIS
 .nf
     _ISOC11_SOURCE
 .fi
-.P
-.BR valloc ():
-.nf
-    Since glibc 2.12:
-        (_XOPEN_SOURCE >= 500) && !(_POSIX_C_SOURCE >= 200112L)
-            || /* glibc >= 2.19: */ _DEFAULT_SOURCE
-            || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
-    Before glibc 2.12:
-        _BSD_SOURCE || _XOPEN_SOURCE >= 500
-.\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
-.fi
 .SH DESCRIPTION
 .BR posix_memalign ()
 allocates
@@ -74,21 +62,10 @@ .SH DESCRIPTION
 .IR alignment ,
 which must be a power of two.
 .P
-The obsolete function
-.BR valloc ()
-allocates
-.I size
-bytes and returns a pointer to the allocated memory.
-The memory address will be a multiple of the page size.
-It is equivalent to
-.IR "memalign(sysconf(_SC_PAGESIZE),size)" .
-.P
 For all of these functions, the memory is not zeroed.
 .SH RETURN VALUE
-.BR aligned_alloc (),
-and
-.BR valloc ()
-return a pointer to the allocated memory on success.
+.BR aligned_alloc ()
+returns a pointer to the allocated memory on success.
 On error, NULL is returned, and
 .I errno
 is set
@@ -131,11 +108,6 @@ .SH ATTRIBUTES
 .BR aligned_alloc (),
 .BR posix_memalign ()
 T}	Thread safety	MT-Safe
-T{
-.na
-.nh
-.BR valloc ()
-T}	Thread safety	MT-Unsafe init
 .TE
 .SH STANDARDS
 .TP
@@ -145,9 +117,6 @@ .SH STANDARDS
 .TP
 .BR posix_memalign ()
 POSIX.1-2024.
-.TP
-.BR valloc ()
-None.
 .SH HISTORY
 .TP
 .BR aligned_alloc ()
@@ -158,29 +127,12 @@ .SH HISTORY
 .BR posix_memalign ()
 glibc 2.1.91.
 POSIX.1d, POSIX.1-2001.
-.TP
-.BR valloc ()
-glibc 2.0.
-3.0BSD.
-Documented as obsolete in 4.3BSD,
-and as legacy in SUSv2.
 .\"
 .SS Headers
 Everybody agrees that
 .BR posix_memalign ()
 is declared in
 .IR <stdlib.h> .
-.P
-According to SUSv2,
-.BR valloc ()
-is declared in
-.IR <stdlib.h> .
-.\" Libc4,5 and
-glibc declares it in
-.IR <malloc.h> ,
-and also in
-.I <stdlib.h>
-if suitable feature test macros are defined (see above).
 .SH NOTES
 On many systems there are alignment restrictions, for example, on buffers
 used for direct block device I/O.
@@ -200,16 +152,6 @@ .SH NOTES
 .BR posix_memalign ()
 can be freed using
 .BR free (3).
-Some systems provide no way to reclaim memory allocated with
-.BR valloc ()
-(see
-.BR memalign (3)).
-.\" Other systems allow passing the result of
-.\" .IR valloc ()
-.\" to
-.\" .IR free (3),
-.\" but not to
-.\" .IR realloc (3).
 .P
 The glibc
 .BR malloc (3)
diff --git a/man/man3/valloc.3 b/man/man3/valloc.3
index 791d4c801..cc3543612 100644
--- a/man/man3/valloc.3
+++ b/man/man3/valloc.3
@@ -1 +1,88 @@
-.so man3/posix_memalign.3
+'\" t
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH valloc 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+valloc
+\-
+page-aligned memory allocation
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdlib.h>
+.P
+.BI "[[deprecated]] void *valloc(size_t " size );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR valloc ():
+.nf
+    Since glibc 2.12:
+        (_XOPEN_SOURCE >= 500) && !(_POSIX_C_SOURCE >= 200112L)
+            || /* glibc >= 2.19: */ _DEFAULT_SOURCE
+            || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
+    Before glibc 2.12:
+        _BSD_SOURCE || _XOPEN_SOURCE >= 500
+.\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
+.fi
+.SH DESCRIPTION
+.BR valloc ()
+allocates
+.I size
+bytes and returns a pointer to the allocated memory.
+The memory address will be a multiple of the page size.
+.P
+It is equivalent to
+.IR "memalign(sysconf(_SC_PAGESIZE),size)" .
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR valloc ()
+T}	Thread safety	MT-Unsafe init
+.TE
+.SH VERSIONS
+According to SUSv2,
+.BR valloc ()
+is declared in
+.IR <stdlib.h> .
+.\" Libc4,5 and
+glibc declares it in
+.IR <malloc.h> ,
+and also in
+.I <stdlib.h>
+if suitable feature test macros are defined (see above).
+.SH STANDARDS
+BSD, GNU.
+.SH HISTORY
+glibc 2.0.
+3.0BSD.
+Documented as obsolete in 4.3BSD,
+and as legacy in SUSv2.
+.\"
+.SH CAVEATS
+See
+.BR memalign (3).
+.\" Other systems allow passing the result of
+.\" .IR valloc ()
+.\" to
+.\" .IR free (3),
+.\" but not to
+.\" .IR realloc (3).
+.SH SEE ALSO
+.BR memalign (3)
-- 
2.51.0

[PATCH v2 09/14] man/man3/{aligned_alloc,posix_memalign}.3: Split aligned_alloc() from posix_memalign(3)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/aligned_alloc.3  | 99 ++++++++++++++++++++++++++++++++++++++-
 man/man3/posix_memalign.3 | 56 +++-------------------
 2 files changed, 105 insertions(+), 50 deletions(-)

diff --git a/man/man3/aligned_alloc.3 b/man/man3/aligned_alloc.3
index 791d4c801..cdc9ba1a2 100644
--- a/man/man3/aligned_alloc.3
+++ b/man/man3/aligned_alloc.3
@@ -1 +1,98 @@
-.so man3/posix_memalign.3
+'\" t
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH aligned_alloc 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+aligned_alloc
+\-
+allocate aligned memory
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdlib.h>
+.P
+.BI "void *aligned_alloc(size_t " alignment ", size_t " size );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR aligned_alloc ():
+.nf
+    _ISOC11_SOURCE
+.fi
+.SH DESCRIPTION
+.BR aligned_alloc ()
+allocates
+.I size
+bytes and returns a pointer to the allocated memory.
+The memory address will be a multiple of
+.IR alignment ,
+which must be a power of two.
+This address can later be successfully passed to
+.BR free (3).
+.P
+The memory is not zeroed.
+.SH RETURN VALUE
+.BR aligned_alloc ()
+returns a pointer to the allocated memory on success.
+On error, NULL is returned, and
+.I errno
+is set
+to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+The
+.I alignment
+argument was not a power of two.
+.TP
+.B ENOMEM
+Out of memory.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR aligned_alloc ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+C23,
+POSIX.1-2024.
+.SH HISTORY
+glibc 2.16.
+C11,
+POSIX.1-2024.
+.SH NOTES
+On many systems there are alignment restrictions, for example, on buffers
+used for direct block device I/O.
+POSIX specifies the
+.I "pathconf(path,_PC_REC_XFER_ALIGN)"
+call that tells what alignment is needed.
+Now one can use
+.BR aligned_alloc ()
+to satisfy this requirement.
+.P
+The glibc
+.BR malloc (3)
+always returns 8-byte aligned memory addresses,
+so this function is needed
+only if you require larger alignment values.
+.SH SEE ALSO
+.BR brk (2),
+.BR getpagesize (2),
+.BR free (3),
+.BR malloc (3)
diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index 2f664eb4e..8b3258dc2 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -5,7 +5,7 @@
 .\"
 .TH posix_memalign 3 (date) "Linux man-pages (unreleased)"
 .SH NAME
-posix_memalign, aligned_alloc
+posix_memalign
 \-
 allocate aligned memory
 .SH LIBRARY
@@ -16,7 +16,6 @@ .SH SYNOPSIS
 .B #include <stdlib.h>
 .P
 .BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size );
-.BI "void *aligned_alloc(size_t " alignment ", size_t " size );
 .fi
 .P
 .RS -4
@@ -28,11 +27,6 @@ .SH SYNOPSIS
 .nf
     _POSIX_C_SOURCE >= 200112L
 .fi
-.P
-.BR aligned_alloc ():
-.nf
-    _ISOC11_SOURCE
-.fi
 .SH DESCRIPTION
 .BR posix_memalign ()
 allocates
@@ -54,23 +48,13 @@ .SH DESCRIPTION
 .\" glibc does this:
 or a unique pointer value.
 .P
-.BR aligned_alloc ()
-allocates
-.I size
-bytes and returns a pointer to the allocated memory.
-The memory address will be a multiple of
-.IR alignment ,
-which must be a power of two.
+The memory is not zeroed.
 .P
-For all of these functions, the memory is not zeroed.
+.BR aligned_alloc (3)
+is a standard function that provides the same functionality,
+and has a more ergonomic prototype.
+Use that instead.
 .SH RETURN VALUE
-.BR aligned_alloc ()
-returns a pointer to the allocated memory on success.
-On error, NULL is returned, and
-.I errno
-is set
-to indicate the error.
-.P
 .BR posix_memalign ()
 returns zero on success, or one of the error values listed in the
 next section on failure.
@@ -105,26 +89,12 @@ .SH ATTRIBUTES
 T{
 .na
 .nh
-.BR aligned_alloc (),
 .BR posix_memalign ()
 T}	Thread safety	MT-Safe
 .TE
 .SH STANDARDS
-.TP
-.BR aligned_alloc ()
-C23,
-POSIX.1-2024.
-.TP
-.BR posix_memalign ()
 POSIX.1-2024.
 .SH HISTORY
-.TP
-.BR aligned_alloc ()
-glibc 2.16.
-C11,
-POSIX.1-2024.
-.TP
-.BR posix_memalign ()
 glibc 2.1.91.
 POSIX.1d, POSIX.1-2001.
 .\"
@@ -134,15 +104,6 @@ .SS Headers
 is declared in
 .IR <stdlib.h> .
 .SH NOTES
-On many systems there are alignment restrictions, for example, on buffers
-used for direct block device I/O.
-POSIX specifies the
-.I "pathconf(path,_PC_REC_XFER_ALIGN)"
-call that tells what alignment is needed.
-Now one can use
-.BR posix_memalign ()
-to satisfy this requirement.
-.P
 .BR posix_memalign ()
 verifies that
 .I alignment
@@ -158,7 +119,4 @@ .SH NOTES
 always returns 8-byte aligned memory addresses, so these functions are
 needed only if you require larger alignment values.
 .SH SEE ALSO
-.BR brk (2),
-.BR getpagesize (2),
-.BR free (3),
-.BR malloc (3)
+.BR aligned_alloc (3)
-- 
2.51.0

[PATCH v2 10/14] man/man3/posix_memalign.3: CAVEATS: Add section, and move paragraph to it

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index 8b3258dc2..c2816e1d4 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -61,13 +61,6 @@ .SH RETURN VALUE
 The value of
 .I errno
 is not set.
-On Linux (and other systems),
-.BR posix_memalign ()
-does not modify
-.I memptr
-on failure.
-A requirement standardizing this behavior was added in POSIX.1-2008 TC2.
-.\" http://austingroupbugs.net/view.php?id=520
 .SH ERRORS
 .TP
 .B EINVAL
@@ -118,5 +111,13 @@ .SH NOTES
 .BR malloc (3)
 always returns 8-byte aligned memory addresses, so these functions are
 needed only if you require larger alignment values.
+.SH CAVEATS
+On Linux (and other systems),
+.BR posix_memalign ()
+does not modify
+.I memptr
+on failure.
+A requirement standardizing this behavior was added in POSIX.1-2008 TC2.
+.\" http://austingroupbugs.net/view.php?id=520
 .SH SEE ALSO
 .BR aligned_alloc (3)
-- 
2.51.0

[PATCH v2 11/14] man/man3/posix_memalign.3: Remove redundant text

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 16 ----------------
 1 file changed, 16 deletions(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index c2816e1d4..fd76895a9 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -90,23 +90,7 @@ .SH STANDARDS
 .SH HISTORY
 glibc 2.1.91.
 POSIX.1d, POSIX.1-2001.
-.\"
-.SS Headers
-Everybody agrees that
-.BR posix_memalign ()
-is declared in
-.IR <stdlib.h> .
 .SH NOTES
-.BR posix_memalign ()
-verifies that
-.I alignment
-matches the requirements detailed above.
-.P
-POSIX requires that memory obtained from
-.BR posix_memalign ()
-can be freed using
-.BR free (3).
-.P
 The glibc
 .BR malloc (3)
 always returns 8-byte aligned memory addresses, so these functions are
-- 
2.51.0

[PATCH v2 12/14] man/man3/posix_memalign.3: NOTES: Remove superfluous section

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/posix_memalign.3 | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3
index fd76895a9..5600f7978 100644
--- a/man/man3/posix_memalign.3
+++ b/man/man3/posix_memalign.3
@@ -90,11 +90,6 @@ .SH STANDARDS
 .SH HISTORY
 glibc 2.1.91.
 POSIX.1d, POSIX.1-2001.
-.SH NOTES
-The glibc
-.BR malloc (3)
-always returns 8-byte aligned memory addresses, so these functions are
-needed only if you require larger alignment values.
 .SH CAVEATS
 On Linux (and other systems),
 .BR posix_memalign ()
-- 
2.51.0

[PATCH v2 13/14] man/man3/memalign.3: wfix

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/memalign.3 | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

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

[PATCH v2 14/14] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11

[Alejandro Colomar]

And document that OpenBSD still implements the C11 specification (but
without the UB).

Fixes: 7fd1e0f2be21 (2023-05-20; "posix_memalign.3: Update aligned_alloc(3) to match C17")
Reported-by: Eugene Syromyatnikov <evgsyr@gmail.com>
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>
---
 man/man3/aligned_alloc.3 | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/man/man3/aligned_alloc.3 b/man/man3/aligned_alloc.3
index cdc9ba1a2..0c9a12787 100644
--- a/man/man3/aligned_alloc.3
+++ b/man/man3/aligned_alloc.3
@@ -76,6 +76,35 @@ .SH HISTORY
 glibc 2.16.
 C11,
 POSIX.1-2024.
+.SS C11
+In C11,
+the specification of this function had several issues.
+.IP \[bu] 3
+.I size
+had to be a multiple of
+.IR alignment .
+Otherwise,
+the behavior was undefined.
+.IP
+Some implementations still implement that restriction,
+such as OpenBSD.
+However,
+in those implementations,
+the function reports an error,
+and don't exploit the UB.
+It was only a theoretical UB.
+.IP
+This restriction was removed in C17.
+.IP \[bu]
+If
+.I alignment
+was not a power of two,
+the behavior was undefined.
+.IP
+No implementations ever exploited this UB.
+It was only a theoretical UB.
+.IP
+This UB was removed in C17.
 .SH NOTES
 On many systems there are alignment restrictions, for example, on buffers
 used for direct block device I/O.
-- 
2.51.0

Re: [PATCH v2 00/14] man/man3/posix_memalign.3: Several fixes, and split the page

[Seth McDonald]

[-- Attachment #1.1: Type: text/plain, Size: 2258 bytes --]

G'day (or night, as I'm writing this),

On Tuesday, 16 December 2025 at 00:41, Alejandro Colomar <alx@kernel.org> wrote:
> Hi!
> 

> In v2, I've removed the explicit sentence saying that one should use
> aligned_alloc(3) instead of memalign(3).
> 

> I've also documented that C11 had a bogus specification for
> aligned_alloc(3), and that OpenBSD still implements that (although at
> least, they don't exploit the UB). I've CCed them, in case they're not
> aware that C17 fixed those issues.
> 

> I've documented that while the C11 specification had a lot of UB, no
> implementation has ever implemented that, and so it's just theoretical
> (and thankfully extinct) UB.

I had a look at FreeBSD's documentation for aligned_alloc(3) - which is
just jemalloc's manual - and it does explicitly specify the C11
undefined behaviour.[1]

"The aligned_alloc() function allocates size bytes of memory such that
the allocation's base address is a multiple of alignment. The requested
alignment must be a power of 2. Behavior is undefined if size is not an
integral multiple of alignment."

However, I have spent a while going over FreeBSD's (jemalloc's)
implementation of aligned_alloc(3), and as far as I can tell, it
appears to work as expected even when size is not a multiple of
alignment. So it seems the man page is just repeating the C11 standard
to conform to it (though the page doesn't specify this conformance,
strangely enough).

Even so, it may be useful to also document FreeBSD's nominal undefined
behaviour in addition to OpenBSD. Perhaps emphasising how jemalloc
doesn't actually exploit this undefined behaviour, and never will given
the project's recent retirement. Thereby meaning the point about C11's
extinct undefined behaviour should still stand.

This would also prevent people (like myself, I imagine) from thinking
that the Linux man page is potentially outdated due to seemingly not
knowing about FreeBSD's (ostensible, but documented) undefined
behaviour.

----
Seth McDonald.
sethmcmail at pm dot me (mailing lists)
2336 E8D2 FEB1 5300 692C  62A9 5839 6AD8 9243 D369

----
[1] https://man.freebsd.org/cgi/man.cgi?query=aligned_alloc&sektion=3&manpath=FreeBSD+15.0-RELEASE+and+Ports

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 343 bytes --]

Re: [PATCH v2 00/14] man/man3/posix_memalign.3: Several fixes, and split the page

[Alejandro Colomar]

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

On Wed, Dec 17, 2025 at 01:03:27PM +0000, Seth McDonald wrote:
> G'day (or night, as I'm writing this),

G'day Seth!

> On Tuesday, 16 December 2025 at 00:41, Alejandro Colomar <alx@kernel.org> wrote:
> > Hi!
> > 

Since nobody complained about patches 1..13, I've pushed them.  I'll
continue work on patch 14.

> 
> > In v2, I've removed the explicit sentence saying that one should use
> > aligned_alloc(3) instead of memalign(3).
> > 
> 
> > I've also documented that C11 had a bogus specification for
> > aligned_alloc(3), and that OpenBSD still implements that (although at
> > least, they don't exploit the UB). I've CCed them, in case they're not
> > aware that C17 fixed those issues.
> > 
> 
> > I've documented that while the C11 specification had a lot of UB, no
> > implementation has ever implemented that, and so it's just theoretical
> > (and thankfully extinct) UB.
> 
> I had a look at FreeBSD's documentation for aligned_alloc(3) - which is
> just jemalloc's manual - and it does explicitly specify the C11
> undefined behaviour.[1]
> 
> "The aligned_alloc() function allocates size bytes of memory such that
> the allocation's base address is a multiple of alignment. The requested
> alignment must be a power of 2. Behavior is undefined if size is not an
> integral multiple of alignment."
> 
> However, I have spent a while going over FreeBSD's (jemalloc's)
> implementation of aligned_alloc(3), and as far as I can tell, it
> appears to work as expected even when size is not a multiple of
> alignment. So it seems the man page is just repeating the C11 standard
> to conform to it (though the page doesn't specify this conformance,
> strangely enough).
> 
> Even so, it may be useful to also document FreeBSD's nominal undefined
> behaviour in addition to OpenBSD. Perhaps emphasising how jemalloc
> doesn't actually exploit this undefined behaviour, and never will given
> the project's recent retirement. Thereby meaning the point about C11's
> extinct undefined behaviour should still stand.
> 
> This would also prevent people (like myself, I imagine) from thinking
> that the Linux man page is potentially outdated due to seemingly not
> knowing about FreeBSD's (ostensible, but documented) undefined
> behaviour.

Thanks!  I'll send a revised patch in a moment.


Have a lovely day!
Alex

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

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

[PATCH v3 0/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11

[Alejandro Colomar]

Hi!

I've already pushed patches 1..13 from v2, as nobody raised concerns.
v3 only contains a signle patch.

I've updated it to also document the case of FreeBSD/jemalloc, as
reported by Seth.


Have a lovely day!
Alex


Alejandro Colomar (1):
  man/man3/aligned_alloc.3: HISTORY: Document bogus specification from
    C11

 man/man3/aligned_alloc.3 | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

Range-diff against v2:
 1:  90f18b452 <  -:  --------- man/man3/posix_memalign.3: Remove confusing exception
 2:  19b5ea61e <  -:  --------- man/man3/posix_memalign.3: wfix
 3:  82bcf3b0f <  -:  --------- man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to C17, not C11
 4:  04f5087e5 <  -:  --------- man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to C23
 5:  c8ffb2124 <  -:  --------- man/man3/posix_memalign.3: STANDARDS: aligned_alloc() and posix_memalign() conform to POSIX.1-2024
 6:  51b7f9f43 <  -:  --------- man/man3/{posix_,}memalign.3: Split memalign() from posix_memalign(3)
 7:  a60d6283f <  -:  --------- man/man3/{posix_memalign,pvalloc}.3: Split pvalloc() from posix_memalign(3)
 8:  126c39d0f <  -:  --------- man/man3/{posix_memalign,valloc}.3: Split valloc() from posix_memalign(3)
 9:  b23cb7bc6 <  -:  --------- man/man3/{aligned_alloc,posix_memalign}.3: Split aligned_alloc() from posix_memalign(3)
10:  1e5a0260e <  -:  --------- man/man3/posix_memalign.3: CAVEATS: Add section, and move paragraph to it
11:  c0b9fd96a <  -:  --------- man/man3/posix_memalign.3: Remove redundant text
12:  34d984534 <  -:  --------- man/man3/posix_memalign.3: NOTES: Remove superfluous section
13:  a5342ef55 <  -:  --------- man/man3/memalign.3: wfix
14:  cdfc42078 !  1:  6ed874153 man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
    @@ man/man3/aligned_alloc.3: .SH HISTORY
     +the behavior was undefined.
     +.IP
     +Some implementations still implement that restriction,
    -+such as OpenBSD.
    -+However,
    -+in those implementations,
    -+the function reports an error,
    -+and don't exploit the UB.
    ++or claim to have it.
    ++.RS
    ++.TP
    ++OpenBSD
    ++The function reports an error
    ++if this restriction is violated,
    ++without exploiting the UB.
    ++.TP
    ++FreeBSD
    ++.TQ
    ++jemalloc
    ++The documentation claims to have this restriction,
    ++but the implementation works correctly if it is violated.
    ++.RE
    ++.IP
     +It was only a theoretical UB.
    ++No known implementation has ever exploited this UB.
     +.IP
     +This restriction was removed in C17.
     +.IP \[bu]

base-commit: a5342ef55f0a96790bf279a98c9d2a30b19fc9eb
-- 
2.51.0

[PATCH v3 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11

[Alejandro Colomar]

And document that OpenBSD still implements the C11 specification (but
without the UB).

Fixes: 7fd1e0f2be21 (2023-05-20; "posix_memalign.3: Update aligned_alloc(3) to match C17")
Reported-by: Eugene Syromyatnikov <evgsyr@gmail.com>
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>
---
 man/man3/aligned_alloc.3 | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/man/man3/aligned_alloc.3 b/man/man3/aligned_alloc.3
index cdc9ba1a2..f5fad3654 100644
--- a/man/man3/aligned_alloc.3
+++ b/man/man3/aligned_alloc.3
@@ -76,6 +76,46 @@ .SH HISTORY
 glibc 2.16.
 C11,
 POSIX.1-2024.
+.SS C11
+In C11,
+the specification of this function had several issues.
+.IP \[bu] 3
+.I size
+had to be a multiple of
+.IR alignment .
+Otherwise,
+the behavior was undefined.
+.IP
+Some implementations still implement that restriction,
+or claim to have it.
+.RS
+.TP
+OpenBSD
+The function reports an error
+if this restriction is violated,
+without exploiting the UB.
+.TP
+FreeBSD
+.TQ
+jemalloc
+The documentation claims to have this restriction,
+but the implementation works correctly if it is violated.
+.RE
+.IP
+It was only a theoretical UB.
+No known implementation has ever exploited this UB.
+.IP
+This restriction was removed in C17.
+.IP \[bu]
+If
+.I alignment
+was not a power of two,
+the behavior was undefined.
+.IP
+No implementations ever exploited this UB.
+It was only a theoretical UB.
+.IP
+This UB was removed in C17.
 .SH NOTES
 On many systems there are alignment restrictions, for example, on buffers
 used for direct block device I/O.
-- 
2.51.0

Re: [PATCH v3 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11

[Alejandro Colomar]

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

Here's how this patch looks like when reading the manual page:

	$ MANWIDTH=64 diffman-git HEAD^ 
	--- HEAD^^:man/man3/aligned_alloc.3
	+++ HEAD^:man/man3/aligned_alloc.3
	@@ -52,6 +52,39 @@ STANDARDS
	 HISTORY
	      glibc 2.16.  C11, POSIX.1‐2024.
	 
	+   C11
	+     In C11, the specification of this function had several is‐
	+     sues.
	+
	+     •  size had to be a multiple of alignment.  Otherwise, the
	+        behavior was undefined.
	+
	+        Some implementations still implement that restriction,
	+        or claim to have it.
	+
	+        OpenBSD
	+               The function reports an error if this restric‐
	+               tion is violated, without exploiting the UB.
	+
	+        FreeBSD
	+        jemalloc
	+               The documentation claims to have this restric‐
	+               tion, but the implementation works correctly if
	+               it is violated.
	+
	+        It was only a theoretical UB.  No known implementation
	+        has ever exploited this UB.
	+
	+        This restriction was removed in C17.
	+
	+     •  If alignment was not a power of two, the behavior was
	+        undefined.
	+
	+        No implementations ever exploited this UB.  It was only
	+        a theoretical UB.
	+
	+        This UB was removed in C17.
	+
	 NOTES
	      On many systems there are alignment restrictions, for ex‐
	      ample, on buffers used for direct block device I/O.  POSIX


Cheers,
Alex

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

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

Re: [PATCH v3 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11

[Eugene Syromyatnikov]

On Wed, Dec 17, 2025 at 2:51 PM Alejandro Colomar <alx@kernel.org> wrote:


> +Otherwise,
> +the behavior was undefined.

I think this statement is incorrect, or at least misleading, because
the current reading (that includes DR460) of ISO 9899:2011 explicitly
states that the function must fail when the condition is not satisfied
(and that is what OpenBSD has implemented), and that also makes any
permissive specification non-conforming wrt C11 as it is now. But that
is also true that C11 _used to_ specify a failure to conform to this
onerous restriction as UB, which rendered the programs malformed, but,
on the other hand, kept libcs that implemented it permissively
standard-conformant.

I understand that I am unnecessarily conscientious here, but I think
it is important to articulate what the standard both says and used to
say, as it is the reference point for the language implementations,
the totality of which an application developer can neither observe nor
inspect, and relying on a couple of anecdotes in terms of
implementations may lead to issues down the road. I guess the outcome
of my rants is "don't use aligned_alloc and C11 together", or
something along those lines.

> +.IP \[bu]
> +If
> +.I alignment
> +was not a power of two,
> +the behavior was undefined.

I can't find a version of the standard that mentions the power-of-two
restriction, it pertains only posix_memalign.

--
Eugene Syromyatnikov
mailto:evgsyr@gmail.com
xmpp:esyr@jabber.{ru|org}

Re: [PATCH v3 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11

[Eugene Syromyatnikov]

On Wed, Dec 17, 2025 at 3:42 PM Eugene Syromyatnikov <evgsyr@gmail.com> wrote:
>
> On Wed, Dec 17, 2025 at 2:51 PM Alejandro Colomar <alx@kernel.org> wrote:
>
>
> > +Otherwise,
> > +the behavior was undefined.
>
> I think this statement is incorrect, or at least misleading, because
> the current reading (that includes DR460) of ISO 9899:2011 explicitly
> states that the function must fail when the condition is not satisfied
> (and that is what OpenBSD has implemented), and that also makes any
> permissive specification non-conforming wrt C11 as it is now. But that
> is also true that C11 _used to_ specify a failure to conform to this
> onerous restriction as UB, which rendered the programs malformed, but,
> on the other hand, kept libcs that implemented it permissively
> standard-conformant.
>
> I understand that I am unnecessarily conscientious here, but I think
> it is important to articulate what the standard both says and used to
> say, as it is the reference point for the language implementations,
> the totality of which an application developer can neither observe nor
> inspect, and relying on a couple of anecdotes in terms of
> implementations may lead to issues down the road. I guess the outcome
> of my rants is "don't use aligned_alloc and C11 together", or
> something along those lines.

Correction: I was thinking that there was a published TR similar to
C++, but apparently there wasn't, so the UB-including wording has
never updated in publicly-available iterations of C11, the next
published version, that is C17, has removed the requirement
altogether, and the version with the
failing-on-size-non-multiple-of-alignment requirement was never
publicly available similar to the ways standard drafts are, while
technically the wording existed for two years before the adoption of
N2072, hence my blabber about the "final version of C11" is
nonsensical;  however, the point about the standard requiring three
different things still stands. My apologies for the excessive noise.


> > +.IP \[bu]
> > +If
> > +.I alignment
> > +was not a power of two,
> > +the behavior was undefined.
>
> I can't find a version of the standard that mentions the power-of-two
> restriction, it pertains only posix_memalign.
>
> --
> Eugene Syromyatnikov
> mailto:evgsyr@gmail.com
> xmpp:esyr@jabber.{ru|org}



--
Eugene Syromyatnikov
mailto:evgsyr@gmail.com
xmpp:esyr@jabber.{ru|org}

Re: [PATCH v3 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11

[Alejandro Colomar]

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

[CC += Martin Sebor]

Hi Eugene,

On Wed, Dec 17, 2025 at 04:37:30PM +0100, Eugene Syromyatnikov wrote:
> On Wed, Dec 17, 2025 at 3:42 PM Eugene Syromyatnikov <evgsyr@gmail.com> wrote:
> >
> > On Wed, Dec 17, 2025 at 2:51 PM Alejandro Colomar <alx@kernel.org> wrote:
> >
> >
> > > +Otherwise,
> > > +the behavior was undefined.
> >
> > I think this statement is incorrect, or at least misleading, because
> > the current reading (that includes DR460) of ISO 9899:2011 explicitly
> > states that the function must fail when the condition is not satisfied
> > (and that is what OpenBSD has implemented), and that also makes any
> > permissive specification non-conforming wrt C11 as it is now. But that
> > is also true that C11 _used to_ specify a failure to conform to this
> > onerous restriction as UB, which rendered the programs malformed, but,
> > on the other hand, kept libcs that implemented it permissively
> > standard-conformant.
> >
> > I understand that I am unnecessarily conscientious here, but I think
> > it is important to articulate what the standard both says and used to
> > say, as it is the reference point for the language implementations,
> > the totality of which an application developer can neither observe nor
> > inspect, and relying on a couple of anecdotes in terms of
> > implementations may lead to issues down the road. I guess the outcome
> > of my rants is "don't use aligned_alloc and C11 together", or
> > something along those lines.
> 
> Correction: I was thinking that there was a published TR similar to
> C++, but apparently there wasn't, so the UB-including wording has
> never updated in publicly-available iterations of C11, the next
> published version, that is C17, has removed the requirement
> altogether, and the version with the
> failing-on-size-non-multiple-of-alignment requirement was never
> publicly available similar to the ways standard drafts are, while
> technically the wording existed for two years before the adoption of
> N2072, hence my blabber about the "final version of C11" is
> nonsensical;  however, the point about the standard requiring three
> different things still stands. My apologies for the excessive noise.
> 

Let's see if I'm following:

C11 (or at least, the draft that I know of, which is n1570) has two
cases of UB for aligned_alloc(3):

-  size is not multiple of alignment
-  alignment is unsupported (often, this means not a power of two)

<https://port70.net/~nsz/c/c11/n1570.html#7.22.3.1p2>

DR460 (2014) reported both cases of UB, and fixed them with a TC.

<https://www.open-std.org/jtc1/sc22/wg14/www/docs/summary.htm#dr_460>

N2072 (2016) reported that the restriction that the size is not a
multiple of alignment is superfluous, and fixed it with a TC.

<https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2072.htm>

C17 (or at least, the draft that I know of, which is n2176) is the first
standard that incorporates both DR460 and N2076.

While C17 is a different standard, it is actually a bugfix release, and
both DR460 and N2072 are meant to retroactively affect C11, so all
conforming implementations of C11 should in fact be conforming to C17
and not C11.  However, OpenBSD conforms to C11+DR460, but not C17.
From what you said, FreeBSD seems to conform to C17, but it claims to
conform to C11.

Please correct me if I'm wrong.


Have a lovely night!
Alex

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

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

Re: [PATCH v3 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11

[Alejandro Colomar]

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

Hi Eugene,

On Wed, Dec 17, 2025 at 06:05:53PM +0100, Alejandro Colomar wrote:
> Let's see if I'm following:
> 
> C11 (or at least, the draft that I know of, which is n1570) has two
> cases of UB for aligned_alloc(3):
> 
> -  size is not multiple of alignment
> -  alignment is unsupported (often, this means not a power of two)
> 
> <https://port70.net/~nsz/c/c11/n1570.html#7.22.3.1p2>
> 
> DR460 (2014) reported both cases of UB, and fixed them with a TC.
> 
> <https://www.open-std.org/jtc1/sc22/wg14/www/docs/summary.htm#dr_460>
> 
> N2072 (2016) reported that the restriction that the size is not a
> multiple of alignment is superfluous, and fixed it with a TC.
> 
> <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2072.htm>
> 
> C17 (or at least, the draft that I know of, which is n2176) is the first
> standard that incorporates both DR460 and N2076.
> 
> While C17 is a different standard, it is actually a bugfix release, and
> both DR460 and N2072 are meant to retroactively affect C11, so all
> conforming implementations of C11 should in fact be conforming to C17
> and not C11.  However, OpenBSD conforms to C11+DR460, but not C17.
> From what you said, FreeBSD seems to conform to C17, but it claims to
> conform to C11.
> 
> Please correct me if I'm wrong.

I've written the following draft for the next revision of this patch.
This time, I've included all of this information in the manual page.

	HISTORY
	     glibc 2.16.  C11, POSIX.1‐2024.

	   C11
	     In C11, the specification of this function had several is‐
	     sues.

	     •  size had to be a multiple of alignment.  Otherwise, the
		behavior was undefined.

		Some implementations still implement that  restriction,
		or claim to have it.

		OpenBSD
		       The  function  reports an error if this restric‐
		       tion is violated.

		FreeBSD
		jemalloc
		       The documentation claims to have  this  restric‐
		       tion,  but the implementation works correctly if
		       it is violated.

	     •  If alignment was not a power of two, the  behavior  was
		undefined.

	     No  known implementations ever exploited these cases of UB
	     in a dangerous way.  They were only theoretical UB.   Pro‐
	     grammers should expect unnecessary failures in some imple‐
	     mentations, but nothing worrying.

	     In 2014, DR460 transformed both cases of UB into failures.

	     Later,  in  2016,  N2072 removed the restriction that size
	     had to be multiple of alignment.

	     The following revision of the standard, C17,  incorporated
	     both of these changes, resulting in the current specifica‐
	     tion.

Does this sound good?


Cheers,
Alex

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

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

Re: [PATCH v3 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11

[Alejandro Colomar]

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

Hi Eugene,

On Wed, Dec 17, 2025 at 03:42:28PM +0100, Eugene Syromyatnikov wrote:
> On Wed, Dec 17, 2025 at 2:51 PM Alejandro Colomar <alx@kernel.org> wrote:
> 
> 
> > +Otherwise,
> > +the behavior was undefined.
> 
> I think this statement is incorrect, or at least misleading, because
> the current reading (that includes DR460) of ISO 9899:2011 explicitly

Does DR460 retroactively fix C11, or is it incorporated as part of C17?

Can you please provide any links to the sources?

> states that the function must fail when the condition is not satisfied
> (and that is what OpenBSD has implemented), and that also makes any
> permissive specification non-conforming wrt C11 as it is now.

What do you mean by "permissive specification"?  I didn't understand
this sentence well.

> But that
> is also true that C11 _used to_ specify a failure to conform to this
> onerous restriction as UB, which rendered the programs malformed, but,
> on the other hand, kept libcs that implemented it permissively
> standard-conformant.
> 
> I understand that I am unnecessarily conscientious here,

Please, be very picky.  That'll result in a better manual page.  :)

> but I think
> it is important to articulate what the standard both says and used to
> say, as it is the reference point for the language implementations,

To some degree, I agree.  Except that the standard isn't that important
where it differs from reality.

> the totality of which an application developer can neither observe nor
> inspect, and relying on a couple of anecdotes in terms of
> implementations may lead to issues down the road. I guess the outcome
> of my rants is "don't use aligned_alloc and C11 together", or
> something along those lines.
> 
> > +.IP \[bu]
> > +If
> > +.I alignment
> > +was not a power of two,
> > +the behavior was undefined.
> 
> I can't find a version of the standard that mentions the power-of-two
> restriction, it pertains only posix_memalign.

Oops, you're right; this should be "if the alignment was an unsupported
value".


Have a lovely day!
Alex

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

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

[PATCH v4 0/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11

[Alejandro Colomar]

Hi,

I've rewritten the entire subsection from scratch, similar to the email
I wrote detailing the history of the specification.  I think this is
explains the turbulent history of this API better, and allows
programmers to decide if they want to trust this API or not.

Does this look good?


Have a lovely night!
Alex


Alejandro Colomar (1):
  man/man3/aligned_alloc.3: HISTORY: Document bogus specification from
    C11

 man/man3/aligned_alloc.3 | 60 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

Range-diff against v3:
1:  6ed874153 ! 1:  f19bb100f man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
    @@ Metadata
      ## Commit message ##
         man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
     
    -    And document that OpenBSD still implements the C11 specification (but
    -    without the UB).
    +    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>
    @@ man/man3/aligned_alloc.3: .SH HISTORY
      POSIX.1-2024.
     +.SS C11
     +In C11,
    -+the specification of this function had several issues.
    ++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
    -+Some implementations still implement that restriction,
    -+or claim to have it.
    -+.RS
    -+.TP
    -+OpenBSD
    -+The function reports an error
    -+if this restriction is violated,
    -+without exploiting the UB.
    -+.TP
    -+FreeBSD
    -+.TQ
    -+jemalloc
    -+The documentation claims to have this restriction,
    -+but the implementation works correctly if it is violated.
    -+.RE
    -+.IP
    -+It was only a theoretical UB.
    -+No known implementation has ever exploited this UB.
    -+.IP
    -+This restriction was removed in C17.
     +.IP \[bu]
     +If
     +.I alignment
     +was not a power of two,
     +the behavior was undefined.
    -+.IP
    -+No implementations ever exploited this UB.
    -+It was only a theoretical UB.
    -+.IP
    -+This UB was removed in C17.
    ++.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.

base-commit: a5342ef55f0a96790bf279a98c9d2a30b19fc9eb
-- 
2.51.0

[PATCH v4 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11

[Alejandro Colomar]

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

Re: [PATCH v4 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11

[Alejandro Colomar]

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

Here's how it looks:

$ MANWIDTH=72 diffman-git f19bb100f31e
--- f19bb100f31e^:man/man3/aligned_alloc.3
+++ f19bb100f31e:man/man3/aligned_alloc.3
@@ -52,6 +52,41 @@ STANDARDS
 HISTORY
      glibc 2.16.  C11, POSIX.1‐2024.
 
+   C11
+     In C11, the specification of this function had several issues.
+
+     •  size had to be a multiple of alignment.  Otherwise, the behav‐
+        ior was undefined.
+
+     •  If alignment was not a power of two, the behavior was unde‐
+        fined.
+
+     DR460 reported both cases of UB as unnecessarily dangerous, and
+     fixed them with a Technical Corrigendum that transformed them into
+     errors.
+
+     N2072 reported that the requirement that size is a multiple of
+     alignment is superfluous, and removed it with a Technical Corri‐
+     gendum.
+
+     C17 incorporates both technical corrigenda.  The API has been sta‐
+     ble since C17.
+
+     glibc originally implemented it as silently aligning as
+     stdc_bit_ceil(alignment) instead of alignment.  Since glibc 2.38,
+     it implements the C17 specification.
+
+     Some implementations, such as FreeBSD/jemalloc, implement the C17
+     specification, even though their documentation claims the C11
+     specification.
+
+     Some implementations, such as OpenBSD, implement C11 amended with
+     DR460, even though their documentation claims having undefined be‐
+     havior.
+
+     No known implementations have exploited the undefined behavior in
+     a more dangerous way.  This function should be safe to use.
+
 NOTES
      On many systems there are alignment restrictions, for example, on
      buffers used for direct block device I/O.  POSIX specifies the


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

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

Re: [PATCH v4 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11

[G. Branden Robinson]

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

Hi Alex,

Content looks great; as you've likely guessed, I have commentary only on
man(7) markup.

At 2025-12-22T22:33:09+0100, Alejandro Colomar wrote:
> I've rewritten the entire subsection from scratch, similar to the
> email I wrote detailing the history of the specification.  I think
> this is explains the turbulent history of this API better, and allows
> programmers to decide if they want to trust this API or not.
> 
> Does this look good?

At 2025-12-22T22:33:13+0100, Alejandro Colomar wrote:
> Document the turbulent past of aligned_alloc(), and how libraries have
> actually implemented it.

Nice summary!

[...]
> +the specification of this function had
> +.UR https://port70.net/~nsz/c/c11/n1570.html#7.22.3.1p2
> +several issues
> +.UE .
[...]
> +.UR https://www.open-std.org/jtc1/sc22/wg14/www/docs/summary.htm#dr_460
> +DR460
> +.UE
[...]
> +.UR https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2072.htm
> +N2072
> +.UE

I'd put hyphenless break points after each sequence of slashes in these
URLs, and before each dot.

I`d spell these `-`s as `\-` so that they appear as hyphen-minuses when
printed, not as hyphens.

groff_man_style(7):
   Hyperlink macros
...
     Prepare arguments to MR, MT, and UR for typesetting; they can
     appear in the output.  Use special character escape sequences to
     encode Unicode basic Latin characters where necessary, particularly
     the hyphen‐minus.  (See subsection “Portability” below.)  URIs can
     be lengthy; rendering them can result in jarring adjustment or
     variations in line length, or troff warnings when one is longer
     than an output line.  The application of non‐printing break point
     escape sequences \: after each slash (or series thereof), and
     before each dot (or series thereof) is recommended as a rule of
     thumb.  The former practice avoids forcing a trailing slash in a
     URI onto a separate output line, and the latter helps the reader to
     avoid mistakenly interpreting a dot at the end of a line as a
     period (or multiple dots as an ellipsis).  Thus,
            .UR http://\:example\:.com/\:fb8afcfbaebc74e\:.cc
     has several potential break points in the URI shown.  Consider
     adding break points before or after at signs in email addresses,
     and question marks, ampersands, and number signs in HTTP(S) URIs.
...
Portability
...
     \-     Minus sign.  \- produces the basic Latin hyphen‐minus
            (U+002D) specifying Unix command‐line options and frequently
            used in file names.  “-” is a hyphen in roff; some output
            devices format it as U+2010 (hyphen).

I recently noticed someone on StackExchange opining that "man" (they
weren't clear on whether they meant the man(1) librarian or the man(7)
macro language) doesn't support URLS: "unlike man, at least [lynx(1)]
supports links!".

That claim is a combination of falsehood, misleading implication, and
out-of-dateness.  It's not man(1) that needs to support hyperlinks in a
terminal, but the pager[1], and less(1) does, since version 661 (June
2024).  grotty(1) has offered OSC 8 links since groff 1.23.0, July 2023.

Regards,
Branden

[1] ...or the terminal emulator, in the event one uses cat(1) as the
    pager or runs "nroff -man" directly, like a hard-bitten,
    two-fisted-drinking, shirtless veteran of the Unix Wars.

    (You can leave Australia, but 'Straya never truly leaves you.)

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

Re: [PATCH v4 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11

[Alejandro Colomar]

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

Hi Branden,

On Mon, Dec 22, 2025 at 06:15:24PM -0600, G. Branden Robinson wrote:
> Hi Alex,
> 
> Content looks great; as you've likely guessed, I have commentary only on
> man(7) markup.
> 
> At 2025-12-22T22:33:09+0100, Alejandro Colomar wrote:
> > I've rewritten the entire subsection from scratch, similar to the
> > email I wrote detailing the history of the specification.  I think
> > this is explains the turbulent history of this API better, and allows
> > programmers to decide if they want to trust this API or not.
> > 
> > Does this look good?
> 
> At 2025-12-22T22:33:13+0100, Alejandro Colomar wrote:
> > Document the turbulent past of aligned_alloc(), and how libraries have
> > actually implemented it.
> 
> Nice summary!

Thanks! :-)

> [...]
> > +the specification of this function had
> > +.UR https://port70.net/~nsz/c/c11/n1570.html#7.22.3.1p2
> > +several issues
> > +.UE .
> [...]
> > +.UR https://www.open-std.org/jtc1/sc22/wg14/www/docs/summary.htm#dr_460
> > +DR460
> > +.UE
> [...]
> > +.UR https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2072.htm
> > +N2072
> > +.UE
> 
> I'd put hyphenless break points after each sequence of slashes in these
> URLs, and before each dot.
> 
> I`d spell these `-`s as `\-` so that they appear as hyphen-minuses when
> printed, not as hyphens.

Yup; thanks for the reminder!  Also fixed the \[ti].


Have a lovely night!
Alex

> 
> groff_man_style(7):
>    Hyperlink macros
> ...
>      Prepare arguments to MR, MT, and UR for typesetting; they can
>      appear in the output.  Use special character escape sequences to
>      encode Unicode basic Latin characters where necessary, particularly
>      the hyphen‐minus.  (See subsection “Portability” below.)  URIs can
>      be lengthy; rendering them can result in jarring adjustment or
>      variations in line length, or troff warnings when one is longer
>      than an output line.  The application of non‐printing break point
>      escape sequences \: after each slash (or series thereof), and
>      before each dot (or series thereof) is recommended as a rule of
>      thumb.  The former practice avoids forcing a trailing slash in a
>      URI onto a separate output line, and the latter helps the reader to
>      avoid mistakenly interpreting a dot at the end of a line as a
>      period (or multiple dots as an ellipsis).  Thus,
>             .UR http://\:example\:.com/\:fb8afcfbaebc74e\:.cc
>      has several potential break points in the URI shown.  Consider
>      adding break points before or after at signs in email addresses,
>      and question marks, ampersands, and number signs in HTTP(S) URIs.
> ...
> Portability
> ...
>      \-     Minus sign.  \- produces the basic Latin hyphen‐minus
>             (U+002D) specifying Unix command‐line options and frequently
>             used in file names.  “-” is a hyphen in roff; some output
>             devices format it as U+2010 (hyphen).
> 
> I recently noticed someone on StackExchange opining that "man" (they
> weren't clear on whether they meant the man(1) librarian or the man(7)
> macro language) doesn't support URLS: "unlike man, at least [lynx(1)]
> supports links!".
> 
> That claim is a combination of falsehood, misleading implication, and
> out-of-dateness.  It's not man(1) that needs to support hyperlinks in a
> terminal, but the pager[1], and less(1) does, since version 661 (June
> 2024).  grotty(1) has offered OSC 8 links since groff 1.23.0, July 2023.
> 
> Regards,
> Branden
> 
> [1] ...or the terminal emulator, in the event one uses cat(1) as the
>     pager or runs "nroff -man" directly, like a hard-bitten,
>     two-fisted-drinking, shirtless veteran of the Unix Wars.
> 
>     (You can leave Australia, but 'Straya never truly leaves you.)



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

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