_ASSERT, _ASSERTE Macros
Evaluate an expression and generate a debug report when the result is FALSE (debug version only).
_ASSERT(booleanExpression);
_ASSERTE(booleanExpression);
| Macro | Required Header | Compatibility |
| _ASSERT | <crtdbg.h> | Win NT, Win 95 |
| _ASSERTE | <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 _ASSERT and _ASSERTE 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
Parameter
booleanExpression
Expression (including pointers) that evaluates to nonzero or 0
Remarks
The _ASSERT and _ASSERTE macros provide an application with a clean and simple mechanism for checking assumptions during the debugging process. They are very flexible 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. _ASSERT and _ASSERTE are only available when _DEBUG is defined. When _DEBUG is not defined, calls to these macros are removed during preprocessing.
_ASSERT and _ASSERTE evaluate their booleanExpression argument and when the result is FALSE (0), they print a diagnostic message and call _CrtDbgReport to generate a debug report. The _ASSERT macro prints a simple diagnostic message, while _ASSERTE includes a string representation of the failed expression in the message. These macros do nothing when booleanExpression evaluates to nonzero.
Because the _ASSERTE macro specifies the failed expression in the generated report, it enables users to identify the problem without referring to the application source code. However, a disadvantage exists in that every expression evaluated by _ASSERTE must be included in the debug version of your application as a string constant. Therefore, if a large number of calls are made to _ASSERTE, these expressions can take up a significant amount of space.
_CrtDbgReport generates the debug report and determines its destination(s), based on the current report mode(s) and file defined for the _CRT_ASSERT report type. By default, assertion failures and errors are directed to a debug message window. 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 the _ASSERT and _ASSERTE macros to start the debugger, provided that “just-in-time” (JIT) debugging is enabled. See Debug Reporting Functions of the C Run-Time Library for an example of an assert message box under Windows NT.
For more information about the reporting process, see the _CrtDbgReport function and the section Debug Reporting Functions of the C Run-Time Library. For more information about resolving assertion failures and using these macros as a debugging error handling mechanism, see Using Macros for Verification and Reporting.
The _RPT, _RPTF debug macros are also available for generating a debug report, but they do not evaluate an expression. The _RPT macros generate a simple report and the _RPTF macros include the source file and line number where the report macro was called, in the generated report. In addition to the _ASSERTE macros, the ANSI assert routine can also be used to verify program logic. This routine is available in both the debug and release versions of the libraries.
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 = (char *)malloc(10);
strcpy(p1, "I am p1");
p2 = (char *)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'
See Also _RPT, _RPTF