Re: [PATCH, BUG 211039] malloc.3: Document that realloc(p, 0) is specific to glibc and nonportable

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hi ALex,

On 1/9/21 10:15 PM, Alejandro Colomar wrote:
> A more detailed notice is on realloc(3p).
> 
> ......
> 
> $ man 3p realloc \
>   |sed -n \
>      -e '/APPLICATION USAGE/,/^$/p' \
>      -e '/FUTURE DIRECTIONS/,/^$/p';
> APPLICATION USAGE
>        The description of realloc() has been modified from  pre‐
>        vious  versions  of  this  standard  to  align  with  the
>        ISO/IEC 9899:1999 standard. Previous versions  explicitly
>        permitted  a  call  to  realloc(p,  0)  to free the space
>        pointed to by p and return a null pointer. While this be‐
>        havior  could be interpreted as permitted by this version
>        of the standard, the C language committee have  indicated
>        that   this  interpretation  is  incorrect.  Applications
>        should assume that if realloc() returns a  null  pointer,
>        the  space pointed to by p has not been freed. Since this
>        could lead to double-frees, implementations  should  also
>        set errno if a null pointer actually indicates a failure,
>        and applications should only free the space if errno  was
>        changed.
> 
> FUTURE DIRECTIONS
>        This  standard  defers  to the ISO C standard. While that
>        standard currently has language that might  permit  real‐
>        loc(p, 0), where p is not a null pointer, to free p while
>        still returning a null pointer, the committee responsible
>        for  that standard is considering clarifying the language
>        to explicitly prohibit that alternative.
> 
> Bug: 211039 <https://bugzilla.kernel.org/show_bug.cgi?id=211039>
> Reported-by: Johannes Pfister <johannes.pfister@josttech.ch>
> Cc: libc-alpha@sourceware.org
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks. Patch applied.

Cheers,

Michael

> ---
> 
> Hi Johannes, Michael,
> 
> Thanks for the report, Johannes!
> Please review that your name is correct (I guessed it from the email).
> 
> Michael, please review the wording.
> 
> Thanks,
> 
> Alex
> 
>  man3/malloc.3 | 18 +++++++++++++++++-
>  1 file changed, 17 insertions(+), 1 deletion(-)
> 
> diff --git a/man3/malloc.3 b/man3/malloc.3
> index d8b4da62f..467e2438a 100644
> --- a/man3/malloc.3
> +++ b/man3/malloc.3
> @@ -149,7 +149,8 @@ is equal to zero,
>  and
>  .I ptr
>  is not NULL, then the call is equivalent to
> -.IR free(ptr) .
> +.I free(ptr)
> +(this behavior is nonportable; see NOTES).
>  Unless
>  .I ptr
>  is NULL, it must have been returned by an earlier call to
> @@ -375,6 +376,21 @@ The
>  implementation is tunable via environment variables; see
>  .BR mallopt (3)
>  for details.
> +.SS Nonportable behavior
> +The behavior of
> +.BR realloc ()
> +when
> +.I size
> +is equal to zero,
> +and
> +.I ptr
> +is not NULL,
> +is glibc specific;
> +other implementations may return NULL, and set
> +.IR errno .
> +Portable POSIX programs should avoid it.
> +See
> +.BR realloc (3p).
>  .SH SEE ALSO
>  .\" http://g.oswego.edu/dl/html/malloc.html
>  .\" A Memory Allocator - by Doug Lea
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/