man3/malloc.3

   1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\" and Copyright i2007, 2012, 2018, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Modified Sat Jul 24 19:00:59 1993 by Rik Faith (faith@cs.unc.edu)
   7 .\" Clarification concerning realloc, iwj10@cus.cam.ac.uk (Ian Jackson), 950701
   8 .\" Documented MALLOC_CHECK_, Wolfram Gloger (wmglo@dent.med.uni-muenchen.de)
   9 .\" 2007-09-15 mtk: added notes on malloc()'s use of sbrk() and mmap().
  10 .\"
  11 .\" FIXME . Review http://austingroupbugs.net/view.php?id=374
  12 .\" to see what changes are required on this page.
  13 .\"
  14 .TH MALLOC 3  2021-03-22 "GNU" "Linux Programmer's Manual"
  15 .SH NAME
  16 malloc, free, calloc, realloc, reallocarray \- allocate and free dynamic memory
  17 .SH LIBRARY
  18 Standard C library
  19 .RI ( libc ", " \-lc )
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <stdlib.h>
  23 .PP
  24 .BI "void *malloc(size_t " "size" );
  25 .BI "void free(void " "*ptr" );
  26 .BI "void *calloc(size_t " "nmemb" ", size_t " "size" );
  27 .BI "void *realloc(void " "*ptr" ", size_t "  "size" );
  28 .BI "void *reallocarray(void " "*ptr" ", size_t " nmemb ", size_t "  "size" );
  29 .fi
  30 .PP
  31 .RS -4
  32 Feature Test Macro Requirements for glibc (see
  33 .BR feature_test_macros (7)):
  34 .RE
  35 .PP
  36 .BR reallocarray ():
  37 .nf
  38     Since glibc 2.29:
  39         _DEFAULT_SOURCE
  40     Glibc 2.28 and earlier:
  41         _GNU_SOURCE
  42 .fi
  43 .SH DESCRIPTION
  44 .SS malloc()
  45 The
  46 .BR malloc ()
  47 function allocates
  48 .I size
  49 bytes and returns a pointer to the allocated memory.
  50 .IR "The memory is not initialized" .
  51 If
  52 .I size
  53 is 0, then
  54 .BR malloc ()
  55 returns a unique pointer value that can later be successfully passed to
  56 .BR free ().
  57 (See "Nonportable behavior" for portability issues.)
  58 .SS free()
  59 The
  60 .BR free ()
  61 function frees the memory space pointed to by
  62 .IR ptr ,
  63 which must have been returned by a previous call to
  64 .BR malloc ()
  65 or related functions.
  66 Otherwise, or if
  67 .I ptr
  68 has already been freed, undefined behavior occurs.
  69 If
  70 .I ptr
  71 is NULL, no operation is performed.
  72 .SS calloc()
  73 The
  74 .BR calloc ()
  75 function allocates memory for an array of
  76 .I nmemb
  77 elements of
  78 .I size
  79 bytes each and returns a pointer to the allocated memory.
  80 The memory is set to zero.
  81 If
  82 .I nmemb
  83 or
  84 .I size
  85 is 0, then
  86 .BR calloc ()
  87 returns a unique pointer value that can later be successfully passed to
  88 .BR free ().
  89 .PP
  90 If the multiplication of
  91 .I nmemb
  92 and
  93 .I size
  94 would result in integer overflow, then
  95 .BR calloc ()
  96 returns an error.
  97 By contrast,
  98 an integer overflow would not be detected in the following call to
  99 .BR malloc (),
 100 with the result that an incorrectly sized block of memory would be allocated:
 101 .PP
 102 .in +4n
 103 .EX
 104 malloc(nmemb * size);
 105 .EE
 106 .in
 107 .SS realloc()
 108 The
 109 .BR realloc ()
 110 function changes the size of the memory block pointed to by
 111 .I ptr
 112 to
 113 .I size
 114 bytes.
 115 The contents of the memory
 116 will be unchanged in the range from the start of the region
 117 up to the minimum of the old and new sizes.
 118 If the new size is larger than the old size, the added memory will
 119 .I not
 120 be initialized.
 121 .PP
 122 If
 123 .I ptr
 124 is NULL, then the call is equivalent to
 125 .IR malloc(size) ,
 126 for all values of
 127 .IR size .
 128 .PP
 129 If
 130 .I size
 131 is equal to zero,
 132 and
 133 .I ptr
 134 is not NULL, then the call is equivalent to
 135 .I free(ptr)
 136 (but see "Nonportable behavior" for portability issues).
 137 .PP
 138 Unless
 139 .I ptr
 140 is NULL, it must have been returned by an earlier call to
 141 .B malloc
 142 or related functions.
 143 If the area pointed to was moved, a
 144 .I free(ptr)
 145 is done.
 146 .SS reallocarray()
 147 The
 148 .BR reallocarray ()
 149 function changes the size of (and possibly moves)
 150 the memory block pointed to by
 151 .I ptr
 152 to be large enough for an array of
 153 .I nmemb
 154 elements, each of which is
 155 .I size
 156 bytes.
 157 It is equivalent to the call
 158 .PP
 159 .in +4n
 160 .EX
 161 realloc(ptr, nmemb * size);
 162 .EE
 163 .in
 164 .PP
 165 However, unlike that
 166 .BR realloc ()
 167 call,
 168 .BR reallocarray ()
 169 fails safely in the case where the multiplication would overflow.
 170 If such an overflow occurs,
 171 .BR reallocarray ()
 172 returns an error.
 173 .SH RETURN VALUE
 174 The
 175 .BR malloc (),
 176 .BR calloc (),
 177 .BR realloc (),
 178 and
 179 .BR reallocarray ()
 180 functions return a pointer to the allocated memory,
 181 which is suitably aligned for any type that fits into
 182 the requested size or less.
 183 On error, these functions return NULL and set
 184 .IR errno .
 185 Attempting to allocate more than
 186 .B PTRDIFF_MAX
 187 bytes is considered an error, as an object that large
 188 could cause later pointer subtraction to overflow.
 189 .PP
 190 The
 191 .BR free ()
 192 function returns no value, and preserves
 193 .IR errno .
 194 .PP
 195 The
 196 .BR realloc ()
 197 and
 198 .BR reallocarray ()
 199 functions return NULL if
 200 .I ptr
 201 is not NULL and the requested size is zero;
 202 this is not considered an error.
 203 (See "Nonportable behavior" for portability issues.)
 204 Otherwise, the returned pointer may be the same as
 205 .I ptr
 206 if the allocation was not moved
 207 (e.g., there was room to expand the allocation in-place), or different from
 208 .I ptr
 209 if the allocation was moved to a new address.
 210 If these functions fail,
 211 the original block is left untouched; it is not freed or moved.
 212 .SH ERRORS
 213 .BR calloc (),
 214 .BR malloc (),
 215 .BR realloc (),
 216 and
 217 .BR reallocarray ()
 218 can fail with the following error:
 219 .TP
 220 .B ENOMEM
 221 Out of memory.
 222 Possibly, the application hit the
 223 .B RLIMIT_AS
 224 or
 225 .B RLIMIT_DATA
 226 limit described in
 227 .BR getrlimit (2).
 228 .SH VERSIONS
 229 .BR reallocarray ()
 230 first appeared in glibc in version 2.26.
 231 .PP
 232 .BR malloc ()
 233 and related functions rejected sizes greater than
 234 .B PTRDIFF_MAX
 235 starting in glibc 2.30.
 236 .PP
 237 .BR free ()
 238 preserved
 239 .I errno
 240 starting in glibc 2.33.
 241 .SH ATTRIBUTES
 242 For an explanation of the terms used in this section, see
 243 .BR attributes (7).
 244 .ad l
 245 .nh
 246 .TS
 247 allbox;
 248 lbx lb lb
 249 l l l.
 250 Interface       Attribute       Value
 251 T{
 252 .BR malloc (),
 253 .BR free (),
 254 .BR calloc (),
 255 .BR realloc ()
 256 T}      Thread safety   MT-Safe
 257 .TE
 258 .hy
 259 .ad
 260 .sp 1
 261 .SH CONFORMING TO
 262 .BR malloc (),
 263 .BR free (),
 264 .BR calloc (),
 265 .BR realloc ():
 266 POSIX.1-2001, POSIX.1-2008, C89, C99.
 267 .PP
 268 .BR reallocarray ()
 269 is a nonstandard extension that first appeared in OpenBSD 5.6 and FreeBSD 11.0.
 270 .SH NOTES
 271 By default, Linux follows an optimistic memory allocation strategy.
 272 This means that when
 273 .BR malloc ()
 274 returns non-NULL there is no guarantee that the memory really
 275 is available.
 276 In case it turns out that the system is out of memory,
 277 one or more processes will be killed by the OOM killer.
 278 For more information, see the description of
 279 .I /proc/sys/vm/overcommit_memory
 280 and
 281 .I /proc/sys/vm/oom_adj
 282 in
 283 .BR proc (5),
 284 and the Linux kernel source file
 285 .IR Documentation/vm/overcommit\-accounting.rst .
 286 .PP
 287 Normally,
 288 .BR malloc ()
 289 allocates memory from the heap, and adjusts the size of the heap
 290 as required, using
 291 .BR sbrk (2).
 292 When allocating blocks of memory larger than
 293 .B MMAP_THRESHOLD
 294 bytes, the glibc
 295 .BR malloc ()
 296 implementation allocates the memory as a private anonymous mapping using
 297 .BR mmap (2).
 298 .B MMAP_THRESHOLD
 299 is 128\ kB by default, but is adjustable using
 300 .BR mallopt (3).
 301 Prior to Linux 4.7
 302 allocations performed using
 303 .BR mmap (2)
 304 were unaffected by the
 305 .B RLIMIT_DATA
 306 resource limit;
 307 since Linux 4.7, this limit is also enforced for allocations performed using
 308 .BR mmap (2).
 309 .PP
 310 To avoid corruption in multithreaded applications,
 311 mutexes are used internally to protect the memory-management
 312 data structures employed by these functions.
 313 In a multithreaded application in which threads simultaneously
 314 allocate and free memory,
 315 there could be contention for these mutexes.
 316 To scalably handle memory allocation in multithreaded applications,
 317 glibc creates additional
 318 .I memory allocation arenas
 319 if mutex contention is detected.
 320 Each arena is a large region of memory that is internally allocated
 321 by the system
 322 (using
 323 .BR brk (2)
 324 or
 325 .BR mmap (2)),
 326 and managed with its own mutexes.
 327 .PP
 328 If your program uses a private memory allocator,
 329 it should do so by replacing
 330 .BR malloc (),
 331 .BR free (),
 332 .BR calloc (),
 333 and
 334 .BR realloc ().
 335 The replacement functions must implement the documented glibc behaviors,
 336 including
 337 .I errno
 338 handling, size-zero allocations, and overflow checking;
 339 otherwise, other library routines may crash or operate incorrectly.
 340 For example, if the replacement
 341 .IR free ()
 342 does not preserve errno, then seemingly unrelated library routines may
 343 fail without having a valid reason in
 344 .IR errno .
 345 Private memory allocators may also need to replace other glibc functions;
 346 see "Replacing malloc" in the glibc manual for details.
 347 .PP
 348 Crashes in memory allocators
 349 are almost always related to heap corruption, such as overflowing
 350 an allocated chunk or freeing the same pointer twice.
 351 .PP
 352 The
 353 .BR malloc ()
 354 implementation is tunable via environment variables; see
 355 .BR mallopt (3)
 356 for details.
 357 .SS Nonportable behavior
 358 The behavior of
 359 these functions when the requested size is zero
 360 is glibc specific;
 361 other implementations may return NULL without setting
 362 .IR errno ,
 363 and portable POSIX programs should tolerate such behavior.
 364 See
 365 .BR realloc (3p).
 366 .PP
 367 POSIX requires memory allocators
 368 to set
 369 .I errno
 370 upon failure.
 371 However, the C standard does not require this, and applications
 372 portable to non-POSIX platforms should not assume this.
 373 .PP
 374 Portable programs should not use private memory allocators,
 375 as POSIX and the C standard do not allow replacement of
 376 .BR malloc (),
 377 .BR free (),
 378 .BR calloc (),
 379 and
 380 .BR realloc ().
 381 .SH SEE ALSO
 382 .\" http://g.oswego.edu/dl/html/malloc.html
 383 .\" A Memory Allocator - by Doug Lea
 384 .\"
 385 .\" http://www.bozemanpass.com/info/linux/malloc/Linux_Heap_Contention.html
 386 .\" Linux Heap, Contention in free() - David Boreham
 387 .\"
 388 .\" http://www.citi.umich.edu/projects/linux-scalability/reports/malloc.html
 389 .\" malloc() Performance in a Multithreaded Linux Environment -
 390 .\"     Check Lever, David Boreham
 391 .\"
 392 .ad l
 393 .nh
 394 .BR valgrind (1),
 395 .BR brk (2),
 396 .BR mmap (2),
 397 .BR alloca (3),
 398 .BR malloc_get_state (3),
 399 .BR malloc_info (3),
 400 .BR malloc_trim (3),
 401 .BR malloc_usable_size (3),
 402 .BR mallopt (3),
 403 .BR mcheck (3),
 404 .BR mtrace (3),
 405 .BR posix_memalign (3)
 406 .PP
 407 For details of the GNU C library implementation, see
 408 .UR https://sourceware.org/glibc/wiki/MallocInternals
 409 .UE .