malloc_debug

Syntax

#include <stdlib.h> int malloc_debug(int level);

Description

This function sets the level of error diagnosis and reporting during subsequent calls to malloc, free, realloc, and all functions which call them internally. The argument level is interpreted as follows:

Level 0

No checking; the memory allocation functions behave as they do if malloc_debug was never called. Memory in use by the application which was allocated while level 0 was in effect cannot be checked by malloc_verify unless it is freed first.

Level 1

Each one of the allocated blocks is recorded in a special structure, where malloc_verify can test them for corruption, even if these blocks were not yet freed. If errors are detected by malloc_verify, it prints diagnostic messages to the standard error stream, with address and size of the offending block and other pertinent information. This level slows down memory allocation to some extent due to additional overhead of calling special functions which record extra debugging info.

Level 2

Like level 1, but in addition the consistency of the entire heap is verified (by calling malloc_verify) on every call to the memory allocation functions. Warning: this may significantly slow down the application.

Level 3

Like level 2, except that the program is aborted whenever a heap corruption is detected. In addition, failed allocations (i.e. when malloc returns NULL because it cannot satisfy a request) are reported to standard error. Also, if the storage where allocated blocks are recorded is exhausted, a message to that effect is printed.

Level 4

Like level 3, but calls to free with a NULL pointer as an argument are also reported.

When malloc_debug is first called with a positive argument, it allocates storage for recording blocks in use. To avoid reentrancy problems, this storage is allocated via a direct call to sbrk, and its size is fixed. The size used to allocate this storage is by default 400KB, which is enough to record 100 thousand allocated blocks. You can tailor the size to your needs by setting the environment variable MALLOC_DEBUG to the maximum number of blocks you want to be able to track. (The value of MALLOC_DEBUG should only be as large as the maximum number of allocations which is expected to be in use at any given time, because when a buffer is freed, it is removed from this storage and its cell can be reused for another allocation.) Note that the larger this storage size, the more slow-down will your program experience when the diagnostic level is set to a non-zero value, since the debugging code needs to search the list of recorded blocks in use each time you call malloc or free.

Return Value

malloc_debug returns the previous error diagnostic level. The default level is 0.

Portability

ANSI/ISO C	No
POSIX	No (see note 1)

Notes:

1. This function is available on many Unix systems.

Example

malloc_debug(2); ... malloc_verify();