Memory Allocation Library Functions umem_alloc(3MALLOC)
NAME
umem_alloc, umem_zalloc, umem_free, umem_nofail_callback -
fast, scalable memory allocationSYNOPSIS
cc [ flag ... ] file... -lumem [ library ... ]
#include
void *umem_alloc(size_t size, int flags);
void *umem_zalloc(size_t size, int flags);
void umem_free(void *buf, size_t size);
void umem_nofail_callback((int (*callback)(void));
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);
DESCRIPTION
The umem_alloc() function returns a pointer to a block of
size bytes suitably aligned for any variable type. The ini-
tial contents of memory allocated using umem_alloc() is
undefined. The flags argument determines the behavior ofumem_alloc() if it is unable to fulfill the request. The
flags argument can take the following values:UMEM_DEFAULT Return NULL on failure.
UMEM_NOFAIL Call an optional callback (set with
umem_nofail_callback()) on failure. The
callback takes no arguments and can finishSunOS 5.11 Last change: 24 Mar 2008 1
Memory Allocation Library Functions umem_alloc(3MALLOC)
by:o returning UMEM_CALLBACK_RETRY, in
which case the allocation will be retried. If the allocation fails, the callback will be invoked again. o returningUMEM_CALLBACK_EXIT(status), in
which case exit(2) is invoked with status as its argument. The exit() function is called only once. If multiple threads return from theUMEM_NOFAIL callback with
UMEM_CALLBACK_EXIT(status), one
will call exit() while the other blocks until exit() terminates the program.o invoking a context-changing func-
tion (setcontext(2)) or a non-local
jump (longjmp(3C) or siglongjmp(3C), or ending the current thread of control(thr_exit(3C) or pthread_exit(3C).
The application is responsible for any necessary cleanup. The state of libumem remains consistent. If no callback has been set or the callbackhas been set to NULL, umem_alloc(...,
UMEM_NOFAIL) behaves as though the callback
returned UMEM_CALLBACK_EXIT(255).
The libumem library can call callbacks fromany place that a UMEM_NOFAIL allocation is
issued. In multithreaded applications, call-
backs are expected to perform their own con-
currency management.The function call umem_alloc(0, flag) always returns NULL.
The function call umem_free(NULL, 0) is allowed.
The umem_zalloc() function has the same semantics as
umem_alloc(), but the block of memory is initialized to
zeros before it is returned.The umem_free() function frees blocks previously allocated
using umem_alloc() and umem_zalloc(). The buffer address and
SunOS 5.11 Last change: 24 Mar 2008 2
Memory Allocation Library Functions umem_alloc(3MALLOC)
size must exactly match the original allocation. Memory must not be returned piecemeal.The umem_nofail_callback() function sets the process-wide
UMEM_NOFAIL callback. See the description of UMEM_NOFAIL for
more information. The malloc(), calloc(), free(), memalign(), realloc(), and valloc() functions are as described in malloc(3C). Thelibumem library provides these functions for backwards-
compatibility with the standard functions. ENVIRONMENT VARIABLESSee umem_debug(3MALLOC) for environment variables that
effect the debugging features of the libumem library.UMEM_OPTIONS Contains a list of comma-separated options.
Unrecognized options are ignored. The options that are supported are: backend=sbrk Set the underlying function backend=mmap used to allocate memory. This option can be set to sbrk (the default) for ansbrk(2)-based source or mmap
for an mmap(2)-based source.
If set to a value that is not supported, sbrk will be used.EXAMPLES
Example 1 Using the umem_alloc() function.
#include
#include
...char *buf = umem_alloc(1024, UMEM_DEFAULT);
if (buf == NULL) { fprintf(stderr, "out of memory\n"); return (1); } /* cannot assume anything about buf's contents */ ...umem_free(buf, 1024);
...SunOS 5.11 Last change: 24 Mar 2008 3
Memory Allocation Library Functions umem_alloc(3MALLOC)
Example 2 Using the umem_zalloc() function
#include
#include
...char *buf = umem_zalloc(1024, UMEM_DEFAULT);
if (buf == NULL) { fprintf(stderr, "out of memory\n"); return (1); } /* buf contains zeros */ ...umem_free(buf, 1024);
...Example 3 Using UMEM_NOFAIL
#include
#include
#include
/* * Note that the allocation code below does not have to* check for umem_alloc() returning NULL
*/ intmy_failure_handler(void)
{ (void) fprintf(stderr, "out of memory\n");return (UMEM_CALLBACK_EXIT(255));
} ...umem_nofail_callback(my_failure_handler);
... int i; char *buf[100]; for (i = 0; i < 100; i++)buf[i] = umem_alloc(1024 * 1024, UMEM_NOFAIL);
... for (i = 0; i < 100; i++)umem_free(buf[i], 1024 * 1024);
...Example 4 Using UMEM_NOFAIL in a multithreaded application
#define _REENTRANT
#include
#include
SunOS 5.11 Last change: 24 Mar 2008 4
Memory Allocation Library Functions umem_alloc(3MALLOC)
#include
void *start_func(void *the_arg)
{int *info = (int *)the_arg;
char *buf = umem_alloc(1024 * 1024, UMEM_NOFAIL);
/* does not need to check for buf == NULL */ buf[0] = 0; ... /** if there were other UMEM_NOFAIL allocations,
* we would need to arrange for buf to be* umem_free()ed upon failure.
*/ ...umem_free(buf, 1024 * 1024);
return (the_arg);
} ... intmy_failure_handler(void)
{ /* terminate the current thread with status NULL */thr_exit(NULL);
} ...umem_nofail_callback(my_failure_handler);
...int my_arg;
thread_t tid;
void *status;(void) thr_create(NULL, NULL, start_func, &my_arg, 0,
NULL); ...while (thr_join(0, &tid, &status) != 0)
; if (status == NULL) {(void) fprintf(stderr, "thread %d ran out of memory\n",
tid); } ...ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 24 Mar 2008 5
Memory Allocation Library Functions umem_alloc(3MALLOC)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
| Standard | See below. ||_____________________________|_____________________________|
For malloc(), calloc(), free(), realloc(), and valloc(), see standards(5).SEE ALSO
exit(2), mmap(2), sbrk(2), bsdmalloc(3MALLOC), libumem(3LIB), longjmp(3C), malloc(3C), malloc(3MALLOC),mapmalloc(3MALLOC), pthread_exit(3C), thr_exit(3C),
umem_cache_create(3MALLOC), umem_debug(3MALLOC),
watchmalloc(3MALLOC), attributes(5), standards(5) Oracle Solaris Modular Debugger Guide WARNINGS Any of the following can cause undefined results:o Passing a pointer returned from umem_alloc() or
umem_zalloc() to free() or realloc().
o Passing a pointer returned from malloc(), calloc(),valloc(), memalign(), or realloc() to umem_free().
o Writing past the end of a buffer allocated usingumem_alloc() or umem_zalloc()
o Performing UMEM_NOFAIL allocations from an
atexit(3C) handler.If the UMEM_NOFAIL callback performs UMEM_NOFAIL alloca-
tions, infinite recursion can occur. NOTES The following list compares the features of the malloc(3C), bsdmalloc(3MALLOC), malloc(3MALLOC), mtmalloc(3MALLOC) , and the libumem functions. o The malloc(3C), bsdmalloc(3MALLOC), andmalloc(3MALLOC) functions have no support for con-
currency. The libumem and mtmalloc(3MALLOC)SunOS 5.11 Last change: 24 Mar 2008 6
Memory Allocation Library Functions umem_alloc(3MALLOC)
functions support concurrent allocations.o The bsdmalloc(3MALLOC) functions afford better per-
formance but are space-inefficient.
o The malloc(3MALLOC) functions are space-efficient
but have slower performance.o The standard, fully SCD-compliant malloc(3C) func-
tions are a trade-off between performance and
space-efficiency.
o The mtmalloc(3MALLOC) functions provide fast, con-
current malloc() implementations that are notspace-efficient.
o The libumem functions provide a fast, concurrent allocation implementation that in most cases ismore space-efficient than mtmalloc(3MALLOC).
SunOS 5.11 Last change: 24 Mar 2008 7