1MALLOC(3)                  Linux Programmer's Manual                 MALLOC(3)
2
3
4

NAME

6       malloc, free, calloc, realloc, reallocarray - allocate and free dynamic
7       memory
8

SYNOPSIS

10       #include <stdlib.h>
11
12       void *malloc(size_t size);
13       void free(void *ptr);
14       void *calloc(size_t nmemb, size_t size);
15       void *realloc(void *ptr, size_t size);
16       void *reallocarray(void *ptr, size_t nmemb, size_t size);
17
18   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
19
20       reallocarray():
21           Since glibc 2.29:
22               _DEFAULT_SOURCE
23           Glibc 2.28 and earlier:
24               _GNU_SOURCE
25

DESCRIPTION

27       The malloc() function allocates size bytes and returns a pointer to the
28       allocated  memory.   The memory is not initialized.  If size is 0, then
29       malloc() returns either NULL, or a unique pointer value that can  later
30       be successfully passed to free().
31
32       The  free()  function  frees  the memory space pointed to by ptr, which
33       must have been returned by a previous call to  malloc(),  calloc(),  or
34       realloc().   Otherwise, or if free(ptr) has already been called before,
35       undefined behavior occurs.  If ptr is NULL, no operation is performed.
36
37       The calloc() function allocates memory for an array of  nmemb  elements
38       of  size bytes each and returns a pointer to the allocated memory.  The
39       memory is set to zero.  If nmemb or size is 0,  then  calloc()  returns
40       either  NULL,  or a unique pointer value that can later be successfully
41       passed to free().  If the multiplication of nmemb and size would result
42       in  integer  overflow, then calloc() returns an error.  By contrast, an
43       integer overflow would not be detected in the following  call  to  mal‐
44       loc(),  with the result that an incorrectly sized block of memory would
45       be allocated:
46
47           malloc(nmemb * size);
48
49       The realloc() function changes the size of the memory block pointed  to
50       by ptr to size bytes.  The contents will be unchanged in the range from
51       the start of the region up to the minimum of the old and new sizes.  If
52       the  new size is larger than the old size, the added memory will not be
53       initialized.  If ptr is NULL, then  the  call  is  equivalent  to  mal‐
54       loc(size), for all values of size; if size is equal to zero, and ptr is
55       not NULL, then the call is equivalent to free(ptr)  (this  behavior  is
56       nonportable;  see  NOTES).   Unless  ptr is NULL, it must have been re‐
57       turned by an earlier call to malloc(), calloc(), or realloc().  If  the
58       area pointed to was moved, a free(ptr) is done.
59
60       The  reallocarray()  function  changes  the  size  of  the memory block
61       pointed to by ptr to be large enough for an array  of  nmemb  elements,
62       each of which is size bytes.  It is equivalent to the call
63
64               realloc(ptr, nmemb * size);
65
66       However, unlike that realloc() call, reallocarray() fails safely in the
67       case where the multiplication would overflow.  If such an overflow  oc‐
68       curs, reallocarray() returns NULL, sets errno to ENOMEM, and leaves the
69       original block of memory unchanged.
70

RETURN VALUE

72       The malloc() and calloc() functions return a pointer to  the  allocated
73       memory,  which  is  suitably  aligned for any built-in type.  On error,
74       these functions return NULL.  NULL may also be returned by a successful
75       call  to  malloc() with a size of zero, or by a successful call to cal‐
76       loc() with nmemb or size equal to zero.
77
78       The free() function returns no value.
79
80       The realloc() function returns a pointer to the newly allocated memory,
81       which is suitably aligned for any built-in type, or NULL if the request
82       failed.  The returned pointer may be the same as ptr if the  allocation
83       was not moved (e.g., there was room to expand the allocation in-place),
84       or different from ptr if the allocation was moved to a new address.  If
85       size  was equal to 0, either NULL or a pointer suitable to be passed to
86       free() is returned.  If realloc() fails, the original block is left un‐
87       touched; it is not freed or moved.
88
89       On  success, the reallocarray() function returns a pointer to the newly
90       allocated memory.  On failure, it returns NULL and the  original  block
91       of memory is left untouched.
92

ERRORS

