# malloc

## NAME



           malloc, free, calloc, realloc, reallocarray - allocate and free
           dynamic memory
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <stdlib.h>**
    
           **void *malloc(size_t** _size_**);**
           **void free(void *_Nullable** _p_**);**
           **void *calloc(size_t** _n_**, size_t** _size_**);**
           **void *realloc(void *_Nullable** _p_**, size_t** _size_**);**
           **void *reallocarray(void *_Nullable** _p_**, size_t** _n_**, size_t** _size_**);**
    
       Feature Test Macro Requirements for glibc (see
       feature_test_macros(7)):
    
           **reallocarray**():
               Since glibc 2.29:
                   _DEFAULT_SOURCE
               glibc 2.28 and earlier:
                   _GNU_SOURCE
    


## DESCRIPTION



       **malloc()**
           The **malloc**() function allocates _size_ bytes and returns a pointer
           to the allocated memory.  _The memory is not initialized_.  If _size_
           is 0, then **malloc**() returns a unique pointer value that can later
           be successfully passed to **free**().  (See "Nonportable behavior" for
           portability issues.)
    
       **free()**
           The **free**() function frees the memory space pointed to by _p_ , which
           must have been returned by a previous call to **malloc**() or related
           functions.  Otherwise, or if _p_ has already been freed, undefined
           behavior occurs.  If _p_ is NULL, no operation is performed.
    
       **calloc()**
           The **calloc**() function allocates memory for an array of _n_ elements
           of _size_ bytes each and returns a pointer to the allocated memory.
           The memory is set to zero.  If _n_ or _size_ is 0, then **calloc**()
           returns a unique pointer value that can later be successfully
           passed to **free**().
    
           If the multiplication of _n_ and _size_ would result in integer
           overflow, then **calloc**() returns an error.  By contrast, an integer
           overflow would not be detected in the following call to **malloc**(),
           with the result that an incorrectly sized block of memory would be
           allocated:
    
               malloc(n * size);
    
       **realloc()**
           The **realloc**() function changes the size of the memory block
           pointed to by _p_ to _size_ bytes.  The contents of the memory 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 _not_ be initialized.
    
           If _p_ is NULL, then the call is equivalent to _malloc(size)_ , for all
           values of _size_.
    
           If _size_ is equal to zero, and _p_ is not NULL, then the call is
           equivalent to _free(p)_ (but see "Nonportable behavior" for
           portability issues).
    
           Unless _p_ is NULL, it must have been returned by an earlier call to
           **malloc** or related functions.  If the area pointed to was moved, a
           _free(p)_ is done.
    
       **reallocarray()**
           The **reallocarray**() function changes the size of (and possibly
           moves) the memory block pointed to by _p_ to be large enough for an
           array of _n_ elements, each of which is _size_ bytes.  It is
           equivalent to the call
    
               realloc(p, n * size);
    
           However, unlike that **realloc**() call, **reallocarray**() fails safely
           in the case where the multiplication would overflow.  If such an
           overflow occurs, **reallocarray**() returns an error.
    


## RETURN VALUE



           The **malloc**(), **calloc**(), **realloc**(), and **reallocarray**() functions
           return a pointer to the allocated memory, which is suitably
           aligned for any type that fits into the requested size or less.
           On error, these functions return NULL and set _errno_.  Attempting
           to allocate more than **PTRDIFF_MAX** bytes is considered an error, as
           an object that large could cause later pointer subtraction to
           overflow.
    
           The **free**() function returns no value, and preserves _errno_.
    
           The **realloc**() and **reallocarray**() functions return NULL if _p_ is not
           NULL and the requested size is zero; this is not considered an
           error.  (See "Nonportable behavior" for portability issues.)
           Otherwise, the returned pointer may be the same as _p_ if the
           allocation was not moved (e.g., there was room to expand the
           allocation in-place), or different from _p_ if the allocation was
           moved to a new address.  If these functions fail, the original
           block is left untouched; it is not freed or moved.
    


## ERRORS



           **calloc**(), **malloc**(), **realloc**(), and **reallocarray**() can fail with
           the following error:
    
           **ENOMEM** Out of memory.  Possibly, the application hit the **RLIMIT_AS**
                  or **RLIMIT_DATA** limit described in getrlimit(2).  Another
                  reason could be that the number of mappings created by the
                  caller process exceeded the limit specified by
                  _/proc/sys/vm/max_map_count_.
    


## ATTRIBUTES



           For an explanation of the terms used in this section, see
           attributes(7).
           ┌──────────────────────────────────────┬───────────────┬─────────┐
           │ **Interface** │ **Attribute** │ **Value** │
           ├──────────────────────────────────────┼───────────────┼─────────┤
           │ **malloc**(), **free**(), **calloc**(),          │ Thread safety │ MT-Safe │
           │ **realloc**()                            │               │         │
           └──────────────────────────────────────┴───────────────┴─────────┘
    


