MALLOC(3C)                           SysV                           MALLOC(3C)



NAME
     malloc, free, realloc, calloc - main memory allocator

SYNOPSIS
     #include <stdlib.h>

     void *malloc (size)
     size_t size;

     void free (ptr)
     void *ptr;

     void *realloc (ptr, size)
     void *ptr;
     size_t size;

     void *calloc (nelem, elsize)
     size_t nelem, elsize;

DESCRIPTION
     malloc and free comprise a simple general-purpose memory allocation
     package.  malloc returns a pointer to a block of at least size bytes
     suitably aligned for any use.

     The argument to free is a pointer to a block previously allocated by
     malloc; free makes this space available for further allocation, but
     leaves its contents undisturbed.

     Undefined results will occur if the space assigned by malloc is overrun
     or if some random number is handed to free.

     malloc allocates the first contiguous reach of size byes of free space
     that it finds in a circular search from the last block allocated or
     freed.  It coalesces adjacent free blocks as it searches.  It calls sbrk
     (see brk(2)) to get more memory from the system when there is
     insufficient 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.  If no free
     block of size bytes is available in the storage arena, then realloc will
     ask malloc to enlarge the arena by size bytes and will then move the data
     to the new space.

     realloc also works if ptr points to a block freed since the last call of
     malloc, realloc, or calloc.  Thus, sequences of free, malloc and realloc
     can exploit the search strategy of malloc to do storage compaction.

     If ptr is a null pointer, the realloc function behaves like the malloc
     function for the specified size.

     If ptr does not match a pointer returned earlier by the calloc, malloc,
     or realloc functions, or if the space has previously been deallocated by
     a call to free or realloc, the behavior is undefined.

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

     The order and contiguity of storage allocated by successive calls to
     calloc, malloc, and realloc functions is unspecified. The pointer
     returned if the allocation succeeds is suitably aligned so that it may be

     assigned to a pointer to any type of object and then used to access such
     an object in the space allocated (until the space is explicitly freed or
     reallocated). Each such allocation yields a pointer to an object disjoint
     from any other object. The pointer returned points to the start (lowest
     byte address) of the allocated space. If the space cannot be allocated, a
     null pointer is returned. If the size of the space requested is zero, a
     unique pointer is returned. (This pointer should not be used to store any
     data.)

NOTES
     Developers of installed libraries should include <apollo/shlib.h> in
     those modules which use malloc, free, or realloc.  Doing so assures that
     references to these routines resolve to those defined by the application,
     if any.

     To be compatible with traditional C usage, make malloc, calloc, and
     realloc return type pointer-to-character by compiling your program with
     the

          -A nansi

     option (see cc(1)) and inserting the directive

          #define _CLASSIC_TYPES

     before any #include directives.

SEE ALSO
     brk(2), cc(1), malloc(3X), malloc.dbg(3C).

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.  When this happens, the block pointed to by ptr
     may be destroyed.

ERRORS
     The calloc, malloc, and realloc functions fail if:

     [ENOMEM]  Insufficient storage space is available.

NOTES
     Search time increases when many objects have been allocated; that is, if
     a program allocates but never frees, then each successive allocation
     takes longer.  For an alternate, more flexible implementation, see
     malloc(3X).