October 2005 - Wine-Commits

docs/en winedev-debugger.sgml
by Dimi Paun Oct. 4, 2005

Oct. 4, 2005

ChangeSet ID: 1128390724281499355406599 CVSROOT: /cvsroot/wine Module name: docs Changes by: dimi(a)sc8-pr-cvs1.sourceforge.net 2005/10/03 18:52:04 Modified files: en : winedev-debugger.sgml Log message: Molle Bestefich <molle.bestefich(a)gmail.com> Fix up winedev-debugger doc to match 0.9. Remove 404s, remove config file references, mention disassemblers that actually installs, etc. Old revision New revision Changes Path 1.2 1.3 +240 -149 docs/en/winedev-debugger.sgml Index: docs/en/winedev-debugger.sgml diff -u -p docs/en/winedev-debugger.sgml:1.2 docs/en/winedev-debugger.sgml:1.3 --- docs/en/winedev-debugger.sgml 4 Oct 2005 1:52: 4 -0000 +++ /dev/null 4 Oct 2005 1:52: 4 -0000 @@ -41,9 +41,9 @@ </itemizedlist> <para> A <varname>W-process</varname> is made of one or several - <varname>W-threads</varname>. Each + <varname>W-threads</varname>. Each <varname>W-thread</varname> is mapped to one and only one - <varname>U-process</varname>. All + <varname>U-process</varname>. All <varname>U-processes</varname> of a same <varname>W-process</varname> share the same address space. </para> @@ -64,17 +64,17 @@ </itemizedlist> <para> Each Windows' process has also a Windows' process id - (<varname>wpid</varname> in the following). It must be clear + (<varname>wpid</varname> in the following). It must be clear that <varname>upid</varname> and <varname>wpid</varname> are different and shall not be used instead of the other. </para> <para> <varname>Wpid</varname> and <varname>tid</varname> are - defined (Windows) system wide. They must not be confused + defined (Windows) system wide. They must not be confused with process or thread handles which, as any handle, is an indirection to a system object (in this case process or - thread). A same process can have several different handles - on the same kernel object. The handles can be defined as + thread). A same process can have several different handles + on the same kernel object. The handles can be defined as local (the values is only valid in a process), or system wide (the same handle can be used by any <varname>W-process</varname>). @@ -101,17 +101,17 @@ </listitem> </itemizedlist> <para> - Wine implements most of the Windows' debugging API. The + Wine implements most of the Windows' debugging API. The first part of the debugging APIs (in <filename>KERNEL32.DLL</filename>) allows a W-process, called the debugger, to control the execution of another W-process, - the debuggee. To control means stopping/resuming execution, + the debuggee. To control means stopping/resuming execution, enabling/disabling single stepping, setting breakpoints, - reading/writing debuggee memory... Another part of the + reading/writing debuggee memory... Another part of the debugging APIs resides in <filename>DBGHELP.DLL</filename> (and its ancestor <filename>IMAGEHLP.DLL</filename>) and lets a debugger look into symbols and types from any module (if - the module has been compiled with the proper options). + the module has been compiled with the proper options). </para> <para> <command>winedbg</command> is a Winelib application making @@ -133,7 +133,7 @@ <para> Any application (either a Windows' native executable, or a Winelib application) can be run through - <command>winedbg</command>. Command line options and tricks + <command>winedbg</command>. Command line options and tricks are the same as for wine: </para> <screen> @@ -148,13 +148,13 @@ winedbg hl.exe -windowed <para> <command>winedbg</command> can also be launched without any command line argument: <command>winedbg</command> is started - without any attached process. You can get a list of running + without any attached process. You can get a list of running <varname>W-processes</varname> (and their <varname>wpid</varname>'s) using the <command>info process</command> command, and then, with the <command>attach</command> command, pick up the <varname>wpid</varname> of the <varname>W-process</varname> - you want to debug. This is a neat feature as it allows you + you want to debug. This is a neat feature as it allows you to debug an already started application. </para> </sect2> @@ -164,23 +164,23 @@ winedbg hl.exe -windowed <para> When something goes wrong, Windows tracks this as an - exception. Exceptions exist for segmentation violation, + exception. Exceptions exist for segmentation violation, stack overflow, division by zero, etc. </para> <para> When an exception occurs, Wine checks if the - <varname>W-process</varname> is debugged. If so, the + <varname>W-process</varname> is debugged. If so, the exception event is sent to the debugger, which takes care of - it: end of the story. This mechanism is part of the standard + it: end of the story. This mechanism is part of the standard Windows' debugging API. </para> <para> If the <varname>W-process</varname> is not debugged, Wine - tries to launch a debugger. This debugger (normally + tries to launch a debugger. This debugger (normally <command>winedbg</command>, see III Configuration for more details), at startup, attaches to the <varname>W-process</varname> which generated the exception - event. In this case, you are able to look at the causes of + event. In this case, you are able to look at the causes of the exception, and either fix the causes (and continue further the execution) or dig deeper to understand what went wrong. @@ -215,9 +215,9 @@ winedbg hl.exe -windowed <listitem> <para> the debugger couldn't correct the cause of the - first chance exception. Wine will now try to walk + first chance exception. Wine will now try to walk the list of exception handlers to see if one of them - can handle the exception. If no exception handler is + can handle the exception. If no exception handler is found, the exception is sent once again to the debugger to indicate the failure of the exception handling. @@ -230,7 +230,7 @@ winedbg hl.exe -windowed since some of Wine's code uses exceptions and <function>try/catch</function> blocks to provide some functionality, <command>winedbg</command> can be entered - in such cases with segv exceptions. This happens, for + in such cases with segv exceptions. This happens, for example, with <function>IsBadReadPtr</function> function. In that case, the <command>pass</command> command shall be used, to let the handling of the exception to be done by @@ -245,7 +245,7 @@ winedbg hl.exe -windowed <para> You can stop the debugger while it's running by hitting - Ctrl-C in its window. This will stop the debugged process, + Ctrl-C in its window. This will stop the debugged process, and let you manipulate the current context. </para> </sect2> @@ -266,7 +266,7 @@ winedbg hl.exe -windowed <title>Using the Wine Debugger</title> <para> - This section describes where to start debugging Wine. If at any + This section describes where to start debugging Wine. If at any point you get stuck and want to ask for help, please read the <emphasis>How to Report A Bug</emphasis> section of the <emphasis>Wine Users Guide</emphasis> for information on how to write @@ -307,7 +307,7 @@ winedbg hl.exe -windowed |0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c): movw %es:0x38(%bx),%dx </screen> <para> - Steps to debug a crash. You may stop at any step, but please + Steps to debug a crash. You may stop at any step, but please report the bug and provide as much of the information gathered to the bug report as feasible. </para> @@ -315,10 +315,10 @@ winedbg hl.exe -windowed <orderedlist> <listitem> <para> - Get the reason for the crash. This is usually an access to + Get the reason for the crash. This is usually an access to an invalid selector, an access to an out of range address in a valid selector, popping a segment register from the - stack or the like. When reporting a crash, report this + stack or the like. When reporting a crash, report this <emphasis>whole</emphasis> crashdump even if it doesn't make sense to you. </para> @@ -330,10 +330,10 @@ winedbg hl.exe -windowed </listitem> <listitem> <para> - Determine the cause of the crash. Since this is usually + Determine the cause of the crash. Since this is usually a primary/secondary reaction to a failed or misbehaving - Wine function, rerun Wine with the<parameter>WINEDEBUG=+relay</parameter> - environment variable set. This will + Wine function, rerun Wine with the <parameter>WINEDEBUG=+relay</parameter> + environment variable set. This will generate quite a lot of output, but usually the reason is located in the last call(s). Those lines usually look like this: @@ -345,9 +345,9 @@ winedbg hl.exe -windowed | | | | |Return address | | | |textual parameter | | | - | | |Argument(s). This one is a win16 segmented pointer. + | | |Argument(s). This one is a win16 segmented pointer. | |Function called. - |The module, the function is called in. In this case it is KERNEL. + |The module, the function is called in. In this case it is KERNEL. |Ret KERNEL.90: LSTRLEN() retval=0x0004 ret=01e7:2ce7 ds=0227 ^^^^^^ @@ -356,19 +356,19 @@ winedbg hl.exe -windowed </listitem> <listitem> <para> - If you have found a misbehaving function, try to find out - why it misbehaves. Find the function in the source code. - Try to make sense of the arguments passed. Usually there is + If you have found a misbehaving Wine function, try to find out + why it misbehaves. Find the function in the source code. + Try to make sense of the arguments passed. Usually there is a <function>WINE_DEFAULT_DEBUG_CHANNEL(<channel>);</function> - at the beginning of the file. Rerun wine with the + at the beginning of the source file. Rerun wine with the <parameter>WINEDEBUG=+xyz,+relay</parameter> environment variable set. </para> <para> Occasionally there are additional debug channels defined at the - beginning of the file in the form. + beginning of the source file in the form <function>WINE_DECLARE_DEBUG_CHANNEL(<channel>);</function> If so the offending function may also uses one of these alternate - channels. Look through the the function for + channels. Look through the the function for <function>TRACE_(<channel>)(" ... /n");</function> and add any additional channels to the commandline. </para> @@ -385,37 +385,41 @@ winedbg hl.exe -windowed If this information isn't clear enough or if you want to know more about what's happening in the function itself, try running wine with <parameter>WINEDEBUG=+all</parameter>, - which dumps ALL included debug - information in wine. + which dumps ALL included debug information in wine. + It is often necessary to limit the debug output produced. + That can be done by piping the output through <command>grep</command>, + or alternatively with the registry value RelayExclude located + under + <programlisting>HKCU\\Software\\Wine\\Debug</programlisting>. </para> </listitem> <listitem> <para> If even that isn't enough, add more debug output for yourself - into the functions you find relevant. See The section on Debug - Logging in this guide for more information. You might + into the functions you find relevant. See The section on Debug + Logging in this guide for more information. You might also try to run the program in <command>gdb</command> - instead of using the Wine debugger. If you do that, use + instead of using the Wine debugger. If you do that, use <parameter>handle SIGSEGV nostop noprint</parameter> to disable the handling of seg faults inside - <command>gdb</command> (needed for Win16). + <command>gdb</command> (needed for Win16). </para> </listitem> <listitem> <para> - You can also set a breakpoint for that function. Start wine - useing <command>winedbg</command> instead of - <command>wine</command>. Once the debugger is is running enter + You can also set a breakpoint for that function. Start wine + using <command>winedbg</command> instead of + <command>wine</command>. Once the debugger is is running enter <command>break</command> <parameter>KERNEL_LSTRLEN</parameter> (replace by function you want to debug, CASE IS RELEVANT) to set a breakpoint. Then use <command>continue</command> to start normal - program-execution. Wine will stop if it reaches the - breakpoint. If the program isn't yet at the crashing call + program-execution. Wine will stop if it reaches the + breakpoint. If the program isn't yet at the crashing call of that function, use <command>continue</command> again - until you are about to enter that function. You may now + until you are about to enter that function. You may now proceed with single-stepping the function until you reach - the point of crash. Use the other debugger commands to + the point of crash. Use the other debugger commands to print registers and the like. </para> </listitem> @@ -427,11 +431,11 @@ winedbg hl.exe -windowed <para> Start the program with <command>winedbg</command> instead of - <command>wine</command>. When the program locks up switch to the + <command>wine</command>. When the program locks up switch to the winedbg's terminal and press - <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>. this + <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>. This will stop the program and let you debug the program as you would for - a crash. + a crash. </para> </sect2> @@ -440,8 +444,8 @@ winedbg hl.exe -windowed <para> Sometimes programs are reporting failure using more or - less nondescript messageboxes. We can debug this using the - same method as Crashes, but there is one problem... For + less nondescript messageboxes. We can debug this using the + same method as Crashes, but there is one problem... For setting up a message box the program also calls Wine producing huge chunks of debug code. </para> @@ -450,9 +454,9 @@ winedbg hl.exe -windowed the Messagebox you can start winedbg and set a breakpoint at <function>MessageBoxA</function> (called by win16 and win32 programs) and proceed with - <command>continue</command>. With <parameter>WINEDEBUG=+all</parameter> + <command>continue</command>. With <parameter>WINEDEBUG=+all</parameter> Wine will now stop directly before setting - up the Messagebox. Proceed as explained above. + up the Messagebox. Proceed as explained above. </para> <para> You can also run wine using <command>WINEDEBUG=+relay wine @@ -471,25 +475,45 @@ winedbg hl.exe -windowed <para> The best, freely available, disassembler for Win16 programs is <application>Windows Codeback</application>, archive name - <filename>wcbxxx.zip</> (e.g. <filename>wcb105a.zip</>), which - usually can be found in the <filename>Cica-Mirror</filename> - subdirectory on the Wine ftp sites. (See <filename>ANNOUNCE</>). + <filename>wcbxxx.zip</> (e.g. <filename>wcb105a.zip</>). </para> <para> Disassembling win32 programs is possible using - <application>Windows Disassembler 32</>. Look for - a file called <filename>w32dsm87.zip</> (or similar) - on <ulink url="http://www.winsite.com/">http://www.winsite.com</> - and mirrors. The shareware version does not allow saving of - disassembly listings. You can also use the newer (and in the - full version better) <application>Interactive - Disassembler</application> (IDA) from the ftp sites mentioned - at the end of the document. Understanding disassembled code is - mostly a question of exercise. + eg. <application>GoVest</> by Ansgar Trimborn. It can be found + <ulink url="http://www.geocities.com/GoVest/">here</>. </para> <para> + Another popular disassembler is + <application>Windows Disassembler 32</> from URSoft. + Look for a file called <filename>w32dsm87.zip</> (or similar) on + <ulink url="http://www.winsite.com/">winsite.com</> or + <ulink url="http://www.softpedia.com/">softpedia.com</>. + </para> + <para> + You can also use the newer (and in the full version better) + <application>Interactive Disassembler</> (IDA) from + DataRescue. The version of IDA that has been most actively used by + Wine project enthusiasts is named <filename>ida35bx.zip</filename>, + although that version now seems impossible to locate. Take a look + in the 'useful programs' section later on for links to working + versions of IDA. + </para> + <para> + Also of considerable fame amongst disassemblers is + <application>SoftIce</> from NuMega. That software has since been + acquired by CompuWare (http://www.compuware.com/) and made part of + their Windows driver development suite. Newer versions of SoftIce + needs to run as a Windows Service and therefore won't currently + work under Wine. + </para> + <para> + If nothing works for you, try one of the disassemblers found in + <ulink url="http://directory.google.com/Top/Computers/Programming/Disassemblers/DOS_and…">Google's directory</>. + </para> + <para> + Understanding disassembled code is mostly a question of exercise. Most code out there uses standard C function entries (for it - is usually written in C). Win16 function entries usually + is usually written in C). Win16 function entries usually look like that: </para> <programlisting> @@ -500,11 +524,11 @@ retf XXXX <--------- XXXX is number </programlisting> <para> This is a <function>FAR</function> function with no local - storage. The arguments usually start at - <literal>[bp+6]</literal> with increasing offsets. Note, that + storage. The arguments usually start at + <literal>[bp+6]</literal> with increasing offsets. Note, that <literal>[bp+6]</literal> belongs to the <emphasis>rightmost</emphasis> argument, for exported win16 - functions use the PASCAL calling convention. So, if we use + functions use the PASCAL calling convention. So, if we use <function>strcmp(a,b)</function> with <parameter>a</parameter> and <parameter>b</parameter> both 32 bit variables <parameter>b</parameter> would be at <literal>[bp+6]</literal> @@ -522,7 +546,7 @@ retf XXXX <para> This does mostly the same as above, but also adds <literal>0x86</literal> bytes of stackstorage, which is - accessed using <literal>[bp-xx]</literal>. Before calling a + accessed using <literal>[bp-xx]</literal>. Before calling a function, arguments are pushed on the stack using something like this: </para> @@ -631,7 +655,7 @@ Wine-dbg> </screen> <para> The code seems to find a writeable harddisk and tries to create - a file there. To work around this bug, you can define + a file there. To work around this bug, you can define <medialabel>C:</medialabel> as a networkdrive, which is ignored by the code above. </para> @@ -649,7 +673,7 @@ Wine-dbg> <para> If you have a program crashing at such an early loader phase that you can't use the Wine debugger normally, but Wine already executes the program's - start code, then you may use a special trick. You should do a + start code, then you may use a special trick. You should do a <programlisting> WINEDEBUG=+relay wine program </programlisting> @@ -660,12 +684,12 @@ winedbg winfile.exe </programlisting> </para> <para> - This way, you get into <command>winedbg</command>. Now you + This way, you get into <command>winedbg</command>. Now you can set a breakpoint on any function the program calls in the start function and just type <userinput>c</userinput> to bypass the eventual calls of Winfile to this function until you are finally at the place where this function gets - called by the crashing start function. Now you can proceed + called by the crashing start function. Now you can proceed with your debugging as usual. </para> </listitem> @@ -679,7 +703,7 @@ winedbg winfile.exe WINEDEBUG=+relay wine <program name> &>relmsg </programlisting> Then do a <command>more relmsg</command> and search for the - last occurrence of a call to the string "MESSAGEBOX". This is a line like + last occurrence of a call to the string "MESSAGEBOX". This is a line like <programlisting> Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff </programlisting> @@ -718,7 +742,7 @@ Call USER.1: MESSAGEBOX(0x0000,0x01ff124 <para> As the segment value of the address is only <literal>4</literal>, I think that that is only an internal - program value. But the offset address reveals something + program value. But the offset address reveals something quite interesting: Offset <literal>1056</literal> is <emphasis>very</emphasis> close to the return address of <function>FREELIBRARY()</function>: @@ -729,15 +753,15 @@ Call KERNEL.96: FREELIBRARY(0x031f) ret= </para> <para> Provided that segment <literal>0x0004</literal> is indeed segment - <literal>0x1cf</literal>, we now we can use IDA (available at - <ulink url="http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip"> - http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip</ulink>) to - disassemble the part that caused the error. We just have to find the address of - the call to <function>FreeLibrary()</function>. Some lines before that the - runtime error occurred. But be careful! In some cases you don't have to - disassemble the main program, but instead some DLL called by it in order to find - the correct place where the runtime error occurred. That can be determined by - finding the origin of the segment value (in this case <literal>0x1cf</literal>). + <literal>0x1cf</literal>, we now we can use IDA to disassemble + the part that caused the error. We just have to find the + address of the call to <function>FreeLibrary()</function>. Some + lines before that the runtime error occurred. But be careful! + In some cases you don't have to disassemble the main program, + but instead some DLL called by it in order to find the correct + place where the runtime error occurred. That can be determined + by finding the origin of the segment value (in this case + <literal>0x1cf</literal>). </para> </listitem> <listitem> @@ -761,15 +785,39 @@ Call KERNEL.96: FREELIBRARY(0x031f) ret= <variablelist> <varlistentry> <term> + <application>GoVest</application>: + <filename>govest.zip</filename> is available from + <ulink url="http://www.geocities.com/GoVest/">http://www.geocities.com/GoVest/</>. + </term> + <listitem> + <para> + The win32 disassembler that currently works + the best with Wine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> <application>IDA</application>: - <filename> - <ulink url="http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip"> - http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip</ulink> - </filename> + <filename>ida35bx.zip</filename> is near impossible to + locate, but you might try a trial version of the new IDA Pro + from + <ulink url="http://www.datarescue.com/">http://www.datarescue.com</ulink> + or try locating the free version of IDA Pro 4.3 by + <ulink url="http://www.google.com/search?q=%22IDA+Pro+freeware%22+4.3">Googling</>. + The newer versions mentioned above currently has problems + installing under Wine. In the mean time, you can use the + free version of IDA Pro 3.85b, which you can also find by + <ulink url="http://www.google.com/search?q=IDA+Pro+freeware+3.85b">Googling</>. + Version 3.85b does not have a GUI. It does have a textual + interface, which currently has problems launching under + Wine. To get it to launch correctly, start it with + <application>winedbg</> instead of <application>wine</>. + Remember to 'c'ontinue the program after starting it. </term> <listitem> <para> - <emphasis>Very</emphasis> good DOS disassembler ! It's badly needed + <emphasis>Very</emphasis> good DOS disassembler! It's badly needed for debugging Wine sometimes. </para> </listitem> @@ -784,7 +832,7 @@ Call KERNEL.96: FREELIBRARY(0x031f) ret= </term> <listitem> <para> - Traces DOS calls (Int 21h, DPMI, ...). Use it with + Traces DOS calls (Int 21h, DPMI, ...). Use it with Windows to correct file management problems etc. </para> </listitem> @@ -827,11 +875,11 @@ Call KERNEL.96: FREELIBRARY(0x031f) ret= After starting your program with </para> <screen> -wine -debug myprog.exe +winedbg myprog.exe </screen> <para> the program loads and you get a prompt at the program - starting point. Then you can set breakpoints: + starting point. Then you can set breakpoints: </para> <screen> b RoutineName (by routine name) OR @@ -839,7 +887,7 @@ wine -debug myprog.exe </screen> <para> Then you hit <command>c</command> (continue) to run the - program. It stops at the breakpoint. You can type + program. It stops at the breakpoint. You can type </para> <screen> step (to step one line) OR @@ -898,7 +946,7 @@ wine -debug myprog.exe has the lowest 3 bits set. Some sample selectors are 0x1f7, 0x16f, 0x8f. If these bits are set except for the lowest bit, as e.g. with 0x1f6,xi then it might be a - handle to global memory. Just set the lowest bit to get + handle to global memory. Just set the lowest bit to get the selector in these cases. A selector kind of "points" to a certain linear (see above) base address. It has more or less three important attributes: segment @@ -951,17 +999,17 @@ wine -debug myprog.exe <title>Configuration</title> <sect2> - <title>Registry configuration</title> + <title>Windows Debugging configuration</title> <para> The Windows' debugging API uses a registry entry to know which debugger to invoke when an unhandled exception occurs (see <link endterm="dbg-exception-title" - linkend="dbg-on-exception"></link> for some details). Two + linkend="dbg-on-exception"></link> for some details). Two values in key </para> <programlisting> -"MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug" +[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug] </programlisting> <para> Determine the behavior: @@ -971,16 +1019,16 @@ wine -debug myprog.exe <term>Debugger</term> <listitem> <para> - this is the command line used to launch the debugger + This is the command line used to launch the debugger (it uses two <function>printf</function> formats (<literal>%ld</literal>) to pass context dependent - information to the debugger). You should put here a + information to the debugger). You should put here a complete path to your debugger (<command>winedbg</command> can of course be used, but - any other Windows' debugging API aware debugger will - do). - The path to the debugger you chose to use must be reachable - via a DOS drive in the Wine config file ! + any other Windows' debugging API aware debugger will do). + The path to the debugger you choose to use must be reachable + via one of the DOS drives configured under /dosdevices in + your $WINEPREFIX or ~/.wine folder. </para> </listitem> </varlistentry> @@ -990,7 +1038,7 @@ wine -debug myprog.exe <para> if this value is zero, a message box will ask the user if he/she wishes to launch the debugger when an - unhandled exception occurs. Otherwise, the debugger + unhandled exception occurs. Otherwise, the debugger is automatically started. </para> </listitem> @@ -1009,7 +1057,7 @@ wine -debug myprog.exe <note> <title>Note 1</title> <para> - creating this key is mandatory. Not doing so will not + creating this key is mandatory. Not doing so will not fire the debugger when an exception occurs. </para> </note> @@ -1037,8 +1085,8 @@ wine -debug myprog.exe <para> <command>winedbg</command> can be configured through a number - of options. Those options are stored in the registry, on a - per user basis. The key is (in <emphasis>my</emphasis> registry) + of options. Those options are stored in the registry, on a + per user basis. The key is (in <emphasis>my</emphasis> registry) </para> <programlisting> [HKCU\\Software\\Wine\\WineDbg] @@ -1046,8 +1094,8 @@ wine -debug myprog.exe <para> Those options can be read/written while inside <command>winedbg</command>, as part of the debugger - expressions. To refer to one of these options, its name must - be prefixed by a <literal>$</literal> sign. For example, + expressions. To refer to one of these options, its name must + be prefixed by a <literal>$</literal> sign. For example, </para> <programlisting> set $BreakAllThreadsStartup = 1 @@ -1077,7 +1125,7 @@ set $BreakAllThreadsStartup = 1 start-up the debugger stops set to <literal>FALSE</literal> if only at the first thread startup of a given process the debugger - stops. <literal>FALSE</literal> by default. + stops. <literal>FALSE</literal> by default. </para> </listitem> </varlistentry> @@ -1099,7 +1147,7 @@ set $BreakAllThreadsStartup = 1 <command>winedbg</command> attaches to an existing process after an unhandled exception, <command>winedbg</command> shall be entered on the - first attach event. Since the attach event is + first attach event. Since the attach event is meaningless in the context of an exception event (the next event which is the exception event is of course relevant), that option is likely to be @@ -1111,19 +1159,19 @@ set $BreakAllThreadsStartup = 1 <term><varname>BreakOnFirstChance</varname></term> <listitem> <para> - An exception can generate two debug events. The first + An exception can generate two debug events. The first one is passed to the debugger (known as a first - chance) just after the exception. The debugger can + chance) just after the exception. The debugger can then decide either to resume execution (see <command>winedbg</command>'s <command>cont</command> command) or pass the exception up to the exception handler chain in the program (if it exists) (<command>winedbg</command> implements this through - the <command>pass</command> command). If none of the + the <command>pass</command> command). If none of the exception handlers takes care of the exception, the exception event is sent again to the debugger (known - as last chance exception). You cannot pass on a last - exception. When the + as last chance exception). You cannot pass on a last + exception. When the <varname>BreakOnFirstChance</varname> exception is <literal>TRUE</literal>, then winedbg is entered for both first and last chance execptions (to @@ -1138,7 +1186,7 @@ set $BreakAllThreadsStartup = 1 <para> Set to <literal>TRUE</literal> if the debugger, when looking up for a symbol from its name, displays all - the thunks with that name. The default value + the thunks with that name. The default value (<literal>FALSE</literal>) allows not to have to choose between a symbol and all the import thunks from all the DLLs using that symbols. @@ -1147,6 +1195,49 @@ set $BreakAllThreadsStartup = 1 </varlistentry> </variablelist> </sect2> + + <sect2> + <title>Configuring +relay behaviour</title> + <para> + When setting <parameter>WINEDEBUG</> to +relay and debugging, + you might get a lot of output. You can limit the output by + configuring the value RelayExclude in the registry, located + under the key: + </para> + <programlisting> + [HKCU\\Software\\Wine\\Debug] + </programlisting> + <para> + Set the value of RelayExclude to a semicolon-separated list of + calls to exclude. Example: + "RtlEnterCriticalSection;RtlLeaveCriticalSection;kernel32.97;kernel32.98". + </para> + <para> + RelayInclude is an option similar to RelayExclude, except that + functions listed here will be the only ones included in the output. + Also see section 3.4.3.5 for more options. + </para> + <para> + If your application runs too slow with +relay to get meaningful + output and you're stuck with multi-GB relay log files, but + you're not sure what to exclude, here's a trick to get you started. + First, run your application for a minute or so, piping it's output + to a file on disk: + </para> + <programlisting> + WINEDEBUG=+relay wine <appname.exe> &>relay.log + </programlisting> + <para> + Then run this command to see which calls are performed the most: + </para> + <programlisting> + awk -F'(' '{print $1}' < relay.log | awk '{print $2}' | sort | uniq -c | sort + </programlisting> + <para> + Exclude the bottom-most calls with RelayExclude after making + sure that they are irrelevant and run your application again. + </para> + </sect2> </sect1> <sect1 id="dbg-expr"> @@ -1156,11 +1247,11 @@ set $BreakAllThreadsStartup = 1 <para> Expressions in Wine Debugger are mostly written in a C - form. However, there are a few discrepancies: + form. However, there are a few discrepancies: <itemizedlist> <listitem> <para> - Identifiers can take a '!' in their names. This allow + Identifiers can take a '!' in their names. This allow mainly to access symbols from different DLLs like <function>USER32!CreateWindowExA</function>. </para> @@ -1169,7 +1260,7 @@ set $BreakAllThreadsStartup = 1 <para> In cast operation, when specifying a structure or an union, you must use the <type>struct</type> or - <type>union</type> keyword (even if your program uses a typedef). + <type>union</type> keyword (even if your program uses a typedef). </para> </listitem> </itemizedlist> @@ -1177,7 +1268,7 @@ set $BreakAllThreadsStartup = 1 <para> When specifying an identifier by its name, if several symbols with the same name exist, the debugger will prompt - for the symbol you want to use. Pick up the one you want + for the symbol you want to use. Pick up the one you want from its number. </para> <para> @@ -1186,8 +1277,8 @@ set $BreakAllThreadsStartup = 1 </para> <para> <command>winedbg</command> defines its own set of - variables. The configuration variables from above are part - of them. Some others include: + variables. The configuration variables from above are part + of them. Some others include: <variablelist> <varlistentry> <term><varname>$ThreadId</varname></term> @@ -1212,7 +1303,7 @@ set $BreakAllThreadsStartup = 1 <listitem> <para> All CPU registers are also available, using $ as a - prefix. You can use <command>info regs</command> to + prefix. You can use <command>info regs</command> to get a list of avaible CPU registers </para> </listitem> @@ -1250,8 +1341,8 @@ set $BreakAllThreadsStartup = 1 <entry><command>attach N</command></entry> <entry> attach to a W-process (N is its ID, numeric - or hexadecimal (0xN)). IDs can be obtained using - the info process command. Note the info process + or hexadecimal (0xN)). IDs can be obtained using + the info process command. Note the info process command returns hexadecimal values. </entry> </row> @@ -1373,7 +1464,7 @@ set $BreakAllThreadsStartup = 1 <command>cont</command>, <command>step</command>, <command>next</command>, <command>stepi</command>, <command>nexti</command> can be postfixed by a number (N), - meaning that the command must be executed N times. + meaning that the command must be executed N times. </para> </sect2> @@ -1410,8 +1501,8 @@ set $BreakAllThreadsStartup = 1 </entry> <entry> adds condition <expr> to (break|watch)point - N. <expr> will be evaluated each time the - breakpoint is hit. If the result is a zero value, + N. <expr> will be evaluated each time the + breakpoint is hit. If the result is a zero value, the breakpoint isn't triggered </entry> </row> @@ -1478,7 +1569,7 @@ set $BreakAllThreadsStartup = 1 symbol cannot be found (for example, the symbol is contained in a not yet loaded module), winedbg will recall the name of the symbol and will try to set the breakpoint each time a - new module is loaded (until it succeeds). + new module is loaded (until it succeeds). </para> </sect2> @@ -1643,7 +1734,7 @@ set $BreakAllThreadsStartup = 1 <para> You can specify the end target (to change the 10 lines - value) using the ','. For example: + value) using the ','. For example: <table> <title>WineDbg's list command examples</title> <tgroup cols="2" align="left"> @@ -1678,7 +1769,7 @@ set $BreakAllThreadsStartup = 1 </para> <para> <command>winedbg</command> will automatically detect if the - expression you entered contains a local variable. If so, + expression you entered contains a local variable. If so, display will only be shown if the context is still in the same function as the one the debugger was in when the display expression was entered. @@ -1719,7 +1810,7 @@ set $BreakAllThreadsStartup = 1 </entry> <entry> adds a display for expression - <expr>. Printing evaluated <expr> is + <expr>. Printing evaluated <expr> is done using the given format (see <command>print</command> command for more on formats) @@ -2054,11 +2145,11 @@ set $BreakAllThreadsStartup = 1 <title>GDB mode</title> <para> - WineDbg can act as a remote monitor for GDB. This allows to + WineDbg can act as a remote monitor for GDB. This allows to use all the power of GDB, but while debugging wine and/or - any Win32 application. To enable this mode, just add - <parameter>--gdb</parameter> to winedbg command line. You'll - end up on a GDB prompt. You'll have to use the GDB commands + any Win32 application. To enable this mode, just add + <parameter>--gdb</parameter> to winedbg command line. You'll + end up on a GDB prompt. You'll have to use the GDB commands (not WineDbg's). </para> @@ -2076,7 +2167,7 @@ set $BreakAllThreadsStartup = 1 <para> Moreover, it also provides support for the Dwarf II debug format (which became the default format (instead - of stabs) in gcc 3.1). + of stabs) in gcc 3.1). </para> </listitem> </itemizedlist> @@ -2157,7 +2248,7 @@ set $BreakAllThreadsStartup = 1 </para> </listitem> </orderedlist> - The program should now be loaded and up and running. If + The program should now be loaded and up and running. If you want, you can also add in 1/ after the name of the exec all the needed parameters </para> @@ -2193,7 +2284,7 @@ kdbg -r localhost:32878 wine </para> </listitem> </orderedlist> - The program should now be loaded and up and running. If + The program should now be loaded and up and running. If you want, you can also add in 1/ after the name of the exec all the needed parameters </para> @@ -2229,7 +2320,7 @@ kdbg -r localhost:32878 wine <listitem> <para> Wine is running on the pthread model (it won't work - in the kthread one). See the Wine architecture + in the kthread one). See the Wine architecture documentation for further details. </para> </listitem> @@ -2261,7 +2352,7 @@ $ gdb wine </screen> <para> Switch to another console and enter <command>ps ax | grep - wine</command> to find all wine processes. Inside + wine</command> to find all wine processes. Inside <command>gdb</command>, repeat for all Wine processes: </para> <screen> @@ -2313,9 +2404,9 @@ $ gdb wine <para> You can use any Windows' debugging API compliant debugger - with Wine. Some reports have been made of success with + with Wine. Some reports have been made of success with VisualStudio debugger (in remote mode, only the hub runs - in Wine). GoVest fully runs in Wine. + in Wine). GoVest fully runs in Wine. </para> </sect2>

