Provided by: manpages-dev_3.24-1ubuntu1_all bug

NAME

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

SYNOPSIS

       #include <stdlib.h>

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

DESCRIPTION

       calloc()  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().

       malloc()  allocates  size  bytes and returns a pointer to the allocated
       memory.  The memory is not  cleared.   If  size  is  0,  then  malloc()
       returns  either  NULL,  or  a  unique  pointer  value that can later be
       successfully passed to free().

       free() 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.

       realloc()  changes  the  size  of the memory block pointed to by ptr to
       size bytes.  The contents will be unchanged to the minimum of  the  old
       and new sizes; newly allocated memory will be uninitialized.  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

       For calloc() and malloc(), return a pointer to  the  allocated  memory,
       which  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.

       free() returns no value.

       realloc() 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

       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 Unix98 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.

BUGS

       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.  This is a really bad bug.  In
       case it turns out that the  system  is  out  of  memory,  one  or  more
       processes  will be killed by the infamous OOM killer.  In case Linux is
       employed under circumstances  where  it  would  be  less  desirable  to
       suddenly  lose  some randomly picked processes, and moreover the kernel
       version is sufficiently recent, one can switch off this  overcommitting
       behavior using a command like:

           # echo 2 > /proc/sys/vm/overcommit_memory

       See  also  the  kernel  Documentation  directory,  files vm/overcommit-
       accounting and sysctl/vm.txt.

SEE ALSO

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

COLOPHON

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