AutoDbg - Auto Debugger Helper DLL
(c) 2001 by A. Tofahrn
www.tofahrn.de
Inhalt

Intention
Konventionen
API
Copyright und Kontakt

Intention TOC ->

In größeren und kleineren Anwendungen stellen die sogenannten Ausnahe-Schutzverletzungen sowohl die Anwender als auch die Programmierer vor teilweise erhebliche Geduld-Proben. Vor allem jede Fehler, welche nur selten oder unter nur schwer zu reproduzierenden Bedingungen auftreten, vermindern zur zu häufigt die Freude an einer Anwendung.

Zwar bieten Debugger mitunter weitreichenden Support beim Auffinden solcher Fehler, nur sind diese in der Regel gerade nicht gestartet, wenn ein solcher Fehler auftritt. Und die Meldung des Systems, daß die Anwendung nun wegen eines solchen Fehlers an einer bestimmten Adresse abgebrochen wird, hilft auch nur selten weiter.

Die AutoDbg.DLL soll nun Anwendungen mit einem einfachen Mechanismus zur Erstellung von Diagnose-Informationen beim Auftreten eines Ausnahmefehlers erweitern. Dazu registriert sich die DLL beim Laden in den Prozess als Unexpected-Handler und fängt somit alle nicht anderweitig behandelten Fehler ab.

Über verschiedene System-APIs sowie der DBGHELP.DLL aus dem Platform SDK von Microsoft werden zahlreiche Informationen zusammengetragen, welche dem Programmierer beim Auffinden des Fehlers helfen können. Dazu gehören neben der verwendeten System-Umgebung, wie Betriebs-System, Prozessor-Typ und -Geschwindigkeit oder der RAM-Ausbau, auch ein Stack-Trace mit Symbol-Informationen sowie die Angabe der Quelltext-Datei samt Zeilen-Nummer.

Um diese Funktionalität in eine Anwendung einzubingen, muß lediglich die AutoDbg.DLL im jeweiligen Prozeß geladen werden. Dies kann durch direkte Bindung mit einer der exportierten Funktionen oder über einen LoadLibrary-Aufruf erfolgen.

Konventionen TOC ->

Zunächst müssen einige Begriffe definiert werden, welche in der weiteren Dokumentation verwendet werden.

Damit vernünftige Informationen auch in der Release-Build angezeigt werden, muss unter Visual C++ folgendes geschehen:

AutoDbg Funktionen TOC ->

Die Library bietet einen kleinen Satz an Schnittstellen, über welche einige Funktionalitäten parametrisiert werden können:

DWORD AdbgSetFlags(DWORD Flags)
Setzt verschiedene Flags, welche das Verhalten des Debuggers steuern.
ADBGUNEXPECTED AdbgSetUnexpectedHandler(ADBGUNEXPECTED UnexpectedHandler)
Setzt eine Callback-Funktion, welche vor der Erzeugung des Logs aufgerufen wird.
ADBGLOGGER AdbgSetLogger(ADBGLOGGER pLog, PVOID LogCtx)
Setzt die Callback-Funktion zur Protokollierung.
DWORD AdbgSetFlags(DWORD Flags) AutoDbg Funktionen

Mit dieser Funktion läßt sich die Menge und Art der ausgewerteten Informationen beeinflußen. Als Flags wird dabei eine Kombination der folgenden Schalter akzeptiert:

ADBGLOGGER AdbgSetLogger(ADBGLOGGER pLog, PVOID LogCtx) AutoDbg Funktionen

Das Ausgabe-Verhalten der DLL kann durch Setzen einer Log-Funktion leicht angepaßt werden. Eine Log-Funktion muß folgendermaßen deklariert werden:

void (*ADBGLOGGER)(ADBGLOG LogType, PVOID LogCtx, char const *Fmt, ...)

Die Parameter sind die Folgenden:

Als Logger ließe sich zum Beispiel diese Funktion verwenden:

void LogConsole(ADBGLOG LogType, PVOID LogCtx, char const *Fmt, ...)
   {
   vprintf(Fmt, (char*)(&Fmt+1));
   }

Zwei Logger-Funktionen sind in der AutoDbg-Library bereits enthalten:

void AdbgLogConsole(ADBGLOG LogType, PVOID LogCtx, char const *Fmt, ...)

void AdbgLogDialog(ADBGLOG LogType, PVOID LogCtx, char const *Fmt, ...)

ADBGUNEXPECTED AdbgSetUnexpectedHandler(ADBGUNEXPECTED UnexpectedHandler) AutoDbg Funktionen

Da sich der Auto-Debugger über den Unexpected-Handler im System registriert, steht dieser Mechanismus folglich nicht mehr der Anwendung zur Verfügung. Falls diese unerwartete Fehler zunächst selber prüfen möchte, kann sie einen entsprechenden Handler installieren.

Dieser Handler erhält genau einen Parameter vom Typ EXCEPTION_POINTERS* und muß eine der EXCEPTION_-Konstanten zurückliefern:

LONG (*ADBGUNEXPECTED)(EXCEPTION_POINTERS* pExp)

Liefert der Handler EXCEPTION_CONTINUE_SEARCH zurück, erzeugt der Auto-Debugger die angeforderten Log-Informationen. Jeder andere Wert wird an das System weitergeleitet, ohne daß die Log-Funktionen ausgeführt werden.

Copyright und Kontakt TOC

Kontakt

Andreas Tofahrn
Software-Entwicklung und Beratung
Hessenring 107
D-61184 Karben
e-mail: andreas@tofahrn.de

Copyright (c) 2001-2003 by A. Tofahrn