Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: July 2017
 
 

adimalloc_debug (3MALLOC)

Name

adimalloc_debug - debugging features of the adimalloc library

Synopsis

cc [ flag... ] file... -ladimalloc [ library... ]

Description

The libadimalloc 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 extended run-time debugging features is controlled by environment variables.

Environment Variables

ADIMALLOC_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 ADIMALLOC_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 ADIMALLOC_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 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 with 0xbaddcafe. The redzone is checked every time a buffer is allocated or freed.

precise

The library uses ADI precise mode trapping. This has an overall performance overhead, but is more accurate at determining the exact point that an ADI fault occurred. The default is to use disrupting mode traps.

adi[=value]

This option sets the mode ADI will operate in. It may be one of three values:

on (default if unspecified)

On platforms that support ADI it will be enabled and used to check for heap errors. On platforms that do not support ADI, memory allocation routines such as malloc(3C) will return NULL with errno set to ENOMEM. A diagnostic message will be logged to the internal libadimalloc log to indicate that ADI is unavailable.

fallback

On platforms that support ADI it will be enabled and used to check for heap errors. On platforms that do not support ADI the application will continue with adimalloc using the same allocation strategies it would use if ADI was available, however no ADI calls will be made by adimalloc.

off

ADI will be disabled. The same allocation strategies will be used as when ADI is available, however no ADI calls will be made by adimalloc. For more information, see the adimalloc_debug_init() and adimalloc_logging_init() functions.

verbose

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

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

Functions

const char *adimalloc_debug_init(void);
const char *adimalloc_logging_init(void);

An application that uses libadimalloc may use the above functions to specify the default ADI debugging and logging settings that it requires. The adimalloc_debug_init() function corresponds to the ADIMALLOC_DEBUG environment variable and the adimalloc_logging_init() function corresponds to the ADIMALLOC_LOGGING environment variable. These functions should return a string that is the same as the value for the corresponding environment variable.

These functions should be defined when required by the application. If they are present libadimalloc will call them at initialization time, using the returned value as described above. Any values specified using these functions will be overriden if the corresponding environment is set, in which case the value of the environment variable will be used to configure adimalloc.

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Volatile
MT-Level
MT-Safe

See Also

mdb(1), abort(3C), signal(3C), libadimalloc(3LIB), attributes(5)

Warnings

When libadimalloc 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 1Mb in size. Allocations larger than that could have reduced support.

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

This API is Volatile and as such can change at any time and for any reason. See the Volatile entry of the Classifications section of attributes(5).