94       calloc(),  malloc(),  realloc(),  and  reallocarray() can fail with the
95       following error:
96
97       ENOMEM Out of memory.  Possibly, the application hit the  RLIMIT_AS  or
98              RLIMIT_DATA limit described in getrlimit(2).
99

VERSIONS

101       reallocarray() first appeared in glibc in version 2.26.
102

ATTRIBUTES

104       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
105       tributes(7).
106
107       ┌────────────────────────────────────────────┬───────────────┬─────────┐
108Interface                                   Attribute     Value   
109       ├────────────────────────────────────────────┼───────────────┼─────────┤
110malloc(), free(), calloc(), realloc()       │ Thread safety │ MT-Safe │
111       └────────────────────────────────────────────┴───────────────┴─────────┘
112

CONFORMING TO

114       malloc(), free(), calloc(), realloc(): POSIX.1-2001, POSIX.1-2008, C89,
115       C99.
116
117       reallocarray()  is a nonstandard extension that first appeared in Open‐
118       BSD 5.6 and FreeBSD 11.0.
119

NOTES

121       By default, Linux follows an  optimistic  memory  allocation  strategy.
122       This  means  that  when malloc() returns non-NULL there is no guarantee
123       that the memory really is available.  In case it  turns  out  that  the
124       system  is  out  of memory, one or more processes will be killed by the
125       OOM  killer.   For   more   information,   see   the   description   of
126       /proc/sys/vm/overcommit_memory and /proc/sys/vm/oom_adj in proc(5), and
127       the  Linux  kernel  source  file   Documentation/vm/overcommit-account‐
128       ing.rst.
129
130       Normally, malloc() allocates memory from the heap, and adjusts the size
131       of the heap as required, using sbrk(2).  When allocating blocks of mem‐
132       ory larger than MMAP_THRESHOLD bytes, the glibc malloc() implementation
133       allocates the memory as a  private  anonymous  mapping  using  mmap(2).
134       MMAP_THRESHOLD  is  128 kB  by  default,  but  is adjustable using mal‐
135       lopt(3).  Prior to Linux 4.7 allocations performed using  mmap(2)  were
136       unaffected  by  the  RLIMIT_DATA  resource limit; since Linux 4.7, this
137       limit is also enforced for allocations performed using mmap(2).
138
139       To avoid corruption in multithreaded applications, mutexes are used in‐
140       ternally  to  protect the memory-management data structures employed by
141       these functions.  In a multithreaded application in which  threads  si‐
142       multaneously  allocate  and  free memory, there could be contention for
143       these mutexes.  To scalably handle memory allocation  in  multithreaded
144       applications,  glibc creates additional memory allocation arenas if mu‐
145       tex contention is detected.  Each arena is a  large  region  of  memory
146       that  is  internally allocated by the system (using brk(2) or mmap(2)),
147       and managed with its own mutexes.
148
149       SUSv2 requires malloc(), calloc(), and realloc() to set errno to ENOMEM
150       upon  failure.  Glibc assumes that this is done (and the glibc versions
151       of these routines do this); if you use a private malloc  implementation
152       that does not set errno, then certain library routines may fail without
153       having a reason in errno.
154
155       Crashes in malloc(), calloc(), realloc(), or free() are  almost  always
156       related  to  heap corruption, such as overflowing an allocated chunk or
157       freeing the same pointer twice.
158
159       The malloc() implementation is tunable via environment  variables;  see
160       mallopt(3) for details.
161
162   Nonportable behavior
163       The  behavior  of  realloc() when size is equal to zero, and ptr is not
164       NULL, is glibc specific; other implementations may return NULL, and set
165       errno.  Portable POSIX programs should avoid it.  See realloc(3p).
166

SEE ALSO

168       valgrind(1), brk(2), mmap(2), alloca(3), malloc_get_state(3),
169       malloc_info(3), malloc_trim(3), malloc_usable_size(3), mallopt(3),
170       mcheck(3), mtrace(3), posix_memalign(3)
171
172       For details of the GNU C library implementation, see
173https://sourceware.org/glibc/wiki/MallocInternals⟩.
174

COLOPHON

176       This page is part of release 5.12 of the Linux man-pages project.  A
177       description of the project, information about reporting bugs, and the
178       latest version of this page, can be found at
179       https://www.kernel.org/doc/man-pages/.
180
181
182
183GNU                               2021-03-22                         MALLOC(3)
Impressum