INtime SDK Help
_CrtSetDbgFlag
INtime SDK v6 > About INtime > Other system libraries > Heaps and memory pools > Using the Debug Heap > The Debug Heap > _CrtSetDbgFlag

Retrieves or modifies the _crtDbgFlag flag state to control the debug heap manager's allocation behavior (debug version only).

int _CrtSetDbgFlag (
    int fNewBits
);

Parameters

fNewBits
New state for _crtDbgFlag.

Remarks

_CrtSetDbgFlag lets the application 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:

When _DEBUG is not defined, preprocessing removes calls to _CrtSetDbgFlag.

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, these bits are not set (turned off) by default. For more information about these bit fields, see Using the Debug Heap.

Bit field Description
_CRTDBG_ALLOC_MEM_DF ON (default): 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.

Can also be combined with any of the heap-frequency check macros.

_CRTDBG_CHECK_ALWAYS_DF ON: Call _CrtCheckMemory at every allocation and deallocation request.

OFF (default): _CrtCheckMemory must be called explicitly.

Heap-frequency check macros have no effect when this flag is set.

_CRTDBG_CHECK_CRT_DF ON: Include _CRT_BLOCK types in leak detection and memory state difference operations.

OFF (default): These operations ignore memory used internally by the run-time library.

Can also be combined with any of the heap-frequency check macros.

_CRTDBG_DELAY_FREE_MEM_DF 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 (default): Do not keep freed blocks in the heap's linked list.

Can also be combined with any of the heap-frequency check macros.

_CRTDBG_LEAK_CHECK_DF ON: Perform automatic leak checking at program exit through a call to _CrtDumpMemoryLeaks and generate an error report if the application failed to free all the memory it allocated.

OFF (default): Do not automatically perform leak checking at program exit.

Can also be combined with any of the heap-frequency check macros.


Heap-Check Frequency Macros

You can specify how often the C runtime library performs validation of the debug heap (_CrtCheckMemory) based on the number of calls to malloc, realloc, free, and _msize.

_CrtSetDbgFlag then inspects the upper 16 bits of the fNewBits parameter for a value. The value specified are the number of malloc, realloc, free, and _msize calls between _CrtCheckMemory calls. Four predefined macros are provided for this purpose.

Macro Number of malloc, realloc, free, and _msize calls between calls to _CrtCheckMemory
_CRTDBG_CHECK_EVERY_16_DF 16
_CRTDBG_CHECK_EVERY_128_DF 128
_CRTDBG_CHECK_EVERY_1024_DF 1024
_CRTDBG_CHECK_DEFAULT_DF

0

By default, _CrtCheckMemory is called once every 1,024 times you call malloc, realloc, free, and _msize.

For example, you can specify a heap check every 16 malloc, realloc, free, and _msize operations with this code:

#include 
int main( )
{
int tmp;

// Get the current bits
tmp = _CrtSetDbgFlag(_CRTDBG_REPORT_FLAG);

// Clear the upper 16 bits and OR in the desired freqency
tmp = (tmp & 0x0000FFFF) | _CRTDBG_CHECK_EVERY_16_DF;

// Set the new bits
_CrtSetDbgFlag(tmp);
}

The upper 16 bits of the newFlag parameter are ignored when _CRTDBG_CHECK_ALWAYS_DF is specified. In this case, _CrtCheckMemory is called each time you call malloc, realloc, free, and _msize.

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:

  1. Call _CrtSetDbgFlag with newFlag equal 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 the temporary variable with the corresponding bitmasks (represented in the application code by manifest constants).
  3. Turn off the other bits by AND-ing the variable with a bitwise NOT of the appropriate bitmasks.
  4. Call _CrtSetDbgFlag with newFlag equal to the value stored in the temporary variable to set the new state for _crtDbgFlag.

The following code demonstrates 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.

If newFlag is not a valid value, this function invokes the invalid parameter handler. If execution continues, this function sets errno to EINVAL and returns _crtDbgFlag's previous state.

Return Values

The previous state of _crtDbgFlag.

Requirements

Versions Defined in Include Link to
INtime 3.13 intime/rt/include/crtdbg.h crtdbg.h clib.lib
   
See Also