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  2017-09-15 "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 .br
  54 .RS 4
  55 .ad l
  56 _GNU_SOURCE
  57 .RE
  58 .ad
  59 .SH DESCRIPTION
  60 .PP
  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 .IR free(ptr) .
 153 Unless
 154 .I ptr
 155 is NULL, it must have been returned by an earlier call to
 156 .BR malloc (),
 157 .BR calloc (),
 158 or
 159 .BR realloc ().
 160 If the area pointed to was moved, a
 161 .I free(ptr)
 162 is done.
 163 .PP
 164 The
 165 .BR reallocarray ()
 166 function changes the size of the memory block pointed to by
 167 .I ptr
 168 to be large enough for an array of
 169 .I nmemb
 170 elements, each of which is
 171 .I size
 172 bytes.
 173 It is equivalent to the call
 174 .PP
 175 .in +4n
 176     realloc(ptr, nmemb * size);
 177 .in
 178 .PP
 179 However, unlike that
 180 .BR realloc ()
 181 call,
 182 .BR reallocarray ()
 183 fails safely in the case where the multiplication would overflow.
 184 If such an overflow occurs,
 185 .BR reallocarray ()
 186 returns NULL, sets
 187 .I errno
 188 to
 189 .BR ENOMEM ,
 190 and leaves the original block of memory unchanged.
 191 .SH RETURN VALUE
 192 The
 193 .BR malloc ()
 194 and
 195 .BR calloc ()
 196 functions return a pointer to the allocated memory,
 197 which is suitably aligned for any built-in type.
 198 On error, these functions return NULL.
 199 NULL may also be returned by a successful call to
 200 .BR malloc ()
 201 with a
 202 .I size
 203 of zero,
 204 or by a successful call to
 205 .BR calloc ()
 206 with
 207 .I nmemb
 208 or
 209 .I size
 210 equal to zero.
 211 .PP
 212 The
 213 .BR free ()
 214 function returns no value.
 215 .PP
 216 The
 217 .BR realloc ()
 218 function returns a pointer to the newly allocated memory, which is suitably
 219 aligned for any built-in type and may be different from
 220 .IR ptr ,
 221 or NULL if the request fails.
 222 If
 223 .I size
 224 was equal to 0, either NULL or a pointer suitable to be passed to
 225 .BR free ()
 226 is returned.
 227 If
 228 .BR realloc ()
 229 fails, the original block is left untouched; it is not freed or moved.
 230 .PP
 231 On success, the
 232 .BR reallocarray ()
 233 function returns a pointer to the newly allocated memory.
 234 On failure,
 235 it returns NULL and the original block of memory is left untouched.
 236 .SH ERRORS
 237 .BR calloc (),
 238 .BR malloc (),
 239 .BR realloc (),
 240 and
 241 .BR reallocarray ()
 242 can fail with the following error:
 243 .TP
 244 .B ENOMEM
 245 Out of memory.
 246 Possibly, the application hit the
 247 .BR RLIMIT_AS
 248 or
 249 .BR RLIMIT_DATA
 250 limit described in
 251 .BR getrlimit (2).
 252 .SH ATTRIBUTES
 253 For an explanation of the terms used in this section, see
 254 .BR attributes (7).
 255 .TS
 256 allbox;
 257 lbw20 lb lb
 258 l l l.
 259 Interface       Attribute       Value
 260 T{
 261 .BR malloc (),
 262 .BR free (),
 263 .br
 264 .BR calloc (),
 265 .BR realloc ()
 266 T}      Thread safety   MT-Safe
 267 .TE
 268 .SH CONFORMING TO
 269 .BR malloc (),
 270 .BR free (),
 271 .BR calloc (),
 272 .BR realloc ():
 273 POSIX.1-2001, POSIX.1-2008, C89, C99.
 274 .PP
 275 .BR reallocarray ()
 276 is a nonstandard extension that first appeared in OpenBSD 5.6 and FreeBSD 11.0.
 277 .SH NOTES
 278 By default, Linux follows an optimistic memory allocation strategy.
 279 This means that when
 280 .BR malloc ()
 281 returns non-NULL there is no guarantee that the memory really
 282 is available.
 283 In case it turns out that the system is out of memory,
 284 one or more processes will be killed by the OOM killer.
 285 For more information, see the description of
 286 .IR /proc/sys/vm/overcommit_memory
 287 and
 288 .IR /proc/sys/vm/oom_adj
 289 in
 290 .BR proc (5),
 291 and the Linux kernel source file
 292 .IR Documentation/vm/overcommit-accounting .
 293 .PP
 294 Normally,
 295 .BR malloc ()
 296 allocates memory from the heap, and adjusts the size of the heap
 297 as required, using
 298 .BR sbrk (2).
 299 When allocating blocks of memory larger than
 300 .B MMAP_THRESHOLD
 301 bytes, the glibc
 302 .BR malloc ()
 303 implementation allocates the memory as a private anonymous mapping using
 304 .BR mmap (2).
 305 .B MMAP_THRESHOLD
 306 is 128\ kB by default, but is adjustable using
 307 .BR mallopt (3).
 308 Prior to Linux 4.7
 309 allocations performed using
 310 .BR mmap (2)
 311 were unaffected by the
 312 .B RLIMIT_DATA
 313 resource limit;
 314 since Linux 4.7, this limit is also enforced for allocations performed using
 315 .BR mmap (2).
 316 .PP
 317 To avoid corruption in multithreaded applications,
 318 mutexes are used internally to protect the memory-management
 319 data structures employed by these functions.
 320 In a multithreaded application in which threads simultaneously
 321 allocate and free memory,
 322 there could be contention for these mutexes.
 323 To scalably handle memory allocation in multithreaded applications,
 324 glibc creates additional
 325 .IR "memory allocation arenas"
 326 if mutex contention is detected.
 327 Each arena is a large region of memory that is internally allocated
 328 by the system
 329 (using
 330 .BR brk (2)
 331 or
 332 .BR mmap (2)),
 333 and managed with its own mutexes.
 334 .PP
 335 SUSv2 requires
 336 .BR malloc (),
 337 .BR calloc (),
 338 and
 339 .BR realloc ()
 340 to set
 341 .I errno
 342 to
 343 .B ENOMEM
 344 upon failure.
 345 Glibc assumes that this is done
 346 (and the glibc versions of these routines do this); if you
 347 use a private malloc implementation that does not set
 348 .IR errno ,
 349 then certain library routines may fail without having
 350 a reason in
 351 .IR errno .
 352 .PP
 353 Crashes in
 354 .BR malloc (),
 355 .BR calloc (),
 356 .BR realloc (),
 357 or
 358 .BR free ()
 359 are almost always related to heap corruption, such as overflowing
 360 an allocated chunk or freeing the same pointer twice.
 361 .PP
 362 The
 363 .BR malloc ()
 364 implementation is tunable via environment variables; see
 365 .BR mallopt (3)
 366 for details.
 367 .SH SEE ALSO
 368 .\" http://g.oswego.edu/dl/html/malloc.html
 369 .\" A Memory Allocator - by Doug Lea
 370 .\"
 371 .\" http://www.bozemanpass.com/info/linux/malloc/Linux_Heap_Contention.html
 372 .\" Linux Heap, Contention in free() - David Boreham
 373 .\"
 374 .\" http://www.citi.umich.edu/projects/linux-scalability/reports/malloc.html
 375 .\" malloc() Performance in a Multithreaded Linux Environment -
 376 .\"     Check Lever, David Boreham
 377 .\"
 378 .ad l
 379 .nh
 380 .BR valgrind (1),
 381 .BR brk (2),
 382 .BR mmap (2),
 383 .BR alloca (3),
 384 .BR malloc_get_state (3),
 385 .BR malloc_info (3),
 386 .BR malloc_trim (3),
 387 .BR malloc_usable_size (3),
 388 .BR mallopt (3),
 389 .BR mcheck (3),
 390 .BR mtrace (3),
 391 .BR posix_memalign (3)