Controlling Exceptions and Events

You can catch and handle exceptions in user-mode and kernel-mode applications by a variety of methods. An active debugger, a postmortem debugger, or an internal error handling routine are all common ways to handle exceptions.

For more information about the precedence order of these various exception handlers, see Enabling Postmortem Debugging.

When the Microsoft Windows operating system allows a debugger to handle an exception, the application that generated the exception breaks into the debugger. That is, the application stops and the debugger becomes active. The debugger can then handle the exception in some way or analyze the situation. The debugger can then end the process or let it resume running.

If the debugger ignores the exception and lets the application continue running, the operating system looks for other exception handlers as if no debugger was present. If the exception is handled, the application continues running. However, if the exception remains unhandled, the debugger is then given a second opportunity to deal with the situation.

Using the Debugger to Analyze an Exception

When an exception or event breaks into the debugger, you can use the debugger to examine the code that is being executed and the memory that the application is using. By altering certain quantities or jumping to a different point in the application, you might be able to remove the cause of the exception.

You can resume execution by issuing a gh (Go with Exception Handled) or gn (Go with Exception Not Handled) command.

If you issue the gn command in the debugger's second opportunity to handle the exception, the application ends.

Kernel-Mode Exceptions

Exceptions that occur in kernel-mode code are more serious than user-mode exceptions. If kernel-mode exceptions are not handled, a bug check is issued and the system stops.

As with user-mode exceptions, if a kernel-mode debugger is attached to the system, the debugger is notified before the bug check screen (also known as a blue screen) appears. If no debugger is attached, the bug check screen appears. In this case, the operating system might create a crash dump file.

Controlling Exceptions and Events from the Debugger

You can configure the debugger to react to specified exceptions and events in a specific way.

The debugger can set the break status for each exception or event:

• The event can cause a break into the debugger as soon as it occurs (the "first chance").

• The event can break in after other error handlers have been given an opportunity to respond (the "second chance").

• The event can also send the debugger a message but continue executing.

• The debugger can ignore the event.

The debugger can also set the handling status for each exception and event. The debugger can treat the event like a handled exception or an unhandled exception. (Of course, events that are not actually errors do not require any handling.)

You can control the break status and handling status by doing one of the following:

• Use the SXE, SXD, SXN, or SXI command in the Debugger Command window.

• (CDB and NTSD) Use the -x, -xe, -xd, -xn, or -xi option on the command line.

• (CDB, NTSD, and KD) Use the sxe or sxd keyword in the Tools.ini file.

• (WinDbg only) Select Event Filters on the Debug menu to open the Event Filters dialog box, and then choose the options that you want.

The SX\* command, the -x\* command-line option, and the sx\* Tools.ini keyword typically set the break status of the specified event. You can add the -h option to cause the handling status to be set instead.

There are four special event codes (cc, hc, bpec, and ssec) that always specify handling status instead of break status.

You can display the most recent exception or event by using the .lastevent (Display Last Event) command.

Controlling Break Status

When you set the break status of an exception or event, you can use the following options.

If an exception is not anticipated by an SX* setting, the target application breaks into the debugger on the second chance. The default status for events is listed in the following "Event Definitions and Defaults" section of this topic.

To set break status by using the WinDbg graphical interface, Event Filters on the Debug menu select the event that you want from the list in the Event Filters dialog box, and then select Enabled, Disabled, Output, or Ignore.

Controlling Handling Status

All events are considered unhandled, unless you use the gh (Go with Exception Handled) command.

All exceptions are considered unhandled, unless you use the sx\* command together with the -h option.

Additionally, SX* options can configure the handling status for invalid handles, STATUS_BREAKPOINT break instructions, and single-step exceptions. (This configuration is separate from their break configuration.) When you configure their break status, these events are named ch, bpe, and sse, respectively. When you configure their handling status, these events are named hc, bpec, and ssec, respectively. (For the full listing of events, see the following "Event Definitions and Defaults" section.)

You can configure the handling status for the CTRL+C event (cc), but not its break status. If an application receives a CTRL+C event, the application always breaks into the debugger.

When you use the SX* command on cc, hc, bpec, and ssec events, or when you use the SX* command together with the -h option on an exception, the following actions occur.

To set handling status by using the WinDbg graphical interface, select Event Filters on the Debug menu, select the event that you want from the list in the Event Filters dialog box, and then select Handled or Not Handled.

Automatic Commands

The debugger also enables you to set commands that are automatically executed if the event or exception causes a break into the debugger. You can set a command string for the first-chance break and a command string for the second-chance break. You can set these strings with the SX\* command or the Debug | Event Filters command. Each command string can contain multiple commands that are separated with semicolons.

These commands are executed regardless of the break status. That is, if the break status is "Ignore," the command is still executed. If the break status is "Second-chance break," the first-chance command is executed when the exception first occurs, before any other exception handlers are involved. The command string can end with an execution command such as g (Go), gh (Go with Exception Handled), or gn (Go with Exception Not Handled).

Event Definitions and Defaults

You can change the break status or handling status of the following exceptions. Their default break status is indicated.

The following exceptions' default handling status is always "Not Handled". Be careful about changing this status. If you change this status to "Handled", all first-chance and second-chance exceptions of this type are considered handled, and this configuration bypasses all of the exception-handling routines.

Note   You can override the asrt break status for a specific address by using the ah (Assertion Handling) command. The ch and hc event codes refer to the same exception. When you are controlling its break status, use sx* ch. When you are controlling its handling status, use sx* hc.

You can change the break status or handling status of the following exceptions. Their default break status is indicated.

The following exceptions' default handling status is always "Handled". Because these exceptions are used to communicate with the debugger, you should not typically change their status to "Not Handled". This status causes other exception handlers to catch the exceptions if the debugger ignores them.

An application can use DBG_COMMAND_EXCEPTION (dbce) to communicate with the debugger. This exception is similar to a breakpoint, but you can use the SX* command to react in a specific way when this exception occurs.

Note   The final three exceptions in the preceding table have two different event codes. When you are controlling their break status, use sse, bpe, and cce. When you are controlling their handling status, use ssec, bpec, and cc.

The following exceptions are useful when you are debugging managed code.

You can change the break status of the following events. Because these events are not exceptions, their handling status is irrelevant.