svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
umem_alloc(3malloc)
umem_alloc(3MALLOC) Memory Allocation Library Functions umem_alloc(3MALLOC)
NAME
umem_alloc, umem_zalloc, umem_free, umem_nofail_callback - fast, scal‐
able memory allocation
SYNOPSIS
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 *memalign(size_t alignment, size_t size);
void *realloc(void *ptr, size_t size);
void *valloc(size_t size);
size_t malloc_usable_size(void *ptr);
void free(void *ptr);
DESCRIPTION
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 deter‐
mines the behavior of umem_alloc() if it is unable to fulfill the re‐
quest. The flags argument can take the following values:
UMEM_DEFAULT Return NULL on failure.
UMEM_NOFAIL Call an optional callback (set with umem_nofail_call‐
back()) on failure. The callback takes no arguments and
can finish by:
o returning UMEM_CALLBACK_RETRY, in which case
the allocation will be retried. If the allo‐
cation fails, the callback will be invoked
again.
o returning UMEM_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
the UMEM_NOFAIL callback with UMEM_CALL‐
BACK_EXIT(status), one will call exit()
while the other blocks until exit() termi‐
nates the program.
o invoking a context-changing function (set‐
context(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 respon‐
sible for any necessary cleanup. The state
of libumem remains consistent.
If no callback has been set or the callback has been
set to NULL, umem_alloc(..., UMEM_NOFAIL) behaves as
though the callback returned UMEM_CALLBACK_EXIT(255).
The libumem library can call callbacks from any place
that a UMEM_NOFAIL allocation is issued. In multi‐
threaded applications, callbacks are expected to per‐
form their own concurrency 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 size must ex‐
actly match the original allocation. Memory must not be returned piece‐
meal.
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(), malloc_usable_size(), memalign(), real‐
loc(), and valloc() functions are as described in malloc(3C), including
support for the ADIHEAP security extension. The libumem library pro‐
vides these functions for backward compatibility with the standard
functions.
Memory allocated by these functions may be on pages with the PROT_EXEC
access protections disabled to block execution of machine instructions,
depending on the system settings for NXHEAP in sxadm(8) and any -z
sx=nxheap options that were passed to ld(1) when linking the applica‐
tion, even when using backend=mmap. These settings may be overridden
for individual pages by calling mprotect(2).
ENVIRONMENT VARIABLES
See umem_debug(3MALLOC) for environment variables that effect the de‐
bugging features of the libumem library.
UMEM_OPTIONS Contains a list of comma-separated options. Unrecog‐
nized options are ignored. The options that are sup‐
ported are:
backend=sbrk Set the underlying function used to al‐
backend=mmap locate memory. This option can be set
to sbrk (the default) for an
sbrk(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 <stdio.h>
#include <umem.h>
...
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);
...
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\n");
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\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
#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\n",
tid);
}
...
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelMT-Safe _ Stan‐
dardSee below.
For malloc(), calloc(), free(), realloc(), and valloc(), see malloc(3C)
for applicable standards.
USAGE
Comparative features of the various allocation libraries can be found
in the malloc(3C) manual page.
SEE ALSO
exit(2), mmap(2), mprotect(2), sbrk(2), longjmp(3C), malloc(3C),
pthread_exit(3C), thr_exit(3C), libumem(3LIB), umem_cache_create(3MAL‐
LOC), umem_debug(3MALLOC), adi(7), attributes(7), standards(7), sx‐
adm(8)
Oracle Solaris Modular Debugger Guide
WARNINGS
Any of the following can cause undefined results:
o Passing a pointer returned from umem_alloc() or umem_zal‐
loc() to free(), malloc_usable_size(), or realloc().
o Passing a pointer returned from malloc(), calloc(), val‐
loc(), memalign(), realloc(), or reallocarray() to
umem_free().
o Writing past the end of a buffer allocated using umem_al‐
loc() or umem_zalloc().
o Performing UMEM_NOFAIL allocations from an atexit(3C) han‐
dler.
If the UMEM_NOFAIL callback performs UMEM_NOFAIL allocations, infinite
recursion can occur.
Oracle Solaris 11.4 11 May 2021 umem_alloc(3MALLOC)