Geoff Chappell - Software Analyst
CURRENT WORK ITEM - PREVIEW ONLY
The !stackdbg command sets options for stack walking.
!stackdbg [options] [mask]
The options are a sequence of option elements separated by any number, including none, of spaces or tabs. Each option is a hyphen or forward slash followed immediately by one or two characters. The options may be followed by any number, including none, of spaces or tabs before the mask, which is an expression.
An option is any of the following (with either a hyphen or forward slash):
| Option | Interpretation |
|---|---|
| /c | send stack-walk debug text through callback |
| /d | send stack-walk debug text as debug output |
| /sfeature | enable feature |
| /Sfeature | disable feature |
Though feature immediately after /s or /S stands for any single character, only the following such characters actually do correspond to a feature that can be enabled or disabled:
| Feature | Interpretation |
|---|---|
| 7 | VC7 FPO |
| l | LOP frame unwind |
| i | symbol info |
| r | return search |
| L | Force LOP frame unwind |
The mask is interpreted in bits, such that higher bits represent less severe grades of debug text. Evaluation to zero has the effect that stack-walk debug text is disabled. An absent mask evaluates as zero.
The !stackdbg command and equivalent stackdbg function are implemented in DBGHELP.DLL. They affect all that module’s stack-walking services, most notably the StackWalk64 function, including its use for the k command in debuggers (such as WinDbg) that are DBGENG clients.
The command acts on the options and mask in their given order to change the current settings, and then displays what are now the current settings. The initial settings are that “VC7 FPO” and “symbol info” are enabled, and everything else is disabled.
Diagnostic text for stack walking is enabled if mask evaluates as non-zero. Specifically, each set bit in mask enables diagnostic text of the corresponding severity. DBGHELP has diagnostic text for bits 0x01, 0x02, 0x04 and 0x08. The /c and /d options select from two modes for output. The /d option is straightforward: the text is sent to a debugger. (Just for clarity, note that if DBGHELP is executing in a debugger, then the text goes to a debugger of the debugger.) The /c option sends the text through whichever of various other mechanisms are active. Most notable is a symbol server callback, but the text is also written to a log file (if configured through the DBGHELP_LOG environment variable) or to a debugger (if enabled by the DBGHELP_DBGOUT environment variable).
The /s and /S options enable and disable various features of DBGHELP’s stack-walking algorithm for the X86 architecture. Microsoft’s documentation of StackWalk64 speaks of “all the complexities associated with stack walking on platforms” but omits to mention these options for configuring how DBGHELP negotiates those complexities.
The stackdbg function is exported from DBGHELP.DLL as a 64-bit WinDbg extension command, making it accessible as the command !stackdbg in any sufficiently recent DBGENG client. In terms of versions distributed with Windows, as opposed to the separate package of Debugging Tools for Windows, it is available in Windows Vista and Windows Server 2003 but not in Windows XP.