Debugging-Related Macros

Article
10/26/2017

The following table contains debugging-related macros:

Macro Declared in Description

Macro	Declared in	Description
ASSERT	ntddk.h	The ASSERT macro tests an expression. If the expression is false, it breaks into the kernel debugger. `VOID ASSERT( Expression );` Expression Specifies any logical expression. Return value VOID None. ASSERT will only be included in your binary if your code is compiled in a Debug configuration. Once your driver is built, ASSERT will work properly regardless of whether your driver is run on the checked build or on the free build of Windows. If Expression evaluates to TRUE, this routine has no effect. If Expression evaluates to FALSE, a message is displayed in the Debugger Command window. The message contains the source-code string of Expression, as well as the path of the source-code file and the line number of the instruction that called the macro. In this event, ASSERT can be ignored and the process or thread in which ASSERT occurred can be terminated. Alternatively, the debugger can be used to analyze the situation or to edit memory. If ASSERT is ignored, execution continues as if the g (Go) command was entered. Available in Microsoft Windows 2000 and later.
NT_ASSERT	wdm.h	The NT_ASSERT macro tests an expression. If the expression is false, the macro raises a STATUS_ASSERTION_FAILURE exception and gives you the option of ignoring the exception, handling the exception, or breaking into the kernel debugger. `VOID NT_ASSERT( Expression );` Expression Specifies any logical expression. Return value VOID None. The NT_ASSERT macro will be included in your binary only if your code is compiled for a debug configuration. Once your driver is built, NT_ASSERT will work properly regardless of whether your driver is run on the checked build or on the free build of Windows. Unlike the ASSERT macro, the NT_ASSERT macro stores 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_ASSERT macro can also be called as NT_VERIFY. The difference is that NT_VERIFY always evaluates its argument, while NT_ASSERT only evaluates its argument when you have compiled your code for a debug configuration. That is, when you compile your code using a debug configuration (DBG is defined), NT_VERIFY(expression) is equivalent to NT_ASSERT(expression). When you compile your code using a release configuration (DBG is not defined), NT_VERIFY(expression) is equivalent to (expression), while NT_ASSERT(expression) does nothing. Available in Microsoft Windows Vista and later.
NT_ASSERTMSG	wdm.h	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. `VOID NT_ASSERTMSG( Message, Expression );` 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 VOID None. 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. Available in Microsoft Windows Vista and later.

ASSERT

ntddk.h

The ASSERT macro tests an expression. If the expression is false, it breaks into the kernel debugger.

VOID ASSERT(
    Expression
);

Expression

Specifies any logical expression.

Return value

VOID

None.

ASSERT will only be included in your binary if your code is compiled in a Debug configuration. Once your driver is built, ASSERT will work properly regardless of whether your driver is run on the checked build or on the free build of Windows.

If Expression evaluates to TRUE, this routine has no effect.

If Expression evaluates to FALSE, a message is displayed in the Debugger Command window. The message contains the source-code string of Expression, as well as the path of the source-code file and the line number of the instruction that called the macro. In this event, ASSERT can be ignored and the process or thread in which ASSERT occurred can be terminated. Alternatively, the debugger can be used to analyze the situation or to edit memory. If ASSERT is ignored, execution continues as if the g (Go) command was entered.

Available in Microsoft Windows 2000 and later.

NT_ASSERT

wdm.h

The NT_ASSERT macro tests an expression. If the expression is false, the macro raises a STATUS_ASSERTION_FAILURE exception and gives you the option of ignoring the exception, handling the exception, or breaking into the kernel debugger.

VOID NT_ASSERT(
    Expression
);

Expression

Specifies any logical expression.

Return value

VOID

None.

The NT_ASSERT macro will be included in your binary only if your code is compiled for a debug configuration. Once your driver is built, NT_ASSERT will work properly regardless of whether your driver is run on the checked build or on the free build of Windows. Unlike the ASSERT macro, the NT_ASSERT macro stores 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_ASSERT macro can also be called as NT_VERIFY. The difference is that NT_VERIFY always evaluates its argument, while NT_ASSERT only evaluates its argument when you have compiled your code for a debug configuration. That is, when you compile your code using a debug configuration (DBG is defined), NT_VERIFY(expression) is equivalent to NT_ASSERT(expression). When you compile your code using a release configuration (DBG is not defined), NT_VERIFY(expression) is equivalent to (expression), while NT_ASSERT(expression) does nothing.

Available in Microsoft Windows Vista and later.

NT_ASSERTMSG

wdm.h

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.


VOID NT_ASSERTMSG(
    Message,
    Expression
);

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

VOID

None.

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.

The NT_ASSERTMSG macro can also be called as NT_VERIFYMSG, and the NT_ASSERTMSGW macro can be called as NT_VERIFYMSGW.

Available in Microsoft Windows Vista and later.

ah (Assertion Handling)

Controlling Exceptions and Events

DbgBreakPoint

gh (Go with Exception Handled)

gn (Go with Exception Not Handled)

Send comments about this topic to Microsoft

Share via

Additional resources

Share via

Related topics

Additional resources