1 0

appdb/. maintainersubmit.php
by WineHQ Oct. 4, 2005

Oct. 4, 2005

ChangeSet ID: 20560 CVSROOT: /opt/cvs-commit Module name: appdb Changes by: wineowner(a)winehq.org 2005/10/03 20:22:16 Modified files: . : maintainersubmit.php Log message: Chris Morgan <cmorgan(a)alum.wpi.edu> User::isMaintainer(iVersionId) was being passed (iAppId, iVersionId) instead, oops Patch: http://cvs.winehq.org/patch.py?id=20560 Old revision New revision Changes Path 1.18 1.19 +1 -1 appdb/maintainersubmit.php

1 0

appdb/. appsubmit.php
by WineHQ Oct. 3, 2005

Oct. 3, 2005

ChangeSet ID: 20559 CVSROOT: /opt/cvs-commit Module name: appdb Changes by: wineowner(a)winehq.org 2005/10/03 18:16:41 Modified files: . : appsubmit.php Log message: Chris Morgan <cmorgan(a)alum.wpi.edu> Fix Xinha control on submit new version page. We should only create a 'editor2' control for a new version as only the 'editor2' textarea is created for new versions. Patch: http://cvs.winehq.org/patch.py?id=20559 Old revision New revision Changes Path 1.29 1.30 +4 -2 appdb/appsubmit.php

