_CrtSetDbgFlag

Article
09/15/2006

Retrieves and/or modifies the state of the _crtDbgFlag flag to control the allocation behavior of the debug heap manager (debug version only).

int_CrtSetDbgFlag(intnewFlag );

Routine	Required Header	Compatibility
_CrtSetDbgFlag	<crtdbg.h>	Win NT, Win 95

For additional compatibility information, see Compatibility in the Introduction.

Libraries

LIBCD.LIB	Single thread static library, debug version
LIBCMTD.LIB	Multithread static library, debug version
MSVCRTD.LIB	Import library for MSVCRTD.DLL, debug version

_CrtSetDbgFlag returns the previous state of _crtDbgFlag.

Parameter

newFlag

New state for the _crtDbgFlag

Remarks

The _CrtSetDbgFlag function allows the application to control how the debug heap manager tracks memory allocations by modifying the bit fields of the _crtDbgFlag flag. By setting the bits (turning on), the application can instruct the debug heap manager to perform special debugging operations, including checking for memory leaks when the application exits and reporting if any are found, simulating low memory conditions by specifying that freed memory blocks should remain in the heap’s linked list, and verifying the integrity of the heap by inspecting each memory block at every allocation request. When _DEBUG is not defined, calls to _CrtSetDbgFlag are removed during preprocessing.

The following table lists the bit fields for _crtDbgFlag and describes their behavior. Because setting the bits results in increased diagnostic output and reduced program execution speed, most of the bits are not set (turned off) by default. For more information about these bit fields, see Using the Debug Heap.

Bit field	Default	Description
_CRTDBG_ALLOC- _MEM_DF	ON	ON: Enable debug heap allocations and use of memory block type identifiers, such as _CLIENT_BLOCK. OFF: Add new allocations to heap’s linked list, but set block type to _IGNORE_BLOCK.
_CRTDBG_CHECK- _ALWAYS_DF	OFF	ON: Call _CrtCheckMemory at every allocation and deallocation request. OFF: _CrtCheckMemory must be called explicitly.
_CRTDBG_CHECK- _CRT_DF	OFF	ON: Include _CRT_BLOCK types in leak detection and memory state difference operations. OFF: Memory used internally by the run-time library is ignored by these operations.
_CRTDBG_DELAY- _FREE_MEM_DF	OFF	ON: Keep freed memory blocks in the heap’s linked list, assign them the _FREE_BLOCK type, and fill them with the byte value 0xDD. OFF: Do not keep freed blocks in the heap’s linked list.
_CRTDBG_LEAK- _CHECK_DF	OFF	ON: Perform automatic leak checking at program exit via a call to _CrtDumpMemoryLeaks and generate an error report if the application failed to free all the memory it allocated. OFF: Do not automatically perform leak checking at program exit.

newFlag is the new state to apply to the _crtDbgFlag and is a combination of the values for each of the bit fields. To change one or more of these bit fields and create a new state for the flag, follow these steps:

Call _CrtSetDbgFlag with newFlag equal to _CRTDBG_REPORT_FLAG to obtain the current _crtDbgFlag state and store the returned value in a temporary variable.
Turn on any bits by OR-ing the temporary variable with the corresponding bitmasks (represented in the application code by manifest constants).
Turn off the other bits by AND-ing the variable with a bitwise NOT of the appropriate bitmasks.
Call _CrtSetDbgFlag with newFlag equal to the value stored in the temporary variable to set the new state for _crtDbgFlag.

The following lines of code demonstrate how to simulate low memory conditions by keeping freed memory blocks in the heap’s linked list and prevent _CrtCheckMemory from being called at every allocation request:

// Get the current state of the flag
// and store it in a temporary variable
int tmpFlag = _CrtSetDbgFlag( _CRTDBG_REPORT_FLAG );

// Turn On (OR) - Keep freed memory blocks in the
// heap’s linked list and mark them as freed
tmpFlag |= _CRTDBG_DELAY_FREE_MEM_DF;

// Turn Off (AND) - prevent _CrtCheckMemory from
// being called at every allocation request
tmpFlag &= ~_CRTDBG_CHECK_ALWAYS_DF;

// Set the new state for the flag
_CrtSetDbgFlag( tmpFlag );

For an overview of memory management and the debug heap, see Memory Management and the Debug Heap.

To disable a flag with the _CrtSetDbgFlag function, you should AND the variable with the bitwise NOT of the bitmask.

Example

/*
 * SETDFLAG.C
 * This program concentrates on allocating and freeing memory
 * blocks to test the functionality of the _crtDbgFlag flag..
 */

#include <string.h>
#include <malloc.h>
#include <crtdbg.h>

void main( )
{
        char *p1, *p2;
        int tmpDbgFlag;

        /*
         * Set the debug-heap flag to keep freed blocks in the
         * heap's linked list - This will allow us to catch any
         * inadvertent use of freed memory
         */
        tmpDbgFlag = _CrtSetDbgFlag(_CRTDBG_REPORT_FLAG);
        tmpDbgFlag |= _CRTDBG_DELAY_FREE_MEM_DF;
        tmpDbgFlag |= _CRTDBG_LEAK_CHECK_DF;
        _CrtSetDbgFlag(tmpDbgFlag);

        /*
         * Allocate 2 memory blocks and store a string in each
         */
        p1 = malloc( 34 );
        p2 = malloc( 38 );
        strcpy( p1, "p1 points to a Normal allocation block" );
        strcpy( p2, "p2 points to a Client allocation block" );

        /*
         * Free both memory blocks
         */
        free( p2 );
        free( p1 );

        /*
         * Set the debug-heap flag to no longer keep freed blocks in the
         * heap's linked list and turn on Debug type allocations (CLIENT)
         */
        tmpDbgFlag = _CrtSetDbgFlag(_CRTDBG_REPORT_FLAG);
        tmpDbgFlag |= _CRTDBG_ALLOC_MEM_DF;
        tmpDbgFlag &= ~_CRTDBG_DELAY_FREE_MEM_DF;
        _CrtSetDbgFlag(tmpDbgFlag);

        /*
         * Explicitly call _malloc_dbg to obtain the filename and line number
         * of our allocation request and also so we can allocate CLIENT type
         * blocks specifically for tracking
         */
        p1 = _malloc_dbg( 40, _NORMAL_BLOCK, __FILE__, __LINE__ );
        p2 = _malloc_dbg( 40, _CLIENT_BLOCK, __FILE__, __LINE__ );
        strcpy( p1, "p1 points to a Normal allocation block" );
        strcpy( p2, "p2 points to a Client allocation block" );

        /*
         * _free_dbg must be called to free the CLIENT block
         */
        _free_dbg( p2, _CLIENT_BLOCK );
        free( p1 );

        /*
         * Allocate p1 again and then exit - this will leave unfreed
         * memory on the heap
         */
        p1 = malloc( 10 );
}

Output

Debug Error!
Program: C:\code\setdflag.exe
DAMAGE: after Normal block (#31) at 0x002D06A8.
Press Retry to debug the application.

Debug Functions

_CrtSetDbgFlag

Additional resources