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.

Command	Status name	Description
SXE or -xe	Break (Enabled)	When this exception occurs, the target immediately breaks into the debugger. This break in occurs before any other error handlers are activated. This method is called first-chance handling.
SXD or -xd	Second chance break (Disabled)	The debugger does not break in for this kind of first-chance exception (although a message is displayed). If other error handlers cannot address this exception, execution stops and the target breaks into the debugger. This method is called second-chance handling.
SXN or -xn	Output (Notify)	When this exception occurs, the target application does not break into the debugger at all. However, a message is displayed that informs the user of this exception.
SXI or -xi	Ignore	When this exception occurs, the target application does not break into the debugger, and no message is displayed.

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.

Command	Status name	Description
SXE	Handled	The event is considered handled when execution resumes.
SXD,SXN,SXI	Not Handled	The event is considered not handled when execution resumes.

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.

Event code	Meaning	Default break status
asrt	Assertion failure	Break
av	Access violation	Break
dm	Data misaligned	Break
dz	Integer division by zero	Break
c000008e	Floating point division by zero	Break
eh	C++ EH exception	Second-chance break
gp	Guard page violation	Break
ii	Illegal instruction	Second-chance break
iov	Integer overflow	Break
ip	In-page I/O error	Break
isc	Invalid system call	Break
lsq	Invalid lock sequence	Break
sbo	Stack buffer overflow	Break
sov	Stack overflow	Break
wkd	Wake debugger	Break
aph	Application hang This exception is triggered if the Windows operating system concludes that a process has stopped responding (that is, is hung).	Break
3c	Child application termination	Second-chance break
chhc	Invalid handle	Break
Number	Any numbered exception	Second-chance break

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.

Event code	Meaning	Default break status
dbce	Special debugger command exception	Ignore
vcpp	Special Visual C++ exception	Ignore
wos	WOW64 single-step exception	Break
wob	WOW64 breakpoint exception-	Break
sse ssec	Single-step exception	Break
bpe bpec	Breakpoint exception	Break
cce cc	CTRL+C or CTRL+BREAK This exception is triggered if the target is a console application and CTRL+C or CTRL+BREAK is passed to it.	Break

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.

Event code	Meaning	Default status
clr	Common Language Runtime exception	Second-chance break Not handled
clrn	Common Language Runtime notification exception	Second-chance break Handled

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

Event code	Meaning	Default break status
ser	System error	Ignore
cpr[:Process]	Process creation Setting the break status of this event applies only to user-mode debugging. This event does not occur in kernel mode. You can control this event only if you have activated debugging of child processes in CDB or WinDbg, either through the -ocommand-line option or through the .childdbg (Debug Child Processes) command. The process name can include an optional file name extension and an asterisk () or question mark (?) as wildcard characters. The debugger remembers only the most recent cpr setting. Separate settings for separate processes are not supported. Include a colon or a space between cpr and Process. If Process is omitted, the setting applies to any child process creation.	Ignore
epr[:Process]	Process exit Setting the break status of this event applies only to user-mode debugging. This event does not occur in kernel mode. You can control this event only if you have activated debugging of child processes in CDB or WinDbg, either through the -ocommand-line option or through the .childdbg (Debug Child Processes) command. The process name can include an optional file name extension and an asterisk () or question mark (?) as wildcard characters. The debugger remembers only the most recent epr setting. Separate settings for separate processes are not supported. Include a colon or a space between epr and Process. If Process is omitted, the setting applies to any child process exit.	Ignore
ct	Thread creation	Ignore
et	Thread exit	Ignore
ld[:Module]	Load module If you specify Module, the break occurs when the module with this name is loaded. Module can specify the name or the address of the module. If the name is used, Module might contain a variety of wildcard characters and specifiers. (For more information about the syntax, see String Wildcard Syntax.) The debugger remembers only the most recent ld setting. Separate settings for separate modules are not supported. Include a colon or a space between ld and Module. If Module is omitted, the event is triggered when any module is loaded.	Output
ud[:Module]	Unload module If you specify Module, the break occurs when the module with this name, or at this base address, is unloaded. Module can specify the name or the address of the module. If the name is used, Module can be an exact name or include wildcard characters. If Module is an exact name, it is immediately resolved to a base address by using the current debugger module list and it is stored as an address. If Module contains wildcard characters, the pattern string is kept for later matching when unload events occur. Rarely, the debugger does not have name information for unload events and matches only by the base address. Therefore, if Module contains wildcard characters, the debugger cannot perform a name match in this particular unload case and breaks when any module is unloaded. The debugger remembers only the most recent ud setting. Separate settings for separate modules are not supported. Include a colon or a space between ud and Module. If Module is omitted, the event is triggered when any module is loaded.	Output
out[:Output]	Target application output If you specify Output, the break occurs only when output that matches the specified pattern is received. Output can contain a variety of wildcard characters and specifiers. (For more information about the syntax, see String Wildcard Syntax.) However, Output cannot contain a colon or spaces. The match is not case sensitive. Include a colon or space between out and Output.	Ignore
ibp	Initial break point (This event occurs at the beginning of the debug session and after you restart the target computer.)	In user mode: Break. You can change this status to "Ignore" by using the -gcommand-line option. In kernel mode: Ignore. You can change this status to "Enabled" by a variety of methods. For more information about how to change this status, see Crashing and Rebooting the Target Computer.
iml	Initial module load (Kernel mode only)	Ignore. You can change this status to "Break" by a variety of methods. For more information about how to change this status, see Crashing and Rebooting the Target Computer.