1 0

wine/dlls/winspool info.c
by Alexandre Julliard Oct. 3, 2005

Oct. 3, 2005

ChangeSet ID: 20558 CVSROOT: /opt/cvs-commit Module name: wine Changes by: julliard(a)winehq.org 2005/10/03 13:48:56 Modified files: dlls/winspool : info.c Log message: Maxime Bellengé <maxime.bellenge(a)laposte.net> Fix a cut&paste mistake. Patch: http://cvs.winehq.org/patch.py?id=20558 Old revision New revision Changes Path 1.128 1.129 +1 -1 wine/dlls/winspool/info.c

1 0

wine/dlls/user win.c
by Alexandre Julliard Oct. 3, 2005

Oct. 3, 2005

ChangeSet ID: 20557 CVSROOT: /opt/cvs-commit Module name: wine Changes by: julliard(a)winehq.org 2005/10/03 13:48:36 Modified files: dlls/user : win.c Log message: Vitaliy Margolen <wine-patch(a)kievinfo.com> Use GetSystemMetrics instead of hardcoding drag width & height. Patch: http://cvs.winehq.org/patch.py?id=20557 Old revision New revision Changes Path 1.19 1.20 +2 -2 wine/dlls/user/win.c

1 0

wine/dlls/ntdll server.c
by Alexandre Julliard Oct. 3, 2005

