Fix the dwUrlPathLength returned by InternetCrackUrl when
[wine] / 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 -->