[[patch] 1/2] malloc.3: modernize for glibc 2.34

[[patch] 1/2] malloc.3: modernize for glibc 2.34

[Paul Eggert]

glibc has tightened up its rules for replacing the memory allocator.
I went through the malloc man page and looked for how it documented
malloc and related functions, and fixed discrepancies with glibc malloc
documentation and/or implementation.  I also reorganized the portability
discussion so that portability issues can be seen more clearly.
---
 man3/malloc.3 | 163 ++++++++++++++++++++++++--------------------------
 1 file changed, 79 insertions(+), 84 deletions(-)

diff --git a/man3/malloc.3 b/man3/malloc.3
index 0214233bb..fe88948d1 100644
--- a/man3/malloc.3
+++ b/man3/malloc.3
@@ -68,23 +68,20 @@ If
 .I size
 is 0, then
 .BR malloc ()
-returns either NULL,
-.\" glibc does this:
-or a unique pointer value that can later be successfully passed to
+returns a unique pointer value that can later be successfully passed to
 .BR free ().
+(See "Nonportable behavior" for portability issues.)
 .PP
 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 calloc (),
-or
-.BR realloc ().
+.BR malloc ()
+or related functions.
 Otherwise, or if
-.I free(ptr)
-has already been called before, undefined behavior occurs.
+.I ptr
+has already been freed, undefined behavior occurs.
 If
 .I ptr
 is NULL, no operation is performed.
@@ -103,9 +100,7 @@ or
 .I size
 is 0, then
 .BR calloc ()
-returns either NULL,
-.\" glibc does this:
-or a unique pointer value that can later be successfully passed to
+returns a unique pointer value that can later be successfully passed to
 .BR free ().
 If the multiplication of
 .I nmemb
@@ -150,14 +145,12 @@ 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).
 Unless
 .I ptr
 is NULL, it must have been returned by an earlier call to
-.BR malloc (),
-.BR calloc (),
-or
-.BR realloc ().
+.B malloc
+or related functions.
 If the area pointed to was moved, a
 .I free(ptr)
 is done.
@@ -184,60 +177,46 @@ call,
 fails safely in the case where the multiplication would overflow.
 If such an overflow occurs,
 .BR reallocarray ()
-returns NULL, sets
-.I errno
-to
-.BR ENOMEM ,
-and leaves the original block of memory unchanged.
+returns an error.
 .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.
-On error, these functions return NULL.
-NULL may also be returned by a successful call to
-.BR malloc ()
-with a
-.I size
-of zero,
-or by a successful call to
-.BR calloc ()
-with
-.I nmemb
-or
-.I size
-equal to zero.
+which is suitably aligned for any type that fits into
+the requested size or less.
+On error, these functions return NULL and set
+.IR errno .
+Attempting to allocate more than
+.B PTRDIFF_MAX
+bytes is considered an error, as an object that large
+could cause later pointer subtraction to overflow.
 .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
-aligned for any built-in type, or NULL if the request failed.
-The returned pointer may be the same as
+and
+.BR reallocarray ()
+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
-.I size
-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.
+If these functions fail,
+the original block is left untouched; it is not freed or moved.
 .SH ERRORS
 .BR calloc (),
 .BR malloc (),
@@ -257,6 +236,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 +333,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 ()
-to set
+.BR realloc ().
+The replacement functions must implement the documented glibc behaviors,
+including
 .I errno
-to
-.B ENOMEM
-upon failure.
-Glibc assumes that this is done
-(and the glibc versions of these routines do this); if you
-use a private malloc implementation that does not set
-.IR errno ,
-then certain library routines may fail without having
-a reason in
+handling, size-zero allocations, and overflow checking;
+otherwise, other library routines may crash or operate incorrectly.
+For example, if the replacement
+.IR free ()
+does not preserve errno, then seemingly unrelated library routines may
+fail without having a valid 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
-.BR malloc (),
-.BR calloc (),
-.BR realloc (),
-or
-.BR free ()
+Crashes in memory allocators
 are almost always related to heap corruption, such as overflowing
 an allocated chunk or freeing the same pointer twice.
 .PP
