USMALLOC(3P)                                                      USMALLOC(3P)


NAME
     usmalloc, usfree, usrealloc, uscalloc, usmallopt, usmallinfo, - shared
     arena memory allocator

C SYNOPSIS
     #include <ulocks.h>
     #include <malloc.h>

     void *usmalloc (size_t size, usptr_t *handle);

     void usfree (void *ptr, usptr_t *handle);

     void *usrealloc (void *ptr, size_t size, usptr_t *handle);

     void *uscalloc (size_t nelem, size_t elsize, usptr_t *handle);

     int usmallopt (int cmd, int value, usptr_t *handle);

     struct mallinfo usmallinfo (usptr_t *handle);

     size_t usmallocblksize (void *ptr, usptr_t *handle);

     void *usrecalloc (void *ptr, size_t nelem, size_t elsize,
                    usptr_t *handle);

     void *usmemalign (size_t align, size_t size, usptr_t *handle);

DESCRIPTION
     These routines provide a simple general-purpose memory allocation package
     that allows the user to allocate from a shared arena (see usinit(3P)).
     All these functions are MP safe, multiple threads/processes may access
     them simultaneously and are guaranteed correct behavior.

     More than one call can be made to usinit(3P) to set up separate malloc
     arenas.  The file name passed to usinit(3P) is used as a key to allow
     shared arenas to be created for use amongst unrelated processes.  Once
     the arena is set up, calls to usmalloc will attempt to allocate space
     from the arena.  If the arena gets full, NULL is returned.  Note that
     this malloc arena is also used by other us* calls (such as usnewlock and
     usnewsema ).

     The argument to usfree is a pointer to a block previously allocated by
     usmalloc; after usfree is performed this space is made available for
     further allocation.

     Undefined results will occur if the space assigned by usmalloc is overrun
     or if some random number is handed to usfree.  It is always permitted to
     pass NULL to usfree.

     usrealloc 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 usrealloc will ask
     usmalloc to enlarge the arena by size bytes and will then move the data
     to the new space.  In the special case of a null ptr, usrealloc
     degenerates to usmalloc.  A zero size causes the passed block to be
     freed.

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

     usrecalloc combines usrealloc and uscalloc.  If the size of the block
     increases, any new bytes are initialized to zero.  Note that for this to
     work properly, all allocations of a given pointer must go through
     usrecalloc.  If the original pointer was allocated with either usmalloc
     or usrealloc some new bytes may not be set properly to zero.

     usmemalign 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 align.  Note: the value
     of align must be a power of two, and must be greater than or equal to the
     size of a word, or, for 64 bit objects, the size of a doubleword.

     usmallocblksize returns the actual size of the block pointed to by ptr.
     The returned size may be greater than the original requested size due to
     padding and alignment.

     usmallopt provides for control over the allocation algorithm.  See
     amalloc(3P) for details on the allowable options.

     usmallinfo provides instrumentation describing space usage.  See
     amalloc(3P) for details on the returned information.

SEE ALSO
     intro(3), usinit(3P), usconfig(3P), amalloc(3P), malloc(3X).

DIAGNOSTICS
     usmalloc, uscalloc, usrecalloc, and usrealloc 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.  If usmallopt is
     called after any allocation (for most cmd arguments) or if cmd or value
     are invalid, non-zero is returned.  Otherwise, it returns zero.


                                                                        Page 2