[musl] malloc.3: Clarify realloc(3) standards conformance

[musl] malloc.3: Clarify realloc(3) standards conformance

[Alejandro Colomar]

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

Hi!

I've applied a patch to document the conformance of realloc(3) and
reallocarray(3).  See below, both the patch, and the formatted changes.

BTW, Paul, Bruno, does gnulib also wrap reallocarray(3)?  If not, it
should.


Have a lovely day!
Alex

---
	commit 7279622113349f32428fa14467ba2aa9ef090394
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   Thu Jun 19 02:27:48 2025 +0200

	    man/man3/malloc.3: VERSIONS, STANDARDS: Clarify conformance of realloc{,array}(3)
	    
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

	diff --git a/man/man3/malloc.3 b/man/man3/malloc.3
	index 9cdfa6b58..bd6cc161f 100644
	--- a/man/man3/malloc.3
	+++ b/man/man3/malloc.3
	@@ -241,6 +241,37 @@ .SH ATTRIBUTES
	 .BR realloc ()
	 T}	Thread safety	MT-Safe
	 .TE
	+.SH VERSIONS
	+The behavior of
	+.I realloc(p,\~0)
	+in glibc doesn't conform to any of
	+C99,
	+C11,
	+POSIX.1-2001,
	+POSIX.1-2008,
	+POSIX.1-2017,
	+or POSIX.1-2024.
	+The C17 specification was changed to make it conforming,
	+but that specification was broken
	+\[em]it is impossible to write code that works portably\[em],
	+and C23 changed it again to make this undefined behavior,
	+acknowledging that the C17 specification was broad enough that
	+undefined behavior wasn't worse than that.
	+The POSIX.1-2024 specification is good,
	+and ideally the ISO C standard should embrace something similar,
	+but glibc does not conform to it.
	+.P
	+musl libc conforms to all versions of ISO C and POSIX.1.
	+.P
	+gnulib provides the
	+.I realloc-posix
	+module,
	+which provides a wrapper
	+.BR realloc ()
	+that conforms to POSIX.1-2024.
	+.P
	+.BR reallocarray ()
	+suffers the same issues in glibc.
	 .SH STANDARDS
	 .TP
	 .BR malloc ()
	@@ -250,10 +281,10 @@ .SH STANDARDS
	 .BR calloc ()
	 .TQ
	 .BR realloc ()
	-C11, POSIX.1-2008.
	+C23, POSIX.1-2024.
	 .TP
	 .BR reallocarray ()
	-None.
	+POSIX.1-2024.
	 .SH HISTORY
	 .TP
	 .BR malloc ()

$ MANWIDTH=72 diffman-git HEAD
--- HEAD^:man/man3/malloc.3
+++ HEAD:man/man3/malloc.3
@@ -126,15 +126,34 @@
        │ realloc()                          │               │         │
        └────────────────────────────────────┴───────────────┴─────────┘
 
+VERSIONS
+       The behavior of realloc(p, 0) in glibc doesn’t conform to any of
+       C99, C11, POSIX.1‐2001, POSIX.1‐2008, POSIX.1‐2017, or
+       POSIX.1‐2024.  The C17 specification was changed to make it con‐
+       forming, but that specification was broken —it is impossible to
+       write code that works portably—, and C23 changed it again to
+       make this undefined behavior, acknowledging that the C17 speci‐
+       fication was broad enough that undefined behavior wasn’t worse
+       than that.  The POSIX.1‐2024 specification is good, and ideally
+       the ISO C standard should embrace something similar, but glibc
+       does not conform to it.
+
+       musl libc conforms to all versions of ISO C and POSIX.1.
+
+       gnulib provides the realloc‐posix module, which provides a wrap‐
+       per realloc() that conforms to POSIX.1‐2024.
+
+       reallocarray() suffers the same issues in glibc.
+
 STANDARDS
        malloc()
        free()
        calloc()
        realloc()
-              C11, POSIX.1‐2008.
+              C23, POSIX.1‐2024.
 
        reallocarray()
-              None.
+              POSIX.1‐2024.
 
 HISTORY
        malloc()


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

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

[musl] Re: malloc.3: Clarify realloc(3) standards conformance

[Collin Funk]

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

Alejandro Colomar <alx@kernel.org> writes:

