October 4, 2011

C/C++ dbug library

There are many debug libraries available for C/C++.  Recently I started looking into the "dbug" library created by Fred Fish in 1988 and released to public. You can download the library at source forge .

The library has just one C file: dbug.c and one header file: dbug.h (another header file dbug_long.h has more comments can be used in place of dbug.h)

The concept is that you can turn debug on/off on the fly; enable per-function tracing; and other stuff such as profiling which usually you don't need.

To use it:

First, you initialize it by doing this:

  DBUG_PUSH ("d:t:O:L:");

Then in every function, you begin your function code with:
  DBUG_ENTER ("my_function_name");

End your function with either
   DBUG_VOID_RETURN;

or 

   DBUG_RETURN (0);

if you return integer 0.

To use printf to debug something, use this macro:
   DBUG_PRINT ("info", ("Returned value: %d", ret));
where "info" is your keyword/category of debugs. In DBUG_PUSH, you can use "d,keyword1,keyword2..." to turn on/off a list of categories that you want to debug.

Note that there is a file "example.c" in the root directory of the downloaded package, which shows you how to use the library.

Reference for the controlling string in dbug_push:
this is copied from MySQL document Appendix C

The debug control string is a sequence of colon separated fields as follows:
      <field_1>:<field_2>:<field_N>
Each field consists of a mandatory flag character followed by an optional "," and comma separated list of modifiers:
       flag[,modifier,modifier,...,modifier]

The currently recognized flag characters are:

  • d Enable output from DBUG_ macros for for the current state. May be followed by a list of keywords which selects output only for the DBUG macros with that keyword. A null list of keywords implies output for all macros.
  • D Delay after each debugger output line. The argument is the number of tenths of seconds to delay, subject to machine capabilities. I.E. -#D,20 is delay two seconds.
  • f Limit debugging and/or tracing, and profiling to the list of named functions. Note that a null list will disable all functions. The appropriate "d" or "t" flags must still be given, this flag only limits their actions if they are enabled.
  • F Identify the source file name for each line of debug or trace output.
  • i Identify the process with the pid for each line of debug or trace output.
  • g Enable profiling. Create a file called 'dbugmon.out' containing information that can be used to profile the program. May be followed by a list of keywords that select profiling only for the functions in that list. A null list implies that all functions are considered.
  • L Identify the source file line number for each line of debug or trace output.
  • n Print the current function nesting depth for each line of debug or trace output.
  • N Number each line of dbug output.
  • o Redirect the debugger output stream to the specified file. The default output is stderr.
  • O As O but the file is really flushed between each write. When needed the file is closed and reopened between each write.
  • p Limit debugger actions to specified processes. A process must be identified with the DBUG_PROCESS macro and match one in the list for debugger actions to occur.
  • P Print the current process name for each line of debug or trace output.
  • r When pushing a new state, do not inherit the previous state's function nesting level. Useful when the output is to start at the left margin.
  • S Do function _sanity(_file_,_line_) at each debugged function until _sanity() returns something that differs from 0. (Mostly used with safemalloc)
  • t Enable function call/exit trace lines. May be followed by a list (containing only one modifier) giving a numeric maximum trace level, beyond which no output will occur for either debugging or tracing macros. The default is a compile time option.
Some examples of debug control strings which might appear on a shell command line (the "-#" is typically used to introduce a control string to an application program) are:

                -#d:t
                -#d:f,main,subr1:F:L:t,20
                -#d,input,output,files:n
For convenience, any leading "-#" is stripped off.




1 comment:

  1. I'm rustycar54, who made a comment on the Fred Fish debug macros on the sourceforge page.

    I REALLY liked those macros. I made a performance improvement where I set a flag (boolean) telling the DBUG macros whether or not to even bother checking to see if the tags were set. This made it so that, with no debugging going on, your only added performance hit was an if on a variable and a jump. This allowed me to quash the concerns of the naysayers who were afraid of the overhead of string compares all over the place....

    Anyway, I even managed to turn them into C++ usable macros, but either the code was done as an employee and I didn't have the right to release, or something like that. It would be very good if someone would take that task on...

    Rustycar54

    ReplyDelete