share/man/man3malloc/umem_alloc.3malloc

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