packages/net/snmp/lib/v2_0/include/snmp_debug.h

   1 //==========================================================================
   2 //
   3 //      ./lib/current/include/snmp_debug.h
   4 //
   5 //
   6 //==========================================================================
   7 //####ECOSGPLCOPYRIGHTBEGIN####
   8 // -------------------------------------------
   9 // This file is part of eCos, the Embedded Configurable Operating System.
  10 // Copyright (C) 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.
  11 //
  12 // eCos is free software; you can redistribute it and/or modify it under
  13 // the terms of the GNU General Public License as published by the Free
  14 // Software Foundation; either version 2 or (at your option) any later version.
  15 //
  16 // eCos is distributed in the hope that it will be useful, but WITHOUT ANY
  17 // WARRANTY; without even the implied warranty of MERCHANTABILITY or
  18 // FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  19 // for more details.
  20 //
  21 // You should have received a copy of the GNU General Public License along
  22 // with eCos; if not, write to the Free Software Foundation, Inc.,
  23 // 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
  24 //
  25 // As a special exception, if other files instantiate templates or use macros
  26 // or inline functions from this file, or you compile this file and link it
  27 // with other works to produce a work based on this file, this file does not
  28 // by itself cause the resulting work to be covered by the GNU General Public
  29 // License. However the source code for this file must still be made available
  30 // in accordance with section (3) of the GNU General Public License.
  31 //
  32 // This exception does not invalidate any other reasons why a work based on
  33 // this file might be covered by the GNU General Public License.
  34 //
  35 // Alternative licenses for eCos may be arranged by contacting Red Hat, Inc.
  36 // at http://sources.redhat.com/ecos/ecos-license/
  37 // -------------------------------------------
  38 //####ECOSGPLCOPYRIGHTEND####
  39 //####UCDSNMPCOPYRIGHTBEGIN####
  40 //
  41 // -------------------------------------------
  42 //
  43 // Portions of this software may have been derived from the UCD-SNMP
  44 // project,  <http://ucd-snmp.ucdavis.edu/>  from the University of
  45 // California at Davis, which was originally based on the Carnegie Mellon
  46 // University SNMP implementation.  Portions of this software are therefore
  47 // covered by the appropriate copyright disclaimers included herein.
  48 //
  49 // The release used was version 4.1.2 of May 2000.  "ucd-snmp-4.1.2"
  50 // -------------------------------------------
  51 //
  52 //####UCDSNMPCOPYRIGHTEND####
  53 //==========================================================================
  54 //#####DESCRIPTIONBEGIN####
  55 //
  56 // Author(s):    hmt
  57 // Contributors: hmt
  58 // Date:         2000-05-30
  59 // Purpose:      Port of UCD-SNMP distribution to eCos.
  60 // Description:
  61 //
  62 //
  63 //####DESCRIPTIONEND####
  64 //
  65 //==========================================================================
  66 /********************************************************************
  67        Copyright 1989, 1991, 1992 by Carnegie Mellon University
  68
  69                           Derivative Work -
  70 Copyright 1996, 1998, 1999, 2000 The Regents of the University of California
  71
  72                          All Rights Reserved
  73
  74 Permission to use, copy, modify and distribute this software and its
  75 documentation for any purpose and without fee is hereby granted,
  76 provided that the above copyright notice appears in all copies and
  77 that both that copyright notice and this permission notice appear in
  78 supporting documentation, and that the name of CMU and The Regents of
  79 the University of California not be used in advertising or publicity
  80 pertaining to distribution of the software without specific written
  81 permission.
  82
  83 CMU AND THE REGENTS OF THE UNIVERSITY OF CALIFORNIA DISCLAIM ALL
  84 WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED
  85 WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL CMU OR
  86 THE REGENTS OF THE UNIVERSITY OF CALIFORNIA BE LIABLE FOR ANY SPECIAL,
  87 INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
  88 FROM THE LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
  89 CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  90 CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  91 *********************************************************************/
  92 #ifndef SNMP_DEBUG_H
  93 #define SNMP_DEBUG_H
  94
  95 #ifdef __cplusplus
  96 extern "C" {
  97 #endif
  98
  99 /* snmp_debug.h:
 100
 101    - prototypes for snmp debugging routines.
 102    - easy to use macros to wrap around the functions.  This also provides
 103      the ability to reove debugging code easily from the applications at
 104      compile time.
 105 */
 106
 107
 108 /* These functions should not be used, if at all possible.  Instead, use
 109    the macros below. */
 110 #if HAVE_STDARG_H
 111 void debugmsg(const char *token, const char *format, ...);
 112 void debugmsgtoken(const char *token, const char *format, ...);
 113 #else
 114 void debugmsg(va_alist);
 115 void debugmsgtoken(va_alist);
 116 #endif
 117 void debugmsg_oid(const char *token, oid *theoid, size_t len);
 118 void debugmsg_hex(const char *token, u_char *thedata, size_t len);
 119 void debugmsg_hextli(const char *token, u_char *thedata, size_t len);
 120 void debug_indent_add(int amount);
 121 char *debug_indent(void);
 122
 123 /* Use these macros instead of the functions above to allow them to be
 124    re-defined at compile time to NOP for speed optimization.
 125
 126    They need to be called enclosing all the arguments in a single set of ()s.
 127    Example:
 128       DEBUGMSGTL(("token", "debugging of something %s related\n", "snmp"));
 129
 130 Usage:
 131    All of the functions take a "token" argument that helps determine when
 132    the output in question should be printed.  See the snmpcmd.1 manual page
 133    on the -D flag to turn on/off output for a given token on the command line.
 134
 135      DEBUGMSG((token, format, ...)):      equivelent to printf(format, ...)
 136                                           (if "token" debugging output
 137                                           is requested by the user)
 138
 139      DEBUGMSGT((token, format, ...)):     equivelent to DEBUGMSG, but prints
 140                                           "token: " at the beginning of the
 141                                           line for you.
 142
 143      DEBUGTRACE                           Insert this token anywhere you want
 144                                           tracing output displayed when the
 145                                           "trace" debugging token is selected.
 146
 147      DEBUGMSGL((token, format, ...)):     equivelent to DEBUGMSG, but includes
 148                                           DEBUGTRACE debugging line just before
 149                                           yours.
 150
 151      DEBUGMSGTL((token, format, ...)):    Same as DEBUGMSGL and DEBUGMSGT
 152                                           combined.
 153
 154 Important:
 155    It is considered best if you use DEBUGMSGTL() everywhere possible, as it
 156    gives the nicest format output and provides tracing support just before
 157    every debugging statement output.
 158
 159 To print multiple pieces to a single line in one call, use:
 160
 161      DEBUGMSGTL(("token", "line part 1"));
 162      DEBUGMSG  (("token", " and part 2\n"));
 163
 164    to get:
 165
 166      token: line part 1 and part 2
 167
 168    as debugging output.
 169 */
 170
 171 #ifndef SNMP_NO_DEBUGGING  /* make sure we're wanted */
 172
 173 /*
 174  * define two macros : one macro with, one without,
 175  *                     a test if debugging is enabled.
 176  *
 177  * Generally, use the macro with _DBG_IF_
 178  */
 179
 180 /******************* Start private macros ************************/
 181 #define _DBG_IF_            snmp_get_do_debugging()
 182 #define DEBUGIF(x)         if (_DBG_IF_ && debug_is_token_registered(x) == SNMPERR_SUCCESS)
 183
 184 #define __DBGMSGT(x)     debugmsgtoken x,  debugmsg x
 185
 186 #ifdef  HAVE_CPP_UNDERBAR_FUNCTION_DEFINED
 187 #define __DBGTRACE       __DBGMSGT(("trace","%s(): %s, %d\n",__FUNCTION__,\
 188                                  __FILE__,__LINE__))
 189 #else
 190 #define __DBGTRACE       __DBGMSGT(("trace"," %s, %d\n", __FILE__,__LINE__))
 191 #endif
 192
 193 #define __DBGMSGL(x)     __DBGTRACE, debugmsg x
 194 #define __DBGMSGTL(x)    __DBGTRACE, debugmsgtoken x, debugmsg x
 195 #define __DBGMSGOID(x)     debugmsg_oid x
 196 #define __DBGMSGHEX(x)     debugmsg_hex x
 197 #define __DBGMSGHEXTLI(x)  debugmsg_hextli x
 198 #define __DBGINDENT()      debug_indent()
 199 #define __DBGINDENTADD(x)  debug_indent_add(x)
 200 #define __DBGINDENTMORE()  debug_indent_add(2)
 201 #define __DBGINDENTLESS()  debug_indent_add(-2)
 202 #define __DBGPRINTINDENT(token) __DBGMSGTL((token, "%s", __DBGINDENT()))
 203
 204 #define __DBGDUMPHEADER(token,x) \
 205         __DBGPRINTINDENT(token), \
 206         debugmsg(token,x), \
 207         __DBGINDENTMORE()
 208
 209 #define __DBGDUMPSETUP(token,buf,len) \
 210         __DBGTRACE, \
 211         __DBGMSGHEXTLI((token,buf,len)), \
 212         debugmsg(token,"\n"), \
 213         __DBGPRINTINDENT(token)
 214
 215 /******************* End   private macros ************************/
 216 /*****************************************************************/
 217
 218 /*****************************************************************/
 219 /********************Start public  macros ************************/
 220
 221 #define DEBUGMSG(x)        do {if (_DBG_IF_) {debugmsg x;} }while(0)
 222 #define DEBUGMSGT(x)       do {if (_DBG_IF_) {__DBGMSGT(x);} }while(0)
 223 #define DEBUGTRACE         do {if (_DBG_IF_) {__DBGTRACE;} }while(0)
 224 #define DEBUGMSGL(x)       do {if (_DBG_IF_) {__DBGMSGL(x);} }while(0)
 225 #define DEBUGMSGTL(x)      do {if (_DBG_IF_) {__DBGMSGTL(x);} }while(0)
 226 #define DEBUGMSGOID(x)     do {if (_DBG_IF_) {__DBGMSGOID(x);} }while(0)
 227 #define DEBUGMSGHEX(x)     do {if (_DBG_IF_) {__DBGMSGHEX(x);} }while(0)
 228 #define DEBUGMSGHEXTLI(x)  do {if (_DBG_IF_) {__DBGMSGHEXTLI(x);} }while(0)
 229 #define DEBUGINDENT()      do {if (_DBG_IF_) {__DBGINDENT();} }while(0)
 230 #define DEBUGINDENTADD(x)  do {if (_DBG_IF_) {__DBGINDENTADD(x);} }while(0)
 231 #define DEBUGINDENTMORE()  do {if (_DBG_IF_) {__DBGINDENTMORE();} }while(0)
 232 #define DEBUGINDENTLESS()  do {if (_DBG_IF_) {__DBGINDENTLESS();} }while(0)
 233 #define DEBUGPRINTINDENT(token) \
 234         do {if (_DBG_IF_) {__DBGPRINTINDENT(token);} }while(0)
 235
 236
 237 #define DEBUGDUMPHEADER(token,x) \
 238         do {if (_DBG_IF_) {__DBGDUMPHEADER(token,x);} }while(0)
 239
 240 #define DEBUGDUMPSETUP(token,buf,len) \
 241         do {if (_DBG_IF_) {__DBGDUMPSETUP(token,buf,len);} }while(0)
 242
 243 #else /* SNMP_NO_DEBUGGING := enable streamlining of the code */
 244
 245 #define DEBUGMSG(x)
 246 #define DEBUGMSGT(x)
 247 #define DEBUGTRACE
 248 #define DEBUGMSGL(x)
 249 #define DEBUGMSGTL(x)
 250 #define DEBUGMSGOID(x)
 251 #define DEBUGMSGHEX(x)
 252 #define DEBUGIF(x)        if(0)
 253 #define DEBUGDUMP(t,b,l,p)
 254 #define DEBUGINDENT()
 255 #define DEBUGINDENTMORE()
 256 #define DEBUGINDENTLESS()
 257 #define DEBUGINDENTADD(x)
 258 #define DEBUGMSGHEXTLI(x)
 259 #define DEBUGPRINTINDENT(token)
 260 #define DEBUGDUMPHEADER(token,x)
 261 #define DEBUGDUMPSETUP(token, buf, len)
 262
 263 #endif
 264
 265 #define MAX_DEBUG_TOKENS 256
 266 #define MAX_DEBUG_TOKEN_LEN 128
 267 #define DEBUG_TOKEN_DELIMITER ","
 268 #define DEBUG_ALWAYS_TOKEN "all"
 269
 270 /*
 271   setup routines:
 272
 273   debug_register_tokens(char *):     registers a list of tokens to
 274                                      print debugging output for.
 275
 276   debug_is_token_registered(char *): returns SNMPERR_SUCCESS or SNMPERR_GENERR
 277                                      if a token has been registered or
 278                                      not (and debugging output is "on").
 279   snmp_debug_init(void):             registers .conf handlers.
 280 */
 281 void debug_register_tokens(char *tokens);
 282 int debug_is_token_registered(const char *token);
 283 void snmp_debug_init(void);
 284
 285 /* provided for backwards compatability.  Don't use these functions. */
 286 #if HAVE_STDARG_H
 287 void DEBUGP (const char *, ...);
 288 #else
 289 void DEBUGP (va_alist);
 290 #endif
 291 void DEBUGPOID(oid *, size_t);
 292 void snmp_set_do_debugging (int);
 293 int snmp_get_do_debugging (void);
 294 int debug_is_token_registered(const char *token);
 295
 296 #ifdef __cplusplus
 297 }
 298 #endif
 299
 300 #endif /* SNMP_DEBUG_H */