1MALLOC(3) Linux Programmer's Manual MALLOC(3)
2
6 malloc, free, calloc, realloc, reallocarray - allocate and free dynamic
7 memory
8
10 #include <stdlib.h>
11 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 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
19 reallocarray():
21 Since glibc 2.29:
22 _DEFAULT_SOURCE
23 Glibc 2.28 and earlier:
24 _GNU_SOURCE
25
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 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 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 malloc(nmemb * size);
48 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 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 realloc(ptr, nmemb * size);
65 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
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 The free() function returns no value.
79 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 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
94 calloc(), malloc(), realloc(), and reallocarray() can fail with the
95 following error:
96 ENOMEM Out of memory. Possibly, the application hit the RLIMIT_AS or
98 RLIMIT_DATA limit described in getrlimit(2).
99
101 reallocarray() first appeared in glibc in version 2.26.
102
104 For an explanation of the terms used in this section, see at‐
105 tributes(7).
106 ┌────────────────────────────────────────────┬───────────────┬─────────┐
108 │Interface │ Attribute │ Value │
109 ├────────────────────────────────────────────┼───────────────┼─────────┤
110 │malloc(), free(), calloc(), realloc() │ Thread safety │ MT-Safe │
111 └────────────────────────────────────────────┴───────────────┴─────────┘
112
114 malloc(), free(), calloc(), realloc(): POSIX.1-2001, POSIX.1-2008, C89,
115 C99.
116 reallocarray() is a nonstandard extension that first appeared in Open‐
118 BSD 5.6 and FreeBSD 11.0.
119
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 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 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 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 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 The malloc() implementation is tunable via environment variables; see
160 mallopt(3) for details.
161 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
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 For details of the GNU C library implementation, see
173 ⟨https://sourceware.org/glibc/wiki/MallocInternals⟩.
174
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/.
180GNU 2021-03-22 MALLOC(3)