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.




No comments:

Post a Comment