Export (0) Print
Expand All
div
Expand Minimize

assert

Evaluates an expression and, when the result is false, prints a diagnostic message and aborts the program.

void assert( 
   int expression 
);

Parameter

expression
Expression (including pointers) that evaluates to nonzero or 0.

Remarks

The ANSI assert macro is typically used to identify logic errors during program development by implementing the expression argument to evaluate to false only when the program is operating incorrectly. After debugging is complete, assertion checking can be turned off without modifying the source file by defining the identifier NDEBUG. NDEBUG can be defined with a /D command-line option or with a #define directive. If NDEBUG is defined with #define, the directive must appear before Assert.h is included.

assert prints a diagnostic message when expression evaluates to false (0) and calls abort to terminate program execution. No action is taken if expression is true (nonzero). The diagnostic message includes the failed expression and the name of the source file and line number where the assertion failed.

The destination of the diagnostic message depends on the type of application that called the routine. Console applications always receive the message through stderr. In a single- or multithreaded Windows application, assert calls the Windows MessageBox API to create a message box to display the message along with an OK button. When the user clicks OK, the program aborts immediately.

When the application is linked with a debug version of the run-time libraries, assert creates a message box with three buttons: Abort, Retry, and Ignore. If the user clicks Abort, the program aborts immediately. If the user clicks Retry, the debugger is called and the user can debug the program if just-in-time (JIT) debugging is enabled. If the user clicks Ignore, assert continues with its normal execution: creating the message box with the OK button. Note that clicking Ignore when an error condition exists can result in undefined behavior.

For more information on CRT debugging, see CRT Debugging Techniques.

The assert routine is available in both the release and debug versions of the C run-time libraries. Two other assertion macros, _ASSERT and _ASSERTE, are also available, but they only evaluate the expressions passed to them when the _DEBUG flag has been defined.

Requirements

Routine Required header Compatibility
assert <assert.h> ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP

For additional compatibility information, see Compatibility in the Introduction.

Libraries

All versions of the C run-time libraries.

Example

In this program, the analyze_string function uses the assert function to test several conditions related to string and length. If any of the conditions fails, the program prints a message indicating what caused the failure.

// crt_assert.c
#include <stdio.h>
#include <assert.h>
#include <string.h>

void analyze_string( char *string );   /* Prototype */

int main( void )
{
   char  test1[] = "abc", *test2 = NULL, test3[] = "";

   printf ( "Analyzing string '%s'\n", test1 ); fflush( stdout );
   analyze_string( test1 );
   printf ( "Analyzing string '%s'\n", test2 ); fflush( stdout );
   analyze_string( test2 );
   printf ( "Analyzing string '%s'\n", test3 ); fflush( stdout );
   analyze_string( test3 );
}

/* Tests a string to see if it is NULL, */ 
/*   empty, or longer than 0 characters */
void analyze_string( char * string )
{
   assert( string != NULL );        /* Cannot be NULL */
   assert( *string != '\0' );       /* Cannot be empty */
   assert( strlen( string ) > 2 );  /* Length must exceed 2 */
}

Sample Output

Analyzing string 'abc'
Analyzing string '(null)'
Assertion failed: string != NULL, file crt_assert.c, line 24

This application has requested the Runtime to terminate it in an unusual way.
Please contact the application's support team for more information.

See Also

Error Handling Routines | Process and Environment Control Routines | abort | raise, signal | _ASSERT, _ASSERTE | _DEBUG | Run-Time Routines and .NET Framework Equivalents

Show:
© 2014 Microsoft