Skip to contentSkip to conversation

malloc.3: Document that realloc(p, 0) is specific to glibc and nonportable

PATCH In review Alejandro Colomar 3 participants 4 messages Jan 9, 2021 – Jan 11, 2021 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 malloc.3: Document that realloc(p, 0) is specific to glibc and nonportable

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.

---

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(-)
man3/malloc.3 +17 -1
index d8b4da62f..467e2438a 100644
@@ -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
Signature · 1 line
2.30.0
#1 lore raw

Hi ALex,

Quoted 32 lines · 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.

Quoted 4 lines

Thanks. Patch applied.

Cheers,

Michael

Quoted 53 lines

---

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(-)
man3/malloc.3 +17 -1
index d8b4da62f..467e2438a 100644
@@ -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
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#2 lore raw
In reply to Alejandro Colomar
Quoted 1 line

A more detailed notice is on realloc(3p).

Yes. But i think it will lead to bugs when there is a documentation that describes the behavior of realloc(), says realloc(ptr,0) will do free(ptr), says realloc() is conforming to POSIX.1-2001, POSIX.1-2008, C89, C99.
But does not mention that the realloc(ptr,0) is not specified in this standards (except C89).

And there are some distributions that do not include the realloc(3p) man page. On my Debian Buster (10) there is no realloc(3p) man page and man realloc goes to the malloc man page of the Linux Programmer's Manual.
But maybe this is a problem of the distributions/Debian?

Quoted 2 lines

Thanks for the report, Johannes!
Please review that your name is correct (I guessed it from the email).

Yes it is. Should i configure my name somewhere?

Kind Regards
Johannes

Am Sa., 9. Jan. 2021 um 21:20 Uhr schrieb Alejandro Colomar <[email protected]>:

Quoted 92 lines

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.

---

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(-)
man3/malloc.3 +17 -2
index d8b4da62f..467e2438a 100644
@@ -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

#3 lore raw
Quoted 9 lines · Johannes Pfister
Quoted 1 line

A more detailed notice is on realloc(3p).

Yes. But i think it will lead to bugs when there is a documentation that describes the behavior of realloc(), says realloc(ptr,0) will do free(ptr), says realloc() is conforming to POSIX.1-2001, POSIX.1-2008, C89, C99.
But does not mention that the realloc(ptr,0) is not specified in this standards (except C89).

Quoted 5 lines

And there are some distributions that do not include the realloc(3p) man page. On my Debian Buster (10) there is no realloc(3p) man page and man realloc goes to the malloc man page of the Linux Programmer's Manual.
But maybe this is a problem of the distributions/Debian?

Hi Johannes,

That was the message for the commit.
See commit: da116d481b79892026029b442fb381713a09f123
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=da116d481b79892026029b442fb381713a09f123>

Quoted 4 lines
Quoted 3 lines

Thanks for the report, Johannes!
Please review that your name is correct (I guessed it from the email).

Yes it is. Should i configure my name somewhere?

No, don't worry. It was only for the "Reported-by" line in the patch.

Regards,

Alex

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/