documentation/debugger.sgml

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