Using the Debug Heap

To use the debug heap, link the debug build of your application with a debug version of the C run-time library. All calls to heap functions such as malloc, free, calloc, realloc, new, and delete resolve to debug versions of those functions that operate in the debug heap. When you free a memory block, the debug heap automatically checks the integrity of the buffers on either side of your allocated area and issues an error report if overwriting has occurred.

Many of the debug heap’s features, however, must be accessed from within your code. You can use a call to _CrtCheckMemory, for example, to check the heap’s integrity at any point. This function inspects every memory block in the heap, verifies that the memory block header information is valid, and confirms that the buffers have not been modified. You can control how the debug heap keeps track of allocations using an internal flag, _crtDbgFlag, which can be read and set using the _CrtSetDbgFlag function. By changing this flag, you can instruct the debug heap to check for memory leaks when the program exits, and report any leaks that are detected. Similarly, you can specify that freed memory blocks not be removed from the linked list, to simulate low-memory situations. When the heap is checked, these freed blocks are inspected in their entirety to ensure that they have not been disturbed.

The _crtDbgFlag flag contains the following bit fields:

Bit Field Value Description
_CRTDBG_ALLOC_MEM_DF On Turns on debug allocation. When this bit is off, allocations remain chained together but their block type is _IGNORE_BLOCK.
_CRTDBG_DELAY_FREE_MEM_DF Off Prevents memory from actually being freed, as for simulating low-memory conditions. When this bit is on, freed blocks are kept in the debug heap’s linked list but are marked as _FREE_BLOCK and filled with a special byte value.
_CRTDBG_CHECK_ALWAYS_DF Off Causes _CrtCheckMemory to be called at every allocation and deallocation. This slows execution, but catches errors quickly.
_CRTDBG_CHECK_CRT_DF Off Causes blocks marked as type _CRT_BLOCK to be included in leak-detection and state-difference operations. When this bit is off, the memory used internally by the run-time library is ignored during such operations.
_CRTDBG_LEAK_CHECK_DF Off Causes leak checking to be performed at program exit via a call to _CrtDumpMemoryLeaks. An error report is generated if the application has failed to free all the memory that it allocated.

To change one or more of these bit fields and create a new state for the flag, follow these steps:

  1. Call _CrtSetDbgFlag with the newFlag parameter set to _CRTDBG_REPORT_FLAG to obtain the current _crtDbgFlag state and store the returned value in a temporary variable.

  2. Turn on any bits by OR-ing (bitwise | symbol) the temporary variable with the corresponding bitmasks (represented in the application code by manifest constants).

  3. Turn off the other bits by AND-ing (bitwise & symbol) the variable with a NOT (bitwise ~ symbol) of the appropriate bitmasks.

  4. Call _CrtSetDbgFlag with the newFlag parameter set to the value stored in the temporary variable to create the new state for _crtDbgFlag.

For example, the following lines of code turn on automatic leak detection and turn off checking for blocks of type _CRT_BLOCK:

// Get current flag
int tmpFlag = _CrtSetDbgFlag( _CRTDBG_REPORT_FLAG );

// Turn on leak-checking bit
tmpFlag |= _CRTDBG_LEAK_CHECK_DF;

// Turn off CRT block checking bit
tmpFlag &= ~_CRTDBG_CHECK_CRT_DF;

// Set flag to the new value
_CrtSetDbgFlag( tmpFlag );