summaryrefslogtreecommitdiff
path: root/dmake/dbug/dbug/dbug.txt
diff options
context:
space:
mode:
Diffstat (limited to 'dmake/dbug/dbug/dbug.txt')
-rwxr-xr-xdmake/dbug/dbug/dbug.txt1452
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 -
+
+
generated by cgit v1.2.3 (git 2.39.1) at 2024-05-09 11:46:58 +0000