Reformatting page.  Please Wait... done


Memory Allocation Library Functions           UMEM_ALLOC(3MALLOC)


NAME
     umem_alloc, umem_zalloc, umem_free,  umem_nofail_callback  -
     fast, scalable memory allocation

SYNOPSIS
     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);


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

     UMEM_DEFAULT
                     Return NULL on failure.


     UMEM_NOFAIL
                     Call  an   optional   callback   (set   with


Illumos             Last change: Mar 24, 2008                   1


Memory Allocation Library Functions           UMEM_ALLOC(3MALLOC)


                     umem_nofail_callback())   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_CALLBACK_EXIT(status),     one
                              will call exit()  while  the  other
                              blocks  until exit() terminates the
                              program.

                         o    invoking a  context-changing  func-
                              tion (setcontext(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 responsible  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 multithreaded applications, call-
                     backs are expected to perform their own con-
                     currency management.


     The function call umem_alloc(0, flag) always  returns  NULL.
     The function 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.


Illumos             Last change: Mar 24, 2008                   2


Memory Allocation Library Functions           UMEM_ALLOC(3MALLOC)


     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 piecemeal.


     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 functions.

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

     UMEM_OPTIONS
                     Contains a list of comma-separated  options.
                     Unrecognized   options   are  ignored.   The
                     options that are supported are:

                     backend=sbrk
                     backend=mmap
                                     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
                                     used.

                     allocator=best
                     allocator=first
                     allocator=instant
                     allocator=next
                                     Set the  underlying  alloca-
                                     tion  strategy. The best fit
                                     strategy  tells  libumem  to
                                     use  the  smallest free seg-
                                     ment 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


Illumos             Last change: Mar 24, 2008                   3


Memory Allocation Library Functions           UMEM_ALLOC(3MALLOC)


                                     strategy  uses the next free
                                     segment after the previously
                                     allocated one.


EXAMPLES
     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
        */
       int


Illumos             Last change: Mar 24, 2008                   4


Memory Allocation Library Functions           UMEM_ALLOC(3MALLOC)


       my_failure_handler(void)
       {
                (void) fprintf(stderr, "out of memory\n");
                return (UMEM_CALLBACK_EXIT(255));
       }
       ...
       umem_nofail_callback(my_failure_handler);
       ...
       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);
       }
       ...
       int
       my_failure_handler(void)
       {
                /* terminate the current thread with status NULL */
                thr_exit(NULL);
       }
       ...


Illumos             Last change: Mar 24, 2008                   5


Memory Allocation Library Functions           UMEM_ALLOC(3MALLOC)


       umem_nofail_callback(my_failure_handler);
       ...
       int my_arg;

       thread_t tid;
       void *status;

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

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


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:


     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|_________________|
    | Interface Stability|  Committed      |
    |____________________|_________________|
    | MT-Level           |  MT-Safe        |
    |____________________|_________________|
    | Standard           |  See below.     |
    |____________________|_________________|


     For malloc(), calloc(), free(), realloc(), and valloc(), see
     standards(5).

SEE ALSO
     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


Illumos             Last change: Mar 24, 2008                   6


Memory Allocation Library Functions           UMEM_ALLOC(3MALLOC)


WARNINGS
     Any of the following can cause undefined results:

         o    Passing a pointer  returned  from  umem_alloc()  or
              umem_zalloc() to free() or realloc().

         o    Passing a pointer returned from malloc(), calloc(),
              valloc(), 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) handler.


     If the UMEM_NOFAIL  callback  performs  UMEM_NOFAIL  alloca-
     tions, infinite recursion can occur.

NOTES
     The following list compares the features of the  malloc(3C),
     bsdmalloc(3MALLOC)malloc(3MALLOC)mtmalloc(3MALLOC) , and
     the libumem functions.

         o    The     malloc(3C),     bsdmalloc(3MALLOC),     and
              malloc(3MALLOC)  functions have no support for con-
              currency. The libumem and  mtmalloc(3MALLOC)  func-
              tions support concurrent allocations.

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

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

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

         o    The mtmalloc(3MALLOC) functions provide fast,  con-
              current   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).


Illumos             Last change: Mar 24, 2008                   7