documentation/debugger.sgml

   1   <chapter id="debugger">
   2     <title>Debugging Wine</title>
   3
   4     <sect1 id="dbg-intro">
   5       <title>Introduction</title>
   6
   7       <sect2>
   8         <title>Processes and threads: in underlying OS and in Windows</title>
   9
  10         <para>
  11           Before going into the depths of debugging in Wine, here's
  12           a small overview of process and thread handling in Wine.
  13           It has to be clear that there are two different beasts:
  14           processes/threads from the Unix point of view and
  15           processes/threads from a Windows point of view.
  16         </para>
  17         <para>
  18           Each Windows' thread is implemented as a Unix process (under
  19           Linux using the <function>clone</function> syscall), meaning
  20           that all threads of a same Windows' process share the same
  21           (unix) address space.
  22         </para>
  23         <para>
  24           In the following:
  25         </para>
  26         <itemizedlist>
  27           <listitem>
  28             <para>
  29               <varname>W-process</varname> means a process in Windows' terminology
  30             </para>
  31           </listitem>
  32           <listitem>
  33             <para>
  34               <varname>U-process</varname> means a process in Unix' terminology
  35             </para>
  36           </listitem>
  37           <listitem>
  38             <para>
  39               <varname>W-thread</varname> means a thread in Windows' terminology
  40             </para>
  41           </listitem>
  42         </itemizedlist>
  43         <para>
  44           A <varname>W-process</varname> is made of one or several
  45           <varname>W-threads</varname>. Each
  46           <varname>W-thread</varname> is mapped to one and only one
  47           <varname>U-process</varname>. All
  48           <varname>U-processes</varname> of a same
  49           <varname>W-process</varname> share the same address space.
  50         </para>
  51         <para>
  52           Each Unix process can be identified by two values:
  53         </para>
  54         <itemizedlist>
  55           <listitem>
  56             <para>
  57               the Unix process id (<varname>upid</varname> in the following)
  58             </para>
  59           </listitem>
  60           <listitem>
  61             <para>
  62               the Windows's thread id (<varname>tid</varname>)
  63             </para>
  64           </listitem>
  65         </itemizedlist>
  66         <para>
  67           Each Windows' process has also a Windows' process id
  68           (<varname>wpid</varname> in the following). It must be clear
  69           that <varname>upid</varname> and <varname>wpid</varname> are
  70           different and shall not be used instead of the other.
  71         </para>
  72         <para>
  73           <varname>Wpid</varname> and <varname>tid</varname> are
  74           defined (Windows) system wide. They must not be confused
  75           with process or thread handles which, as any handle, is an
  76           indirection to a system object (in this case process or
  77           thread). A same process can have several different handles
  78           on the same kernel object. The handles can be defined as
  79           local (the values is only valid in a process), or system
  80           wide (the same handle can be used by any
  81           <varname>W-process</varname>).
  82         </para>
  83       </sect2>
  84
  85       <sect2>
  86         <title>Wine, debugging and WineDbg</title>
  87
  88         <para>
  89           When talking of debugging in Wine, there are at least two
  90           levels to think of:
  91         </para>
  92         <itemizedlist>
  93           <listitem>
  94             <para>
  95               the Windows' debugging API.
  96             </para>
  97           </listitem>
  98           <listitem>
  99             <para>
 100               the Wine integrated debugger, dubbed <command>winedbg</command>.
 101             </para>
 102           </listitem>
 103         </itemizedlist>
 104         <para>
 105           Wine implements most of the Windows' debugging API (the
 106           part in <filename>KERNEL32.DLL</filename>, not the one in
 107           <filename>IMAGEHLP.DLL</filename>), and allows any program
 108           (emulated or Winelib) using that API to debug a
 109           <varname>W-process</varname>.
 110         </para>
 111         <para>
 112           Wine also implements <filename>DBGHELP.DLL</filename> which
 113           allows to look into symbols and types from any module (if
 114           the module has been compiled with the proper options).
 115         </para>
 116         <para>
 117           <command>winedbg</command> is a Winelib application making
 118           use of these APIs (<filename>KERNEL32.DLL</filename>'s
 119           debugging API and <filename>DBGHELP.DLL</filename>) to allow
 120           debugging both any Wine or Winelib applications as well as
 121           Wine itself (kernel and all DLLs).
 122         </para>
 123       </sect2>
 124     </sect1>
 125
 126
 127     <sect1 id="dbg-modes">
 128       <title>WineDbg's modes of invocation</title>
 129
 130       <sect2>
 131         <title>Starting a process</title>
 132
 133         <para>
 134           Any application (either a Windows' native executable, or a
 135           Winelib application) can be run through
 136           <command>winedbg</command>. Command line options and tricks
 137           are the same as for wine:
 138         </para>
 139         <screen>
 140 winedbg telnet.exe
 141 winedbg "hl.exe -windowed"
 142         </screen>
 143       </sect2>
 144
 145       <sect2>
 146         <title>Attaching</title>
 147
 148         <para>
 149           <command>winedbg</command> can also be launched without any
 150           command line argument: <command>winedbg</command> is started
 151           without any attached process. You can get a list of running
 152           <varname>W-processes</varname> (and their
 153           <varname>wpid</varname>'s) using the <command>info
 154             process</command> command, and then, with the
 155           <command>attach</command> command, pick up the
 156           <varname>wpid</varname> of the <varname>W-process</varname>
 157           you want to debug. This is a neat feature as it allows you
 158           to debug an already started application.
 159          </para>
 160       </sect2>
 161
 162       <sect2 id="dbg-on-exception">
 163         <title id="dbg-exception-title">On exceptions</title>
 164
 165         <para>
 166           When something goes wrong, Windows tracks this as an
 167           exception. Exceptions exist for segmentation violation,
 168           stack overflow, division by zero, etc.
 169         </para>
 170         <para>
 171           When an exception occurs, Wine checks if the
 172           <varname>W-process</varname> is debugged. If so, the
 173           exception event is sent to the debugger, which takes care of
 174           it: end of the story. This mechanism is part of the standard
 175           Windows' debugging API.
 176         </para>
 177         <para>
 178           If the <varname>W-process</varname> is not debugged, Wine
 179           tries to launch a debugger. This debugger (normally
 180           <command>winedbg</command>, see III Configuration for more
 181           details), at startup, attaches to the
 182           <varname>W-process</varname> which generated the exception
 183           event. In this case, you are able to look at the causes of
 184           the exception, and either fix the causes (and continue
 185           further the execution) or dig deeper to understand what went
 186           wrong.
 187         </para>
 188         <para>
 189           If <command>winedbg</command> is the standard debugger, the
 190           <command>pass</command> and <command>cont</command> commands
 191           are the two ways to let the process go further for the
 192           handling of the  exception event.
 193         </para>
 194         <para>
 195           To be more precise on the way Wine (and Windows) generates
 196           exception events, when a fault occurs (segmentation
 197           violation, stack overflow...), the event is first sent to
 198           the debugger (this is known as a first chance exception).
 199           The debugger can give two answers:
 200         </para>
 201
 202         <variablelist>
 203           <varlistentry>
 204             <term>continue:</term>
 205             <listitem>
 206               <para>
 207                 the debugger had the ability to correct what's
 208                 generated the exception, and is now able to continue
 209                 process execution.
 210               </para>
 211             </listitem>
 212           </varlistentry>
 213           <varlistentry>
 214             <term>pass:</term>
 215             <listitem>
 216               <para>
 217                 the debugger couldn't correct the cause of the
 218                 first chance exception. Wine will now try to walk
 219                 the list of exception handlers to see if one of them
 220                 can handle the exception. If no exception handler is
 221                 found, the exception is sent once again to the
 222                 debugger to indicate the failure of the exception
 223                 handling.
 224               </para>
 225             </listitem>
 226           </varlistentry>
 227         </variablelist>
 228         <note>
 229           <para>
 230             since some of Wine's code uses exceptions and
 231             <function>try/catch</function> blocks to provide some
 232             functionality, <command>winedbg</command> can be entered
 233             in such cases with segv exceptions. This happens, for
 234             example, with <function>IsBadReadPtr</function> function.
 235             In that case, the <command>pass</command> command shall be
 236             used, to let the handling of the exception to be done by
 237             the <function>catch</function> block in
 238             <function>IsBadReadPtr</function>.
 239           </para>
 240         </note>
 241       </sect2>
 242
 243       <sect2 id="interrupt">
 244         <title>Interrupting</title>
 245
 246         <para>
 247           You can stop the debugger while it's running by hitting
 248           Ctrl-C in its window. This will stop the debugged process,
 249           and let you manipulate the current context.
 250         </para>
 251       </sect2>
 252
 253       <sect2>
 254         <title>Quitting</title>
 255
 256         <para>
 257           Wine supports the new XP APIs, allowing for a debugger to
 258           detach from a program being debugged (see
 259           <command>detach</command> command).
 260         </para>
 261       </sect2>
 262     </sect1>
 263
 264
 265     <sect1 id="wine-debugger">
 266       <title>Using the Wine Debugger</title>
 267
 268       <para>
 269         This section describes where to start debugging Wine. If at any
 270         point you get stuck and want to ask for help, please read the
 271         <emphasis>How to Report A Bug</emphasis> section of the
 272         <emphasis>Wine Users Guide</emphasis> for information on how to write
 273         useful bug reports.
 274       </para>
 275
 276       <sect2>
 277         <title>Crashes</title>
 278
 279         <para>
 280           These usually show up like this:
 281         </para>
 282         <screen>
 283 |Unexpected Windows program segfault - opcode = 8b
 284 |Segmentation fault in Windows program 1b7:c41.
 285 |Loading symbols from ELF file /root/wine/wine...
 286 |....more Loading symbols from ...
 287 |In 16 bit mode.
 288 |Register dump:
 289 | CS:01b7 SS:016f DS:0287 ES:0000
 290 | IP:0c41 SP:878a BP:8796 FLAGS:0246
 291 | AX:811e BX:0000 CX:0000 DX:0000 SI:0001 DI:ffff
 292 |Stack dump:
 293 |0x016f:0x878a:  0001 016f ffed 0000 0000 0287 890b 1e5b
 294 |0x016f:0x879a:  01b7 0001 000d 1050 08b7 016f 0001 000d
 295 |0x016f:0x87aa:  000a 0003 0004 0000 0007 0007 0190 0000
 296 |0x016f:0x87ba:
 297 |
 298 |0050: sel=0287 base=40211d30 limit=0b93f (bytes) 16-bit rw-
 299 |Backtrace:
 300 |0 0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c)
 301 |1 0x01b7:0x1e5b (PXSRV_FONPUTCATFONT+0x2cd)
 302 |2 0x01a7:0x05aa
 303 |3 0x01b7:0x0768 (PXSRV_FONINITFONTS+0x81)
 304 |4 0x014f:0x03ed (PDOXWIN_@SQLCURCB$Q6CBTYPEULN8CBSCTYPE+0x1b1)
 305 |5 0x013f:0x00ac
 306 |
 307 |0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c):  movw        %es:0x38(%bx),%dx
 308         </screen>
 309         <para>
 310           Steps to debug a crash. You may stop at any step, but please
 311           report the bug and provide as much of the information
 312           gathered to the bug report as feasible.
 313         </para>
 314
 315         <orderedlist>
 316           <listitem>
 317             <para>
 318               Get the reason for the crash. This is usually an access to
 319               an invalid selector, an access to an out of range address
 320               in a valid selector, popping a segment register from the
 321               stack or the like. When reporting a crash, report this
 322               <emphasis>whole</emphasis> crashdump even if it doesn't
 323               make sense to you.
 324             </para>
 325             <para>
 326               (In this case it is access to an invalid selector, for
 327               <systemitem>%es</systemitem> is <literal>0000</literal>, as
 328               seen in the register dump).
 329             </para>
 330           </listitem>
 331           <listitem>
 332             <para>
 333               Determine the cause of the crash. Since this is usually
 334               a primary/secondary reaction to a failed or misbehaving
 335               Wine function, rerun Wine with the<parameter>WINEDEBUG=+relay</parameter>
 336               environment variable set. This will
 337               generate quite a lot of output, but usually the reason is
 338               located in the last call(s).  Those lines usually look like
 339               this:
 340             </para>
 341             <screen>
 342 |Call KERNEL.90: LSTRLEN(0227:0692 "text") ret=01e7:2ce7 ds=0227
 343       ^^^^^^^^^  ^       ^^^^^^^^^ ^^^^^^      ^^^^^^^^^    ^^^^
 344       |          |       |         |           |            |Datasegment
 345       |          |       |         |           |Return address
 346       |          |       |         |textual parameter
 347       |          |       |
 348       |          |       |Argument(s). This one is a win16 segmented pointer.
 349       |          |Function called.
 350       |The module, the function is called in. In this case it is KERNEL.
 351
 352 |Ret  KERNEL.90: LSTRLEN() retval=0x0004 ret=01e7:2ce7 ds=0227
 353                                   ^^^^^^
 354                                   |Returnvalue is 16 bit and has the value 4.
 355             </screen>
 356           </listitem>
 357           <listitem>
 358             <para>
 359               If you have found a misbehaving function, try to find out
 360               why it misbehaves. Find the function in the source code.
 361               Try to make sense of the arguments passed. Usually there is
 362               a <function>WINE_DEFAULT_DEBUG_CHANNEL(&lt;channel>);</function>
 363               at the beginning of the file. Rerun wine with the
 364               <parameter>WINEDEBUG=+xyz,+relay</parameter> environment variable set.
 365             </para>
 366             <para>
 367               Occasionally there are additional debug channels defined at the
 368               beginning of the file in the form.
 369               <function>WINE_DECLARE_DEBUG_CHANNEL(&lt;channel>);</function>
 370               If so the offending function may also uses one of these alternate
 371               channels. Look through the the function for
 372              <function>TRACE_(&lt;channel>)(" ... /n");</function> and add any
 373              additional channels to the commandline.
 374             </para>
 375           </listitem>
 376           <listitem>
 377             <para>
 378               Additional information on how to debug using the internal
 379               debugger can be  found in
 380               <filename>programs/winedbg/README</filename>.
 381             </para>
 382           </listitem>
 383           <listitem>
 384             <para>
 385               If this information isn't clear enough or if you want to
 386               know more about what's happening in the function itself,
 387               try running wine with <parameter>WINEDEBUG=+all</parameter>,
 388               which dumps ALL included debug
 389               information in wine.
 390             </para>
 391           </listitem>
 392           <listitem>
 393             <para>
 394               If even that isn't enough, add more debug output for yourself
 395               into the functions you find relevant. See The section on Debug
 396               Logging in this guide for more information. You might
 397               also try to run the program in <command>gdb</command>
 398               instead of using the Wine debugger. If you do that, use
 399               <parameter>handle SIGSEGV nostop noprint</parameter> to
 400               disable the handling of seg faults inside
 401               <command>gdb</command> (needed for Win16).
 402             </para>
 403           </listitem>
 404           <listitem>
 405             <para>
 406               You can also set a breakpoint for that function. Start wine
 407               useing <command>winedbg</command> instead of
 408               <command>wine</command>. Once the debugger is is running enter
 409               <command>break</command> <parameter>KERNEL_LSTRLEN</parameter>
 410               (replace by function you want to debug, CASE IS RELEVANT)
 411               to set a breakpoint.  Then
 412               use <command>continue</command> to start normal
 413               program-execution. Wine will stop if it reaches the
 414               breakpoint. If the program isn't yet at the crashing call
 415               of that function, use <command>continue</command> again
 416               until you are about to enter that function. You may now
 417               proceed with single-stepping the function until you reach
 418               the point of crash. Use the other debugger commands to
 419               print registers and the like.
 420             </para>
 421           </listitem>
 422         </orderedlist>
 423       </sect2>
 424
 425       <sect2>
 426         <title>Program hangs, nothing happens</title>
 427
 428         <para>
 429           Start the program with <command>winedbg</command> instead of
 430           <command>wine</command>. When the program locks up switch to the
 431           winedbg's terminal and press
 432           <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>. this
 433           will stop the program and let you debug the program as you would for
 434           a crash.
 435         </para>
 436       </sect2>
 437
 438       <sect2>
 439         <title>Program reports an error with a Messagebox</title>
 440
 441         <para>
 442           Sometimes programs are reporting failure using more or
 443           less nondescript messageboxes. We can debug this using the
 444           same method as Crashes, but there is one problem... For
 445           setting up a message box the program also calls Wine
 446           producing huge chunks of debug code.
 447         </para>
 448         <para>
 449           Since the failure happens usually directly before setting up
 450           the Messagebox you can start winedbg and set a
 451           breakpoint at <function>MessageBoxA</function> (called by win16
 452           and win32 programs) and proceed with
 453           <command>continue</command>. With <parameter>WINEDEBUG=+all</parameter>
 454           Wine will now stop directly before setting
 455           up the Messagebox. Proceed as explained above.
 456         </para>
 457         <para>
 458           You can also run wine using <command>WINEDEBUG=+relay wine
 459             program.exe 2>&1 | less -i</command> and in
 460           <command>less</command> search for <quote>MessageBox</quote>.
 461         </para>
 462       </sect2>
 463
 464       <sect2>
 465         <title>Disassembling programs:</title>
 466
 467         <para>
 468           You may also try to disassemble the offending program to
 469           check for undocumented features and/or use of them.
 470         </para>
 471         <para>
 472           The best, freely available, disassembler for Win16 programs is
 473           <application>Windows Codeback</application>, archive name
 474           <filename>wcbxxx.zip</> (e.g. <filename>wcb105a.zip</>), which
 475           usually can be found in the <filename>Cica-Mirror</filename>
 476           subdirectory on the Wine ftp sites. (See <filename>ANNOUNCE</>).
 477         </para>
 478         <para>
 479           Disassembling win32 programs is possible using
 480           <application>Windows Disassembler 32</>. Look for
 481           a file called <filename>w32dsm87.zip</> (or similar)
 482           on <ulink url="http://www.winsite.com/">http://www.winsite.com</>
 483           and mirrors.  The shareware version does not allow saving of
 484           disassembly listings. You can also use the newer (and in the
 485           full version better) <application>Interactive
 486             Disassembler</application> (IDA) from the ftp sites mentioned
 487           at the end of the document. Understanding disassembled code is
 488           mostly a question of exercise.
 489         </para>
 490         <para>
 491           Most code out there uses standard C function entries (for it
 492           is usually  written in C). Win16 function entries usually
 493           look like that:
 494         </para>
 495         <programlisting>
 496 push bp
 497 mov bp, sp
 498 ... function code ..
 499 retf XXXX       &lt;--------- XXXX is number of bytes of arguments
 500         </programlisting>
 501         <para>
 502           This is a <function>FAR</function> function with no local
 503           storage. The arguments usually start at
 504           <literal>[bp+6]</literal> with increasing offsets. Note, that
 505           <literal>[bp+6]</literal> belongs to the
 506           <emphasis>rightmost</emphasis> argument, for exported win16
 507           functions use the PASCAL calling convention. So, if we use
 508           <function>strcmp(a,b)</function> with <parameter>a</parameter>
 509           and <parameter>b</parameter> both 32 bit variables
 510           <parameter>b</parameter> would be at <literal>[bp+6]</literal>
 511           and <parameter>a</parameter> at <literal>[bp+10]</literal>.
 512         </para>
 513         <para>
 514           Most functions make also use of local storage in the stackframe:
 515         </para>
 516         <programlisting>
 517 enter 0086, 00
 518 ... function code ...
 519 leave
 520 retf XXXX
 521         </programlisting>
 522         <para>
 523           This does mostly the same as above, but also adds
 524           <literal>0x86</literal> bytes of stackstorage, which is
 525           accessed using <literal>[bp-xx]</literal>. Before calling a
 526           function, arguments are pushed on the stack using something
 527           like this:
 528         </para>
 529         <programlisting>
 530 push word ptr [bp-02]   &lt;- will be at [bp+8]
 531 push di                 &lt;- will be at [bp+6]
 532 call KERNEL.LSTRLEN
 533         </programlisting>
 534         <para>
 535           Here first the selector and then the offset to the passed
 536           string are pushed.
 537         </para>
 538       </sect2>
 539
 540       <sect2>
 541         <title>Sample debugging session:</title>
 542
 543         <para>
 544           Let's debug the infamous Word <filename>SHARE.EXE</filename>
 545           messagebox:
 546         </para>
 547         <screen>
 548 |marcus@jet $ wine winword.exe
 549 |            +---------------------------------------------+
 550 |            | !  You must leave Windows and load SHARE.EXE|
 551 |            |    before starting Word.                    |
 552 |            +---------------------------------------------+
 553         </screen>
 554         <screen>
 555 |marcus@jet $ WINEDEBUG=+relay,-debug wine winword.exe
 556 |CallTo32(wndproc=0x40065bc0,hwnd=000001ac,msg=00000081,wp=00000000,lp=00000000)
 557 |Win16 task 'winword': Breakpoint 1 at 0x01d7:0x001a
 558 |CallTo16(func=0127:0070,ds=0927)
 559 |Call WPROCS.24: TASK_RESCHEDULE() ret=00b7:1456 ds=0927
 560 |Ret  WPROCS.24: TASK_RESCHEDULE() retval=0x8672 ret=00b7:1456 ds=0927
 561 |CallTo16(func=01d7:001a,ds=0927)
 562 |     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=0927 BP=0000 ES=11f7
 563 |Loading symbols: /home/marcus/wine/wine...
 564 |Stopped on breakpoint 1 at 0x01d7:0x001a
 565 |In 16 bit mode.
 566 |Wine-dbg>break MessageBoxA                          &lt;---- Set Breakpoint
 567 |Breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
 568 |Wine-dbg>c                                            &lt;---- Continue
 569 |Call KERNEL.91: INITTASK() ret=0157:0022 ds=08a7
 570 |     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=08a7 ES=11d7 EFL=00000286
 571 |CallTo16(func=090f:085c,ds=0dcf,0x0000,0x0000,0x0000,0x0000,0x0800,0x0000,0x0000,0x0dcf)
 572 |...                                                   &lt;----- Much debugoutput
 573 |Call KERNEL.136: GETDRIVETYPE(0x0000) ret=060f:097b ds=0927
 574                                ^^^^^^ Drive 0 (A:)
 575 |Ret  KERNEL.136: GETDRIVETYPE() retval=0x0002 ret=060f:097b ds=0927
 576                                         ^^^^^^  DRIVE_REMOVEABLE
 577                                                 (It is a floppy diskdrive.)
 578
 579 |Call KERNEL.136: GETDRIVETYPE(0x0001) ret=060f:097b ds=0927
 580                                ^^^^^^ Drive 1 (B:)
 581 |Ret  KERNEL.136: GETDRIVETYPE() retval=0x0000 ret=060f:097b ds=0927
 582                                         ^^^^^^  DRIVE_CANNOTDETERMINE
 583                                                 (I don't have drive B: assigned)
 584
 585 |Call KERNEL.136: GETDRIVETYPE(0x0002) ret=060f:097b ds=0927
 586                                ^^^^^^^ Drive 2 (C:)
 587 |Ret  KERNEL.136: GETDRIVETYPE() retval=0x0003 ret=060f:097b ds=0927
 588                                         ^^^^^^ DRIVE_FIXED
 589                                                (specified as a harddisk)
 590
 591 |Call KERNEL.97: GETTEMPFILENAME(0x00c3,0x09278364"doc",0x0000,0927:8248) ret=060f:09b1 ds=0927
 592                                  ^^^^^^           ^^^^^        ^^^^^^^^^
 593                                  |                |            |buffer for fname
 594                                  |                |temporary name ~docXXXX.tmp
 595                                  |Force use of Drive C:.
 596
 597 |Warning: GetTempFileName returns 'C:~doc9281.tmp', which doesn't seem to be writeable.
 598 |Please check your configuration file if this generates a failure.
 599         </screen>
 600         <para>
 601           Whoops, it even detects that something is wrong!
 602         </para>
 603         <screen>
 604 |Ret  KERNEL.97: GETTEMPFILENAME() retval=0x9281 ret=060f:09b1 ds=0927
 605                                           ^^^^^^ Temporary storage ID
 606
 607 |Call KERNEL.74: OPENFILE(0x09278248"C:~doc9281.tmp",0927:82da,0x1012) ret=060f:09d8 ds=0927
 608                                     ^^^^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^
 609                                     |filename        |OFSTRUCT |open mode:
 610
 611                                        OF_CREATE|OF_SHARE_EXCLUSIVE|OF_READWRITE
 612         </screen>
 613         <para>
 614           This fails, since my <medialabel>C:</medialabel> drive is in
 615           this case mounted readonly.
 616         </para>
 617         <screen>
 618 |Ret  KERNEL.74: OPENFILE() retval=0xffff ret=060f:09d8 ds=0927
 619                                    ^^^^^^ HFILE_ERROR16, yes, it failed.
 620
 621 |Call USER.1: MESSAGEBOX(0x0000,0x09278376"You must close Windows and load SHARE.EXE before you start Word.",0x00000000,0x1030) ret=060f:084f ds=0927
 622         </screen>
 623         <para>
 624           And MessageBox'ed.
 625         </para>
 626         <screen>
 627 |Stopped on breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
 628 |190     {              &lt;- the sourceline
 629 In 32 bit mode.
 630 Wine-dbg>
 631         </screen>
 632         <para>
 633           The code seems to find a writeable harddisk and tries to create
 634           a file there. To work around this bug, you can define
 635           <medialabel>C:</medialabel> as a networkdrive, which is ignored
 636           by the code above.
 637         </para>
 638       </sect2>
 639
 640       <sect2>
 641         <title>Debugging Tips</title>
 642
 643         <para>
 644           Here are some additional debugging tips:
 645         </para>
 646
 647         <itemizedlist>
 648           <listitem>
 649             <para>
 650               If you have a program crashing at such an early loader phase that you can't
 651               use the Wine debugger normally, but Wine already executes the program's
 652               start code, then you may use a special trick. You should do a
 653               <programlisting>
 654 WINEDEBUG=+relay wine program
 655               </programlisting>
 656               to get a listing of the functions the program calls in its start function.
 657               Now you do a
 658               <programlisting>
 659 winedbg winfile.exe
 660               </programlisting>
 661             </para>
 662             <para>
 663               This way, you get into <command>winedbg</command>. Now you
 664               can set a breakpoint on any function the program calls in
 665               the start function and just type <userinput>c</userinput>
 666               to bypass the eventual calls of Winfile to this function
 667               until you are finally at the place where this function gets
 668               called by the crashing start function. Now you can proceed
 669               with your debugging as usual.
 670             </para>
 671           </listitem>
 672           <listitem>
 673             <para>
 674               If you try to run a program and it quits after showing an error messagebox,
 675               the problem can usually be identified in the return value of one of the
 676               functions executed before <function>MessageBox()</function>.
 677               That's why you should re-run the program with e.g.
 678               <programlisting>
 679 WINEDEBUG=+relay wine  &lt;program name> &>relmsg
 680               </programlisting>
 681               Then do a <command>more relmsg</command> and search for the
 682               last occurrence of a call to the string "MESSAGEBOX". This is a line like
 683               <programlisting>
 684 Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
 685               </programlisting>
 686               In my example the lines before the call to
 687               <function>MessageBox()</function> look like that:
 688               <programlisting>
 689 Call KERNEL.96: FREELIBRARY(0x0347) ret=01cf:1033 ds=01ff
 690 CallTo16(func=033f:0072,ds=01ff,0x0000)
 691 Ret  KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:1033 ds=01ff
 692 Call KERNEL.96: FREELIBRARY(0x036f) ret=01cf:1043 ds=01ff
 693 CallTo16(func=0367:0072,ds=01ff,0x0000)
 694 Ret  KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:1043 ds=01ff
 695 Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
 696 CallTo16(func=0317:0072,ds=01ff,0x0000)
 697 Ret  KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:105c ds=01ff
 698 Call USER.171: WINHELP(0x02ac,0x01ff05b4 "COMET.HLP",0x0002,0x00000000) ret=01cf:1070 ds=01ff
 699 CallTo16(func=0117:0080,ds=01ff)
 700 Call WPROCS.24: TASK_RESCHEDULE() ret=00a7:0a2d ds=002b
 701 Ret  WPROCS.24: TASK_RESCHEDULE() retval=0x0000 ret=00a7:0a2d ds=002b
 702 Ret  USER.171: WINHELP() retval=0x0001 ret=01cf:1070 ds=01ff
 703 Call KERNEL.96: FREELIBRARY(0x01be) ret=01df:3e29 ds=01ff
 704 Ret  KERNEL.96: FREELIBRARY() retval=0x0000 ret=01df:3e29 ds=01ff
 705 Call KERNEL.52: FREEPROCINSTANCE(0x02cf00ba) ret=01f7:1460 ds=01ff
 706 Ret  KERNEL.52: FREEPROCINSTANCE() retval=0x0001 ret=01f7:1460 ds=01ff
 707 Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
 708               </programlisting>
 709             </para>
 710             <para>
 711               I think that the call to <function>MessageBox()</function>
 712               in this example is <emphasis>not</emphasis> caused by a
 713               wrong result value of some previously executed function
 714               (it's happening quite often like that), but instead the
 715               messagebox complains about a runtime error at
 716               <literal>0x0004:0x1056</literal>.
 717             </para>
 718             <para>
 719               As the segment value of the address is only
 720               <literal>4</literal>, I think that that is only an internal
 721               program value. But the offset address reveals something
 722               quite interesting: Offset <literal>1056</literal> is
 723               <emphasis>very</emphasis> close to the return address of
 724               <function>FREELIBRARY()</function>:
 725               <programlisting>
 726 Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
 727                                              ^^^^
 728               </programlisting>
 729             </para>
 730             <para>
 731               Provided that segment <literal>0x0004</literal> is indeed segment
 732               <literal>0x1cf</literal>, we now we can use IDA                 (available at
 733               <ulink url="http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip">
 734                http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip</ulink>) to
 735               disassemble the part that caused the error. We just have to find the address of
 736               the call to <function>FreeLibrary()</function>. Some lines before that the
 737               runtime error occurred. But be careful! In some cases you don't have to
 738               disassemble the main program, but instead some DLL called by it in order to find
 739               the correct place where the runtime error occurred. That can be determined by
 740               finding the origin of the segment value (in this case <literal>0x1cf</literal>).
 741             </para>
 742           </listitem>
 743           <listitem>
 744             <para>
 745               If you have created a relay file of some crashing
 746               program and want to set a breakpoint at a certain
 747               location which is not yet available as the program loads
 748               the breakpoint's segment during execution, you may set a
 749               breakpoint to <function>GetVersion16/32</function> as
 750               those functions are called very often.
 751             </para>
 752             <para>
 753               Then do a <userinput>c</userinput> until you are able to
 754               set this breakpoint without error message.
 755             </para>
 756           </listitem>
 757           <listitem>
 758             <para>
 759               Some useful programs:
 760             </para>
 761             <variablelist>
 762               <varlistentry>
 763                 <term>
 764                   <application>IDA</application>:
 765                   <filename>
 766                     <ulink url="http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip">
 767                      http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip</ulink>
 768                   </filename>
 769                 </term>
 770                 <listitem>
 771                   <para>
 772                     <emphasis>Very</emphasis> good DOS disassembler ! It's badly needed
 773                     for debugging Wine sometimes.
 774                   </para>
 775                 </listitem>
 776               </varlistentry>
 777               <varlistentry>
 778                 <term>
 779                   <application>XRAY</application>:
 780                   <filename>
 781                     <ulink url="http://garbo.uwasa.fi/pub/pc/sysinfo/xray15.zip">
 782                      http://garbo.uwasa.fi/pub/pc/sysinfo/xray15.zip</ulink>
 783                   </filename>
 784                 </term>
 785                 <listitem>
 786                   <para>
 787                     Traces DOS calls (Int 21h, DPMI, ...). Use it with
 788                     Windows to correct file management problems etc.
 789                   </para>
 790                 </listitem>
 791               </varlistentry>
 792               <varlistentry>
 793                 <term>
 794                   <application>pedump</application>:
 795                   <filename>
 796                     <ulink url="ftp://ftp.simtel.net/pub/simtelnet/win95/prog/pedump.zip">
 797                      ftp://ftp.simtel.net/pub/simtelnet/win95/prog/pedump.zip</ulink>
 798                   </filename>
 799                 </term>
 800                 <listitem>
 801                   <para>
 802                     Dumps the imports and exports of a PE (Portable
 803                     Executable) DLL.
 804                   </para>
 805                 </listitem>
 806               </varlistentry>
 807               <varlistentry>
 808                 <term>
 809                   <application>winedump</application>:
 810                 </term>
 811                 <listitem>
 812                   <para>
 813                     Dumps the imports and exports of a PE (Portable
 814                     Executable) DLL (included in wine tree).
 815                   </para>
 816                 </listitem>
 817               </varlistentry>
 818             </variablelist>
 819           </listitem>
 820         </itemizedlist>
 821       </sect2>
 822
 823       <sect2>
 824         <title>Some basic debugger usages:</title>
 825
 826         <para>
 827           After starting your program with
 828         </para>
 829         <screen>
 830 wine -debug myprog.exe
 831         </screen>
 832         <para>
 833           the program loads and you get a prompt at the program
 834           starting point. Then you can set breakpoints:
 835         </para>
 836         <screen>
 837   b RoutineName      (by routine name) OR
 838   b *0x812575        (by address)
 839         </screen>
 840         <para>
 841           Then you hit <command>c</command> (continue) to run the
 842           program. It stops at the breakpoint. You can type
 843         </para>
 844         <screen>
 845   step               (to step one line) OR
 846   stepi              (to step one machine instruction at a time;
 847                       here, it helps to know the basic 386
 848                       instruction set)
 849   info reg           (to see registers)
 850   info stack         (to see hex values in the stack)
 851   info local         (to see local variables)
 852   list &lt;line number&gt; (to list source code)
 853   x &lt;variable name&gt;  (to examine a variable; only works if code
 854                       is not compiled with optimization)
 855   x 0x4269978        (to examine a memory location)
 856   ?                  (help)
 857   q                  (quit)
 858         </screen>
 859         <para>
 860           By hitting <keycap>Enter</keycap>, you repeat the last
 861           command.
 862         </para>
 863       </sect2>
 864     </sect1>
 865
 866
 867     <sect1 id="memory-addresses">
 868       <title>Useful memory addresses</title>
 869       <para>
 870         Wine uses several different kinds of memory addresses.
 871       </para>
 872       <variablelist>
 873         <varlistentry>
 874           <term>
 875             Win32/"normal" Wine addresses/Linux: linear addresses.
 876           </term>
 877           <listitem>
 878             <para>
 879               Linear addresses can be everything from 0x0 up to
 880               0xffffffff.  In Wine on Linux they are often around
 881               e.g. 0x08000000, 0x00400000 (std. Win32 program load
 882               address), 0x40000000.  Every Win32 process has its own
 883               private 4GB address space (that is, from 0x0 up to
 884               0xffffffff).
 885             </para>
 886           </listitem>
 887         </varlistentry>
 888         <varlistentry>
 889           <term>
 890             Win16 "enhanced mode": segmented addresses.
 891           </term>
 892           <listitem>
 893             <para>
 894               These are the "normal" Win16 addresses, called SEGPTR.
 895               They have a segment:offset notation, e.g. 0x01d7:0x0012.
 896               The segment part usually is a "selector", which
 897               <emphasis>always</emphasis>
 898               has the lowest 3 bits set.  Some sample selectors are
 899               0x1f7, 0x16f, 0x8f.  If these bits are set except for
 900               the lowest bit, as e.g. with 0x1f6,xi then it might be a
 901               handle to global memory. Just set the lowest bit to get
 902               the selector in these cases.  A selector kind of
 903               "points" to a certain linear (see above) base address.
 904               It has more or less three important attributes: segment
 905               base address, segment limit, segment access rights.
 906             </para>
 907             <para>
 908               Example:
 909             </para>
 910             <para>
 911               Selector 0x1f7 (0x40320000, 0x0000ffff, r-x) So 0x1f7
 912               has a base address of 0x40320000, the segment's last
 913               address is 0x4032ffff (limit 0xffff), and it's readable
 914               and executable.  So an address of 0x1f7:0x2300 would be
 915               the linear address of 0x40322300.
 916             </para>
 917           </listitem>
 918         </varlistentry>
 919         <varlistentry>
 920           <term>
 921             DOS/Win16 "standard mode"
 922           </term>
 923           <listitem>
 924             <para>
 925               They, too, have a segment:offset notation.  But they are
 926               completely different from "normal" Win16 addresses, as
 927               they just represent at most 1MB of memory: The segment
 928               part can be anything from 0 to 0xffff, and it's the same
 929               with the offset part.
 930             </para>
 931             <para>
 932               Now the strange thing is the calculation that's behind
 933               these addresses: Just calculate segment*16 + offset in
 934               order to get a "linear DOS" address.  So
 935               e.g. 0x0f04:0x3628 results in 0xf040 + 0x3628 = 0x12668.
 936               And the highest address you can get is 0xfffff (1MB), of
 937               course.  In Wine, this "linear DOS" address of 0x12668
 938               has to be added to the linear base address of the
 939               corresponding DOS memory allocated for dosmod in order
 940               to get the true linear address of a DOS seg:offs
 941               address.  And make sure that you're doing this in the
 942               correct process with the correct linear address space,
 943               of course ;-)
 944             </para>
 945           </listitem>
 946         </varlistentry>
 947       </variablelist>
 948     </sect1>
 949
 950     <sect1 id="dbg-config">
 951       <title>Configuration</title>
 952
 953       <sect2>
 954         <title>Registry configuration</title>
 955
 956         <para>
 957           The Windows' debugging API uses a registry entry to know
 958           which debugger to invoke when an unhandled exception occurs
 959           (see <link endterm="dbg-exception-title"
 960           linkend="dbg-on-exception"></link> for some details). Two
 961           values in key
 962         </para>
 963         <programlisting>
 964 "MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug"
 965         </programlisting>
 966         <para>
 967           Determine the behavior:
 968         </para>
 969         <variablelist>
 970           <varlistentry>
 971             <term>Debugger:</term>
 972             <listitem>
 973               <para>
 974                 this is the command line used to launch the debugger
 975                 (it uses two <function>printf</function> formats
 976                 (<literal>%ld</literal>) to pass context dependent
 977                 information to  the debugger). You should put here a
 978                 complete path to your debugger
 979                 (<command>winedbg</command> can of course be used, but
 980                 any other Windows' debugging API aware debugger will
 981                 do).
 982                 The path to the debugger you chose to use must be reachable
 983                 via a DOS drive in the Wine config file !
 984               </para>
 985             </listitem>
 986           </varlistentry>
 987           <varlistentry>
 988             <term>Auto:</term>
 989             <listitem>
 990               <para>
 991                 if this value is zero, a message box will ask the
 992                 user if he/she wishes to launch the debugger when an
 993                 unhandled exception occurs. Otherwise, the debugger
 994                 is automatically started.
 995               </para>
 996             </listitem>
 997           </varlistentry>
 998         </variablelist>
 999
1000         <para>
1001           A regular Wine registry looks like:
1002         </para>
1003         <programlisting>
1004 [MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug] 957636538
1005 "Auto"=dword:00000001
1006 "Debugger"="winedbg %ld %ld"
1007         </programlisting>
1008
1009         <note>
1010           <title>Note 1</title>
1011           <para>
1012             creating this key is mandatory. Not doing so will not
1013             fire the debugger when an exception occurs.
1014           </para>
1015         </note>
1016         <note>
1017           <title>Note 2</title>
1018           <para>
1019             <command>wineinstall</command> (available in Wine source)
1020             sets up this correctly.
1021             However, due to some limitation of the registry installed,
1022             if a previous Wine installation exists, it's safer to
1023             remove the whole
1024           </para>
1025           <programlisting>
1026 [MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]
1027           </programlisting>
1028           <para>
1029             key before running again <command>wineinstall</command> to
1030             regenerate this key.
1031           </para>
1032         </note>
1033       </sect2>
1034
1035       <sect2>
1036         <title>WineDbg configuration</title>
1037
1038         <para>
1039           <command>winedbg</command> can be configured through a number
1040           of options. Those options are stored in the registry, on a
1041           per user basis. The key is (in <emphasis>my</emphasis> registry)
1042         </para>
1043         <programlisting>
1044 [eric\\Software\\Wine\\WineDbg]
1045         </programlisting>
1046         <para>
1047           Those options can be read/written while inside
1048           <command>winedbg</command>, as part of the debugger
1049           expressions. To refer to one of these options, its name must
1050           be  prefixed by a <literal>$</literal> sign. For example,
1051         </para>
1052         <programlisting>
1053 set $BreakAllThreadsStartup = 1
1054         </programlisting>
1055         <para>
1056           sets the option <varname>BreakAllThreadsStartup</varname> to
1057           <literal>TRUE</literal>.
1058         </para>
1059         <para>
1060           All the options are read from the registry when
1061           <command>winedbg</command> starts (if no corresponding value
1062           is found, a default value is used), and are written back to
1063           the registry when <command>winedbg</command> exits (hence,
1064           all modifications to those options are automatically saved
1065           when <command>winedbg</command> terminates).
1066         </para>
1067         <para>
1068           Here's the list of all options:
1069         </para>
1070
1071         <variablelist>
1072           <varlistentry>
1073             <term><varname>BreakAllThreadsStartup</varname></term>
1074             <listitem>
1075               <para>
1076                 Set to <literal>TRUE</literal> if at all threads
1077                 start-up the debugger stops  set to
1078                 <literal>FALSE</literal> if only at the first thread
1079                 startup of a given process the debugger
1080                 stops. <literal>FALSE</literal> by default.
1081               </para>
1082             </listitem>
1083           </varlistentry>
1084           <varlistentry>
1085             <term><varname>BreakOnCritSectTimeOut</varname></term>
1086             <listitem>
1087               <para>
1088                 Set to <literal>TRUE</literal> if the debugger stops
1089                 when a critical section times out (5 minutes);
1090                 <literal>TRUE</literal> by default.
1091               </para>
1092             </listitem>
1093           </varlistentry>
1094           <varlistentry>
1095             <term><varname>BreakOnAttach</varname></term>
1096             <listitem>
1097               <para>
1098                 Set to <literal>TRUE</literal> if when
1099                 <command>winedbg</command> attaches to an existing
1100                 process after an unhandled exception,
1101                 <command>winedbg</command> shall be entered on the
1102                 first attach event. Since the attach event is
1103                 meaningless in the context of an exception event (the
1104                 next event  which is the exception event is of course
1105                 relevant), that option is likely to be
1106                 <literal>FALSE</literal>.
1107               </para>
1108             </listitem>
1109           </varlistentry>
1110           <varlistentry>
1111             <term><varname>BreakOnFirstChance</varname></term>
1112             <listitem>
1113               <para>
1114                 An exception can generate two debug events. The first
1115                 one is passed to the debugger (known as a first
1116                 chance) just after the exception. The debugger can
1117                 then decide either to resume execution (see
1118                 <command>winedbg</command>'s <command>cont</command>
1119                 command) or pass the exception up to the exception
1120                 handler chain in the program (if it exists)
1121                 (<command>winedbg</command> implements this through
1122                 the <command>pass</command> command). If none of the
1123                 exception handlers takes care of the exception, the
1124                 exception event is sent again to the debugger (known
1125                 as last chance exception). You cannot pass on a last
1126                 exception. When the
1127                 <varname>BreakOnFirstChance</varname> exception is
1128                 <literal>TRUE</literal>, then winedbg is entered for
1129                 both first and last chance execptions (to
1130                 <literal>FALSE</literal>, it's only entered for last
1131                 chance exceptions).
1132               </para>
1133             </listitem>
1134           </varlistentry>
1135           <varlistentry>
1136             <term><varname>AlwaysShowThunk</varname></term>
1137             <listitem>
1138               <para>
1139                 Set to <literal>TRUE</literal> if the debugger, when
1140                 looking up for a symbol from its name, displays all
1141                 the thunks with that name. The default value
1142                 (<literal>FALSE</literal>) allows not to have to
1143                 choose between a symbol and all the import thunks
1144                 from all the DLLs using that symbols.
1145               </para>
1146             </listitem>
1147           </varlistentry>
1148         </variablelist>
1149       </sect2>
1150     </sect1>
1151
1152     <sect1 id="dbg-expr">
1153       <title>WineDbg Expressions and Variables</title>
1154       <sect2>
1155         <title>Expressions</title>
1156
1157         <para>
1158           Expressions in Wine Debugger are mostly written in a C
1159           form. However, there are a few discrepancies:
1160           <itemizedlist>
1161             <listitem>
1162               <para>
1163                 Identifiers can take a '!' in their names. This allow
1164                 mainly to access symbols from different DLLs like
1165                 <function>USER32!CreateWindowExA</function>.
1166               </para>
1167             </listitem>
1168             <listitem>
1169               <para>
1170                 In cast operation, when specifying a structure or an
1171                 union, you must use the <type>struct</type> or
1172                 <type>union</type> keyword (even if your program uses a typedef).
1173               </para>
1174             </listitem>
1175           </itemizedlist>
1176         </para>
1177         <para>
1178           When specifying an identifier by its name, if several
1179           symbols with the same name exist, the debugger will prompt
1180           for the symbol you want to use. Pick up the one you want
1181           from its number.
1182         </para>
1183         <para>
1184           In lots of cases, you can also use regular expressions for
1185           looking for a symbol.
1186         </para>
1187         <para>
1188           <command>winedbg</command> defines its own set of
1189           variables. The configuration variables from above are part
1190           of them. Some others include:
1191           <variablelist>
1192             <varlistentry>
1193               <term><varname>$ThreadId</varname></term>
1194               <listitem>
1195                 <para>
1196                   ID of the <varname>W-thread</varname> currently
1197                   examined by the debugger
1198                 </para>
1199               </listitem>
1200             </varlistentry>
1201             <varlistentry>
1202               <term><varname>$ProcessId</varname></term>
1203               <listitem>
1204                 <para>
1205                   ID of the <varname>W-thread</varname> currently
1206                   examined by the debugger
1207                 </para>
1208               </listitem>
1209             </varlistentry>
1210             <varlistentry>
1211               <term>&lt;registers></term>
1212               <listitem>
1213                 <para>
1214                   All CPU registers are also available, using $ as a
1215                   prefix. You can use <command>info regs</command> to
1216                   get a list of avaible CPU registers
1217                 </para>
1218               </listitem>
1219             </varlistentry>
1220           </variablelist>
1221         </para>
1222         <para>
1223           The <varname>$ThreadId</varname> and
1224           <varname>$ProcessId</varname> variables can be handy to set
1225           conditional breakpoints on a given thread or process.
1226         </para>
1227       </sect2>
1228     </sect1>
1229
1230     <sect1 id="dbg-commands">
1231       <title>WineDbg Command Reference</title>
1232
1233       <sect2>
1234         <title>Misc</title>
1235
1236         <para>
1237           <table>
1238             <title>WineDbg's misc. commands</title>
1239             <tgroup cols="2" align="left">
1240               <tbody>
1241                 <row>
1242                   <entry><command>abort</command></entry>
1243                   <entry>aborts the debugger</entry>
1244                 </row>
1245                 <row>
1246                   <entry><command>quit</command></entry>
1247                   <entry>exits the debugger</entry>
1248                 </row>
1249                 <row>
1250                   <entry><command>attach&nbsp;N</command></entry>
1251                   <entry>
1252                     attach to a W-process (N is its ID, numeric
1253                     or hexadecimal (0xN)). IDs can be obtained using
1254                     the info process command. Note the info process
1255                     command returns hexadecimal values.
1256                   </entry>
1257                 </row>
1258                 <row>
1259                   <entry><command>detach</command></entry>
1260                   <entry>detach from a W-process.</entry>
1261                 </row>
1262                 <row>
1263                   <entry><command>help</command></entry>
1264                   <entry>prints some help on the commands</entry>
1265                 </row>
1266                 <row>
1267                   <entry><command>help info</command></entry>
1268                   <entry>prints some help on info commands</entry>
1269                 </row>
1270               </tbody>
1271             </tgroup>
1272           </table>
1273         </para>
1274       </sect2>
1275
1276       <sect2>
1277         <title>Flow control</title>
1278
1279         <para>
1280           <table>
1281             <title>WineDbg's flow control commands</title>
1282             <tgroup cols="2" align="left">
1283               <tbody>
1284                 <row>
1285                   <entry>
1286                     <msgtext>
1287                       <simplelist type="inline">
1288                         <member><command>cont</command></member>
1289                         <member><command>c</command></member>
1290                       </simplelist>
1291                     </msgtext>
1292                   </entry>
1293                   <entry>continue execution until next breakpoint or
1294                     exception.</entry>
1295                 </row>
1296                 <row>
1297                   <entry><command>pass</command></entry>
1298                   <entry>pass the exception event up to the filter
1299                     chain.</entry>
1300                 </row>
1301                 <row>
1302                   <entry>
1303                     <msgtext>
1304                       <simplelist type="inline">
1305                         <member><command>step</command></member>
1306                         <member><command>s</command></member>
1307                       </simplelist>
1308                     </msgtext>
1309                   </entry>
1310                   <entry>
1311                     continue execution until next 'C' line of code
1312                     (enters function call)
1313                   </entry>
1314                 </row>
1315                 <row>
1316                   <entry>
1317                     <msgtext>
1318                       <simplelist type="inline">
1319                         <member><command>next</command></member>
1320                         <member><command>n</command></member>
1321                       </simplelist>
1322                     </msgtext>
1323                   </entry>
1324                   <entry>
1325                     continue execution until next 'C' line of code
1326                     (doesn't enter function call)
1327                   </entry>
1328                 </row>
1329                 <row>
1330                   <entry>
1331                     <msgtext>
1332                       <simplelist type="inline">
1333                         <member><command>stepi</command></member>
1334                         <member><command>si</command></member>
1335                       </simplelist>
1336                     </msgtext>
1337                   </entry>
1338                   <entry>
1339                     execute next assembly instruction (enters function
1340                     call)
1341                   </entry>
1342                 </row>
1343                 <row>
1344                   <entry>
1345                     <msgtext>
1346                       <simplelist type="inline">
1347                         <member><command>nexti</command></member>
1348                         <member><command>ni</command></member>
1349                       </simplelist>
1350                     </msgtext>
1351                   </entry>
1352                   <entry>
1353                     execute next assembly instruction (doesn't enter
1354                     function call)
1355                   </entry>
1356                 </row>
1357                 <row>
1358                   <entry>
1359                     <msgtext>
1360                       <simplelist type="inline">
1361                         <member><command>finish</command></member>
1362                         <member><command>f</command></member>
1363                       </simplelist>
1364                     </msgtext>
1365                   </entry>
1366                   <entry>execute until current function is exited</entry>
1367                 </row>
1368               </tbody>
1369             </tgroup>
1370           </table>
1371         </para>
1372         <para>
1373           <command>cont</command>, <command>step</command>,
1374           <command>next</command>, <command>stepi</command>,
1375           <command>nexti</command> can be postfixed by a number (N),
1376           meaning that the command must be executed N times.
1377         </para>
1378       </sect2>
1379
1380       <sect2>
1381         <title>Breakpoints, watch points</title>
1382
1383         <para>
1384           <table>
1385             <title>WineDbg's break & watch points</title>
1386             <tgroup cols="2" align="left">
1387               <tbody>
1388                 <row>
1389                   <entry><command>enable&nbsp;N</command></entry>
1390                   <entry>enables (break|watch)point #N</entry>
1391                 </row>
1392                 <row>
1393                   <entry><command>disable&nbsp;N</command></entry>
1394                   <entry>disables (break|watch)point #N</entry>
1395                 </row>
1396                 <row>
1397                   <entry><command>delete&nbsp;N</command></entry>
1398                   <entry>deletes (break|watch)point #N</entry>
1399                 </row>
1400                 <row>
1401                   <entry><command>cond&nbsp;N</command></entry>
1402                   <entry>
1403                     removes any existing condition to
1404                     (break|watch)point N
1405                   </entry>
1406                 </row>
1407                 <row>
1408                   <entry>
1409                     <command>cond&nbsp;N &lt;expr&gt;</command>
1410                   </entry>
1411                   <entry>
1412                     adds condition &lt;expr&gt; to (break|watch)point
1413                     N. &lt;expr&gt; will be evaluated each time the
1414                     breakpoint is hit. If the result is a zero value,
1415                     the breakpoint isn't triggered
1416                   </entry>
1417                 </row>
1418                 <row>
1419                   <entry><command>break&nbsp;*&nbsp;N</command></entry>
1420                   <entry>adds a breakpoint at address N</entry>
1421                 </row>
1422                 <row>
1423                   <entry><command>break &lt;id&gt;</command></entry>
1424                   <entry>
1425                     adds a breakpoint at the address of symbol
1426                     &lt;id&gt;
1427                   </entry>
1428                 </row>
1429                 <row>
1430                   <entry><command>break &lt;id&gt;&nbsp;N</command></entry>
1431                   <entry>
1432                     adds a breakpoint at the address of symbol
1433                     &lt;id&gt; (N ?)
1434                   </entry>
1435                 </row>
1436                 <row>
1437                   <entry><command>break&nbsp;N</command></entry>
1438                   <entry>
1439                     adds a breakpoint at line N of current source file
1440                   </entry>
1441                 </row>
1442                 <row>
1443                   <entry><command>break</command></entry>
1444                   <entry>
1445                     adds a breakpoint at current $PC address
1446                   </entry>
1447                 </row>
1448                 <row>
1449                   <entry><command>watch&nbsp;*&nbsp;N</command></entry>
1450                   <entry>
1451                     adds a watch command (on write) at address N (on 4
1452                     bytes)
1453                   </entry>
1454                 </row>
1455                 <row>
1456                   <entry><command>watch &lt;id&gt;</command></entry>
1457                   <entry>
1458                     adds a watch command (on write) at the address of
1459                     symbol &lt;id&gt;
1460                   </entry>
1461                 </row>
1462                 <row>
1463                   <entry><command>info break</command></entry>
1464                   <entry>
1465                     lists all (break|watch)points (with state)
1466                   </entry>
1467                 </row>
1468               </tbody>
1469             </tgroup>
1470           </table>
1471         </para>
1472         <para>
1473           You can use the symbol <emphasis>EntryPoint</emphasis> to stand for
1474           the entry point of the Dll.
1475         </para>
1476         <para>
1477           When setting a break/watch-point by &lt;id&gt;, if the
1478           symbol cannot be found (for example, the symbol is contained
1479           in a not yet loaded module), winedbg will recall the name of
1480           the symbol and will try to set the breakpoint each time a
1481           new module is loaded (until it succeeds).
1482         </para>
1483       </sect2>
1484
1485       <sect2>
1486         <title>Stack manipulation</title>
1487
1488         <para>
1489           <table>
1490             <title>WineDbg's stack manipulation</title>
1491             <tgroup cols="2" align="left">
1492               <tbody>
1493                 <row>
1494                   <entry><command>bt</command></entry>
1495                   <entry>print calling stack of current thread</entry>
1496                 </row>
1497                 <row>
1498                   <entry><command>bt&nbsp;N</command></entry>
1499                   <entry>
1500                     print calling stack of thread of ID N (note: this
1501                     doesn't change the position of the current frame
1502                     as manipulated by the <command>up</command> and
1503                     <command>dn</command> commands)
1504                   </entry>
1505                 </row>
1506                 <row>
1507                   <entry><command>up</command></entry>
1508                   <entry>
1509                     goes up one frame in current thread's stack
1510                   </entry>
1511                 </row>
1512                 <row>
1513                   <entry><command>up&nbsp;N</command></entry>
1514                   <entry>
1515                     goes up N frames in current thread's stack
1516                   </entry>
1517                 </row>
1518                 <row>
1519                   <entry><command>dn</command></entry>
1520                   <entry>
1521                     goes down one frame in current thread's stack
1522                   </entry>
1523                 </row>
1524                 <row>
1525                   <entry><command>dn&nbsp;N</command></entry>
1526                   <entry>
1527                     goes down N frames in current thread's stack
1528                   </entry>
1529                 </row>
1530                 <row>
1531                   <entry><command>frame&nbsp;N</command></entry>
1532                   <entry>
1533                     set N as the current frame for current thread's
1534                     stack
1535                   </entry>
1536                 </row>
1537                 <row>
1538                   <entry><command>info&nbsp;local</command></entry>
1539                   <entry>
1540                     prints information on local variables for current
1541                     function frame
1542                   </entry>
1543                 </row>
1544               </tbody>
1545             </tgroup>
1546           </table>
1547         </para>
1548       </sect2>
1549
1550       <sect2>
1551         <title>Directory & source file manipulation</title>
1552
1553         <para>
1554           <table>
1555             <title>WineDbg's directory & source file manipulation</title>
1556             <tgroup cols="2" align="left">
1557               <tbody>
1558                 <row>
1559                   <entry><command>show&nbsp;dir</command></entry>
1560                   <entry>
1561                     prints the list of dir:s where source files are
1562                     looked for
1563                   </entry>
1564                 </row>
1565                 <row>
1566                   <entry>
1567                     <command>dir&nbsp;&lt;pathname&gt;</command>
1568                   </entry>
1569                   <entry>
1570                     adds &lt;pathname&gt; to the list of dir:s
1571                     where to look for source files
1572                   </entry>
1573                 </row>
1574                 <row>
1575                   <entry><command>dir</command></entry>
1576                   <entry>
1577                     deletes the list of dir:s where to look for source
1578                     files
1579                   </entry>
1580                 </row>
1581                 <row>
1582                   <entry>
1583                     <command>
1584                       symbolfile&nbsp;&lt;pathname&gt;
1585                     </command>
1586                   </entry>
1587                   <entry>loads external symbol definition</entry>
1588                 </row>
1589                 <row>
1590                   <entry>
1591                     <command>
1592                       symbolfile&nbsp;&lt;pathname&gt;&nbsp;N
1593                     </command>
1594                   </entry>
1595                   <entry>
1596                     loads external symbol definition (applying an
1597                     offset of N to addresses)
1598                   </entry>
1599                 </row>
1600                 <row>
1601                   <entry><command>list</command></entry>
1602                   <entry>
1603                     lists 10 source lines forwards from current
1604                     position
1605                   </entry>
1606                 </row>
1607                 <row>
1608                   <entry><command>list&nbsp;-</command></entry>
1609                   <entry>
1610                     lists 10 source lines backwards from current
1611                     position
1612                   </entry>
1613                 </row>
1614                 <row>
1615                   <entry><command>list&nbsp;N</command></entry>
1616                   <entry>
1617                     lists 10 source lines from line N in current file
1618                   </entry>
1619                 </row>
1620                 <row>
1621                   <entry>
1622                     <command>list&nbsp;&lt;path&gt;:N</command>
1623                   </entry>
1624                   <entry>
1625                     lists 10 source lines from line N in file
1626                     &lt;path&gt;
1627                   </entry>
1628                 </row>
1629                 <row>
1630                   <entry><command>list &lt;id&gt;</command></entry>
1631                   <entry>
1632                     lists 10 source lines of function &lt;id&gt;
1633                   </entry>
1634                 </row>
1635                 <row>
1636                   <entry><command>list&nbsp;*&nbsp;N</command></entry>
1637                   <entry>lists 10 source lines from address N</entry>
1638                 </row>
1639               </tbody>
1640             </tgroup>
1641           </table>
1642         </para>
1643
1644         <para>
1645           You can specify the end target (to change the 10 lines
1646           value) using the ','. For example:
1647           <table>
1648             <title>WineDbg's list command examples</title>
1649             <tgroup cols="2" align="left">
1650               <tbody>
1651                 <row>
1652                   <entry><command>list 123, 234</command></entry>
1653                   <entry>
1654                     lists source lines from line 123 up to line 234 in
1655                     current file
1656                   </entry>
1657                 </row>
1658                 <row>
1659                   <entry><command>list foo.c:1,&nbsp;56</command></entry>
1660                   <entry>
1661                     lists source lines from line 1 up to 56 in file
1662                     foo.c
1663                   </entry>
1664                 </row>
1665               </tbody>
1666             </tgroup>
1667           </table>
1668         </para>
1669       </sect2>
1670
1671       <sect2>
1672         <title>Displaying</title>
1673
1674         <para>
1675           A display is an expression that's evaluated and printed
1676           after the execution of any <command>winedbg</command>
1677           command.
1678         </para>
1679         <para>
1680           <table>
1681             <title>WineDbg's displays</title>
1682             <tgroup cols="2" align="left">
1683               <tbody>
1684                 <row>
1685                   <entry>
1686                     <msgtext>
1687                       <simplelist type="inline">
1688                         <member><command>display</command></member>
1689                         <member>
1690                           <command>info&nbsp;display</command>
1691                         </member>
1692                       </simplelist>
1693                     </msgtext>
1694                   </entry>
1695                   <entry>lists the active displays</entry>
1696                 </row>
1697                 <row>
1698                   <entry>
1699                     <command>display&nbsp;&lt;expr&gt;</command>
1700                   </entry>
1701                   <entry>
1702                     adds a display for expression &lt;expr&gt;
1703                   </entry>
1704                 </row>
1705                 <row>
1706                   <entry>
1707                     <command>
1708                       display&nbsp;/fmt&nbsp;&lt;expr&gt;
1709                     </command>
1710                   </entry>
1711                   <entry>
1712                     adds a display for expression
1713                     &lt;expr&gt;. Printing evaluated &lt;expr&gt; is
1714                     done using the given format (see
1715                     <command>print</command> command for more on
1716                     formats)
1717                   </entry>
1718                 </row>
1719                 <row>
1720                   <entry>
1721                     <msgtext>
1722                       <simplelist type="inline">
1723                         <member>
1724                           <command>del&nbsp;display&nbsp;N</command>
1725                         </member>
1726                         <member>
1727                           <command>undisplay&nbsp;N</command>
1728                         </member>
1729                       </simplelist>
1730                     </msgtext>
1731                   </entry>
1732                   <entry>deletes display #N</entry>
1733                 </row>
1734               </tbody>
1735             </tgroup>
1736           </table>
1737         </para>
1738       </sect2>
1739
1740       <sect2>
1741         <title>Disassembly</title>
1742
1743         <para>
1744           <table>
1745             <title>WineDbg's dissassembly</title>
1746             <tgroup cols="2" align="left">
1747               <tbody>
1748                 <row>
1749                   <entry><command>disas</command></entry>
1750                   <entry>disassemble from current position</entry>
1751                 </row>
1752                 <row>
1753                   <entry>
1754                     <command>disas&nbsp;&lt;expr&gt;</command>
1755                   </entry>
1756                   <entry>
1757                     disassemble from address &lt;expr&gt;
1758                   </entry>
1759                 </row>
1760                 <row>
1761                   <entry>
1762                     <command>
1763                       disas&nbsp;&lt;expr&gt;,&lt;expr&gt;
1764                     </command>
1765                   </entry>
1766                   <entry>
1767                     disassembles code between addresses specified by
1768                     the two &lt;expr&gt;
1769                   </entry>
1770                 </row>
1771               </tbody>
1772             </tgroup>
1773           </table>
1774         </para>
1775       </sect2>
1776
1777       <sect2>
1778         <title>Memory (reading, writing, typing)</title>
1779
1780         <para>
1781           <table>
1782             <title>WineDbg's memory management</title>
1783             <tgroup cols="2" align="left">
1784               <tbody>
1785                 <row>
1786                   <entry>
1787                     <command>x&nbsp;&lt;expr&gt;</command>
1788                   </entry>
1789                   <entry>
1790                     examines memory at &lt;expr&gt; address
1791                   </entry>
1792                 </row>
1793                 <row>
1794                   <entry>
1795                     <command>
1796                       x&nbsp;/fmt&nbsp;&lt;expr&gt;
1797                     </command>
1798                   </entry>
1799                   <entry>
1800                     examines memory at &lt;expr&gt; address using
1801                     format /fmt
1802                   </entry>
1803                 </row>
1804                 <row>
1805                   <entry>
1806                     <command>
1807                       print&nbsp;&lt;expr&gt;
1808                     </command>
1809                   </entry>
1810                   <entry>
1811                     prints the value of &lt;expr&gt; (possibly using
1812                     its type)
1813                   </entry>
1814                 </row>
1815                 <row>
1816                   <entry>
1817                     <command>
1818                       print&nbsp;/fmt&nbsp;&lt;expr&gt;
1819                     </command>
1820                   </entry>
1821                   <entry>prints the value of &lt;expr&gt; (possibly
1822                     using its type)
1823                   </entry>
1824                 </row>
1825                 <row>
1826                   <entry>
1827                     <command>
1828                       set&nbsp;&lt;lval&gt;&nbsp;=&nbsp;&lt;expr&gt;
1829                     </command>
1830                   </entry>
1831                   <entry>
1832                     writes the value of &lt;expr&gt; in &lt;lval&gt;
1833                   </entry>
1834                 </row>
1835                 <row>
1836                   <entry>
1837                     <command>
1838                       whatis&nbsp;&lt;expr&gt;
1839                     </command>
1840                   </entry>
1841                   <entry>
1842                     prints the C type of expression &lt;expr&gt;
1843                   </entry>
1844                 </row>
1845               </tbody>
1846             </tgroup>
1847           </table>
1848         </para>
1849         <para>
1850           <filename>/fmt</filename> is either <filename>/&lt;letter&gt;</filename> or
1851           <filename>/&lt;count&gt;&lt;letter&gt;</filename> letter can be
1852           <simplelist type="horiz" columns="2">
1853             <member>s</member><member>an ASCII string</member>
1854             <member>u</member><member>an Unicode UTF16 string</member>
1855             <member>i</member><member>instructions (disassemble)</member>
1856             <member>x</member><member>32 bit unsigned hexadecimal integer</member>
1857             <member>d</member><member>32 bit signed decimal integer</member>
1858             <member>w</member><member>16 bit unsigned hexadecimal integer</member>
1859             <member>c</member><member>character (only printable 0x20-0x7f are actually printed)</member>
1860             <member>b</member><member>8 bit unsigned hexadecimal integer</member>
1861             <member>g</member><member>GUID</member>
1862           </simplelist>
1863         </para>
1864       </sect2>
1865
1866       <sect2>
1867         <title>Information on Wine's internals</title>
1868
1869         <para>
1870           <table>
1871             <title>WineDbg's Win32 objects management</title>
1872             <tgroup cols="2" align="left">
1873               <tbody>
1874                 <row>
1875                   <entry><command>info&nbsp;class</command></entry>
1876                   <entry>
1877                     lists all Windows' classes registered in Wine
1878                   </entry>
1879                 </row>
1880                 <row>
1881                   <entry>
1882                     <command>
1883                       info&nbsp;class&nbsp;&lt;id&gt;
1884                     </command>
1885                   </entry>
1886                   <entry>
1887                     prints information on Windows's class &lt;id&gt;
1888                   </entry>
1889                 </row>
1890                 <row>
1891                   <entry><command>info&nbsp;share;</command></entry>
1892                   <entry>
1893                     lists all the dynamic libraries loaded in the
1894                     debugged program (including .so files, NE and PE
1895                     DLLs)
1896                   </entry>
1897                 </row>
1898                 <row>
1899                   <entry>
1900                     <command>
1901                       info&nbsp;share&nbsp;&lt;N&gt;;
1902                     </command>
1903                   </entry>
1904                   <entry>
1905                     prints information on module at address &lt;N&gt;
1906                   </entry>
1907                 </row>
1908                 <row>
1909                   <entry><command>info regs;</command></entry>
1910                   <entry>
1911                     prints the value of the CPU registers
1912                   </entry>
1913                 </row>
1914                 <row>
1915                   <entry>
1916                     <command>info segment &lt;N&gt;;</command>
1917                   </entry>
1918                   <entry>
1919                     prints information on segment &lt;N&gt; (i386
1920                     only)
1921                   </entry>
1922                 </row>
1923                 <row>
1924                   <entry>
1925                     <command>info&nbsp;segment;</command>
1926                   </entry>
1927                   <entry>
1928                     lists all allocated segments (i386 only)
1929                   </entry>
1930                 </row>
1931                 <row>
1932                   <entry><command>info&nbsp;stack;</command></entry>
1933                   <entry>
1934                     prints the values on top of the stack
1935                   </entry>
1936                 </row>
1937                 <row>
1938                   <entry><command>info&nbsp;map;</command></entry>
1939                   <entry>
1940                     lists all virtual mappings used by the debugged
1941                     program
1942                   </entry>
1943                 </row>
1944                 <row>
1945                   <entry>
1946                     <command>info&nbsp;map&nbsp;&lt;N&gt;</command>
1947                   </entry>
1948                   <entry>
1949                     lists all virtual mappings used by the program of
1950                     pid &lt;N&gt;
1951                   </entry>
1952                 </row>
1953                 <row>
1954                   <entry>
1955                     <command>info&nbsp;wnd&nbsp;&lt;N&gt;</command>
1956                   </entry>
1957                   <entry>
1958                     prints information of Window of handle &lt;N&gt;
1959                   </entry>
1960                 </row>
1961                 <row>
1962                   <entry><command>info&nbsp;wnd</command></entry>
1963                   <entry>
1964                     lists all the window hierarchy starting from the
1965                     desktop window
1966                   </entry>
1967                 </row>
1968                 <row>
1969                   <entry><command>info process</command></entry>
1970                   <entry>
1971                     lists all w-processes in Wine session
1972                   </entry>
1973                 </row>
1974                 <row>
1975                   <entry><command>info&nbsp;thread</command></entry>
1976                   <entry>lists all w-threads in Wine session</entry>
1977                 </row>
1978                 <row>
1979                   <entry><command>info&nbsp;exception</command></entry>
1980                   <entry>
1981                     lists the exception frames (starting from current
1982                     stack frame)
1983                   </entry>
1984                 </row>
1985               </tbody>
1986             </tgroup>
1987           </table>
1988         </para>
1989       </sect2>
1990
1991       <sect2 id="winedbg-dbg-chan">
1992         <title>Debug channels</title>
1993         <para>
1994           It is possible to turn on and off debug messages as you
1995           are debugging using the set command.
1996           See <xref linkend="debugging"> for more details on debug
1997           channels.
1998         </para>
1999
2000         <para>
2001           <table>
2002             <title>WineDbg's debug channels' management</title>
2003             <tgroup cols="2" align="left">
2004               <tbody>
2005                 <row>
2006                   <entry>
2007                     <command>set&nbsp;+&nbsp;warn&nbsp;win</command>
2008                   </entry>
2009                   <entry>turn on warn on 'win' channel</entry>
2010                 </row>
2011                 <row>
2012                   <entry>
2013                     <command>set&nbsp;+&nbsp;win</command>
2014                   </entry>
2015                   <entry>
2016                     turn on warn/fixme/err/trace on 'win' channel
2017                   </entry>
2018                 </row>
2019                 <row>
2020                   <entry>
2021                     <command>set&nbsp;-&nbsp;win</command>
2022                   </entry>
2023                   <entry>
2024                     turn off warn/fixme/err/trace on 'win' channel
2025                   </entry>
2026                 </row>
2027                 <row>
2028                   <entry>
2029                     <command>set&nbsp;-&nbsp;fixme</command>
2030                   </entry>
2031                   <entry>turn off the 'fixme' class</entry>
2032                 </row>
2033               </tbody>
2034             </tgroup>
2035           </table>
2036         </para>
2037       </sect2>
2038
2039     </sect1>
2040
2041     <sect1 id="dbg-others">
2042       <title>Other debuggers</title>
2043
2044       <sect2>
2045         <title>GDB mode</title>
2046
2047         <para>
2048           WineDbg can act as a remote monitor for GDB. This allows to
2049           use all the power of GDB, but while debugging wine and/or
2050           any Win32 application. To enable this mode, just add
2051           <parameter>--gdb</parameter> to winedbg command line. You'll
2052           end up on a GDB prompt. You'll have to use the GDB commands
2053           (not WineDbg's).
2054         </para>
2055
2056         <para>
2057           However, some limitation in GDB while debugging wine (see
2058           below) don't appear in this mode:
2059           <itemizedlist>
2060             <listitem>
2061               <para>
2062                 GDB will correctly present Win32 thread
2063                 information and breakpoint behavior
2064               </para>
2065             </listitem>
2066             <listitem>
2067               <para>
2068                 Moreover, it also provides support for the Dwarf II
2069                 debug format (which became the default format (instead
2070                 of stabs) in gcc 3.1).
2071               </para>
2072             </listitem>
2073           </itemizedlist>
2074         </para>
2075
2076         <para>
2077           A few Wine extensions available through the monitor command.
2078           <table>
2079             <title>WineDbg's debug channels' management</title>
2080             <tgroup cols="2" align="left">
2081               <tbody>
2082                 <row>
2083                   <entry><command>monitor&nbsp;wnd</command></entry>
2084                   <entry>lists all window in the Wine session</entry>
2085                 </row>
2086                 <row>
2087                   <entry><command>monitor&nbsp;proc</command></entry>
2088                   <entry>
2089                     lists all processes in the Wine session
2090                   </entry>
2091                 </row>
2092                 <row>
2093                   <entry><command>monitor&nbsp;mem</command></entry>
2094                   <entry>
2095                     displays memory mapping of debugged process
2096                   </entry>
2097                 </row>
2098               </tbody>
2099             </tgroup>
2100           </table>
2101         </para>
2102       </sect2>
2103
2104       <sect2>
2105         <title>Graphical frontends to gdb</title>
2106
2107         <para>
2108           This section will describe how you can debug Wine using the
2109           GDB mode of winedbg and some graphical front ends to GDB for
2110           those of you who really like graphical debuggers.
2111         </para>
2112
2113         <sect3>
2114           <title>DDD</title>
2115
2116           <para>
2117             Use the following steps, in this order:
2118             <orderedlist>
2119               <listitem>
2120                 <para>
2121                   Start the Wine debugger with a command line like:
2122 <screen>
2123         winedbg --gdb --no-start &lt;name_of_exe_to_debug.exe&gt;
2124 </screen>
2125                 </para>
2126               </listitem>
2127               <listitem>
2128                 <para>
2129                   Start ddd
2130                 </para>
2131               </listitem>
2132               <listitem>
2133                 <para>
2134                   In ddd, use the 'Open File' or 'Open Program' to
2135                   point to the Wine executable (which is either
2136                   wine-pthread or wine-kthread depending on your
2137                   settings).
2138                 </para>
2139               </listitem>
2140               <listitem>
2141                 <para>
2142                   In the output of 1/, there's a line like
2143 <screen>
2144         target remote localhost:32878
2145 </screen>
2146                   copy that line and paste into ddd command pane (the
2147                   one with the (gdb) prompt)
2148                 </para>
2149               </listitem>
2150             </orderedlist>
2151             The program should now be loaded and up and running. If
2152             you want, you can also add in 1/ after the name of the
2153             exec all the needed parameters
2154           </para>
2155         </sect3>
2156         <sect3>
2157           <title>kdbg</title>
2158
2159           <para>
2160             Use the following steps, in this order:
2161             <orderedlist>
2162               <listitem>
2163                 <para>
2164                   Start the Wine debugger with a command line like:
2165 <screen>
2166         winedbg --gdb --no-start &lt;name_of_exe_to_debug.exe&gt;
2167 </screen>
2168 </para>
2169               </listitem>
2170               <listitem>
2171                 <para>
2172                   In the output of 1/, there's a line like
2173 <screen>
2174         target remote localhost:32878
2175 </screen>
2176                   Start kdbg with
2177 <screen>
2178 kdbg -r localhost:32878 wine
2179 </screen>
2180                   localhost:32878 is not a fixed value, but has been
2181                   printed in step 1/. 'wine' should also be the full
2182                   path to the Wine executable (which is either
2183                   wine-pthread or wine-kthread depending on your settings).
2184                 </para>
2185               </listitem>
2186             </orderedlist>
2187             The program should now be loaded and up and running. If
2188             you want, you can also add in 1/ after the name of the
2189             exec all the needed parameters
2190           </para>
2191         </sect3>
2192       </sect2>
2193
2194       <sect2>
2195         <title>Using other Unix debuggers</title>
2196
2197         <para>
2198           You can also use other debuggers (like
2199           <command>gdb</command>), but you must be aware of a few
2200           items:
2201         </para>
2202         <para>
2203           You need to attach the unix debugger to the correct unix
2204           process (representing the correct windows thread) (you can
2205           "guess" it from a <command>ps fax</command> for example:
2206           When running the emulator, usually the first two
2207           <varname>upids</varname> are for the Windows' application
2208           running the desktop, the first thread of the application is
2209           generally the third <varname>upid</varname>; when running a
2210           Winelib program, the first thread of the application is
2211           generally the first <varname>upid</varname>)
2212         </para>
2213         <note>
2214           <para>
2215             Even if latest <command>gdb</command> implements the
2216             notion of threads, it won't work with Wine because the
2217             thread abstraction used for implementing Windows' thread
2218             is not 100% mapped onto the Linux POSIX threads
2219             implementation. It means that you'll have to spawn a
2220             different <command>gdb</command> session for each Windows'
2221             thread you wish to debug.
2222           </para>
2223         </note>
2224
2225         <para>
2226           Here's how to get info about the current execution status of a
2227           certain Wine process:
2228         </para>
2229         <para>
2230           Change into your Wine source dir and enter:
2231         </para>
2232         <screen>
2233 $ gdb wine
2234         </screen>
2235         <para>
2236           Switch to another console and enter <command>ps ax | grep
2237             wine</command> to find all wine processes. Inside
2238           <command>gdb</command>, repeat for all Wine processes:
2239         </para>
2240         <screen>
2241 (gdb) attach <userinput>PID</userinput>
2242         </screen>
2243         <para>
2244           with <userinput>PID</userinput> being the process ID of one of
2245           the Wine processes.  Use
2246         </para>
2247         <screen>
2248 (gdb) bt
2249         </screen>
2250         <para>
2251           to get the backtrace of the current Wine process, i.e. the
2252           function call history.  That way you can find out what the
2253           current process is doing right now.  And then you can use
2254           several times:
2255         </para>
2256         <screen>
2257 (gdb) n
2258         </screen>
2259         <para>
2260           or maybe even
2261         </para>
2262         <screen>
2263 (gdb) b <userinput>SomeFunction</userinput>
2264         </screen>
2265         <para>
2266           and
2267         </para>
2268         <screen>
2269 (gdb) c
2270         </screen>
2271         <para>
2272           to set a breakpoint at a certain function and continue up to
2273           that function.  Finally you can enter
2274         </para>
2275         <screen>
2276 (gdb) detach
2277         </screen>
2278         <para>
2279           to detach from the Wine process.
2280         </para>
2281         <!-- *** End of xtra content *** -->
2282       </sect2>
2283
2284       <sect2>
2285         <title>Using other Windows debuggers</title>
2286
2287         <para>
2288           You can use any Windows' debugging API compliant debugger
2289           with Wine. Some reports have been made of success with
2290           VisualStudio debugger (in remote mode, only the hub runs
2291           in Wine). GoVest fully runs in Wine.
2292         </para>
2293       </sect2>
2294
2295       <sect2>
2296         <title>Main differences between winedbg and regular Unix debuggers</title>
2297         <table><title>Debuggers comparison</title>
2298           <tgroup cols=2 align="left">
2299             <tbody>
2300               <row>
2301                 <entry>WineDbg</entry><entry>gdb</entry>
2302               </row>
2303               <row>
2304                 <entry>
2305                   WineDbg debugs a Windows' process: the various
2306                   threads will be handled by the same WineDbg session,
2307                   and a breakpoint will be triggered for any thread of
2308                   the W-process
2309                 </entry>
2310                 <entry>
2311                   gdb debugs a Windows' thread: a separate gdb session
2312                   is needed for each thread of a Windows' process and
2313                   a breakpoint will be triggered only for the w-thread
2314                   debugged
2315                 </entry>
2316               </row>
2317               <row>
2318                 <entry>
2319                   WineDbg supports debug information from stabs
2320                   (standard Unix format) and Microsoft's C, CodeView,
2321                   .DBG
2322                 </entry>
2323                 <entry>
2324                   GDB supports debug information from stabs (standard
2325                   Unix format) and Dwarf II.
2326                 </entry>
2327               </row>
2328             </tbody>
2329           </tgroup>
2330         </table>
2331       </sect2>
2332     </sect1>
2333
2334
2335     <sect1 id="dbg-limits">
2336       <title>Limitations</title>
2337
2338       <itemizedlist>
2339         <listitem>
2340           <para>
2341             16 bit processes are not supported (but calls to 16 bit
2342             code in 32 bit  applications are).
2343           </para>
2344         </listitem>
2345         <listitem>
2346           <para>
2347             Function call in expression is no longer supported
2348           </para>
2349         </listitem>
2350       </itemizedlist>
2351     </sect1>
2352   </chapter>
2353
2354 <!-- Keep this comment at the end of the file
2355 Local variables:
2356 mode: sgml
2357 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
2358 End:
2359 -->