[PATCH] malloc_usable_size.3: The returned value should not be trusted

[Alejandro Colomar <alx.manpages@gmail.com>]

It might very well return a value larger than the actual usable size, so
writing to the excess bytes is Undefined Behavior.  There's absolutely
no promise about the value, except that it is no less than the size
that was once passed to malloc(3).

Link: <https://github.com/systemd/systemd/issues/22801#issuecomment-1343041481>
Link: <https://inbox.sourceware.org/libc-alpha/20221124213258.305192-1-siddhesh@gotplt.org/T/>
Reported-by: Mingye Wang <arthur200126@gmail.com>
Reported-by: Siddhesh Poyarekar <siddhesh@gotplt.org>
Cc: DJ Delorie <dj@redhat.com>
Cc: Sam James <sam@gentoo.org>
Cc: Florian Weimer <fweimer@redhat.com>
Cc: Andreas Schwab <schwab@linux-m68k.org>
Cc: Zack Weinberg <zack@owlfolio.org>
Cc: Wilco Dijkstra <Wilco.Dijkstra@arm.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man3/malloc_usable_size.3 | 33 +++++++++++++++------------------
 1 file changed, 15 insertions(+), 18 deletions(-)

diff --git a/man3/malloc_usable_size.3 b/man3/malloc_usable_size.3
index 754b255de..f96f1abb5 100644
--- a/man3/malloc_usable_size.3
+++ b/man3/malloc_usable_size.3
@@ -13,20 +13,17 @@ .SH SYNOPSIS
 .nf
 .B #include <malloc.h>
 .PP
-.BI "size_t malloc_usable_size(void *" ptr );
+.BI "size_t malloc_usable_size(void *_Nullable " ptr );
 .fi
 .SH DESCRIPTION
-The
-.BR malloc_usable_size ()
-function returns the number of usable bytes in the block pointed to by
-.IR ptr ,
-a pointer to a block of memory allocated by
+This function can be used for
+diagnostics or statistics about allocations from
 .BR malloc (3)
 or a related function.
 .SH RETURN VALUE
 .BR malloc_usable_size ()
-returns the number of usable bytes in
-the block of allocated memory pointed to by
+returns a value no less than
+the size of the block of allocated memory pointed to by
 .IR ptr .
 If
 .I ptr
@@ -50,17 +47,17 @@ .SH ATTRIBUTES
 .sp 1
 .SH STANDARDS
 GNU.
-.SH NOTES
+.SH CAVEATS
 The value returned by
 .BR malloc_usable_size ()
-may be greater than the requested size of the allocation because
-of alignment and minimum size constraints.
-Although the excess bytes can be overwritten by the application
-without ill effects,
-this is not good programming practice:
-the number of excess bytes in an allocation depends on
-the underlying implementation.
-.PP
-The main use of this function is for debugging and introspection.
+may be greater than the requested size of the allocation
+because of various internal implementation details,
+none of which the programmer should rely on.
+This function is intended to only be used
+for diagnostics and statistics;
+writing to the excess memory without first calling
+.BR realloc (3)
+to resize the allocation is not supported.
+The returned value is only valid at the time of the call.
 .SH SEE ALSO
 .BR malloc (3)
-- 
2.40.0