Oct. 3, 2005

ChangeSet ID: 20556 CVSROOT: /opt/cvs-commit Module name: wine Changes by: julliard(a)winehq.org 2005/10/03 13:46:57 Modified files: dlls/ntdll : server.c Log message: Fixed a bug where we could set the wrong handle in the fd cache when encountering the race condition in wine_server_handle_to_fd. Patch: http://cvs.winehq.org/patch.py?id=20556 Old revision New revision Changes Path 1.35 1.36 +1 -1 wine/dlls/ntdll/server.c

1 0

wine/dlls/comctl32 tab.c
by Alexandre Julliard Oct. 3, 2005

Oct. 3, 2005

ChangeSet ID: 20555 CVSROOT: /opt/cvs-commit Module name: wine Changes by: julliard(a)winehq.org 2005/10/03 13:46:07 Modified files: dlls/comctl32 : tab.c Log message: Vitaliy Margolen <wine-patch(a)kievinfo.com> Don't arrange tabs if there is only one line. Patch: http://cvs.winehq.org/patch.py?id=20555 Old revision New revision Changes Path 1.118 1.119 +4 -1 wine/dlls/comctl32/tab.c

1 0

wine/programs/winetest Makefile.in
by Alexandre Julliard Oct. 3, 2005

Oct. 3, 2005

