Man Pages

malloc(3) - phpMan malloc(3) - phpMan

Command: man perldoc info search(apropos)  


MALLOC(3)                  Linux Programmer's Manual                 MALLOC(3)



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 allo-
       cated 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 over-
       flowing 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 argu-
       ment,  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 non-zero 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.22 of the Linux man-pages project.  A description of the project, and informa-
       tion about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



GNU                               2009-01-13                         MALLOC(3)