| .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Modified Sat Jul 24 19:00:59 1993 by Rik Faith (faith@cs.unc.edu) |
| .\" Clarification concerning realloc, iwj10@cus.cam.ac.uk (Ian Jackson), 950701 |
| .\" Documented MALLOC_CHECK_, Wolfram Gloger (wmglo@dent.med.uni-muenchen.de) |
| .\" 2007-09-15 mtk: added notes on malloc()'s use of sbrk() and mmap(). |
| .\" |
| .\" FIXME . Review http://austingroupbugs.net/view.php?id=374 |
| .\" to see what changes are required on this page. |
| .\" |
| .TH MALLOC 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| malloc, free, calloc, realloc \- allocate and free dynamic memory |
| .SH SYNOPSIS |
| .nf |
| .B #include <stdlib.h> |
| .PP |
| .BI "void *malloc(size_t " "size" ); |
| .BI "void free(void " "*ptr" ); |
| .BI "void *calloc(size_t " "nmemb" ", size_t " "size" ); |
| .BI "void *realloc(void " "*ptr" ", size_t " "size" ); |
| .BI "void *reallocarray(void " "*ptr" ", size_t " nmemb ", size_t " "size" ); |
| .fi |
| .PP |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .PP |
| .BR reallocarray (): |
| .br |
| .RS 4 |
| .ad l |
| _GNU_SOURCE |
| .RE |
| .ad |
| .SH DESCRIPTION |
| .PP |
| The |
| .BR malloc () |
| function allocates |
| .I size |
| bytes and returns a pointer to the allocated memory. |
| .IR "The memory is not initialized" . |
| If |
| .I size |
| is 0, then |
| .BR malloc () |
| returns either NULL, |
| .\" glibc does this: |
| or a unique pointer value that can later be successfully passed to |
| .BR free (). |
| .PP |
| The |
| .BR free () |
| function frees the memory space pointed to by |
| .IR ptr , |
| which must have been returned by a previous call to |
| .BR malloc (), |
| .BR calloc (), |
| or |
| .BR realloc (). |
| Otherwise, or if |
| .I free(ptr) |
| has already been called before, undefined behavior occurs. |
| If |
| .I ptr |
| is NULL, no operation is performed. |
| .PP |
| The |
| .BR calloc () |
| function allocates memory for an array of |
| .I nmemb |
| elements of |
| .I size |
| bytes each and returns a pointer to the allocated memory. |
| The memory is set to zero. |
| If |
| .I nmemb |
| or |
| .I size |
| is 0, then |
| .BR calloc () |
| returns either NULL, |
| .\" glibc does this: |
| or a unique pointer value that can later be successfully passed to |
| .BR free (). |
| .PP |
| The |
| .BR realloc () |
| function changes the size of the memory block pointed to by |
| .I ptr |
| to |
| .I size |
| bytes. |
| The contents will be unchanged in the range from the start of the region |
| up to the minimum of the old and new sizes. |
| If the new size is larger than the old size, the added memory will |
| .I not |
| be initialized. |
| If |
| .I ptr |
| is NULL, then the call is equivalent to |
| .IR malloc(size) , |
| for all values of |
| .IR size ; |
| if |
| .I size |
| is equal to zero, |
| and |
| .I ptr |
| is not NULL, then the call is equivalent to |
| .IR free(ptr) . |
| Unless |
| .I ptr |
| is NULL, it must have been returned by an earlier call to |
| .BR malloc (), |
| .BR calloc (), |
| or |
| .BR realloc (). |
| If the area pointed to was moved, a |
| .I free(ptr) |
| is done. |
| .PP |
| The |
| .BR reallocarray () |
| function changes the size of the memory block pointed to by |
| .I ptr |
| to be large enough for an array of |
| .I nmemb |
| elements, each of which is |
| .I size |
| bytes. |
| It is equivalent to the call |
| .PP |
| .in +4n |
| realloc(ptr, nmemb * size); |
| .in |
| .PP |
| However, unlike that |
| .BR realloc () |
| call, |
| .BR reallocarray () |
| fails safely in the case where the multiplication would overflow. |
| If such an overflow occurs, |
| .BR reallocarray () |
| returns NULL, sets |
| .I errno |
| to |
| .BR ENOMEM , |
| and leaves the original block of memory unchanged. |
| .SH RETURN VALUE |
| The |
| .BR malloc () |
| and |
| .BR calloc () |
| functions return a pointer to the allocated memory, |
| which is suitably aligned for any built-in type. |
| On error, these functions return NULL. |
| NULL may also be returned by a successful call to |
| .BR malloc () |
| with a |
| .I size |
| of zero, |
| or by a successful call to |
| .BR calloc () |
| with |
| .I nmemb |
| or |
| .I size |
| equal to zero. |
| .PP |
| The |
| .BR free () |
| function returns no value. |
| .PP |
| The |
| .BR realloc () |
| function returns a pointer to the newly allocated memory, which is suitably |
| aligned for any built-in type and may be different from |
| .IR ptr , |
| or NULL if the request fails. |
| If |
| .I size |
| was equal to 0, either NULL or a pointer suitable to be passed to |
| .BR free () |
| is returned. |
| If |
| .BR realloc () |
| fails, the original block is left untouched; it is not freed or moved. |
| .PP |
| On success, the |
| .BR reallocarray () |
| function returns a pointer to the newly allocated memory. |
| On failure, |
| it returns NULL and the original block of memory is left untouched. |
| .SH ERRORS |
| .BR calloc (), |
| .BR malloc (), |
| .BR realloc (), |
| and |
| .BR reallocarray () |
| can fail with the following error: |
| .TP |
| .B ENOMEM |
| Out of memory. |
| Possibly, the application hit the |
| .BR RLIMIT_AS |
| or |
| .BR RLIMIT_DATA |
| limit described in |
| .BR getrlimit (2). |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .TS |
| allbox; |
| lbw20 lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR malloc (), |
| .BR free (), |
| .br |
| .BR calloc (), |
| .BR realloc () |
| T} Thread safety MT-Safe |
| .TE |
| .SH CONFORMING TO |
| .BR malloc (), |
| .BR free (), |
| .BR calloc (), |
| .BR realloc (): |
| POSIX.1-2001, POSIX.1-2008, C89, C99. |
| .PP |
| .BR reallocarray () |
| is a nonstandard extension that first appeared in OpenBSD 5.6 and FreeBSD 11.0. |
| .SH NOTES |
| By default, Linux follows an optimistic memory allocation strategy. |
| This means that when |
| .BR malloc () |
| returns non-NULL there is no guarantee that the memory really |
| is available. |
| In case it turns out that the system is out of memory, |
| one or more processes will be killed by the OOM killer. |
| For more information, see the description of |
| .IR /proc/sys/vm/overcommit_memory |
| and |
| .IR /proc/sys/vm/oom_adj |
| in |
| .BR proc (5), |
| and the Linux kernel source file |
| .IR Documentation/vm/overcommit-accounting . |
| .PP |
| Normally, |
| .BR malloc () |
| allocates memory from the heap, and adjusts the size of the heap |
| as required, using |
| .BR sbrk (2). |
| When allocating blocks of memory larger than |
| .B MMAP_THRESHOLD |
| bytes, the glibc |
| .BR malloc () |
| implementation allocates the memory as a private anonymous mapping using |
| .BR mmap (2). |
| .B MMAP_THRESHOLD |
| is 128\ kB by default, but is adjustable using |
| .BR mallopt (3). |
| Prior to Linux 4.7 |
| allocations performed using |
| .BR mmap (2) |
| were unaffected by the |
| .B RLIMIT_DATA |
| resource limit; |
| since Linux 4.7, this limit is also enforced for allocations performed using |
| .BR mmap (2). |
| .PP |
| To avoid corruption in multithreaded applications, |
| mutexes are used internally to protect the memory-management |
| data structures employed by these functions. |
| In a multithreaded application in which threads simultaneously |
| allocate and free memory, |
| there could be contention for these mutexes. |
| To scalably handle memory allocation in multithreaded applications, |
| glibc creates additional |
| .IR "memory allocation arenas" |
| if mutex contention is detected. |
| Each arena is a large region of memory that is internally allocated |
| by the system |
| (using |
| .BR brk (2) |
| or |
| .BR mmap (2)), |
| and managed with its own mutexes. |
| .PP |
| SUSv2 requires |
| .BR malloc (), |
| .BR calloc (), |
| and |
| .BR realloc () |
| to set |
| .I errno |
| to |
| .B ENOMEM |
| upon failure. |
| Glibc assumes that this is done |
| (and the glibc versions of these routines do this); if you |
| use a private malloc implementation that does not set |
| .IR errno , |
| then certain library routines may fail without having |
| a reason in |
| .IR errno . |
| .PP |
| Crashes in |
| .BR malloc (), |
| .BR calloc (), |
| .BR realloc (), |
| or |
| .BR free () |
| are almost always related to heap corruption, such as overflowing |
| an allocated chunk or freeing the same pointer twice. |
| .PP |
| The |
| .BR malloc () |
| implementation is tunable via environment variables; see |
| .BR mallopt (3) |
| for details. |
| .SH SEE ALSO |
| .\" http://g.oswego.edu/dl/html/malloc.html |
| .\" A Memory Allocator - by Doug Lea |
| .\" |
| .\" http://www.bozemanpass.com/info/linux/malloc/Linux_Heap_Contention.html |
| .\" Linux Heap, Contention in free() - David Boreham |
| .\" |
| .\" http://www.citi.umich.edu/projects/linux-scalability/reports/malloc.html |
| .\" malloc() Performance in a Multithreaded Linux Environment - |
| .\" Check Lever, David Boreham |
| .\" |
| .ad l |
| .nh |
| .BR valgrind (1), |
| .BR brk (2), |
| .BR mmap (2), |
| .BR alloca (3), |
| .BR malloc_get_state (3), |
| .BR malloc_info (3), |
| .BR malloc_trim (3), |
| .BR malloc_usable_size (3), |
| .BR mallopt (3), |
| .BR mcheck (3), |
| .BR mtrace (3), |
| .BR posix_memalign (3) |