@@ -378,19 +364,28 @@ implementation is tunable via environment variables; see
 for details.
 .SS Nonportable behavior
 The behavior of
-.BR realloc ()
-when
-.I size
-is equal to zero,
-and
-.I ptr
-is not NULL,
+these functions when the requested size is zero
 is glibc specific;
-other implementations may return NULL, and set
-.IR errno .
-Portable POSIX programs should avoid it.
+other implementations may return NULL without setting
+.IR errno ,
+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
-- 
2.31.1

[[patch] 2/2] malloc_hook.3: modernize for glibc 2.34

[Paul Eggert]

---
 man3/malloc_hook.3 | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/man3/malloc_hook.3 b/man3/malloc_hook.3
index 6d944003b..7b76bbc9b 100644
--- a/man3/malloc_hook.3
+++ b/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
-- 
2.31.1

[PATCH] malloc.3: modernize for glibc 2.34 (ping 1)

[Paul Eggert]

Pinging about this patch. The original email is archived here:

https://lore.kernel.org/linux-man/20210810193708.10277-1-eggert@cs.ucla.edu/

On 8/10/21 12:37 PM, Paul Eggert wrote:
> glibc has tightened up its rules for replacing the memory allocator.
> I went through the malloc man page and looked for how it documented
> malloc and related functions, and fixed discrepancies with glibc malloc
> documentation and/or implementation.  I also reorganized the portability
> discussion so that portability issues can be seen more clearly.
> ---
>   man3/malloc.3 | 163 ++++++++++++++++++++++++--------------------------
>   1 file changed, 79 insertions(+), 84 deletions(-)
> 
> diff --git a/man3/malloc.3 b/man3/malloc.3
> index 0214233bb..fe88948d1 100644
> --- a/man3/malloc.3
> +++ b/man3/malloc.3
> @@ -68,23 +68,20 @@ If
>   .I size
>   is 0, then
>   .BR malloc ()
> -returns either NULL,
> -.\" glibc does this:
> -or a unique pointer value that can later be successfully passed to
> +returns a unique pointer value that can later be successfully passed to
>   .BR free ().
> +(See "Nonportable behavior" for portability issues.)
>   .PP
>   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 calloc (),
> -or
> -.BR realloc ().
> +.BR malloc ()
> +or related functions.
>   Otherwise, or if
> -.I free(ptr)
> -has already been called before, undefined behavior occurs.
> +.I ptr
> +has already been freed, undefined behavior occurs.
>   If
>   .I ptr
>   is NULL, no operation is performed.
> @@ -103,9 +100,7 @@ or
>   .I size
>   is 0, then
>   .BR calloc ()
> -returns either NULL,
> -.\" glibc does this:
> -or a unique pointer value that can later be successfully passed to
> +returns a unique pointer value that can later be successfully passed to
>   .BR free ().
>   If the multiplication of
>   .I nmemb
> @@ -150,14 +145,12 @@ 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).
>   Unless
>   .I ptr
>   is NULL, it must have been returned by an earlier call to
> -.BR malloc (),
> -.BR calloc (),
> -or
> -.BR realloc ().
> +.B malloc
> +or related functions.
>   If the area pointed to was moved, a
>   .I free(ptr)
>   is done.
> @@ -184,60 +177,46 @@ call,
>   fails safely in the case where the multiplication would overflow.
>   If such an overflow occurs,
>   .BR reallocarray ()
> -returns NULL, sets
> -.I errno
> -to
> -.BR ENOMEM ,
> -and leaves the original block of memory unchanged.
> +returns an error.
>   .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.
> -On error, these functions return NULL.
> -NULL may also be returned by a successful call to
> -.BR malloc ()
> -with a
> -.I size
> -of zero,
> -or by a successful call to
> -.BR calloc ()
> -with
> -.I nmemb
> -or
> -.I size
> -equal to zero.
> +which is suitably aligned for any type that fits into
> +the requested size or less.
> +On error, these functions return NULL and set
> +.IR errno .
> +Attempting to allocate more than
> +.B PTRDIFF_MAX
> +bytes is considered an error, as an object that large
> +could cause later pointer subtraction to overflow.
>   .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
> -aligned for any built-in type, or NULL if the request failed.
> -The returned pointer may be the same as
> +and
> +.BR reallocarray ()
> +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
> -.I size
> -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.
> +If these functions fail,
> +the original block is left untouched; it is not freed or moved.
>   .SH ERRORS
>   .BR calloc (),
>   .BR malloc (),
> @@ -257,6 +236,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 +333,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 ()
> -to set
> +.BR realloc ().
> +The replacement functions must implement the documented glibc behaviors,
> +including
>   .I errno
> -to
> -.B ENOMEM
> -upon failure.
> -Glibc assumes that this is done
> -(and the glibc versions of these routines do this); if you
> -use a private malloc implementation that does not set
> -.IR errno ,
> -then certain library routines may fail without having
> -a reason in
> +handling, size-zero allocations, and overflow checking;
> +otherwise, other library routines may crash or operate incorrectly.
> +For example, if the replacement
> +.IR free ()
> +does not preserve errno, then seemingly unrelated library routines may
> +fail without having a valid 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
> -.BR malloc (),
> -.BR calloc (),
> -.BR realloc (),
> -or
> -.BR free ()
> +Crashes in memory allocators
>   are almost always related to heap corruption, such as overflowing
>   an allocated chunk or freeing the same pointer twice.
>   .PP
> @@ -378,19 +364,28 @@ implementation is tunable via environment variables; see
>   for details.
>   .SS Nonportable behavior
>   The behavior of
> -.BR realloc ()
> -when
> -.I size
> -is equal to zero,
> -and
> -.I ptr
> -is not NULL,
> +these functions when the requested size is zero
>   is glibc specific;
> -other implementations may return NULL, and set
> -.IR errno .
> -Portable POSIX programs should avoid it.
> +other implementations may return NULL without setting
> +.IR errno ,
> +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
> 

