root/trunk/umem_alloc.3

Revision 30, 10.8 kB (checked in by wez, 7 years ago)

add man pages from opensolaris

Line 
1 '\" te
2 .\" CDDL HEADER START
3 .\"
4 .\" The contents of this file are subject to the terms of the
5 .\" Common Development and Distribution License (the "License"). 
6 .\" You may not use this file except in compliance with the License.
7 .\"
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or http://www.opensolaris.org/os/licensing.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
12 .\"
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 .\"
19 .\" CDDL HEADER END
20 .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
21 .TH umem_alloc 3MALLOC "26 Aug 2002" "SunOS 5.11" "Memory Allocation Library Functions"
22 .SH NAME
23 umem_alloc, umem_zalloc, umem_free, umem_nofail_callback \- fast, scalable memory allocation
24 .SH SYNOPSIS
25 .LP
26 .nf
27 cc [ \fIflag \&.\|.\|.\fR ] \fIfile\fR\&.\|.\|. \fB-lumem\fR [ \fIlibrary \&.\|.\|.\fR ]
28 #include <umem.h>
29
30 \fBvoid *\fR\fBumem_alloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR  \fIflags\fR);
31 .fi
32 .LP
33 .nf
34 \fBvoid *\fR\fBumem_zalloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR  \fIflags\fR);
35 .fi
36 .LP
37 .nf
38 \fBvoid\fR \fBumem_free\fR(\fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
39 .fi
40 .LP
41 .nf
42 \fBvoid\fR \fBumem_nofail_callback\fR(\fB(int (*\fR\fIcallback\fR)(void));
43 .fi
44 .LP
45 .nf
46 \fBvoid *\fR\fBmalloc\fR(\fBsize_t\fR \fIsize\fR);
47 .fi
48 .LP
49 .nf
50 \fBvoid *\fR\fBcalloc\fR(\fBsize_t\fR \fInelem\fR, \fBsize_t\fR \fIelsize\fR);
51 .fi
52 .LP
53 .nf
54 \fBvoid\fR \fBfree\fR(\fBvoid *\fR\fIptr\fR);
55 .fi
56 .LP
57 .nf
58 \fBvoid *\fR\fBmemalign\fR(\fBsize_t\fR \fIalignment\fR, \fBsize_t\fR \fIsize\fR);
59 .fi
60 .LP
61 .nf
62 \fBvoid *\fR\fBrealloc\fR(\fBvoid *\fR\fIptr\fR, \fBsize_t\fR \fIsize\fR);
63 .fi
64 .LP
65 .nf
66 \fBvoid *\fR\fBvalloc\fR(\fBsize_t\fR \fIsize\fR);
67 .fi
68
69 .SH DESCRIPTION
70
71 .LP
72 The \fBumem_alloc()\fR function returns a pointer to a block of \fIsize\fR bytes suitably aligned for any variable type. The initial contents of memory allocated using \fBumem_alloc()\fR is undefined. The \fIflags\fR argument determines
73 the behavior of \fBumem_alloc()\fR if it is unable to fulfill the request. The \fIflags\fR argument can take the following values:
74 .sp
75
76 .sp
77 .ne 2
78 .mk
79 .na
80 \fB\fBUMEM_DEFAULT\fR\fR
81 .ad
82 .RS 14n
83 .rt 
84 Return \fINULL\fR on failure.
85 .sp
86
87 .RE
88
89 .sp
90 .ne 2
91 .mk
92 .na
93 \fB\fBUMEM_NOFAIL\fR\fR
94 .ad
95 .RS 14n
96 .rt 
97 Call an optional \fIcallback\fR (set with \fBumem_nofail_callback()\fR) on failure. The \fIcallback\fR takes no arguments and can finish by:
98 .sp
99
100 .sp
101 .RS +4
102 .TP
103 .ie t \(bu
104 .el o
105 returning \fBUMEM_CALLBACK_RETRY\fR, in which case the allocation will be retried.  If the allocation fails, the callback will be invoked again.
106 .sp
107
108 .RE
109
110 .sp
111 .RS +4
112 .TP
113 .ie t \(bu
114 .el o
115 returning \fBUMEM_CALLBACK_EXIT\fR(\fIstatus\fR), in which case
116 \fBexit\fR(2) is invoked with \fIstatus\fR
117 as its argument. The \fBexit()\fR function is called only once. If multiple threads return from the \fBUMEM_NOFAIL\fR callback with \fBUMEM_CALLBACK_EXIT\fR(\fIstatus\fR), one will call \fBexit()\fR while the other blocks until \fBexit()\fR terminates the program.
118 .sp
119
120 .RE
121
122 .sp
123 .RS +4
124 .TP
125 .ie t \(bu
126 .el o
127 invoking a context-changing function (
128 \fBsetcontext\fR(2)) or a non-local jump (
129 \fBlongjmp\fR(3C) or
130 \fBsiglongjmp\fR(3C), or ending the current thread of control (
131 \fBthr_exit\fR(3C) or
132 \fBpthread_exit\fR(3C). The application is responsible for any necessary cleanup. The state of \fBlibumem\fR remains consistent.
133 .sp
134
135 .RE
136
137 If no callback has been set or the callback has been set to \fINULL\fR, \fBumem_alloc\fR(..., \fBUMEM_NOFAIL\fR) behaves as though the callback returned \fBUMEM_CALLBACK_EXIT\fR(255).
138 .sp
139
140 .sp
141 The \fBlibumem\fR library can call callbacks from any place that a \fBUMEM_NOFAIL\fR allocation is issued. In multithreaded applications, callbacks are expected to perform their own concurrency management.
142 .sp
143
144 .RE
145
146 .LP
147 The function call \fBumem_alloc\fR(0, \fIflag\fR) always returns \fINULL\fR. The function call \fBumem_free\fR(\fINULL\fR, 0) is allowed.
148 .sp
149
150 .LP
151 The \fBumem_zalloc()\fR function has the same semantics as \fBumem_alloc()\fR, but the block of memory is initialized to zeros before it is returned.
152 .sp
153
154 .LP
155 The \fBumem_free()\fR function frees blocks previously allocated using \fBumem_alloc()\fR and \fBumem_zalloc()\fR. The buffer address and size must exactly match the original allocation. Memory must not be returned piecemeal.
156 .sp
157
158 .LP
159 The \fBumem_nofail_callback()\fR function sets the process-wide UMEM_NOFAIL callback. See the description of UMEM_NOFAIL for more information.
160 .sp
161
162 .LP
163 The \fBmalloc()\fR, \fBcalloc()\fR, \fBfree()\fR, \fBmemalign()\fR, \fBrealloc()\fR, and \fBvalloc()\fR functions are are as described in
164 \fBmalloc\fR(3C). The \fBlibumem\fR library provides these functions for backwards-compatibility with the standard functions.
165 .sp
166
167 .SH ENVIRONMENT VARIABLES
168
169 .LP
170 See
171 \fBumem_debug\fR(3MALLOC) for environment variables that effect the debugging features of the \fBlibumem\fR library.
172 .sp
173
174 .sp
175 .ne 2
176 .mk
177 .na
178 \fBUMEM_OPTIONS\fR
179 .ad
180 .RS 14n
181 .rt 
182 Contains a list of comma-separated options.  Unrecognized options are ignored. The options that are supported are:
183 .sp
184
185 .sp
186 .ne 2
187 .mk
188 .na
189 \fB\fBbackend\fR=\fBsbrk\fR\fR
190 .ad
191 .br
192 .na
193 \fB\fBbackend\fR=\fBmmap\fR\fR
194 .ad
195 .RS 14n
196 .rt 
197 Set the underlying function used to allocate memory. This option can be set to \fBsbrk\fR (the default) for an
198 \fBsbrk\fR(2)-based source or \fBmmap\fR for an
199 \fBmmap\fR(2)-based
200 source. If set to a value that is not supported, \fBsbrk\fR will be used.
201 .sp
202
203 .RE
204
205 .RE
206
207 .SH EXAMPLES
208 .LP
209 \fBExample 1 \fRUsing the \fBumem_alloc()\fR function.
210
211 .LP
212 .in +2
213 .nf
214 #include <stdio.h>
215 #include <umem.h>
216 \&...
217 char *buf = umem_alloc(1024, UMEM_DEFAULT);
218
219 if (buf == NULL) {
220     fprintf(stderr, "out of memory\en");
221          return (1);
222 }
223 /* cannot assume anything about buf's contents */
224 \&...
225 umem_free(buf, 1024);
226 \&...
227 .fi
228 .in -2
229 .LP
230 \fBExample 2 \fRUsing the \fBumem_zalloc()\fR function
231
232 .LP
233 .in +2
234 .nf
235 #include <stdio.h>
236 #include <umem.h>
237 \&...
238 char *buf = umem_zalloc(1024, UMEM_DEFAULT);
239
240 if (buf == NULL) {
241    fprintf(stderr, "out of memory\en");
242         return (1);
243 }
244 /* buf contains zeros */
245 \&...
246 umem_free(buf, 1024);
247 \&...
248 .fi
249 .in -2
250 .LP
251 \fBExample 3 \fRUsing UMEM_NOFAIL
252
253 .LP
254 .in +2
255 .nf
256 #include <stdlib.h>
257 #include <stdio.h>
258 #include <umem.h>
259
260 /*
261 * Note that the allocation code below does not have to
262 * check for umem_alloc() returning NULL
263 */
264 int
265 my_failure_handler(void)
266 {
267         (void) fprintf(stderr, "out of memory\en");
268         return (UMEM_CALLBACK_EXIT(255));
269 }
270 \&...
271 umem_nofail_callback(my_failure_handler);
272 \&...
273 int i;
274 char *buf[100];
275
276 for (i = 0; i < 100; i++)
277         buf[i] = umem_alloc(1024 * 1024, UMEM_NOFAIL);
278 \&...
279 for (i = 0; i < 100; i++)
280    umem_free(buf[i], 1024 * 1024);
281 \&...
282 .fi
283 .in -2
284 .LP
285 \fBExample 4 \fRUsing UMEM_NOFAIL in a multithreaded application
286
287 .LP
288 .in +2
289 .nf
290 #define _REENTRANT
291 #include <thread.h>
292 #include <stdio.h>
293 #include <umem.h>
294
295 void *
296 start_func(void *the_arg)
297 {
298          int *info = (int *)the_arg;
299          char *buf = umem_alloc(1024 * 1024, UMEM_NOFAIL);
300
301          /* does not need to check for buf == NULL */
302          buf[0] = 0;
303          ...
304          /*
305           * if there were other UMEM_NOFAIL allocations,
306           * we would need to arrange for buf to be
307           * umem_free()ed upon failure.
308           */
309          ...
310          umem_free(buf, 1024 * 1024);
311          return (the_arg);
312 }
313 \&...
314 int
315 my_failure_handler(void)
316 {
317         /* terminate the current thread with status NULL */
318         thr_exit(NULL);
319 }
320 \&...
321 umem_nofail_callback(my_failure_handler);
322 \&...
323 int my_arg;
324
325 thread_t tid;
326 void *status;
327
328 (void) thr_create(NULL, NULL, start_func, &my_arg, 0,
329    NULL);
330 \&...
331 while (thr_join(0, &tid, &status) != 0)
332          ;
333
334 if (status == NULL) {
335    (void) fprintf(stderr, "thread %d ran out of memory\en",
336             tid);
337 }
338 \&...
339 .fi
340 .in -2
341
342 .SH ATTRIBUTES
343
344 .LP
345 See
346 \fBattributes\fR(5) for descriptions of the following attributes:
347 .sp
348
349 .LP
350
351 .sp
352 .TS
353 tab() box;
354 cw(2.75i) |cw(2.75i)
355 lw(2.75i) |lw(2.75i)
356 .
357 ATTRIBUTE TYPEATTRIBUTE VALUE
358 _
359 Interface StabilitySee below.
360 _
361 MT-LevelMT-Safe
362 .TE
363
364 .LP
365 The \fBmalloc()\fR, \fBcalloc()\fR, \fBfree()\fR, \fBrealloc()\fR, and \fBvalloc()\fR functions are Standard. The \fBmemalign()\fR function is Stable. The \fBumem_alloc()\fR, \fBumem_zalloc()\fR, \fBumem_free()\fR, and \fBumem_nofail_callback()\fR functions are Evolving.
366 .sp
367
368 .SH SEE ALSO
369
370 .LP
371
372 \fBexit\fR(2),
373 \fBmmap\fR(2),
374 \fBsbrk\fR(2),
375 \fBbsdmalloc\fR(3MALLOC),
376 \fBlibumem\fR(3LIB),
377 \fBlongjmp\fR(3C),
378 \fBmalloc\fR(3C),
379 \fBmalloc\fR(3MALLOC),
380 \fBmapmalloc\fR(3MALLOC),
381 \fBpthread_exit\fR(3C),
382 \fBthr_exit\fR(3C),
383 \fBumem_cache_create\fR(3MALLOC),
384 \fBumem_debug\fR(3MALLOC),
385 \fBwatchmalloc\fR(3MALLOC),
386 \fBattributes\fR(5),
387 \fBstandards\fR(5)
388 .sp
389
390 .LP
391
392 .sp
393
394 .SH WARNINGS
395
396 .LP
397 Any of the following can cause undefined results:
398 .sp
399
400 .sp
401 .RS +4
402 .TP
403 .ie t \(bu
404 .el o
405 Passing a pointer returned from \fBumem_alloc()\fR or \fBumem_zalloc()\fR to \fBfree()\fR or \fBrealloc()\fR.
406 .sp
407
408 .RE
409
410 .sp
411 .RS +4
412 .TP
413 .ie t \(bu
414 .el o
415 Passing a pointer returned from \fBmalloc()\fR, \fBcalloc()\fR, \fBvalloc()\fR, \fBmemalign()\fR, or \fBrealloc()\fR to \fBumem_free()\fR.
416 .sp
417
418 .RE
419
420 .sp
421 .RS +4
422 .TP
423 .ie t \(bu
424 .el o
425 Writing past the end of a buffer allocated using \fBumem_alloc()\fR or \fBumem_zalloc()\fR
426 .sp
427
428 .RE
429
430 .sp
431 .RS +4
432 .TP
433 .ie t \(bu
434 .el o
435 Performing \fBUMEM_NOFAIL\fR allocations from an
436 \fBatexit\fR(3C) handler.
437 .sp
438
439 .RE
440
441 .LP
442 If the \fBUMEM_NOFAIL\fR callback performs \fBUMEM_NOFAIL\fR allocations, infinite recursion can occur.
443 .sp
444
445 .SH NOTES
446
447 .LP
448 The following list compares the features of the
449 \fBmalloc\fR(3C),
450 \fBbsdmalloc\fR(3MALLOC),
451 \fBmalloc\fR(3MALLOC),
452 \fBmtmalloc\fR(3MALLOC) , and the \fBlibumem\fR
453 functions.
454 .sp
455
456 .sp
457 .RS +4
458 .TP
459 .ie t \(bu
460 .el o
461 The
462 \fBmalloc\fR(3C),
463 \fBbsdmalloc\fR(3MALLOC), and
464 \fBmalloc\fR(3MALLOC) functions have no support for concurrency. The \fBlibumem\fR and
465 \fBmtmalloc\fR(3MALLOC)
466 functions support concurrent allocations.
467 .sp
468
469 .RE
470
471 .sp
472 .RS +4
473 .TP
474 .ie t \(bu
475 .el o
476 The
477 \fBbsdmalloc\fR(3MALLOC) functions afford better performance but are space-inefficient.
478 .sp
479
480 .RE
481
482 .sp
483 .RS +4
484 .TP
485 .ie t \(bu
486 .el o
487 The
488 \fBmalloc\fR(3MALLOC) functions are space-efficient but have slower performance.
489 .sp
490
491 .RE
492
493 .sp
494 .RS +4
495 .TP
496 .ie t \(bu
497 .el o
498 The standard, fully SCD-compliant
499 \fBmalloc\fR(3C) functions are a trade-off between performance and space-efficiency.
500 .sp
501
502 .RE
503
504 .sp
505 .RS +4
506 .TP
507 .ie t \(bu
508 .el o
509 The
510 \fBmtmalloc\fR(3MALLOC) functions provide fast, concurrent \fBmalloc()\fR implementations that are not space-efficient.
511 .sp
512
513 .RE
514
515 .sp
516 .RS +4
517 .TP
518 .ie t \(bu
519 .el o
520 The \fBlibumem\fR functions provide a fast, concurrent allocation implementation that in most cases is more space-efficient than
521 \fBmtmalloc\fR(3MALLOC).
522 .sp
523
524 .RE
525
Note: See TracBrowser for help on using the browser.