Reformatting page.  Please Wait... done


Memory Allocation Library Functions           UMEM_DEBUG(3MALLOC)


NAME
     umem_debug - debugging features of the umem library

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


DESCRIPTION
     The libumem library provides debugging features that  detect
     memory leaks, buffer overruns, multiple frees, use of unini-
     tialized data, use of freed data, and many other common pro-
     gramming  errors.  The  activation of the run-time debugging
     features is controlled by environment variables.


     When the library detects an error, it writes  a  description
     of the error to an internal buffer that is readable with the
     ::umem_status mdb(1) dcmd and then calls abort(3C).

ENVIRONMENT VARIABLES
     UMEM_DEBUG
                     This variable  contains  a  list  of  comma-
                     separated options.  Unrecognized options are
                     ignored. Possible options include:

                     audit[=frames]
                                         This option enables  the
                                         recording   of  auditing
                                         information,   including
                                         thread     ID,     high-
                                         resolution  time  stamp,
                                         and  stack trace for the
                                         last action  (allocation
                                         or  free) on every allo-
                                         cation.  If  transaction
                                         logging             (see
                                         UMEM_LOGGING)         is
                                         enabled,  this  auditing
                                         information   is    also
                                         logged.

                                         The   frames   parameter
                                         sets the number of stack
                                         frames recorded  in  the
                                         auditing  structure. The
                                         upper bound  for  frames
                                         is       implementation-
                                         defined.  If  a   larger
                                         value  is requested, the
                                         upper  bound   is   used
                                         instead.


Illumos             Last change: Jul 26, 2002                   1


Memory Allocation Library Functions           UMEM_DEBUG(3MALLOC)


                                         If frames is not  speci-
                                         fied   or   is   not  an
                                         integer,   the   default
                                         value of 15 is used.

                                         This option also enables
                                         the guards option.


                     contents[=count]
                                         If auditing and contents
                                         logging             (see
                                         UMEM_LOGGING)        are
                                         enabled, the first count
                                         bytes of each buffer are
                                         logged   when  they  are
                                         freed.  If a  buffer  is
                                         shorter    than    count
                                         bytes, it is  logged  in
                                         its entirety.

                                         If count is  not  speci-
                                         fied   or   is   not  an
                                         integer,   the   default
                                         value of 256 is used.


                     default
                                         This      option      is
                                         equivalent            to
                                         audit,contents,guards.


                     guards
                                         This option enables fil-
                                         ling allocated and freed
                                         buffers   with   special
                                         patterns  to help detect
                                         the use of uninitialized
                                         data    and   previously
                                         freed buffers.  It  also
                                         enables  an  8-byte red-
                                         zone after  each  buffer
                                         that            contains
                                         0xfeedfacefeedfaceULL.

                                         When an object is freed,
                                         it    is   filled   with
                                         0xdeadbeef.    When   an
                                         object is allocated, the
                                         0xdeadbeef  pattern   is
                                         verified   and  replaced


Illumos             Last change: Jul 26, 2002                   2


Memory Allocation Library Functions           UMEM_DEBUG(3MALLOC)


                                         with  0xbaddcafe.    The
                                         redzone is checked every
                                         time a buffer  is  allo-
                                         cated or freed.

                                         For caches  with  either
                                         constructors or destruc-
                                         tors,      or      both,
                                         umem_cache_alloc(3MALLOC)
                                         and
                                         umem_cache_free(3MALLOC)
                                         apply the  cache's  con-
                                         structor and destructor,
                                         respectively, instead of
                                         caching      constructed
                                         objects. The presence of
                                         assert(3C)s  in the des-
                                         tructor  verifying  that
                                         the  buffer  is  in  the
                                         constructed state can be
                                         used   to   detect   any
                                         objects returned  in  an
                                         improper   state.    See
                                         umem_cache_create(3MALLOC)
                                         for details.


                     verbose
                                         The library writes error
                                         descriptions to standard
                                         error  before  aborting.
                                         These  messages  are not
                                         localized.


     UMEM_LOGGING
                     To be enabled, this variable should  be  set
                     to a comma-separated list of in-memory logs.
                     The logs available are:

                     transaction[=size]
                                           If the audit debugging
                                           option   is  set  (see
                                           UMEM_DEBUG), the audit
                                           structures from previ-
                                           ous  transactions  are
                                           entered into this log.


                     contents[=size]
                                           If the audit debugging


Illumos             Last change: Jul 26, 2002                   3


Memory Allocation Library Functions           UMEM_DEBUG(3MALLOC)


                                           option   is  set,  the
                                           contents  of   objects
                                           are  recorded  in this
                                           log as they are freed.

                                           If   the    "contents"
                                           debugging  option  was
                                           not set, 256 bytes  of
                                           each  freed buffer are
                                           saved.


                     fail[=size]
                                           Records  are   entered
                                           into   this   log  for
                                           every  failed  alloca-
                                           tion.

                     For any of these options,  if  size  is  not
                     specified, the default value of 64k is used.
                     The size parameter must be an  integer  that
                     can  be  qualified  with  K,  M,  G, or T to
                     specify kilobytes, megabytes, gigabytes,  or
                     terabytes, respectively.

                     Logs that are not listed or that have either
                     a size of 0 or an invalid size are disabled.

                     The log is disabled if during initialization
                     the  requested  amount  of storage cannot be
                     allocated.


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


     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|_________________|
    | Interface Stability|  Unstable       |
    |____________________|_________________|
    | MT-Level           |  MT-Safe        |
    |____________________|_________________|


SEE ALSO
     mdb(1)abort(3C),  signal(3C),  umem_cache_create(3MALLOC),
     attributes(5)


Illumos             Last change: Jul 26, 2002                   4


Memory Allocation Library Functions           UMEM_DEBUG(3MALLOC)


     Solaris Modular Debugger Guide

WARNINGS
     When libumem aborts the process using abort(3C), any  exist-
     ing  signal  handler  for  SIGABRT  is called. If the signal
     handler performs allocations, undefined behavior can result.

NOTES
     Some of the debugging features  work  only  for  allocations
     smaller  than  16 kilobytes in size. Allocations larger than
     16 kilobytes could have reduced support.


     Activating any of the  library's  debugging  features  could
     significantly  increase  the  library's memory footprint and
     decrease its performance.


Illumos             Last change: Jul 26, 2002                   5