[PATCH] malloc_hook.3: modernize for glibc 2.34

[Paul Eggert]

Pinging about this patch. The original email is archived here:

https://lore.kernel.org/linux-man/20210810193708.10277-2-eggert@cs.ucla.edu


On 8/10/21 12:37 PM, Paul Eggert wrote:
> ---
>   man3/malloc_hook.3 | 13 ++++++++++---
>   1 file changed, 10 insertions(+), 3 deletions(-)
> 
> diff --git a/man3/malloc_hook.3 b/man3/malloc_hook.3
> index 6d944003b..7b76bbc9b 100644
> --- a/man3/malloc_hook.3
> +++ b/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
> 

Re: [PATCH] malloc.3: modernize for glibc 2.34 (ping 1)

[Alejandro Colomar (man-pages)]

Hi Paul,

On 8/28/21 12:02 AM, Paul Eggert wrote:
> Pinging about this patch. The original email is archived here:
> 
> https://lore.kernel.org/linux-man/20210810193708.10277-1-eggert@cs.ucla.edu/ 

Thanks

> 
> 
> On 8/10/21 12:37 PM, Paul Eggert wrote:
>> glibc has tightened up its rules for replacing the memory allocator.
>> I went through the malloc man page and looked for how it documented
>> malloc and related functions, and fixed discrepancies with glibc malloc
>> documentation and/or implementation.  I also reorganized the portability
>> discussion so that portability issues can be seen more clearly.

Could you break this patch into a few of them?

I see some different things here:

- Removing the "malloc(0) may return NULL" text (especially, I'd like 
this one to be separate).
- Rewording some things to simplify
- Reorganizing text

Also, for the removal of malloc(0), is it that glibc removed that 
behavior? or is it that it was never implemented in that way by glibc? 
I think that info should go in the commit message, maybe with a 
reference to gilbc commits (if there are any).


