Tribblix: 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)