Export (0) Print
Expand All
div
Expand Minimize
This topic has not yet been rated - Rate this topic

_CrtDbgReport

Generates a report with a debugging message and sends the report to three possible destinations (debug version only).

int _CrtDbgReport( 
   int reportType,
   const char *filename,
   int linenumber,
   const char *moduleName,
   const char *format [,
   argument] ... 
);

Parameters

reportType
Report type: _CRT_WARN, _CRT_ERROR, _CRT_ASSERT.
filename
Pointer to name of source file where assert/report occurred or NULL.
linenumber
Line number in source file where assert/report occurred or NULL.
moduleName
Pointer to name of module (.exe or .dll) where assert/report occurred.
format
Pointer to format-control string used to create the user message.
argument
Optional substitution arguments used by format.

Return Value

For all report destinations, _CrtDbgReport returns –1 if an error occurs and 0 if no errors are encountered. However, when the report destination is a debug message window and the user clicks the Retry button, _CrtDbgReport returns 1. If the user clicks the Abort button in the Debug Message window, _CrtDbgReport immediately aborts and does not return a value.

The _ASSERT[E] and _RPT, _RPTF debug macros call _CrtDbgReport to generate their debug report. When _CrtDbgReport returns 1, these macros start the debugger, provided that "just-in-time" (JIT) debugging is enabled.

Remarks

_CrtDbgReport can send the debug report to three different destinations: a debug report file, a debug monitor (the Visual Studio debugger), or a debug message window. Two configuration functions, _CrtSetReportMode and _CrtSetReportFile, are used to specify the destination or destinations for each report type. These functions allow the reporting destination or destinations for each report type to be separately controlled. For example, it is possible to specify that a reportType of _CRT_WARN only be sent to the debug monitor, while a reportType of _CRT_ASSERT be sent to a debug message window and a user-defined report file.

_CrtDbgReport creates the user message for the debug report by substituting the argument[n] arguments into the format string, using the same rules defined by the printf function. _CrtDbgReport then generates the debug report and determines the destination or destinations, based on the current report modes and file defined for reportType. When the report is sent to a debug message window, the filename, lineNumber, and moduleName are included in the information displayed in the window.

The following table lists the available choices for the report mode or modes and file and the resulting behavior of _CrtDbgReport. These options are defined as bit-flags in CRTDBG.H.

Report mode Report file _CrtDbgReport behavior
_CRTDBG_
MODE_DEBUG
Not applicable Writes message to Windows OutputDebugString API.
_CRTDBG_
MODE_WNDW
Not applicable Calls Windows MessageBox API to create message box to display the message along with Abort, Retry, and Ignore buttons. If user clicks Abort, _CrtDbgReport immediately aborts. If user clicks Retry, it returns 1. If user clicks Ignore, execution continues and _CrtDbgReport returns 0. Note that clicking Ignore when an error condition exists often results in "undefined behavior."
_CRTDBG_
MODE_FILE
__HFILE Writes message to user-supplied HANDLE, using the Windows WriteFile API, and does not verify validity of file handle; the application is responsible for opening the report file and passing a valid file handle.
_CRTDBG_
MODE_FILE
_CRTDBG_
FILE_STDERR
Writes message to stderr.
_CRTDBG_
MODE_FILE
_CRTDBG_
FILE_STDOUT
Writes message to stdout.

The report can be sent to one, two, or three destinations or to no destination at all. For more information about specifying the report mode or modes and report file, see the _CrtSetReportMode and _CrtSetReportFile functions. For more information about using the debug macros and reporting functions, see Using Macros for Verification and Reporting.

If your application needs more flexibility than that provided by _CrtDbgReport, you can write your own reporting function and hook it into the C run-time library reporting mechanism by using the _CrtSetReportHook function.

Requirements

Routine Required header Compatibility
_CrtDbgReport <crtdbg.h> Win 98, Win Me, Win NT, Win 2000, Win XP

For additional compatibility information, see Compatibility in the Introduction.

Libraries

Debug versions of C run-time libraries only.

Example

// crt_crtdbgreport.c
#include <crtdbg.h>

int main() {
#ifdef _DEBUG
   CrtDbgReport(_CRT_ASSERT, NULL, NULL, "some module", NULL);
#endif
}

See crt_dbg2 for an example of how to change the report function.

See Also

Debug Functions | _CrtSetReportMode | _CrtSetReportFile | printf | _DEBUG | Run-Time Routines and .NET Framework Equivalents

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.