Thank you,

Alex

>> ---
>>   man3/malloc.3 | 163 ++++++++++++++++++++++++--------------------------
>>   1 file changed, 79 insertions(+), 84 deletions(-)
>>
>> diff --git a/man3/malloc.3 b/man3/malloc.3
>> index 0214233bb..fe88948d1 100644
>> --- a/man3/malloc.3
>> +++ b/man3/malloc.3
>> @@ -68,23 +68,20 @@ If
>>   .I size
>>   is 0, then
>>   .BR malloc ()
>> -returns either NULL,
>> -.\" glibc does this:
>> -or a unique pointer value that can later be successfully passed to
>> +returns a unique pointer value that can later be successfully passed to
>>   .BR free ().
>> +(See "Nonportable behavior" for portability issues.)
>>   .PP
>>   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 calloc (),
>> -or
>> -.BR realloc ().
>> +.BR malloc ()
>> +or related functions.
>>   Otherwise, or if
>> -.I free(ptr)
>> -has already been called before, undefined behavior occurs.
>> +.I ptr
>> +has already been freed, undefined behavior occurs.
>>   If
>>   .I ptr
>>   is NULL, no operation is performed.
>> @@ -103,9 +100,7 @@ or
>>   .I size
>>   is 0, then
>>   .BR calloc ()
>> -returns either NULL,
>> -.\" glibc does this:
>> -or a unique pointer value that can later be successfully passed to
>> +returns a unique pointer value that can later be successfully passed to
>>   .BR free ().
>>   If the multiplication of
>>   .I nmemb
>> @@ -150,14 +145,12 @@ 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).
>>   Unless
>>   .I ptr
>>   is NULL, it must have been returned by an earlier call to
>> -.BR malloc (),
>> -.BR calloc (),
>> -or
>> -.BR realloc ().
>> +.B malloc
>> +or related functions.
>>   If the area pointed to was moved, a
>>   .I free(ptr)
>>   is done.
>> @@ -184,60 +177,46 @@ call,
>>   fails safely in the case where the multiplication would overflow.
>>   If such an overflow occurs,
>>   .BR reallocarray ()
>> -returns NULL, sets
>> -.I errno
>> -to
>> -.BR ENOMEM ,
>> -and leaves the original block of memory unchanged.
>> +returns an error.
>>   .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.
>> -On error, these functions return NULL.
>> -NULL may also be returned by a successful call to
>> -.BR malloc ()
>> -with a
>> -.I size
>> -of zero,
>> -or by a successful call to
>> -.BR calloc ()
>> -with
>> -.I nmemb
>> -or
>> -.I size
>> -equal to zero.
>> +which is suitably aligned for any type that fits into
>> +the requested size or less.
>> +On error, these functions return NULL and set
>> +.IR errno .
>> +Attempting to allocate more than
>> +.B PTRDIFF_MAX
>> +bytes is considered an error, as an object that large
>> +could cause later pointer subtraction to overflow.
>>   .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
>> -aligned for any built-in type, or NULL if the request failed.
>> -The returned pointer may be the same as
>> +and
>> +.BR reallocarray ()
>> +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
>> -.I size
>> -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.
>> +If these functions fail,
>> +the original block is left untouched; it is not freed or moved.
>>   .SH ERRORS
>>   .BR calloc (),
>>   .BR malloc (),
>> @@ -257,6 +236,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 +333,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 ()
>> -to set
>> +.BR realloc ().
>> +The replacement functions must implement the documented glibc behaviors,
>> +including
>>   .I errno
>> -to
>> -.B ENOMEM
>> -upon failure.
>> -Glibc assumes that this is done
>> -(and the glibc versions of these routines do this); if you
>> -use a private malloc implementation that does not set
>> -.IR errno ,
>> -then certain library routines may fail without having
>> -a reason in
>> +handling, size-zero allocations, and overflow checking;
>> +otherwise, other library routines may crash or operate incorrectly.
>> +For example, if the replacement
>> +.IR free ()
>> +does not preserve errno, then seemingly unrelated library routines may
>> +fail without having a valid 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
>> -.BR malloc (),
>> -.BR calloc (),
>> -.BR realloc (),
>> -or
>> -.BR free ()
>> +Crashes in memory allocators
>>   are almost always related to heap corruption, such as overflowing
>>   an allocated chunk or freeing the same pointer twice.
>>   .PP
>> @@ -378,19 +364,28 @@ implementation is tunable via environment 
>> variables; see
>>   for details.
>>   .SS Nonportable behavior
>>   The behavior of
>> -.BR realloc ()
>> -when
>> -.I size
>> -is equal to zero,
>> -and
>> -.I ptr
>> -is not NULL,
>> +these functions when the requested size is zero
>>   is glibc specific;
>> -other implementations may return NULL, and set
>> -.IR errno .
>> -Portable POSIX programs should avoid it.
>> +other implementations may return NULL without setting
>> +.IR errno ,
>> +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
>>
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH] malloc_hook.3: modernize for glibc 2.34

