From: sandmann AT clio DOT rice DOT edu (Charles Sandmann)
Message-Id: <10302012320.AA22101@clio.rice.edu>
Subject: symify docs
To: djgpp-workers AT delorie DOT com (DJGPP developers)
Date: Sat, 1 Feb 2003 17:20:15 -0600 (CST)
X-Mailer: ELM [version 2.5 PL2]
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Reply-To: djgpp-workers AT delorie DOT com

Plan to commit soon

*** utils.bak	Sat Jan 25 11:50:58 2003
--- utils.tex	Sat Feb  1 17:16:38 2003
*************** come with DJGPP.
*** 62,67 ****
--- 62,71 ----
  
  * dxegen::      Create Dynamic Executable file
  
+ * symify::      Add procedure names and line numbers to tracebacks
+ * edebug32::    Simple line mode debugger for DJGPP images
+ * fsdb::        Full screen debugger for DJGPP images
+ 
  * djasm::       The DJGPP 16-bit assembler.
  
  @end menu
*************** getconf NAME_MAX c:/djgpp
*** 790,795 ****
--- 794,800 ----
  
  @include ../stub/stubdocs.txi
  @include ../dxe/dxegen.txi
+ @include ../debug/debugdoc.txi
  
  @c -----------------------------------------------------------------------------
  @node djasm, , getconf, Top


src/debug/debugdoc.txi .... >>>

@c -----------------------------------------------------------------------------
@node symify, edebug32, , Top
@chapter @command{symify}
@pindex symify

Usage: @kbd{symify [-o output.dmp] [-i input.dmp] progname.exe}

@command{symify} is a utility that adds procedure names and source line
numbers to the call frame traceback displayed on the screen when a program
aborts.  The default behavior is to add the extra information to the
screen, but input or output from files can be specified with the
@code{-o} and @code{-i} switches.  If @command{bfdsymify} is installed
@command{symify} will pass the arguments to @command{bfdsymify}.

@cindex Call frame traceback EIPs
@cindex traceback

The call frame traceback EIPs are displayed in hexadecimal address
values.  These values show the addresses where one procedure calls
another and has pushed its return information onto the stack.  The
values at the top are the most recently called procedures.
@command{symify} reads the debug information from the executable you
specify on the command line (with .exe extension) and puts it after the
hexadecimal numbers.  If the image is stripped there is no additional
information which can be added.  If you compiled the modules with the
@code{-g} switch to @command{gcc} you can also display source line
numbers (without @code{-g} you will only get procedure names and
offsets into those procedures).

@strong{Options:}

@table @code

@item -o output.dmp

Output to file.  @command{symify} copies the traceback plus symbolic
names and puts it into the file name you specify after the @code{-o}
option.  This allows you to save it (for sending to the author, or
examination while fixing the bug).  If @code{-o} is specified the
screen buffer is not changed.

@item -i input.dmp

Input from file.  @command{symify} reads the stack trace from the file
name you specify after the @code{-i} option.  This file could be created
by @code{redir} (@pxref{redir}) or redirecting handle 2 to a file.

@end table

Known compatibility problem (Windows NT, Windows 2000, Windows XP):

Sometimes @code{symify} cannot read the screen buffer to get the traceback
information.  In that case you must copy the screen buffer manually and
save it to a file, and use the @code{-i} option.


@c -----------------------------------------------------------------------------
@node edebug32, fsdb, symify, Top
@chapter @command{edebug32}
@pindex edebug32

Usage: @kbd{edebug32 debug-image.exe [args to debug-image]}

@command{edebug32} is a simple debugger for DJGPP images.  See the internal
help for more information on usage.  @command{edebug32} is an expert's 
debugger and does not support newer debugging formats.  It is recommended
that new users try one of the other more powerful or easy to use debuggers.


@c -----------------------------------------------------------------------------
@node fsdb, , edebug32, Top
@chapter @command{fsdb}
@pindex fsdb

Usage: @kbd{fsdb [-p path] [-d] [-s setup] debug-image.exe [args]}

@command{fsdb} is a full screen debugger for DJGPP images.  See the internal
help for more information on usage.  @command{fsdb} is not actively 
maintained and does not support newer debugging formats.  It is recommended
that new users try one of the other newer debuggers.

@strong{Options:}

@table @code

@item -p source-path

Source path.  Specify the path for source files used to build this image.

@item -d

Dual monitors.  Enable dual monitor display using monochrome graphics
card.  Useful when debugging graphics images but requires special hardware.

@item -s setup-file

Setup file.  Load setup from specified file.

@end table