_CrtSetReportMode

Specifies the destination or destinations for a specific report type generated by _CrtDbgReport and any macros that call _CrtDbgReport, _CrtDbgReportW, such as _ASSERT, _ASSERTE, _ASSERT_EXPR macros and _RPT, _RPTF, _RPTW, _RPTFW macros (debug version only).

Syntax

int _CrtSetReportMode(
   int reportType,
   int reportMode
);

Parameters

reportType
Report type: _CRT_WARN, _CRT_ERROR, and _CRT_ASSERT.

reportMode
New report mode or modes for reportType.

Return value

On successful completion, _CrtSetReportMode returns the previous report mode or modes for the report type specified in reportType. If an invalid value is passed in as reportType or an invalid mode is specified for reportMode, _CrtSetReportMode invokes the invalid parameter handler as described in Parameter validation. If execution is allowed to continue, this function sets errno to EINVAL and returns -1. For more information, see errno, _doserrno, _sys_errlist, and _sys_nerr.

Remarks

_CrtSetReportMode specifies the output destination for _CrtDbgReport. Because the macros _ASSERT, _ASSERTE, _RPT, and _RPTF call _CrtDbgReport, _CrtSetReportMode specifies the output destination of text specified with those macros.

When _DEBUG isn't defined, calls to _CrtSetReportMode are removed during preprocessing.

If you don't call _CrtSetReportMode to define the output destination of messages, then the following defaults are in effect:

  • Assertion failures and errors are directed to a debug message window.

  • Warnings from Windows applications are sent to the debugger's output window.

  • Warnings from console applications aren't displayed.

The following table lists the report types defined in Crtdbg.h.

Report type Description
_CRT_WARN Warnings, messages, and information that doesn't need immediate attention.
_CRT_ERROR Errors, unrecoverable problems, and issues that require immediate attention.
_CRT_ASSERT Assertion failures (asserted expressions that evaluate to FALSE).

The _CrtSetReportMode function assigns the new report mode specified in reportMode to the report type specified in reportType and returns the previously defined report mode for reportType. The following table lists the available choices for reportMode and the resulting behavior of _CrtDbgReport. These options are defined as bit flags in Crtdbg.h.

Report mode _CrtDbgReport behavior
_CRTDBG_MODE_DEBUG Writes the message to the debugger's output window.
_CRTDBG_MODE_FILE Writes the message to a user-supplied file handle. _CrtSetReportFile should be called to define the specific file or stream to use as the destination.
_CRTDBG_MODE_WNDW Creates a message box to display the message along with the Abort, Retry, and Ignore buttons.
_CRTDBG_REPORT_MODE Returns reportMode for the specified reportType:

1 _CRTDBG_MODE_FILE

2 _CRTDBG_MODE_DEBUG

4 _CRTDBG_MODE_WNDW

Each report type can be reported using one, two, or three modes or no mode at all. Therefore, it's possible to have more than one destination defined for a single report type. For example, the following code fragment causes assertion failures to be sent to both a debug message window and to stderr:

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

In addition, you can control the reporting mode or modes for each report type separately. For example, it's possible to specify that a reportType of _CRT_WARN goes to an output debug string, while _CRT_ASSERT is displayed using a debug message window and is sent to stderr, as previously illustrated.

Requirements

Routine Required header Optional header
_CrtSetReportMode <crtdbg.h> <errno.h>

For more compatibility information, see Compatibility.

Libraries: Debug versions of the C runtime libraries only.

See also

Debug routines