From c788fd5bcf2e63734aca8973c964b089efba91c6 Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Sat, 19 Oct 2024 14:23:39 +0200 Subject: [PATCH] realloc: Improve documentation. * doc/posix-functions/realloc.texi: Regarding realloc(p,0), document what the platforms actually do, not merely theoretical possibilities. --- ChangeLog | 6 ++++++ doc/posix-functions/realloc.texi | 30 ++++++++++++++++++++++++------ 2 files changed, 30 insertions(+), 6 deletions(-) diff --git a/ChangeLog b/ChangeLog index 948846f62d..1c58b474c3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2024-10-19 Bruno Haible + + 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 Use a warranty disclaimer in all-permissive license notices, part 2. diff --git a/doc/posix-functions/realloc.texi b/doc/posix-functions/realloc.texi index bd130195c2..9eec174fa1 100644 --- a/doc/posix-functions/realloc.texi +++ b/doc/posix-functions/realloc.texi @@ -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. -- 2.39.5