Standard C Library Functions                           malloc(3C)

NAME
     malloc, calloc, free, memalign, realloc,  valloc,  alloca  -
     memory allocator

SYNOPSIS
     #include <stdlib.h>

     void *malloc(size_t size);

     void *calloc(size_t nelem, size_t elsize);

     void free(void *ptr);

     void *memalign(size_t alignment, size_t size);

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

     void *valloc(size_t size);

     #include <alloca.h>

     void *alloca(size_t size);

DESCRIPTION
     The  malloc()  and  free()  functions  provide   a   simple,
     general-purpose  memory  allocation  package.  The  malloc()
     function 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(), calloc(), or realloc(). After free()
     is executed, this space is made available for further  allo-
     cation  by  the application, though not returned to the sys-
     tem. Memory is returned to the system only upon  termination
     of  the  application.   If  ptr is a null pointer, no action
     occurs.

     Undefined results will occur if the space assigned  by  mal-
     loc()  is  overrun  or  if  some  random number is passed to
     free().

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

     The memalign() function allocates size bytes on a  specified
     alignment  boundary  and  returns a pointer to the allocated
     block. The value of the returned address is guaranteed to be
     an even multiple of alignment. Note that the value of align-
     ment must be a power of two, and must  be  greater  than  or
     equal to the size of a word.

SunOS 5.8           Last change: 26 Feb 1999                    1

Standard C Library Functions                           malloc(3C)

     The realloc() function changes the size of the block pointed
     to by ptr to size bytes and returns a pointer to the (possi-
     bly moved) block.  The contents will be unchanged up to  the
     lesser  of the new and old sizes. If  ptr is NULL, realloc()
     behaves like malloc() for the specified size. If  size is  0
     and  ptr  is  not a null pointer, the space pointed to is is
     made available for further allocation  by  the  application,
     though not returned to the system. Memory is returned to the
     system only upon termination of the application.

     The     valloc()     function     is      equivalent      to
     memalign(sysconf(_SC_PAGESIZE),size).

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

     The malloc(), realloc(), memalign(), and  valloc() functions
     will fail if there is not enough available memory.

     The alloca() function allocates size bytes of space  in  the
     stack  frame  of  the  caller,  and returns a pointer to the
     allocated block. This temporary space is automatically freed
     when  the  caller  returns. If the allocated block is beyond
     the current stack limit, the  resulting  behavior  is  unde-
     fined.

RETURN VALUES
     If there  is  no  available  memory,   malloc(),  realloc(),
     memalign(),  valloc(),  and  calloc() return a null pointer.
     When realloc() returns NULL, the block pointed to by  ptr is
     left  intact.  If   size,  nelem,  or elsize is  0, a unique
     pointer to the arena is returned.

     If malloc(), calloc(), or realloc() returns  unsuccessfully,
     errno will be set to indicate the error. The free() function
     does not set errno.

ERRORS
     The malloc(), calloc(), and realloc()  functions  will  fail
     if:

     ENOMEM
           The physical limits of the system are exceeded by size
           bytes of memory which cannot be allocated.

     EAGAIN
           There is not enough memory available at this point  in
           time  to allocate size bytes of memory; but the appli-
           cation could try again later.

SunOS 5.8           Last change: 26 Feb 1999                    2

Standard C Library Functions                           malloc(3C)

USAGE
     Comparative features of malloc(3C), bsdmalloc(3MALLOC),  and
     malloc(3MALLOC) are as follows:

        o  The bsdmalloc(3MALLOC) routines afford better  perfor-
           mance, but are space-inefficient.

        o  The malloc(3MALLOC) routines are space-efficient,  but
           have slower performance.

        o  The standard, fully SCD-compliant malloc routines  are
           a trade-off between performance and space-efficiency.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|

SEE ALSO
     brk(2), getrlimit(2),  bsdmalloc(3MALLOC),  malloc(3MALLOC),
     mapmalloc(3MALLOC), watchmalloc(3MALLOC), attributes(5)

WARNINGS
     Undefined results will occur if the  size  requested  for  a
     block  of  memory  exceeds  the  maximum size of a process's
     heap, which may be obtained with getrlimit(2)

     The alloca() function is machine-, compiler-,  and  most  of
     all, system-dependent. Its use is strongly discouraged.

SunOS 5.8           Last change: 26 Feb 1999                    3