man/man3/posix_memalign.3: Several fixes, and split the page
Alejandro Colomar
maintainercover man/man3/posix_memalign.3: Several fixes, and split the page
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 sectionSignature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH 1/12 man/man3/posix_memalign.3: Remove confusing exception
This is already a requirement of memalign(3). aligned_alloc(3) is indeed exactly equivalent to memalign(3), since ISO C17.
--- man/man3/posix_memalign.3 | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-)
man/man3/posix_memalign.3 +1 -4
@@ -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 ()
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH 2/12 man/man3/posix_memalign.3: wfix
In reply to Alejandro ColomarDocument aligned_alloc(3), and then say memalign(3) is equivalent, instead of the other way around. aligned_alloc(3) is the important one.
--- man/man3/posix_memalign.3 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
man/man3/posix_memalign.3 +4 -4
@@ -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 ()
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH 3/12 man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to ISO C17, not C11
In reply to Alejandro ColomarISO C17 removed a restriction that was in place in C11. This documentation doesn't conform to C11; it conforms to C17.
--- man/man3/posix_memalign.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
man/man3/posix_memalign.3 +1 -1
@@ -162,7 +162,7 @@ .SH ATTRIBUTES .SH STANDARDS .TP .BR aligned_alloc () -C11. +C17. .TP .BR posix_memalign () POSIX.1-2008.
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH 4/12 man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to C23
In reply to Alejandro Colomar--- man/man3/posix_memalign.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
man/man3/posix_memalign.3 +1 -1
@@ -162,7 +162,7 @@ .SH ATTRIBUTES .SH STANDARDS .TP .BR aligned_alloc () -C17. +C23. .TP .BR posix_memalign () POSIX.1-2008.
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH 5/12 man/man3/posix_memalign.3: STANDARDS: aligned_alloc() and posix_memalign() conform to POSIX.1-2024
In reply to Alejandro Colomar--- man/man3/posix_memalign.3 | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-)
man/man3/posix_memalign.3 +5 -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.
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH 6/12 man/man3/{posix_,}memalign.3: Split memalign() from posix_memalign(3)
In reply to Alejandro Colomar--- man/man3/memalign.3 | 77 ++++++++++++++++++++++++++++++++++++++- man/man3/posix_memalign.3 | 46 ++--------------------- 2 files changed, 79 insertions(+), 44 deletions(-)
man/man3/memalign.3 +76 -1
@@ -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)
man/man3/posix_memalign.3 +3 -43
113 lines not on this page · raw message
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH 7/12 man/man3/{posix_memalign,pvalloc}.3: Split pvalloc() from posix_memalign(3)
In reply to Alejandro Colomar--- man/man3/posix_memalign.3 | 26 ++++----------------- man/man3/pvalloc.3 | 49 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 52 insertions(+), 23 deletions(-)
man/man3/posix_memalign.3 +4 -22
@@ -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
man/man3/pvalloc.3 +48 -1
49 lines not on this page · raw message
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH 8/12 man/man3/{posix_memalign,valloc}.3: Split valloc() from posix_memalign(3)
In reply to Alejandro Colomar--- man/man3/posix_memalign.3 | 64 ++-------------------------- man/man3/valloc.3 | 89 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 91 insertions(+), 62 deletions(-)
man/man3/posix_memalign.3 +3 -61
@@ -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)
man/man3/valloc.3 +88 -1
89 lines not on this page · raw message
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH 9/12 man/man3/{aligned_alloc,posix_memalign}.3: Split aligned_alloc() from posix_memalign(3)
In reply to Alejandro Colomar--- man/man3/aligned_alloc.3 | 99 ++++++++++++++++++++++++++++++++++++++- man/man3/posix_memalign.3 | 56 +++------------------- 2 files changed, 105 insertions(+), 50 deletions(-)
man/man3/aligned_alloc.3 +98 -1
@@ -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)
man/man3/posix_memalign.3 +7 -49
103 lines not on this page · raw message
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH 10/12 man/man3/posix_memalign.3: CAVEATS: Add section, and move paragraph to it
In reply to Alejandro Colomar--- man/man3/posix_memalign.3 | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-)
man/man3/posix_memalign.3 +8 -7
@@ -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)
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH 11/12 man/man3/posix_memalign.3: Remove redundant text
In reply to Alejandro Colomar--- man/man3/posix_memalign.3 | 16 ---------------- 1 file changed, 16 deletions(-)
man/man3/posix_memalign.3 +0 -16
@@ -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
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH 12/12 man/man3/posix_memalign.3: NOTES: Remove superfluous section
In reply to Alejandro Colomar--- man/man3/posix_memalign.3 | 5 ----- 1 file changed, 5 deletions(-)
man/man3/posix_memalign.3 +0 -5
@@ -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 ()
Signature · 1 line
2.51.0
Quoted 2 lines · Alejandro Colomar
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.
Signature · 3 lines
Eugene Syromyatnikov mailto:[email protected] xmpp:esyr@jabber.{ru|org}
Alejandro Colomar
maintainerHi Eugene,
Quoted 7 lines · Eugene Syromyatnikov
Quoted 2 lines · Alejandro Colomar
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.
Quoted 2 lines
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
Signature · 1 line
<https://www.alejandro-colomar.es>
Quoted 12 lines · Alejandro Colomar
Hi Eugene,
Quoted 7 lines · Eugene Syromyatnikov
Quoted 2 lines · Alejandro Colomar
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,
Quoted 5 lines
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
Quoted 27 lines
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.
Quoted 2 lines
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; }
Quoted 7 lines
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.
Quoted 9 lines
Prior to that implementation, glibc had
aligned_alloc(3)as an alias for memalign(3).Have a lovely night!
Alex
Signature · 3 lines
Eugene Syromyatnikov mailto:[email protected] xmpp:esyr@jabber.{ru|org}
Alejandro Colomar
maintainer[CC += Ingo]
Hi Eugene, Ingo,
Quoted 1 line · Eugene Syromyatnikov
On Wed, Dec 10, 2025 at 6:12 PM Alejandro Colomar <[email protected]> wrote:
[...]
Quoted 35 lines
Quoted 27 lines
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.
Quoted 2 lines
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; }Quoted 7 lines
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); }
Quoted 8 lines
OpenBSD's libc isn't:
https://github.com/openbsd/src/blob/master/lib/libc/stdlib/malloc.c#L2336And 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.
Quoted 2 lines
Quoted 2 lines
Prior to that implementation, glibc had
aligned_alloc(3)as an alias for memalign(3).
[...]
[Reordered]
Quoted 13 lines
Quoted 13 lines · Eugene Syromyatnikov
Quoted 7 lines · Alejandro Colomar
Quoted 2 lines
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.
Quoted 8 lines
Quoted 1 line
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.
Quoted 7 lines
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 toposix_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;
}Quoted 4 lines
The other aspect (which is irrelevant to this
discussion, but doesn't adds points toaligned_allocin 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)?
Quoted 3 lines
[1] https://open-std.org/JTC1/SC22/WG14/www/docs/summary.htm#dr_460
Have a lovely night!
Alex
Signature · 1 line
<https://www.alejandro-colomar.es>
Quoted 8 lines · Alejandro Colomar
[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.
Quoted 17 lines
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.
Quoted 6 lines
Quoted 4 lines
The other aspect (which is irrelevant to this
discussion, but doesn't adds points toaligned_allocin 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.
Quoted 1 line
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
Signature · 3 lines
Eugene Syromyatnikov mailto:[email protected] xmpp:esyr@jabber.{ru|org}
Alejandro Colomar
maintainerHi Eugene,
Quoted 10 lines · Eugene Syromyatnikov
Quoted 8 lines · Alejandro Colomar
[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.
Quoted 6 lines
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. :)
Quoted 28 lines
Quoted 17 lines
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 thansizeof(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.
Quoted 3 lines
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.
Quoted 7 lines
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.
Quoted 7 lines
Quoted 6 lines
Quoted 4 lines
The other aspect (which is irrelevant to this
discussion, but doesn't adds points toaligned_allocin 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)?
Quoted 8 lines
No.
Quoted 1 line
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. :)
Quoted 5 lines
[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
Signature · 1 line
<https://www.alejandro-colomar.es>
Alejandro Colomar
maintainerv2 cover man/man3/posix_memalign.3: Several fixes, and split the page
In reply to Alejandro ColomarHi!
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
C11man/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 <[email protected]>
## 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 C11Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v2 1/14 man/man3/posix_memalign.3: Remove confusing exception
This is already a requirement of memalign(3). aligned_alloc(3) is indeed exactly equivalent to memalign(3), since ISO C17.
--- man/man3/posix_memalign.3 | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-)
man/man3/posix_memalign.3 +1 -4
@@ -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 ()
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v2 2/14 man/man3/posix_memalign.3: wfix
In reply to Alejandro ColomarDocument aligned_alloc(3), and then say memalign(3) is equivalent, instead of the other way around. aligned_alloc(3) is the important one.
--- man/man3/posix_memalign.3 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
man/man3/posix_memalign.3 +4 -4
@@ -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 ()
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v2 3/14 man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to C17, not C11
In reply to Alejandro ColomarISO C17 removed a restriction that was in place in C11. This documentation doesn't conform to C11; it conforms to C17.
--- man/man3/posix_memalign.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
man/man3/posix_memalign.3 +1 -1
@@ -162,7 +162,7 @@ .SH ATTRIBUTES .SH STANDARDS .TP .BR aligned_alloc () -C11. +C17. .TP .BR posix_memalign () POSIX.1-2008.
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v2 4/14 man/man3/posix_memalign.3: STANDARDS: aligned_alloc() conforms to C23
In reply to Alejandro Colomar--- man/man3/posix_memalign.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
man/man3/posix_memalign.3 +1 -1
@@ -162,7 +162,7 @@ .SH ATTRIBUTES .SH STANDARDS .TP .BR aligned_alloc () -C17. +C23. .TP .BR posix_memalign () POSIX.1-2008.
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v2 5/14 man/man3/posix_memalign.3: STANDARDS: aligned_alloc() and posix_memalign() conform to POSIX.1-2024
In reply to Alejandro Colomar--- man/man3/posix_memalign.3 | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-)
man/man3/posix_memalign.3 +5 -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.
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v2 6/14 man/man3/{posix_,}memalign.3: Split memalign() from posix_memalign(3)
In reply to Alejandro Colomar--- man/man3/memalign.3 | 76 ++++++++++++++++++++++++++++++++++++++- man/man3/posix_memalign.3 | 46 ++---------------------- 2 files changed, 78 insertions(+), 44 deletions(-)
man/man3/memalign.3 +75 -1
@@ -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)
man/man3/posix_memalign.3 +3 -43
113 lines not on this page · raw message
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v2 7/14 man/man3/{posix_memalign,pvalloc}.3: Split pvalloc() from posix_memalign(3)
In reply to Alejandro Colomar--- man/man3/posix_memalign.3 | 26 ++++----------------- man/man3/pvalloc.3 | 49 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 52 insertions(+), 23 deletions(-)
man/man3/posix_memalign.3 +4 -22
@@ -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
man/man3/pvalloc.3 +48 -1
49 lines not on this page · raw message
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v2 8/14 man/man3/{posix_memalign,valloc}.3: Split valloc() from posix_memalign(3)
In reply to Alejandro Colomar--- man/man3/posix_memalign.3 | 64 ++-------------------------- man/man3/valloc.3 | 89 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 91 insertions(+), 62 deletions(-)
man/man3/posix_memalign.3 +3 -61
@@ -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)
man/man3/valloc.3 +88 -1
89 lines not on this page · raw message
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v2 9/14 man/man3/{aligned_alloc,posix_memalign}.3: Split aligned_alloc() from posix_memalign(3)
In reply to Alejandro Colomar--- man/man3/aligned_alloc.3 | 99 ++++++++++++++++++++++++++++++++++++++- man/man3/posix_memalign.3 | 56 +++------------------- 2 files changed, 105 insertions(+), 50 deletions(-)
man/man3/aligned_alloc.3 +98 -1
@@ -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)
man/man3/posix_memalign.3 +7 -49
103 lines not on this page · raw message
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v2 10/14 man/man3/posix_memalign.3: CAVEATS: Add section, and move paragraph to it
In reply to Alejandro Colomar--- man/man3/posix_memalign.3 | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-)
man/man3/posix_memalign.3 +8 -7
@@ -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)
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v2 11/14 man/man3/posix_memalign.3: Remove redundant text
In reply to Alejandro Colomar--- man/man3/posix_memalign.3 | 16 ---------------- 1 file changed, 16 deletions(-)
man/man3/posix_memalign.3 +0 -16
@@ -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
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v2 12/14 man/man3/posix_memalign.3: NOTES: Remove superfluous section
In reply to Alejandro Colomar--- man/man3/posix_memalign.3 | 5 ----- 1 file changed, 5 deletions(-)
man/man3/posix_memalign.3 +0 -5
@@ -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 ()
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v2 13/14 man/man3/memalign.3: wfix
In reply to Alejandro Colomar--- man/man3/memalign.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
man/man3/memalign.3 +3 -2
@@ -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
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v2 14/14 man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
In reply to Alejandro ColomarAnd document that OpenBSD still implements the C11 specification (but without the UB).
--- man/man3/aligned_alloc.3 | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+)
man/man3/aligned_alloc.3 +29 -0
@@ -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.
Signature · 1 line
2.51.0
G'day (or night, as I'm writing this),
Quoted 13 lines · 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.
Quoted 3 lines
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
Alejandro Colomar
maintainerQuoted 1 line · Seth McDonald
G'day (or night, as I'm writing this),
G'day Seth!
Quoted 3 lines · Alejandro Colomar
Quoted 2 lines
Hi!
Since nobody complained about patches 1..13, I've pushed them. I'll continue work on patch 14.
Quoted 37 lines
Quoted 11 lines
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.Quoted 3 lines
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.
Quoted 4 lines
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
Signature · 1 line
<https://www.alejandro-colomar.es>
Alejandro Colomar
maintainerv3 cover man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
In reply to Alejandro ColomarHi!
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
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v3 1/1 man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
And document that OpenBSD still implements the C11 specification (but without the UB).
--- man/man3/aligned_alloc.3 | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+)
man/man3/aligned_alloc.3 +40 -0
@@ -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.
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerRe: [PATCH v3 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
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
Signature · 1 line
<https://www.alejandro-colomar.es>
Re: [PATCH v3 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
In reply to Alejandro ColomarReview
Quoted 2 lines · Alejandro Colomar
(quoted diff) +2
-0+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.
man/man3/aligned_alloc.3 .SH HISTORY · line 113
Quoted 5 lines
+.IP \[bu]
man/man3/aligned_alloc.3 +4
-0+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:[email protected]
xmpp:esyr@jabber.{ru|org}
Re: [PATCH v3 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
Quoted 17 lines · Eugene Syromyatnikov
Review
Quoted 2 lines · Alejandro Colomar
(quoted diff) +2
-0+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
_usedto_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.
Quoted 8 lines
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_allocand 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.
Quoted 9 lines
man/man3/aligned_alloc.3 .SH HISTORY · line 113
Quoted 5 lines
+.IP \[bu]
man/man3/aligned_alloc.3 +4
-0+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.
Quoted 4 lines
--
Eugene Syromyatnikov
mailto:[email protected]
xmpp:esyr@jabber.{ru|org}
--
Eugene Syromyatnikov
mailto:[email protected]
xmpp:esyr@jabber.{ru|org}
Alejandro Colomar
maintainerRe: [PATCH v3 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
[CC += Martin Sebor]
Hi Eugene,
Quoted 27 lines · Eugene Syromyatnikov
Quoted 17 lines · Eugene Syromyatnikov
Review
Quoted 2 lines · Alejandro Colomar
(quoted diff) +2
-0+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
_usedto_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.Quoted 8 lines
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_allocand C11 together", or something along those lines.
Quoted 12 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
Signature · 1 line
<https://www.alejandro-colomar.es>
Alejandro Colomar
maintainerRe: [PATCH v3 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
Hi Eugene,
Quoted 22 lines · Alejandro Colomar
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):(quoted diff) +0
-2- 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.
Quoted 8 lines
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
Signature · 1 line
<https://www.alejandro-colomar.es>
Alejandro Colomar
maintainerRe: [PATCH v3 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
In reply to Eugene SyromyatnikovHi Eugene,
Quoted 8 lines · Eugene Syromyatnikov
Review
Quoted 2 lines · Alejandro Colomar
(quoted diff) +2
-0+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?
Quoted 3 lines
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.
Quoted 7 lines
But that
is also true that C11_usedto_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. :)
Quoted 3 lines
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.
Quoted 6 lines
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_allocand C11 together", or something along those lines.
Quoted 8 lines
man/man3/aligned_alloc.3 .SH HISTORY · line 113
Quoted 5 lines
+.IP \[bu]
man/man3/aligned_alloc.3 +4
-0+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
Signature · 1 line
<https://www.alejandro-colomar.es>
Alejandro Colomar
maintainerv4 cover man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
In reply to Alejandro ColomarHi,
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.
@@ 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
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v4 1/1 man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
Document the turbulent past of aligned_alloc(), and how libraries have actually implemented it.
--- man/man3/aligned_alloc.3 | 60 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+)
man/man3/aligned_alloc.3 +60 -0
@@ -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.
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerRe: [PATCH v4 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
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
Signature · 1 line
<https://www.alejandro-colomar.es>
Re: [PATCH v4 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
In reply to Alejandro ColomarHi Alex,
Content looks great; as you've likely guessed, I have commentary only on man(7) markup.
Quoted 6 lines · Alejandro Colomar
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?
Quoted 2 lines · Alejandro Colomar
Document the turbulent past of
aligned_alloc(), and how libraries have actually implemented it.
Nice summary!
[...]
Quoted 4 lines
man/man3/aligned_alloc.3 +4
-0+the specification of this function had +.UR https://port70.net/~nsz/c/c11/n1570.html#7.22.3.1p2 +several issues +.UE .
[...]
Quoted 3 lines
+.UR https://www.open-std.org/jtc1/sc22/wg14/www/docs/summary.htm#dr_460
+DR460
+.UE
[...]
Quoted 3 lines
+.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.
Id 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.)
Alejandro Colomar
maintainerRe: [PATCH v4 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11
Hi Branden,
Quoted 11 lines · G. Branden Robinson
Hi Alex,
Content looks great; as you've likely guessed, I have commentary only on man(7) markup.
Quoted 5 lines · Alejandro Colomar
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.
Quoted 7 lines
Quoted 1 line
Does this look good?
Quoted 2 lines · Alejandro Colomar
Document the turbulent past of
aligned_alloc(), and how libraries have actually implemented it.Nice summary!
Thanks! :-)
Quoted 14 lines
[...]
Quoted 4 lines
man/man3/aligned_alloc.3 +4
-0+the specification of this function had +.UR https://port70.net/~nsz/c/c11/n1570.html#7.22.3.1p2 +several issues +.UE .[...]
Quoted 3 lines
+.UR https://www.open-std.org/jtc1/sc22/wg14/www/docs/summary.htm#dr_460
+DR460
+.UE[...]
Quoted 3 lines
+.UR https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2072.htm
+N2072
+.UE
Quoted 5 lines
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
Quoted 47 lines
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.)
Signature · 1 line
<https://www.alejandro-colomar.es>