allbery@uunet.UU.NET (Brandon S. Allbery - comp.sources.misc) (07/22/89)
Posting-number: Volume 7, Issue 98 Submitted-by: kap121%ztivax@ztivax.siemens.com (Thomas Oeser) Archive-name: dbug-man [[Note: these are neither a patch to nor an official part of the DBUG package. ++bsa]] enclosed you find two man pages for the recently distributed DBUG package. I've picked up some information found in the source files and user's documentation and put them together to the man pages. I hope this is a start to make a more complete and accurate version of them. Thomas Oeser ------------------------------------------------------------------------------ ARPA: kap121@ztivax.siemens.com UUCP: kap121@ztivax.uucp (may work only in Europe...) Postal mail: Siemens AG, K Sys Ap 121, Otto-Hahn-Ring 6, P.O. Box 830951, D-8000 Munich 83, West Germany Phone: + 49 (89) 636-47537 FAX: + 49 (89) 636-41477 Disclaimer: The opinions expressed are my own, and should not be attributed to anyone else living or dead. ------------------------------------------------------------------------------ #---------- cut here ---------- cut here ----------- cut here ----------------- #! /bin/sh # This is a shell archive. Remove anything before this line, then feed it # into a shell via "sh file" or similar. To overwrite existing files, # type "sh file -c". # The tool that generated this appeared in the comp.sources.unix newsgroup; # send mail to comp-sources-unix@uunet.uu.net if you want that tool. # If this archive is complete, you will see the following message at the end: # "End of shell archive." # Contents: analyze.man dbug.man # Wrapped by email@perlach on Thu Jul 20 09:10:09 1989 PATH=/bin:/usr/bin:/usr/ucb ; export PATH if test -f 'analyze.man' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'analyze.man'\" else echo shar: Extracting \"'analyze.man'\" \(1714 characters\) sed "s/^X//" >'analyze.man' <<'END_OF_FILE' X.\" SCCSID = @(#)analyze.man 1.1 X.\" X.TH ANALYZE 1L "89/07/20" "K Sys Ap 121" X.SH NAME Xanalyze \- analyzes the profile file written out by the dbug Xroutines with profiling enabled. X.SH SYNOPSIS X\fIanalyze\fP [-v] [profileFile] X.ad X.SH DESCRIPTION X\fIAnalyze\fP will read an trace file created by the dbug package X(when run with traceing enabled). It will then produce a Xsummary on standard output listing the name of each traced Xfunction, the number of times it was called, the percentage Xof total calls, the time spent executing the function, the Xproportion of the total time and the 'importance'. The last Xis a metric which is obtained by multiplying the proportions Xof calls and the proportions of time for each function. The Xgreater the importance, the more likely it is that a speedup Xcould be obtained by reducing the time taken by that function. X.PP XNote that the timing values that you obtain are only rough Xmeasures. The overhead of the dbug package is included Xwithin. However, there is no need to link in special profiled Xlibraries and the like. X.SH OPTIONS X\fIAnnalize\fP accepts the following command line options: X.TP 16 X-v XIf this option is specified, the output of this program will be a verbose Xtable. By default, the output of this program will look very similar to XUnix profiler. X.TP 16 XprofileFile XSpecifies the the name of file containing the input data to be examined X(default: dbugmon.out). X.SH USAGE XThis should be easy :-). X.SH FILES Xdbugmon.out X.SH "SEE ALSO" Xdbug(3L) X.SH ENVIRONMENT Xnone X.SH BUGS XThere still are some. X.SH COPYRIGHT Xnone X.SH AUTHORS XFred Fish, Binayak Banerjee X.br XEnhanced Software Technologies, Tempe, AZ X.br Xasuvax!mcdphx!estinc!fnf, seismo!bpa!sjuvax!bbanerje END_OF_FILE echo shar: NEWLINE appended to \"'analyze.man'\" if test 1715 -ne `wc -c <'analyze.man'`; then echo shar: \"'analyze.man'\" unpacked with wrong size! fi # end of 'analyze.man' fi if test -f 'dbug.man' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'dbug.man'\" else echo shar: Extracting \"'dbug.man'\" \(12580 characters\) sed "s/^X//" >'dbug.man' <<'END_OF_FILE' X.\" SCCSID = @(#)dbug.man 1.1 X.\" X.TH DBUG 3L "89/07/20" "K Sys Ap 121" X.SH NAME Xdbug \- a toolset for internal debugging of C programs. X.ad X.SH SYNOPSIS XNote, the following "functions" are C macros. Therefore, the description of Xthe parameters are not necessarily correct C. The intention is, to describe as Xclose as possible but shortly what type of "data" can be used for the Xparameters of the macros. X.PP X#include <dbug.h> X.PP X\fIDBUG_ENTER\fP ( aName ) X.RS 6 Xchar * aName; X.RS -6 X.PP X\fIDBUG_RETURN\fP ( aValue ) X.RS 6 Xint aValue; X.RS -6 X.PP X\fIDBUG_VOID_RETURN\fP X.PP X\fIDBUG_PRINT\fP ( aLabelString, (thePrintfParameters) ) X.RS 6 Xchar * aLabelString; X.br XParameterList thePrintfParameters; X.RS -6 X.PP X\fIDBUG_PROCESS\fP ( aName ) X.RS 6 Xchar * aName; X.RS -6 X.PP X\fIDBUG_PUSH\fP ( aDbugOptionString ) X.RS 6 Xchar * aDbugOptionString; X.RS -6 X.PP X\fIDBUG_POP\fP () X.PP X\fIDBUG_FILE\fP X.PP X\fIDBUG_EXECUTE\fP ( aLabelString, someCode ) X.RS 6 Xchar * aLabelString; X.br XC-Code someCode; X.RS -6 X.PP X\fIDBUG_SETJMP\fP ( env ) X.RS 6 Xjmp_buf env; X.RS -6 X.PP X\fIDBUG_LONGJMP\fP ( env, val ) X.RS 6 Xjmp_buf env; X.br Xint val; X.RS -6 X.SH DESCRIPTION X\fIDbug\fP is Xa macro based C internal debugging Xpackage which has proven to be a very flexible and useful tool Xfor debugging, testing, and porting C programs. X.PP XInternal debugging are typically "print statements" included into the program Xsource. \fIDbug\fP provides for enhanced capabilities to do so. In addition Xeach capability can be individually enabled or disabled at the time a program Xis invoked by specifying the appropriate command line arguments. X.PP XSo, all of the features of the X.I dbug Xpackage can be enabled or disabled dynamically at execution time. XThis means that production programs will run normally when Xdebugging is not enabled, and eliminates the need to maintain two Xseparate versions of a program. X.PP XThe following specifies a summary of the \fIdbug\fP capabilities: X.TP 3 X- XExecution trace showing function level control flow in a Xsemi-graphically manner using indentation to indicate nesting Xdepth. X.TP 3 X- XOutput the values of all, or any subset of, key internal variables. X.TP 3 X- XLimit actions to a specific set of named functions. X.TP 3 X- XLimit function trace to a specified nesting depth. X.TP 3 X- XLabel each output line with source file name and line number. X.TP 3 X- XLabel each output line with name of current process. X.TP 3 X- XPush or pop internal debugging state to allow execution with Xbuilt in debugging defaults. X.TP 3 X- XRedirect the debug output stream to standard output (stdout) Xor a named file. XThe default output stream is standard error (stderr). X.PP XMany of the things easily accomplished with conventional debugging Xtools, such as symbolic debuggers, are difficult or impossible with this Xpackage, and vice versa. XThus the X.I dbug Xpackage should X.I not Xbe thought of as a replacement or substitute for Xother debugging tools, but simply as a useful X.I addition Xto the Xprogram development and maintenance environment. X.PP XThe X.I dbug Xpackage imposes only a slight speed penalty on executing Xprograms, typically much less than 10 percent, and a modest size Xpenalty, typically 10 to 20 percent. XBy defining a specific C preprocessor symbol both of these Xcan be reduced to zero with no changes required to the Xsource code. X.PP XNotice, that all of the debugger functions are implemented Xvia preprocessor macros. XThis does not detract from the readability of the code and makes disabling Xall debug compilation trivial (a single preprocessor symbol, X.B DBUG_OFF , Xforces the macro expansions to be null). X.SH "SUMMARY OF MACROS" XThis summarizes the usage of all currently defined macros Xin the X.I dbug Xpackage. XThe macros definitions are found in the user include file X.B dbug.h Xfrom the standard include directory. X.TP 15 XDBUG_ENTER XUsed to tell the runtime support module the name of the function Xbeing entered. XThe argument must be of type "pointer to character". XThe XDBUG_ENTER Xmacro must precede all executable lines in the Xfunction just entered, and must come after all local declarations. XEach XDBUG_ENTER Xmacro must have a matching XDBUG_RETURN Xor XDBUG_VOID_RETURN Xmacro Xat the function exit points. XDBUG_ENTER Xmacros used without a matching XDBUG_RETURN Xor XDBUG_VOID_RETURN Xmacro Xwill cause warning messages from the X.I dbug Xpackage runtime support module. X.br X.sp XEX:\ DBUG_ENTER\ ("main"); X.TP 15 XDBUG_RETURN XUsed at each exit point of a function containing a XDBUG_ENTER Xmacro Xat the entry point. XThe argument is the value to return. XFunctions which return no value (void) should use the XDBUG_VOID_RETURN Xmacro. XIt Xis an error to have a XDBUG_RETURN Xor XDBUG_VOID_RETURN Xmacro in a function Xwhich has no matching XDBUG_ENTER Xmacro, and the compiler will complain Xif the macros are actually used (expanded). X.br X.sp XEX:\ DBUG_RETURN\ (value); X.br XEX:\ DBUG_VOID_RETURN; X.TP 15 XDBUG_PROCESS XUsed to name the current process being executed. XA typical argument for this macro is "argv[0]", though Xit will be perfectly happy with any other string. X.br X.sp XEX:\ DBUG_PROCESS\ (argv[0]); X.TP 15 XDBUG_PUSH XSets a new debugger state by pushing the current X.B dbug Xstate onto an Xinternal stack and setting up the new state using the debug control Xstring passed as the macro argument. XThe most common usage is to set the state specified by a debug Xcontrol string retrieved from the argument list. XNote that the leading "\-#" in a debug control string specified Xas a command line argument must X.B not Xbe passed as part of the macro argument. XThe proper usage is to pass a pointer to the first character X.B after Xthe "\-#" string. X.br X.sp XEX:\ DBUG_PUSH\ (\&(argv[i][2])); X.br XEX:\ DBUG_PUSH\ ("d:t"); X.br XEX:\ DBUG_PUSH\ (" "); X.TP 15 XDBUG_POP XRestores the previous debugger state by popping the state stack. XAttempting to pop more states than pushed will be ignored and no Xwarning will be given. XThe XDBUG_POP Xmacro has no arguments. X.br X.sp XEX:\ DBUG_POP\ (); X.TP 15 XDBUG_FILE XThe XDBUG_FILE Xmacro is used to do explicit I/O on the debug output Xstream. XIt is used in the same manner as the symbols "stdout" and "stderr" Xin the standard I/O package. X.br X.sp XEX:\ fprintf\ (DBUG_FILE,\ "Doing\ my\ own\ I/O!\\n"); X.TP 15 XDBUG_EXECUTE XThe DBUG_EXECUTE macro is used to execute any arbitrary C code. XThe first argument is the debug keyword, used to trigger execution Xof the code specified as the second argument. XThis macro must be used cautiously because, like the XDBUG_PRINT Xmacro, Xit is automatically selected by default whenever the 'd' flag has Xno argument list (I.E., a "\-#d:t" control string). X.br X.sp XEX:\ DBUG_EXECUTE\ ("abort",\ abort\ ()); X.TP 15 XDBUG_N XThese macros, where N is in the range 2\-5, are currently obsolete Xand will be removed in a future release. XUse the new DBUG_PRINT macro. X.TP 15 XDBUG_PRINT XUsed to do printing via the "fprintf" library function on the Xcurrent debug stream, XDBUG_FILE. XThe first argument is a debug keyword, the second is a format string Xand the corresponding argument list. XNote that the format string and argument list are all one macro argument Xand X.B must Xbe enclosed in parenthesis. X.br X.sp XEX:\ DBUG_PRINT\ ("eof",\ ("end\ of\ file\ found")); X.br XEX:\ DBUG_PRINT\ ("type",\ ("type\ is\ %x",\ type)); X.br XEX:\ DBUG_PRINT\ ("stp",\ ("%x\ \->\ %s",\ stp,\ stp\ \->\ name)); X.TP 15 XDBUG_SETJMP XUsed in place of the setjmp() function to first save the current Xdebugger state and then execute the standard setjmp call. XThis allows the debugger to restore its state when the XDBUG_LONGJMP macro is used to invoke the standard longjmp() call. XCurrently all instances of DBUG_SETJMP must occur within the Xsame function and at the same function nesting level. X.br X.sp XEX:\ DBUG_SETJMP\ (env); X.TP 15 XDBUG_LONGJMP XUsed in place of the longjmp() function to first restore the Xprevious debugger state at the time of the last DBUG_SETJMP Xand then execute the standard longjmp() call. XNote that currently all DBUG_LONGJMP macros restore the state Xat the time of the last DBUG_SETJMP. XIt would be possible to maintain separate DBUG_SETJMP and DBUG_LONGJMP Xpairs by having the debugger runtime support module use the first Xargument to differentiate the pairs. X.br X.sp XEX:\ DBUG_LONGJMP\ (env,val); X.SH "DEBUG CONTROL STRING" XThe debug control string is used to control the "behaviour" of the dbug macros, Xwhen running the application. The \fIdebug control string\fP is passed to the X\fIdbug\fP package via the \fIDBUG_PUSH()\fP macro (note, that the parameter of Xthis macro may be the value of a program argument; see example above). X.PP XThe following list summarizes the currently available debugger options Xand the flag characters which enable or disable them. Debugger options may be Xconcatenated to a \fIdebug control string\fP using the ":" (colon) as a Xseperator (e.g., <option1>:<option2>:...:<optionN>). X.PP XArgument lists enclosed in '[' and ']' are optional. X.TP 15 Xd[,keywords] XEnable output from macros with specified keywords. XA null list of keywords implies that all keywords are selected. X.TP 15 XD[,time] XDelay for specified time after each output line, to let output drain. XTime is given in tenths of a second (value of 10 is one second). XDefault is zero. X.TP 15 Xf[,functions] XLimit debugger actions to the specified list of functions. XA null list of functions implies that all functions are selected. X.TP 15 XF XMark each debugger output line with the name of the source file Xcontaining the macro causing the output. X.TP 15 Xg XTurn on machine independent profiling. XA profiling data collection file, named dbugmon.out, will be written Xfor postprocessing by the "analyze(1L)" program. XThe accuracy of this feature is relatively unknown at this time. X.TP 15 Xi XIdentify the process emitting each line of debug or trace output Xwith the process id for that process. X.TP 15 XL XMark each debugger output line with the source file line number of Xthe macro causing the output. X.TP 15 Xn XMark each debugger output line with the current function nesting depth. X.TP 15 XN XSequentially number each debugger output line starting at 1. XThis is useful for reference purposes when debugger output is Xinterspersed with program output. X.TP 15 Xo[,file] XRedirect the debugger output stream to the specified file. XThe default output stream is stderr. XA null argument list causes output to be redirected to stdout. X.TP 15 Xp[,processes] XLimit debugger actions to the specified processes. XA null list implies all processes. XThis is useful for processes which run child processes. XNote that each debugger output line can be marked with the name of Xthe current process via the 'P' flag. XThe process name must match the argument passed to the X.B DBUG_PROCESS Xmacro. X.TP 15 XP XMark each debugger output line with the name of the current process Xfrom argv[0]. XMost useful when used with a process which runs child processes that Xare also being debugged. XNote that the parent process must arrange for the debugger control Xstring to be passed to the child processes. X.TP 15 Xr XUsed in conjunction with the X.B DBUG_PUSH Xmacro to reset the current Xindentation level back to zero. XMost useful with X.B DBUG_PUSH Xmacros used to temporarily alter the Xdebugger state. X.TP 15 Xt[,N] XEnable function control flow tracing. XThe maximum nesting depth is specified by N, and defaults to X200. X.SH USAGE XThe following example shows a very simple use of the \fIdbug\fP facilities. X.PP XFirst, the source code including some \fIdbug\fP statements is given: X.RS 12 X.sp X.nf X#include <stdio.h> X#include <dbug.h> X Xmain (argc, argv) Xint argc; Xchar *argv[]; X{ X int i; X int atoi(); X X DBUG_ENTER ("main"); X DBUG_PROCESS (argv[0]); X X for (i = 1; i < argc && argv[i][0] == '-'; i++) { X switch (argv[i][1]) { X case '#': X DBUG_PUSH (&(argv[i][2])); X break; X } X } X X for (; i < argc; i++) { X DBUG_PRINT ("args", ("argv[%d] = %s", i, argv[i])); X printf ("%F\\n", 1.0/atoi(argv[i])); X } X X DBUG_RETURN (0); X} X.fi X.sp X.RS -12 X.PP XThe following invocation of the program "inverse" compiled from the source Xabove would cause the corresponding outputs: X.RS 12 X.sp X.nf X$ inverse\ \ 2 4 X0.5 X0.25 X X$ inverse -#t\ \ 2 4 X| X0.5 X0.25 X< main X Xinverse -#d:t\ \ 2 4 X| args: argv[2] = 2 X0.5 X| args: argv[3] = 4 X0.25 X< main X.fi X.sp X.RS -12 X.SH FILES X/LocalTools/lib/local/libdbug.a X/LocalTools/include/local/dbug.h X.SH "SEE ALSO" XDBUG Users Manual, analyze(1L) X.SH ENVIRONMENT Xnone X.SH BUGS XThere still are some. X.SH COPYRIGHT Xnone X.SH AUTHORS XFred Fish, Binayak Banerjee X.br XEnhanced Software Technologies, Tempe, AZ X.br Xasuvax!mcdphx!estinc!fnf, seismo!bpa!sjuvax!bbanerje END_OF_FILE echo shar: NEWLINE appended to \"'dbug.man'\" if test 12581 -ne `wc -c <'dbug.man'`; then echo shar: \"'dbug.man'\" unpacked with wrong size! fi # end of 'dbug.man' fi echo shar: End of shell archive. exit 0