system/wine
system/wine
1
0
Fork 0
mirror of git://source.winehq.org/git/wine.git synced 2024-08-31 11:04:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated winedbg documentation.

Browse source
This commit is contained in:
Eric Pouech 2002-09-21 01:17:32 +00:00 committed by Alexandre Julliard
parent 6c39d4130a
commit 0996541cc6
1 changed files with 137 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

178
documentation/debugger.sgml
View file

@ -6,7 +6,7 @@
<para> <para>
Written by &name-eric-pouech; <email>&email-eric-pouech;</email> Written by &name-eric-pouech; <email>&email-eric-pouech;</email>
(Last updated: 6/14/2000) (Last updated: 9/15/2002)
</para> </para>
<para> <para>
(Extracted from <filename>wine/documentation/winedbg</filename>) (Extracted from <filename>wine/documentation/winedbg</filename>)
@ -98,7 +98,7 @@
</itemizedlist> </itemizedlist>
<para> <para>
Wine implements most of the Windows' debugging API (the Wine implements most of the Windows' debugging API (the
part in KERNEL32, not the one in part in <filename>KERNEL32.DLL</filename>, not the one in
<filename>IMAGEHLP.DLL</filename>), and allows any program <filename>IMAGEHLP.DLL</filename>), and allows any program
(emulated or Winelib) using that API to debug a (emulated or Winelib) using that API to debug a
<varname>W-process</varname>. <varname>W-process</varname>.
@ -153,7 +153,7 @@ winedbg "hl.exe -windowed"
</sect2> </sect2>
<sect2 id="dbg-on-exception"> <sect2 id="dbg-on-exception">
<title id="dbg-exception-title">On exception</title> <title id="dbg-exception-title">On exceptions</title>
<para> <para>
When something goes wrong, Windows tracks this as an When something goes wrong, Windows tracks this as an
@ -232,16 +232,26 @@ winedbg "hl.exe -windowed"
</note> </note>
</sect2> </sect2>
<sect2 id="interrupt">
<title>Interrupting</title>
<para>
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
</para>
</sect2>
<sect2> <sect2>
<title>Quitting</title> <title>Quitting</title>
<para> <para>
Unfortunately, Windows doesn't provide a detach kind of API, Wine supports the new XP APIs, allowing for a debugger to
meaning that once you started debugging a process, you must detach from a program being debugged (see
do so until the process dies. Killing (or stopping/aborting) <command>detach</command> command). Unfortunately, as the
the debugger will also kill the debugged process. This will debugger cannot, for now, neither clear its internal
be true for any Windows' debugging API compliant debugger, information, nor restart a new process, the debugger, after
starting with <command>WineDbg</command>. detaching itself, cannot do much except being quited.
</para> </para>
</sect2> </sect2>
</sect1> </sect1>
@ -797,6 +807,17 @@ Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term>
<application>winedump</application>:
</term>
<listitem>
<para>
Dumps the imports and exports of a PE (Portable
Executable) DLL (included in wine tree).
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -831,8 +852,8 @@ wine -debug myprog.exe
info reg (to see registers) info reg (to see registers)
info stack (to see hex values in the stack) info stack (to see hex values in the stack)
info local (to see local variables) info local (to see local variables)
list &lt;line number> (to list source code) list &lt;line number&gt; (to list source code)
x &lt;variable name> (to examine a variable; only works if code x &lt;variable name&gt; (to examine a variable; only works if code
is not compiled with optimization) is not compiled with optimization)
x 0x4269978 (to examine a memory location) x 0x4269978 (to examine a memory location)
? (help) ? (help)
@ -1354,6 +1375,10 @@ info break lists all (break|watch)points (with state)
You can use the symbol <emphasis>EntryPoint</emphasis> to stand for You can use the symbol <emphasis>EntryPoint</emphasis> to stand for
the entry point of the Dll. the entry point of the Dll.
</para> </para>
<para>
When setting a break/watch-point by &lt;id&gt;, 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).
</para>
</sect2> </sect2>
<sect2> <sect2>
@ -1381,7 +1406,9 @@ info local prints information on local variables for current
show dir show dir
dir &lt;pathname&gt; dir &lt;pathname&gt;
dir dir
symbolfile &lt;module&gt; &lt;pathname&gt; symbolfile &lt;pathname&gt; loads external symbol definition
symbolfile &lt;pathname&gt; N loads external symbol definition
(applying an offset of N to addresses)
</screen> </screen>
<screen> <screen>
list lists 10 source lines from current position 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 process lists all w-processes in Wine session
walk thread lists all w-threads in Wine session walk thread lists all w-threads in Wine session
walk modref (no longer avail) walk modref (no longer avail)
walk exception lists the exception frames (starting from current
stack frame)
</screen> </screen>
</sect2> </sect2>
@ -1485,9 +1514,9 @@ i =&gt; instructions (disassemble)
x =&gt; 32 bit unsigned hexadecimal integer x =&gt; 32 bit unsigned hexadecimal integer
d =&gt; 32 bit signed decimal integer d =&gt; 32 bit signed decimal integer
w =&gt; 16 bit unsigned hexadecimal integer w =&gt; 16 bit unsigned hexadecimal integer
c =&gt; character (only printable 0x20-0x7f are actually c =&gt; character (only printable 0x20-0x7f are actuallyprinted)
printed)
b =&gt; 8 bit unsigned hexadecimal integer b =&gt; 8 bit unsigned hexadecimal integer
g =&gt; GUID
</screen> </screen>
</sect2> </sect2>
@ -1500,8 +1529,9 @@ b =&gt; 8 bit unsigned hexadecimal integer
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
Identifiers can take a '.' in their names. This allow mainly to access symbols Identifiers can take a '.' in their names. This allow
from different DLLs like USER32.DLL.CreateWindowA mainly to access symbols from different DLLs like
<function>USER32.DLL.CreateWindowA</function>.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -1515,7 +1545,7 @@ b =&gt; 8 bit unsigned hexadecimal integer
</para> </para>
</sect2> </sect2>
<sect2> <sect2>
<title>debug messages</title> <title>Debug channels</title>
<para> <para>
It is possible to turn on and off debug messages as you are debuging using It is possible to turn on and off debug messages as you are debuging using
the set command. the set command.
@ -1533,6 +1563,49 @@ set - fixme =&gt; turn off the 'fixme' class
<sect1 id="dbg-others"> <sect1 id="dbg-others">
<title>Other debuggers</title> <title>Other debuggers</title>
<sect2>
<title>GDB mode</title>
<para>
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
<parameter>--gdb</parameter> to winedbg command line. You'll
end up on a GDB prompt. You'll have to use the GDB commands
(not the wine nes).
</para>
<para>
However, some limitation in GDB while debugging wine (see
below) don't ppear in this mode:
<itemizedlist>
<listitem>
<para>
GDB will correctly present Win32 thread
information and breakpoint behavior
</para>
</listitem>
<listitem>
<para>
Moreover, it also provides support for the Dwarf II
debug format (which became the default format (instead
of stabs) in gcc 3.1).
</para>
</listitem>
</itemizedlist>
</para>
<para>
A few wine extensions available through the monitor command.
<screen>
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)
</screen>
</para>
</sect2>
<sect2> <sect2>
<title>Using other Unix debuggers</title> <title>Using other Unix debuggers</title>
@ -1640,25 +1713,40 @@ $ gdb wine
<sect2> <sect2>
<title>Main differences between winedbg and regular Unix debuggers</title> <title>Main differences between winedbg and regular Unix debuggers</title>
<table><title>Debuggers comparison</title>
<!-- FIXME: convert this into a table --> <tgroup cols=2 align="left">
<screen> <tbody>
+----------------------------------+---------------------------------+ <row>
| WineDbg | gdb | <entry>WineDbg</entry><entry>gdb</entry>
+----------------------------------+---------------------------------+ </row>
|WineDbg debugs a Windows' process:|gdb debugs a Windows' thread: | <row>
|+ the various threads will be |+ a separate gdb session is | <entry>
| handled by the same WineDbg | needed for each thread of | WineDbg debugs a Windows' process: the various
| session | Windows' process | threads will be handled by the same WineDbg session,
|+ a breakpoint will be triggered |+ a breakpoint will be triggered | and a breakpoint will be triggered for any thread of
| for any thread of the w-process | only for the w-thread debugged | the W-process
+----------------------------------+---------------------------------+ </entry>
|WineDbg supports debug information|gdb supports debug information | <entry>
|from: |from: | gdb debugs a Windows' thread: a separate gdb session
|+ stabs (standard Unix format) |+ stabs (standard Unix format) | is needed for each thread of a Windows' process and
|+ Microsoft's C, CodeView, .DBG | | a breakpoint will be triggered only for the w-thread
+----------------------------------+---------------------------------+ debugged
</screen> </entry>
</row>
<row>
<entry>
WineDbg supports debug information from stabs
(standard Unix format) and Microsoft's C, CodeView,
.DBG
</entry>
<entry>
GDB supports debug information from stabs (standard
Unix format) and Dwarf II.
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2> </sect2>
</sect1> </sect1>
@ -1666,11 +1754,19 @@ $ gdb wine
<sect1 id="dbg-limits"> <sect1 id="dbg-limits">
<title>Limitations</title> <title>Limitations</title>
<para> <itemizedlist>
16 bit processes are not supported (but calls to 16 bit code <listitem>
in 32 bit applications are). <para>
</para> 16 bit processes are not supported (but calls to 16 bit
code in 32 bit applications are).
</para>
</listitem>
<listitem>
<para>
Function call in expression is no longer supported
</para>
</listitem>
</itemizedlist>
</sect1> </sect1>
</chapter> </chapter>