Dokumentation zu DBUG V1.00 (11/92)
Geschrieben von Holger Weets mit SOZOBON-C V2.00x9

F�r Programmierer ein fast t„gliches Erlebnis: ein paar Quelltexte
�bersetzt, anschliežend das resultierende Programm gestartet und ...
... Bomben.
Woran liegts ?
Genau hier soll das vorliegende Programm weiterhelfen: einfach fehlerhaftes
Programm erneut linken, dabei den Linker anweisen, die Symboltabelle in
das Programm zu schreiben und anschliežend DBUG mit dem Programm als
Parameter starten (und evtl. ein paar Optionen).
DBUG versucht nun herauszufinden, in welcher Funktion das Programm abge-
st�rzt ist, und gibt den Namen dann aus, was im allgemeinen eine Menge
Probeausgaben spart.

Aufruf: DBUG [-npbirh -oFILE -eMEM] Programm
        -n: SymbolTabellen etc. nicht auf den Bildschirm ausgeben
        -p: SymbolTabelle ausgeben;
            die Ausgabe erfolgt sortiert nach Position in der Datei, so
            daž die L„nge der einzelnen Funktionen z.B. direkt abgelesen
            werden kann
        -b: letzte Absturzstelle nicht anzeigen;
            DBUG kann nat�rlich auch dazu verwendet werden, sich einfach
            mal die Segementgr”žen oder die Symboltabelle von Programmen
            anzeigen zu lassen, und zwar von solchen, die nicht abgest�rzt
            sind; in diesem Fall w�rde die Ausgabe, weil falsch, nur Ver-
            wirren.
            Wenn die Absturzstelle angezeigt wird (Default), dann in
            folgender Form:
            - Exception Nummer (wieviele Bomben, welche FehlerArt)
            - falls gefunden den Namen der Funktion und der Offset in
              diese
            - falls gefunden die Datei, in der die Funktion steht, und
              die Nummer der Zeile, in der sie beginnt
              dies funktioniert genau dann, wenn eine TAGFILE-Datei im
              gleichen Ordner steht, wie das Programm, und im TAGFILE die
              Funktion auch aufgef�hrt ist.
              Das TAGFILE wird durch das gleichnamige von mir geschriebene
              Programm erzeugt, Pfad und Dateiname werden i.a. automatisch
              auf die richtigen Werte gesetzt. Tagfile gibts aktuell nur
              f�r die Sprache C.
        -i: Segment-Gr”žen ausgeben;
            zeigt die Gr”že des TEXT-, DATA- BSS- und Symbol-Segmentes
        -r: Register- und Stack-Inhalte zur Zeit des letzten Absturzes
            ausgeben (nur, wenn -b nicht angegeben)
        -h: am Ende auf eine Taste warten
            Damit DBUG auch vom Desktop aus verwendet werden kann, muž ein
            TOS-Programm vor seiner Terminierung auf einen Tastendruck
            warten, damit die Ausgaben noch gelesen werden k”nnen.
        -oFILE: Ausgabe in Datei FILE, und, wenn -n nicht angegeben wurde,
                zus„tzlich auf den Bildschirm
        -eMEM: falls die fehlerhafte Funktion im Tagfile gefunden wurde,
               die betreffende Datei plus Zeilennummer in MEM schreiben
               und mit Exit-Code 4 abbrechen.
               Diese Option wurde speziell f�r ACE, einen ebenfalls von
               mir geschriebenen C-Editor mit eingebauter Projektverwaltung,
               eingebaut, und stellt eine einfache Art dar, Daten an das
               aufrufende Programm zur�ckzugeben. Zuerst gesehen habe ich
               dieses Verfahren beim Lindner-TeX, wo es daf�r verwendet
               wird, den Namen der fehlerhaften Datei und die Nummer der
               fehlerhaften Zeile an die Shell zur�ckzugeben. Da ich dies
               in ACE eingebaut habe, ist die Kennung im Buffer auch in
               diesem Fall "texshell" (der Einfachheit halber).
               Wenn DBUG also von ACE aus mit der Kommandozeile
                    "-e$t $f"
               aufgerufen wird, dann l„dt ACE die anschliežend in MEM
               angegebene Datei evtl. nach und setzt den Cursor auf die
               dort angegebene Zeilennummer.
               F�r Shellschreiber hier das Vorgehen im einzelnen:
                    - einen Buffer anlegen, der mindestens 140 Zeichen
                      fassen k”nnen sollte
                    - dessen Adresse hinter '-e' schreiben
                    - in diesen Buffer den String "texshell" kopieren
                    - DBUG aufrufen
                    - falls der ExitCode (Ergebnis von Pexec()) 4 ist, sind
                      die Daten im Buffer g�ltig und haben folgende Form:
                      Dateiname mit Pfad / ein Leerzeichen / Zeilennummer
                      z.B.: |a:\test\main.c 123|
                      dieser Buffer kann also direkt als Kommandozeile f�r
                      einen Editor verwendet werden.

Falls Ausgaben auf dem Bildschirm gemacht werden, so k”nnen diese jederzeit
durch dr�cken und festhalten einer der Tasten SHIFT, CONTROL oder ALTERNATE
angehalten werden.

Happy Debugging
--Holger