ChangeSet ID: 20554 CVSROOT: /opt/cvs-commit Module name: wine Changes by: julliard(a)winehq.org 2005/10/03 13:45:45 Modified files: programs/winetest: Makefile.in Log message: Paul Millar <paul(a)astro.gla.ac.uk> Fix cross-compilation of winetest by update the makefile to use OBJS instead of the now absent ALL_OBJS. Patch: http://cvs.winehq.org/patch.py?id=20554 Old revision New revision Changes Path 1.41 1.42 +4 -4 wine/programs/winetest/Makefile.in

1 0

wine/dlls/riched20 reader.c editor.c
by Alexandre Julliard Oct. 3, 2005

Oct. 3, 2005

ChangeSet ID: 20553 CVSROOT: /opt/cvs-commit Module name: wine Changes by: julliard(a)winehq.org 2005/10/03 13:45:39 Modified files: dlls/riched20 : reader.c editor.c Log message: Krzysztof Foltman <wdev(a)foltman.com> - Remove another potential sources of infinite loops caused by EOF in the middle of the font and color tables. - Closing brace on text level is treated as EOF (effectively protecting the control from trash after the end of RTF). - Removed misleading comment about incomplete buffers (I was definitely wrong). Patch: http://cvs.winehq.org/patch.py?id=20553 Old revision New revision Changes Path 1.18 1.19 +18 -7 wine/dlls/riched20/reader.c 1.58 1.59 +5 -0 wine/dlls/riched20/editor.c

1 0

wine/programs/winecfg No.rc
by Alexandre Julliard Oct. 3, 2005

Oct. 3, 2005

ChangeSet ID: 20552 CVSROOT: /opt/cvs-commit Module name: wine Changes by: julliard(a)winehq.org 2005/10/03 13:45:02 Modified files: programs/winecfg: No.rc Log message: Alexander N. Sørnes <alex(a)thehandofagony.com> Fixed a few missing characters in winecfg. Patch: http://cvs.winehq.org/patch.py?id=20552 Old revision New revision Changes Path 1.1 1.2 +5 -5 wine/programs/winecfg/No.rc

1 0