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
Page 1
USMALLOC(3P)USMALLOC(3P)
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 ALSOintro(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
