umem_alloc man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]


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

       cc [ flag ... ] file... -lumem [ library ... ]
       #include <umem.h>

       void *umem_alloc(size_t size, int  flags);

       void *umem_zalloc(size_t size, int  flags);

       void umem_free(void *buf, size_t size);

       void umem_nofail_callback((int (*callback)(void));

       void *malloc(size_t size);

       void *calloc(size_t nelem, size_t elsize);

       void free(void *ptr);

       void *memalign(size_t alignment, size_t size);

       void *realloc(void *ptr, size_t size);

       void *valloc(size_t size);

       The umem_alloc() function returns a pointer to a block  of  size	 bytes
       suitably	 aligned for any variable type. The initial contents of memory
       allocated using umem_alloc() is undefined. The  flags  argument	deter‐
       mines  the  behavior  of	 umem_alloc()  if  it is unable to fulfill the
       request. The flags argument can take the following values:

		       Return NULL on failure.

		       Call an optional callback (set  with  umem_nofail_call‐
		       back()) on failure. The callback takes no arguments and
		       can finish by:

			   o	  returning UMEM_CALLBACK_RETRY, in which case
				  the  allocation  will	 be  retried.	If the
				  allocation  fails,  the  callback  will   be
				  invoked again.

			   o	  returning   UMEM_CALLBACK_EXIT(status),   in
				  which case exit(2) is invoked with status as
				  its  argument. The exit() function is called
				  only once. If multiple threads  return  from
				  the  UMEM_NOFAIL  callback  with  UMEM_CALL‐
				  BACK_EXIT(status),  one  will	 call	exit()
				  while	 the  other blocks until exit() termi‐
				  nates the program.

			   o	  invoking a context-changing  function	 (set‐
				  context(2)) or a non-local jump (longjmp(3C)
				  or siglongjmp(3C),  or  ending  the  current
				  thread    of	  control   (thr_exit(3C)   or
				  pthread_exit(3C). The application is respon‐
				  sible	 for  any necessary cleanup. The state
				  of libumem remains consistent.
		       If no callback has been set or the  callback  has  been
		       set  to	NULL,  umem_alloc(..., UMEM_NOFAIL) behaves as
		       though the callback returned UMEM_CALLBACK_EXIT(255).

		       The libumem library can call callbacks from  any	 place
		       that  a	UMEM_NOFAIL  allocation	 is  issued. In multi‐
		       threaded applications, callbacks are expected  to  per‐
		       form their own concurrency management.

       The  function  call umem_alloc(0, flag) always returns NULL.  The func‐
       tion call umem_free(NULL, 0) is allowed.

       The umem_zalloc() function has the same semantics as umem_alloc(),  but
       the block of memory is initialized to zeros before it is returned.

       The  umem_free()	 function  frees  blocks  previously  allocated	 using
       umem_alloc() and	 umem_zalloc().	 The  buffer  address  and  size  must
       exactly	match  the  original  allocation.  Memory must not be returned

       The umem_nofail_callback() function sets the  process-wide  UMEM_NOFAIL
       callback. See the description of UMEM_NOFAIL for more information.

       The  malloc(),  calloc(),  free(),  memalign(), realloc(), and valloc()
       functions are as described in malloc(3C). The libumem library  provides
       these  functions	 for  backwards-compatibility  with the standard func‐

       See umem_debug(3MALLOC)	for  environment  variables  that  effect  the
       debugging features of the libumem library.

		       Contains	 a  list of comma-separated options.  Unrecog‐
		       nized options are ignored.  The options that  are  sup‐
		       ported are:

				       Set  the	 underlying  function  used to
				       allocate memory. This option can be set
				       to    sbrk   (the   default)   for   an
				       sbrk(2)-based source  or	 mmap  for  an
				       mmap(2)-based source. If set to a value
				       that is not  supported,	sbrk  will  be

				       libumem allows for each thread to cache
				       recently freed  small  allocations  for
				       future  allocations. The size argument,
				       which accepts k, m, g, and t,  suffixes
				       denotes	the  maximum  amount of memory
				       each thread can use for	this  purpose.
				       The  default  amount  used is 1 MB. Any
				       buffers in  the	per-thread  cache  are
				       freed  when the thread exits. The effi‐
				       cacy of the  per-thread	cache  can  be
				       determined  with	 the  ::umastat mdb(1)
				       dcmd debugger command.

				       Set the underlying allocation strategy.
				       The  best fit strategy tells libumem to
				       use the smallest free segment possible.
				       The  instant  fit strategy approximates
				       the best fit strategy in	 constant  cpu
				       time.  The first fit strategy takes the
				       first free segment that can  honor  the
				       allocation.  The next fit strategy uses
				       the next free segment after the	previ‐
				       ously allocated one.

       Example 1 Using the umem_alloc() function.

	 #include <stdio.h>
	 #include <umem.h>
	 char *buf = umem_alloc(1024, UMEM_DEFAULT);

	 if (buf == NULL) {
	      fprintf(stderr, "out of memory\n");
		   return (1);
	 /* cannot assume anything about buf's contents */
	 umem_free(buf, 1024);

       Example 2 Using the umem_zalloc() function

	 #include <stdio.h>
	 #include <umem.h>
	 char *buf = umem_zalloc(1024, UMEM_DEFAULT);

	 if (buf == NULL) {
	     fprintf(stderr, "out of memory\n");
		  return (1);
	 /* buf contains zeros */
	 umem_free(buf, 1024);

       Example 3 Using UMEM_NOFAIL

	 #include <stdlib.h>
	 #include <stdio.h>
	 #include <umem.h>

	  * Note that the allocation code below does not have to
	  * check for umem_alloc() returning NULL
		  (void) fprintf(stderr, "out of memory\n");
		  return (UMEM_CALLBACK_EXIT(255));
	 int i;
	 char *buf[100];

	 for (i = 0; i < 100; i++)
		  buf[i] = umem_alloc(1024 * 1024, UMEM_NOFAIL);
	 for (i = 0; i < 100; i++)
	     umem_free(buf[i], 1024 * 1024);

       Example 4 Using UMEM_NOFAIL in a multithreaded application

	 #define _REENTRANT
	 #include <thread.h>
	 #include <stdio.h>
	 #include <umem.h>

	 void *
	 start_func(void *the_arg)
		   int *info = (int *)the_arg;
		   char *buf = umem_alloc(1024 * 1024, UMEM_NOFAIL);

		   /* does not need to check for buf == NULL */
		   buf[0] = 0;
		    * if there were other UMEM_NOFAIL allocations,
		    * we would need to arrange for buf to be
		    * umem_free()ed upon failure.
		   umem_free(buf, 1024 * 1024);
		   return (the_arg);
		  /* terminate the current thread with status NULL */
	 int my_arg;

	 thread_t tid;
	 void *status;

	 (void) thr_create(NULL, NULL, start_func, &my_arg, 0,
	 while (thr_join(0, &tid, &status) != 0)

	 if (status == NULL) {
	     (void) fprintf(stderr, "thread %d ran out of memory\n",

       See attributes(5) for descriptions of the following attributes:

       │Interface Stability │ Committed	      │
       │MT-Level	    │ MT-Safe	      │
       │Standard	    │ See below.      │

       For  malloc(),  calloc(),  free(),  realloc(),  and valloc(), see stan‐

       exit(2),	  mmap(2),   sbrk(2),	 bsdmalloc(3MALLOC),	libumem(3LIB),
       longjmp(3C),	malloc(3C),    malloc(3MALLOC),	   mapmalloc(3MALLOC),
       pthread_exit(3C),       thr_exit(3C),	   umem_cache_create(3MALLOC),
       umem_debug(3MALLOC), watchmalloc(3MALLOC), attributes(5), standards(5)

       Solaris Modular Debugger Guide

       Any of the following can cause undefined results:

	   o	  Passing  a  pointer  returned from umem_alloc() or umem_zal‐
		  loc() to free() or realloc().

	   o	  Passing a pointer returned  from  malloc(),  calloc(),  val‐
		  loc(), memalign(), or realloc() to umem_free().

	   o	  Writing   past   the	 end   of  a  buffer  allocated	 using
		  umem_alloc() or umem_zalloc()

	   o	  Performing UMEM_NOFAIL allocations from an  atexit(3C)  han‐

       If  the UMEM_NOFAIL callback performs UMEM_NOFAIL allocations, infinite
       recursion can occur.

       The following list compares the features	 of  the  malloc(3C),  bsdmal‐
       loc(3MALLOC),  malloc(3MALLOC),	mtmalloc(3MALLOC)  ,  and  the libumem

	   o	  The  malloc(3C),  bsdmalloc(3MALLOC),	 and   malloc(3MALLOC)
		  functions  have  no support for concurrency. The libumem and
		  mtmalloc(3MALLOC) functions support concurrent allocations.

	   o	  The bsdmalloc(3MALLOC) functions afford  better  performance
		  but are space-inefficient.

	   o	  The  malloc(3MALLOC)	functions are space-efficient but have
		  slower performance.

	   o	  The standard, fully SCD-compliant malloc(3C) functions are a
		  trade-off between performance and space-efficiency.

	   o	  The  mtmalloc(3MALLOC)  functions  provide  fast, concurrent
		  malloc() implementations that are not space-efficient.

	   o	  The libumem functions provide a fast, concurrent  allocation
		  implementation  that	in  most cases is more space-efficient
		  than mtmalloc(3MALLOC).

				 Mar 24, 2008		   UMEM_ALLOC(3MALLOC)

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net