_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'

Debug Functions

See Also   _RPT, _RPTF