userapps/opensource/net-snmp/include/net-snmp/library/snmp_debug.h

   1 #ifndef SNMP_DEBUG_H
   2 #define SNMP_DEBUG_H
   3
   4 #ifdef __cplusplus
   5 extern          "C" {
   6 #endif
   7
   8     /*
   9      * snmp_debug.h:
  10      *
  11      * - prototypes for snmp debugging routines.
  12      * - easy to use macros to wrap around the functions.  This also provides
  13      * the ability to reove debugging code easily from the applications at
  14      * compile time.
  15      */
  16
  17
  18     /*
  19      * These functions should not be used, if at all possible.  Instead, use
  20      * the macros below.
  21      */
  22 #if HAVE_STDARG_H
  23     void            debugmsg(const char *token, const char *format, ...);
  24     void            debugmsgtoken(const char *token, const char *format,
  25                                   ...);
  26 #else
  27     void            debugmsg(va_alist);
  28     void            debugmsgtoken(va_alist);
  29 #endif
  30     void            debugmsg_oid(const char *token, const oid * theoid,
  31                                  size_t len);
  32     void            debugmsg_var(const char *token,
  33                                  netsnmp_variable_list * var);
  34     void            debugmsg_oidrange(const char *token,
  35                                       const oid * theoid, size_t len,
  36                                       size_t var_subid, oid range_ubound);
  37     void            debugmsg_hex(const char *token, u_char * thedata,
  38                                  size_t len);
  39     void            debugmsg_hextli(const char *token, u_char * thedata,
  40                                     size_t len);
  41     void            debug_indent_add(int amount);
  42     char           *debug_indent(void);
  43
  44     /*
  45      * Use these macros instead of the functions above to allow them to be
  46      * re-defined at compile time to NOP for speed optimization.
  47      *
  48      * They need to be called enclosing all the arguments in a single set of ()s.
  49      * Example:
  50      * DEBUGMSGTL(("token", "debugging of something %s related\n", "snmp"));
  51      *
  52      * Usage:
  53      * All of the functions take a "token" argument that helps determine when
  54      * the output in question should be printed.  See the snmpcmd.1 manual page
  55      * on the -D flag to turn on/off output for a given token on the command line.
  56      *
  57      * DEBUGMSG((token, format, ...)):      equivelent to printf(format, ...)
  58      * (if "token" debugging output
  59      * is requested by the user)
  60      *
  61      * DEBUGMSGT((token, format, ...)):     equivelent to DEBUGMSG, but prints
  62      * "token: " at the beginning of the
  63      * line for you.
  64      *
  65      * DEBUGTRACE                           Insert this token anywhere you want
  66      * tracing output displayed when the
  67      * "trace" debugging token is selected.
  68      *
  69      * DEBUGMSGL((token, format, ...)):     equivelent to DEBUGMSG, but includes
  70      * DEBUGTRACE debugging line just before
  71      * yours.
  72      *
  73      * DEBUGMSGTL((token, format, ...)):    Same as DEBUGMSGL and DEBUGMSGT
  74      * combined.
  75      *
  76      * Important:
  77      * It is considered best if you use DEBUGMSGTL() everywhere possible, as it
  78      * gives the nicest format output and provides tracing support just before
  79      * every debugging statement output.
  80      *
  81      * To print multiple pieces to a single line in one call, use:
  82      *
  83      * DEBUGMSGTL(("token", "line part 1"));
  84      * DEBUGMSG  (("token", " and part 2\n"));
  85      *
  86      * to get:
  87      *
  88      * token: line part 1 and part 2
  89      *
  90      * as debugging output.
  91      */
  92
  93 #ifndef SNMP_NO_DEBUGGING       /* make sure we're wanted */
  94
  95     /*
  96      * define two macros : one macro with, one without,
  97      *                     a test if debugging is enabled.
  98      *
  99      * Generally, use the macro with _DBG_IF_
 100      */
 101
 102 /******************* Start private macros ************************/
 103 #define _DBG_IF_            snmp_get_do_debugging()
 104 #define DEBUGIF(x)         if (_DBG_IF_ && debug_is_token_registered(x) == SNMPERR_SUCCESS)
 105
 106 #define __DBGMSGT(x)     debugmsgtoken x,  debugmsg x
 107
 108 #ifdef  HAVE_CPP_UNDERBAR_FUNCTION_DEFINED
 109 #define __DBGTRACE       __DBGMSGT(("trace","%s(): %s, %d\n",__FUNCTION__,\
 110                                  __FILE__,__LINE__))
 111 #else
 112 #define __DBGTRACE       __DBGMSGT(("trace"," %s, %d\n", __FILE__,__LINE__))
 113 #endif
 114
 115 #define __DBGMSGL(x)     __DBGTRACE, debugmsg x
 116 #define __DBGMSGTL(x)    __DBGTRACE, debugmsgtoken x, debugmsg x
 117 #define __DBGMSGOID(x)     debugmsg_oid x
 118 #define __DBGMSGVAR(x)     debugmsg_var x
 119 #define __DBGMSGOIDRANGE(x) debugmsg_oidrange x
 120 #define __DBGMSGHEX(x)     debugmsg_hex x
 121 #define __DBGMSGHEXTLI(x)  debugmsg_hextli x
 122 #define __DBGINDENT()      debug_indent()
 123 #define __DBGINDENTADD(x)  debug_indent_add(x)
 124 #define __DBGINDENTMORE()  debug_indent_add(2)
 125 #define __DBGINDENTLESS()  debug_indent_add(-2)
 126 #define __DBGPRINTINDENT(token) __DBGMSGTL((token, "%s", __DBGINDENT()))
 127
 128 #define __DBGDUMPHEADER(token,x) \
 129         __DBGPRINTINDENT("dumph_" token); \
 130         debugmsg("dumph_" token,x); \
 131         if (debug_is_token_registered("dumpx" token) == SNMPERR_SUCCESS ||    \
 132             debug_is_token_registered("dumpv" token) == SNMPERR_SUCCESS ||    \
 133             (debug_is_token_registered("dumpx_" token) != SNMPERR_SUCCESS &&  \
 134              debug_is_token_registered("dumpv_" token) != SNMPERR_SUCCESS)) { \
 135             debugmsg("dumph_" token,"\n"); \
 136         } else { \
 137             debugmsg("dumph_" token,"  "); \
 138         } \
 139         __DBGINDENTMORE()
 140
 141 #define __DBGDUMPSECTION(token,x) \
 142         __DBGPRINTINDENT("dumph_" token); \
 143         debugmsg("dumph_" token,x); \
 144         debugmsg("dumph_" token,"\n"); \
 145         __DBGINDENTMORE()
 146
 147 #define __DBGDUMPSETUP(token,buf,len) \
 148         debugmsg("dumpx" token, "dumpx_%s:%s", token, __DBGINDENT()); \
 149         __DBGMSGHEX(("dumpx_" token,buf,len)); \
 150         if (debug_is_token_registered("dumpv" token) == SNMPERR_SUCCESS || \
 151             debug_is_token_registered("dumpv_" token) != SNMPERR_SUCCESS) { \
 152             debugmsg("dumpx_" token,"\n"); \
 153         } else { \
 154             debugmsg("dumpx_" token,"  "); \
 155         } \
 156         debugmsg("dumpv" token, "dumpv_%s:%s", token, __DBGINDENT());
 157
 158 /******************* End   private macros ************************/
 159 /*****************************************************************/
 160
 161 /*****************************************************************/
 162 /********************Start public  macros ************************/
 163
 164 #define DEBUGMSG(x)        do {if (_DBG_IF_) {debugmsg x;} }while(0)
 165 #define DEBUGMSGT(x)       do {if (_DBG_IF_) {__DBGMSGT(x);} }while(0)
 166 #define DEBUGTRACE         do {if (_DBG_IF_) {__DBGTRACE;} }while(0)
 167 #define DEBUGMSGL(x)       do {if (_DBG_IF_) {__DBGMSGL(x);} }while(0)
 168 #define DEBUGMSGTL(x)      do {if (_DBG_IF_) {__DBGMSGTL(x);} }while(0)
 169 #define DEBUGMSGOID(x)     do {if (_DBG_IF_) {__DBGMSGOID(x);} }while(0)
 170 #define DEBUGMSGVAR(x)     do {if (_DBG_IF_) {__DBGMSGVAR(x);} }while(0)
 171 #define DEBUGMSGOIDRANGE(x) do {if (_DBG_IF_) {__DBGMSGOIDRANGE(x);} }while(0)
 172 #define DEBUGMSGHEX(x)     do {if (_DBG_IF_) {__DBGMSGHEX(x);} }while(0)
 173 #define DEBUGMSGHEXTLI(x)  do {if (_DBG_IF_) {__DBGMSGHEXTLI(x);} }while(0)
 174 #define DEBUGINDENT()      do {if (_DBG_IF_) {__DBGINDENT();} }while(0)
 175 #define DEBUGINDENTADD(x)  do {if (_DBG_IF_) {__DBGINDENTADD(x);} }while(0)
 176 #define DEBUGINDENTMORE()  do {if (_DBG_IF_) {__DBGINDENTMORE();} }while(0)
 177 #define DEBUGINDENTLESS()  do {if (_DBG_IF_) {__DBGINDENTLESS();} }while(0)
 178 #define DEBUGPRINTINDENT(token) \
 179         do {if (_DBG_IF_) {__DBGPRINTINDENT(token);} }while(0)
 180
 181
 182 #define DEBUGDUMPHEADER(token,x) \
 183         do {if (_DBG_IF_) {__DBGDUMPHEADER(token,x);} }while(0)
 184
 185 #define DEBUGDUMPSECTION(token,x) \
 186         do {if (_DBG_IF_) {__DBGDUMPSECTION(token,x);} }while(0)
 187
 188 #define DEBUGDUMPSETUP(token,buf,len) \
 189         do {if (_DBG_IF_) {__DBGDUMPSETUP(token,buf,len);} }while(0)
 190
 191 #else                           /* SNMP_NO_DEBUGGING := enable streamlining of the code */
 192
 193 #define DEBUGMSG(x)
 194 #define DEBUGMSGT(x)
 195 #define DEBUGTRACE
 196 #define DEBUGMSGL(x)
 197 #define DEBUGMSGTL(x)
 198 #define DEBUGMSGOID(x)
 199 #define DEBUGMSGVAR(x)
 200 #define DEBUGMSGOIDRANGE(x)
 201 #define DEBUGMSGHEX(x)
 202 #define DEBUGIF(x)        if(0)
 203 #define DEBUGDUMP(t,b,l,p)
 204 #define DEBUGINDENT()
 205 #define DEBUGINDENTMORE()
 206 #define DEBUGINDENTLESS()
 207 #define DEBUGINDENTADD(x)
 208 #define DEBUGMSGHEXTLI(x)
 209 #define DEBUGPRINTINDENT(token)
 210 #define DEBUGDUMPHEADER(token,x)
 211 #define DEBUGDUMPSECTION(token,x)
 212 #define DEBUGDUMPSETUP(token, buf, len)
 213
 214 #endif
 215
 216 #define MAX_DEBUG_TOKENS 256
 217 #define MAX_DEBUG_TOKEN_LEN 128
 218 #define DEBUG_TOKEN_DELIMITER ","
 219 #define DEBUG_ALWAYS_TOKEN "all"
 220
 221     /*
 222      * setup routines:
 223      *
 224      * debug_register_tokens(char *):     registers a list of tokens to
 225      * print debugging output for.
 226      *
 227      * debug_is_token_registered(char *): returns SNMPERR_SUCCESS or SNMPERR_GENERR
 228      * if a token has been registered or
 229      * not (and debugging output is "on").
 230      * snmp_debug_init(void):             registers .conf handlers.
 231      */
 232     void            debug_register_tokens(char *tokens);
 233     int             debug_is_token_registered(const char *token);
 234     void            snmp_debug_init(void);
 235     void            snmp_set_do_debugging(int);
 236     int             snmp_get_do_debugging(void);
 237     int             debug_is_token_registered(const char *token);
 238
 239 #ifdef __cplusplus
 240 }
 241 #endif
 242 #endif                          /* SNMP_DEBUG_H */