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.