malloc(3)

NAME

     malloc, free, realloc, calloc, alloca - memory allocator

SYNOPSIS

     #include <sys/types.h>
     #include <stdlib.h>
     #include <alloca.h>

     void *malloc(size_t size)
     void free(void *ptr)
     void *realloc(void *ptr, size_t size)
     void *calloc(size_t nelem, size_t elsize)
     void *alloca(size_t size)

DESCRIPTION

     Malloc and free provide  a  general-purpose  memory  allocation  package.
     Malloc returns a pointer to a block of at least size bytes beginning on a
     word boundary.

     The argument to free is a pointer to  a  block  previously  allocated  by
     malloc;  this  space  is  made  available for further allocation, but its
     contents are left undisturbed.  A call with a null ptr is legal and  does
     nothing.

     Needless to say, grave disorder will result  if  the  space  assigned  by
     malloc is overrun or if some random number is handed to free.

     Malloc maintains  multiple  lists  of  free  blocks  according  to  size,
     allocating  space  from the appropriate list.  It calls sbrk (see brk(2))
     to get more memory from the  system  when  there  is  no  suitable  space
     already free.

     Realloc changes the size of the block pointed to by ptr to size bytes and
     returns  a  pointer  to the (possibly moved) block.  The contents will be
     unchanged up to the lesser of the new and old sizes.  A call with a  null
     ptr is legal and has the same result as malloc(size).

     Calloc allocates space for an array of nelem elements of size elsize. The
     space is initialized to zeros.

     Alloca allocates size bytes of space in the stack frame  of  the  caller.
     This temporary space is automatically freed on return.

     Each of the allocation routines  returns  a  pointer  to  space  suitably
     aligned  (after  possible  pointer  coercion)  for storage of any type of
     object.

SEE ALSO

     brk(2).

DIAGNOSTICS

     Malloc, realloc and calloc return a null pointer if there is no available
     memory  or  if the arena has been detectably corrupted by storing outside
     the bounds of a block.

NOTES

     Other implementations of malloc, realloc or  calloc  may  return  a  null
     pointer  if the size of the requested block is zero.  This implementation
     will always return a zero length block  at  a  unique  address,  but  you
     should  keep in mind that a null return is possible if the program is run
     to another system and that this should  not  be  mistakenly  seen  as  an
     error.

BUGS

     When realloc returns a null pointer, the block pointed to by ptr  may  be
     destroyed.

     Alloca is machine dependent; its use is discouraged.