Quick ?s
Cheat Sheets
Man Pages
The Lynx
Software
MALLOC(3)		   Linux Programmers Manual		    MALLOC(3)



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

SYNOPSIS
       #include 

       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 suc
       cessfully 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().	Other
       wise, or if free(ptr) has already been called before, undefined	behav
       ior 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 realloc()
       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 mem
       ory 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  mal
       lopt(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 over
       runs  of  a  single byte (off-by-one bugs).  Not all such errors can be
       protected against, however, and	memory	leaks  can  result.   If  MAL
       LOC_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 MAL
       LOC_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  pro
       cesses  will  be  killed  by the infamous OOM killer.  In case Linux is
       employed under circumstances where it would be less desirable  to  sud
       denly lose some randomly picked processes, and moreover the kernel ver
       sion 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.05 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/.



GNU				  2008-04-05			     MALLOC(3)




Yals.net is © 1999-2009 Crescendo Communications
Sharing tech info on the web for more than a decade!
This page was generated Thu Apr 30 17:05:27 2009