mirror of https://github.com/mkerrisk/man-pages
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. I also reorganized the portability discussion so that portability issues can be seen more clearly. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
77a4c23215
commit
cfc381be29
163
man3/malloc.3
163
man3/malloc.3
|
@ -68,23 +68,20 @@ If
|
||||||
.I size
|
.I size
|
||||||
is 0, then
|
is 0, then
|
||||||
.BR malloc ()
|
.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 ().
|
.BR free ().
|
||||||
|
(See "Nonportable behavior" for portability issues.)
|
||||||
.PP
|
.PP
|
||||||
The
|
The
|
||||||
.BR free ()
|
.BR free ()
|
||||||
function frees the memory space pointed to by
|
function frees the memory space pointed to by
|
||||||
.IR ptr ,
|
.IR ptr ,
|
||||||
which must have been returned by a previous call to
|
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
|
Otherwise, or if
|
||||||
.I free(ptr)
|
.I ptr
|
||||||
has already been called before, undefined behavior occurs.
|
has already been freed, undefined behavior occurs.
|
||||||
If
|
If
|
||||||
.I ptr
|
.I ptr
|
||||||
is NULL, no operation is performed.
|
is NULL, no operation is performed.
|
||||||
|
@ -103,9 +100,7 @@ or
|
||||||
.I size
|
.I size
|
||||||
is 0, then
|
is 0, then
|
||||||
.BR calloc ()
|
.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 ().
|
.BR free ().
|
||||||
If the multiplication of
|
If the multiplication of
|
||||||
.I nmemb
|
.I nmemb
|
||||||
|
@ -150,14 +145,12 @@ and
|
||||||
.I ptr
|
.I ptr
|
||||||
is not NULL, then the call is equivalent to
|
is not NULL, then the call is equivalent to
|
||||||
.I free(ptr)
|
.I free(ptr)
|
||||||
(this behavior is nonportable; see NOTES).
|
(but see "Nonportable behavior" for portability issues).
|
||||||
Unless
|
Unless
|
||||||
.I ptr
|
.I ptr
|
||||||
is NULL, it must have been returned by an earlier call to
|
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
|
If the area pointed to was moved, a
|
||||||
.I free(ptr)
|
.I free(ptr)
|
||||||
is done.
|
is done.
|
||||||
|
@ -184,60 +177,46 @@ call,
|
||||||
fails safely in the case where the multiplication would overflow.
|
fails safely in the case where the multiplication would overflow.
|
||||||
If such an overflow occurs,
|
If such an overflow occurs,
|
||||||
.BR reallocarray ()
|
.BR reallocarray ()
|
||||||
returns NULL, sets
|
returns an error.
|
||||||
.I errno
|
|
||||||
to
|
|
||||||
.BR ENOMEM ,
|
|
||||||
and leaves the original block of memory unchanged.
|
|
||||||
.SH RETURN VALUE
|
.SH RETURN VALUE
|
||||||
The
|
The
|
||||||
.BR malloc ()
|
.BR malloc (),
|
||||||
|
.BR calloc (),
|
||||||
|
.BR realloc (),
|
||||||
and
|
and
|
||||||
.BR calloc ()
|
.BR reallocarray ()
|
||||||
functions return a pointer to the allocated memory,
|
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
|
.PP
|
||||||
The
|
The
|
||||||
.BR free ()
|
.BR free ()
|
||||||
function returns no value.
|
function returns no value, and preserves
|
||||||
|
.IR errno .
|
||||||
.PP
|
.PP
|
||||||
The
|
The
|
||||||
.BR realloc ()
|
.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
|
.IR ptr
|
||||||
if the allocation was not moved
|
if the allocation was not moved
|
||||||
(e.g., there was room to expand the allocation in-place), or different from
|
(e.g., there was room to expand the allocation in-place), or different from
|
||||||
.IR ptr
|
.IR ptr
|
||||||
if the allocation was moved to a new address.
|
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
|
.SH ERRORS
|
||||||
.BR calloc (),
|
.BR calloc (),
|
||||||
.BR malloc (),
|
.BR malloc (),
|
||||||
|
@ -257,6 +236,16 @@ limit described in
|
||||||
.SH VERSIONS
|
.SH VERSIONS
|
||||||
.BR reallocarray ()
|
.BR reallocarray ()
|
||||||
first appeared in glibc in version 2.26.
|
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
|
.SH ATTRIBUTES
|
||||||
For an explanation of the terms used in this section, see
|
For an explanation of the terms used in this section, see
|
||||||
.BR attributes (7).
|
.BR attributes (7).
|
||||||
|
@ -344,30 +333,27 @@ or
|
||||||
.BR mmap (2)),
|
.BR mmap (2)),
|
||||||
and managed with its own mutexes.
|
and managed with its own mutexes.
|
||||||
.PP
|
.PP
|
||||||
SUSv2 requires
|
If your program uses a private memory allocator,
|
||||||
|
it should do so by replacing
|
||||||
.BR malloc (),
|
.BR malloc (),
|
||||||
|
.BR free (),
|
||||||
.BR calloc (),
|
.BR calloc (),
|
||||||
and
|
and
|
||||||
.BR realloc ()
|
.BR realloc ().
|
||||||
to set
|
The replacement functions must implement the documented glibc behaviors,
|
||||||
|
including
|
||||||
.I errno
|
.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 .
|
.IR errno .
|
||||||
|
Private memory allocators may also need to replace other glibc functions;
|
||||||
|
see "Replacing malloc" in the glibc manual for details.
|
||||||
.PP
|
.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
|
are almost always related to heap corruption, such as overflowing
|
||||||
an allocated chunk or freeing the same pointer twice.
|
an allocated chunk or freeing the same pointer twice.
|
||||||
.PP
|
.PP
|
||||||
|
@ -378,19 +364,28 @@ implementation is tunable via environment variables; see
|
||||||
for details.
|
for details.
|
||||||
.SS Nonportable behavior
|
.SS Nonportable behavior
|
||||||
The behavior of
|
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;
|
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
|
See
|
||||||
.BR realloc (3p).
|
.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
|
.SH SEE ALSO
|
||||||
.\" http://g.oswego.edu/dl/html/malloc.html
|
.\" http://g.oswego.edu/dl/html/malloc.html
|
||||||
.\" A Memory Allocator - by Doug Lea
|
.\" A Memory Allocator - by Doug Lea
|
||||||
|
|
Loading…
Reference in New Issue