diff options
Diffstat (limited to 'dmake/dbug/dbug/dbug.txt')
-rwxr-xr-x | dmake/dbug/dbug/dbug.txt | 1452 |
1 files changed, 1452 insertions, 0 deletions
diff --git a/dmake/dbug/dbug/dbug.txt b/dmake/dbug/dbug/dbug.txt new file mode 100755 index 000000000000..ec032f61ebff --- /dev/null +++ b/dmake/dbug/dbug/dbug.txt @@ -0,0 +1,1452 @@ + + + + + + + D B U G + + C Program Debugging Package + + by + Fred Fish + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - 1 - + + + + + + DBUG User Manual October 29, 1986 + + + + INTRODUCTION + + + Almost every program development environment worthy of + the name provides some sort of debugging facility. Usually + this takes the form of a program which is capable of + controlling execution of other programs and examining the + internal state of other executing programs. These types of + programs will be referred to as external debuggers since the + debugger is not part of the executing program. Examples of + this type of debugger include the adb and sdb debuggers + provided with the UNIX1 operating system. + + + One of the problems associated with developing programs + in an environment with good external debuggers is that + developed programs tend to have little or no internal + instrumentation. This is usually not a problem for the + developer since he is, or at least should be, intimately + familiar with the internal organization, data structures, + and control flow of the program being debugged. It is a + serious problem for maintenance programmers, who are + unlikely to have such familiarity with the program being + maintained, modified, or ported to another environment. It + is also a problem, even for the developer, when the program + is moved to an environment with a primitive or unfamiliar + debugger, or even no debugger. + + + On the other hand, dbug is an example of an internal + debugger. Because it requires internal instrumentation of a + program, and its usage does not depend on any special + capabilities of the execution environment, it is always + available and will execute in any environment that the + program itself will execute in. In addition, since it is a + complete package with a specific user interface, all + programs which use it will be provided with similar + debugging capabilities. This is in sharp contrast to other + forms of internal instrumentation where each developer has + their own, usually less capable, form of internal debugger. + In summary, because dbug is an internal debugger it provides + consistency across operating environments, and because it is + available to all developers it provides consistency across + all programs in the same environment. + + + The dbug package imposes only a slight speed penalty on + executing programs, typically much less than 10 percent, and + a modest size penalty, typically 10 to 20 percent. By + defining a specific C preprocessor symbol both of these can + be reduced to zero with no changes required to the source + + ____________________ + + 1. UNIX is a trademark of AT&T Bell Laboratories. + + - 2 - + + + + + + DBUG User Manual October 29, 1986 + + + + code. + + + The following list is a quick summary of the + capabilities of the dbug package. Each capability can be + individually enabled or disabled at the time a program is + invoked by specifying the appropriate command line + arguments. + + o Execution trace showing function level control + flow in a semi-graphically manner using + indentation to indicate nesting depth. + + o Output the values of all, or any subset of, key + internal variables. + + o Limit actions to a specific set of named + functions. + + o Limit function trace to a specified nesting depth. + + o Label each output line with source file name and + line number. + + o Label each output line with name of current + process. + + o Push or pop internal debugging state to allow + execution with built in debugging defaults. + + o Redirect the debug output stream to standard + output (stdout) or a named file. The default + output stream is standard error (stderr). The + redirection mechanism is completely independent of + normal command line redirection to avoid output + conflicts. + + + + + + + + + + + + + + + + + + + + + - 3 - + + + + + + DBUG User Manual October 29, 1986 + + + + PRIMITIVE DEBUGGING TECHNIQUES + + + Internal instrumentation is already a familiar concept + to most programmers, since it is usually the first debugging + technique learned. Typically, "print statements" are + inserted in the source code at interesting points, the code + is recompiled and executed, and the resulting output is + examined in an attempt to determine where the problem is. + + The procedure is iterative, with each iteration yielding + more and more output, and hopefully the source of the + problem is discovered before the output becomes too large to + deal with or previously inserted statements need to be + removed. Figure 1 is an example of this type of primitive + debugging technique. + + + + #include <stdio.h> + + main (argc, argv) + int argc; + char *argv[]; + { + printf ("argv[0] = %d\n", argv[0]); + /* + * Rest of program + */ + printf ("== done ==\n"); + } + + + Figure 1 + Primitive Debugging Technique + + + + + + Eventually, and usually after at least several + iterations, the problem will be found and corrected. At + this point, the newly inserted print statements must be + dealt with. One obvious solution is to simply delete them + all. Beginners usually do this a few times until they have + to repeat the entire process every time a new bug pops up. + The second most obvious solution is to somehow disable the + output, either through the source code comment facility, + creation of a debug variable to be switched on or off, or by + using the C preprocessor. Figure 2 is an example of all + three techniques. + + + + + + - 4 - + + + + + + DBUG User Manual October 29, 1986 + + + + #include <stdio.h> + + int debug = 0; + + main (argc, argv) + int argc; + char *argv[]; + { + /* printf ("argv = %x\n", argv) */ + if (debug) printf ("argv[0] = %d\n", argv[0]); + /* + * Rest of program + */ + #ifdef DEBUG + printf ("== done ==\n"); + #endif + } + + + Figure 2 + Debug Disable Techniques + + + + + + Each technique has its advantages and disadvantages + with respect to dynamic vs static activation, source code + overhead, recompilation requirements, ease of use, program + readability, etc. Overuse of the preprocessor solution + quickly leads to problems with source code readability and + maintainability when multiple #ifdef symbols are to be + defined or undefined based on specific types of debug + desired. The source code can be made slightly more readable + by suitable indentation of the #ifdef arguments to match the + indentation of the code, but not all C preprocessors allow + this. The only requirement for the standard UNIX C + preprocessor is for the '#' character to appear in the first + column, but even this seems like an arbitrary and + unreasonable restriction. Figure 3 is an example of this + usage. + + + + + + + + + + + + + + + + - 5 - + + + + + + DBUG User Manual October 29, 1986 + + + + #include <stdio.h> + + main (argc, argv) + int argc; + char *argv[]; + { + # ifdef DEBUG + printf ("argv[0] = %d\n", argv[0]); + # endif + /* + * Rest of program + */ + # ifdef DEBUG + printf ("== done ==\n"); + # endif + } + + + Figure 3 + More Readable Preprocessor Usage + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - 6 - + + + + + + DBUG User Manual October 29, 1986 + + + + FUNCTION TRACE EXAMPLE + + + We will start off learning about the capabilities of + the dbug package by using a simple minded program which + computes the factorial of a number. In order to better + demonstrate the function trace mechanism, this program is + implemented recursively. Figure 4 is the main function for + this factorial program. + + + + #include <stdio.h> + /* User programs should use <local/dbug.h> */ + #include "dbug.h" + + int main (argc, argv) + int argc; + char *argv[]; + { + register int result, ix; + extern int factorial (), atoi (); + + DBUG_ENTER ("main"); + DBUG_PROCESS (argv[0]); + for (ix = 1; ix < argc && argv[ix][0] == '-'; ix++) { + switch (argv[ix][1]) { + case '#': + DBUG_PUSH (&(argv[ix][2])); + break; + } + } + for (; ix < argc; ix++) { + DBUG_PRINT ("args", ("argv[%d] = %s", ix, argv[ix])); + result = factorial (atoi (argv[ix])); + printf ("%d\n", result); + } + DBUG_RETURN (0); + } + + + Figure 4 + Factorial Program Mainline + + + + + + The main function is responsible for processing any + command line option arguments and then computing and + printing the factorial of each non-option argument. + + First of all, notice that all of the debugger functions + are implemented via preprocessor macros. This does not + + + - 7 - + + + + + + DBUG User Manual October 29, 1986 + + + + detract from the readability of the code and makes disabling + all debug compilation trivial (a single preprocessor symbol, + DBUG_OFF, forces the macro expansions to be null). + + Also notice the inclusion of the header file dbug.h + from the local header file directory. (The version included + here is the test version in the dbug source distribution + directory). This file contains all the definitions for the + debugger macros, which all have the form DBUG_XX...XX. + + + The DBUG_ENTER macro informs that debugger that we have + entered the function named main. It must be the very first + "executable" line in a function, after all declarations and + before any other executable line. The DBUG_PROCESS macro is + generally used only once per program to inform the debugger + what name the program was invoked with. The DBUG_PUSH macro + modifies the current debugger state by saving the previous + state and setting a new state based on the control string + passed as its argument. The DBUG_PRINT macro is used to + print the values of each argument for which a factorial is + to be computed. The DBUG_RETURN macro tells the debugger + that the end of the current function has been reached and + returns a value to the calling function. All of these + macros will be fully explained in subsequent sections. + + To use the debugger, the factorial program is invoked + with a command line of the form: + + factorial -#d:t 1 2 3 + + The main function recognizes the "-#d:t" string as a + debugger control string, and passes the debugger arguments + ("d:t") to the dbug runtime support routines via the + DBUG_PUSH macro. This particular string enables output from + the DBUG_PRINT macro with the 'd' flag and enables function + tracing with the 't' flag. The factorial function is then + called three times, with the arguments "1", "2", and "3". + Note that the DBUG_PRINT takes exactly two arguments, with + the second argument (a format string and list of printable + values) enclosed in parenthesis. + + Debug control strings consist of a header, the "-#", + followed by a colon separated list of debugger arguments. + Each debugger argument is a single character flag followed + by an optional comma separated list of arguments specific to + the given flag. Some examples are: + + -#d:t:o + -#d,in,out:f,main:F:L + + Note that previously enabled debugger actions can be + disabled by the control string "-#". + + + + - 8 - + + + + + + DBUG User Manual October 29, 1986 + + + + The definition of the factorial function, symbolized as + "N!", is given by: + + N! = N * N-1 * ... 2 * 1 + + Figure 5 is the factorial function which implements this + algorithm recursively. Note that this is not necessarily + the best way to do factorials and error conditions are + ignored completely. + + + + #include <stdio.h> + /* User programs should use <local/dbug.h> */ + #include "dbug.h" + + int factorial (value) + register int value; + { + DBUG_ENTER ("factorial"); + DBUG_PRINT ("find", ("find %d factorial", value)); + if (value > 1) { + value *= factorial (value - 1); + } + DBUG_PRINT ("result", ("result is %d", value)); + DBUG_RETURN (value); + } + + + Figure 5 + Factorial Function + + + + + + One advantage (some may not consider it so) to using + the dbug package is that it strongly encourages fully + structured coding with only one entry and one exit point in + each function. Multiple exit points, such as early returns + to escape a loop, may be used, but each such point requires + the use of an appropriate DBUG_RETURN or DBUG_VOID_RETURN + macro. + + + To build the factorial program on a UNIX system, + compile and link with the command: + + cc -o factorial main.c factorial.c -ldbug + + The "-ldbug" argument tells the loader to link in the + runtime support modules for the dbug package. Executing the + factorial program with a command of the form: + + + + - 9 - + + + + + + DBUG User Manual October 29, 1986 + + + + factorial 1 2 3 4 5 + + generates the output shown in figure 6. + + + + 1 + 2 + 6 + 24 + 120 + Figure 6 + factorial 1 2 3 4 5 + + + + + + Function level tracing is enabled by passing the + debugger the 't' flag in the debug control string. Figure 7 + is the output resulting from the command + "factorial -#t:o 3 2". + + + + | >factorial + | | >factorial + | | <factorial + | <factorial + 2 + | >factorial + | | >factorial + | | | >factorial + | | | <factorial + | | <factorial + | <factorial + 6 + <main + + + Figure 7 + factorial -#t:o 3 2 + + + + + + Each entry to or return from a function is indicated by + '>' for the entry point and '<' for the exit point, + connected by vertical bars to allow matching points to be + easily found when separated by large distances. + + + This trace output indicates that there was an initial + + + - 10 - + + + + + + DBUG User Manual October 29, 1986 + + + + call to factorial from main (to compute 2!), followed by a + single recursive call to factorial to compute 1!. The main + program then output the result for 2! and called the + factorial function again with the second argument, 3. + Factorial called itself recursively to compute 2! and 1!, + then returned control to main, which output the value for 3! + and exited. + + + Note that there is no matching entry point "main>" for + the return point "<main" because at the time the DBUG_ENTER + macro was reached in main, tracing was not enabled yet. It + was only after the macro DBUG_PUSH was executing that + tracing became enabled. This implies that the argument list + should be processed as early as possible since all code + preceding the first call to DBUG_PUSH is essentially + invisible to dbug (this can be worked around by inserting a + temporary DBUG_PUSH(argv[1]) immediately after the + DBUG_ENTER("main") macro. + + + One last note, the trace output normally comes out on + the standard error. Since the factorial program prints its + result on the standard output, there is the possibility of + the output on the terminal being scrambled if the two + streams are not synchronized. Thus the debugger is told to + write its output on the standard output instead, via the 'o' + flag character. Note that no 'o' implies the default + (standard error), a 'o' with no arguments means standard + output, and a 'o' with an argument means used the named + file. I.E, "factorial -#t:o,logfile 3 2" would write the + trace output in "logfile". Because of UNIX implementation + details, programs usually run faster when writing to stdout + rather than stderr, though this is not a prime consideration + in this example. + + + + + + + + + + + + + + + + + + + + + + - 11 - + + + + + + DBUG User Manual October 29, 1986 + + + + USE OF DBUG_PRINT MACRO + + + The mechanism used to produce "printf" style output is + the DBUG_PRINT macro. + + + To allow selection of output from specific macros, the + first argument to every DBUG_PRINT macro is a dbug keyword. + When this keyword appears in the argument list of the 'd' + flag in a debug control string, as in + "-#d,keyword1,keyword2,...:t", output from the corresponding + macro is enabled. The default when there is no 'd' flag in + the control string is to enable output from all DBUG_PRINT + macros. + + + Typically, a program will be run once, with no keywords + specified, to determine what keywords are significant for + the current problem (the keywords are printed in the macro + output line). Then the program will be run again, with the + desired keywords, to examine only specific areas of + interest. + + + The second argument to a DBUG_PRINT macro is a standard + printf style format string and one or more arguments to + print, all enclosed in parenthesis so that they collectively + become a single macro argument. This is how variable + numbers of printf arguments are supported. Also note that + no explicit newline is required at the end of the format + string. As a matter of style, two or three small DBUG_PRINT + macros are preferable to a single macro with a huge format + string. Figure 8 shows the output for default tracing and + debug. + + + + + + + + + + + + + + + + + + + + + + - 12 - + + + + + + DBUG User Manual October 29, 1986 + + + + | args: argv[2] = 3 + | >factorial + | | find: find 3 factorial + | | >factorial + | | | find: find 2 factorial + | | | >factorial + | | | | find: find 1 factorial + | | | | result: result is 1 + | | | <factorial + | | | result: result is 2 + | | <factorial + | | result: result is 6 + | <factorial + 6 + <main + + + Figure 8 + factorial -#d:t:o 3 + + + + + + The output from the DBUG_PRINT macro is indented to + match the trace output for the function in which the macro + occurs. When debugging is enabled, but not trace, the + output starts at the left margin, without indentation. + + + To demonstrate selection of specific macros for output, + figure 9 shows the result when the factorial program is + invoked with the debug control string "-#d,result:o". + + + + factorial: result: result is 1 + factorial: result: result is 2 + factorial: result: result is 6 + factorial: result: result is 24 + 24 + Figure 9 + factorial -#d,result:o 4 + + + + + + It is sometimes desirable to restrict debugging and + trace actions to a specific function or list of functions. + This is accomplished with the 'f' flag character in the + debug control string. Figure 10 is the output of the + factorial program when run with the control string + "-#d:f,factorial:F:L:o". The 'F' flag enables printing of + + + - 13 - + + + + + + DBUG User Manual October 29, 1986 + + + + the source file name and the 'L' flag enables printing of + the source file line number. + + + + factorial.c: 9: factorial: find: find 3 factorial + factorial.c: 9: factorial: find: find 2 factorial + factorial.c: 9: factorial: find: find 1 factorial + factorial.c: 13: factorial: result: result is 1 + factorial.c: 13: factorial: result: result is 2 + factorial.c: 13: factorial: result: result is 6 + 6 + + + Figure 10 + factorial -#d:f,factorial:F:L:o 3 + + + + + + The output in figure 10 shows that the "find" macro is + in file "factorial.c" at source line 8 and the "result" + macro is in the same file at source line 12. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - 14 - + + + + + + DBUG User Manual October 29, 1986 + + + + SUMMARY OF MACROS + + + This section summarizes the usage of all currently + defined macros in the dbug package. The macros definitions + are found in the user include file dbug.h from the standard + include directory. + + + + DBUG_ENTER Used to tell the runtime support module + the name of the function being entered. + The argument must be of type "pointer to + character". The DBUG_ENTER macro must + precede all executable lines in the + function just entered, and must come + after all local declarations. Each + DBUG_ENTER macro must have a matching + DBUG_RETURN or DBUG_VOID_RETURN macro at + the function exit points. DBUG_ENTER + macros used without a matching + DBUG_RETURN or DBUG_VOID_RETURN macro + will cause warning messages from the + dbug package runtime support module. + + EX: DBUG_ENTER ("main"); + + DBUG_RETURN Used at each exit point of a function + containing a DBUG_ENTER macro at the + entry point. The argument is the value + to return. Functions which return no + value (void) should use the + DBUG_VOID_RETURN macro. It is an error + to have a DBUG_RETURN or + DBUG_VOID_RETURN macro in a function + which has no matching DBUG_ENTER macro, + and the compiler will complain if the + macros are actually used (expanded). + + EX: DBUG_RETURN (value); + EX: DBUG_VOID_RETURN; + + DBUG_PROCESS Used to name the current process being + executed. A typical argument for this + macro is "argv[0]", though it will be + perfectly happy with any other string. + + EX: DBUG_PROCESS (argv[0]); + + DBUG_PUSH Sets a new debugger state by pushing the + current dbug state onto an internal + stack and setting up the new state using + the debug control string passed as the + macro argument. The most common usage + + + - 15 - + + + + + + DBUG User Manual October 29, 1986 + + + + is to set the state specified by a debug + control string retrieved from the + argument list. Note that the leading + "-#" in a debug control string specified + as a command line argument must not be + passed as part of the macro argument. + The proper usage is to pass a pointer to + the first character after the "-#" + string. + + EX: DBUG_PUSH ((argv[i][2])); + EX: DBUG_PUSH ("d:t"); + EX: DBUG_PUSH (""); + + DBUG_POP Restores the previous debugger state by + popping the state stack. Attempting to + pop more states than pushed will be + ignored and no warning will be given. + The DBUG_POP macro has no arguments. + + EX: DBUG_POP (); + + DBUG_FILE The DBUG_FILE macro is used to do + explicit I/O on the debug output stream. + It is used in the same manner as the + symbols "stdout" and "stderr" in the + standard I/O package. + + EX: fprintf (DBUG_FILE, "Doing my own + I/O!\n"); + + DBUG_EXECUTE The DBUG_EXECUTE macro is used to + execute any arbitrary C code. The first + argument is the debug keyword, used to + trigger execution of the code specified + as the second argument. This macro must + be used cautiously because, like the + DBUG_PRINT macro, it is automatically + selected by default whenever the 'd' + flag has no argument list (I.E., a + "-#d:t" control string). + + EX: DBUG_EXECUTE ("abort", abort ()); + + DBUG_N These macros, where N is in the range + 2-5, are currently obsolete and will be + removed in a future release. Use the + new DBUG_PRINT macro. + + DBUG_PRINT Used to do printing via the "fprintf" + library function on the current debug + stream, DBUG_FILE. The first argument + is a debug keyword, the second is a + format string and the corresponding + + + - 16 - + + + + + + DBUG User Manual October 29, 1986 + + + + argument list. Note that the format + string and argument list are all one + macro argument and must be enclosed in + parenthesis. + + EX: DBUG_PRINT ("eof", ("end of file found")); + EX: DBUG_PRINT ("type", ("type is %x", + type)); + EX: DBUG_PRINT ("stp", ("%x -> %s", stp, + stp -> name)); + + DBUG_SETJMP Used in place of the setjmp() function + to first save the current debugger state + and then execute the standard setjmp + call. This allows to the debugger to + restore it's state when the DBUG_LONGJMP + macro is used to invoke the standard + longjmp() call. Currently all instances + of DBUG_SETJMP must occur within the + same function and at the same function + nesting level. + + EX: DBUG_SETJMP (env); + + DBUG_LONGJMP Used in place of the longjmp() function + to first restore the previous debugger + state at the time of the last + DBUG_SETJMP and then execute the + standard longjmp() call. Note that + currently all DBUG_LONGJMP macros + restore the state at the time of the + last DBUG_SETJMP. It would be possible + to maintain separate DBUG_SETJMP and + DBUG_LONGJMP pairs by having the + debugger runtime support module use the + first argument to differentiate the + pairs. + + EX: DBUG_LONGJMP (env,val); + + + + + + + + + + + + + + + + + + - 17 - + + + + + + DBUG User Manual October 29, 1986 + + + + DEBUG CONTROL STRING + + + The debug control string is used to set the state of + the debugger via the DBUG_PUSH macro. This section + summarizes the currently available debugger options and the + flag characters which enable or disable them. Argument + lists enclosed in '[' and ']' are optional. + + + d[,keywords] Enable output from macros with + specified keywords. A null list of + keywords implies that all keywords are + selected. + + D[,time] Delay for specified time after each + output line, to let output drain. + Time is given in tenths of a second + (value of 10 is one second). Default + is zero. + + f[,functions] Limit debugger actions to the + specified list of functions. A null + list of functions implies that all + functions are selected. + + F Mark each debugger output line with + the name of the source file containing + the macro causing the output. + + L Mark each debugger output line with + the source file line number of the + macro causing the output. + + n Mark each debugger output line with + the current function nesting depth. + + N Sequentially number each debugger + output line starting at 1. This is + useful for reference purposes when + debugger output is interspersed with + program output. + + o[,file] Redirect the debugger output stream to + the specified file. The default + output stream is stderr. A null + argument list causes output to be + redirected to stdout. + + p[,processes] Limit debugger actions to the + specified processes. A null list + implies all processes. This is useful + for processes which run child + processes. Note that each debugger + + + - 18 - + + + + + + DBUG User Manual October 29, 1986 + + + + output line can be marked with the + name of the current process via the + 'P' flag. The process name must match + the argument passed to the + DBUG_PROCESS macro. + + P Mark each debugger output line with + the name of the current process. Most + useful when used with a process which + runs child processes that are also + being debugged. Note that the parent + process must arrange for the debugger + control string to be passed to the + child processes. + + r Used in conjunction with the DBUG_PUSH + macro to reset the current indentation + level back to zero. Most useful with + DBUG_PUSH macros used to temporarily + alter the debugger state. + + t[,N] Enable function control flow tracing. + The maximum nesting depth is specified + by N, and defaults to 200. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - 19 - + + + + + + DBUG User Manual October 29, 1986 + + + + HINTS AND MISCELLANEOUS + + + One of the most useful capabilities of the dbug package + is to compare the executions of a given program in two + different environments. This is typically done by executing + the program in the environment where it behaves properly and + saving the debugger output in a reference file. The program + is then run with identical inputs in the environment where + it misbehaves and the output is again captured in a + reference file. The two reference files can then be + differentially compared to determine exactly where execution + of the two processes diverges. + + + A related usage is regression testing where the + execution of a current version is compared against + executions of previous versions. This is most useful when + there are only minor changes. + + + It is not difficult to modify an existing compiler to + implement some of the functionality of the dbug package + automatically, without source code changes to the program + being debugged. In fact, such changes were implemented in a + version of the Portable C Compiler by the author in less + than a day. However, it is strongly encouraged that all + newly developed code continue to use the debugger macros for + the portability reasons noted earlier. The modified + compiler should be used only for testing existing programs. + + + + + + + + + + + + + + + + + + + + + + + + + + + - 20 - + + + + + + DBUG User Manual October 29, 1986 + + + + CAVEATS + + + The dbug package works best with programs which have + "line oriented" output, such as text processors, general + purpose utilities, etc. It can be interfaced with screen + oriented programs such as visual editors by redefining the + appropriate macros to call special functions for displaying + the debugger results. Of course, this caveat is not + applicable if the debugger output is simply dumped into a + file for post-execution examination. + + + Programs which use memory allocation functions other + than malloc will usually have problems using the standard + dbug package. The most common problem is multiply allocated + memory. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - 21 - + + + + + + + + + D B U G + C Program Debugging Package + + by + Fred Fish + + + + ABSTRACT + + + This document introduces dbug, a macro based C debugging + package which has proven to be a very flexible and useful + tool for debugging, testing, and porting C programs. + + + All of the features of the dbug package can be enabled + or disabled dynamically at execution time. This means that + production programs will run normally when debugging is not + enabled, and eliminates the need to maintain two separate + versions of a program. + + + Many of the things easily accomplished with + conventional debugging tools, such as symbolic debuggers, + are difficult or impossible with this package, and vice + versa. Thus the dbug package should not be thought of as a + replacement or substitute for other debugging tools, but + simply as a useful addition to the program development and + maintenance environment. + + + + + + + + + + + + + + + + + + + + + + + + + + + + - 22 - + + |