| 1 |
'\" t |
| 2 |
.\" Copyright 1993, Thomas Koenig <[email protected]> |
| 3 |
.\" Copyright 2007-2018, Michael Kerrisk <[email protected]> |
| 4 |
.\" Copyright, the authors of the Linux man-pages project |
| 5 |
.\" |
| 6 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 7 |
.\" |
| 8 |
.\" FIXME . Review http://austingroupbugs.net/view.php?id=374 |
| 9 |
.\" to see what changes are required on this page. |
| 10 |
.\" |
| 11 |
.TH malloc 3 2026-02-08 "Linux man-pages 6.18" |
| 12 |
.SH NAME |
| 13 |
malloc, free, calloc, realloc, reallocarray \- allocate and free dynamic memory |
| 14 |
.SH LIBRARY |
| 15 |
Standard C library |
| 16 |
.RI ( libc ,\~ \-lc ) |
| 17 |
.SH SYNOPSIS |
| 18 |
.nf |
| 19 |
.B #include <stdlib.h> |
| 20 |
.P |
| 21 |
.BI "void *malloc(size_t " size ); |
| 22 |
.BI "void free(void *_Nullable " p ); |
| 23 |
.BI "void *calloc(size_t " n ", size_t " size ); |
| 24 |
.BI "void *realloc(void *_Nullable " p ", size_t " size ); |
| 25 |
.BI "void *reallocarray(void *_Nullable " p ", size_t " n ", size_t " size ); |
| 26 |
.fi |
| 27 |
.P |
| 28 |
.RS -4 |
| 29 |
Feature Test Macro Requirements for glibc (see |
| 30 |
.BR feature_test_macros (7)): |
| 31 |
.RE |
| 32 |
.P |
| 33 |
.BR reallocarray (): |
| 34 |
.nf |
| 35 |
Since glibc 2.29: |
| 36 |
_DEFAULT_SOURCE |
| 37 |
glibc 2.28 and earlier: |
| 38 |
_GNU_SOURCE |
| 39 |
.fi |
| 40 |
.SH DESCRIPTION |
| 41 |
.SS malloc() |
| 42 |
The |
| 43 |
.BR malloc () |
| 44 |
function allocates |
| 45 |
.I size |
| 46 |
bytes and returns a pointer to the allocated memory. |
| 47 |
.IR "The memory is not initialized" . |
| 48 |
If |
| 49 |
.I size |
| 50 |
is 0, then |
| 51 |
.BR malloc () |
| 52 |
returns a unique pointer value that can later be successfully passed to |
| 53 |
.BR free (). |
| 54 |
(See "Nonportable behavior" for portability issues.) |
| 55 |
.SS free() |
| 56 |
The |
| 57 |
.BR free () |
| 58 |
function frees the memory space pointed to by |
| 59 |
.IR p , |
| 60 |
which must have been returned by a previous call to |
| 61 |
.BR malloc () |
| 62 |
or related functions. |
| 63 |
Otherwise, or if |
| 64 |
.I p |
| 65 |
has already been freed, undefined behavior occurs. |
| 66 |
If |
| 67 |
.I p |
| 68 |
is NULL, no operation is performed. |
| 69 |
.SS calloc() |
| 70 |
The |
| 71 |
.BR calloc () |
| 72 |
function allocates memory for an array of |
| 73 |
.I n |
| 74 |
elements of |
| 75 |
.I size |
| 76 |
bytes each and returns a pointer to the allocated memory. |
| 77 |
The memory is set to zero. |
| 78 |
If |
| 79 |
.I n |
| 80 |
or |
| 81 |
.I size |
| 82 |
is 0, then |
| 83 |
.BR calloc () |
| 84 |
returns a unique pointer value that can later be successfully passed to |
| 85 |
.BR free (). |
| 86 |
.P |
| 87 |
If the multiplication of |
| 88 |
.I n |
| 89 |
and |
| 90 |
.I size |
| 91 |
would result in integer overflow, then |
| 92 |
.BR calloc () |
| 93 |
returns an error. |
| 94 |
By contrast, |
| 95 |
an integer overflow would not be detected in the following call to |
| 96 |
.BR malloc (), |
| 97 |
with the result that an incorrectly sized block of memory would be allocated: |
| 98 |
.P |
| 99 |
.in +4n |
| 100 |
.EX |
| 101 |
malloc(n * size); |
| 102 |
.EE |
| 103 |
.in |
| 104 |
.SS realloc() |
| 105 |
The |
| 106 |
.BR realloc () |
| 107 |
function changes the size of the memory block pointed to by |
| 108 |
.I p |
| 109 |
to |
| 110 |
.I size |
| 111 |
bytes. |
| 112 |
The contents of the memory |
| 113 |
will be unchanged in the range from the start of the region |
| 114 |
up to the minimum of the old and new sizes. |
| 115 |
If the new size is larger than the old size, the added memory will |
| 116 |
.I not |
| 117 |
be initialized. |
| 118 |
.P |
| 119 |
If |
| 120 |
.I p |
| 121 |
is NULL, then the call is equivalent to |
| 122 |
.IR malloc(size) , |
| 123 |
for all values of |
| 124 |
.IR size . |
| 125 |
.P |
| 126 |
If |
| 127 |
.I size |
| 128 |
is equal to zero, |
| 129 |
and |
| 130 |
.I p |
| 131 |
is not NULL, then the call is equivalent to |
| 132 |
.I free(p) |
| 133 |
(but see "Nonportable behavior" for portability issues). |
| 134 |
.P |
| 135 |
Unless |
| 136 |
.I p |
| 137 |
is NULL, it must have been returned by an earlier call to |
| 138 |
.B malloc |
| 139 |
or related functions. |
| 140 |
If the area pointed to was moved, a |
| 141 |
.I free(p) |
| 142 |
is done. |
| 143 |
.SS reallocarray() |
| 144 |
The |
| 145 |
.BR reallocarray () |
| 146 |
function changes the size of (and possibly moves) |
| 147 |
the memory block pointed to by |
| 148 |
.I p |
| 149 |
to be large enough for an array of |
| 150 |
.I n |
| 151 |
elements, each of which is |
| 152 |
.I size |
| 153 |
bytes. |
| 154 |
It is equivalent to the call |
| 155 |
.P |
| 156 |
.in +4n |
| 157 |
.EX |
| 158 |
realloc(p, n * size); |
| 159 |
.EE |
| 160 |
.in |
| 161 |
.P |
| 162 |
However, unlike that |
| 163 |
.BR realloc () |
| 164 |
call, |
| 165 |
.BR reallocarray () |
| 166 |
fails safely in the case where the multiplication would overflow. |
| 167 |
If such an overflow occurs, |
| 168 |
.BR reallocarray () |
| 169 |
returns an error. |
| 170 |
.SH RETURN VALUE |
| 171 |
The |
| 172 |
.BR malloc (), |
| 173 |
.BR calloc (), |
| 174 |
.BR realloc (), |
| 175 |
and |
| 176 |
.BR reallocarray () |
| 177 |
functions return a pointer to the allocated memory, |
| 178 |
which is suitably aligned for any type that fits into |
| 179 |
the requested size or less. |
| 180 |
On error, these functions return NULL and set |
| 181 |
.IR errno . |
| 182 |
Attempting to allocate more than |
| 183 |
.B PTRDIFF_MAX |
| 184 |
bytes is considered an error, as an object that large |
| 185 |
could cause later pointer subtraction to overflow. |
| 186 |
.P |
| 187 |
The |
| 188 |
.BR free () |
| 189 |
function returns no value, and preserves |
| 190 |
.IR errno . |
| 191 |
.P |
| 192 |
The |
| 193 |
.BR realloc () |
| 194 |
and |
| 195 |
.BR reallocarray () |
| 196 |
functions return NULL if |
| 197 |
.I p |
| 198 |
is not NULL and the requested size is zero; |
| 199 |
this is not considered an error. |
| 200 |
(See "Nonportable behavior" for portability issues.) |
| 201 |
Otherwise, the returned pointer may be the same as |
| 202 |
.I p |
| 203 |
if the allocation was not moved |
| 204 |
(e.g., there was room to expand the allocation in-place), or different from |
| 205 |
.I p |
| 206 |
if the allocation was moved to a new address. |
| 207 |
If these functions fail, |
| 208 |
the original block is left untouched; |
| 209 |
it is not freed or moved. |
| 210 |
.SH ERRORS |
| 211 |
.BR calloc (), |
| 212 |
.BR malloc (), |
| 213 |
.BR realloc (), |
| 214 |
and |
| 215 |
.BR reallocarray () |
| 216 |
can fail with the following error: |
| 217 |
.TP |
| 218 |
.B ENOMEM |
| 219 |
Out of memory. |
| 220 |
Possibly, the application hit the |
| 221 |
.B RLIMIT_AS |
| 222 |
or |
| 223 |
.B RLIMIT_DATA |
| 224 |
limit described in |
| 225 |
.BR getrlimit (2). |
| 226 |
Another reason could be that |
| 227 |
the number of mappings created by the caller process |
| 228 |
exceeded the limit specified by |
| 229 |
.IR /proc/sys/vm/max_map_count . |
| 230 |
.SH ATTRIBUTES |
| 231 |
For an explanation of the terms used in this section, see |
| 232 |
.BR attributes (7). |
| 233 |
.TS |
| 234 |
allbox; |
| 235 |
lbx lb lb |
| 236 |
l l l. |
| 237 |
Interface Attribute Value |
| 238 |
T{ |
| 239 |
.na |
| 240 |
.nh |
| 241 |
.BR malloc (), |
| 242 |
.BR free (), |
| 243 |
.BR calloc (), |
| 244 |
.BR realloc () |
| 245 |
T} Thread safety MT-Safe |
| 246 |
.TE |
| 247 |
.SH STANDARDS |
| 248 |
.TP |
| 249 |
.BR malloc () |
| 250 |
.TQ |
| 251 |
.BR free () |
| 252 |
.TQ |
| 253 |
.BR calloc () |
| 254 |
.TQ |
| 255 |
.BR realloc () |
| 256 |
C23, POSIX.1-2024. |
| 257 |
.TP |
| 258 |
.BR reallocarray () |
| 259 |
POSIX.1-2024. |
| 260 |
.SS realloc(p, 0) |
| 261 |
The behavior of |
| 262 |
.I realloc(p,\~0) |
| 263 |
in glibc doesn't conform to any of |
| 264 |
C99, |
| 265 |
C11, |
| 266 |
POSIX.1-2001, |
| 267 |
POSIX.1-2004, |
| 268 |
POSIX.1-2008, |
| 269 |
POSIX.1-2013, |
| 270 |
POSIX.1-2017, |
| 271 |
or POSIX.1-2024. |
| 272 |
The C17 specification was changed to make it conforming, |
| 273 |
but that specification made it |
| 274 |
impossible to write code that reliably |
| 275 |
determines if the input pointer is freed after |
| 276 |
.IR realloc(p,\~0) , |
| 277 |
and C23 changed it again to make this undefined behavior, |
| 278 |
acknowledging that the C17 specification was broad enough, |
| 279 |
so that undefined behavior wasn't worse than that. |
| 280 |
.P |
| 281 |
.BR reallocarray () |
| 282 |
suffers the same issues in glibc. |
| 283 |
.P |
| 284 |
musl libc and the BSDs conform to all versions of ISO C and POSIX.1. |
| 285 |
.P |
| 286 |
gnulib provides the |
| 287 |
.I realloc-posix |
| 288 |
module, |
| 289 |
which provides wrappers |
| 290 |
.BR realloc () |
| 291 |
and |
| 292 |
.BR reallocarray () |
| 293 |
that conform to all versions of ISO C and POSIX.1. |
| 294 |
.P |
| 295 |
There's a proposal to standardize the BSD behavior: |
| 296 |
.UR https:\://www.open\-std.org/\:jtc1/\:sc22/\:wg14/\:www/\:docs/\:n3621.txt |
| 297 |
.UE . |
| 298 |
.SH HISTORY |
| 299 |
.TP |
| 300 |
.BR malloc () |
| 301 |
.TQ |
| 302 |
.BR free () |
| 303 |
.TQ |
| 304 |
.BR calloc () |
| 305 |
.TQ |
| 306 |
.BR realloc () |
| 307 |
POSIX.1-2001, C89. |
| 308 |
.TP |
| 309 |
.BR reallocarray () |
| 310 |
glibc 2.26. |
| 311 |
OpenBSD 5.6, FreeBSD 11.0. |
| 312 |
.P |
| 313 |
.BR malloc () |
| 314 |
and related functions rejected sizes greater than |
| 315 |
.B PTRDIFF_MAX |
| 316 |
starting in glibc 2.30. |
| 317 |
.P |
| 318 |
.BR free () |
| 319 |
preserved |
| 320 |
.I errno |
| 321 |
starting in glibc 2.33. |
| 322 |
.SS realloc(p,\~0) |
| 323 |
C89 was ambiguous in its specification of |
| 324 |
.IR realloc(p,\~0) . |
| 325 |
C99 partially fixed this. |
| 326 |
.P |
| 327 |
The original implementation in glibc would have been conforming to C99. |
| 328 |
However, and ironically, |
| 329 |
trying to comply with C99 before the standard was released, |
| 330 |
glibc changed its behavior in glibc 2.1.1 into something that ended up |
| 331 |
not conforming to the final C99 specification |
| 332 |
(but this is debated, |
| 333 |
as the wording of the standard seems self-contradicting). |
| 334 |
.SH NOTES |
| 335 |
By default, Linux follows an optimistic memory allocation strategy. |
| 336 |
This means that when |
| 337 |
.BR malloc () |
| 338 |
returns non-NULL there is no guarantee that the memory really |
| 339 |
is available. |
| 340 |
In case it turns out that the system is out of memory, |
| 341 |
one or more processes will be killed by the OOM killer. |
| 342 |
For more information, see the description of |
| 343 |
.I /proc/sys/vm/overcommit_memory |
| 344 |
and |
| 345 |
.I /proc/sys/vm/oom_adj |
| 346 |
in |
| 347 |
.BR proc (5), |
| 348 |
and the Linux kernel source file |
| 349 |
.IR Documentation/vm/overcommit\-accounting.rst . |
| 350 |
.P |
| 351 |
Normally, |
| 352 |
.BR malloc () |
| 353 |
allocates memory from the heap, and adjusts the size of the heap |
| 354 |
as required, using |
| 355 |
.BR sbrk (2). |
| 356 |
When allocating blocks of memory larger than |
| 357 |
.B MMAP_THRESHOLD |
| 358 |
bytes, the glibc |
| 359 |
.BR malloc () |
| 360 |
implementation allocates the memory as a private anonymous mapping using |
| 361 |
.BR mmap (2). |
| 362 |
.B MMAP_THRESHOLD |
| 363 |
is 128\ kB by default, but is adjustable using |
| 364 |
.BR mallopt (3). |
| 365 |
Prior to Linux 4.7 |
| 366 |
allocations performed using |
| 367 |
.BR mmap (2) |
| 368 |
were unaffected by the |
| 369 |
.B RLIMIT_DATA |
| 370 |
resource limit; |
| 371 |
since Linux 4.7, this limit is also enforced for allocations performed using |
| 372 |
.BR mmap (2). |
| 373 |
.P |
| 374 |
To avoid corruption in multithreaded applications, |
| 375 |
mutexes are used internally to protect the memory-management |
| 376 |
data structures employed by these functions. |
| 377 |
In a multithreaded application in which threads simultaneously |
| 378 |
allocate and free memory, |
| 379 |
there could be contention for these mutexes. |
| 380 |
To scalably handle memory allocation in multithreaded applications, |
| 381 |
glibc creates additional |
| 382 |
.I memory allocation arenas |
| 383 |
if mutex contention is detected. |
| 384 |
Each arena is a large region of memory that is internally allocated |
| 385 |
by the system |
| 386 |
(using |
| 387 |
.BR brk (2) |
| 388 |
or |
| 389 |
.BR mmap (2)), |
| 390 |
and managed with its own mutexes. |
| 391 |
.P |
| 392 |
If your program uses a private memory allocator, |
| 393 |
it should do so by replacing |
| 394 |
.BR malloc (), |
| 395 |
.BR free (), |
| 396 |
.BR calloc (), |
| 397 |
and |
| 398 |
.BR realloc (). |
| 399 |
The replacement functions must implement the documented glibc behaviors, |
| 400 |
including |
| 401 |
.I errno |
| 402 |
handling, size-zero allocations, and overflow checking; |
| 403 |
otherwise, other library routines may crash or operate incorrectly. |
| 404 |
For example, if the replacement |
| 405 |
.IR free () |
| 406 |
does not preserve |
| 407 |
.IR errno , |
| 408 |
then seemingly unrelated library routines may |
| 409 |
fail without having a valid reason in |
| 410 |
.IR errno . |
| 411 |
Private memory allocators may also need to replace other glibc functions; |
| 412 |
see "Replacing malloc" in the glibc manual for details. |
| 413 |
.P |
| 414 |
Crashes in memory allocators |
| 415 |
are almost always related to heap corruption, such as overflowing |
| 416 |
an allocated chunk or freeing the same pointer twice. |
| 417 |
.P |
| 418 |
The |
| 419 |
.BR malloc () |
| 420 |
implementation is tunable via environment variables; |
| 421 |
see |
| 422 |
.BR mallopt (3) |
| 423 |
for details. |
| 424 |
.SS Nonportable behavior |
| 425 |
The behavior of |
| 426 |
these functions when the requested size is zero |
| 427 |
is glibc specific; |
| 428 |
other implementations may return NULL without setting |
| 429 |
.IR errno , |
| 430 |
and portable POSIX programs should tolerate such behavior. |
| 431 |
See |
| 432 |
.BR realloc (3p). |
| 433 |
.P |
| 434 |
POSIX requires memory allocators |
| 435 |
to set |
| 436 |
.I errno |
| 437 |
upon failure. |
| 438 |
However, the C standard does not require this, and applications |
| 439 |
portable to non-POSIX platforms should not assume this. |
| 440 |
.P |
| 441 |
Portable programs should not use private memory allocators, |
| 442 |
as POSIX and the C standard do not allow replacement of |
| 443 |
.BR malloc (), |
| 444 |
.BR free (), |
| 445 |
.BR calloc (), |
| 446 |
and |
| 447 |
.BR realloc (). |
| 448 |
.SH BUGS |
| 449 |
Programmers would naturally expect by induction that |
| 450 |
.I \%realloc(p,\~size) |
| 451 |
is consistent with |
| 452 |
.I free(p) |
| 453 |
and |
| 454 |
.IR malloc(size) , |
| 455 |
as that is the behavior in the general case. |
| 456 |
This is not explicitly required by POSIX.1-2024 or C11, |
| 457 |
but all conforming implementations are consistent with that. |
| 458 |
.P |
| 459 |
The glibc implementation of |
| 460 |
.BR realloc () |
| 461 |
is not consistent with that, |
| 462 |
and as a consequence, |
| 463 |
it is dangerous to call |
| 464 |
.I \%realloc(p,\~0) |
| 465 |
in glibc. |
| 466 |
.P |
| 467 |
A trivial workaround for glibc is calling it as |
| 468 |
.IR \%realloc(p,\~size?size:1) . |
| 469 |
.P |
| 470 |
The workaround for |
| 471 |
.BR reallocarray () |
| 472 |
in glibc |
| 473 |
\[em]which shares the same bug\[em] |
| 474 |
would be |
| 475 |
.IR \%reallocarray(p,\~n?n:1,\~size?size:1) . |
| 476 |
.SH EXAMPLES |
| 477 |
.EX |
| 478 |
#include <err.h> |
| 479 |
#include <stddef.h> |
| 480 |
#include <stdio.h> |
| 481 |
#include <stdlib.h> |
| 482 |
#include <string.h> |
| 483 |
\& |
| 484 |
#define MALLOCARRAY(n, type) ((type *) my_mallocarray(n, sizeof(type))) |
| 485 |
#define MALLOC(type) MALLOCARRAY(1, type) |
| 486 |
\& |
| 487 |
static inline void *my_mallocarray(size_t n, size_t size); |
| 488 |
\& |
| 489 |
int |
| 490 |
main(void) |
| 491 |
{ |
| 492 |
char *p; |
| 493 |
\& |
| 494 |
p = MALLOCARRAY(32, char); |
| 495 |
if (p == NULL) |
| 496 |
err(EXIT_FAILURE, "malloc"); |
| 497 |
\& |
| 498 |
strlcpy(p, "foo", 32); |
| 499 |
puts(p); |
| 500 |
} |
| 501 |
\& |
| 502 |
static inline void * |
| 503 |
my_mallocarray(size_t n, size_t size) |
| 504 |
{ |
| 505 |
return reallocarray(NULL, n, size); |
| 506 |
} |
| 507 |
.EE |
| 508 |
.SH SEE ALSO |
| 509 |
.\" http://g.oswego.edu/dl/html/malloc.html |
| 510 |
.\" A Memory Allocator - by Doug Lea |
| 511 |
.\" |
| 512 |
.\" http://www.bozemanpass.com/info/linux/malloc/Linux_Heap_Contention.html |
| 513 |
.\" Linux Heap, Contention in free() - David Boreham |
| 514 |
.\" |
| 515 |
.\" http://www.citi.umich.edu/projects/linux-scalability/reports/malloc.html |
| 516 |
.\" malloc() Performance in a Multithreaded Linux Environment - |
| 517 |
.\" Check Lever, David Boreham |
| 518 |
.\" |
| 519 |
.ad l |
| 520 |
.nh |
| 521 |
.BR valgrind (1), |
| 522 |
.BR brk (2), |
| 523 |
.BR mmap (2), |
| 524 |
.BR alloca (3), |
| 525 |
.BR malloc_get_state (3), |
| 526 |
.BR malloc_info (3), |
| 527 |
.BR malloc_trim (3), |
| 528 |
.BR malloc_usable_size (3), |
| 529 |
.BR mallopt (3), |
| 530 |
.BR mcheck (3), |
| 531 |
.BR mtrace (3), |
| 532 |
.BR posix_memalign (3) |
| 533 |
.P |
| 534 |
For details of the GNU C library implementation, see |
| 535 |
.UR https:\://sourceware.org/glibc/wiki/MallocInternals |
| 536 |
.UE . |