> BTW, Paul, Bruno, does gnulib also wrap reallocarray(3)?  If not, it
> should.

Yep, Gnulib has had it since 2017 after it was added to glibc.

Collin

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

[musl] Re: malloc.3: Clarify realloc(3) standards conformance

[Alejandro Colomar]

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

Hi Paul,

On Wed, Jun 18, 2025 at 05:49:43PM -0700, Collin Funk wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> 
> > BTW, Paul, Bruno, does gnulib also wrap reallocarray(3)?  If not, it
> > should.
> 
> Yep, Gnulib has had it since 2017 after it was added to glibc.

Thanks!  Yep, now I revised the patch that fixed the gnulib behavior,
and it is mentioned in the changelog

<https://gitweb.git.savannah.gnu.org/gitweb/?p=gnulib.git;a=patch;h=d884e6fc4a609dda5428fa84d19cb656d7e317f8>


Have a lovely day!
Alex

> 
> Collin



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

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

Re: [musl] malloc.3: Clarify realloc(3) standards conformance

[Rich Felker]

On Thu, Jun 19, 2025 at 02:42:14AM +0200, Alejandro Colomar wrote:
> Hi!
> 
> I've applied a patch to document the conformance of realloc(3) and
> reallocarray(3).  See below, both the patch, and the formatted changes.
> 
> BTW, Paul, Bruno, does gnulib also wrap reallocarray(3)?  If not, it
> should.
> 
> 
> Have a lovely day!
> Alex
> 
> ---
> 	commit 7279622113349f32428fa14467ba2aa9ef090394
> 	Author: Alejandro Colomar <alx@kernel.org>
> 	Date:   Thu Jun 19 02:27:48 2025 +0200
> 
> 	    man/man3/malloc.3: VERSIONS, STANDARDS: Clarify conformance of realloc{,array}(3)
> 	    
> 	    Signed-off-by: Alejandro Colomar <alx@kernel.org>
> 
> 	diff --git a/man/man3/malloc.3 b/man/man3/malloc.3
> 	index 9cdfa6b58..bd6cc161f 100644
> 	--- a/man/man3/malloc.3
> 	+++ b/man/man3/malloc.3
> 	@@ -241,6 +241,37 @@ .SH ATTRIBUTES
> 	 .BR realloc ()
> 	 T}	Thread safety	MT-Safe
> 	 .TE
> 	+.SH VERSIONS
> 	+The behavior of
> 	+.I realloc(p,\~0)
> 	+in glibc doesn't conform to any of
> 	+C99,
> 	+C11,
> 	+POSIX.1-2001,
> 	+POSIX.1-2008,
> 	+POSIX.1-2017,
> 	+or POSIX.1-2024.
> 	+The C17 specification was changed to make it conforming,
> 	+but that specification was broken
> 	+\[em]it is impossible to write code that works portably\[em],
> 	+and C23 changed it again to make this undefined behavior,
> 	+acknowledging that the C17 specification was broad enough that
> 	+undefined behavior wasn't worse than that.
> 	+The POSIX.1-2024 specification is good,
> 	+and ideally the ISO C standard should embrace something similar,
> 	+but glibc does not conform to it.
> 	+.P
> 	+musl libc conforms to all versions of ISO C and POSIX.1.
> 	+.P
> 	+gnulib provides the
> 	+.I realloc-posix
> 	+module,
> 	+which provides a wrapper
> 	+.BR realloc ()
> 	+that conforms to POSIX.1-2024.
> 	+.P
> 	+.BR reallocarray ()
> 	+suffers the same issues in glibc.
> 	 .SH STANDARDS
> 	 .TP
> 	 .BR malloc ()
> 	@@ -250,10 +281,10 @@ .SH STANDARDS
> 	 .BR calloc ()
> 	 .TQ
> 	 .BR realloc ()
> 	-C11, POSIX.1-2008.
> 	+C23, POSIX.1-2024.
> 	 .TP
> 	 .BR reallocarray ()
> 	-None.
> 	+POSIX.1-2024.
> 	 .SH HISTORY
> 	 .TP
> 	 .BR malloc ()
> 
> $ MANWIDTH=72 diffman-git HEAD
> --- HEAD^:man/man3/malloc.3
> +++ HEAD:man/man3/malloc.3
> @@ -126,15 +126,34 @@
>         │ realloc()                          │               │         │
>         └────────────────────────────────────┴───────────────┴─────────┘
>  
> +VERSIONS
> +       The behavior of realloc(p, 0) in glibc doesn’t conform to any of
> +       C99, C11, POSIX.1‐2001, POSIX.1‐2008, POSIX.1‐2017, or
> +       POSIX.1‐2024.  The C17 specification was changed to make it con‐
> +       forming, but that specification was broken —it is impossible to
> +       write code that works portably—, and C23 changed it again to
> +       make this undefined behavior, acknowledging that the C17 speci‐
> +       fication was broad enough that undefined behavior wasn’t worse
> +       than that.  The POSIX.1‐2024 specification is good, and ideally
> +       the ISO C standard should embrace something similar, but glibc
> +       does not conform to it.
> +
> +       musl libc conforms to all versions of ISO C and POSIX.1.
> +
> +       gnulib provides the realloc‐posix module, which provides a wrap‐
> +       per realloc() that conforms to POSIX.1‐2024.
> +
> +       reallocarray() suffers the same issues in glibc.

