.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
.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)