Debug Reporting Functions of the C Run-Time Library

The run-time library includes three new debug reporting functions that provide extensive flexibility for reporting warnings and errors during execution of a debug build of an application. The main reporting function is _CrtDbgReport. Two configuration functions, _CrtSetReportMode and _CrtSetReportFile, can be used at any point to specify the destinations to which different kinds of reports will be sent.

Function	Destination
_CrtDbgReport	Reports from within an application. Set the report destination(s) by specifying its category (_CRT_WARN, _CRT_ERROR, and _CRT_ASSERT). The report may also include a message string, a source file name and line number, and one or more arguments to be formatted into the message string.
__CrtSetReportMode	Specifies the general destination(s) to which a given category of report output should be sent. The three categories of report output are _CRT_WARN, _CRT_ERROR, and _CRT_ASSERT. Possible destinations include the debugger, a message window, and/or a file or stream.
_CrtSetReportFile	Identifies a specific file or stream when _CrtSetReportMode has specified that a given category of report output will be directed to a file or stream.

For detailed information about the syntax and usage of these functions, see the Debug Routines.

Debug reports can be assigned to three different categories, depending on the urgency of the messages they contain:

_CRT_WARN

Warnings, messages, and information not needing immediate attention.

_CRT_ERROR

Errors, unrecoverable problems, and information needing immediate attention.

_CRT_ASSERT

Assertion failure (an asserted expression evaluated as FALSE).

A different destination can be specified for each of these report categories. Usually one destination is sufficient for a category, but each category can be sent to more than one destination. Up to three of the following bit-flags can be combined in the reportMode argument passed to _CrtReportMode to specify the destination(s) for a given report category:

_CRTDBG_MODE_DEBUG

Reports are sent to the debugger or debug monitor using the Win32 OutputDebugString API.

_CRTDBG_MODE_FILE

Reports are sent to a file (including the stderr and stdout streams) using the Win32 WriteFile API.

_CRTDBG_MODE_WNDW

Reports are sent to a message window using the Win32 MessageBox API.

To turn off a given category of report, pass _CrtReportMode a reportMode value of zero.

By default, errors and assertion failures are directed to a message window, because they generally signal serious problems that you want to know about right away. Warnings from Windows applications are sent to the debugger, and warnings from console applications are directed to stderr. You only need to use the _CrtSetReport... functions when you want to change these destinations. For example, the following code causes assertion failures to be sent both to a message window and to stderr:

_CrtSetReportMode( _CRT_ASSERT, _CRTDBG_MODE_FILE |
                   _CRTDBG_MODE_WNDW );
_CrtSetReportFile( _CRT_ASSERT, _CRTDBG_FILE_STDERR );

To send a debug report, you use _CrtDbgReport and control the destination by specifying the category of the report. If you need more flexibility, you can write your own reporting function and hook it into the C run-time library reporting mechanism using _CrtSetReportHook.

While messages that go to a file or the debugger are generally single lines that can include a file name and line number, the message window contains considerably more information. It identifies the error and the program more fully, along with message text, and can also display a file name and line number. Assert message windows contain additional information particular to asserts.

All message windows display Abort/Retry/Ignore buttons. Clicking Abort causes the program to stop execution immediately, Ignore causes execution to continue, and **Retry****invokes the debugger, provided that Just-in-time debugging is enabled. Clicking Ignore when an error condition exists often results in undefined behavior.