| 1 |
/* |
| 2 |
* Portions of this file are subject to the following copyright(s). See |
| 3 |
* the Net-SNMP's COPYING file for more details and other copyrights |
| 4 |
* that may apply: |
| 5 |
* |
| 6 |
* Portions of this file are copyrighted by: |
| 7 |
* Copyright (c) 2016 VMware, Inc. All rights reserved. |
| 8 |
* Use is subject to license terms specified in the COPYING file |
| 9 |
* distributed with the Net-SNMP package. |
| 10 |
*/ |
| 11 |
|
| 12 |
#ifndef SNMP_DEBUG_H |
| 13 |
#define SNMP_DEBUG_H |
| 14 |
|
| 15 |
#include <net-snmp/library/netsnmp-attribute-format.h> |
| 16 |
|
| 17 |
#ifdef __cplusplus |
| 18 |
extern "C" { |
| 19 |
#endif |
| 20 |
|
| 21 |
/* |
| 22 |
* snmp_debug.h: |
| 23 |
* |
| 24 |
* - prototypes for snmp debugging routines. |
| 25 |
* - easy to use macros to wrap around the functions. This also provides |
| 26 |
* the ability to remove debugging code easily from the applications at |
| 27 |
* compile time. |
| 28 |
*/ |
| 29 |
|
| 30 |
/* |
| 31 |
* These functions should not be used, if at all possible. Instead, use |
| 32 |
* the macros below. |
| 33 |
*/ |
| 34 |
NETSNMP_IMPORT |
| 35 |
void debugmsg(const char *token, const char *format, ...) |
| 36 |
NETSNMP_ATTRIBUTE_FORMAT(printf, 2, 3); |
| 37 |
NETSNMP_IMPORT |
| 38 |
void debugmsgtoken(const char *token, const char *format, |
| 39 |
...) |
| 40 |
NETSNMP_ATTRIBUTE_FORMAT(printf, 2, 3); |
| 41 |
NETSNMP_IMPORT |
| 42 |
void debug_combo_nc(const char *token, const char *format, |
| 43 |
...) |
| 44 |
NETSNMP_ATTRIBUTE_FORMAT(printf, 2, 3); |
| 45 |
NETSNMP_IMPORT |
| 46 |
void debugmsg_oid(const char *token, const oid * theoid, |
| 47 |
size_t len); |
| 48 |
NETSNMP_IMPORT |
| 49 |
void debugmsg_suboid(const char *token, const oid * theoid, |
| 50 |
size_t len); |
| 51 |
NETSNMP_IMPORT |
| 52 |
void debugmsg_var(const char *token, |
| 53 |
netsnmp_variable_list * var); |
| 54 |
NETSNMP_IMPORT |
| 55 |
void debugmsg_oidrange(const char *token, |
| 56 |
const oid * theoid, size_t len, |
| 57 |
size_t var_subid, oid range_ubound); |
| 58 |
NETSNMP_IMPORT |
| 59 |
void debugmsg_hex(const char *token, const u_char * thedata, |
| 60 |
size_t len); |
| 61 |
NETSNMP_IMPORT |
| 62 |
void debugmsg_hextli(const char *token, const u_char * thedata, |
| 63 |
size_t len); |
| 64 |
NETSNMP_IMPORT |
| 65 |
void debug_indent_add(int amount); |
| 66 |
NETSNMP_IMPORT |
| 67 |
int debug_indent_get(void); |
| 68 |
NETSNMP_IMPORT |
| 69 |
void debug_indent_reset(void); |
| 70 |
/* |
| 71 |
* What is said above is true for this function as well. Further this |
| 72 |
* function is deprecated and only provided for backwards compatibility. |
| 73 |
* Please use "%*s", debug_indent_get(), "" if you used this one before. |
| 74 |
*/ |
| 75 |
NETSNMP_IMPORT |
| 76 |
const char *debug_indent(void); |
| 77 |
|
| 78 |
/* |
| 79 |
* Use these macros instead of the functions above to allow them to be |
| 80 |
* re-defined at compile time to NOP for speed optimization. |
| 81 |
* |
| 82 |
* They need to be called enclosing all the arguments in a single set of ()s. |
| 83 |
* Example: |
| 84 |
* DEBUGMSGTL(("token", "debugging of something %s related\n", "snmp")); |
| 85 |
* |
| 86 |
* Usage: |
| 87 |
* All of the functions take a "token" argument that helps determine when |
| 88 |
* the output in question should be printed. See the snmpcmd.1 manual page |
| 89 |
* on the -D flag to turn on/off output for a given token on the command line. |
| 90 |
* |
| 91 |
* DEBUGMSG((token, format, ...)): equivalent to printf(format, ...) |
| 92 |
* (if "token" debugging output |
| 93 |
* is requested by the user) |
| 94 |
* |
| 95 |
* DEBUGMSGT((token, format, ...)): equivalent to DEBUGMSG, but prints |
| 96 |
* "token: " at the beginning of the |
| 97 |
* line for you. |
| 98 |
* |
| 99 |
* DEBUGTRACE Insert this token anywhere you want |
| 100 |
* tracing output displayed when the |
| 101 |
* "trace" debugging token is selected. |
| 102 |
* |
| 103 |
* DEBUGMSGL((token, format, ...)): equivalent to DEBUGMSG, but includes |
| 104 |
* DEBUGTRACE debugging line just before |
| 105 |
* yours. |
| 106 |
* |
| 107 |
* DEBUGMSGTL((token, format, ...)): Same as DEBUGMSGL and DEBUGMSGT |
| 108 |
* combined. |
| 109 |
* |
| 110 |
* Important: |
| 111 |
* It is considered best if you use DEBUGMSGTL() everywhere possible, as it |
| 112 |
* gives the nicest format output and provides tracing support just before |
| 113 |
* every debugging statement output. |
| 114 |
* |
| 115 |
* To print multiple pieces to a single line in one call, use: |
| 116 |
* |
| 117 |
* DEBUGMSGTL(("token", "line part 1")); |
| 118 |
* DEBUGMSG (("token", " and part 2\n")); |
| 119 |
* |
| 120 |
* to get: |
| 121 |
* |
| 122 |
* token: line part 1 and part 2 |
| 123 |
* |
| 124 |
* as debugging output. |
| 125 |
* |
| 126 |
* |
| 127 |
* Each of these macros also have a version with a suffix of '_NC'. The |
| 128 |
* NC suffix stands for 'No Check', which means that no check will be |
| 129 |
* performed to see if debug is enabled or if the token has been turned |
| 130 |
* on. These NC versions are intended for use within a DEBUG_IF {} block, |
| 131 |
* where the debug/token check has already been performed. |
| 132 |
*/ |
| 133 |
|
| 134 |
#ifndef NETSNMP_NO_DEBUGGING /* make sure we're wanted */ |
| 135 |
|
| 136 |
/* |
| 137 |
* define two macros : one macro with, one without, |
| 138 |
* a test if debugging is enabled. |
| 139 |
* |
| 140 |
* Generally, use the macro with _DBG_IF_ |
| 141 |
*/ |
| 142 |
|
| 143 |
/******************* Start private macros ************************/ |
| 144 |
#define _DBG_IF_ snmp_get_do_debugging() |
| 145 |
#define DEBUGIF(x) if (_DBG_IF_ && debug_is_token_registered(x) == SNMPERR_SUCCESS) |
| 146 |
|
| 147 |
#define __DBGMSGT(x) debugmsgtoken x, debugmsg x |
| 148 |
#define __DBGMSG_NC(x) debugmsg x |
| 149 |
#define __DBGMSGT_NC(x) debug_combo_nc x |
| 150 |
#define __DBGMSGL_NC(x) __DBGTRACE; debugmsg x |
| 151 |
#define __DBGMSGTL_NC(x) __DBGTRACE; debug_combo_nc x |
| 152 |
|
| 153 |
#ifdef NETSNMP_FUNCTION |
| 154 |
#define __DBGTRACE __DBGMSGT(("trace","%s(): %s, %d:\n",\ |
| 155 |
NETSNMP_FUNCTION,__FILE__,__LINE__)) |
| 156 |
#define __DBGTRACETOK(x) __DBGMSGT((x,"%s(): %s, %d:\n", \ |
| 157 |
NETSNMP_FUNCTION,__FILE__,__LINE__)) |
| 158 |
#else |
| 159 |
#define __DBGTRACE __DBGMSGT(("trace"," %s, %d:\n", __FILE__,__LINE__)) |
| 160 |
#define __DBGTRACETOK(x) __DBGMSGT((x," %s, %d:\n", __FILE__,__LINE__)) |
| 161 |
#endif |
| 162 |
|
| 163 |
#define __DBGMSGL(x) __DBGTRACE, debugmsg x |
| 164 |
#define __DBGMSGTL(x) __DBGTRACE, debugmsgtoken x, debugmsg x |
| 165 |
#define __DBGMSGOID(x) debugmsg_oid x |
| 166 |
#define __DBGMSGSUBOID(x) debugmsg_suboid x |
| 167 |
#define __DBGMSGVAR(x) debugmsg_var x |
| 168 |
#define __DBGMSGOIDRANGE(x) debugmsg_oidrange x |
| 169 |
#define __DBGMSGHEX(x) debugmsg_hex x |
| 170 |
#define __DBGMSGHEXTLI(x) debugmsg_hextli x |
| 171 |
#define __DBGINDENT() debug_indent_get() |
| 172 |
#define __DBGINDENTADD(x) debug_indent_add(x) |
| 173 |
#define __DBGINDENTMORE() debug_indent_add(2) |
| 174 |
#define __DBGINDENTLESS() debug_indent_add(-2) |
| 175 |
#define __DBGPRINTINDENT(token) __DBGMSGTL((token, "%*s", __DBGINDENT(), "")) |
| 176 |
|
| 177 |
#define __DBGDUMPHEADER(token,x) \ |
| 178 |
__DBGPRINTINDENT("dumph_" token); \ |
| 179 |
debugmsg("dumph_" token,x); \ |
| 180 |
if (debug_is_token_registered("dumpx" token) == SNMPERR_SUCCESS || \ |
| 181 |
debug_is_token_registered("dumpv" token) == SNMPERR_SUCCESS || \ |
| 182 |
(debug_is_token_registered("dumpx_" token) != SNMPERR_SUCCESS && \ |
| 183 |
debug_is_token_registered("dumpv_" token) != SNMPERR_SUCCESS)) { \ |
| 184 |
debugmsg("dumph_" token,"\n"); \ |
| 185 |
} else { \ |
| 186 |
debugmsg("dumph_" token," "); \ |
| 187 |
} \ |
| 188 |
__DBGINDENTMORE() |
| 189 |
|
| 190 |
#define __DBGDUMPSECTION(token,x) \ |
| 191 |
__DBGPRINTINDENT("dumph_" token); \ |
| 192 |
debugmsg("dumph_" token,"%s\n",x);\ |
| 193 |
__DBGINDENTMORE() |
| 194 |
|
| 195 |
#define __DBGDUMPSETUP(token,buf,len) \ |
| 196 |
debugmsg("dumpx" token, "dumpx_%s:%*s", token, __DBGINDENT(), ""); \ |
| 197 |
__DBGMSGHEX(("dumpx_" token,buf,len)); \ |
| 198 |
if (debug_is_token_registered("dumpv" token) == SNMPERR_SUCCESS || \ |
| 199 |
debug_is_token_registered("dumpv_" token) != SNMPERR_SUCCESS) { \ |
| 200 |
debugmsg("dumpx_" token,"\n"); \ |
| 201 |
} else { \ |
| 202 |
debugmsg("dumpx_" token," "); \ |
| 203 |
} \ |
| 204 |
debugmsg("dumpv" token, "dumpv_%s:%*s", token, __DBGINDENT(), ""); |
| 205 |
|
| 206 |
/******************* End private macros ************************/ |
| 207 |
/*****************************************************************/ |
| 208 |
#endif /* NETSNMP_NO_DEBUGGING */ |
| 209 |
|
| 210 |
#ifdef __cplusplus |
| 211 |
} |
| 212 |
#endif |
| 213 |
|
| 214 |
/* Public macros moved to top-level API header file */ |
| 215 |
#include <net-snmp/output_api.h> |
| 216 |
|
| 217 |
#ifdef __cplusplus |
| 218 |
extern "C" { |
| 219 |
#endif |
| 220 |
|
| 221 |
void snmp_debug_init(void); |
| 222 |
void snmp_debug_shutdown(void); |
| 223 |
|
| 224 |
#define MAX_DEBUG_TOKENS 256 |
| 225 |
#define MAX_DEBUG_TOKEN_LEN 128 |
| 226 |
#define DEBUG_TOKEN_DELIMITER "," |
| 227 |
#define DEBUG_ALWAYS_TOKEN "all" |
| 228 |
|
| 229 |
#ifndef NETSNMP_NO_DEBUGGING |
| 230 |
|
| 231 |
/* |
| 232 |
* internal: |
| 233 |
* You probably shouldn't be using this information unless the word |
| 234 |
* "expert" applies to you. I know it looks tempting. |
| 235 |
*/ |
| 236 |
typedef struct netsnmp_token_descr_s { |
| 237 |
char *token_name; |
| 238 |
char enabled; |
| 239 |
} netsnmp_token_descr; |
| 240 |
|
| 241 |
NETSNMP_IMPORT int debug_num_tokens; |
| 242 |
NETSNMP_IMPORT netsnmp_token_descr dbg_tokens[MAX_DEBUG_TOKENS]; |
| 243 |
|
| 244 |
#endif /* NETSNMP_NO_DEBUGGING */ |
| 245 |
|
| 246 |
#ifdef __cplusplus |
| 247 |
} |
| 248 |
#endif |
| 249 |
#endif /* SNMP_DEBUG_H */ |