Getting Started with WinDbg (User-Mode)
- 6 minutes to read
-
Contributors
WinDbg is a kernel-mode and user-mode debugger that is included in Debugging Tools for Windows. Here we provide hands-on exercises that will help you get started using WinDbg as a user-mode debugger.
For information about how to get Debugging Tools for Windows, see Debugging Tools for Windows (WinDbg, KD, CDB, NTSD). After you have installed the debugging tools, locate the installation directories for 64-bit (x64) and 32-bit (x86) versions of the tools. For example:
- C:\Program Files (x86)\Windows Kits\8.1\Debuggers\x64
- C:\Program Files (x86)\Windows Kits\8.1\Debuggers\x86
Launch Notepad and attach WinDbg
Navigate to your installation directory, and open WinDbg.exe.
On the Help menu, choose Contents. This opens the debugger documentation CHM file. The debugger documentation is also available on line here.
On the File menu, choose Open Executable. In the Open Executable dialog box, navigate to the folder that contains notepad.exe (for example, C:\Windows\System32). For File name, enter notepad.exe. Click Open.
Near the bottom of the WinDbg window, in the command line, enter this command:
The output is similar to this:
Symbol search path is: srv* Expanded Symbol search path is: cache*;SRV*https://msdl.microsoft.com/download/symbolsThe symbol search path tells WinDbg where to look for symbol (PDB) files. The debugger needs symbol files to obtain information about code modules (function names, variable names, and the like).
Enter this command, which tells WinDbg to do its initial finding and loading of symbol files:
To see the symbols for the Notepad.exe module, enter this command:
Note If you don't see any output, enter .reload again.
To see symbols in the Notepad.exe module that contain main, enter this command:
**x notepad!\*main\***
The output is similar to this:
```
000000d0`428ff7e8 00007ff6`3282122f notepad!WinMain
...
```
To put a breakpoint at notepad!WinMain, enter this command:
To verify that your breakpoint was set, enter this command:
The output is similar to this:
0 e 00007ff6`32825f64 0001 (0001) 0:**** notepad!WinMainTo start Notepad running, enter this command:
Notepad runs until it comes to the WinMain function, and then breaks in to the debugger.
To see a list of code modules that are loaded in the Notepad process, enter this command:
The output is similar to this:
0:000> lm start end module name 00007ff6`32820000 00007ff6`3285a000 notepad (pdb symbols) C:\...\notepad.pdb 00007ffc`ab7e0000 00007ffc`ab85b000 WINSPOOL (deferred) 00007ffc`aba10000 00007ffc`abc6a000 COMCTL32 (deferred) 00007ffc`adea0000 00007ffc`adf3f000 SHCORE (deferred) 00007ffc`af490000 00007ffc`af59f000 KERNELBASE (deferred) 00007ffc`af7d0000 00007ffc`af877000 msvcrt (deferred) 00007ffc`af880000 00007ffc`b0c96000 SHELL32 (deferred) 00007ffc`b0e40000 00007ffc`b0ef7000 OLEAUT32 (deferred) 00007ffc`b0f00000 00007ffc`b0f57000 sechost (deferred) 00007ffc`b0f60000 00007ffc`b1005000 ADVAPI32 (deferred) 00007ffc`b1010000 00007ffc`b1155000 GDI32 (deferred) 00007ffc`b1160000 00007ffc`b1296000 RPCRT4 (deferred) 00007ffc`b12a0000 00007ffc`b1411000 USER32 (deferred) 00007ffc`b1420000 00007ffc`b15f6000 combase (deferred) 00007ffc`b16c0000 00007ffc`b17f9000 MSCTF (deferred) 00007ffc`b1800000 00007ffc`b189a000 COMDLG32 (deferred) 00007ffc`b18a0000 00007ffc`b18f1000 SHLWAPI (deferred) 00007ffc`b1b60000 00007ffc`b1cd8000 ole32 (deferred) 00007ffc`b1cf0000 00007ffc`b1e2a000 KERNEL32 (pdb symbols) C:\...\kernel32.pdb 00007ffc`b1eb0000 00007ffc`b1ee4000 IMM32 (deferred) 00007ffc`b1f50000 00007ffc`b20fa000 ntdll (private pdb symbols) C:\...\ntdll.pdbTo see a stack trace, enter this command:
The output is similar to this:
Breakpoint 0 hit notepad!WinMain: 00007ff6`32825f64 488bc4 mov rax,rsp 0:000> k Child-SP RetAddr Call Site 00000048`4e0cf6a8 00007ff6`3282122f notepad!WinMain 00000048`4e0cf6b0 00007ffc`b1cf16ad notepad!WinMainCRTStartup+0x1a7 00000048`4e0cf770 00007ffc`b1fc4629 KERNEL32!BaseThreadInitThunk+0xd 00000048`4e0cf7a0 00000000`00000000 ntdll!RtlUserThreadStart+0x1d ...To start Notepad running again, enter this command:
To break in to Notepad, choose Break from the Debug menu.
To set and verify a breakpoint at ZwWriteFile, enter these commands:
Enter g to start Notepad running again. In the Notepad window, enter some text and choose Save from the File menu. The running code breaks in when it comes to ZwCreateFile. Enter k to see the stack trace.
In the WinDbg window, just to the left of the command line, notice the processor and thread numbers. In this example the current processor number is 0, and the current thread number is 11. So we are looking at the stack trace for thread 11 (which happens to be running on processor 0).
To see a list of all threads in the Notepad process, enter this command (the tilde):
The output is similar to this:
0:011> ~ 0 Id: 10c8.128c Suspend: 1 Teb: 00007ff6`31cdd000 Unfrozen 1 Id: 10c8.1a10 Suspend: 1 Teb: 00007ff6`31cdb000 Unfrozen 2 Id: 10c8.1850 Suspend: 1 Teb: 00007ff6`31cd9000 Unfrozen 3 Id: 10c8.1774 Suspend: 1 Teb: 00007ff6`31cd7000 Unfrozen 4 Id: 10c8.1e80 Suspend: 1 Teb: 00007ff6`31cd5000 Unfrozen 5 Id: 10c8.10ac Suspend: 1 Teb: 00007ff6`31cd3000 Unfrozen 6 Id: 10c8.13a4 Suspend: 1 Teb: 00007ff6`31bae000 Unfrozen 7 Id: 10c8.2b4 Suspend: 1 Teb: 00007ff6`31bac000 Unfrozen 8 Id: 10c8.1df0 Suspend: 1 Teb: 00007ff6`31baa000 Unfrozen 9 Id: 10c8.1664 Suspend: 1 Teb: 00007ff6`31ba8000 Unfrozen 10 Id: 10c8.15e4 Suspend: 1 Teb: 00007ff6`31ba6000 Unfrozen . 11 Id: 10c8.8bc Suspend: 1 Teb: 00007ff6`31ba4000 UnfrozenIn this example, there are 12 threads with indexes 0 through 11.
To look at the stack trace for thread 0, enter these commands:
The output is similar to this:
0:011> ~0s USER32!SystemParametersInfoW: 00007ffc`b12a4d20 48895c2408 mov qword ptr [rsp+8], ... 0:000> k Child-SP RetAddr Call Site 00000033`d1e9da48 00007ffc`adfb227d USER32!SystemParametersInfoW (Inline Function) --------`-------- uxtheme!IsHighContrastMode+0x1d 00000033`d1e9da50 00007ffc`adfb2f12 uxtheme!IsThemeActive+0x4d ... 00000033`d1e9f810 00007ffc`b1cf16ad notepad!WinMainCRTStartup+0x1a7 00000033`d1e9f8d0 00007ffc`b1fc4629 KERNEL32!BaseThreadInitThunk+0xd 00000033`d1e9f900 00000000`00000000 ntdll!RtlUserThreadStart+0x1dTo quit debugging and detach from the Notepad process, enter this command:
Launch your own application and attach WinDbg
Suppose you have written and built this small console application.
...
void MyFunction(long p1, long p2, long p3)
{
long x = p1 + p2 + p3;
long y = 0;
y = x / p2;
}
void main ()
{
long a = 2;
long b = 0;
MyFunction(a, b, 5);
}
For this exercise, we will assume that the built application (MyApp.exe) and the symbol file (MyApp.pdb) are in C:\MyApp\x64\Debug. We will also assume that the application source code is in C:\MyApp\MyApp.
Open WinDbg.
On the File menu, choose Open Executable. In the Open Executable dialog box, navigate to C:\MyApp\x64\Debug. For File name, enter MyApp.exe. Click Open.
Enter these commands:
.sympath+ C:\MyApp\x64\Debug
Now WinDbg knows where to find symbols and source code for your application.
Enter these commands:
Your application breaks in to the debugger when it comes to its main function.
WinDbg displays your source code and the Command window.
On the Debug menu, choose Step Into (or press F11). Continue stepping until you have stepped into MyFunction. When you step into the line
y = x / p2, your application will crash and break in to the debugger. The output is similar to this:(1450.1424): Integer divide-by-zero - code c0000094 (first chance) First chance exceptions are reported before any exception handling. This exception may be expected and handled. MyApp!MyFunction+0x44: 00007ff6`3be11064 f77c2428 idiv eax,dword ptr [rsp+28h] ss:00000063`2036f808=00000000Enter this command:
WinDbg displays an analysis of the problem (division by 0 in this case).
FAULTING_IP: MyApp!MyFunction+44 [c:\myapp\myapp\myapp.cpp @ 7] 00007ff6`3be11064 f77c2428 idiv eax,dword ptr [rsp+28h] EXCEPTION_RECORD: ffffffffffffffff -- (.exr 0xffffffffffffffff) ExceptionAddress: 00007ff63be11064 (MyApp!MyFunction+0x0000000000000044) ExceptionCode: c0000094 (Integer divide-by-zero) ExceptionFlags: 00000000 NumberParameters: 0 ... STACK_TEXT: 00000063`2036f7e0 00007ff6`3be110b8 : ... : MyApp!MyFunction+0x44 00000063`2036f800 00007ff6`3be1141d : ... : MyApp!main+0x38 00000063`2036f840 00007ff6`3be1154e : ... : MyApp!__tmainCRTStartup+0x19d 00000063`2036f8b0 00007ffc`b1cf16ad : ... : MyApp!mainCRTStartup+0xe 00000063`2036f8e0 00007ffc`b1fc4629 : ... : KERNEL32!BaseThreadInitThunk+0xd 00000063`2036f910 00000000`00000000 : ... : ntdll!RtlUserThreadStart+0x1d STACK_COMMAND: dt ntdll!LdrpLastDllInitializer BaseDllName ;dt ntdll!LdrpFailureData ;.cxr 0x0 ;kb FOLLOWUP_IP: MyApp!MyFunction+44 [c:\myapp\myapp\myapp.cpp @ 7] 00007ff6`3be11064 f77c2428 idiv eax,dword ptr [rsp+28h] FAULTING_SOURCE_LINE: c:\myapp\myapp\myapp.cpp FAULTING_SOURCE_FILE: c:\myapp\myapp\myapp.cpp FAULTING_SOURCE_LINE_NUMBER: 7 FAULTING_SOURCE_CODE: 3: void MyFunction(long p1, long p2, long p3) 4: { 5: long x = p1 + p2 + p3; 6: long y = 0; > 7: y = x / p2; 8: } 9: 10: void main () 11: { 12: long a = 2; ...
Summary of commands
- Contents command on the Help menu
- .sympath (Set Symbol Path)
- .reload (Reload Module)
- x (Examine Symbols)
- g (Go)
- Break command on the Debug menu
- lm (List Loaded Modules)
- k (Display Stack Backtrace)
- bu (Set Breakpoint)
- bl (Breakpoint List)
- ~ (Thread Status)
- ~s (Set Current Thread)
- .sympath+ (Set Symbol Path) append to existing symbol path
- .srcpath (Set Source Path)
- Step Into command on the Debug menu (F11)
- !analyze -v
- qd (Quit and Detach)