mingw/doc/drmingw/drmingw.html

   1 <html>
   2 <head>
   3         <title>Dr. Mingw</title>
   4 </head>
   5 <body>
   6         <p>Dr. Mingw is a <i>Just-in-Time (JIT)</i> debugger. When the application throws
   7         an unhandled exception, Dr. Mingw attaches itself to the application and collects
   8         information about the exception, using the available debugging information.</p>
   9
  10         <h1>Features</h1>
  11
  12         <p>Dr. Mingw can read debugging information in <em>Stabs</em> formats &#151; generated
  13         by the Gnu C/C++ Compiler, and in a PDB file &#151; generated by the Microsoft
  14         Visual C++ Compiler.</p>
  15
  16         <p>Windows NT/2000 platform is supported, as well as Windows 95/98. On older Windows
  17         versions though, the IMAGEHLP.DLL isn't included or it's a rather old version.
  18         Dr. Mingw doesn't require it, but relies upon it to resolve symbols in modules
  19         compiled by the Microsoft tools. See <a href="#imagehlp">The
  20         IMAGEHLP.DLL Saga</a> for more information. </p>
  21
  22         <h1>Download</h1>
  23
  24         <p>Dr. Mingw is now part of <a
  25         href="http://sourceforge.net/project/showfiles.php?group_id=2435&release_id=115457">mingw-utils</a>.</p>
  26
  27         <h1>Installation</h1>
  28
  29         <p>If you didn't download the self-installing package, to install enter</p>
  30
  31         <blockquote>
  32                 <pre><b>drmingw -i</b></pre>
  33         </blockquote>
  34
  35         <p>Dr. Mingw will register itself as the JIT debugger by writting into the
  36         system registry. On Windows NT/2000 make sure you have Administrator
  37         rights. See <a href="#jit">Enabling Just-in-Time (JIT) Debugging</a> for
  38         more information.</p>
  39
  40         <p>If the installation is sucessful, the following message box should appear:</p>
  41
  42         <p align="center"><img src="install.gif" alt="installation dialog"/></p>
  43
  44         <p>To enable other options they must be set them allong with the <b>-i</b>
  45         option. For example,</p>
  46
  47         <blockquote>
  48                 <pre><b>drmingw -i -v </b></pre>
  49         </blockquote>
  50
  51         <p>If you still have trouble installing, edit the included<b>
  52         drmingw.reg</b> file to reflect the <b>drmingw.exe</b> executable path and
  53         load it on the system registry.</p>
  54
  55         <h1>Usage</h1>
  56
  57         <p>You can test Dr. Mingw by running the sample<b> test.exe</b>. Depending
  58         of your Windows version, you'll see a familiar dialog:</p>
  59
  60         <p align="center"><img src="exception-nt.gif" alt="Windows general protection fault dialog"/></p>
  61
  62         <p>If you request to debug the program, Dr. Mingw will attach to the
  63         faulting application, collect information about the exception, and display
  64         the dialog</p>
  65
  66         <p align="center"><img src="sample.gif" alt="sample report"/></p>
  67
  68         <p>To resolve the addresses it's necessary to compile the application with
  69         debugging information. In case of address is in a DLL with no debugging
  70         information, it will resolve to the precedent exported symbol.</p>
  71
  72         <h1>Command Line Options</h1>
  73
  74         <p>The Dr. Mingw command line uses the following syntax:</p>
  75
  76 <pre>
  77 <b>drmingw </b>[<b>-h | --help</b>] [<b>-V | --version</b>] [<b>-i | --install</b>] [<b>-a | --auto</b>] [<b>-u | --uninstall</b>]
  78 [<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>]
  79 [<b>-v | --verbose</b>]
  80 </pre>
  81
  82         <p>The following table describes the Dr. Mingw command-line options. All
  83         comand-line options are case-sensitive. </p>
  84
  85         <table width="78%" summary="command-line options">
  86                 <tr>
  87                         <th align=left width=10%>Option</th>
  88                         <th align=left width=25%>&nbsp;</th>
  89                         <th align=left width=65%>Action</th>
  90                 </tr>
  91                 <tr>
  92                         <td width=10%>
  93                                 <pre><b>-h</b></pre>
  94                         </td>
  95                         <td width=25%>
  96                                 <pre><b>--help</b></pre>
  97                         </td>
  98                         <td width=65%>Print help and exit </td>
  99                 </tr>
 100                 <tr>
 101                         <td width=10%>
 102                                 <pre><b>-V</b></pre>
 103                         </td>
 104                         <td width=25%>
 105                                 <pre><b>--version</b></pre>
 106                         </td>
 107                         <td width=65%>Print version and exit</td>
 108                 </tr>
 109                 <tr>
 110                         <td width=10%>
 111                                 <pre><b>-i</b></pre>
 112                         </td>
 113                         <td width=25%>
 114                                 <pre><b>--install</b></pre>
 115                         </td>
 116                         <td width=65%>Install as the default JIT debugger</td>
 117                 </tr>
 118                 <tr>
 119                         <td width=10%>
 120                                 <pre><b>-a</b></pre>
 121                         </td>
 122                         <td width=25%>
 123                                 <pre><b>--auto</b></pre>
 124                         </td>
 125                         <td width=65%>Automatically start (used with <b>-i</b> | <b>--install</b>)</td>
 126                 </tr>
 127                 <tr>
 128                         <td width=10%>
 129                                 <pre><b>-u</b></pre>
 130                         </td>
 131                         <td width=25%>
 132                                 <pre><b>--uninstall</b></pre>
 133                         </td>
 134                         <td width=65%>Uninstall</td>
 135                 </tr>
 136                 <tr>
 137                         <td width=10%>
 138                                 <pre><b>-p</b> <i>pid</i></pre>
 139                         </td>
 140                         <td width=25%>
 141                                 <pre><b>--process-id=</b><i>pid</i></pre>
 142                         </td>
 143                         <td width=65%>Attach to the process with the given identifier</td>
 144                 </tr>
 145                 <tr>
 146                         <td width=10%>
 147                                 <pre><b>-e</b> <i>event</i></pre>
 148                         </td>
 149                         <td width=25%><pre><b>--event=</b><i>event</i></pre></td>
 150                         <td width=65%>Signal an event after process is attached</td>
 151                 </tr>
 152                 <tr>
 153                         <td width=10%>
 154                                 <pre><b>-v</b></pre>
 155                         </td>
 156                         <td width=25%>
 157                                 <pre><b>--verbose</b></pre>
 158                         </td>
 159                         <td width=65%>Verbose output</td>
 160                 </tr>
 161         </table>
 162
 163         <h1><a name="exchndl"></a>The EXCHNDL.DLL</h1>
 164
 165         <h2>Introduction</h2>
 166
 167         <p>Although internally Dr. Mingw behaves much like a debugger, from the
 168         outside it is like a standalone exception handler. But for its own
 169         debugging purposes, Dr. Mingw has a internal exception handler that is
 170         completly seperate from the main code.</p>
 171
 172         <p>This exception handler resides in <b>exchndl.c</b>. When
 173         <b>drmingw.exe</b> is loaded, the code in <b>exchndl.c</b> is automatically
 174         executed (by the gcc static constructor/destructor mechanism) and registers
 175         itself as a exception handler.</p>
 176
 177         <p>This exception handler is much lighter than Dr. Mingw debugging system
 178         because it doesn't have to deal with interprocess communication. The
 179         exception handling routine runs in the same process context of the faulting
 180         application (<b>drmingw</b>, in this case).</p>
 181
 182         <h2>Using ExcHndl for you own purposes</h2>
 183
 184         <p>If you incorporate ExcHndl in you own programs, especially those that
 185         you release to others, you can have almost the same exception information
 186         that you would get with Dr. Mingw, but with no need of the end user to have
 187         Dr. Mingw installed.</p>
 188
 189         <p>You can use ExcHndl in two ways:</p>
 190
 191         <ul>
 192                 <li>linking <b>exchndl.o</b> and <b>libbfd.a</b> with your program objects</li>
 193
 194                 <li>linking <b>exchndl.o</b> and <b>libfd.a</b> in the
 195                 <b>EXCHNDL.DLL</b> and dinamically loading it at run-time. This can be
 196                 done by linking just <b>exchndl2.o</b> or explicitly calling
 197                 <i>LoadLibrary(&quot;exchndl.dll&quot;)</i></li>
 198         </ul>
 199
 200         <p>The latter method is preferred because you have smaller executables and
 201         don't need to link the BFD library in all builds. The application wont fail
 202         if the <b>EXCHNDL.DLL</b> is missing.</p>
 203
 204         <h2>Example</h2>
 205
 206         <p>The sample<b> test.exe</b> application uses the second method above.
 207         Copy <b>EXCHNDL.DLL</b> to executable directory. When you run it, even
 208         before general protection fault dialog box appears, it's written to the
 209         <b>test.RPT</b> file a report of the fault.</p>
 210
 211         <p>Here is how <b>test.RPT</b> should look like:</p>
 212
 213 <pre>
 214 -------------------
 215
 216 Error occured on Sunday, May 7, 2000 at 20:22:03.
 217
 218 C:\home\jrfonseca\drmingw\src\test.exe caused an Access Violation in module C:\WINDOWS\system32\msvcrt.dll Writing to location 00000008.
 219
 220 Registers:
 221 eax=00003039 ebx=00000064 ecx=00000008 edx=0244fec0 esi=00401211 edi=0244fec0
 222 eip=78027470 esp=0244fcd8 ebp=0244fea8 iopl=0         nv up ei pl nz na pe nc
 223 cs=001b  ss=0023  ds=0023  es=0023  fs=0038  gs=0000             efl=00010202
 224
 225 Call stack:
 226 78027470  C:\WINDOWS\system32\msvcrt.dll:78027470  wscanf
 227 7802544B  C:\WINDOWS\system32\msvcrt.dll:7802544B  sscanf
 228 00401241  C:\home\jrfonseca\drmingw\src\test.exe:00401241  YetAnotherFunction  //C/home/jrfonseca/drmingw/src/test.cxx:14
 229 00401272  C:\home\jrfonseca\drmingw\src\test.exe:00401272  MyWonderfulFunction  //C/home/jrfonseca/drmingw/src/test.cxx:19
 230 004012A9  C:\home\jrfonseca\drmingw\src\test.exe:004012A9  main  //C/home/jrfonseca/drmingw/src/test.cxx:24
 231 004011C1  C:\home\jrfonseca\drmingw\src\test.exe:004011C1
 232 004011EB  C:\home\jrfonseca\drmingw\src\test.exe:004011EB
 233 77E87903  C:\WINDOWS\system32\KERNEL32.dll:77E87903  SetUnhandledExceptionFilter
 234 </pre>
 235
 236         <h1>Appendix</h1>
 237
 238         <h2><a name="jit"></a>Enabling Just-in-Time (JIT) Debugging</h2>
 239
 240         <p><em>[Taken from Using Microsoft Debuggers of the April 2000 Platform SDK.]</em></p>
 241
 242         <p>There are a variety of application errors which will cause Windows
 243         NT/Windows 2000 a to terminate the application. The most common kinds of
 244         errors are deadlocks and access violations. From the operating systems
 245         point of view, these are all simply unhandled exceptions.</p>
 246
 247         <p>When an application error occurs, Windows searches for an exception
 248         handler. If it does not find an exception handler, the system verifies that
 249         the application is not currently being debugged and considers the exception
 250         to be unhandled. At this point, there are three possible responses:</p>
 251
 252         <ul>
 253                 <li>Windows can end the process immediately.</li>
 254
 255                 <li>Windows can freeze the process and start a user-mode debugger. This
 256                 debugger can then be used to examine the application.</li>
 257
 258                 <li>Windows can run a debugging tool which will create a memory dump
 259                 file of the application's memory space, and then end the process.</li>
 260         </ul>
 261
 262         <p>The debugging tool which is used to debug the application or write the
 263         dump file is called <I>Just-in-Time (JIT) Debugger</I>, or the
 264         <i>post-mortem debugger</i>.</p>
 265
 266         <p>The default JIT debugger is Dr. Watson. When the application throws
 267         an unhandled exception, Dr. Watson attaches itself to the application and
 268         generates a crash dump file. After it creates the crash dump file, Dr.
 269         Watson closes the application and exits.</p>
 270
 271         <p>Any user-mode debugging tool can be selected as the JIT debugger:</p>
 272
 273         <ul>
 274                 <li>To change the JIT debugger to WinDbg, run <b>windbg -I</b>. When
 275                 WinDbg is the JIT debugger, WinDbg will be activated whenever an
 276                 application crashes.  See WinDbg Command Line Options for details.</li>
 277
 278                 <li>To change the JIT debugger to NTSD, you must edit the registry.
 279                 When NTSD is the JIT debugger, NTSD will be activated whenever an
 280                 application crashes.</li>
 281
 282                 <li>To change the JIT debugger back to Dr. Watson, run <b>drwtsn32
 283                 -i</b>.  When Dr. Watson is the JIT debugger, a memory dump file will
 284                 be written to disk if an application crashes. See Dr. Watson Command
 285                 Line Options for details.</li>
 286         </ul>
 287
 288         <p>Only a system administrator can alter the JIT settings.</p>
 289
 290         <p>If a JIT debugger has been installed, you can deliberately break into
 291         the debugger from a user-mode application by calling the <b>DebugBreak</b>
 292         function.</p>
 293
 294         <h3>Editing the Registry</h3>
 295
 296         <p>The Just-in-Time debugging settings are stored in the registry, under
 297         <b>\\HKEY_LOCAL_MACHINE\Software\Microsoft\Windows&nbsp;NT\CurrentVersion\AeDebug\</b>.
 298         The two relevant keys in this directory are <b>Debugger</b> and
 299         <b>Auto</b>.</p>
 300
 301         <p>The <b>Debugger</b> key's value shows the name of the debugger specified
 302         to analyze application errors. The <b>Auto</b> key is either zero or
 303         one.</p>
 304
 305         <p>When an unhandled application error occurs, Windows checks to see if the
 306         <b>Debugger</b> and <b>Auto</b> keys exist.</p>
 307
 308         <p>If the <b>Auto</b> key equals zero and the <b>Debugger</b> value
 309         contains the name of a valid debugger (such as WinDbg or NTSD), the message
 310         box will have two buttons: <b>OK</b> and <b>Cancel</b>. If the <b>OK</b>
 311         button is pressed, the application is terminated. If the <b>Cancel</b>
 312         button is pressed, the debugger specified in the <b>Debugger</b> key is
 313         started.</p>
 314
 315         <p>If the <b>Auto</b> key equals zero, but the <b>Debugger</b> key value is
 316         empty, the message box will have only an <b>OK</b> button and no debugger
 317         will start.</p>
 318
 319         <p>If the <b>Auto</b> key equals one, no message box appears. The debugger
 320         referred to in the <b>Debugger</b> key is automatically started.</p>
 321
 322         <p><b>Setting Dr. Watson as the JIT debugger (default):</b></p>
 323
 324 <pre>
 325 Debugger = "drwtsn32 -p %ld -e %ld -g"
 326 Auto = 1
 327 </pre>
 328
 329         <p><b>Setting WinDbg as the JIT debugger:</b></p>
 330
 331 <pre>
 332 Debugger = "WinDbg -p %ld -e %ld"
 333 Auto = 1
 334 </pre>
 335
 336         <p><b>Setting NTSD as the JIT debugger:</b></p>
 337
 338 <pre>
 339 Debugger = "NTSD -p %ld -e %ld -g"
 340 Auto = 1
 341 </pre>
 342
 343         <p>In these examples, -<b>p&nbsp;%ld</b> specifies the process ID that NTSD
 344         will debug, -<b>e&nbsp;%ld</b> provides the event that caused the
 345         exception, and -<b>g</b> causes the debugger to skip the initial
 346         breakpoint. (Dr.&nbsp;Watson ignores the -<b>g</b> option.)</p>
 347
 348         <h2><a name="imagehlp"></a>The IMAGEHLP.DLL Saga</h2>
 349
 350         <p><em>[Taken from several Bugslayer articles of MSJ.]</em></p>
 351
 352         <p>The IMAGEHLP.DLL symbol engine first appeared in Windows NT® 4.0. The
 353         beta Windows NT 5.0 SDK had new parts of IMAGEHLP.H that dealt with source
 354         and line information. In the meantime, the November 1998 Platform SDK
 355         showed and the IMAGEHLP.DLL that shipped with it supported the new source
 356         and line handling.  There are several different versions of IMAGEHLP.DLL.
 357         The only one that does not support the new source and line information is
 358         the original Windows NT 4.0 version. </p>
 359
 360         <p>The IMAGEHLP.DLL version 5.00.1678.1 dynamically links to MSPDB50.DLL.
 361         It first tries to load MSDBI.DLL, and if that is not found it will load
 362         MSPDB50.DLL, so it works with both Visual C++® 5.0 and 6.0. To use it with
 363         Visual C++ 6.0, copy MSPDB50.DLL to MSPDB60.DLL. If you want to get symbols
 364         from the field, you will have to compile with CodeView® symbols and use
 365         .DBG files to get them. Keep in mind that MSPDB50.DLL, like MSDBI.DLL, is
 366         not redistributable.  </p>
 367
 368         <p>The IMAGEHLP.DLL version 5.00.1878.1, which comes with the Windows 2000
 369         Beta 2 Platform SDK, hard links against MSDBI.DLL instead of dynamically
 370         loading MSPDB50.DLL as in earlier versions to read PDB files. The problem
 371         is that MSDBI.DLL is not redistributable.</p>
 372
 373         <p>IMAGEHLP.DLL now uses DEBUGHLP.DLL.</p>
 374
 375         <p>If you want IMAGEHLP.DLL, it's available in:</p>
 376
 377         <ul>
 378                 <li>
 379                         Platform SDK
 380                 </li>
 381                 <li>
 382                         WinDBG Debugger
 383                 </li>
 384                 <li>
 385                         Windows 2000
 386                 </li>
 387         </ul>
 388
 389         <h1>Suggested Reading</h1>
 390
 391         <ul>
 392                 <li> <a
 393                 href="http://www.microsoft.com/msj/0197/exception/exception.htm">A
 394                 Crash Course on the Depths of Win32 Structured Exception Handling, MSJ
 395                 January 1997</a> </li>
 396
 397                 <li> <a
 398                 href="http://www.microsoft.com/msj/0497/hood/hood0497.htm">MSJEXHND -
 399                 Part 1, Under the Hood, MSJ April 1997</a></li>
 400
 401                 <li> <a
 402                 href="http://www.microsoft.com/msj/0597/hood0597.htm">MSJEXHND -
 403                 Part 2, Under the Hood, MSJ May 1997</a></li>
 404
 405                 <li><a
 406                 href=http://www.microsoft.com/msj/0898/bugslayer0898.htm>Bugslayer,
 407                 MSJ, August 1998</a></li>
 408
 409                 <li> <a
 410                 href="http://msdn.microsoft.com/library/techart/msdn_debug.htm"> The
 411                 Win32 Debugging Application Programming Interface</a></li>
 412         </ul>
 413
 414 </body>
 415 </html>
 416
 417 <!-- vim: set ai ts=4 sw=4 noet syntax=pyhtml: -->