Sender:	rich AT delorie DOT com
Message-ID:	<38897875.F4C5E782@tudor21.net>
Date:	Sat, 22 Jan 2000 09:29:25 +0000
From:	Richard Dawe <richdawe AT bigfoot DOT com>
X-Mailer:	Mozilla 4.51 [en] (X11; I; Linux 2.2.14 i586)
X-Accept-Language:	de,fr
MIME-Version:	1.0
To:	djgpp-workers AT delorie DOT com
Subject:	Re: docs for symify
References:	<Pine DOT SUN DOT 3 DOT 91 DOT 1000119120915 DOT 9609a-100000 AT is>
Reply-To:	djgpp-workers AT delorie DOT com

This is a multi-part message in MIME format.
--------------7F3C90CF016B79658547FE73
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

Hello.

Eli Zaretskii wrote:
>
> On Tue, 18 Jan 2000 juergen AT peak-Service DOT com wrote:
>
> > Does any one know where to find docs for symify?
> 
> There are none at this time, unfortunately (want to write it up and
> contribute?).

Please find attached a context diff against djlsr203 that adds a
description of symify to src/utils/utils.tex. It's only a brief
description with links to relevant sections in the (info-version) FAQ. I
didn't think there was any point duplicating the good sections in the FAQ.

Thanks, bye,

-- 
Richard Dawe
richdawe AT bigfoot DOT com ICQ 47595498 http://www.bigfoot.com/~richdawe/
--------------7F3C90CF016B79658547FE73
Content-Type: text/plain; charset=us-ascii;
 name="utils.tex.20000122.diff"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="utils.tex.20000122.diff"

*** src/utils/utils.tex	Fri Jan 21 22:52:50 2000
--- /shared/develop/symify-docs/utils.tex	Sat Jan 22 09:22:16 2000
***************
*** 52,57 ****
--- 52,60 ----
  
  * update::      conditionally copy one file to another.
  
+ * symify::      Analyse the tracebacks generated when DJGPP
+                 programs crash.
+ 
  @end menu
  
  @c -----------------------------------------------------------------------------
***************
*** 507,513 ****
  redirect the output to a file or a printer.
  
  @c -----------------------------------------------------------------------------
! @node update, , texi2ps, Top
  @chapter update
  
  @code{update} is a fancy copy-if-needed program.  Basically, it compares
--- 510,516 ----
  redirect the output to a file or a printer.
  
  @c -----------------------------------------------------------------------------
! @node update, symify, texi2ps, Top
  @chapter update
  
  @code{update} is a fancy copy-if-needed program.  Basically, it compares
***************
*** 529,533 ****
--- 532,634 ----
          update y_tab.h foo.h
          update y_tab.c foo.c
  @end example
+ 
+ @c -----------------------------------------------------------------------------
+ @node symify, , update, Top
+ @chapter symify
+ 
+ When a DJGPP program crashes, it (usually) produces some diagnostic
+ information. This is called a traceback and shows the processor's registers
+ and stack frames at the time of the crash. For example:
+ 
+ @example
+ Exiting due to signal SIGSEGV
+ General Protection Fault at eip=0000158a
+ eax=ffffffff ebx=00008268 ecx=00000000 edx=0000033f esi=00000054 edi=0000c2f4
+ ebp=0008c2a0 esp=0008c2a0 program=C:\DEVELOP\CRASH\CRASH.EXE
+ cs: sel=00a7  base=82685000  limit=0009ffff
+ ds: sel=00af  base=82685000  limit=0009ffff
+ es: sel=00af  base=82685000  limit=0009ffff
+ fs: sel=0087  base=00013f00  limit=0000ffff
+ gs: sel=00bf  base=00000000  limit=0010ffff
+ ss: sel=00af  base=82685000  limit=0009ffff
+ App stack: [0008c2f4..0000c2f4]  Exceptn stack: [0000c1d8..0000a298]
+ 
+ Call frame traceback EIPs:
+   0x0000158a
+   0x00001579
+   0x000028fa
+ @end example
+ 
+ This information can be used to find the location of the crash and help
+ to debug the program. symify can decode this information. For symify to
+ work, the crashed program must have been:
+ 
+ @itemize @bullet
+ @item
+ compiled with debugging, i.e. the @code{-g} option passed to gcc;
+ @item
+ linked without removing symbols, i.e. the @code{-s} option not passed
+ to gcc;
+ @item
+ not stripped (@pxref{strip, , strip, binutils}).
+ @end itemize
+ 
+ Usage:
+ @code{symify}
+ [-i @code{saved_traceback_file}]
+ [-o @code{decoded_output_file}]
+ @code{program}
+ 
+ To analyse the traceback off the screen for a program that has just crashed,
+ run symify like:
+ 
+ @example
+ symify program.exe
+ @end example
+ 
+ symify will update the traceback with the decoded information.
+ 
+ symify can also analyse a saved traceback. The traceback can be saved by
+ input redirection (e.g. via @pxref{redir}) or via cut'n'paste from a
+ DOS window in Windows. The traceback can then be decoded and displayed using
+ a command like:
+ 
+ @example
+ symify -i traceback.dmp program.exe
+ @end example
+ 
+ For instance, the traceback at the start of this chapter decodes to:
+ 
+ @example
+ Exiting due to signal SIGSEGV
+ General Protection Fault at eip=0000158a
+ eax=ffffffff ebx=00008268 ecx=00000000 edx=0000033f esi=00000054 edi=0000c2f4
+ ebp=0008c2a0 esp=0008c2a0 program=C:\DEVELOP\CRASH\CRASH.EXE
+ cs: sel=00a7  base=82685000  limit=0009ffff
+ ds: sel=00af  base=82685000  limit=0009ffff
+ es: sel=00af  base=82685000  limit=0009ffff
+ fs: sel=0087  base=00013f00  limit=0000ffff
+ gs: sel=00bf  base=00000000  limit=0010ffff
+ ss: sel=00af  base=82685000  limit=0009ffff
+ App stack: [0008c2f4..0000c2f4]  Exceptn stack: [0000c1d8..0000a298]
+ 
+ Call frame traceback EIPs:
+   0x0000158a _crash_me_now+6, line 16 of crash.c
+   0x00001579 _main+25, line 13 of crash.c
+   0x000028fa ___crt1_startup+174
+ @end example
+ 
+ Hence, you can trace the flow of execution to the line that caused the crash.
+ 
+ symify can also output the decoded traceback to a file:
+ 
+ @example
+ symify -i traceback.dmp -o decoded.dmp program.exe
+ @end example
+ 
+ symify is also discussed extensively in the DJGPP FAQ - see
+ @ref{Crash traceback, , Crash traceback, djgppfaq},
+ @ref{Crash dump, , Crash dump, djgppfaq}.
  
  @bye

--------------7F3C90CF016B79658547FE73--

- Raw text -