I don't like this text, at least not the second half. Man pages are
not supposed to be polemic. They should be documenting the interface
and what standards the implementation does or doesn't conform to, not
declaring changes to the standards good or bad, nor stating as
undisputed fact aspects of conformance that seem to be under
disagreement.

Rich

Re: [musl] malloc.3: Clarify realloc(3) standards conformance

[Alejandro Colomar]

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

Hi Rich,

On Wed, Jun 18, 2025 at 10:15:10PM -0400, Rich Felker wrote:
> > $ MANWIDTH=72 diffman-git HEAD
> > --- HEAD^:man/man3/malloc.3
> > +++ HEAD:man/man3/malloc.3
> > @@ -126,15 +126,34 @@
> >         │ realloc()                          │               │         │
> >         └────────────────────────────────────┴───────────────┴─────────┘
> >  
> > +VERSIONS
> > +       The behavior of realloc(p, 0) in glibc doesn’t conform to any of
> > +       C99, C11, POSIX.1‐2001, POSIX.1‐2008, POSIX.1‐2017, or
> > +       POSIX.1‐2024.  The C17 specification was changed to make it con‐
> > +       forming, but that specification was broken —it is impossible to
> > +       write code that works portably—, and C23 changed it again to
> > +       make this undefined behavior, acknowledging that the C17 speci‐
> > +       fication was broad enough that undefined behavior wasn’t worse
> > +       than that.  The POSIX.1‐2024 specification is good, and ideally
> > +       the ISO C standard should embrace something similar, but glibc
> > +       does not conform to it.
> > +
> > +       musl libc conforms to all versions of ISO C and POSIX.1.
> > +
> > +       gnulib provides the realloc‐posix module, which provides a wrap‐
> > +       per realloc() that conforms to POSIX.1‐2024.
> > +
> > +       reallocarray() suffers the same issues in glibc.
> 
> I don't like this text, at least not the second half. Man pages are
> not supposed to be polemic. They should be documenting the interface
> and what standards the implementation does or doesn't conform to, not
> declaring changes to the standards good or bad,

Okay, I'll reword, and try to be more objective.  A new BUGS section
would be good for it:

$ MANWIDTH=72 diffman-git -U8
grotty:<standard input>:(<standard input>):9: warning: unrecognized X command 'sgr 0' ignored
grotty:<standard input>:(<standard input>):9: warning: unrecognized X command 'sgr 0' ignored
--- HEAD:man/man3/malloc.3
+++ ./man/man3/malloc.3
@@ -129,19 +129,17 @@
 VERSIONS
        The behavior of realloc(p, 0) in glibc doesn’t conform to any of
        C99, C11, POSIX.1‐2001, POSIX.1‐2008, POSIX.1‐2017, or
        POSIX.1‐2024.  The C17 specification was changed to make it con‐
        forming, but that specification was broken —it is impossible to
        write code that works portably—, and C23 changed it again to
        make this undefined behavior, acknowledging that the C17 speci‐
        fication was broad enough that undefined behavior wasn’t worse
-       than that.  The POSIX.1‐2024 specification is good, and ideally
-       the ISO C standard should embrace something similar, but glibc
-       does not conform to it.
+       than that.
 
        musl libc conforms to all versions of ISO C and POSIX.1.
 
        gnulib provides the realloc‐posix module, which provides a wrap‐
        per realloc() that conforms to POSIX.1‐2024.
 
        reallocarray() suffers the same issues in glibc.
 
