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