cc [ flag .\|.\|. ] file.\|.\|. -lumem [ library .\|.\|. ]
#include <umem.h>

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);

The umem_alloc() function returns a pointer to a block of size bytes suitably aligned for any variable type. The initial contents of memory allocated using umem_alloc() is undefined. The flags argument determines the behavior of umem_alloc() if it is unable to fulfill the request. The flags argument can take the following values: UMEM_DEFAULT

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 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). The libumem library provides these functions for backwards-compatibility with the standard functions.

See umem_debug(3MALLOC) for environment variables that effect the debugging features of the libumem library. UMEM_OPTIONS

Example 1 Using the umem_alloc() function.

#include <stdio.h>
#include <umem.h>
...
char *buf = umem_alloc(1024, UMEM_DEFAULT);

if (buf == NULL) {
 fprintf(stderr, "out of memory\en");
 return (1);
}
/* cannot assume anything about buf's contents */
...
umem_free(buf, 1024);
...

Example 2 Using the umem_zalloc() function

#include <stdio.h>
#include <umem.h>
...
char *buf = umem_zalloc(1024, UMEM_DEFAULT);

if (buf == NULL) {
 fprintf(stderr, "out of memory\en");
 return (1);
}
/* buf contains zeros */
...
umem_free(buf, 1024);
...

Example 3 Using UMEM_NOFAIL

#include <stdlib.h>
#include <stdio.h>
#include <umem.h>

/*
 * Note that the allocation code below does not have to
 * check for umem_alloc() returning NULL
 */
int
my_failure_handler(void)
{
 (void) fprintf(stderr, "out of memory\en");
 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 <thread.h>
#include <stdio.h>
#include <umem.h>

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);
}
...
int
my_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\en",
 tid);
}
...

See attributes(7) for descriptions of the following attributes:

For malloc(), calloc(), free(), realloc(), and valloc(), see standards(7).

exit (2), mmap (2), sbrk (2), longjmp (3C), malloc (3C), pthread_exit (3C), thr_exit (3C), libumem (3LIB), bsdmalloc (3MALLOC), malloc (3MALLOC), mapmalloc (3MALLOC), umem_cache_create (3MALLOC), umem_debug (3MALLOC), watchmalloc (3MALLOC), attributes (7), standards (7)

Modular Debugger Guide:

https://illumos.org/books/mdb/

Any of the following can cause undefined results:

If the UMEM_NOFAIL callback performs UMEM_NOFAIL allocations, infinite recursion can occur.

The following list compares the features of the malloc(3C), bsdmalloc(3MALLOC), malloc(3MALLOC), mtmalloc(3MALLOC) , and the libumem functions.