man3/malloc.3

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