## STANDARDS



           **malloc**()
           **free**()
           **calloc**()
           **realloc**()
                  C23, POSIX.1-2024.
    
           **reallocarray**()
                  POSIX.1-2024.
    
       **realloc(p, 0)**
           The behavior of _realloc(p, 0)_ in glibc doesn't conform to any of
           C99, C11, POSIX.1-2001, POSIX.1-2004, POSIX.1-2008, POSIX.1-2013,
           POSIX.1-2017, or POSIX.1-2024.  The C17 specification was changed
           to make it conforming, but that specification made it impossible
           to write code that reliably determines if the input pointer is
           freed after _realloc(p, 0)_ , and C23 changed it again to make this
           undefined behavior, acknowledging that the C17 specification was
           broad enough that undefined behavior wasn't worse than that.
    
           **reallocarray**() suffers the same issues in glibc.
    
           musl libc and the BSDs conform to all versions of ISO C and
           POSIX.1.
    
           gnulib provides the _realloc-posix_ module, which provides wrappers
           **realloc**() and **reallocarray**() that conform to all versions of ISO C
           and POSIX.1.
    
           There's a proposal to standardize the BSD behavior: 
           ⟨https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3621.txt⟩.
    


## NOTES



           By default, Linux follows an optimistic memory allocation
           strategy.  This means that when **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 _/proc/sys/vm/overcommit_memory_ and
           _/proc/sys/vm/oom_adj_ in proc(5), and the Linux kernel source file
           _Documentation/vm/overcommit-accounting.rst_.
    
           Normally, **malloc**() allocates memory from the heap, and adjusts the
           size of the heap as required, using sbrk(2).  When allocating
           blocks of memory larger than **MMAP_THRESHOLD** bytes, the glibc
           **malloc**() implementation allocates the memory as a private
           anonymous mapping using mmap(2).  **MMAP_THRESHOLD** is 128 kB by
           default, but is adjustable using mallopt(3).  Prior to Linux 4.7
           allocations performed using mmap(2) were unaffected by the
           **RLIMIT_DATA** resource limit; since Linux 4.7, this limit is also
           enforced for allocations performed using mmap(2).
    
           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
           _memory allocation arenas_ if mutex contention is detected.  Each
           arena is a large region of memory that is internally allocated by
           the system (using brk(2) or mmap(2)), and managed with its own
           mutexes.
    
           If your program uses a private memory allocator, it should do so
           by replacing **malloc**(), **free**(), **calloc**(), and **realloc**().  The
           replacement functions must implement the documented glibc
           behaviors, including _errno_ handling, size-zero allocations, and
           overflow checking; otherwise, other library routines may crash or
           operate incorrectly.  For example, if the replacement _free_() does
           not preserve _errno_ , then seemingly unrelated library routines may
           fail without having a valid reason in _errno_.  Private memory
           allocators may also need to replace other glibc functions; see
           "Replacing malloc" in the glibc manual for details.
    
           Crashes in memory allocators are almost always related to heap
           corruption, such as overflowing an allocated chunk or freeing the
           same pointer twice.
    
           The **malloc**() implementation is tunable via environment variables;
           see mallopt(3) for details.
    
       **Nonportable behavior**
           The behavior of these functions when the requested size is zero is
           glibc specific; other implementations may return NULL without
           setting _errno_ , and portable POSIX programs should tolerate such
           behavior.  See realloc(3p).
    
           POSIX requires memory allocators to set _errno_ upon failure.
           However, the C standard does not require this, and applications
           portable to non-POSIX platforms should not assume this.
    
           Portable programs should not use private memory allocators, as
           POSIX and the C standard do not allow replacement of **malloc**(),
           **free**(), **calloc**(), and **realloc**().
    


## BUGS



           Programmers would naturally expect by induction that
           _realloc(p, size)_ is consistent with _free(p)_ and _malloc(size)_ , as
           that is the behavior in the general case.  This is not explicitly
           required by POSIX.1-2024 or C11, but all conforming
           implementations are consistent with that.
    
           The glibc implementation of **realloc**() is not consistent with that,
           and as a consequence, it is dangerous to call _realloc(p, 0)_ in
           glibc.
    
           A trivial workaround for glibc is calling it as
           _realloc(p, size?size:1)_.
    
           The workaround for **reallocarray**() in glibc —which shares the same
           bug— would be _reallocarray(p, n?n:1, size?size:1)_.
    


## EXAMPLES



           #include <err.h>
           #include <stddef.h>
           #include <stdio.h>
           #include <stdlib.h>
           #include <string.h>
    
           #define MALLOCARRAY(n, type)  ((type *) my_mallocarray(n, sizeof(type)))
           #define MALLOC(type)          MALLOCARRAY(1, type)
    
           static inline void *my_mallocarray(size_t n, size_t size);
    
           int
           main(void)
           {
               char  *p;
    
               p = MALLOCARRAY(32, char);
               if (p == NULL)
                   err(EXIT_FAILURE, "malloc");
    
               strlcpy(p, "foo", 32);
               puts(p);
           }
    
           static inline void *
           my_mallocarray(size_t n, size_t size)
           {
               return reallocarray(NULL, n, size);
           }
    


* * *