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:
General diagnostic macros
General diagnostic functions and variables
Object diagnostic functions
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 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. |
| TRACE | Provides printf-like capability in the Debug version of the library. |
| TRACE0 | Similar to TRACE but takes a format string with no arguments. |
| TRACE1 | Similar to TRACE but takes a format string with a single argument. |
| TRACE2 | Similar to TRACE but takes a format string with two arguments. |
| TRACE3 | Similar to TRACE but takes a format string with three arguments. |
| 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. |
| afxTraceEnabled | Global variable used to enable or disable output from the TRACE macro. |
| afxTraceFlags | Global variable used to turn on the built-in reporting features of MFC. |
| AfxCheckError | Global variable used to test the passed 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. |