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