@@ -228,16 +226,29 @@
        POSIX requires memory allocators to set errno upon failure.
        However, the C standard does not require this, and applications
        portable to non‐POSIX platforms should not assume this.
 
        Portable programs should not use private memory allocators, as
        POSIX and the C standard do not allow replacement of malloc(),
        free(), calloc(), and realloc().
 
+BUGS
+       Programmers would naturally expect that realloc(p, n) is consis‐
+       tent with free(p) and malloc(n).  This is not explicitly re‐
+       quired by POSIX.1‐2024, but all conforming implementations are
+       consistent with that.
+
+       The glibc implementation of realloc() is not consistent with
+       that, and as a consequence, it is dangerous to call
+       realloc(p, 0) in glibc.
+
+       A trivial workaround for glibc is calling it as
+       realloc(p, n?:1).
+
 EXAMPLES
        #include <err.h>
        #include <stddef.h>
        #include <stdio.h>
        #include <stdlib.h>
        #include <string.h>
 
        #define MALLOCARRAY(n, type)  ((type *) my_mallocarray(n, sizeof(type)))

> nor stating as
> undisputed fact aspects of conformance that seem to be under
> disagreement.

You're welcome to ask the committee for a clarification of the wording.
I don't think it's open to interpretation.


Have a lovely day!
Alex

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

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

Re: [musl] malloc.3: Clarify realloc(3) standards conformance

[Vincent Lefevre]

On 2025-06-19 12:54:52 +0200, Alejandro Colomar wrote:
> +BUGS
> +       Programmers would naturally expect that realloc(p, n) is consis‐
> +       tent with free(p) and malloc(n).  This is not explicitly re‐
> +       quired by POSIX.1‐2024, but all conforming implementations are
> +       consistent with that.
> +
> +       The glibc implementation of realloc() is not consistent with
> +       that, and as a consequence, it is dangerous to call
> +       realloc(p, 0) in glibc.
> +
> +       A trivial workaround for glibc is calling it as
> +       realloc(p, n?:1).

n?:1 is a GNU extension:

warning: ISO C forbids omitting the middle term of a ‘?:’ expression [-Wpedantic]

with gcc -pedantic -std=c23, and such code should not be given in
examples (as a workaround should still be valid for portable code).

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

Re: [musl] malloc.3: Clarify realloc(3) standards conformance

[Rich Felker]

On Thu, Jun 19, 2025 at 02:36:13PM +0200, Vincent Lefevre wrote:
> On 2025-06-19 12:54:52 +0200, Alejandro Colomar wrote:
> > +BUGS
> > +       Programmers would naturally expect that realloc(p, n) is consis‐
> > +       tent with free(p) and malloc(n).  This is not explicitly re‐
> > +       quired by POSIX.1‐2024, but all conforming implementations are
> > +       consistent with that.
> > +
> > +       The glibc implementation of realloc() is not consistent with
> > +       that, and as a consequence, it is dangerous to call
> > +       realloc(p, 0) in glibc.
> > +
> > +       A trivial workaround for glibc is calling it as
> > +       realloc(p, n?:1).
> 
> n?:1 is a GNU extension:
> 
> warning: ISO C forbids omitting the middle term of a ‘?:’ expression [-Wpedantic]
> 
> with gcc -pedantic -std=c23, and such code should not be given in
> examples (as a workaround should still be valid for portable code).

Indeed. n?n:1 or n|!n or write it out in a non golf form.

Re: [musl] malloc.3: Clarify realloc(3) standards conformance

[Alejandro Colomar]

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

Hi Vincent,

On Thu, Jun 19, 2025 at 02:36:13PM +0200, Vincent Lefevre wrote:
> On 2025-06-19 12:54:52 +0200, Alejandro Colomar wrote:
> > +BUGS
> > +       Programmers would naturally expect that realloc(p, n) is consis‐
> > +       tent with free(p) and malloc(n).  This is not explicitly re‐
> > +       quired by POSIX.1‐2024, but all conforming implementations are
> > +       consistent with that.
> > +
> > +       The glibc implementation of realloc() is not consistent with
> > +       that, and as a consequence, it is dangerous to call
> > +       realloc(p, 0) in glibc.
> > +
> > +       A trivial workaround for glibc is calling it as
> > +       realloc(p, n?:1).
> 
> n?:1 is a GNU extension:
> 
> warning: ISO C forbids omitting the middle term of a ‘?:’ expression [-Wpedantic]
> 
> with gcc -pedantic -std=c23, and such code should not be given in
> examples (as a workaround should still be valid for portable code).

