1umem_alloc(3MALLOC) Memory Allocation Library Functions umem_alloc(3MALLOC)
2
6 umem_alloc, umem_zalloc, umem_free, umem_nofail_callback - fast, scal‐
7 able memory allocation
8
10 cc [ flag ... ] file... -lumem [ library ... ]
11 #include <umem.h>
12 void *umem_alloc(size_t size, int flags);
14 void *umem_zalloc(size_t size, int flags);
17 void umem_free(void *buf, size_t size);
20 void umem_nofail_callback((int (*callback)(void));
23 void *malloc(size_t size);
26 void *calloc(size_t nelem, size_t elsize);
29 void free(void *ptr);
32 void *memalign(size_t alignment, size_t size);
35 void *realloc(void *ptr, size_t size);
38 void *valloc(size_t size);
41
44 The umem_alloc() function returns a pointer to a block of size bytes
45 suitably aligned for any variable type. The initial contents of memory
46 allocated using umem_alloc() is undefined. The flags argument deter‐
47 mines the behavior of umem_alloc() if it is unable to fulfill the
48 request. The flags argument can take the following values:
49 UMEM_DEFAULT Return NULL on failure.
51 UMEM_NOFAIL Call an optional callback (set with umem_nofail_call‐
54 back()) on failure. The callback takes no arguments and
55 can finish by:
56 o returning UMEM_CALLBACK_RETRY, in which case
58 the allocation will be retried. If the
59 allocation fails, the callback will be
60 invoked again.
61 o returning UMEM_CALLBACK_EXIT(status), in
63 which case exit(2) is invoked with status as
64 its argument. The exit() function is called
65 only once. If multiple threads return from
66 the UMEM_NOFAIL callback with UMEM_CALL‐
67 BACK_EXIT(status), one will call exit()
68 while the other blocks until exit() termi‐
69 nates the program.
70 o invoking a context-changing function (set‐
72 context(2)) or a non-local jump (longjmp(3C)
73 or siglongjmp(3C), or ending the current
74 thread of control (thr_exit(3C) or
75 pthread_exit(3C). The application is respon‐
76 sible for any necessary cleanup. The state
77 of libumem remains consistent.
78 If no callback has been set or the callback has been
79 set to NULL, umem_alloc(..., UMEM_NOFAIL) behaves as
80 though the callback returned UMEM_CALLBACK_EXIT(255).
81 The libumem library can call callbacks from any place
83 that a UMEM_NOFAIL allocation is issued. In multi‐
84 threaded applications, callbacks are expected to per‐
85 form their own concurrency management.
86 The function call umem_alloc(0, flag) always returns NULL. The function
90 call umem_free(NULL, 0) is allowed.
91 The umem_zalloc() function has the same semantics as umem_alloc(), but
94 the block of memory is initialized to zeros before it is returned.
95 The umem_free() function frees blocks previously allocated using
98 umem_alloc() and umem_zalloc(). The buffer address and size must
99 exactly match the original allocation. Memory must not be returned
100 piecemeal.
101 The umem_nofail_callback() function sets the process-wide UMEM_NOFAIL
104 callback. See the description of UMEM_NOFAIL for more information.
105 The malloc(), calloc(), free(), memalign(), realloc(), and valloc()
108 functions are as described in malloc(3C). The libumem library provides
109 these functions for backwards-compatibility with the standard func‐
110 tions.
111
113 See umem_debug(3MALLOC) for environment variables that effect the
114 debugging features of the libumem library.
115 UMEM_OPTIONS Contains a list of comma-separated options. Unrecog‐
117 nized options are ignored. The options that are sup‐
118 ported are:
119 backend=sbrk Set the underlying function used to
121 backend=mmap allocate memory. This option can be set
122 to sbrk (the default) for an
123 sbrk(2)-based source or mmap for an
124 mmap(2)-based source. If set to a value
125 that is not supported, sbrk will be
126 used.
127
131 Example 1 Using the umem_alloc() function.
132 #include <stdio.h>
134 #include <umem.h>
135 ...
136 char *buf = umem_alloc(1024, UMEM_DEFAULT);
137 if (buf == NULL) {
139 fprintf(stderr, "out of memory\n");
140 return (1);
141 }
142 /* cannot assume anything about buf's contents */
143 ...
144 umem_free(buf, 1024);
145 ...
146 Example 2 Using the umem_zalloc() function
149 #include <stdio.h>
151 #include <umem.h>
152 ...
153 char *buf = umem_zalloc(1024, UMEM_DEFAULT);
154 if (buf == NULL) {
156 fprintf(stderr, "out of memory\n");
157 return (1);
158 }
159 /* buf contains zeros */
160 ...
161 umem_free(buf, 1024);
162 ...
163 Example 3 Using UMEM_NOFAIL
166 #include <stdlib.h>
168 #include <stdio.h>
169 #include <umem.h>
170 /*
172 * Note that the allocation code below does not have to
173 * check for umem_alloc() returning NULL
174 */
175 int
176 my_failure_handler(void)
177 {
178 (void) fprintf(stderr, "out of memory\n");
179 return (UMEM_CALLBACK_EXIT(255));
180 }
181 ...
182 umem_nofail_callback(my_failure_handler);
183 ...
184 int i;
185 char *buf[100];
186 for (i = 0; i < 100; i++)
188 buf[i] = umem_alloc(1024 * 1024, UMEM_NOFAIL);
189 ...
190 for (i = 0; i < 100; i++)
191 umem_free(buf[i], 1024 * 1024);
192 ...
193 Example 4 Using UMEM_NOFAIL in a multithreaded application
196 #define _REENTRANT
198 #include <thread.h>
199 #include <stdio.h>
200 #include <umem.h>
201 void *
203 start_func(void *the_arg)
204 {
205 int *info = (int *)the_arg;
206 char *buf = umem_alloc(1024 * 1024, UMEM_NOFAIL);
207 /* does not need to check for buf == NULL */
209 buf[0] = 0;
210 ...
211 /*
212 * if there were other UMEM_NOFAIL allocations,
213 * we would need to arrange for buf to be
214 * umem_free()ed upon failure.
215 */
216 ...
217 umem_free(buf, 1024 * 1024);
218 return (the_arg);
219 }
220 ...
221 int
222 my_failure_handler(void)
223 {
224 /* terminate the current thread with status NULL */
225 thr_exit(NULL);
226 }
227 ...
228 umem_nofail_callback(my_failure_handler);
229 ...
230 int my_arg;
231 thread_t tid;
233 void *status;
234 (void) thr_create(NULL, NULL, start_func, &my_arg, 0,
236 NULL);
237 ...
238 while (thr_join(0, &tid, &status) != 0)
239 ;
240 if (status == NULL) {
242 (void) fprintf(stderr, "thread %d ran out of memory\n",
243 tid);
244 }
245 ...
246
249 See attributes(5) for descriptions of the following attributes:
250 ┌─────────────────────────────┬─────────────────────────────┐
255 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
256 ├─────────────────────────────┼─────────────────────────────┤
257 │Interface Stability │Committed │
258 ├─────────────────────────────┼─────────────────────────────┤
259 │MT-Level │MT-Safe │
260 ├─────────────────────────────┼─────────────────────────────┤
261 │Standard │See below. │
262 └─────────────────────────────┴─────────────────────────────┘
263 For malloc(), calloc(), free(), realloc(), and valloc(), see stan‐
266 dards(5).
267
269 exit(2), mmap(2), sbrk(2), bsdmalloc(3MALLOC), libumem(3LIB),
270 longjmp(3C), malloc(3C), malloc(3MALLOC), mapmalloc(3MALLOC),
271 pthread_exit(3C), thr_exit(3C), umem_cache_create(3MALLOC),
272 umem_debug(3MALLOC), watchmalloc(3MALLOC), attributes(5), standards(5)
273 Solaris Modular Debugger Guide
276
278 Any of the following can cause undefined results:
279 o Passing a pointer returned from umem_alloc() or umem_zal‐
281 loc() to free() or realloc().
282 o Passing a pointer returned from malloc(), calloc(), val‐
284 loc(), memalign(), or realloc() to umem_free().
285 o Writing past the end of a buffer allocated using
287 umem_alloc() or umem_zalloc()
288 o Performing UMEM_NOFAIL allocations from an atexit(3C) han‐
290 dler.
291 If the UMEM_NOFAIL callback performs UMEM_NOFAIL allocations, infinite
294 recursion can occur.
295
297 The following list compares the features of the malloc(3C), bsdmal‐
298 loc(3MALLOC), malloc(3MALLOC), mtmalloc(3MALLOC) , and the libumem
299 functions.
300 o The malloc(3C), bsdmalloc(3MALLOC), and malloc(3MALLOC)
302 functions have no support for concurrency. The libumem and
303 mtmalloc(3MALLOC) functions support concurrent allocations.
304 o The bsdmalloc(3MALLOC) functions afford better performance
306 but are space-inefficient.
307 o The malloc(3MALLOC) functions are space-efficient but have
309 slower performance.
310 o The standard, fully SCD-compliant malloc(3C) functions are a
312 trade-off between performance and space-efficiency.
313 o The mtmalloc(3MALLOC) functions provide fast, concurrent
315 malloc() implementations that are not space-efficient.
316 o The libumem functions provide a fast, concurrent allocation
318 implementation that in most cases is more space-efficient
319 than mtmalloc(3MALLOC).
320SunOS 5.11 24 Mar 2008 umem_alloc(3MALLOC)