]> Savannah Git Hosting - gnulib.git/commitdiff
realloc: Improve documentation.
authorBruno Haible <bruno@clisp.org>
Sat, 19 Oct 2024 12:23:39 +0000 (14:23 +0200)
committerBruno Haible <bruno@clisp.org>
Sat, 19 Oct 2024 12:23:39 +0000 (14:23 +0200)
* doc/posix-functions/realloc.texi: Regarding realloc(p,0), document
what the platforms actually do, not merely theoretical possibilities.

ChangeLog
doc/posix-functions/realloc.texi

index 948846f62df51252144a8deff4356104b5220319..1c58b474c3fc6471ffab407b151cb0ea971d3743 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+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.
+
 2024-10-17  Collin Funk  <collin.funk1@gmail.com>
 
        Use a warranty disclaimer in all-permissive license notices, part 2.
index bd130195c2cac2c9a15b4f2e2aec283e72ba64f4..9eec174fa12bb58f96dbd487b69f080b04a77ea8 100644 (file)
@@ -26,12 +26,30 @@ 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 @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
+(on musl libc, macOS, FreeBSD, NetBSD, OpenBSD, Solaris, Cygwin).
+@item
+always fails and leaves @code{p} valid (no known system does this), or
+@item
+usually succeeds and returns a unique zero-size object
+(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.