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

[Alejandro Colomar]

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>
---

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
-- 
2.30.0