crt_dbg2 Sample: C Run-Time Debugging Hook Functions
The crt_dbg2 sample illustrates several ways to use debugging hook functions with the debug versions of the C run-time library. To add some realism, it has a few elements of an actual application, including two bugs.
This sample is not supported on Intel's Itanium processors.
This sample code is provided to illustrate a concept and should not be used in applications or Web sites, as it may not illustrate the safest coding practices. Microsoft assumes no liability for incidental or consequential damages should the sample code be used for purposes other than as intended.
To get samples and instructions for installing them:
On the Visual Studio Help menu, click Samples.
For more information, see Visual Studio Samples.
The most recent version and complete list of samples is available online from the Visual Studio 2008 Samples page.
You can also locate samples on your computer's hard disk. By default, samples and a Readme file are copied into a folder under \Program Files\Visual Studio 9.0\Samples\. For Express editions of Visual Studio, all samples are located online.
Building and Running the Sample
To build and run this sample
Open the solution crt_dbg2.sln.
From the Build menu, click Build.
From the Debug menu, select Start Without Debugging.
How the Sample Works
The program stores birthdate information in a linked list of Client blocks. A Client-dump hook function validates the birthday data and reports the contents of the Client blocks. An allocation hook function logs heap operations to a text file, and the report hook function logs selected reports to the same text file.
Note that the allocation hook function explicitly excludes CRT blocks (the memory allocated internally by the C run-time library) from its log. The hook function uses fprintf to write to the log file, and fprintf allocates a CRT block. If CRT blocks were not excluded in this case, an endless loop would overflow the stack: fprintf would cause the hook function to be called, the hook would in turn call fprintf, which would in turn cause the hook to be called again, and so forth.
To be able to report CRT-type blocks in your allocation hook, Windows API functions could be used instead of C run-time functions. Because the Windows APIs do not use the CRT heap, they would not trap the hook in an endless loop.
The debug heap catches two bugs and a data error in the second example. One bug is that the birthday name field is not large enough to hold several of the test names. The field should be larger, and strncpy should be used instead of strcpy. The second bug is that the while loop in the printRecords function should not end until the HeadPtr itself is equal to null. This bug results not only in an incomplete display of birthdays, but also in a memory leak. Finally, Gauss's birthday should be April 30, not April 32.
This sample uses the following keywords:
_assert; _asserte; _crtcheckmemory; _crtmemcheckpoint; _crtmemdumpallobjectssince; _crtmemdumpstatistics; _crtsetallochook; _crtsetdbgflag; _crtsetdumpclient; _crtsetreportfile; _crtsetreporthook; _crtsetreportmode; _free_dbg; _malloc_dbg; _rpt4; _strdate; _strtime; aboutbox; clear_crt_debug_field; createinstance; createrecord; displaystring; donttouch; exit; fatalerror; fclose; fflush; fopen; fprintf; fputs; get_size; helpstring; id; iid_is; module; myallochook; mydumpclienthook; myreporthook; pointer_default; printf; printrecords; put_size; set_crt_debug_field; strcpy_s; strstr; uuid