Re: realloc: Improve documentation

[Alejandro Colomar]

Hi Bruno,

On Sat, Oct 19, 2024 at 02:23:50PM GMT, Bruno Haible wrote:
> I wrote:
> >    According to our doc, there are three possible behaviours of the realloc
> >    function:
> >        With a non-NULL pointer argument p, C17 says that it is
> >        implementation-defined whether realloc (p, 0) frees p. Behavior 
> > varies on
> >        (A) whether realloc (p, 0) always frees p and successfully returns a
> >            null pointer, or
> >        (B) always fails and leaves p valid, or
> >        (C) usually succeeds and returns a unique zero-size object.
> >    And there is also
> >        (D) usually succeeds and returns a pointer to freshly-allocated 
> > memory
> >            of 1 byte.

I'm not entirely sure what you mean by C and D.

> >    (I believe we should mention this fourth possibility in
> >    doc/posix-functions/realloc.texi.)
> 
> Done as follows:
> 
> 
> 2024-10-19  Bruno Haible  <bruno@clisp.org>
> 
>       realloc: Improve documentation.
>       * doc/posix-functions/realloc.texi: Regarding realloc(p,0), document
>       what the platforms actually do, not merely theoretical possibilities.
> 
> diff --git a/doc/posix-functions/realloc.texi 
> b/doc/posix-functions/realloc.texi
> index bd130195c2..9eec174fa1 100644
> --- a/doc/posix-functions/realloc.texi
> +++ b/doc/posix-functions/realloc.texi
> @@ -26,12 +26,30 @@
>  on whether a unique zero-size object is created.  With a non-NULL
>  pointer argument @code{p}, C17 says that it is implementation-defined
>  whether @code{realloc (p, 0)} frees @code{p}.
> -Behavior varies on whether @code{realloc (p, 0)} always frees @code{p}
> -and successfully returns a null pointer, or always
> -fails and leaves @code{p} valid, or usually succeeds and returns a
> -unique zero-size object; a program not suspecting these variations in
> -semantics will leak memory (either the still-valid @code{p}, or the
> -non-NULL return value).
> +Behavior varies among systems: @code{realloc (p, 0)}
> +@itemize
> +@item
> +always frees @code{p} and successfully returns a null pointer
> +(on glibc, AIX, native Windows, Android).
> +@item
> +usually succeeds and
> +returns a pointer to freshly-allocated memory of 1 byte

I would say 0 bytes.  If the implementation does give you one more byte
for free, it's a detail that the user shouldn't know.  Or if you want to
avoid the specific details at all, you could say "freshly-allocated
memory of minimal size".

Also, I don't think it's necessary that it's freshly allocated.  It
would be valid that

        p = malloc(5);
        q = realloc(p, 0);

q == p, so that it reuses the old block.  So I would say that it returns
a pointer to a minimally sized block of memory.

> +(on musl libc, macOS, FreeBSD, NetBSD, OpenBSD, Solaris, Cygwin).

Are you sure OpenBSD is on this list?  I haven't read their source code
myself, but I've heard reports that it returns a unique zero-size
object.  Please check.  Maybe some others (also?) do that.

> +@item
> +always fails and leaves @code{p} valid (no known system does this), or
> +@item
> +usually succeeds and returns a unique zero-size object

By unique you probably mean that it returns a constant; something like

        #define MALLOC_0  ((void *) 0x12341234
        realloc(p, n)
        {
                if (n == 0) {
                        free(p);
                        return MALLOC_0;
                }
                ...
        }

However, that use of "unique" can be confusing with the use of unique
used to refer to the fact that each pointer returned by malloc(3) or
realloc(3) is unique (so different to every other pointers) in the
entire program.

How about referring to a system-predefined magic pointer that refers to
a zero-sized object?  Or something like that.  I'm not sure what's the
best term for it.

> +(no known system does this).
> +@end itemize
> +A program not suspecting these variations in semantics will
> +@itemize
> +@item
> +either leak memory (the still-valid @code{p}),
> +if it assumes the first behaviour but the system implements the second one,
> +@item
> +have double-free bugs,
> +if it assumes the second behaviour but the system implements the first one.
> +@end itemize
>  
>  Extension: Gnulib provides a module @samp{realloc-gnu} that substitutes a
>  @code{realloc} implementation that behaves more like the glibc 
> implementation.

Have a lovely day!
Alex

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

signature.asc
Description: PGP signature