documentation/debugger.sgml

   1   <chapter id="debugger">
   2     <title>The Wine Debugger</title>
   3
   4     <sect1 id="dbg-intro">
   5       <title>I Introduction</title>
   6
   7       <para>
   8         written by Eric Pouech (???) (Last updated: 6/14/2000)
   9       </para>
  10       <para>
  11         (Extracted from <filename>wine/documentation/winedbg</filename>)
  12       </para>
  13
  14       <sect2>
  15         <title>I.1 Processes and threads: in underlying OS and in Windows</title>
  16
  17         <para>
  18           Before going into the depths of debugging in Wine, here's
  19           a small overview of process and thread handling in Wine.
  20           It has to be clear that there are two different beasts:
  21           processes/threads from the Unix point of view and
  22           processes/threads from a Windows point of view.
  23         </para>
  24         <para>
  25           Each Windows' thread is implemented as a Unix process (under
  26           Linux using the <function>clone</function> syscall), meaning
  27           that all threads of a same Windows' process share the same
  28           (unix) address space.
  29         </para>
  30         <para>
  31           In the following:
  32         </para>
  33         <itemizedlist>
  34           <listitem>
  35             <para><varname>W-process</varname> means a process in Windows' terminology</para>
  36           </listitem>
  37           <listitem>
  38             <para><varname>U-process</varname> means a process in Unix' terminology</para>
  39           </listitem>
  40           <listitem>
  41             <para><varname>W-thread</varname> means a thread in Windows' terminology</para>
  42           </listitem>
  43         </itemizedlist>
  44         <para>
  45           A <varname>W-process</varname> is made of one or several
  46           <varname>W-threads</varname>. Each
  47           <varname>W-thread</varname> is mapped to one and only one
  48           <varname>U-process</varname>. All
  49           <varname>U-processes</varname> of a same
  50           <varname>W-process</varname> share the same address space.
  51         </para>
  52         <para>
  53           Each Unix process can be identified by two values:
  54         </para>
  55         <itemizedlist>
  56           <listitem>
  57             <para>the Unix process id (<varname>upid</varname> in the following)</para>
  58           </listitem>
  59           <listitem>
  60             <para>the Windows's thread id (<varname>tid</varname>)</para>
  61           </listitem>
  62         </itemizedlist>
  63         <para>
  64           Each Windows' process has also a Windows' process id
  65           (<varname>wpid</varname> in the following). It must be clear
  66           that <varname>upid</varname> and <varname>wpid</varname> are
  67           different and shall not be used instead of the other.
  68         </para>
  69         <para>
  70           <varname>Wpid</varname> and <varname>tid</varname> are
  71           defined (Windows) system wide. They must not be confused
  72           with process or thread handles which, as any handle, is an
  73           indirection to a system object (in this case process or
  74           thread). A same process can have several different handles
  75           on the same kernel object. The handles can be defined as
  76           local (the values is only valid in a process), or system
  77           wide (the same handle can be used by any
  78           <varname>W-process</varname>).
  79         </para>
  80       </sect2>
  81
  82       <sect2>
  83         <title>I.2 Wine, debugging and WineDbg</title>
  84
  85         <para>
  86           When talking of debugging in Wine, there are at least two
  87           levels to think of:
  88         </para>
  89         <itemizedlist>
  90           <listitem>
  91             <para>the Windows' debugging API.</para>
  92           </listitem>
  93           <listitem>
  94             <para>the Wine integrated debugger, dubbed
  95               <command>WineDbg</command>.</para>
  96           </listitem>
  97         </itemizedlist>
  98         <para>
  99           Wine implements most the the Windows' debugging API (the
 100           part in KERNEL32, not the one in
 101           <filename>IMAGEHLP.DLL</filename>), and allows any program
 102           (emulated or WineLib) using that API to debug a
 103           <varname>W-process</varname>.
 104         </para>
 105         <para>
 106           <command>WineDbg</command> is a WineLib application making
 107           use of this API to allow debugging both any Wine or WineLib
 108           applications as well as Wine itself (kernel and all DLLs).
 109         </para>
 110       </sect2>
 111     </sect1>
 112
 113     <sect1 id="dbg-modes">
 114       <title>II WineDbg's modes of invocation</title>
 115
 116       <sect2>
 117         <title>II.1 Starting a process</title>
 118
 119         <para>
 120           Any application (either a Windows' native executable, or a
 121           WineLib application) can be run through
 122           <command>WineDbg</command>. Command line options and tricks
 123           are the same as for wine:
 124         </para>
 125         <screen>
 126 winedbg telnet.exe
 127 winedbg "hl.exe -windowed"
 128         </screen>
 129       </sect2>
 130
 131       <sect2>
 132         <title>II.2 Attaching</title>
 133
 134         <para>
 135           <command>WineDbg</command> can also be launched without any
 136           command line argument: <command>WineDbg</command> is started
 137           without any attached process. You can get a list of running
 138           <varname>W-processes</varname> (and their
 139           <varname>wpid</varname>'s) using the <command>walk
 140             process</command> command, and then, with the
 141           <command>attach</command> command, pick up the
 142           <varname>wpid</varname> of the <varname>W-process</varname>
 143           you want to debug. This is (for now) a neat feature for the
 144           following reasons:
 145         </para>
 146         <itemizedlist>
 147           <listitem>
 148             <para>you can debug an already started application</para>
 149           </listitem>
 150         </itemizedlist>
 151       </sect2>
 152
 153       <sect2>
 154         <title>II.3 On exception</title>
 155
 156         <para>
 157           When something goes wrong, Windows tracks this as an
 158           exception. Exceptions exist for segmentation violation,
 159           stack overflow, division by zero...
 160         </para>
 161         <para>
 162           When an exception occurs, Wine checks if the <varname>W-process</varname> is
 163           debugged. If so, the exception event is sent to the
 164           debugger, which takes care of it: end of the story. This
 165           mechanism is part of the standard Windows' debugging API.
 166         </para>
 167         <para>
 168           If the <varname>W-process</varname> is not debugged, Wine
 169           tries to launch a debugger. This debugger (normally
 170           <command>WineDbg</command>, see III Configuration for more
 171           details), at startup, attaches to the
 172           <varname>W-process</varname> which generated the exception
 173           event. In this case, you are able to look at the causes of
 174           the exception, and either fix the causes (and continue
 175           further the execution) or dig deeper to understand what went
 176           wrong.
 177         </para>
 178         <para>
 179           If <command>WineDbg</command> is the standard debugger, the
 180           <command>pass</command> and <command>cont</command> commands
 181           are the two ways to let the process go further for the
 182           handling of the  exception event.
 183         </para>
 184         <para>
 185           To be more precise on the way Wine (and Windows) generates
 186           exception events, when a fault occurs (segmentation
 187           violation, stack overflow...), the event is first sent to
 188           the debugger (this is known as a first chance exception).
 189           The debugger can give two answers:
 190         </para>
 191
 192         <variablelist>
 193           <varlistentry>
 194             <term>continue:</term>
 195             <listitem>
 196               <para>
 197                 the debugger had the ability to correct what's
 198                 generated the exception, and is now able to continue
 199                 process execution.
 200               </para>
 201             </listitem>
 202           </varlistentry>
 203           <varlistentry>
 204             <term>pass:</term>
 205             <listitem>
 206               <para>
 207                 the debugger couldn't correct the cause of the
 208                 first chance exception. Wine will now try to walk
 209                 the list of exception handlers to see if one of them
 210                 can handle the exception. If no exception handler is
 211                 found, the exception is sent once again to the
 212                 debugger to indicate the failure of the exception
 213                 handling.
 214               </para>
 215             </listitem>
 216           </varlistentry>
 217         </variablelist>
 218         <note>
 219           <para>
 220             since some of Wine's code uses exceptions and
 221             <function>try/catch</function> blocks to provide some
 222             functionality, <command>WineDbg</command> can be entered
 223             in such cases with segv exceptions. This happens, for
 224             example, with <function>IsBadReadPtr</function> function.
 225             In that case, the <command>pass</command> command shall be
 226             used, to let the handling of the exception to be done by
 227             the <function>catch</function> block in
 228             <function>IsBadReadPtr</function>.
 229           </para>
 230         </note>
 231       </sect2>
 232
 233       <sect2>
 234         <title>II.4 Quitting</title>
 235
 236         <para>
 237           Unfortunately, Windows doesn't provide a detach kind of API,
 238           meaning that once you started debugging a process, you must
 239           do so until the process dies. Killing (or stopping/aborting)
 240           the debugger will also kill the debugged process. This will
 241           be true for any Windows' debugging API compliant debugger,
 242           starting with <command>WineDbg</command>.
 243         </para>
 244       </sect2>
 245     </sect1>
 246
 247     <sect1 id="dbg-config">
 248       <title>III Configuration</title>
 249
 250       <sect2>
 251         <title>III.1 Registry configuration</title>
 252
 253         <para>
 254           The Windows' debugging API uses a registry entry to know
 255           with debugger  to invoke when an unhandled exception
 256           occurs (see II.3 for some details). Two values in key
 257         </para>
 258         <programlisting>
 259 "MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug"
 260         </programlisting>
 261         <para>
 262           Determine the behavior:
 263         </para>
 264         <variablelist>
 265           <varlistentry>
 266             <term>Debugger:</term>
 267             <listitem>
 268               <para>
 269                 this is the command line used to launch the debugger
 270                 (it uses two <function>printf</function> formats
 271                 (<literal>%ld</literal>) to pass context dependent
 272                 information to  the debugger). You should put here a
 273                 complete path to your debugger
 274                 (<command>WineDbg</command> can of course be used, but
 275                 any other Windows' debugging API aware debugger will
 276                 do).
 277               </para>
 278             </listitem>
 279           </varlistentry>
 280           <varlistentry>
 281             <term>Auto:</term>
 282             <listitem>
 283               <para>
 284                 if this value is zero, a message box will ask the
 285                 user if he/she wishes to launch the debugger when an
 286                 unhandled exception occurs. Otherwise, the debugger
 287                 is automatically started.
 288               </para>
 289             </listitem>
 290           </varlistentry>
 291         </variablelist>
 292
 293         <para>
 294           A regular Wine registry looks like:
 295         </para>
 296         <programlisting>
 297 [MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug] 957636538
 298 "Auto"=dword:00000001
 299 "Debugger"="/usr/local/bin/winedbg %ld %ld"
 300         </programlisting>
 301
 302         <note>
 303           <title>Note 1</title>
 304           <para>
 305             creating this key is mandatory. Not doing so will not
 306             fire the debugger when an exception occurs.
 307           </para>
 308         </note>
 309         <note>
 310           <title>Note 2</title>
 311           <para>
 312             <command>wineinstall</command> sets up this correctly.
 313             However, due to some limitation of the registry installed,
 314             if a previous Wine installation exists, it's safer to
 315             remove the whole
 316           </para>
 317           <programlisting>
 318 [MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]
 319           </programlisting>
 320           <para>
 321             key before running again <command>wineinstall</command> to
 322             regenerate this key.
 323           </para>
 324         </note>
 325       </sect2>
 326
 327       <sect2>
 328         <title>III.2 WineDbg configuration</title>
 329
 330         <para>
 331           <command>WineDbg</command> can be configured thru a number
 332           of options. Those options are stored in the registry, on a
 333           per user basis. The key is (in *my* registry)
 334         </para>
 335         <programlisting>
 336 [eric\\Software\\Wine\\WineDbg]
 337         </programlisting>
 338         <para>
 339           Those options can be read/written while inside
 340           <command>WineDbg</command>, as part of the debugger
 341           expressions. To refer to one of this option, its name must
 342           be  prefixed by a <literal>$</literal> sign. For example,
 343         </para>
 344         <programlisting>
 345 set $BreakAllThreadsStartup = 1
 346         </programlisting>
 347         <para>
 348           sets the option <varname>BreakAllThreadsStartup</varname> to
 349           <literal>TRUE</literal>.
 350         </para>
 351         <para>
 352           All the options are read from the registry when
 353           <command>WineDbg</command> starts (if no corresponding value
 354           is found, a default value is used), and are written back to
 355           the registry when <command>WineDbg</command> exits (hence,
 356           all modifications to those options are automatically saved
 357           when <command>WineDbg</command> terminates).
 358         </para>
 359         <para>
 360           Here's the list of all options:
 361         </para>
 362
 363         <sect3>
 364           <title>III.2.1 Controling when the debugger is entered</title>
 365
 366           <variablelist>
 367             <varlistentry>
 368               <term><varname>BreakAllThreadsStartup</varname></term>
 369               <listitem>
 370                 <para>
 371                   Set to <literal>TRUE</literal> if at all threads
 372                   start-up the debugger stops  set to
 373                   <literal>FALSE</literal> if only at the first thread
 374                   startup of a given process the debugger stops.
 375                   <literal>FALSE</literal> by default.
 376                 </para>
 377               </listitem>
 378             </varlistentry>
 379             <varlistentry>
 380               <term><varname>BreakOnCritSectTimeOut</varname></term>
 381               <listitem>
 382                 <para>
 383                   Set to <literal>TRUE</literal> if the debugger stops
 384                   when a critical section times out (5 minutes);
 385                   <literal>TRUE</literal> by default.
 386                 </para>
 387               </listitem>
 388             </varlistentry>
 389             <varlistentry>
 390               <term><varname>BreakOnAttach</varname></term>
 391               <listitem>
 392                 <para>
 393                   Set to <literal>TRUE</literal> if when
 394                   <command>WineDbg</command> attaches to an existing
 395                   process after an unhandled exception,
 396                   <command>WineDbg</command> shall be entered on the
 397                   first attach event. Since the attach event is
 398                   meaningless in the context of an exception event
 399                   (the next event  which is the exception event is of
 400                   course relevant), that option is likely to be
 401                   <literal>FALSE</literal>.
 402                 </para>
 403               </listitem>
 404             </varlistentry>
 405             <varlistentry>
 406               <term><varname>BreakOnFirstChance</varname></term>
 407               <listitem>
 408                 <para>
 409                   An exception can generate two debug events. The
 410                   first one is passed to the debugger (known as a
 411                   first chance) just after the exception. The debugger
 412                   can then decides either to resume execution (see
 413                   <command>WineDbg</command>'s <command>cont</command>
 414                   command) or pass the exception up to the exception
 415                   handler chain in the program (if it exists)
 416                   (<command>WineDbg</command> implements this thru the
 417                   <command>pass</command> command). If none of the
 418                   exception handlers takes care of the exception, the
 419                   exception event is sent again to the debugger (known
 420                   as last chance exception). You cannot pass on a last
 421                   exception. When the
 422                   <varname>BreakOnFirstChance</varname> exception is
 423                   <literal>TRUE</literal>, then winedbg is entered for
 424                   both first and last chance execptions (to
 425                   <literal>FALSE</literal>, it's only entered for last
 426                   chance exceptions).
 427                 </para>
 428               </listitem>
 429             </varlistentry>
 430           </variablelist>
 431         </sect3>
 432
 433         <sect3>
 434           <title>III.2.2 Output handling</title>
 435
 436           <variablelist>
 437             <varlistentry>
 438               <term><varname>ConChannelMask</varname></term>
 439               <listitem>
 440                 <para>
 441                   Mask of active debugger output channels on console
 442                 </para>
 443               </listitem>
 444             </varlistentry>
 445             <varlistentry>
 446               <term><varname>StdChannelMask</varname></term>
 447               <listitem>
 448                 <para>
 449                   Mask of active debugger output channels on <filename>stderr</filename>
 450                 </para>
 451               </listitem>
 452             </varlistentry>
 453             <varlistentry>
 454               <term><varname>UseXTerm</varname></term>
 455               <listitem>
 456                 <para>
 457                   Set to <literal>TRUE</literal> if the debugger uses
 458                   its own <command>xterm</command> window for console
 459                   input/output.  Set to <literal>FALSE</literal> if
 460                   the debugger uses the current Unix console for
 461                   input/output
 462                 </para>
 463               </listitem>
 464             </varlistentry>
 465           </variablelist>
 466
 467           <para>
 468             Those last 3 variables are jointly used in two generic ways:
 469           </para>
 470
 471           <orderedlist>
 472             <listitem>
 473               <para>default</para>
 474               <programlisting>
 475 ConChannelMask = DBG_CHN_MESG (1)
 476 StdChannelMask = 0
 477 UseXTerm = 1
 478               </programlisting>
 479               <para>
 480                 In this case, all input/output goes into a specific
 481                 <command>xterm</command> window (but all debug
 482                 messages <function>TRACE</function>,
 483                 <function>WARN</function>... still goes to tty where
 484                 wine is run from).
 485               </para>
 486             </listitem>
 487             <listitem>
 488               <para>
 489                 to have all input/output go into the tty where Wine
 490                 was started from (to be used in a X11-free
 491                 environment)
 492               </para>
 493               <screen>
 494 ConChannelMask = 0
 495 StdChannelMask = DBG_CHN_MESG (1)
 496 UseXTerm = 1
 497               </screen>
 498             </listitem>
 499           </orderedlist>
 500           <para>
 501             Those variables also allow, for example for debugging
 502             purposes, to use:
 503           </para>
 504           <screen>
 505 ConChannelMask = 0xfff
 506 StdChannelMask = 0xfff
 507 UseXTerm = 1
 508           </screen>
 509           <para>
 510             This allows to redirect all <function>WineDbg</function>
 511             output to both tty Wine was started from, and
 512             <command>xterm</command> debugging window. If Wine (or
 513             <command>WineDbg</command>) was started with a redirection
 514             of <filename>stdout</filename> and/or
 515             <filename>stderr</filename> to a file (with for
 516             example &gt;& shell redirect command), you'll get in that
 517             file both outputs. It may be interesting to look in the
 518             relay trace for specific values which the process segv'ed
 519             on.
 520           </para>
 521         </sect3>
 522
 523         <sect3>
 524           <title>III.2.2 Context information</title>
 525
 526           <variablelist>
 527             <varlistentry>
 528               <term><varname>ThreadId</varname></term>
 529               <listitem>
 530                 <para>ID of the <varname>W-thread</varname> currently
 531                   examined by the debugger</para>
 532               </listitem>
 533             </varlistentry>
 534             <varlistentry>
 535               <term><varname>ProcessId</varname></term>
 536               <listitem>
 537                 <para>ID of the <varname>W-thread</varname> currently
 538                   examined by the debugger</para>
 539               </listitem>
 540             </varlistentry>
 541             <varlistentry>
 542               <term>&lt;registers></term>
 543               <listitem>
 544                 <para>All CPU registers are also available</para>
 545               </listitem>
 546             </varlistentry>
 547           </variablelist>
 548
 549           <para>
 550             The <varname>ThreadId</varname> and
 551             <varname>ProcessId</varname> variables can be handy to set
 552             conditional breakpoints on a given thread or process.
 553           </para>
 554         </sect3>
 555       </sect2>
 556     </sect1>
 557
 558     <sect1 id="dbg-commands">
 559       <title>IV WineDbg commands</title>
 560
 561       <sect2>
 562         <title>IV.1 Misc</title>
 563
 564         <screen>
 565 abort           aborts the debugger
 566 quit            exits the debugger
 567
 568 attach N        attach to a W-process (N is its ID). IDs can be
 569                 obtained thru walk process command
 570         </screen>
 571         <screen>
 572 help            prints some help on the commands
 573 help info       prints some help on info commands
 574         </screen>
 575         <screen>
 576 mode 16         switch to 16 bit mode
 577 mode 32         switch to 32 bit mode
 578         </screen>
 579       </sect2>
 580
 581       <sect2>
 582         <title>IV.2 Flow control</title>
 583
 584         <screen>
 585 cont            continue execution until next breakpoint or exception.
 586 pass            pass the exception event up to the filter chain.
 587 step            continue execution until next C line of code (enters
 588                 function call)
 589 next            continue execution until next C line of code (doesn't
 590                 enter function call)
 591 stepi           execute next assembly instruction (enters function
 592                 call)
 593 nexti           execute next assembly instruction (doesn't enter
 594                 function call)
 595 finish          do nexti commands until current function is exited
 596         </screen>
 597         <para>
 598           cont, step, next, stepi, nexti can be postfixed by a
 599           number (N), meaning that the command must be executed N
 600           times.
 601         </para>
 602       </sect2>
 603
 604       <sect2>
 605         <title>IV.3 Breakpoints, watch points</title>
 606
 607         <screen>
 608 enable N        enables (break|watch)point #N
 609 disable N       disables (break|watch)point #N
 610 delete N        deletes  (break|watch)point #N
 611 cond N          removes any a existing condition to (break|watch)point N
 612 cond N &lt;expr&gt;     adds condition &lt;expr&gt; to (break|watch)point N. &lt;expr&gt;
 613                 will be evaluated each time the breakpoint is hit. If
 614                 the result is a zero value, the breakpoint isn't
 615                 triggered
 616 break * N       adds a breakpoint at address N
 617 break &lt;id&gt;        adds a breakpoint at the address of symbol &lt;id&gt;
 618 break &lt;id&gt; N      adds a breakpoint at the address of symbol &lt;id&gt; (N ?)
 619 break N         adds a breakpoint at line N of current source file
 620 break           adds a breakpoint at current $pc address
 621 watch * N       adds a watch command (on write) at address N (on 4 bytes)
 622 watch &lt;id&gt;        adds a watch command (on write) at the address of
 623                 symbol &lt;id&gt;
 624 info break      lists all (break|watch)points (with state)
 625         </screen>
 626       </sect2>
 627
 628       <sect2>
 629         <title>IV.4 Stack manipulation</title>
 630
 631         <screen>
 632 bt              print calling stack of current thread
 633 up              goes up one frame in current thread's stack
 634 up N            goes up N frames in current thread's stack
 635 dn              goes down one frame in current thread's stack
 636 dn N            goes down N frames in current thread's stack
 637 frame N         set N as the current frame
 638 info local      prints information on local variables for current
 639                 function
 640         </screen>
 641       </sect2>
 642
 643       <sect2>
 644         <title>IV.5 Directory & source file manipulation</title>
 645
 646         <screen>
 647 show dir
 648 dir &lt;pathname&gt;
 649 dir
 650 symbolfile &lt;pathname&gt;
 651         </screen>
 652         <screen>
 653 list            lists 10 source lines from current position
 654 list -          lists 10 source lines before current position
 655 list N          lists 10 source lines from line N in current file
 656 list &lt;path&gt;:N     lists 10 source lines from line N in file &lt;path&gt;
 657 list &lt;id&gt; lists 10 source lines of function &lt;id&gt;
 658 list * N        lists 10 source lines from address N
 659         </screen>
 660         <para>
 661           You can specify the end target (to change the 10 lines
 662           value) using the ','. For example:
 663         </para>
 664         <screen>
 665 list 123, 234   lists source lines from line 123 up to line 234 in
 666                 current file
 667 list foo.c:1,56 lists source lines from line 1 up to 56 in file foo.c
 668         </screen>
 669       </sect2>
 670
 671       <sect2>
 672         <title>IV.6 Displaying</title>
 673
 674         <para>
 675           A display is an expression that's evaluated and printed
 676           after the execution of any <command>WineDbg</command>
 677           command.
 678         </para>
 679         <screen>
 680 display         lists the active displays
 681 info display    (same as above command)
 682 display &lt;expr&gt;    adds a display for expression &lt;expr&gt;
 683 display /fmt &lt;expr&gt;       adds a display for expression &lt;expr&gt;. Printing
 684                 evaluated &lt;expr&gt; is done using the given format (see
 685                 print command for more on formats)
 686 del display N   deletes display #N
 687 undisplay N     (same as del display)
 688         </screen>
 689       </sect2>
 690
 691       <sect2>
 692         <title>IV.7 Disassembly</title>
 693
 694         <screen>
 695 disas           disassemble from current position
 696 disas &lt;expr&gt;      disassemble from address &lt;expr&gt;
 697 disas &lt;expr&gt;,&lt;expr&gt;disassembles code between addresses specified by
 698                 the two &lt;expr&gt;
 699         </screen>
 700       </sect2>
 701
 702       <sect2>
 703         <title>IV.8 Information on Wine's internals</title>
 704
 705         <screen>
 706 info class &lt;id&gt;   prints information on Windows's class &lt;id&gt;
 707 walk class      lists all Windows' class registered in Wine
 708 info share      lists all the dynamic libraries loaded the debugged
 709                 program (including .so files, NE and PE DLLs)
 710 info module N   prints information on module of handle N
 711 walk module     lists all modules loaded by debugged program
 712 info queue N    prints information on Wine's queue N
 713 walk queue      lists all queues allocated in Wine
 714 info regs       prints the value of CPU register
 715 info segment N  prints information on segment N
 716 info segment    lists all allocated segments
 717 info stack      prints the values on top of the stack
 718 info map        lists all virtual mappings used by the debugged
 719                 program
 720 info wnd N      prints information of Window of handle N
 721 walk wnd        lists all the window hierarchy starting from the
 722                 desktop window
 723 walk wnd N      lists all the window hierarchy starting from the
 724                 window of handle N
 725 walk process    lists all w-processes in Wine session
 726 walk thread     lists all w-threads in Wine session
 727 walk modref     (no longer avail)
 728         </screen>
 729       </sect2>
 730
 731       <sect2>
 732         <title>IV.9 Memory (reading, writing, typing)</title>
 733
 734         <screen>
 735 x &lt;expr&gt;  examines memory at &lt;expr&gt; address
 736 x /fmt &lt;expr&gt;     examines memory at &lt;expr&gt; address using format /fmt
 737 print &lt;expr&gt;      prints the value of &lt;expr&gt; (possibly using its type)
 738 print /fmt &lt;expr&gt; prints the value of &lt;expr&gt; (possibly using its
 739                 type)
 740 set &lt;lval&gt;=&lt;expr&gt;   writes the value of &lt;expr&gt; in &lt;lval&gt;
 741 whatis &lt;expr&gt;     prints the C type of expression &lt;expr&gt;
 742         </screen>
 743         <para>
 744           <filename>/fmt</filename> is either <filename>/&lt;letter&gt;</filename> or
 745           <filename>/&lt;count&gt;&lt;letter&gt;</filename> letter can be
 746         </para>
 747         <screen>
 748 s =&gt; an ASCII string
 749 u =&gt; an Unicode UTF16 string
 750 i =&gt; instructions (disassemble)
 751 x =&gt; 32 bit unsigned hexadecimal integer
 752 d =&gt; 32 bit signed decimal integer
 753 w =&gt; 16 bit unsigned hexadecimal integer
 754 c =&gt; character (only printable 0x20-0x7f are actually
 755      printed)
 756 b =&gt; 8 bit unsigned hexadecimal integer
 757         </screen>
 758       </sect2>
 759     </sect1>
 760
 761     <sect1 id="dbg-others">
 762       <title>V Other debuggers</title>
 763
 764       <sect2>
 765         <title>V.1 Using other Unix debuggers</title>
 766
 767         <para>
 768           You can also use other debuggers (like
 769           <command>gdb</command>), but you must be aware of a few
 770           items:
 771         </para>
 772         <para>
 773           You need to attach the unix debugger to the correct unix
 774           process (representing the correct windows thread) (you can
 775           "guess" it from a <command>ps fax</command> for example:
 776           When running the emulator, usually the first two
 777           <varname>upids</varname> are for the Windows' application
 778           running the desktop, the first thread of the application is
 779           generally the third <varname>upid</varname>; when running a
 780           WineLib program, the first thread of the application is
 781           generally the first <varname>upid</varname>)
 782         </para>
 783         <note>
 784           <para>
 785             Even if latest <command>gdb</command> implements the
 786             notion of threads, it won't work with Wine because the
 787             thread abstraction used for implementing Windows' thread
 788             is not 100% mapped onto the linux posix threads
 789             implementation. It means that you'll have to spawn a
 790             different <command>gdb</command> session for each Windows'
 791             thread you wish to debug.
 792           </para>
 793         </note>
 794       </sect2>
 795
 796       <sect2>
 797         <title>V.2 Using other Windows debuggers</title>
 798
 799         <para>
 800           You can use any Windows' debugging API compliant debugger
 801           with Wine. Some reports have been made of success with
 802           VisualStudio debugger (in remote mode, only the hub runs
 803           in Wine). GoVest fully runs in Wine.
 804         </para>
 805       </sect2>
 806
 807       <sect2>
 808         <title>V.3 Main differences between winedbg and regular Unix debuggers</title>
 809
 810         <!-- FIXME: convert this into a table -->
 811         <screen>
 812 +----------------------------------+---------------------------------+
 813 |             WineDbg              |                 gdb             |
 814 +----------------------------------+---------------------------------+
 815 |WineDbg debugs a Windows' process:|gdb debugs a Windows' thread:    |
 816 |+ the various threads will be     |+ a separate gdb session is      |
 817 |  handled by the same WineDbg     |  needed for each thread of      |
 818 | session                          |  Windows' process               |
 819 |+ a breakpoint will be triggered  |+ a breakpoint will be triggered |
 820 |  for any thread of the w-process |  only for the w-thread debugged |
 821 +----------------------------------+---------------------------------+
 822 |WineDbg supports debug information|gdb supports debug information   |
 823 |from:                             |from:                            |
 824 |+ stabs (standard Unix format)    |+ stabs (standard Unix format)   |
 825 |+ Microsoft's C, CodeView, .DBG   |                                 |
 826 +----------------------------------+---------------------------------+
 827         </screen>
 828       </sect2>
 829     </sect1>
 830
 831     <sect1 id="dbg-limits">
 832       <title>VI Limitations</title>
 833
 834       <para>
 835         16 bit processes are not supported (but calls to 16 bit code
 836         in 32 bit  applications are).
 837       </para>
 838
 839     </sect1>
 840   </chapter>
 841
 842 <!-- Keep this comment at the end of the file
 843 Local variables:
 844 mode: sgml
 845 sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
 846 End:
 847 -->