Provided by: manpages-dev_3.35-0.1ubuntu1_all bug

NAME

       malloc, free, calloc, realloc - Allocate and free dynamic memory

SYNOPSIS

       #include <stdlib.h>

       void *malloc(size_t size);
       void free(void *ptr);
       void *calloc(size_t nmemb, size_t size);
       void *realloc(void *ptr, size_t size);

DESCRIPTION

       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  either  NULL,  or  a
       unique pointer value that can later be successfully passed to free().

       The  free()  function  frees  the  memory  space  pointed  to by ptr, which must have been
       returned by a previous  call  to  malloc(),  calloc()  or  realloc().   Otherwise,  or  if
       free(ptr)  has  already been called before, undefined behavior occurs.  If ptr is NULL, no
       operation is performed.

       The calloc() function allocates memory for an array of nmemb elements of size  bytes  each
       and  returns  a  pointer to the allocated memory.  The memory is set to zero.  If nmemb or
       size is 0, then calloc() returns either NULL, or a unique pointer value that can later  be
       successfully passed to free().

       The  realloc()  function  changes  the  size of the memory block pointed to by ptr to 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 not be  initialized.   If  ptr  is  NULL,  then  the  call  is  equivalent  to
       malloc(size),  for all values of size; if size is equal to zero, and ptr is not NULL, then
       the call is equivalent to free(ptr).  Unless ptr is NULL, it must have been returned by an
       earlier  call  to  malloc(),  calloc()  or realloc().  If the area pointed to was moved, a
       free(ptr) is done.

RETURN VALUE

       The malloc() and calloc() functions return a pointer  to  the  allocated  memory  that  is
       suitably  aligned  for any kind of variable.  On error, these functions return NULL.  NULL
       may also be returned by a successful call to malloc()  with  a  size  of  zero,  or  by  a
       successful call to calloc() with nmemb or size equal to zero.

       The free() function returns no value.

       The  realloc() function returns a pointer to the newly allocated memory, which is suitably
       aligned for any kind of variable and may be different from ptr, or  NULL  if  the  request
       fails.   If  size was equal to 0, either NULL or a pointer suitable to be passed to free()
       is returned.  If realloc() fails the original block is left untouched; it is not freed  or
       moved.

CONFORMING TO

       C89, C99.

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 kernel source
       file Documentation/vm/overcommit-accounting.

       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).  Allocations  performed  using  mmap(2)  are  unaffected  by  the  RLIMIT_DATA
       resource limit (see getrlimit(2)).

       The  UNIX  98  standard  requires malloc(), calloc(), and realloc() to set errno to 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 errno, then certain
       library routines may fail without having a reason in errno.

       Crashes in malloc(), calloc(), realloc(), or free() are  almost  always  related  to  heap
       corruption, such as overflowing an allocated chunk or freeing the same pointer twice.

       Recent  versions  of  Linux  libc  (later  than 5.4.23) and glibc (2.x) include a malloc()
       implementation which is tunable via environment variables.  When MALLOC_CHECK_ is  set,  a
       special  (less  efficient) implementation is used which is designed to be tolerant against
       simple errors, such as double calls of free() with the same argument,  or  overruns  of  a
       single byte (off-by-one bugs).  Not all such errors can be protected against, however, and
       memory leaks can result.  If MALLOC_CHECK_ is set to 0, any detected  heap  corruption  is
       silently  ignored;  if  set  to 1, a diagnostic message is printed on stderr; if set to 2,
       abort(3) is called immediately; if set to 3, a diagnostic message is printed on stderr and
       the  program  is  aborted.   Using  a  nonzero  MALLOC_CHECK_  value can be useful because
       otherwise a crash may happen much later, and the true cause for the problem is  then  very
       hard to track down.

SEE ALSO

       brk(2), mallopt(3), mmap(2), alloca(3), posix_memalign(3)

COLOPHON

       This  page  is  part of release 3.35 of the Linux man-pages project.  A description of the
       project, and information about reporting bugs, can be found at  http://man7.org/linux/man-
       pages/.