net-snmp 5.7
snmp_debug.h
00001 #ifndef SNMP_DEBUG_H
00002 #define SNMP_DEBUG_H
00003 
00004 #ifdef __cplusplus
00005 extern          "C" {
00006 #endif
00007 
00008     /*
00009      * snmp_debug.h:
00010      * 
00011      * - prototypes for snmp debugging routines.
00012      * - easy to use macros to wrap around the functions.  This also provides
00013      * the ability to remove debugging code easily from the applications at
00014      * compile time.
00015      */
00016 
00017 
00018 #if !defined(__GNUC__) || __GNUC__ < 2 || (__GNUC__ == 2 && __GNUC_MINOR__ < 8)
00019 #define NETSNMP_ATTRIBUTE_FORMAT(type, formatArg, firstArg)
00020 #else
00021 #define NETSNMP_ATTRIBUTE_FORMAT(type, formatArg, firstArg) \
00022   __attribute__((__format__( __ ## type ## __, formatArg, firstArg )))
00023 #endif
00024 
00025     /*
00026      * These functions should not be used, if at all possible.  Instead, use
00027      * the macros below. 
00028      */
00029     NETSNMP_IMPORT
00030     void            debugmsg(const char *token, const char *format, ...)
00031                         NETSNMP_ATTRIBUTE_FORMAT(printf, 2, 3);
00032     NETSNMP_IMPORT
00033     void            debugmsgtoken(const char *token, const char *format,
00034                                   ...)
00035                         NETSNMP_ATTRIBUTE_FORMAT(printf, 2, 3);
00036     void            debug_combo_nc(const char *token, const char *format,
00037                                    ...)
00038                         NETSNMP_ATTRIBUTE_FORMAT(printf, 2, 3);
00039 
00040 #undef NETSNMP_ATTRIBUTE_FORMAT
00041 
00042     NETSNMP_IMPORT
00043     void            debugmsg_oid(const char *token, const oid * theoid,
00044                                  size_t len);
00045     NETSNMP_IMPORT
00046     void            debugmsg_suboid(const char *token, const oid * theoid,
00047                                     size_t len);
00048     NETSNMP_IMPORT
00049     void            debugmsg_var(const char *token,
00050                                  netsnmp_variable_list * var);
00051     NETSNMP_IMPORT
00052     void            debugmsg_oidrange(const char *token,
00053                                       const oid * theoid, size_t len,
00054                                       size_t var_subid, oid range_ubound);
00055     NETSNMP_IMPORT
00056     void            debugmsg_hex(const char *token, const u_char * thedata,
00057                                  size_t len);
00058     NETSNMP_IMPORT
00059     void            debugmsg_hextli(const char *token, const u_char * thedata,
00060                                     size_t len);
00061     NETSNMP_IMPORT
00062     void            debug_indent_add(int amount);
00063     NETSNMP_IMPORT
00064     int             debug_indent_get(void);
00065     /*
00066      * What is said above is true for this function as well. Further this
00067      * function is deprecated and only provided for backwards compatibility.
00068      * Please use "%*s", debug_indent_get(), "" if you used this one before.
00069      */
00070     NETSNMP_IMPORT
00071     const char     *debug_indent(void);
00072 
00073     /*
00074      * Use these macros instead of the functions above to allow them to be
00075      * re-defined at compile time to NOP for speed optimization.
00076      * 
00077      * They need to be called enclosing all the arguments in a single set of ()s.
00078      * Example:
00079      * DEBUGMSGTL(("token", "debugging of something %s related\n", "snmp"));
00080      * 
00081      * Usage:
00082      * All of the functions take a "token" argument that helps determine when
00083      * the output in question should be printed.  See the snmpcmd.1 manual page
00084      * on the -D flag to turn on/off output for a given token on the command line.
00085      * 
00086      * DEBUGMSG((token, format, ...)):      equivalent to printf(format, ...)
00087      * (if "token" debugging output
00088      * is requested by the user)
00089      * 
00090      * DEBUGMSGT((token, format, ...)):     equivalent to DEBUGMSG, but prints
00091      * "token: " at the beginning of the
00092      * line for you.
00093      * 
00094      * DEBUGTRACE                           Insert this token anywhere you want
00095      * tracing output displayed when the
00096      * "trace" debugging token is selected.
00097      * 
00098      * DEBUGMSGL((token, format, ...)):     equivalent to DEBUGMSG, but includes
00099      * DEBUGTRACE debugging line just before
00100      * yours.
00101      * 
00102      * DEBUGMSGTL((token, format, ...)):    Same as DEBUGMSGL and DEBUGMSGT
00103      * combined.
00104      * 
00105      * Important:
00106      * It is considered best if you use DEBUGMSGTL() everywhere possible, as it
00107      * gives the nicest format output and provides tracing support just before
00108      * every debugging statement output.
00109      * 
00110      * To print multiple pieces to a single line in one call, use:
00111      * 
00112      * DEBUGMSGTL(("token", "line part 1"));
00113      * DEBUGMSG  (("token", " and part 2\n"));
00114      * 
00115      * to get:
00116      * 
00117      * token: line part 1 and part 2
00118      * 
00119      * as debugging output.
00120      *
00121      *
00122      * Each of these macros also have a version with a suffix of '_NC'. The
00123      * NC suffix stands for 'No Check', which means that no check will be
00124      * performed to see if debug is enabled or if the token has been turned
00125      * on. These NC versions are intended for use within a DEBUG_IF {} block,
00126      * where the debug/token check has already been performed.
00127      */
00128 
00129 #ifndef NETSNMP_NO_DEBUGGING       /* make sure we're wanted */
00130 
00131     /*
00132      * define two macros : one macro with, one without,
00133      *                     a test if debugging is enabled.
00134      * 
00135      * Generally, use the macro with _DBG_IF_
00136      */
00137 
00138 /******************* Start private macros ************************/
00139 #define _DBG_IF_            snmp_get_do_debugging()
00140 #define DEBUGIF(x)         if (_DBG_IF_ && debug_is_token_registered(x) == SNMPERR_SUCCESS)
00141 
00142 #define __DBGMSGT(x)     debugmsgtoken x,  debugmsg x
00143 #define __DBGMSG_NC(x)   debugmsg x
00144 #define __DBGMSGT_NC(x)  debug_combo_nc x
00145 #define __DBGMSGL_NC(x)  __DBGTRACE; debugmsg x
00146 #define __DBGMSGTL_NC(x) __DBGTRACE; debug_combo_nc x
00147 
00148 #ifdef  NETSNMP_FUNCTION
00149 #define __DBGTRACE       __DBGMSGT(("trace","%s(): %s, %d:\n",\
00150                                 NETSNMP_FUNCTION,__FILE__,__LINE__))
00151 #define __DBGTRACETOK(x) __DBGMSGT((x,"%s(): %s, %d:\n",       \
00152                                     NETSNMP_FUNCTION,__FILE__,__LINE__))
00153 #else
00154 #define __DBGTRACE       __DBGMSGT(("trace"," %s, %d:\n", __FILE__,__LINE__))
00155 #define __DBGTRACETOK(x) __DBGMSGT((x," %s, %d:\n", __FILE__,__LINE__))
00156 #endif
00157 
00158 #define __DBGMSGL(x)     __DBGTRACE, debugmsg x
00159 #define __DBGMSGTL(x)    __DBGTRACE, debugmsgtoken x, debugmsg x
00160 #define __DBGMSGOID(x)     debugmsg_oid x
00161 #define __DBGMSGSUBOID(x)  debugmsg_suboid x
00162 #define __DBGMSGVAR(x)     debugmsg_var x
00163 #define __DBGMSGOIDRANGE(x) debugmsg_oidrange x
00164 #define __DBGMSGHEX(x)     debugmsg_hex x
00165 #define __DBGMSGHEXTLI(x)  debugmsg_hextli x
00166 #define __DBGINDENT()      debug_indent_get()
00167 #define __DBGINDENTADD(x)  debug_indent_add(x)
00168 #define __DBGINDENTMORE()  debug_indent_add(2)
00169 #define __DBGINDENTLESS()  debug_indent_add(-2)
00170 #define __DBGPRINTINDENT(token) __DBGMSGTL((token, "%*s", __DBGINDENT(), ""))
00171 
00172 #define __DBGDUMPHEADER(token,x) \
00173         __DBGPRINTINDENT("dumph_" token); \
00174         debugmsg("dumph_" token,x); \
00175         if (debug_is_token_registered("dumpx" token) == SNMPERR_SUCCESS ||    \
00176             debug_is_token_registered("dumpv" token) == SNMPERR_SUCCESS ||    \
00177             (debug_is_token_registered("dumpx_" token) != SNMPERR_SUCCESS &&  \
00178              debug_is_token_registered("dumpv_" token) != SNMPERR_SUCCESS)) { \
00179             debugmsg("dumph_" token,"\n"); \
00180         } else { \
00181             debugmsg("dumph_" token,"  "); \
00182         } \
00183         __DBGINDENTMORE()
00184 
00185 #define __DBGDUMPSECTION(token,x) \
00186         __DBGPRINTINDENT("dumph_" token); \
00187         debugmsg("dumph_" token,"%s\n",x);\
00188         __DBGINDENTMORE()
00189 
00190 #define __DBGDUMPSETUP(token,buf,len) \
00191         debugmsg("dumpx" token, "dumpx_%s:%*s", token, __DBGINDENT(), ""); \
00192         __DBGMSGHEX(("dumpx_" token,buf,len)); \
00193         if (debug_is_token_registered("dumpv" token) == SNMPERR_SUCCESS || \
00194             debug_is_token_registered("dumpv_" token) != SNMPERR_SUCCESS) { \
00195             debugmsg("dumpx_" token,"\n"); \
00196         } else { \
00197             debugmsg("dumpx_" token,"  "); \
00198         } \
00199         debugmsg("dumpv" token, "dumpv_%s:%*s", token, __DBGINDENT(), "");
00200 
00201 /******************* End   private macros ************************/
00202 /*****************************************************************/
00203 #endif /* NETSNMP_NO_DEBUGGING */
00204 
00205 #ifdef __cplusplus
00206 }
00207 #endif
00208 
00209     /* Public macros moved to top-level API header file */
00210 #include <net-snmp/output_api.h>
00211 
00212 #ifdef __cplusplus
00213 extern          "C" {
00214 #endif
00215 
00216     void            snmp_debug_init(void);
00217 
00218 #define MAX_DEBUG_TOKENS 256
00219 #define MAX_DEBUG_TOKEN_LEN 128
00220 #define DEBUG_TOKEN_DELIMITER ","
00221 #define DEBUG_ALWAYS_TOKEN "all"
00222 
00223 #ifndef NETSNMP_NO_DEBUGGING
00224 
00225 /*
00226  * internal:
00227  * You probably shouldn't be using this information unless the word
00228  * "expert" applies to you.  I know it looks tempting.
00229  */
00230 typedef struct netsnmp_token_descr_s {
00231     char *token_name;
00232     char  enabled;
00233 } netsnmp_token_descr;
00234 
00235 NETSNMP_IMPORT int                 debug_num_tokens;
00236 NETSNMP_IMPORT netsnmp_token_descr dbg_tokens[MAX_DEBUG_TOKENS];
00237 
00238 #endif /* NETSNMP_NO_DEBUGGING */
00239 
00240 #ifdef __cplusplus
00241 }
00242 #endif
00243 #endif                          /* SNMP_DEBUG_H */