Enabling Postmortem Debugging
The most common application errors are called exceptions. These include access violations, division-by-zero errors, numerical overflows, and many other kinds of errors.
Applications can also cause breakpoint interrupts. These occur when Windows is unable to run the application (for example, when a necessary module cannot be loaded) or when a breakpoint is encountered. Breakpoints can be inserted into the code by a debugger, or invoked through a function such as DbgBreakPoint.
Windows can handle user-mode errors in a variety of ways. The following sequence shows the precedence used for error handling:
If a user-mode debugger is currently attached to the faulting process, all errors will cause the target to break into this debugger.
As long as the user-mode debugger is attached, no other error-handling methods will be used -- even if the gn (Go With Exception Not Handled) command is used.
If no user-mode debugger is attached and the executing code has its own exception handling routines (for example, try - except), this exception handling routine will attempt to deal with the error.
If no user-mode debugger is attached, and Windows has an open kernel-debugging connection, and the error is a breakpoint interrupt, Windows will attempt to contact the kernel debugger.
Kernel debugging connections must be opened during Windows' boot process. If you are using Windows Server 2003 or a later version of Windows and wish to prevent a user-mode interrupt from breaking into the kernel debugger, you can use the KDbgCtrl utility with the -du parameter. For details on how to configure kernel-debugging connections and how to use KDbgCtrl, see Getting Set Up for Debugging.
If Windows does attempt to contact a kernel debugger but there is no debugger running at the other end of the connection, Windows will freeze until kernel debugger is activated.
In the kernel debugger, you can use gh (Go With Exception Handled) to disregard the error and continue running the target. You can use gn (Go With Exception Not Handled) to bypass the kernel debugger and go on to step 4.
If the conditions in steps 1, 2, and 3 do not apply, Windows will activate a debugging tool. Any program can be selected in advance as the tool to use in this situation. The chosen program is referred to as the postmortem debugger. This is also known as the just-in-time debugger or the JIT debugger.
- If the conditions in steps 1, 2, and 3 do not apply, and there is no postmortem debugger registered, Windows Error Reporting (WER) displays a message and provides solutions if any are available. WER also writes a memory dump file if the appropriate values are set in the Registry. For more information, see Using WER and Collecting User-Mode Dumps.
To set the postmortem debugger to WinDbg, run windbg -I. (The I must be capitalized.) This command will display a success or failure message after it is used. When WinDbg is the postmortem debugger, it will be activated whenever an application crashes.
To set the postmortem debugger to CDB, run cdb -iae or cdb -iaec KeyString. When the -iaec parameter is used, KeyString specifies a string to be appended to the end of command line used to launch the postmortem debugger. If KeyString contains spaces, it must be enclosed in quotation marks. This command will display no message if it succeeds, but will display a failure message if it fails. When CDB is the postmortem debugger, it will be activated whenever an application crashes.
To set the postmortem debugger to NTSD, run ntsd -iae or ntsd -iaec KeyString. When the -iaec switch is used, KeyString specifies a string to be appended to the end of command line used to launch the postmortem debugger. If KeyString contains spaces, it must be enclosed in quotation marks. This command will display no message if it succeeds, but will display a failure message if it fails. When NTSD is the postmortem debugger, it will be activated whenever an application crashes.
These methods will set the appropriate registry values so that the debugger will be automatically launched whenever an application crashes. The debugger command line will include the argument string -p %ld -e %ld -g. The -p %ld parameter specifies the process ID that will be debugged, the -e %ld parameter provides the event that caused the exception, and the -g parameter causes the debugger to skip the initial breakpoint. If the -iaec switch is used when installing CDB or NTSD as the postmortem debugger, the additional arguments specified as KeyString will then follow.
On a 64-bit platform, use a 32-bit post-mortem debugger for 32-bit processes and a 64-bit debugger for 64-bit processes. To accomplish this, run one of the -I or -i commands discussed in this topic twice: once using the 32-bit version of the debugger (WinDbg, CDB, or NTSD) and a second time using the 64-bit version.
If you run an -I or -i command in a 64-bit debugger, the post-mortem registry value for 32-bit processes will not be changed if it was previously set.
Only a system administrator can alter the postmortem settings.
If a postmortem debugger has been installed, you can deliberately break into the debugger from a user-mode application by calling the DebugBreak function.
The postmortem debugging settings are stored in the registry. If you wish to control these settings, it is recommended that you use the WinDbg, CDB, or NTSD commands described above; these will automatically change the relevant registry keys. If you do need to manually edit the registry, do so very carefully, because improper changes to the registry may render Windows unusable. The postmortem settings are stored under this registry key:
On a 64-bit platform, the postmortem settings for 32-bit processes are stored under this registry key:
These are the relevant registry entries:
This REG_SZ value specifies the debugger that will handle postmortem debugging. The full path to the debugger must be listed, unless the debugger is located in a directory that is in the default path.
This REG_SZ value is always either 0 or 1. If Auto is set to 0, a message box is displayed prior to postmortem debugging.
The following values can be used to set WinDbg as the postmortem debugger:
Debugger = "Path\WinDbg -p %ld -e %ld" Auto = 1
The following values can be used to set CDB as the postmortem debugger:
Debugger = "Path\CDB -p %ld -e %ld -g" Auto = 1
In these examples, Path is the directory where the debugger is located, -p %ld specifies the process ID that will be debugged, -e %ld provides the event that caused the exception, and -g causes the debugger to skip the initial breakpoint.
If you are considering enabling postmortem debugging on a computer that you share with other people, see Security During Postmortem Debugging.