NT_ASSERTMSG macro
The NT_ASSERTMSG and NT_ASSERTMSGW macros test an expression. If the expression is false, the macros raise a STATUS_ASSERTION_FAILURE exception, and give you the option of ignoring the exception, handling the exception, or breaking into the kernel debugger. The macros send the specified diagnostic message to the debugger.
Syntax
VOID NT_ASSERTMSG(
Message,
Expression
);
Parameters
Message
Specifies the null-delimited string to be displayed by the debugger. To display an ANSI text, use the NT_ASSERTMSG macro. To display a UNICODE text, use the NT_ASSERTMSGW macro.Expression
Specifies any logical expression.
Return value
None
Remarks
The NT_ASSERTMSG and NT_ASSERTMSGW macros will be included in your binary only if your code is compiled for a debug configuration. Once your driver is built, the macros will work properly regardless of whether your driver is run on the checked build or on the free build of Windows. Unlike the ASSERTMSG macro, the NT_ASSERTMSG and NT_ASSERTMSGW macros store the Expression with the symbol information in the program database (PDB) file. The kernel debugger extracts the Expression and symbol information from the PDB file and also provides additional built-in assertion-handling support. When triggered, the NT_ASSERT macro can break into the debugger immediately, so the valuable state information that led up to the assertion failure is usually intact in the context reported to the debugger.
If Expression evaluates to TRUE, this routine has no effect.
If Expression evaluates to FALSE, and debugging is enabled and a debugger is connected, a message is displayed in the Debugger Command window. The message contains the source-code string of Expression, the path of the source-code file, and the line number of the instruction that called the macro. At this point, you can use debugging commands to ignore the exception, to handle the exception, or to break into the debugger. Use the ah (Assertion Handling) commands to ignore the STATUS_ASSERTION_FAILURE exception or to break into the debugger. You can also use the gh (Go with Exception Handled) or gn (Go with Exception Not Handled) debugger commands to continue execution.
If Expression evaluates to FALSE and debugging is not enabled, or debugging is enabled but the debugger is not connected, the failed assert will not be reported (although assertion checking will still be performed). If you are developing a driver and want to deterministically break into the debugger if one is enabled but not connected, you can use DbgBreakPoint statements in your code. For more information, see Controlling Exceptions and Events.
The NT_ASSERTMSG macro can also be called as NT_VERIFYMSG, and the NT_ASSERTMSGW macro can be called as NT_VERIFYMSGW.
Requirements
Target platform |
Desktop |
Version |
Available in Microsoft Windows Vista and later. |
Header |
Wdm.h (include Wdm.h) |
See also