illumos: manual page: umem

UMEM_DEBUG(3MALLOC) 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 uninitialized data, use of freed
data, and many other common programming 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).

When using the debugging features of the library, a program may opt into
changing the failure rate of memory allocation. This is often useful for
test code that would like to force memory allocation failures in a
controlled fashion. See the umem_setmtbf(3MALLOC) function for more
information.

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

If frames is not specified 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 specified 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 filling 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 redzone 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 with
0xbaddcafe. The redzone is checked
every time a buffer is allocated or
freed.

For caches with either constructors
or destructors, or both,
umem_cache_alloc(3MALLOC) and
umem_cache_free(3MALLOC) apply the
cache's constructor and destructor,
respectively, instead of caching
constructed objects. The presence of
assert(3C)s in the destructor
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 previous
transactions are entered into this
log.

contents[=size]
If the audit debugging 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 allocation.

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

WARNINGS

When libumem aborts the process using abort(3C), any existing 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.

December 9, 2017 UMEM_DEBUG(3MALLOC)