1umem_alloc(3MALLOC)   Memory Allocation Library Functions  umem_alloc(3MALLOC)
2
3
4

NAME

6       umem_alloc,  umem_zalloc, umem_free, umem_nofail_callback - fast, scal‐
7       able memory allocation
8

SYNOPSIS

10       cc [ flag ... ] file... -lumem [ library ... ]
11       #include <umem.h>
12
13       void *umem_alloc(size_t size, int  flags);
14
15
16       void *umem_zalloc(size_t size, int  flags);
17
18
19       void umem_free(void *buf, size_t size);
20
21
22       void umem_nofail_callback((int (*callback)(void));
23
24
25       void *malloc(size_t size);
26
27
28       void *calloc(size_t nelem, size_t elsize);
29
30
31       void free(void *ptr);
32
33
34       void *memalign(size_t alignment, size_t size);
35
36
37       void *realloc(void *ptr, size_t size);
38
39
40       void *valloc(size_t size);
41
42

DESCRIPTION

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
50       UMEM_DEFAULT    Return NULL on failure.
51
52
53       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
57                           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
62                           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
71                           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
82                       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
87
88
89       The function call umem_alloc(0, flag) always returns NULL. The function
90       call umem_free(NULL, 0) is allowed.
91
92
93       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
96
97       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
102
103       The umem_nofail_callback() function sets the  process-wide  UMEM_NOFAIL
104       callback. See the description of UMEM_NOFAIL for more information.
105
106
107       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

ENVIRONMENT VARIABLES

113       See umem_debug(3MALLOC)  for  environment  variables  that  effect  the
114       debugging features of the libumem library.
115
116       UMEM_OPTIONS    Contains  a  list of comma-separated options.  Unrecog‐
117                       nized options are ignored. The options  that  are  sup‐
118                       ported are:
119
120                       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
128
129

EXAMPLES

131       Example 1 Using the umem_alloc() function.
132
133         #include <stdio.h>
134         #include <umem.h>
135         ...
136         char *buf = umem_alloc(1024, UMEM_DEFAULT);
137
138         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
147
148       Example 2 Using the umem_zalloc() function
149
150         #include <stdio.h>
151         #include <umem.h>
152         ...
153         char *buf = umem_zalloc(1024, UMEM_DEFAULT);
154
155         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
164
165       Example 3 Using UMEM_NOFAIL
166
167         #include <stdlib.h>
168         #include <stdio.h>
169         #include <umem.h>
170
171         /*
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
187         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
194
195       Example 4 Using UMEM_NOFAIL in a multithreaded application
196
197         #define _REENTRANT
198         #include <thread.h>
199         #include <stdio.h>
200         #include <umem.h>
201
202         void *
203         start_func(void *the_arg)
204         {
205                   int *info = (int *)the_arg;
206                   char *buf = umem_alloc(1024 * 1024, UMEM_NOFAIL);
207
208                   /* 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
232         thread_t tid;
233         void *status;
234
235         (void) thr_create(NULL, NULL, start_func, &my_arg, 0,
236             NULL);
237         ...
238         while (thr_join(0, &tid, &status) != 0)
239                   ;
240
241         if (status == NULL) {
242             (void) fprintf(stderr, "thread %d ran out of memory\n",
243                      tid);
244         }
245         ...
246
247

ATTRIBUTES

249       See attributes(5) for descriptions of the following attributes:
250
251
252
253
254       ┌─────────────────────────────┬─────────────────────────────┐
255       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
256       ├─────────────────────────────┼─────────────────────────────┤
257       │Interface Stability          │Committed                    │
258       ├─────────────────────────────┼─────────────────────────────┤
259       │MT-Level                     │MT-Safe                      │
260       ├─────────────────────────────┼─────────────────────────────┤
261       │Standard                     │See below.                   │
262       └─────────────────────────────┴─────────────────────────────┘
263
264
265       For  malloc(),  calloc(),  free(),  realloc(),  and valloc(), see stan‐
266       dards(5).
267

SEE ALSO

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
274
275       Solaris Modular Debugger Guide
276

WARNINGS

278       Any of the following can cause undefined results:
279
280           o      Passing  a  pointer  returned from umem_alloc() or umem_zal‐
281                  loc() to free() or realloc().
282
283           o      Passing a pointer returned  from  malloc(),  calloc(),  val‐
284                  loc(), memalign(), or realloc() to umem_free().
285
286           o      Writing   past   the   end   of  a  buffer  allocated  using
287                  umem_alloc() or umem_zalloc()
288
289           o      Performing UMEM_NOFAIL allocations from an  atexit(3C)  han‐
290                  dler.
291
292
293       If  the UMEM_NOFAIL callback performs UMEM_NOFAIL allocations, infinite
294       recursion can occur.
295

NOTES

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
301           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
305           o      The bsdmalloc(3MALLOC) functions afford  better  performance
306                  but are space-inefficient.
307
308           o      The  malloc(3MALLOC)  functions are space-efficient but have
309                  slower performance.
310
311           o      The standard, fully SCD-compliant malloc(3C) functions are a
312                  trade-off between performance and space-efficiency.
313
314           o      The  mtmalloc(3MALLOC)  functions  provide  fast, concurrent
315                  malloc() implementations that are not space-efficient.
316
317           o      The libumem functions provide a fast, concurrent  allocation
318                  implementation  that  in  most cases is more space-efficient
319                  than mtmalloc(3MALLOC).
320
321
322
323SunOS 5.11                        24 Mar 2008              umem_alloc(3MALLOC)
Impressum