malloc(3X)                                             malloc(3X)



NAME
     malloc, free, realloc, calloc, mallopt, mallinfo - fast main
     memory allocator

SYNOPSIS
     #include <malloc.h>

     char *malloc (size)
     unsigned size;

     void free (ptr)
     char *ptr;

     char *realloc (ptr, size)
     char *ptr;
     unsigned size;

     char *calloc (nelem, elsize)
     unsigned nelem, elsize;

     int mallopt (cmd, value)
     int cmd, value;

     struct mallinfo mallinfo()

DESCRIPTION
     malloc and free provide a simple general-purpose memory
     allocation package, which runs considerably faster than the
     malloc(3C) package.  It is found in the library malloc, and
     is loaded if the option -lmalloc is used with cc(1) or
     ld(1).

     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; after free is performed this space is
     made available for further allocation, and its contents have
     been destroyed (but see mallopt below for a way to change
     this behavior).

     Undefined results will occur if the space assigned by malloc
     is overrun or if some random number is handed to 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.

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




Page 1                        CX/UX Programmer's Reference Manual

malloc(3X)                                             malloc(3X)



     Mallopt provides for control over the allocation algorithm.
     The available values for cmd are:

     M_MXFAST Set maxfast to value.  The algorithm allocates all
              blocks below the size of maxfast in large groups
              and then doles them out very quickly.  The default
              value for maxfast is 24.

     M_NLBLKS Set numlblks to value.  The above mentioned ``large
              groups'' each contain numlblks blocks. Numlblks
              must be greater than 0.  The default value for
              numlblks is 100.

     M_GRAIN  Set grain to value.  The sizes of all blocks
              smaller than maxfast are considered to be rounded
              up to the nearest multiple of grain.  Grain must be
              greater than 0.  The default value of grain is the
              smallest number of bytes which will allow alignment
              of any data type.  Value will be rounded up to a
              multiple of the default when grain is set.



     M_KEEP   Preserve data in a freed block until the next mal-
              loc, realloc, or calloc.  This option is provided
              only for compatibility with the old version of mal-
              loc and is not recommended.

     These values are defined in the <malloc.h> header file.

     Mallopt may be called repeatedly, but may not be called
     after the first small block is allocated.

     Mallinfo provides instrumentation describing space usage.
     It returns the structure:

     struct mallinfo  {
             int arena;        /* total space in arena */
             int ordblks;      /* number of ordinary blocks */
             int smblks;       /* number of small blocks */
             int hblkhd;       /* space in holding block headers */
             int hblks;        /* number of holding blocks */
             int usmblks;      /* space in small blocks in use */
             int fsmblks;      /* space in free small blocks */
             int uordblks;     /* space in ordinary blocks in use */
             int fordblks;     /* space in free ordinary blocks */
             int keepcost;     /* space penalty if keep option */
                               /* is used */
     }

     This structure is defined in the <malloc.h> header file.




Page 2                        CX/UX Programmer's Reference Manual

malloc(3X)                                             malloc(3X)



     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), malloc(3C).

DIAGNOSTICS
     malloc, realloc and calloc return a NULL pointer if there is
     not enough available memory.  When realloc returns NULL, the
     block pointed to by ptr is left intact.  If mallopt is
     called after any allocation or if cmd or value are invalid,
     non-zero is returned.  Otherwise, it returns zero.

WARNINGS
     This package usually uses more data space than malloc(3C).
     The code size is also bigger than malloc(3C).
     Note that unlike malloc(3C), this package does not preserve
     the contents of a block when it is freed, unless the M_KEEP
     option of mallopt is used.
     Undocumented features of malloc(3C) have not been dupli-
     cated.

































Page 3                        CX/UX Programmer's Reference Manual