.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
+.\" and Copyright i2007, 2012, 2018, Michael Kerrisk <mtk.manpages@gmail.com>
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
-.\" License.
+.\" %%%LICENSE_END
+.\"
.\" Modified Sat Jul 24 19:00:59 1993 by Rik Faith (faith@cs.unc.edu)
.\" Clarification concerning realloc, iwj10@cus.cam.ac.uk (Ian Jackson), 950701
.\" Documented MALLOC_CHECK_, Wolfram Gloger (wmglo@dent.med.uni-muenchen.de)
.\" 2007-09-15 mtk: added notes on malloc()'s use of sbrk() and mmap().
.\"
-.TH MALLOC 3 2012-05-10 "GNU" "Linux Programmer's Manual"
+.\" FIXME . Review http://austingroupbugs.net/view.php?id=374
+.\" to see what changes are required on this page.
+.\"
+.TH MALLOC 3 2020-02-09 "GNU" "Linux Programmer's Manual"
.SH NAME
-malloc, free, calloc, realloc \- allocate and free dynamic memory
+malloc, free, calloc, realloc, reallocarray \- allocate and free dynamic memory
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.sp
+.PP
.BI "void *malloc(size_t " "size" );
.BI "void free(void " "*ptr" );
.BI "void *calloc(size_t " "nmemb" ", size_t " "size" );
.BI "void *realloc(void " "*ptr" ", size_t " "size" );
+.BI "void *reallocarray(void " "*ptr" ", size_t " nmemb ", size_t " "size" );
.fi
+.PP
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.PP
+.BR reallocarray ():
+.ad l
+ Since glibc 2.29:
+ _DEFAULT_SOURCE
+ Glibc 2.28 and earlier:
+ _GNU_SOURCE
+.ad
.SH DESCRIPTION
.PP
The
.IR ptr ,
which must have been returned by a previous call to
.BR malloc (),
-.BR calloc ()
+.BR calloc (),
or
.BR realloc ().
Otherwise, or if
.\" glibc does this:
or a unique pointer value that can later be successfully passed to
.BR free ().
+If the multiplication of
+.I nmemb
+and
+.I size
+would result in integer overflow, then
+.BR calloc ()
+returns an error.
+By contrast,
+an integer overflow would not be detected in the following call to
+.BR malloc (),
+with the result that an incorrectly sized block of memory would be allocated:
+.PP
+.in +4n
+.EX
+malloc(nmemb * size);
+.EE
+.in
.PP
The
.BR realloc ()
.I ptr
is NULL, it must have been returned by an earlier call to
.BR malloc (),
-.BR calloc ()
+.BR calloc (),
or
.BR realloc ().
If the area pointed to was moved, a
.I free(ptr)
is done.
+.PP
+The
+.BR reallocarray ()
+function changes the size of the memory block pointed to by
+.I ptr
+to be large enough for an array of
+.I nmemb
+elements, each of which is
+.I size
+bytes.
+It is equivalent to the call
+.PP
+.in +4n
+ realloc(ptr, nmemb * size);
+.in
+.PP
+However, unlike that
+.BR realloc ()
+call,
+.BR reallocarray ()
+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.
.SH RETURN VALUE
The
.BR malloc ()
and
.BR calloc ()
-functions return a pointer to the allocated memory
-that is suitably aligned for any kind of variable.
+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 ()
The
.BR realloc ()
function returns a pointer to the newly allocated memory, which is suitably
-aligned for any kind of variable and may be different from
-.IR ptr ,
-or NULL if the request fails.
+aligned for any built-in type, or NULL if the request failed.
+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
is returned.
If
.BR realloc ()
-fails the original block is left untouched; it is not freed or moved.
+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 (),
+.BR realloc (),
+and
+.BR reallocarray ()
+can fail with the following error:
+.TP
+.B ENOMEM
+Out of memory.
+Possibly, the application hit the
+.BR RLIMIT_AS
+or
+.BR RLIMIT_DATA
+limit described in
+.BR getrlimit (2).
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbw20 lb lb
+l l l.
+Interface Attribute Value
+T{
+.BR malloc (),
+.BR free (),
+.br
+.BR calloc (),
+.BR realloc ()
+T} Thread safety MT-Safe
+.TE
.SH CONFORMING TO
-C89, C99.
+.BR malloc (),
+.BR free (),
+.BR calloc (),
+.BR realloc ():
+POSIX.1-2001, POSIX.1-2008, C89, C99.
+.PP
+.BR reallocarray ()
+is a nonstandard extension that first appeared in OpenBSD 5.6 and FreeBSD 11.0.
.SH NOTES
By default, Linux follows an optimistic memory allocation strategy.
This means that when
in
.BR proc (5),
and the Linux kernel source file
-.IR Documentation/vm/overcommit-accounting .
-
+.IR Documentation/vm/overcommit-accounting.rst .
+.PP
Normally,
.BR malloc ()
allocates memory from the heap, and adjusts the size of the heap
implementation allocates the memory as a private anonymous mapping using
.BR mmap (2).
.B MMAP_THRESHOLD
-is 128 kB by default, but is adjustable using
+is 128\ kB by default, but is adjustable using
.BR mallopt (3).
-Allocations performed using
+Prior to Linux 4.7
+allocations performed using
.BR mmap (2)
-are unaffected by the
+were unaffected by the
.B RLIMIT_DATA
-resource limit (see
-.BR getrlimit (2)).
-
+resource limit;
+since Linux 4.7, this limit is also enforced for allocations performed using
+.BR mmap (2).
+.PP
To avoid corruption in multithreaded applications,
mutexes are used internally to protect the memory-management
data structures employed by these functions.
or
.BR mmap (2)),
and managed with its own mutexes.
-
-The UNIX 98 standard requires
+.PP
+SUSv2 requires
.BR malloc (),
.BR calloc (),
and
then certain library routines may fail without having
a reason in
.IR errno .
-.LP
+.PP
Crashes in
.BR malloc (),
.BR calloc (),
are almost always related to heap corruption, such as overflowing
an allocated chunk or freeing the same pointer twice.
.PP
-Recent versions of Linux libc (later than 5.4.23) and glibc (2.x)
-include a
+The
.BR malloc ()
-implementation which is tunable via environment variables.
-For details, see
-.BR mallopt (3).
+implementation is tunable via environment variables; see
+.BR mallopt (3)
+for details.
.SH SEE ALSO
.\" http://g.oswego.edu/dl/html/malloc.html
.\" A Memory Allocator - by Doug Lea
.\"
.ad l
.nh
+.BR valgrind (1),
.BR brk (2),
.BR mmap (2),
.BR alloca (3),
.BR mcheck (3),
.BR mtrace (3),
.BR posix_memalign (3)
+.PP
+For details of the GNU C library implementation, see
+.UR https://sourceware.org/glibc/wiki/MallocInternals
+.UE .
projects / thirdparty / man-pages.git / blobdiff