Hi,
I've rewritten the entire subsection from scratch, similar to the email
I wrote detailing the history of the specification. I think this is
explains the turbulent history of this API better, and allows
programmers to decide if they want to trust this API or not.
Does this look good?
Have a lovely night!
Alex
Alejandro Colomar (1):
man/man3/aligned_alloc.3: HISTORY: Document bogus specification from
C11
man/man3/aligned_alloc.3 | 60 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 60 insertions(+)
Range-diff against v3:
1: 6ed874153 ! 1: f19bb100f man/man3/aligned_alloc.3: HISTORY: Document bogus
specification from C11
@@ Metadata
## Commit message ##
man/man3/aligned_alloc.3: HISTORY: Document bogus specification from
C11
- And document that OpenBSD still implements the C11 specification (but
- without the UB).
+ Document the turbulent past of aligned_alloc(), and how libraries have
+ actually implemented it.
Fixes: 7fd1e0f2be21 (2023-05-20; "posix_memalign.3: Update
aligned_alloc(3) to match C17")
Reported-by: Eugene Syromyatnikov <[email protected]>
@@ man/man3/aligned_alloc.3: .SH HISTORY
POSIX.1-2024.
+.SS C11
+In C11,
-+the specification of this function had several issues.
++the specification of this function had
++.UR https://port70.net/~nsz/c/c11/n1570.html#7.22.3.1p2
++several issues
++.UE .
+.IP \[bu] 3
+.I size
+had to be a multiple of
+.IR alignment .
+Otherwise,
+the behavior was undefined.
-+.IP
-+Some implementations still implement that restriction,
-+or claim to have it.
-+.RS
-+.TP
-+OpenBSD
-+The function reports an error
-+if this restriction is violated,
-+without exploiting the UB.
-+.TP
-+FreeBSD
-+.TQ
-+jemalloc
-+The documentation claims to have this restriction,
-+but the implementation works correctly if it is violated.
-+.RE
-+.IP
-+It was only a theoretical UB.
-+No known implementation has ever exploited this UB.
-+.IP
-+This restriction was removed in C17.
+.IP \[bu]
+If
+.I alignment
+was not a power of two,
+the behavior was undefined.
-+.IP
-+No implementations ever exploited this UB.
-+It was only a theoretical UB.
-+.IP
-+This UB was removed in C17.
++.P
++.UR https://www.open-std.org/jtc1/sc22/wg14/www/docs/summary.htm#dr_460
++DR460
++.UE
++reported both cases of UB as unnecessarily dangerous,
++and fixed them with a Technical Corrigendum
++that transformed them into errors.
++.P
++.UR https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2072.htm
++N2072
++.UE
++reported that the requirement
++that
++.I size
++is a multiple of
++.I alignment
++is superfluous,
++and removed it with a Technical Corrigendum.
++.P
++C17 incorporates both technical corrigenda.
++The API has been stable since C17.
++.P
++glibc originally implemented it as silently aligning as
++.I stdc_bit_ceil(alignment)
++instead of
++.IR alignment .
++Since glibc 2.38,
++it implements the C17 specification.
++.P
++Some implementations,
++such as FreeBSD/jemalloc,
++implement the C17 specification,
++even though their documentation claims the C11 specification.
++.P
++Some implementations,
++such as OpenBSD,
++implement C11 amended with DR460,
++even though their documentation claims having undefined behavior.
++.P
++No known implementations
++have exploited the undefined behavior
++in a more dangerous way.
++This function should be safe to use.
.SH NOTES
On many systems there are alignment restrictions, for example, on buffers
used for direct block device I/O.
base-commit: a5342ef55f0a96790bf279a98c9d2a30b19fc9eb
--
2.51.0