[Alejandro Colomar (man-pages)]

Hi Paul,

On 8/28/21 12:04 AM, Paul Eggert wrote:
> Pinging about this patch. The original email is archived here:
> 
> https://lore.kernel.org/linux-man/20210810193708.10277-2-eggert@cs.ucla.edu
> 

Thanks for the pings (and patches).  Please see some comments below.

Cheers,

Alex

> 
> On 8/10/21 12:37 PM, Paul Eggert wrote:
>> ---
>>   man3/malloc_hook.3 | 13 ++++++++++---
>>   1 file changed, 10 insertions(+), 3 deletions(-)
>>
>> diff --git a/man3/malloc_hook.3 b/man3/malloc_hook.3
>> index 6d944003b..7b76bbc9b 100644
>> --- a/man3/malloc_hook.3
>> +++ b/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.

All good until here.  (Maybe the glibc commit that removed this could go 
in the commit message, if you know it.)

>>   .\" 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 ().

Did this change with glibc 2.34?  If not I think this should go to a 
separate "wfix" commit.

>>   .SH EXAMPLES
>>   Here is a short example of how to use these variables.
>>   .PP
>>
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH] malloc.3: modernize for glibc 2.34 (ping 1)

[Paul Eggert]

[-- Attachment #1: Type: text/plain, Size: 971 bytes --]

On 8/27/21 4:07 PM, Alejandro Colomar (man-pages) wrote:
> Could you break this patch into a few of them?

I could if I had more time, but I'd rather not. If you have the time to 
break up the patch please feel free. My suggestion, however, is for us 
to work on the patch together until it passes muster; that should be 
more efficient for both you and me.
> Also, for the removal of malloc(0), is it that glibc removed that behavior?

In glibc, malloc(0) always returns a unique nonnull pointer when it 
succeeds. This behavior conforms to POSIX but is not required by POSIX, 
as POSIX also allows malloc(0) to return NULL when it succeeds.

This has been glibc behavior for decades. The patch merely documents the 
behavior more clearly. (It also documents some other behavior that *has* 
changed recently.)

> I think that info should go in the commit message

OK, revised patch attached. It's the same as before, except for the 
commit message.

[-- Attachment #2: 0001-malloc.3-modernize-for-glibc-2.34.patch --]
[-- Type: text/x-patch, Size: 7848 bytes --]

From be9fc3024c23c8fdb2d8fe96a384a223e3829207 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Fri, 27 Aug 2021 14:56:41 -0700
Subject: [PATCH] malloc.3: modernize for glibc 2.34

glibc has tightened up its rules for replacing the memory allocator.
I went through the malloc man page and looked for how it documented
malloc and related functions, and fixed discrepancies with glibc malloc
documentation and/or implementation.  In particular, I documented
the behavior for size-zero allocations: malloc (0) returns nonnull
on success in glibc (POSIX allows it to return null), realloc (0, N)
behaves like malloc (N), and realloc (P, 0) where P is nonnull
frees P and returns NULL (POSIX and the C standard allow other
behaviors for these cases, and this patch documents that too).
I also reorganized the portability discussion so that portability
issues can be seen more clearly.
---
 man3/malloc.3 | 163 ++++++++++++++++++++++++--------------------------
 1 file changed, 79 insertions(+), 84 deletions(-)

diff --git a/man3/malloc.3 b/man3/malloc.3
index 0214233bb..fe88948d1 100644
--- a/man3/malloc.3
+++ b/man3/malloc.3
@@ -68,23 +68,20 @@ If
 .I size
 is 0, then
 .BR malloc ()
-returns either NULL,
-.\" glibc does this:
-or a unique pointer value that can later be successfully passed to
+returns a unique pointer value that can later be successfully passed to
 .BR free ().
+(See "Nonportable behavior" for portability issues.)
 .PP
 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 calloc (),
-or
-.BR realloc ().
+.BR malloc ()
+or related functions.
 Otherwise, or if
-.I free(ptr)
-has already been called before, undefined behavior occurs.
+.I ptr
+has already been freed, undefined behavior occurs.
 If
 .I ptr
 is NULL, no operation is performed.
@@ -103,9 +100,7 @@ or
 .I size
 is 0, then
 .BR calloc ()
-returns either NULL,
-.\" glibc does this:
-or a unique pointer value that can later be successfully passed to
+returns a unique pointer value that can later be successfully passed to
 .BR free ().
 If the multiplication of
 .I nmemb
@@ -150,14 +145,12 @@ 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).
 Unless
 .I ptr
 is NULL, it must have been returned by an earlier call to
-.BR malloc (),
-.BR calloc (),
-or
-.BR realloc ().
+.B malloc
+or related functions.
 If the area pointed to was moved, a
 .I free(ptr)
 is done.
@@ -184,60 +177,46 @@ call,
 fails safely in the case where the multiplication would overflow.
 If such an overflow occurs,
 .BR reallocarray ()
-returns NULL, sets
-.I errno
-to
-.BR ENOMEM ,
-and leaves the original block of memory unchanged.
+returns an error.
 .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.
-On error, these functions return NULL.
-NULL may also be returned by a successful call to
-.BR malloc ()
-with a
-.I size
-of zero,
-or by a successful call to
-.BR calloc ()
-with
-.I nmemb
-or
-.I size
-equal to zero.
+which is suitably aligned for any type that fits into
+the requested size or less.
+On error, these functions return NULL and set
+.IR errno .
+Attempting to allocate more than
+.B PTRDIFF_MAX
+bytes is considered an error, as an object that large
+could cause later pointer subtraction to overflow.
 .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
-aligned for any built-in type, or NULL if the request failed.
-The returned pointer may be the same as
+and
+.BR reallocarray ()
+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
-.I size
-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.
+If these functions fail,
+the original block is left untouched; it is not freed or moved.
 .SH ERRORS
 .BR calloc (),
 .BR malloc (),
@@ -257,6 +236,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 +333,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 ()
-to set
+.BR realloc ().
+The replacement functions must implement the documented glibc behaviors,
+including
 .I errno
-to
-.B ENOMEM
-upon failure.
-Glibc assumes that this is done
-(and the glibc versions of these routines do this); if you
-use a private malloc implementation that does not set
-.IR errno ,
-then certain library routines may fail without having
-a reason in
+handling, size-zero allocations, and overflow checking;
+otherwise, other library routines may crash or operate incorrectly.
+For example, if the replacement
+.IR free ()
+does not preserve errno, then seemingly unrelated library routines may
+fail without having a valid 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
-.BR malloc (),
-.BR calloc (),
-.BR realloc (),
-or
-.BR free ()
+Crashes in memory allocators
 are almost always related to heap corruption, such as overflowing
 an allocated chunk or freeing the same pointer twice.
 .PP
@@ -378,19 +364,28 @@ implementation is tunable via environment variables; see
 for details.
 .SS Nonportable behavior
 The behavior of
-.BR realloc ()
-when
-.I size
-is equal to zero,
-and
-.I ptr
-is not NULL,
+these functions when the requested size is zero
 is glibc specific;
-other implementations may return NULL, and set
-.IR errno .
-Portable POSIX programs should avoid it.
+other implementations may return NULL without setting
+.IR errno ,
+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
-- 
2.31.1

Re: [PATCH] malloc_hook.3: modernize for glibc 2.34

[Paul Eggert]

On 8/27/21 4:11 PM, Alejandro Colomar (man-pages) wrote:

> All good until here.  (Maybe the glibc commit that removed this could go 
> in the commit message, if you know it.)

I don't know it, unfortunately.

>>>   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 ().
> 
> Did this change with glibc 2.34?

The glibc manual changed (it started documenting this stuff) but this 
part of the implementation did not change.

> If not I think this should go to a separate "wfix" commit.

Please feel free to do that. (I don't know what a "wfix" commit is, and 
don't particularly want to know. :-)

Re: [PATCH] malloc_hook.3: modernize for glibc 2.34

[Florian Weimer]

* Paul Eggert:

> On 8/27/21 4:11 PM, Alejandro Colomar (man-pages) wrote:
>
>> All good until here.  (Maybe the glibc commit that removed this
>> could go in the commit message, if you know it.)
>
> I don't know it, unfortunately.
>
>>>>   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 ().
>> Did this change with glibc 2.34?
>
> The glibc manual changed (it started documenting this stuff) but this
> part of the implementation did not change.

The documentation is somewhat older than 2.34 and was just minimally
amended.  It's here:

  Replacing malloc
  <https://www.gnu.org/software/libc/manual/html_node/Replacing-malloc.html>

In particular, it lists additional functions that may have to be
interposed due to application use.

Thanks,
Florian

Re: [[patch] 1/2] malloc.3: modernize for glibc 2.34

[Michael Kerrisk (man-pages)]

Hello Paul,

On 8/10/21 9:37 PM, Paul Eggert wrote:
> glibc has tightened up its rules for replacing the memory allocator.
> I went through the malloc man page and looked for how it documented
> malloc and related functions, and fixed discrepancies with glibc malloc
> documentation and/or implementation.  I also reorganized the portability
> discussion so that portability issues can be seen more clearly.

Thanks for the patch. I've applied it.

As Alex noted, it might have been nicer if the patch could have
been broken into some smaller pieces. But, appreciate that that
may not have been simple, and I've a fairly high degree of trust
that you took care in making the changes.

Thanks,

Michael

> ---
>  man3/malloc.3 | 163 ++++++++++++++++++++++++--------------------------
>  1 file changed, 79 insertions(+), 84 deletions(-)
> 
> diff --git a/man3/malloc.3 b/man3/malloc.3
> index 0214233bb..fe88948d1 100644
> --- a/man3/malloc.3
> +++ b/man3/malloc.3
> @@ -68,23 +68,20 @@ If
>  .I size
>  is 0, then
>  .BR malloc ()
> -returns either NULL,
> -.\" glibc does this:
> -or a unique pointer value that can later be successfully passed to
> +returns a unique pointer value that can later be successfully passed to
>  .BR free ().
> +(See "Nonportable behavior" for portability issues.)
>  .PP
>  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 calloc (),
> -or
> -.BR realloc ().
> +.BR malloc ()
> +or related functions.
>  Otherwise, or if
> -.I free(ptr)
> -has already been called before, undefined behavior occurs.
> +.I ptr
> +has already been freed, undefined behavior occurs.
>  If
>  .I ptr
>  is NULL, no operation is performed.
> @@ -103,9 +100,7 @@ or
>  .I size
>  is 0, then
>  .BR calloc ()
> -returns either NULL,
> -.\" glibc does this:
> -or a unique pointer value that can later be successfully passed to
> +returns a unique pointer value that can later be successfully passed to
>  .BR free ().
>  If the multiplication of
>  .I nmemb
> @@ -150,14 +145,12 @@ 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).
>  Unless
>  .I ptr
>  is NULL, it must have been returned by an earlier call to
> -.BR malloc (),
> -.BR calloc (),
> -or
> -.BR realloc ().
> +.B malloc
> +or related functions.
>  If the area pointed to was moved, a
>  .I free(ptr)
>  is done.
> @@ -184,60 +177,46 @@ call,
>  fails safely in the case where the multiplication would overflow.
>  If such an overflow occurs,
>  .BR reallocarray ()
> -returns NULL, sets
> -.I errno
> -to
> -.BR ENOMEM ,
> -and leaves the original block of memory unchanged.
> +returns an error.
>  .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.
> -On error, these functions return NULL.
> -NULL may also be returned by a successful call to
> -.BR malloc ()
> -with a
> -.I size
> -of zero,
> -or by a successful call to
> -.BR calloc ()
> -with
> -.I nmemb
> -or
> -.I size
> -equal to zero.
> +which is suitably aligned for any type that fits into
> +the requested size or less.
> +On error, these functions return NULL and set
> +.IR errno .
> +Attempting to allocate more than
> +.B PTRDIFF_MAX
> +bytes is considered an error, as an object that large
> +could cause later pointer subtraction to overflow.
>  .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
> -aligned for any built-in type, or NULL if the request failed.
> -The returned pointer may be the same as
> +and
> +.BR reallocarray ()
> +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
> -.I size
> -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.
> +If these functions fail,
> +the original block is left untouched; it is not freed or moved.
>  .SH ERRORS
>  .BR calloc (),
>  .BR malloc (),
> @@ -257,6 +236,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 +333,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 ()
> -to set
> +.BR realloc ().
> +The replacement functions must implement the documented glibc behaviors,
> +including
>  .I errno
> -to
> -.B ENOMEM
> -upon failure.
> -Glibc assumes that this is done
> -(and the glibc versions of these routines do this); if you
> -use a private malloc implementation that does not set
> -.IR errno ,
> -then certain library routines may fail without having
> -a reason in
> +handling, size-zero allocations, and overflow checking;
> +otherwise, other library routines may crash or operate incorrectly.
> +For example, if the replacement
> +.IR free ()
> +does not preserve errno, then seemingly unrelated library routines may
> +fail without having a valid 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
> -.BR malloc (),
> -.BR calloc (),
> -.BR realloc (),
> -or
> -.BR free ()
> +Crashes in memory allocators
>  are almost always related to heap corruption, such as overflowing
>  an allocated chunk or freeing the same pointer twice.
>  .PP
> @@ -378,19 +364,28 @@ implementation is tunable via environment variables; see
>  for details.
>  .SS Nonportable behavior
>  The behavior of
> -.BR realloc ()
> -when
> -.I size
> -is equal to zero,
> -and
> -.I ptr
> -is not NULL,
> +these functions when the requested size is zero
>  is glibc specific;
> -other implementations may return NULL, and set
> -.IR errno .
> -Portable POSIX programs should avoid it.
> +other implementations may return NULL without setting
> +.IR errno ,
> +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
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [[patch] 2/2] malloc_hook.3: modernize for glibc 2.34

[Michael Kerrisk (man-pages)]

Hello Paul,

On 8/10/21 9:37 PM, Paul Eggert wrote:
> ---
>  man3/malloc_hook.3 | 13 ++++++++++---
>  1 file changed, 10 insertions(+), 3 deletions(-)

Patch applied.

Thanks you!

Cheers,

Michael

> diff --git a/man3/malloc_hook.3 b/man3/malloc_hook.3
> index 6d944003b..7b76bbc9b 100644
> --- a/man3/malloc_hook.3
> +++ b/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
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/