malloc.3: Clarify that realloc() may move the memory block

Make it clearer, early in the discussion, that realloc()
may move the block.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man3/malloc.3

@@ -58,6 +58,7 @@ Feature Test Macro Requirements for glibc (see
         _GNU_SOURCE
 .fi
 .SH DESCRIPTION
+.SS malloc()
 The
 .BR malloc ()
 function allocates
@@ -68,27 +69,24 @@ If
 .I size
 is 0, then
 .BR malloc ()
-returns either NULL,
+returns a unique pointer value that can later be successfully passed to
-.\" glibc does this:
-or a unique pointer value that can later be successfully passed to
 .BR free ().
-.PP
+(See "Nonportable behavior" for portability issues.)
+.SS free()
 The
 .BR free ()
 function frees the memory space pointed to by
 .IR ptr ,
 which must have been returned by a previous call to
-.BR malloc (),
+.BR malloc ()
-.BR calloc (),
+or related functions.
-or
-.BR realloc ().
 Otherwise, or if
-.I free(ptr)
+.I ptr
-has already been called before, undefined behavior occurs.
+has already been freed, undefined behavior occurs.
 If
 .I ptr
 is NULL, no operation is performed.
-.PP
+.SS calloc()
 The
 .BR calloc ()
 function allocates memory for an array of
@@ -103,10 +101,9 @@ or
 .I size
 is 0, then
 .BR calloc ()
-returns either NULL,
+returns a unique pointer value that can later be successfully passed to
-.\" glibc does this:
-or a unique pointer value that can later be successfully passed to
 .BR free ().
+.PP
 If the multiplication of
 .I nmemb
 and
@@ -124,7 +121,7 @@ with the result that an incorrectly sized block of memory would be allocated:
 malloc(nmemb * size);
 .EE
 .in
-.PP
+.SS realloc()
 The
 .BR realloc ()
 function changes the size of the memory block pointed to by
@@ -132,39 +129,42 @@ function changes the size of the memory block pointed to by
 to
 .I size
 bytes.
-The contents will be unchanged in the range from the start of the region
+The contents of the memory
+will be unchanged in the range from the start of the region
 up to the minimum of the old and new sizes.
 If the new size is larger than the old size, the added memory will
 .I not
 be initialized.
+.PP
 If
 .I ptr
 is NULL, then the call is equivalent to
 .IR malloc(size) ,
 for all values of
-.IR size ;
+.IR size .
-if
+.PP
+If
 .I size
 is equal to zero,
 and
 .I ptr
 is not NULL, then the call is equivalent to
 .I free(ptr)
-(this behavior is nonportable; see NOTES).
+(but see "Nonportable behavior" for portability issues).
+.PP
 Unless
 .I ptr
 is NULL, it must have been returned by an earlier call to
-.BR malloc (),
+.B malloc
-.BR calloc (),
+or related functions.
-or
-.BR realloc ().
 If the area pointed to was moved, a
 .I free(ptr)
 is done.
-.PP
+.SS reallocarray()
 The
 .BR reallocarray ()
-function changes the size of the memory block pointed to by
+function changes the size of (and possibly moves)
+the memory block pointed to by
 .I ptr
 to be large enough for an array of
 .I nmemb
@@ -174,7 +174,9 @@ bytes.
 It is equivalent to the call
 .PP
 .in +4n
-    realloc(ptr, nmemb * size);
+.EX
+realloc(ptr, nmemb * size);
+.EE
 .in
 .PP
 However, unlike that
@@ -184,60 +186,46 @@ call,
 fails safely in the case where the multiplication would overflow.
 If such an overflow occurs,
 .BR reallocarray ()
-returns NULL, sets
+returns an error.
-.I errno
-to
-.BR ENOMEM ,
-and leaves the original block of memory unchanged.
 .SH RETURN VALUE
 The
-.BR malloc ()
+.BR malloc (),
+.BR calloc (),
+.BR realloc (),
 and
-.BR calloc ()
+.BR reallocarray ()
 functions return a pointer to the allocated memory,
-which is suitably aligned for any built-in type.
+which is suitably aligned for any type that fits into
-On error, these functions return NULL.
+the requested size or less.
-NULL may also be returned by a successful call to
+On error, these functions return NULL and set
-.BR malloc ()
+.IR errno .
-with a
+Attempting to allocate more than
-.I size
+.B PTRDIFF_MAX
-of zero,
+bytes is considered an error, as an object that large
-or by a successful call to
+could cause later pointer subtraction to overflow.
-.BR calloc ()
-with
-.I nmemb
-or
-.I size
-equal to zero.
 .PP
 The
 .BR free ()
-function returns no value.
+function returns no value, and preserves
+.IR errno .
 .PP
 The
 .BR realloc ()
-function returns a pointer to the newly allocated memory, which is suitably
+and
-aligned for any built-in type, or NULL if the request failed.
+.BR reallocarray ()
-The returned pointer may be the same as
+functions return NULL if
+.I ptr
+is not NULL and the requested size is zero;
+this is not considered an error.
+(See "Nonportable behavior" for portability issues.)
+Otherwise, the returned pointer may be the same as
 .IR ptr
 if the allocation was not moved
 (e.g., there was room to expand the allocation in-place), or different from
 .IR ptr
 if the allocation was moved to a new address.
-If
+If these functions fail,
-.I size
+the original block is left untouched; it is not freed or moved.
-was equal to 0, either NULL or a pointer suitable to be passed to
-.BR free ()
-is returned.
-If
-.BR realloc ()
-fails, the original block is left untouched; it is not freed or moved.
-.PP
-On success, the
-.BR reallocarray ()
-function returns a pointer to the newly allocated memory.
-On failure,
-it returns NULL and the original block of memory is left untouched.
 .SH ERRORS
 .BR calloc (),
 .BR malloc (),
@@ -257,6 +245,16 @@ limit described in
 .SH VERSIONS
 .BR reallocarray ()
 first appeared in glibc in version 2.26.
+.PP
+.BR malloc ()
+and related functions rejected sizes greater than
+.B PTRDIFF_MAX
+starting in glibc 2.30.
+.PP
+.BR free ()
+preserved
+.I errno
+starting in glibc 2.33.
 .SH ATTRIBUTES
 For an explanation of the terms used in this section, see
 .BR attributes (7).
@@ -344,30 +342,27 @@ or
 .BR mmap (2)),
 and managed with its own mutexes.
 .PP
