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