From 0996541cc6312bba5e5140837385fc7d06eeb573 Mon Sep 17 00:00:00 2001 From: Eric Pouech Date: Sat, 21 Sep 2002 01:17:32 +0000 Subject: [PATCH] Updated winedbg documentation. --- documentation/debugger.sgml | 178 +++++++++++++++++++++++++++--------- 1 file changed, 137 insertions(+), 41 deletions(-) diff --git a/documentation/debugger.sgml b/documentation/debugger.sgml index 607227326cb..a1d661b430e 100644 --- a/documentation/debugger.sgml +++ b/documentation/debugger.sgml @@ -6,7 +6,7 @@ Written by &name-eric-pouech; &email-eric-pouech; - (Last updated: 6/14/2000) + (Last updated: 9/15/2002) (Extracted from wine/documentation/winedbg) @@ -98,7 +98,7 @@ Wine implements most of the Windows' debugging API (the - part in KERNEL32, not the one in + part in KERNEL32.DLL, not the one in IMAGEHLP.DLL), and allows any program (emulated or Winelib) using that API to debug a W-process. @@ -153,7 +153,7 @@ winedbg "hl.exe -windowed" - On exception + On exceptions When something goes wrong, Windows tracks this as an @@ -232,16 +232,26 @@ winedbg "hl.exe -windowed" + + Interrupting + + + You can stop the debugger while it's running by hitting + Ctrl-C in its window. This will stop the debugged process, + and let you manipulate the current context + + + Quitting - Unfortunately, Windows doesn't provide a detach kind of API, - meaning that once you started debugging a process, you must - do so until the process dies. Killing (or stopping/aborting) - the debugger will also kill the debugged process. This will - be true for any Windows' debugging API compliant debugger, - starting with WineDbg. + Wine supports the new XP APIs, allowing for a debugger to + detach from a program being debugged (see + detach command). Unfortunately, as the + debugger cannot, for now, neither clear its internal + information, nor restart a new process, the debugger, after + detaching itself, cannot do much except being quited. @@ -797,6 +807,17 @@ Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff + + + winedump: + + + + Dumps the imports and exports of a PE (Portable + Executable) DLL (included in wine tree). + + + @@ -831,8 +852,8 @@ wine -debug myprog.exe info reg (to see registers) info stack (to see hex values in the stack) info local (to see local variables) - list <line number> (to list source code) - x <variable name> (to examine a variable; only works if code + list <line number> (to list source code) + x <variable name> (to examine a variable; only works if code is not compiled with optimization) x 0x4269978 (to examine a memory location) ? (help) @@ -1354,6 +1375,10 @@ info break lists all (break|watch)points (with state) You can use the symbol EntryPoint to stand for the entry point of the Dll. + + When setting a break/watch-point by <id>, if the symbol cannot be found (for example, the symbol is contained in a not yet loaded module), winedbg will + recall the name of the symbol and will try to set the breakpoint each time a new module is loaded (until it succeeds). + @@ -1381,7 +1406,9 @@ info local prints information on local variables for current show dir dir <pathname> dir -symbolfile <module> <pathname> +symbolfile <pathname> loads external symbol definition +symbolfile <pathname> N loads external symbol definition + (applying an offset of N to addresses) list lists 10 source lines from current position @@ -1459,6 +1486,8 @@ walk wnd N lists all the window hierarchy starting from the walk process lists all w-processes in Wine session walk thread lists all w-threads in Wine session walk modref (no longer avail) +walk exception lists the exception frames (starting from current + stack frame) @@ -1485,9 +1514,9 @@ i => instructions (disassemble) x => 32 bit unsigned hexadecimal integer d => 32 bit signed decimal integer w => 16 bit unsigned hexadecimal integer -c => character (only printable 0x20-0x7f are actually - printed) +c => character (only printable 0x20-0x7f are actuallyprinted) b => 8 bit unsigned hexadecimal integer +g => GUID @@ -1500,8 +1529,9 @@ b => 8 bit unsigned hexadecimal integer - Identifiers can take a '.' in their names. This allow mainly to access symbols - from different DLLs like USER32.DLL.CreateWindowA + Identifiers can take a '.' in their names. This allow + mainly to access symbols from different DLLs like + USER32.DLL.CreateWindowA. @@ -1515,7 +1545,7 @@ b => 8 bit unsigned hexadecimal integer - debug messages + Debug channels It is possible to turn on and off debug messages as you are debuging using the set command. @@ -1533,6 +1563,49 @@ set - fixme => turn off the 'fixme' class Other debuggers + + GDB mode + + + WineDbg can act as a remote monitor for GDB. This allows to + use all the power of GDB, but while debugging wine and/or + any Win32 application. To enable this mode, just add + --gdb to winedbg command line. You'll + end up on a GDB prompt. You'll have to use the GDB commands + (not the wine nes). + + + + However, some limitation in GDB while debugging wine (see + below) don't ppear in this mode: + + + + GDB will correctly present Win32 thread + information and breakpoint behavior + + + + + Moreover, it also provides support for the Dwarf II + debug format (which became the default format (instead + of stabs) in gcc 3.1). + + + + + + + A few wine extensions available through the monitor command. + +monitor wnd lists all window in the Wine session +monitor proc lists all processes in the Wine session +monitor mem displays memory mapping of debugged process + (doesn't work) + + + + Using other Unix debuggers @@ -1640,25 +1713,40 @@ $ gdb wine Main differences between winedbg and regular Unix debuggers - - - -+----------------------------------+---------------------------------+ -| WineDbg | gdb | -+----------------------------------+---------------------------------+ -|WineDbg debugs a Windows' process:|gdb debugs a Windows' thread: | -|+ the various threads will be |+ a separate gdb session is | -| handled by the same WineDbg | needed for each thread of | -| session | Windows' process | -|+ a breakpoint will be triggered |+ a breakpoint will be triggered | -| for any thread of the w-process | only for the w-thread debugged | -+----------------------------------+---------------------------------+ -|WineDbg supports debug information|gdb supports debug information | -|from: |from: | -|+ stabs (standard Unix format) |+ stabs (standard Unix format) | -|+ Microsoft's C, CodeView, .DBG | | -+----------------------------------+---------------------------------+ - + Debuggers comparison + + + + WineDbggdb + + + + WineDbg debugs a Windows' process: the various + threads will be handled by the same WineDbg session, + and a breakpoint will be triggered for any thread of + the W-process + + + gdb debugs a Windows' thread: a separate gdb session + is needed for each thread of a Windows' process and + a breakpoint will be triggered only for the w-thread + debugged + + + + + WineDbg supports debug information from stabs + (standard Unix format) and Microsoft's C, CodeView, + .DBG + + + GDB supports debug information from stabs (standard + Unix format) and Dwarf II. + + + + +
@@ -1666,11 +1754,19 @@ $ gdb wine Limitations - - 16 bit processes are not supported (but calls to 16 bit code - in 32 bit applications are). - - + + + + 16 bit processes are not supported (but calls to 16 bit + code in 32 bit applications are). + + + + + Function call in expression is no longer supported + + +