-SUSv2 requires
+If your program uses a private memory allocator,
+it should do so by replacing
 .BR malloc (),
+.BR free (),
 .BR calloc (),
 and
-.BR realloc ()
+.BR realloc ().
-to set
+The replacement functions must implement the documented glibc behaviors,
+including
 .I errno
-to
+handling, size-zero allocations, and overflow checking;
-.B ENOMEM
+otherwise, other library routines may crash or operate incorrectly.
-upon failure.
+For example, if the replacement
-Glibc assumes that this is done
+.IR free ()
-(and the glibc versions of these routines do this); if you
+does not preserve errno, then seemingly unrelated library routines may
-use a private malloc implementation that does not set
+fail without having a valid reason in
-.IR errno ,
-then certain library routines may fail without having
-a reason in
 .IR errno .
+Private memory allocators may also need to replace other glibc functions;
+see "Replacing malloc" in the glibc manual for details.
 .PP
-Crashes in
+Crashes in memory allocators
-.BR malloc (),
-.BR calloc (),
-.BR realloc (),
-or
-.BR free ()
 are almost always related to heap corruption, such as overflowing
 an allocated chunk or freeing the same pointer twice.
 .PP
@@ -378,19 +373,28 @@ implementation is tunable via environment variables; see
 for details.
 .SS Nonportable behavior
 The behavior of
-.BR realloc ()
+these functions when the requested size is zero
-when
-.I size
-is equal to zero,
-and
-.I ptr
-is not NULL,
 is glibc specific;
-other implementations may return NULL, and set
+other implementations may return NULL without setting
-.IR errno .
+.IR errno ,
-Portable POSIX programs should avoid it.
+and portable POSIX programs should tolerate such behavior.
 See
 .BR realloc (3p).
+.PP
+POSIX requires memory allocators
+to set
+.I errno
+upon failure.
+However, the C standard does not require this, and applications
+portable to non-POSIX platforms should not assume this.
+.PP
+Portable programs should not use private memory allocators,
+as POSIX and the C standard do not allow replacement of
+.BR malloc (),
+.BR free (),
+.BR calloc (),
+and
+.BR realloc ().
 .SH SEE ALSO
 .\" http://g.oswego.edu/dl/html/malloc.html
 .\" A Memory Allocator - by Doug Lea

man3/malloc_hook.3

@@ -11,7 +11,7 @@
 .SH NAME
 __malloc_hook, __malloc_initialize_hook,
 __memalign_hook, __free_hook, __realloc_hook,
-__after_morecore_hook \- malloc debugging variables
+__after_morecore_hook \- malloc debugging variables (DEPRECATED)
 .SH SYNOPSIS
 .nf
 .B "#include <malloc.h>"
@@ -86,11 +86,18 @@ The use of these hook functions is not safe in multithreaded programs,
 and they are now deprecated.
 From glibc 2.24 onwards, the
 .B __malloc_initialize_hook
-variable has been removed from the API.
+variable has been removed from the API,
+and from glibc 2.34 onwards, all
+the hook variables have been removed from the API.
 .\" https://bugzilla.redhat.com/show_bug.cgi?id=450187
 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=9957
 Programmers should instead preempt calls to the relevant functions
-by defining and exporting functions such as "malloc" and "free".
+by defining and exporting
+.BR malloc (),
+.BR free (),
+.BR realloc (),
+and
+.BR calloc ().
 .SH EXAMPLES
 Here is a short example of how to use these variables.
 .PP