Skip to content

Commit

Permalink
Update doc.
Browse files Browse the repository at this point in the history
  • Loading branch information
José Fonseca committed Mar 21, 2009
1 parent 296d9d5 commit db7edd5
Showing 1 changed file with 4 additions and 192 deletions.
196 changes: 4 additions & 192 deletions doc/drmingw.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@
<title>Dr. Mingw</title>
</head>
<body>
<h1>About</h1>

<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>
Expand All @@ -19,11 +21,6 @@ <h1>Features</h1>
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>
Expand Down Expand Up @@ -160,192 +157,7 @@ <h1>Command Line Options</h1>
</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(&quot;exchndl.dll&quot;)</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&nbsp;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&nbsp;%ld</b> specifies the process ID that NTSD
will debug, -<b>e&nbsp;%ld</b> provides the event that caused the
exception, and -<b>g</b> causes the debugger to skip the initial
breakpoint. (Dr.&nbsp;Watson ignores the -<b>g</b> option.)</p>

<h2><a name="imagehlp"></a>The IMAGEHLP.DLL Saga</h2>
<h1><a name="imagehlp"></a>The IMAGEHLP.DLL Saga</h1>

<p><em>[Taken from several Bugslayer articles of MSJ.]</em></p>

Expand Down Expand Up @@ -414,4 +226,4 @@ <h1>Suggested Reading</h1>
</body>
</html>

<!-- vim: set ai ts=4 sw=4 noet syntax=pyhtml: -->
<!-- vim: set ai ts=4 sw=4 noet syntax=html: -->

0 comments on commit db7edd5

Please sign in to comment.