|
1 | 1 | ---
|
2 | 2 | title: "assert Macro, _assert, _wassert"
|
| 3 | +description: "The effects of the assert macros and functions in the C Runtime." |
3 | 4 | ms.date: "11/04/2016"
|
4 | 5 | api_name: ["assert", "_assert", "_wassert"]
|
5 | 6 | api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"]
|
@@ -51,13 +52,21 @@ The `assert` macro is typically used to identify logic errors during program dev
|
51 | 52 |
|
52 | 53 | The `assert` macro prints a diagnostic message when *expression* evaluates to **`false`** (0) and calls [`abort`](abort.md) to terminate program execution. No action is taken if *expression* is **`true`** (nonzero). The diagnostic message includes the failed expression, the name of the source file and line number where the assertion failed.
|
53 | 54 |
|
54 |
| -The diagnostic message is printed in wide characters. Thus, it will work as expected even if there are Unicode characters in the expression. |
| 55 | +The diagnostic message is printed in wide (`wchar_t`) characters. Thus, it will work as expected even if there are Unicode characters in the expression. |
55 | 56 |
|
56 |
| -The destination of the diagnostic message depends on the type of application that called the routine. Console applications receive the message through **stderr**. In a Windows-based application, `assert` calls the Windows [MessageBox](/windows/win32/api/winuser/nf-winuser-messagebox) function to create a message box to display the message 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 normal execution. Note that clicking **Ignore** when an error condition exists can result in undefined behavior. |
| 57 | +The destination of the diagnostic message depends on the type of application that called the routine. Console applications receive the message through **stderr**. In a Windows-based application, `assert` calls the Windows [MessageBox](/windows/win32/api/winuser/nf-winuser-messagebox) function to create a message box to display the message 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**, the program will continue with normal execution. Note that clicking **Ignore** when an error condition exists can result in undefined behavior. |
57 | 58 |
|
58 |
| -To override the default behavior, the [`_set_error_mode`](set-error-mode.md) function can be used to select between the output-to-stderr and display-dialog-box behavior regardless of application type. |
| 59 | +To override the default output behavior regardless of the app type, call [`_set_error_mode`](set-error-mode.md) to select between the output-to-stderr and display-dialog-box behavior. |
59 | 60 |
|
60 |
| -Since `assert` calls [`abort`](abort.md) immediately after displaying the message, the debug behavior for [`abort`](abort.md) will also occur. [`abort`](abort.md) will display a dialog box with the Abort, Retry, and Ignore buttons. This is not the same as the `assert` dialog box described above. In particular, [`abort`](abort.md) always exits the program during its execution, so neither the Retry nor Ignore button will resume execution following the `assert` call. The [`abort`](abort.md) dialog box is skipped if a dialog box was already displayed during `assert`, so this is only seen when output-to-stderr `assert` behavior is used. |
| 61 | +Since `assert` calls [`abort`](abort.md) immediately after displaying the message, the debug behavior for [`abort`](abort.md) will also occur. [`abort`](abort.md) will display a dialog box with the **Abort**, **Retry**, and **Ignore** buttons. This is not the same as the `assert` dialog box described above. In particular, [`abort`](abort.md) always exits the program during its execution, so neither the **Retry** nor **Ignore** button will resume execution following the `assert` call. The [`abort`](abort.md) dialog box is skipped if a dialog box was already displayed during `assert`, so this is only seen when output-to-stderr `assert` behavior is used. |
| 62 | + |
| 63 | +This means that a dialog box is always displayed following an `assert` call in debug mode. The behavior of each button is captured in the below table. |
| 64 | + |
| 65 | +|Error mode|Output to stderr (Console/_OUT_TO_STDERR)|Display Dialog Box (Windows/_OUT_TO_MSGBOX)| |
| 66 | +|----------|----------------|------------------| |
| 67 | +|Abort|Exit immediately with exit code 3|Exit immediately with exit code 3| |
| 68 | +|Retry|Break into debugger during `abort`|Break into debugger during `assert`| |
| 69 | +|Ignore|Finish exiting via `abort`|Continue program as though the assert did not fire (may result in undefined behavior)| |
61 | 70 |
|
62 | 71 | For more information about CRT debugging, see [CRT Debugging Techniques](/visualstudio/debugger/crt-debugging-techniques).
|
63 | 72 |
|
|
0 commit comments