MALLOC(3X-SysV)     RISC/os Reference Manual      MALLOC(3X-SysV)



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

SYNOPSIS
     #include <bsd/sys/types.h>
     #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.



                         Printed 1/15/91                   Page 1

MALLOC(3X-SysV)     RISC/os Reference Manual      MALLOC(3X-SysV)



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

     M_MXFAST       Set maxfast to value.  The algorithm allo-
                    cates 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
                    malloc, realloc, or calloc.  This option is
                    provided only for compatibility with the old
                    version of malloc 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                  Printed 1/15/91

MALLOC(3X-SysV)     RISC/os Reference Manual      MALLOC(3X-SysV)



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

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.






























                         Printed 1/15/91                   Page 3