[PATCH] realloc: document portability problem

[Eric Blake]

* doc/posix-functions/realloc.texi (realloc): Mention pitfalls of
passing 0 size to realloc.

Signed-off-by: Eric Blake <address@hidden>
---

> The issue is well worth documenting in the gnulib manual.

Agreed.  I pushed this.

 ChangeLog                        |    6 ++++++
 doc/posix-functions/realloc.texi |   13 +++++++++++++
 2 files changed, 19 insertions(+), 0 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 3bc9240..58f8195 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2011-03-24  Eric Blake  <address@hidden>
+
+       realloc: document portability problem
+       * doc/posix-functions/realloc.texi (realloc): Mention pitfalls of
+       passing 0 size to realloc.
+
 2011-03-23  Ben Walton  <address@hidden>

        doc: update users.txt
diff --git a/doc/posix-functions/realloc.texi b/doc/posix-functions/realloc.texi
index 2ff4e16..12a9dc7 100644
--- a/doc/posix-functions/realloc.texi
+++ b/doc/posix-functions/realloc.texi
@@ -16,6 +16,19 @@ realloc

 Portability problems not fixed by Gnulib:
 @itemize
address@hidden
+It is not portable to call @code{realloc} with a size of 0.  With a
+NULL pointer argument, this is the same ambiguity as @code{malloc (0)}
+on whether a unique zero-size object is created.  With a non-NULL
+pointer argument, C99 requires that if @code{realloc (p, 0)} returns
address@hidden then @code{p} is still valid.  Among implementations that
+obey C99, behavior varies on whether @code{realloc (p, 0)} always
+fails and leaves @code{p} valid, or usually succeeds and returns a
+unique zero-size object; either way, a program not suspecting these
+semantics will leak memory (either the still-valid @code{p}, or the
+non-NULL return value).  Meanwhile, several implementations violate
+C99, by always calling @code{free (p)} but returning NULL:
+glibc, Cygwin
 @end itemize

 Extension: Gnulib provides a module @samp{realloc-gnu} that substitutes a
-- 
1.7.4