_RPT, _RPTF Macros

Article
09/15/2006

Track an application’s progress by generating a debug report (debug version only).

_RPT0(reportType,format);

_RPT1(reportType, format**,arg1);**

_RPT2(reportType,format,arg1,arg2);

_RPT3(reportType,format,arg1,arg2,arg3);

_RPT4(reportType,format,arg1,arg2,arg3,arg4);

_RPTF0(reportType,format);

_RPTF1(reportType,format,arg1);

_RPTF2(reportType,format,arg1,arg2);

_RPTF3(reportType,format,arg1,arg2,arg3);

_RPTF4(reportType,format,arg1,arg2,arg3,arg4);

Macro	Required Header	Compatibility
_RPT macros	<crtdbg.h>	Win NT, Win 95
_RPTF macros	<crtdbg.h>	Win NT, Win 95

For additional compatibility information, see Compatibility in the Introduction.

Libraries

LIBCD.LIB	Single thread static library, debug version
LIBCMTD.LIB	Multithread static library, debug version
MSVCRTD.LIB	Import library for MSVCRTD.DLL, debug version

Although these are macros and are obtained by including CRTDBG.H, the application must link with one of the libraries listed above because these macros call other run-time functions.

Return Value

None

Parameters

reportType

Report type: _CRT_WARN, _CRT_ERROR, _CRT_ASSERT

format

Format-control string used to create the user message

arg1

Name of first substitution argument used by format

arg2

Name of second substitution argument used by format

arg3

Name of third substitution argument used by format

arg4

Name of fourth substitution argument used by format

All of these macros take the reportType and format parameters. In addition, they might also take arg1 through arg4, signified by the number appended to the macro name. For example, _RPT0 and _RPTF0 take no additional arguments, _RPT1 and _RPTF1 take arg1, _RPT2 and _RPTF2 take arg1 and arg2, and so on.

Remarks

The _RPT and _RPTF macros are similar to the printf function, as they can be used to track an application’s progress during the debugging process. However, these macros are more flexible than printf because they do not need to be enclosed in #ifdef statements to prevent them from being called in a retail build of an application. This flexibility is achieved by using the _DEBUG macro. The _RPT and _RPTF macros are only available when the _DEBUG flag is defined. When _DEBUG is not defined, calls to these macros are removed during preprocessing.

The _RPT macros call the _CrtDbgReport function to generate a debug report with a user message. The _RPTF macros create a debug report with the source file and line number where the report macro was called, in addition to the user message. The user message is created by substituting the arg[n] arguments into the format string, using the same rules defined by the printf function.

_CrtDbgReport generates the debug report and determines its destination(s), based on the current report modes and file defined for reportType. The _CrtSetReportMode and _CrtSetReportFile functions are used to define the destination(s) for each report type.

When the destination is a debug message window and the user chooses the Retry button, _CrtDbgReport returns 1, causing these macros to start the debugger, provided that “just-in-time” (JIT) debugging is enabled. For more information about using these macros as a debugging error handling mechanism, see Using Macros for Verification and Reporting.

Two other macros exist that generate a debug report. The _ASSERT macro generates a report, but only when its expression argument evaluates to FALSE. _ASSERTE is exactly like _ASSERT, but includes the failed expression in the generated report.

Example

/*
 * DBGMACRO.C
 * In this program, calls are made to the _ASSERT and _ASSERTE
 * macros to test the condition 'string1 == string2'.  If the
 * condition fails, these macros print a diagnostic message.
 * The _RPTn and _RPTFn group of macros are also exercised in
 * this program, as an alternative to the printf function.
 */

#include <stdio.h>
#include <string.h>
#include <malloc.h>
#include <crtdbg.h>

int main()
{
   char *p1, *p2;

   /*
    * The Reporting Mode and File must be specified
    * before generating a debug report via an assert
    * or report macro.
    * This program sends all report types to STDOUT
    */                                            
   _CrtSetReportMode(_CRT_WARN, _CRTDBG_MODE_FILE);
   _CrtSetReportFile(_CRT_WARN, _CRTDBG_FILE_STDOUT);
   _CrtSetReportMode(_CRT_ERROR, _CRTDBG_MODE_FILE);
   _CrtSetReportFile(_CRT_ERROR, _CRTDBG_FILE_STDOUT);
   _CrtSetReportMode(_CRT_ASSERT, _CRTDBG_MODE_FILE);
   _CrtSetReportFile(_CRT_ASSERT, _CRTDBG_FILE_STDOUT);

   /*
    * Allocate and assign the pointer variables
    */
   p1 = malloc(10);
   strcpy(p1, "I am p1");
   p2 = malloc(10);
   strcpy(p2, "I am p2");

   /*
    * Use the report macros as a debugging
    * warning mechanism, similar to printf.
    * Use the assert macros to check if the
    * p1 and p2 variables are equivalent.
    * If the expression fails, _ASSERTE will
    * include a string representation of the
    * failed expression in the report.
    * _ASSERT does not include the
    * expression in the generated report.
    */
   _RPT0(_CRT_WARN, "\n\n Use the assert macros to evaluate the expression p1 == p2.\n");
   _RPTF2(_CRT_WARN, "\n Will _ASSERT find '%s' == '%s' ?\n", p1, p2);
   _ASSERT(p1 == p2);

   _RPTF2(_CRT_WARN, "\n\n Will _ASSERTE find '%s' == '%s' ?\n", p1, p2);
   _ASSERTE(p1 == p2);

   _RPT2(_CRT_ERROR, "\n \n '%s' != '%s'\n", p1, p2);

   free(p2);
   free(p1);

   return 0;
}

Output

Use the assert macros to evaluate the expression p1 == p2.

dbgmacro.c(54) : Will _ASSERT find 'I am p1' == 'I am p2' ?
dbgmacro.c(55) : Assertion failed


dbgmacro.c(57) : Will _ASSERTE find 'I am p1' == 'I am p2' ?
dbgmacro.c(58) : Assertion failed: p1 == p2


'I am p1' != 'I am p2'

Debug Functions

Share via

_RPT, _RPTF Macros

Additional resources