Diagnostic Services
Important This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer

Diagnostic Services

The Microsoft Foundation Class Library supplies many diagnostic services that make debugging your programs easier. These diagnostic services include macros and global functions that allow you to track your program's memory allocations, dump the contents of objects during run time, and print debugging messages during run time. The macros and global functions for diagnostic services are grouped into the following categories:

These macros and functions are available for all classes derived from CObject in the Debug and Release versions of MFC. However, all except DEBUG_NEW and VERIFY do nothing in the Release version.

In the Debug library, all allocated memory blocks are bracketed with a series of "guard bytes." If these bytes are disturbed by an errant memory write, then the diagnostic routines can report a problem. If you include the line:

#define new DEBUG_NEW

in your implementation file, all calls to new will store the filename and line number where the memory allocation took place. The function CMemoryState::DumpAllObjectsSince will display this extra information, allowing you to identify memory leaks. Refer also to the class CDumpContext for additional information on diagnostic output.

In addition, the C run-time library also supports a set of diagnostic functions you can use to debug your applications. For more information, see Debug Routines in the Run-Time Library Reference.

MFC General Diagnostic Macros

ASSERT Prints a message and then aborts the program if the specified expression evaluates to FALSE in the Debug version of the library.
ASSERT_KINDOF Tests that an object is an object of the specified class or of a class derived from the specified class.
ASSERT_VALID Tests the internal validity of an object by calling its AssertValid member function; typically overridden from CObject.
DEBUG_NEW Supplies a filename and line number for all object allocations in Debug mode to help find memory leaks.
DEBUG_ONLY Similar to ASSERT but does not test the value of the expression; useful for code that should execute only in Debug mode.
TRACE Provides printf-like capability in the Debug version of the library.
VERIFY Similar to ASSERT but evaluates the expression in the Release version of the library as well as in the Debug version.

MFC General Diagnostic Variables and Functions

afxDump Global variable that sends CDumpContext information to the debugger output window or to the debug terminal.
afxMemDF Global variable that controls the behavior of the debugging memory allocator.
AfxCheckError Global variable used to test the passed SCODE to see if it is an error and, if so, throws the appropriate error.
AfxCheckMemory Checks the integrity of all currently allocated memory.
AfxDump If called while in the debugger, dumps the state of an object while debugging.
AfxDumpStack Generate an image of the current stack. This function is always linked statically.
AfxEnableMemoryTracking Turns memory tracking on and off.
AfxIsMemoryBlock Verifies that a memory block has been properly allocated.
AfxIsValidAddress Verifies that a memory address range is within the program's bounds.
AfxIsValidString Determines whether a pointer to a string is valid.
AfxSetAllocHook Enables the calling of a function on each memory allocation.

MFC Object Diagnostic Functions

AfxDoForAllClasses Performs a specified function on all CObject-derived classes that support run-time type checking.
AfxDoForAllObjects Performs a specified function on all CObject-derived objects that were allocated with new.

See Also

MFC Macros and Globals

© 2016 Microsoft