зеркало из https://github.com/github/msysgit.git
418 строки
14 KiB
HTML
418 строки
14 KiB
HTML
<html>
|
||
<head>
|
||
<title>Dr. Mingw</title>
|
||
</head>
|
||
<body>
|
||
<p>Dr. Mingw is a <i>Just-in-Time (JIT)</i> debugger. When the application throws
|
||
an unhandled exception, Dr. Mingw attaches itself to the application and collects
|
||
information about the exception, using the available debugging information.</p>
|
||
|
||
<h1>Features</h1>
|
||
|
||
<p>Dr. Mingw can read debugging information in <em>Stabs</em> formats — generated
|
||
by the Gnu C/C++ Compiler, and in a PDB file — generated by the Microsoft
|
||
Visual C++ Compiler.</p>
|
||
|
||
<p>Windows NT/2000 platform is supported, as well as Windows 95/98. On older Windows
|
||
versions though, the IMAGEHLP.DLL isn't included or it's a rather old version.
|
||
Dr. Mingw doesn't require it, but relies upon it to resolve symbols in modules
|
||
compiled by the Microsoft tools. See <a href="#imagehlp">The
|
||
IMAGEHLP.DLL Saga</a> for more information. </p>
|
||
|
||
<h1>Download</h1>
|
||
|
||
<p>Dr. Mingw is now part of <a
|
||
href="http://sourceforge.net/project/showfiles.php?group_id=2435&release_id=115457">mingw-utils</a>.</p>
|
||
|
||
<h1>Installation</h1>
|
||
|
||
<p>If you didn't download the self-installing package, to install enter</p>
|
||
|
||
<blockquote>
|
||
<pre><b>drmingw -i</b></pre>
|
||
</blockquote>
|
||
|
||
<p>Dr. Mingw will register itself as the JIT debugger by writting into the
|
||
system registry. On Windows NT/2000 make sure you have Administrator
|
||
rights. See <a href="#jit">Enabling Just-in-Time (JIT) Debugging</a> for
|
||
more information.</p>
|
||
|
||
<p>If the installation is sucessful, the following message box should appear:</p>
|
||
|
||
<p align="center"><img src="install.gif" alt="installation dialog"/></p>
|
||
|
||
<p>To enable other options they must be set them allong with the <b>-i</b>
|
||
option. For example,</p>
|
||
|
||
<blockquote>
|
||
<pre><b>drmingw -i -v </b></pre>
|
||
</blockquote>
|
||
|
||
<p>If you still have trouble installing, edit the included<b>
|
||
drmingw.reg</b> file to reflect the <b>drmingw.exe</b> executable path and
|
||
load it on the system registry.</p>
|
||
|
||
<h1>Usage</h1>
|
||
|
||
<p>You can test Dr. Mingw by running the sample<b> test.exe</b>. Depending
|
||
of your Windows version, you'll see a familiar dialog:</p>
|
||
|
||
<p align="center"><img src="exception-nt.gif" alt="Windows general protection fault dialog"/></p>
|
||
|
||
<p>If you request to debug the program, Dr. Mingw will attach to the
|
||
faulting application, collect information about the exception, and display
|
||
the dialog</p>
|
||
|
||
<p align="center"><img src="sample.gif" alt="sample report"/></p>
|
||
|
||
<p>To resolve the addresses it's necessary to compile the application with
|
||
debugging information. In case of address is in a DLL with no debugging
|
||
information, it will resolve to the precedent exported symbol.</p>
|
||
|
||
<h1>Command Line Options</h1>
|
||
|
||
<p>The Dr. Mingw command line uses the following syntax:</p>
|
||
|
||
<pre>
|
||
<b>drmingw </b>[<b>-h | --help</b>] [<b>-V | --version</b>] [<b>-i | --install</b>] [<b>-a | --auto</b>] [<b>-u | --uninstall</b>]
|
||
[<b>-p</b> <i>pid</i> | <b>--process-id=</b><i>pid</i>] [<b>-e</b> <i>event</i> | <b>--event=</b><i>event</i>]
|
||
[<b>-v | --verbose</b>]
|
||
</pre>
|
||
|
||
<p>The following table describes the Dr. Mingw command-line options. All
|
||
comand-line options are case-sensitive. </p>
|
||
|
||
<table width="78%" summary="command-line options">
|
||
<tr>
|
||
<th align=left width=10%>Option</th>
|
||
<th align=left width=25%> </th>
|
||
<th align=left width=65%>Action</th>
|
||
</tr>
|
||
<tr>
|
||
<td width=10%>
|
||
<pre><b>-h</b></pre>
|
||
</td>
|
||
<td width=25%>
|
||
<pre><b>--help</b></pre>
|
||
</td>
|
||
<td width=65%>Print help and exit </td>
|
||
</tr>
|
||
<tr>
|
||
<td width=10%>
|
||
<pre><b>-V</b></pre>
|
||
</td>
|
||
<td width=25%>
|
||
<pre><b>--version</b></pre>
|
||
</td>
|
||
<td width=65%>Print version and exit</td>
|
||
</tr>
|
||
<tr>
|
||
<td width=10%>
|
||
<pre><b>-i</b></pre>
|
||
</td>
|
||
<td width=25%>
|
||
<pre><b>--install</b></pre>
|
||
</td>
|
||
<td width=65%>Install as the default JIT debugger</td>
|
||
</tr>
|
||
<tr>
|
||
<td width=10%>
|
||
<pre><b>-a</b></pre>
|
||
</td>
|
||
<td width=25%>
|
||
<pre><b>--auto</b></pre>
|
||
</td>
|
||
<td width=65%>Automatically start (used with <b>-i</b> | <b>--install</b>)</td>
|
||
</tr>
|
||
<tr>
|
||
<td width=10%>
|
||
<pre><b>-u</b></pre>
|
||
</td>
|
||
<td width=25%>
|
||
<pre><b>--uninstall</b></pre>
|
||
</td>
|
||
<td width=65%>Uninstall</td>
|
||
</tr>
|
||
<tr>
|
||
<td width=10%>
|
||
<pre><b>-p</b> <i>pid</i></pre>
|
||
</td>
|
||
<td width=25%>
|
||
<pre><b>--process-id=</b><i>pid</i></pre>
|
||
</td>
|
||
<td width=65%>Attach to the process with the given identifier</td>
|
||
</tr>
|
||
<tr>
|
||
<td width=10%>
|
||
<pre><b>-e</b> <i>event</i></pre>
|
||
</td>
|
||
<td width=25%><pre><b>--event=</b><i>event</i></pre></td>
|
||
<td width=65%>Signal an event after process is attached</td>
|
||
</tr>
|
||
<tr>
|
||
<td width=10%>
|
||
<pre><b>-v</b></pre>
|
||
</td>
|
||
<td width=25%>
|
||
<pre><b>--verbose</b></pre>
|
||
</td>
|
||
<td width=65%>Verbose output</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<h1><a name="exchndl"></a>The EXCHNDL.DLL</h1>
|
||
|
||
<h2>Introduction</h2>
|
||
|
||
<p>Although internally Dr. Mingw behaves much like a debugger, from the
|
||
outside it is like a standalone exception handler. But for its own
|
||
debugging purposes, Dr. Mingw has a internal exception handler that is
|
||
completly seperate from the main code.</p>
|
||
|
||
<p>This exception handler resides in <b>exchndl.c</b>. When
|
||
<b>drmingw.exe</b> is loaded, the code in <b>exchndl.c</b> is automatically
|
||
executed (by the gcc static constructor/destructor mechanism) and registers
|
||
itself as a exception handler.</p>
|
||
|
||
<p>This exception handler is much lighter than Dr. Mingw debugging system
|
||
because it doesn't have to deal with interprocess communication. The
|
||
exception handling routine runs in the same process context of the faulting
|
||
application (<b>drmingw</b>, in this case).</p>
|
||
|
||
<h2>Using ExcHndl for you own purposes</h2>
|
||
|
||
<p>If you incorporate ExcHndl in you own programs, especially those that
|
||
you release to others, you can have almost the same exception information
|
||
that you would get with Dr. Mingw, but with no need of the end user to have
|
||
Dr. Mingw installed.</p>
|
||
|
||
<p>You can use ExcHndl in two ways:</p>
|
||
|
||
<ul>
|
||
<li>linking <b>exchndl.o</b> and <b>libbfd.a</b> with your program objects</li>
|
||
|
||
<li>linking <b>exchndl.o</b> and <b>libfd.a</b> in the
|
||
<b>EXCHNDL.DLL</b> and dinamically loading it at run-time. This can be
|
||
done by linking just <b>exchndl2.o</b> or explicitly calling
|
||
<i>LoadLibrary("exchndl.dll")</i></li>
|
||
</ul>
|
||
|
||
<p>The latter method is preferred because you have smaller executables and
|
||
don't need to link the BFD library in all builds. The application wont fail
|
||
if the <b>EXCHNDL.DLL</b> is missing.</p>
|
||
|
||
<h2>Example</h2>
|
||
|
||
<p>The sample<b> test.exe</b> application uses the second method above.
|
||
Copy <b>EXCHNDL.DLL</b> to executable directory. When you run it, even
|
||
before general protection fault dialog box appears, it's written to the
|
||
<b>test.RPT</b> file a report of the fault.</p>
|
||
|
||
<p>Here is how <b>test.RPT</b> should look like:</p>
|
||
|
||
<pre>
|
||
-------------------
|
||
|
||
Error occured on Sunday, May 7, 2000 at 20:22:03.
|
||
|
||
C:\home\jrfonseca\drmingw\src\test.exe caused an Access Violation in module C:\WINDOWS\system32\msvcrt.dll Writing to location 00000008.
|
||
|
||
Registers:
|
||
eax=00003039 ebx=00000064 ecx=00000008 edx=0244fec0 esi=00401211 edi=0244fec0
|
||
eip=78027470 esp=0244fcd8 ebp=0244fea8 iopl=0 nv up ei pl nz na pe nc
|
||
cs=001b ss=0023 ds=0023 es=0023 fs=0038 gs=0000 efl=00010202
|
||
|
||
Call stack:
|
||
78027470 C:\WINDOWS\system32\msvcrt.dll:78027470 wscanf
|
||
7802544B C:\WINDOWS\system32\msvcrt.dll:7802544B sscanf
|
||
00401241 C:\home\jrfonseca\drmingw\src\test.exe:00401241 YetAnotherFunction //C/home/jrfonseca/drmingw/src/test.cxx:14
|
||
00401272 C:\home\jrfonseca\drmingw\src\test.exe:00401272 MyWonderfulFunction //C/home/jrfonseca/drmingw/src/test.cxx:19
|
||
004012A9 C:\home\jrfonseca\drmingw\src\test.exe:004012A9 main //C/home/jrfonseca/drmingw/src/test.cxx:24
|
||
004011C1 C:\home\jrfonseca\drmingw\src\test.exe:004011C1
|
||
004011EB C:\home\jrfonseca\drmingw\src\test.exe:004011EB
|
||
77E87903 C:\WINDOWS\system32\KERNEL32.dll:77E87903 SetUnhandledExceptionFilter
|
||
</pre>
|
||
|
||
<h1>Appendix</h1>
|
||
|
||
<h2><a name="jit"></a>Enabling Just-in-Time (JIT) Debugging</h2>
|
||
|
||
<p><em>[Taken from Using Microsoft Debuggers of the April 2000 Platform SDK.]</em></p>
|
||
|
||
<p>There are a variety of application errors which will cause Windows
|
||
NT/Windows 2000 a to terminate the application. The most common kinds of
|
||
errors are deadlocks and access violations. From the operating systems
|
||
point of view, these are all simply unhandled exceptions.</p>
|
||
|
||
<p>When an application error occurs, Windows searches for an exception
|
||
handler. If it does not find an exception handler, the system verifies that
|
||
the application is not currently being debugged and considers the exception
|
||
to be unhandled. At this point, there are three possible responses:</p>
|
||
|
||
<ul>
|
||
<li>Windows can end the process immediately.</li>
|
||
|
||
<li>Windows can freeze the process and start a user-mode debugger. This
|
||
debugger can then be used to examine the application.</li>
|
||
|
||
<li>Windows can run a debugging tool which will create a memory dump
|
||
file of the application's memory space, and then end the process.</li>
|
||
</ul>
|
||
|
||
<p>The debugging tool which is used to debug the application or write the
|
||
dump file is called <I>Just-in-Time (JIT) Debugger</I>, or the
|
||
<i>post-mortem debugger</i>.</p>
|
||
|
||
<p>The default JIT debugger is Dr. Watson. When the application throws
|
||
an unhandled exception, Dr. Watson attaches itself to the application and
|
||
generates a crash dump file. After it creates the crash dump file, Dr.
|
||
Watson closes the application and exits.</p>
|
||
|
||
<p>Any user-mode debugging tool can be selected as the JIT debugger:</p>
|
||
|
||
<ul>
|
||
<li>To change the JIT debugger to WinDbg, run <b>windbg -I</b>. When
|
||
WinDbg is the JIT debugger, WinDbg will be activated whenever an
|
||
application crashes. See WinDbg Command Line Options for details.</li>
|
||
|
||
<li>To change the JIT debugger to NTSD, you must edit the registry.
|
||
When NTSD is the JIT debugger, NTSD will be activated whenever an
|
||
application crashes.</li>
|
||
|
||
<li>To change the JIT debugger back to Dr. Watson, run <b>drwtsn32
|
||
-i</b>. When Dr. Watson is the JIT debugger, a memory dump file will
|
||
be written to disk if an application crashes. See Dr. Watson Command
|
||
Line Options for details.</li>
|
||
</ul>
|
||
|
||
<p>Only a system administrator can alter the JIT settings.</p>
|
||
|
||
<p>If a JIT debugger has been installed, you can deliberately break into
|
||
the debugger from a user-mode application by calling the <b>DebugBreak</b>
|
||
function.</p>
|
||
|
||
<h3>Editing the Registry</h3>
|
||
|
||
<p>The Just-in-Time debugging settings are stored in the registry, under
|
||
<b>\\HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\AeDebug\</b>.
|
||
The two relevant keys in this directory are <b>Debugger</b> and
|
||
<b>Auto</b>.</p>
|
||
|
||
<p>The <b>Debugger</b> key's value shows the name of the debugger specified
|
||
to analyze application errors. The <b>Auto</b> key is either zero or
|
||
one.</p>
|
||
|
||
<p>When an unhandled application error occurs, Windows checks to see if the
|
||
<b>Debugger</b> and <b>Auto</b> keys exist.</p>
|
||
|
||
<p>If the <b>Auto</b> key equals zero and the <b>Debugger</b> value
|
||
contains the name of a valid debugger (such as WinDbg or NTSD), the message
|
||
box will have two buttons: <b>OK</b> and <b>Cancel</b>. If the <b>OK</b>
|
||
button is pressed, the application is terminated. If the <b>Cancel</b>
|
||
button is pressed, the debugger specified in the <b>Debugger</b> key is
|
||
started.</p>
|
||
|
||
<p>If the <b>Auto</b> key equals zero, but the <b>Debugger</b> key value is
|
||
empty, the message box will have only an <b>OK</b> button and no debugger
|
||
will start.</p>
|
||
|
||
<p>If the <b>Auto</b> key equals one, no message box appears. The debugger
|
||
referred to in the <b>Debugger</b> key is automatically started.</p>
|
||
|
||
<p><b>Setting Dr. Watson as the JIT debugger (default):</b></p>
|
||
|
||
<pre>
|
||
Debugger = "drwtsn32 -p %ld -e %ld -g"
|
||
Auto = 1
|
||
</pre>
|
||
|
||
<p><b>Setting WinDbg as the JIT debugger:</b></p>
|
||
|
||
<pre>
|
||
Debugger = "WinDbg -p %ld -e %ld"
|
||
Auto = 1
|
||
</pre>
|
||
|
||
<p><b>Setting NTSD as the JIT debugger:</b></p>
|
||
|
||
<pre>
|
||
Debugger = "NTSD -p %ld -e %ld -g"
|
||
Auto = 1
|
||
</pre>
|
||
|
||
<p>In these examples, -<b>p %ld</b> specifies the process ID that NTSD
|
||
will debug, -<b>e %ld</b> provides the event that caused the
|
||
exception, and -<b>g</b> causes the debugger to skip the initial
|
||
breakpoint. (Dr. Watson ignores the -<b>g</b> option.)</p>
|
||
|
||
<h2><a name="imagehlp"></a>The IMAGEHLP.DLL Saga</h2>
|
||
|
||
<p><em>[Taken from several Bugslayer articles of MSJ.]</em></p>
|
||
|
||
<p>The IMAGEHLP.DLL symbol engine first appeared in Windows NT<4E> 4.0. The
|
||
beta Windows NT 5.0 SDK had new parts of IMAGEHLP.H that dealt with source
|
||
and line information. In the meantime, the November 1998 Platform SDK
|
||
showed and the IMAGEHLP.DLL that shipped with it supported the new source
|
||
and line handling. There are several different versions of IMAGEHLP.DLL.
|
||
The only one that does not support the new source and line information is
|
||
the original Windows NT 4.0 version. </p>
|
||
|
||
<p>The IMAGEHLP.DLL version 5.00.1678.1 dynamically links to MSPDB50.DLL.
|
||
It first tries to load MSDBI.DLL, and if that is not found it will load
|
||
MSPDB50.DLL, so it works with both Visual C++<2B> 5.0 and 6.0. To use it with
|
||
Visual C++ 6.0, copy MSPDB50.DLL to MSPDB60.DLL. If you want to get symbols
|
||
from the field, you will have to compile with CodeView<65> symbols and use
|
||
.DBG files to get them. Keep in mind that MSPDB50.DLL, like MSDBI.DLL, is
|
||
not redistributable. </p>
|
||
|
||
<p>The IMAGEHLP.DLL version 5.00.1878.1, which comes with the Windows 2000
|
||
Beta 2 Platform SDK, hard links against MSDBI.DLL instead of dynamically
|
||
loading MSPDB50.DLL as in earlier versions to read PDB files. The problem
|
||
is that MSDBI.DLL is not redistributable.</p>
|
||
|
||
<p>IMAGEHLP.DLL now uses DEBUGHLP.DLL.</p>
|
||
|
||
<p>If you want IMAGEHLP.DLL, it's available in:</p>
|
||
|
||
<ul>
|
||
<li>
|
||
Platform SDK
|
||
</li>
|
||
<li>
|
||
WinDBG Debugger
|
||
</li>
|
||
<li>
|
||
Windows 2000
|
||
</li>
|
||
</ul>
|
||
|
||
<h1>Suggested Reading</h1>
|
||
|
||
<ul>
|
||
<li> <a
|
||
href="http://www.microsoft.com/msj/0197/exception/exception.htm">A
|
||
Crash Course on the Depths of Win32 Structured Exception Handling, MSJ
|
||
January 1997</a> </li>
|
||
|
||
<li> <a
|
||
href="http://www.microsoft.com/msj/0497/hood/hood0497.htm">MSJEXHND -
|
||
Part 1, Under the Hood, MSJ April 1997</a></li>
|
||
|
||
<li> <a
|
||
href="http://www.microsoft.com/msj/0597/hood0597.htm">MSJEXHND -
|
||
Part 2, Under the Hood, MSJ May 1997</a></li>
|
||
|
||
<li><a
|
||
href=http://www.microsoft.com/msj/0898/bugslayer0898.htm>Bugslayer,
|
||
MSJ, August 1998</a></li>
|
||
|
||
<li> <a
|
||
href="http://msdn.microsoft.com/library/techart/msdn_debug.htm"> The
|
||
Win32 Debugging Application Programming Interface</a></li>
|
||
</ul>
|
||
|
||
</body>
|
||
</html>
|
||
|
||
<!-- vim: set ai ts=4 sw=4 noet syntax=pyhtml: -->
|