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/
