winedbg's doc

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



this patch updates the winedbg documentation
A+
Name:          doc_winedbg
ChangeLog:     updated winedbg documentation
License:       X11
GenDate:       2002/09/20 20:11:58 UTC
ModifiedFiles: documentation/debugger.sgml
AddedFiles:    
===================================================================
RCS file: /home/cvs/cvsroot/wine/wine/documentation/debugger.sgml,v
retrieving revision 1.11
diff -u -u -r1.11 debugger.sgml
--- documentation/debugger.sgml	3 Jul 2002 01:20:46 -0000	1.11
+++ documentation/debugger.sgml	19 Sep 2002 19:21:44 -0000
@@ -6,7 +6,7 @@
 
       <para>
         Written by &name-eric-pouech; <email>&email-eric-pouech;</email>
-	(Last updated: 6/14/2000)
+	(Last updated: 9/15/2002)
       </para>
       <para>
         (Extracted from <filename>wine/documentation/winedbg</filename>)
@@ -98,7 +98,7 @@
         </itemizedlist>
         <para>
           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
           (emulated or Winelib) using that API to debug a
           <varname>W-process</varname>.
@@ -153,7 +153,7 @@
       </sect2>
 
       <sect2 id="dbg-on-exception">
-        <title id="dbg-exception-title">On exception</title>
+        <title id="dbg-exception-title">On exceptions</title>
 
         <para>
           When something goes wrong, Windows tracks this as an
@@ -232,16 +232,26 @@
         </note>
       </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>
         <title>Quitting</title>
 
         <para>
-          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 <command>WineDbg</command>.
+	  Wine supports the new XP APIs, allowing for a debugger to
+	  detach from a program being debugged (see
+	  <command>detach</command> 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.  
         </para>
       </sect2>
     </sect1>
@@ -797,6 +807,17 @@
                   </para>
                 </listitem>
               </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>
           </listitem>
         </itemizedlist>
@@ -831,8 +852,8 @@
   info reg           (to see registers)
   info stack         (to see hex values in the stack)
   info local         (to see local variables)
-  list &lt;line number> (to list source code)
-  x &lt;variable name>  (to examine a variable; only works if code
+  list &lt;line number&gt; (to list source code)
+  x &lt;variable name&gt;  (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 @@
           You can use the symbol <emphasis>EntryPoint</emphasis> to stand for
           the entry point of the Dll.
         </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>
@@ -1381,7 +1406,9 @@
 show dir
 dir &lt;pathname&gt;
 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>
 list		lists 10 source lines from current position
@@ -1459,6 +1486,8 @@
 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)
         </screen>
       </sect2>
 
@@ -1485,9 +1514,9 @@
 x =&gt; 32 bit unsigned hexadecimal integer
 d =&gt; 32 bit signed decimal integer
 w =&gt; 16 bit unsigned hexadecimal integer
-c =&gt; character (only printable 0x20-0x7f are actually
-     printed)
+c =&gt; character (only printable 0x20-0x7f are actuallyprinted)
 b =&gt; 8 bit unsigned hexadecimal integer
+g =&gt; GUID
         </screen>
       </sect2>
 
@@ -1500,8 +1529,9 @@
 	  <itemizedlist>
 	    <listitem>
 	      <para>
-		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
+		<function>USER32.DLL.CreateWindowA</function>.
 	      </para>
 	    </listitem>
 	    <listitem>
@@ -1515,7 +1545,7 @@
 	</para>
       </sect2>
       <sect2>
-          <title>debug messages</title>
+          <title>Debug channels</title>
 	      <para>
                It is possible to turn on and off debug messages as you are debuging using
                the set command.
@@ -1534,6 +1564,49 @@
       <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>
         <title>Using other Unix debuggers</title>
 
         <para>
@@ -1640,25 +1713,40 @@
 
       <sect2>
         <title>Main differences between winedbg and regular Unix debuggers</title>
-
-        <!-- FIXME: convert this into a table -->
-        <screen>
-+----------------------------------+---------------------------------+
-|             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   |                                 |
-+----------------------------------+---------------------------------+
-        </screen>
+	<table><title>Debuggers comparison</title>
+	  <tgroup cols=2 align="left">
+	    <tbody>
+	      <row>
+		<entry>WineDbg</entry><entry>gdb</entry>
+	      </row>
+	      <row>
+		<entry>
+		  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 
+                </entry>
+	        <entry>
+		  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 
+                </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>
     </sect1>
 
@@ -1666,11 +1754,19 @@
     <sect1 id="dbg-limits">
       <title>Limitations</title>
 
-      <para>
-        16 bit processes are not supported (but calls to 16 bit code
-        in 32 bit  applications are).
-      </para>
-
+      <itemizedlist>
+	<listitem>
+	  <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>
   </chapter>
 

[Index of Archives]     [Gimp for Windows]     [Red Hat]     [Samba]     [Yosemite Camping]     [Graphics Cards]     [Wine Home]

  Powered by Linux