7a2f098e57
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@976 626c5289-ae23-0410-ae9c-e8d60b6d4f22
147 lines
5.1 KiB
Text
147 lines
5.1 KiB
Text
WAD (Wrapped Application Debugger)
|
|
|
|
David M. Beazley
|
|
Department of Computer Science
|
|
University of Chicago
|
|
Chicago, IL 60637
|
|
beazley@cs.uchicago.edu
|
|
|
|
Copyright (C) 2001
|
|
University of Chicago
|
|
All Rights Reserved
|
|
|
|
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
!!!!!!!! READ THIS NOW !!!!!!!!
|
|
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
|
THIS IS EXPERIMENTAL UNSUPPORTED SOFTWARE THAT UTILIZES A HORRIBLE MIX
|
|
OF LOW-LEVEL SYSTEMS PROGRAMMING, C, C++, AND ASSEMBLY CODE. IT IS
|
|
NOT PORTABLE, IT HAS NOT BEEN RIGOROUSLY TESTED, AND IT MIGHT NOT WORK
|
|
AT ALL. PLEASE KEEP AWAY FROM SMALL CHILDREN, PETS, NUCLEAR REACTORS,
|
|
AIR-TRAFFIC CONTROL, VOTING MACHINES, AND MEDICAL EQUIPMENT. SIDE
|
|
EFFECTS MAY INCLUDE NAUSEA, VOMITING, AND HEADACHE. OTHER THAN THIS,
|
|
IT'S PERFECTLY SAFE.
|
|
|
|
1. Introduction
|
|
|
|
WAD is an embedded error-recovery mechanism that attempts to convert
|
|
fatal errors such as SIGSEGV, SIGBUS, and SIGFPE into sensible error messages
|
|
and exceptions. It is specifically designed to support scripting language
|
|
environments although it can also be used with stand-alone C programs.
|
|
|
|
The primary goal of this system is to explore alternative approaches
|
|
to mixed scripting-compiled debugging. Feedback is
|
|
welcome. Contributions and modifications are even more welcome.
|
|
|
|
2. Compilation and Installation
|
|
|
|
WAD is not particularly portable (for obvious reasons). At this time,
|
|
only two platforms are supported: SPARC Solaris and i386-Linux. To
|
|
build the Solaris version, type 'make solaris'. To build the Linux
|
|
version, type 'make linux'.
|
|
|
|
The build process creates the following shared libraries:
|
|
|
|
libwad.so - Standalone WAD. Can be linked with C/C++
|
|
programs.
|
|
|
|
libwadpy.so - Python WAD. Can be linked to Python extension
|
|
modules or imported on its own as 'import libwadpy'
|
|
|
|
libwadtcl.so - Tcl WAD. Can be linked to Tcl extension
|
|
modules or loaded as 'load libwadtcl.so'.
|
|
|
|
libwadpl.so - Perl WAD. Can be linked to Perl extension
|
|
modules.
|
|
|
|
To install the libraries, simply type 'make install'. This copies the libraries
|
|
to /usr/local/lib (unless you modify the makefile).
|
|
|
|
Notes:
|
|
|
|
- Not all of these libraries are currently available on all platforms.
|
|
Most development work has taken place on Solaris.
|
|
|
|
- You may need to modify the Makefile to point to the installed locations
|
|
of various scripting language libraries. Eventually this will be
|
|
put under autoconf, but that's for later.
|
|
|
|
- WAD only supports systems with ELF-format executables and stabs
|
|
format debugging tables. This is fairly common on many systems.
|
|
However, it also means that WAD does not work with newer compilers
|
|
and debugging formats such as DWARF2.
|
|
|
|
3. Using WAD
|
|
|
|
WAD has no functional API nor does it have any command line options so
|
|
it's pretty easy to use---simply link the appropriate WAD library with
|
|
your C code. For example:
|
|
|
|
% cc blah.c -lwad
|
|
|
|
Once linked, fatal errors will now produce stack traces. For example:
|
|
|
|
% ./a.out seg
|
|
starting.
|
|
Segmentation fault.
|
|
#2 0x400571eb in __libc_start_main() in 'libc-start.c', line 90
|
|
#1 0x08048b39 in main(argc=0x2,argv=0xbffffce4) in 'debug.c', line 62
|
|
#0 0x080489b3 in seg_crash(n=0x0) in 'debug.c', line 9
|
|
|
|
/r0/beazley/Projects/WAD/Wad/debug.c, line 9
|
|
|
|
int *a = 0;
|
|
if (n > 0) seg_crash(n-1);
|
|
=> *a = 3;
|
|
return 1;
|
|
}
|
|
|
|
|
|
4. Debugging Modes
|
|
|
|
Due to WAD's experimental nature, a number of debugging modes can be set
|
|
through the use of environment variables. These variables control WAD's
|
|
runtime behavior and cause the system to dump debugging information for
|
|
various stages of error recovery.
|
|
|
|
WAD_DEBUG_SEGMENT - Displays information about the virtual memory
|
|
map and mapping of addresses to segments.
|
|
|
|
WAD_DEBUG_SYMBOL - Symbol table mapping.
|
|
|
|
WAD_DEBUG_OBJECT - Loading/Unloading of object files.
|
|
|
|
WAD_DEBUG_FILE - Loading/Unloading of raw files.
|
|
|
|
WAD_DEBUG_HOLD - Freezes WAD before it returns from the signal handler.
|
|
Useful if you need to attach a debugger to WAD itself.
|
|
|
|
WAD_DEBUG_STABS - Display stabs data.
|
|
|
|
WAD_DEBUG_RETURN - Display information about WAD return points.
|
|
|
|
WAD_DEBUG_SYMBOL_SEARCH - Display all symbols in the symbol table that are
|
|
searched.
|
|
|
|
WAD_DEBUG_INIT - Print initialization information.
|
|
|
|
WAD_NOSTACK - Do NOT use an alternative signal handling stack.
|
|
This may be necessary on certain Linux systems when
|
|
threads are being used.
|
|
|
|
WAD_ONESHOT - Disable WAD signal handler after first signal has
|
|
been received.
|
|
|
|
|
|
5. Known Limitations
|
|
|
|
6. Documentation
|
|
|
|
No official documentation exists at this time. However, the Papers directory contains
|
|
two conference papers that describe WAD's design and high-level operation.
|
|
|
|
Dave Beazley
|
|
December 28, 2000
|
|
|
|
|
|
|