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

[Alejandro Colomar <alx@kernel.org>]

Hi,

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

Does this look good?


Have a lovely night!
Alex


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

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

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

base-commit: a5342ef55f0a96790bf279a98c9d2a30b19fc9eb
-- 
2.51.0