Debian Codegraph @

include/net-snmp/library/snmp_debug.h

raw
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 */