1 <chapter id="debugger">
2 <title>Debugging Wine</title>
5 <title>Introduction</title>
8 <title>Processes and threads: in underlying OS and in Windows</title>
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.
18 Each Windows' thread is implemented as a Unix thread, meaning
19 that all threads of a same Windows' process share the same
28 <varname>W-process</varname> means a process in Windows' terminology
33 <varname>U-process</varname> means a process in Unix' terminology
38 <varname>W-thread</varname> means a thread in Windows' terminology
43 A <varname>W-process</varname> is made of one or several
44 <varname>W-threads</varname>. Each
45 <varname>W-thread</varname> is mapped to one and only one
46 <varname>U-process</varname>. All
47 <varname>U-processes</varname> of a same
48 <varname>W-process</varname> share the same address space.
51 Each Unix process can be identified by two values:
56 the Unix process id (<varname>upid</varname> in the following)
61 the Windows's thread id (<varname>tid</varname>)
66 Each Windows' process has also a Windows' process id
67 (<varname>wpid</varname> in the following). It must be clear
68 that <varname>upid</varname> and <varname>wpid</varname> are
69 different and shall not be used instead of the other.
72 <varname>Wpid</varname> and <varname>tid</varname> are
73 defined (Windows) system wide. They must not be confused
74 with process or thread handles which, as any handle, is an
75 indirection to a system object (in this case process or
76 thread). A same process can have several different handles
77 on the same kernel object. The handles can be defined as
78 local (the values is only valid in a process), or system
79 wide (the same handle can be used by any
80 <varname>W-process</varname>).
85 <title>Wine, debugging and WineDbg</title>
88 When talking of debugging in Wine, there are at least two
94 the Windows' debugging API.
99 the Wine integrated debugger, dubbed <command>winedbg</command>.
104 Wine implements most of the Windows' debugging API. The
105 first part of the debugging APIs (in
106 <filename>KERNEL32.DLL</filename>) allows a W-process, called
107 the debugger, to control the execution of another W-process,
108 the debuggee. To control means stopping/resuming execution,
109 enabling/disabling single stepping, setting breakpoints,
110 reading/writing debuggee memory... Another part of the
111 debugging APIs resides in <filename>DBGHELP.DLL</filename>
112 (and its ancestor <filename>IMAGEHLP.DLL</filename>) and lets
113 a debugger look into symbols and types from any module (if
114 the module has been compiled with the proper options).
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).
127 <sect1 id="dbg-modes">
128 <title>WineDbg's modes of invocation</title>
131 <title>Starting a process</title>
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:
141 winedbg hl.exe -windowed
146 <title>Attaching</title>
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.
162 <sect2 id="dbg-on-exception">
163 <title id="dbg-exception-title">On exceptions</title>
166 When something goes wrong, Windows tracks this as an
167 exception. Exceptions exist for segmentation violation,
168 stack overflow, division by zero, etc.
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.
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
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.
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:
204 <term>continue</term>
207 the debugger had the ability to correct what's
208 generated the exception, and is now able to continue
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
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>.
243 <sect2 id="interrupt">
244 <title>Interrupting</title>
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.
254 <title>Quitting</title>
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).
265 <sect1 id="wine-debugger">
266 <title>Using the Wine Debugger</title>
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
277 <title>Crashes</title>
280 These usually show up like this:
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 ...
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
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
298 |0050: sel=0287 base=40211d30 limit=0b93f (bytes) 16-bit rw-
300 |0 0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c)
301 |1 0x01b7:0x1e5b (PXSRV_FONPUTCATFONT+0x2cd)
303 |3 0x01b7:0x0768 (PXSRV_FONINITFONTS+0x81)
304 |4 0x014f:0x03ed (PDOXWIN_@SQLCURCB$Q6CBTYPEULN8CBSCTYPE+0x1b1)
307 |0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c): movw %es:0x38(%bx),%dx
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.
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
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).
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
342 |Call KERNEL.90: LSTRLEN(0227:0692 "text") ret=01e7:2ce7 ds=0227
343 ^^^^^^^^^ ^ ^^^^^^^^^ ^^^^^^ ^^^^^^^^^ ^^^^
344 | | | | | |Datasegment
345 | | | | |Return address
346 | | | |textual parameter
348 | | |Argument(s). This one is a win16 segmented pointer.
350 |The module, the function is called in. In this case it is KERNEL.
352 |Ret KERNEL.90: LSTRLEN() retval=0x0004 ret=01e7:2ce7 ds=0227
354 |Returnvalue is 16 bit and has the value 4.
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(<channel>);</function>
363 at the beginning of the file. Rerun wine with the
364 <parameter>WINEDEBUG=+xyz,+relay</parameter> environment variable set.
367 Occasionally there are additional debug channels defined at the
368 beginning of the file in the form.
369 <function>WINE_DECLARE_DEBUG_CHANNEL(<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_(<channel>)(" ... /n");</function> and add any
373 additional channels to the commandline.
378 Additional information on how to debug using the internal
379 debugger can be found in
380 <filename>programs/winedbg/README</filename>.
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
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).
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.
426 <title>Program hangs, nothing happens</title>
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
439 <title>Program reports an error with a Messagebox</title>
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.
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.
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>.
465 <title>Disassembling programs</title>
468 You may also try to disassemble the offending program to
469 check for undocumented features and/or use of them.
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</>).
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.
491 Most code out there uses standard C function entries (for it
492 is usually written in C). Win16 function entries usually
499 retf XXXX <--------- XXXX is number of bytes of arguments
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>.
514 Most functions make also use of local storage in the stackframe:
518 ... function code ...
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
530 push word ptr [bp-02] <- will be at [bp+8]
531 push di <- will be at [bp+6]
535 Here first the selector and then the offset to the passed
541 <title>Sample debugging session</title>
544 Let's debug the infamous Word <filename>SHARE.EXE</filename>
548 |marcus@jet $ wine winword.exe
549 | +---------------------------------------------+
550 | | ! You must leave Windows and load SHARE.EXE|
551 | | before starting Word. |
552 | +---------------------------------------------+
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
566 |Wine-dbg>break MessageBoxA <---- Set Breakpoint
567 |Breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
568 |Wine-dbg>c <---- 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 |... <----- Much debugoutput
573 |Call KERNEL.136: GETDRIVETYPE(0x0000) ret=060f:097b ds=0927
575 |Ret KERNEL.136: GETDRIVETYPE() retval=0x0002 ret=060f:097b ds=0927
576 ^^^^^^ DRIVE_REMOVEABLE
577 (It is a floppy diskdrive.)
579 |Call KERNEL.136: GETDRIVETYPE(0x0001) ret=060f:097b ds=0927
581 |Ret KERNEL.136: GETDRIVETYPE() retval=0x0000 ret=060f:097b ds=0927
582 ^^^^^^ DRIVE_CANNOTDETERMINE
583 (I don't have drive B: assigned)
585 |Call KERNEL.136: GETDRIVETYPE(0x0002) ret=060f:097b ds=0927
587 |Ret KERNEL.136: GETDRIVETYPE() retval=0x0003 ret=060f:097b ds=0927
589 (specified as a harddisk)
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:.
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.
601 Whoops, it even detects that something is wrong!
604 |Ret KERNEL.97: GETTEMPFILENAME() retval=0x9281 ret=060f:09b1 ds=0927
605 ^^^^^^ Temporary storage ID
607 |Call KERNEL.74: OPENFILE(0x09278248"C:~doc9281.tmp",0927:82da,0x1012) ret=060f:09d8 ds=0927
608 ^^^^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^
609 |filename |OFSTRUCT |open mode:
611 OF_CREATE|OF_SHARE_EXCLUSIVE|OF_READWRITE
614 This fails, since my <medialabel>C:</medialabel> drive is in
615 this case mounted readonly.
618 |Ret KERNEL.74: OPENFILE() retval=0xffff ret=060f:09d8 ds=0927
619 ^^^^^^ HFILE_ERROR16, yes, it failed.
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
627 |Stopped on breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
628 |190 { <- the sourceline
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
641 <title>Debugging Tips</title>
644 Here are some additional debugging tips:
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
654 WINEDEBUG=+relay wine program
656 to get a listing of the functions the program calls in its start function.
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.
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.
679 WINEDEBUG=+relay wine <program name> &>relmsg
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
684 Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
686 In my example the lines before the call to
687 <function>MessageBox()</function> look like that:
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
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>.
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>:
726 Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
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>).
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.
753 Then do a <userinput>c</userinput> until you are able to
754 set this breakpoint without error message.
759 Some useful programs:
764 <application>IDA</application>:
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>
772 <emphasis>Very</emphasis> good DOS disassembler ! It's badly needed
773 for debugging Wine sometimes.
779 <application>XRAY</application>:
781 <ulink url="http://garbo.uwasa.fi/pub/pc/sysinfo/xray15.zip">
782 http://garbo.uwasa.fi/pub/pc/sysinfo/xray15.zip</ulink>
787 Traces DOS calls (Int 21h, DPMI, ...). Use it with
788 Windows to correct file management problems etc.
794 <application>pedump</application>:
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>
802 Dumps the imports and exports of a PE (Portable
809 <application>winedump</application>:
813 Dumps the imports and exports of a PE (Portable
814 Executable) DLL (included in wine tree).
824 <title>Some basic debugger usages</title>
827 After starting your program with
830 wine -debug myprog.exe
833 the program loads and you get a prompt at the program
834 starting point. Then you can set breakpoints:
837 b RoutineName (by routine name) OR
838 b *0x812575 (by address)
841 Then you hit <command>c</command> (continue) to run the
842 program. It stops at the breakpoint. You can type
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
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 <line number> (to list source code)
853 x <variable name> (to examine a variable; only works if code
854 is not compiled with optimization)
855 x 0x4269978 (to examine a memory location)
860 By hitting <keycap>Enter</keycap>, you repeat the last
867 <sect1 id="memory-addresses">
868 <title>Useful memory addresses</title>
870 Wine uses several different kinds of memory addresses.
875 Win32/"normal" Wine addresses/Linux: linear addresses.
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
890 Win16 "enhanced mode": segmented addresses.
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.
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.
921 DOS/Win16 "standard mode"
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.
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,
950 <sect1 id="dbg-config">
951 <title>Configuration</title>
954 <title>Registry configuration</title>
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
964 "MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug"
967 Determine the behavior:
971 <term>Debugger</term>
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
982 The path to the debugger you chose to use must be reachable
983 via a DOS drive in the Wine config file !
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.
1001 A regular Wine registry looks like:
1004 [MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug] 957636538
1005 "Auto"=dword:00000001
1006 "Debugger"="winedbg %ld %ld"
1010 <title>Note 1</title>
1012 creating this key is mandatory. Not doing so will not
1013 fire the debugger when an exception occurs.
1017 <title>Note 2</title>
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
1026 [MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]
1029 key before running again <command>wineinstall</command> to
1030 regenerate this key.
1036 <title>WineDbg configuration</title>
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)
1044 [HKCU\\Software\\Wine\\WineDbg]
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,
1053 set $BreakAllThreadsStartup = 1
1056 sets the option <varname>BreakAllThreadsStartup</varname> to
1057 <literal>TRUE</literal>.
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).
1068 Here's the list of all options:
1073 <term><varname>BreakAllThreadsStartup</varname></term>
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.
1085 <term><varname>BreakOnCritSectTimeOut</varname></term>
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.
1095 <term><varname>BreakOnAttach</varname></term>
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>.
1111 <term><varname>BreakOnFirstChance</varname></term>
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
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
1136 <term><varname>AlwaysShowThunk</varname></term>
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.
1152 <sect1 id="dbg-expr">
1153 <title>WineDbg Expressions and Variables</title>
1155 <title>Expressions</title>
1158 Expressions in Wine Debugger are mostly written in a C
1159 form. However, there are a few discrepancies:
1163 Identifiers can take a '!' in their names. This allow
1164 mainly to access symbols from different DLLs like
1165 <function>USER32!CreateWindowExA</function>.
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).
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
1184 In lots of cases, you can also use regular expressions for
1185 looking for a symbol.
1188 <command>winedbg</command> defines its own set of
1189 variables. The configuration variables from above are part
1190 of them. Some others include:
1193 <term><varname>$ThreadId</varname></term>
1196 ID of the <varname>W-thread</varname> currently
1197 examined by the debugger
1202 <term><varname>$ProcessId</varname></term>
1205 ID of the <varname>W-thread</varname> currently
1206 examined by the debugger
1211 <term><registers></term>
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
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.
1230 <sect1 id="dbg-commands">
1231 <title>WineDbg Command Reference</title>
1238 <title>WineDbg's misc. commands</title>
1239 <tgroup cols="2" align="left">
1242 <entry><command>abort</command></entry>
1243 <entry>aborts the debugger</entry>
1246 <entry><command>quit</command></entry>
1247 <entry>exits the debugger</entry>
1250 <entry><command>attach N</command></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.
1259 <entry><command>detach</command></entry>
1260 <entry>detach from a W-process.</entry>
1263 <entry><command>help</command></entry>
1264 <entry>prints some help on the commands</entry>
1267 <entry><command>help info</command></entry>
1268 <entry>prints some help on info commands</entry>
1277 <title>Flow control</title>
1281 <title>WineDbg's flow control commands</title>
1282 <tgroup cols="2" align="left">
1287 <simplelist type="inline">
1288 <member><command>cont</command></member>
1289 <member><command>c</command></member>
1293 <entry>continue execution until next breakpoint or
1297 <entry><command>pass</command></entry>
1298 <entry>pass the exception event up to the filter
1304 <simplelist type="inline">
1305 <member><command>step</command></member>
1306 <member><command>s</command></member>
1311 continue execution until next 'C' line of code
1312 (enters function call)
1318 <simplelist type="inline">
1319 <member><command>next</command></member>
1320 <member><command>n</command></member>
1325 continue execution until next 'C' line of code
1326 (doesn't enter function call)
1332 <simplelist type="inline">
1333 <member><command>stepi</command></member>
1334 <member><command>si</command></member>
1339 execute next assembly instruction (enters function
1346 <simplelist type="inline">
1347 <member><command>nexti</command></member>
1348 <member><command>ni</command></member>
1353 execute next assembly instruction (doesn't enter
1360 <simplelist type="inline">
1361 <member><command>finish</command></member>
1362 <member><command>f</command></member>
1366 <entry>execute until current function is exited</entry>
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.
1381 <title>Breakpoints, watch points</title>
1385 <title>WineDbg's break & watch points</title>
1386 <tgroup cols="2" align="left">
1389 <entry><command>enable N</command></entry>
1390 <entry>enables (break|watch)point #N</entry>
1393 <entry><command>disable N</command></entry>
1394 <entry>disables (break|watch)point #N</entry>
1397 <entry><command>delete N</command></entry>
1398 <entry>deletes (break|watch)point #N</entry>
1401 <entry><command>cond N</command></entry>
1403 removes any existing condition to
1404 (break|watch)point N
1409 <command>cond N <expr></command>
1412 adds condition <expr> to (break|watch)point
1413 N. <expr> will be evaluated each time the
1414 breakpoint is hit. If the result is a zero value,
1415 the breakpoint isn't triggered
1419 <entry><command>break * N</command></entry>
1420 <entry>adds a breakpoint at address N</entry>
1423 <entry><command>break <id></command></entry>
1425 adds a breakpoint at the address of symbol
1430 <entry><command>break <id> N</command></entry>
1432 adds a breakpoint at the address of symbol
1437 <entry><command>break N</command></entry>
1439 adds a breakpoint at line N of current source file
1443 <entry><command>break</command></entry>
1445 adds a breakpoint at current $PC address
1449 <entry><command>watch * N</command></entry>
1451 adds a watch command (on write) at address N (on 4
1456 <entry><command>watch <id></command></entry>
1458 adds a watch command (on write) at the address of
1463 <entry><command>info break</command></entry>
1465 lists all (break|watch)points (with state)
1473 You can use the symbol <emphasis>EntryPoint</emphasis> to stand for
1474 the entry point of the Dll.
1477 When setting a break/watch-point by <id>, 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).
1486 <title>Stack manipulation</title>
1490 <title>WineDbg's stack manipulation</title>
1491 <tgroup cols="2" align="left">
1494 <entry><command>bt</command></entry>
1495 <entry>print calling stack of current thread</entry>
1498 <entry><command>bt N</command></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)
1507 <entry><command>up</command></entry>
1509 goes up one frame in current thread's stack
1513 <entry><command>up N</command></entry>
1515 goes up N frames in current thread's stack
1519 <entry><command>dn</command></entry>
1521 goes down one frame in current thread's stack
1525 <entry><command>dn N</command></entry>
1527 goes down N frames in current thread's stack
1531 <entry><command>frame N</command></entry>
1533 set N as the current frame for current thread's
1538 <entry><command>info local</command></entry>
1540 prints information on local variables for current
1551 <title>Directory & source file manipulation</title>
1555 <title>WineDbg's directory & source file manipulation</title>
1556 <tgroup cols="2" align="left">
1559 <entry><command>show dir</command></entry>
1561 prints the list of dir:s where source files are
1567 <command>dir <pathname></command>
1570 adds <pathname> to the list of dir:s
1571 where to look for source files
1575 <entry><command>dir</command></entry>
1577 deletes the list of dir:s where to look for source
1584 symbolfile <pathname>
1587 <entry>loads external symbol definition</entry>
1592 symbolfile <pathname> N
1596 loads external symbol definition (applying an
1597 offset of N to addresses)
1601 <entry><command>list</command></entry>
1603 lists 10 source lines forwards from current
1608 <entry><command>list -</command></entry>
1610 lists 10 source lines backwards from current
1615 <entry><command>list N</command></entry>
1617 lists 10 source lines from line N in current file
1622 <command>list <path>:N</command>
1625 lists 10 source lines from line N in file
1630 <entry><command>list <id></command></entry>
1632 lists 10 source lines of function <id>
1636 <entry><command>list * N</command></entry>
1637 <entry>lists 10 source lines from address N</entry>
1645 You can specify the end target (to change the 10 lines
1646 value) using the ','. For example:
1648 <title>WineDbg's list command examples</title>
1649 <tgroup cols="2" align="left">
1652 <entry><command>list 123, 234</command></entry>
1654 lists source lines from line 123 up to line 234 in
1659 <entry><command>list foo.c:1, 56</command></entry>
1661 lists source lines from line 1 up to 56 in file
1672 <title>Displaying</title>
1675 A display is an expression that's evaluated and printed
1676 after the execution of any <command>winedbg</command>
1680 <command>winedbg</command> will automatically detect if the
1681 expression you entered contains a local variable. If so,
1682 display will only be shown if the context is still in the
1683 same function as the one the debugger was in when the
1684 display expression was entered.
1688 <title>WineDbg's displays</title>
1689 <tgroup cols="2" align="left">
1693 <command>info display</command>
1695 <entry>lists the active displays</entry>
1699 <command>display</command>
1702 print the active displays' values (as done each
1703 time the debugger stops)
1708 <command>display <expr></command>
1711 adds a display for expression <expr>
1717 display /fmt <expr>
1721 adds a display for expression
1722 <expr>. Printing evaluated <expr> is
1723 done using the given format (see
1724 <command>print</command> command for more on
1731 <simplelist type="inline">
1733 <command>del display N</command>
1736 <command>undisplay N</command>
1741 <entry>deletes display #N</entry>
1750 <title>Disassembly</title>
1754 <title>WineDbg's dissassembly</title>
1755 <tgroup cols="2" align="left">
1758 <entry><command>disas</command></entry>
1759 <entry>disassemble from current position</entry>
1763 <command>disas <expr></command>
1766 disassemble from address <expr>
1772 disas <expr>,<expr>
1776 disassembles code between addresses specified by
1777 the two <expr>
1787 <title>Memory (reading, writing, typing)</title>
1791 <title>WineDbg's memory management</title>
1792 <tgroup cols="2" align="left">
1796 <command>x <expr></command>
1799 examines memory at <expr> address
1805 x /fmt <expr>
1809 examines memory at <expr> address using
1816 print <expr>
1820 prints the value of <expr> (possibly using
1827 print /fmt <expr>
1830 <entry>prints the value of <expr> (possibly
1837 set <lval> = <expr>
1841 writes the value of <expr> in <lval>
1847 whatis <expr>
1851 prints the C type of expression <expr>
1859 <filename>/fmt</filename> is either <filename>/<letter></filename> or
1860 <filename>/<count><letter></filename> letter can be
1861 <simplelist type="horiz" columns="2">
1862 <member>s</member><member>an ASCII string</member>
1863 <member>u</member><member>an Unicode UTF16 string</member>
1864 <member>i</member><member>instructions (disassemble)</member>
1865 <member>x</member><member>32 bit unsigned hexadecimal integer</member>
1866 <member>d</member><member>32 bit signed decimal integer</member>
1867 <member>w</member><member>16 bit unsigned hexadecimal integer</member>
1868 <member>c</member><member>character (only printable 0x20-0x7f are actually printed)</member>
1869 <member>b</member><member>8 bit unsigned hexadecimal integer</member>
1870 <member>g</member><member>GUID</member>
1876 <title>Information on Wine's internals</title>
1880 <title>WineDbg's Win32 objects management</title>
1881 <tgroup cols="2" align="left">
1884 <entry><command>info class</command></entry>
1886 lists all Windows' classes registered in Wine
1892 info class <id>
1896 prints information on Windows's class <id>
1900 <entry><command>info share</command></entry>
1902 lists all the dynamic libraries loaded in the
1903 debugged program (including .so files, NE and PE
1910 info share <N>
1914 prints information on module at address <N>
1918 <entry><command>info regs</command></entry>
1920 prints the value of the CPU registers
1925 <command>info segment <N></command>
1928 prints information on segment <N> (i386
1934 <command>info segment</command>
1937 lists all allocated segments (i386 only)
1941 <entry><command>info stack</command></entry>
1943 prints the values on top of the stack
1947 <entry><command>info map</command></entry>
1949 lists all virtual mappings used by the debugged
1955 <command>info map <N></command>
1958 lists all virtual mappings used by the program of
1964 <command>info wnd <N></command>
1967 prints information of Window of handle <N>
1971 <entry><command>info wnd</command></entry>
1973 lists all the window hierarchy starting from the
1978 <entry><command>info process</command></entry>
1980 lists all w-processes in Wine session
1984 <entry><command>info thread</command></entry>
1985 <entry>lists all w-threads in Wine session</entry>
1988 <entry><command>info exception</command></entry>
1990 lists the exception frames (starting from current
2000 <sect2 id="winedbg-dbg-chan">
2001 <title>Debug channels</title>
2003 It is possible to turn on and off debug messages as you
2004 are debugging using the set command.
2005 See <xref linkend="debugging"> for more details on debug
2011 <title>WineDbg's debug channels' management</title>
2012 <tgroup cols="2" align="left">
2016 <command>set + warn win</command>
2018 <entry>turn on warn on 'win' channel</entry>
2022 <command>set + win</command>
2025 turn on warn/fixme/err/trace on 'win' channel
2030 <command>set - win</command>
2033 turn off warn/fixme/err/trace on 'win' channel
2038 <command>set - fixme</command>
2040 <entry>turn off the 'fixme' class</entry>
2050 <sect1 id="dbg-others">
2051 <title>Other debuggers</title>
2054 <title>GDB mode</title>
2057 WineDbg can act as a remote monitor for GDB. This allows to
2058 use all the power of GDB, but while debugging wine and/or
2059 any Win32 application. To enable this mode, just add
2060 <parameter>--gdb</parameter> to winedbg command line. You'll
2061 end up on a GDB prompt. You'll have to use the GDB commands
2066 However, some limitation in GDB while debugging wine (see
2067 below) don't appear in this mode:
2071 GDB will correctly present Win32 thread
2072 information and breakpoint behavior
2077 Moreover, it also provides support for the Dwarf II
2078 debug format (which became the default format (instead
2079 of stabs) in gcc 3.1).
2086 A few Wine extensions available through the monitor command.
2088 <title>WineDbg's debug channels' management</title>
2089 <tgroup cols="2" align="left">
2092 <entry><command>monitor wnd</command></entry>
2093 <entry>lists all window in the Wine session</entry>
2096 <entry><command>monitor proc</command></entry>
2098 lists all processes in the Wine session
2102 <entry><command>monitor mem</command></entry>
2104 displays memory mapping of debugged process
2114 <title>Graphical frontends to gdb</title>
2117 This section will describe how you can debug Wine using the
2118 GDB mode of winedbg and some graphical front ends to GDB for
2119 those of you who really like graphical debuggers.
2126 Use the following steps, in this order:
2130 Start the Wine debugger with a command line like:
2132 winedbg --gdb --no-start <name_of_exe_to_debug.exe>
2143 In ddd, use the 'Open File' or 'Open Program' to
2144 point to the Wine executable (which is either
2145 wine-pthread or wine-kthread depending on your
2151 In the output of 1/, there's a line like
2153 target remote localhost:32878
2155 copy that line and paste into ddd command pane (the
2156 one with the (gdb) prompt)
2160 The program should now be loaded and up and running. If
2161 you want, you can also add in 1/ after the name of the
2162 exec all the needed parameters
2169 Use the following steps, in this order:
2173 Start the Wine debugger with a command line like:
2175 winedbg --gdb --no-start <name_of_exe_to_debug.exe>
2181 In the output of 1/, there's a line like
2183 target remote localhost:32878
2187 kdbg -r localhost:32878 wine
2189 localhost:32878 is not a fixed value, but has been
2190 printed in step 1/. 'wine' should also be the full
2191 path to the Wine executable (which is either
2192 wine-pthread or wine-kthread depending on your settings).
2196 The program should now be loaded and up and running. If
2197 you want, you can also add in 1/ after the name of the
2198 exec all the needed parameters
2204 <title>Using other Unix debuggers</title>
2207 You can also use other debuggers (like
2208 <command>gdb</command>), but you must be aware of a few
2212 You need to attach the unix debugger to the correct unix
2213 process (representing the correct windows thread) (you can
2214 "guess" it from a <command>ps fax</command> for example:
2215 When running the emulator, usually the first two
2216 <varname>upids</varname> are for the Windows' application
2217 running the desktop, the first thread of the application is
2218 generally the third <varname>upid</varname>; when running a
2219 Winelib program, the first thread of the application is
2220 generally the first <varname>upid</varname>)
2224 If you plan to used <command>gdb</command> for a
2225 multi-threaded Wine application (native or Winelib), then
2226 <command>gdb</command> will be able to handle the multiple
2227 threads directly only if:
2231 Wine is running on the pthread model (it won't work
2232 in the kthread one). See the Wine architecture
2233 documentation for further details.
2238 <command>gdb</command> supports the multi-threading
2239 (you need gdb at least 5.0 for that).
2243 In the unfortunate case (no direct thread support in
2244 <command>gdb</command> because one of the above conditions
2245 is false), you'll have to spawn a different
2246 <command>gdb</command> session for each Windows' thread
2247 you wish to debug (which means no synchronization for
2248 debugging purposes between the various threads).
2253 Here's how to get info about the current execution status of a
2254 certain Wine process:
2257 Change into your Wine source dir and enter:
2263 Switch to another console and enter <command>ps ax | grep
2264 wine</command> to find all wine processes. Inside
2265 <command>gdb</command>, repeat for all Wine processes:
2268 (gdb) attach <userinput>PID</userinput>
2271 with <userinput>PID</userinput> being the process ID of one of
2272 the Wine processes. Use
2278 to get the backtrace of the current Wine process, i.e. the
2279 function call history. That way you can find out what the
2280 current process is doing right now. And then you can use
2290 (gdb) b <userinput>SomeFunction</userinput>
2299 to set a breakpoint at a certain function and continue up to
2300 that function. Finally you can enter
2306 to detach from the Wine process.
2308 <!-- *** End of xtra content *** -->
2312 <title>Using other Windows debuggers</title>
2315 You can use any Windows' debugging API compliant debugger
2316 with Wine. Some reports have been made of success with
2317 VisualStudio debugger (in remote mode, only the hub runs
2318 in Wine). GoVest fully runs in Wine.
2323 <title>Main differences between winedbg and regular Unix debuggers</title>
2324 <table><title>Debuggers comparison</title>
2325 <tgroup cols=2 align="left">
2328 <entry>WineDbg</entry><entry>gdb</entry>
2332 WineDbg debugs a Windows' process: the various
2333 threads will be handled by the same WineDbg session,
2334 and a breakpoint will be triggered for any thread of
2338 gdb debugs a Windows' thread: a separate gdb session
2339 is needed for each thread of a Windows' process and
2340 a breakpoint will be triggered only for the w-thread
2346 WineDbg supports debug information from stabs
2347 (standard Unix format) and Microsoft's C, CodeView,
2351 GDB supports debug information from stabs (standard
2352 Unix format) and Dwarf II.
2363 <!-- Keep this comment at the end of the file
2366 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
projects / wine / blob