Hmmm, I guess I can write it as n?n:1.

I'll write a proposal to standardize ?: in ISO C too.


Have a lovely day!
Alex

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

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

Re: [musl] [v2] malloc.3: Clarify realloc(3) standards conformance

[Rich Felker]

On Thu, Jun 19, 2025 at 03:57:47PM +0200, Alejandro Colomar wrote:
> Hi,
> 
> Here's a revision of this change, addressing some concerns.  I'm only
> showing the formatted changes, since the patch itself is unimportant.
> 
> 
> Have a lovely day!
> Alex
> 
> ---
> $ MANWIDTH=72 diffman-git HEAD
> --- HEAD^:man/man3/malloc.3
> +++ HEAD:man/man3/malloc.3
> @@ -126,15 +126,32 @@
>         │ realloc()                          │               │         │
>         └────────────────────────────────────┴───────────────┴─────────┘
>  
> +VERSIONS
> +       The behavior of realloc(p, 0) in glibc doesn’t conform to any of
> +       C99, C11, POSIX.1‐2001, POSIX.1‐2008, POSIX.1‐2017, or
> +       POSIX.1‐2024.  The C17 specification was changed to make it con‐
> +       forming, but that specification was broken —it is impossible to
> +       write code that works portably—, and C23 changed it again to
> +       make this undefined behavior, acknowledging that the C17 speci‐
> +       fication was broad enough that undefined behavior wasn’t worse
> +       than that.

This is still full of your polemics. The word "broken" generally
belongs in personal blog posts, not a manual that's supposed to be
documenting the facts of an interface. In fact it is very possible to
write code which works portably: by refraining from passing 0.
Regardless of what action is taken here on the standards or
documentation, that's already been necessary for a long time, and will
continue to be necessary for a long time, because of the existence of
implementations on which passing 0 has inconsistent results.

I would suggest something more like:

      The behavior of realloc(p, 0) in glibc doesn’t conform to any of
      C99, C11, POSIX.1‐2001, POSIX.1‐2008, POSIX.1‐2017, or
      POSIX.1‐2024. C11 was amended in 2017 to allow the glibc
      behavior [insert description of exactly how that was done, I
      forget] and C23 followed up by making the behavior explicitly
      undefined.

In particular, this text is purely matters of fact, no statement of
your or my preferred future outcome or disagreement with what
happened.

I would also move it to CONFORMANCE rather than VERSIONS since
VERSIONS is normally about differences between versions of the
implementation being described, not conformance requirement
differences between versions of the standard.

> +BUGS
> +       Programmers would naturally expect that realloc(p, size) is con‐
> +       sistent with free(p) and malloc(size).  This is not explicitly
> +       required by POSIX.1‐2024 or C11, but all conforming implementa‐
> +       tions are consistent with that.

This has not historically been a conformance requirement and it is not
one now. Because the behavior is undefined, arbitrarily-inconsistent
behavior is conforming.

It's possible to read this as not stating a conformance requirement,
just a matter of fact that all implementations which conform(ed to
past versions of the standard) happened to also be consistent here.
But in that case I would very much prefer if you make it clear by just
saying that they're consistent on [some explicit list or description
of the class of implementations you've reviewed to have this
property].

> +       The glibc implementation of realloc() is not consistent with
> +       that, and as a consequence, it is dangerous to call
> +       realloc(p, 0) in glibc.

It's not dangerous if you know what it's doing. Rather it's
non-portable. It does something predictable that you can use safely,
but the way you use it safely is different from other, more consistent
implementations in a way that can be a footgun.

> +       A trivial workaround for glibc is calling it as
> +       realloc(p, size?size:1).

It should probably be noted that use of such a workaround sacrifices
the ability to diagnose logic errors (via sanitizers, valgrind, etc.)
where 1 byte is written to allocated memory that was not intended to
have any accessible bytes of storage.

Rich