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, AND VOTING MACHINES. 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. Installation
is as follows:
./configure
make
make install
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_UNWIND - Display information about stack unwinding.
WAD_DEBUG_SIGNAL - Display information about signal handling.
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 Problems
General:
- WAD does not gracefully recover from errors that corrupt the call
stack (i.e., buffer overlow).
- Errors that destroy the process heap may or may not be recoverable
depending on what has been destroyed.
- WAD does not currently support 64 bit applications on any platform.
Solaris:
- No platform specific issues are known at this time.
Linux:
- The interaction of threads and signals are particularly problematic
on this platform and may cause WAD not to work at all. Here are
some specific thread-based problems:
1. WAD causes the program to crash immediately upon startup.
This appears to be caused by a bug in in the implemenation
of sigaction() and the initialization of signals. There is no
known solution.
2. Programs lock up when an error occurs. This is sometimes
caused by a non-working implementation of sigaltstack().
One solution to this is to set the following environment
variable:
setenv WAD_NOSTACK
in which case the WAD signal handler will use the same
stack as the thread/process that generates the error.
3. WAD just crashes altogether and doesn't seem to do anything.
It appears that some versions of Linux threads do *not*
pass CPU context information correctly to signal handlers
defined in threaded programs. There is no known fix to
this at this time.
6. Language dependent issues
If WAD is linked with a normal C/C++ program, errors simply produce a stack trace
that is printed on standard error.
Python:
WAD tries to raise a Python exception and return. At this time, the exception
merely contains a traceback string. However, in future versions, it may be
possible to access a complete exception object.
Tcl:
WAD returns a Tcl and places the stack trace into the Tcl variable $errorInfo.
The wish shell uses this to dump error information.
Perl:
Perl doesn't seem to have a very well-defined exception handling
mechanism. Standard functions tend to just exit. The WAD handler
produces a C stack trace and produces a Perl stack trace using some
code derived from the sigtrap module.
7. 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
a623fa28bc