userapps/opensource/net-snmp/man/mib_api.3.def

   1 .TH MIB_API 3 "06 Mar 2002" VVERSIONINFO "Net-SNMP"
   2 .UC 5
   3 .SH NAME
   4 init_mib, add_mibdir, init_mib_internals,
   5 add_module_replacement,
   6 read_module, read_mib, read_all_mibs,
   7 read_objid, read_module_node,
   8 get_module_node, read_objid
   9 snmp_set_mib_warnings, snmp_set_save_descriptions,
  10 shutdown_mib,
  11 print_mib,
  12 print_variable, fprint_variable, snprint_variable, sprint_realloc_variable,
  13 print_value, fprint_value, snprint_value, sprint_realloc_value,
  14 print_objid, fprint_objid, snprint_objid, sprint_realloc_objid,
  15 print_description, fprint_description - mib_api functions
  16 .SH SYNOPSIS
  17 .B #include <net-snmp/mib_api.h>
  18 .PP
  19 .B "void init_mib(void);
  20 .br
  21 .BI "int add_mibdir(char *" "dirname" );
  22 .br
  23 .BI "int add_module_replacement(char *" "old_module" ", char *" "new_module" ", char *" "tag" ", int " "len" );
  24 .br
  25 .B "void init_mib_internals(void);
  26 .br
  27 .BI "struct tree *read_module(char *" "name" );
  28 .br
  29 .BI "struct tree *read_mib(char *" "filename" );
  30 .br
  31 .B "struct tree *read_all_mibs(void);
  32 .PP
  33 .B "void shutdown_mib(void);
  34 .PP
  35 .BI "void print_mib(FILE *" "fp" );
  36 .PP
  37 .BI "int read_objid(char *" "input" ", oid *" "output" ", int *" "out_len" );
  38 .br
  39 .BI "int get_module_node(char *" "name" ", char *" "module" ", oid *" "objid" ", int *" "objidlen" );
  40 .PP
  41 .BI "void print_variable(const oid *" "objid" ", size_t " "objidlen" ", struct variable_list *" "variable" );
  42 .br
  43 .BI "void fprint_variable(FILE *" fp ", const oid *" objid ", size_t " objidlen ", struct variable_list *" variable );
  44 .br
  45 .BI "int snprint_variable(char *" "buf" ", size_t " "len" ", const oid *" "objid" ", size_t " "objidlen" ", struct variable_list *" "variable" );
  46 .br
  47 .BI "int sprint_realloc_variable(u_char **" buf ", size_t *" buf_len ", size_t *" out_len ", int " allow_realloc ", const oid *" objid ", size_t " objidlen ", struct variable_list *" variable );
  48 .PP
  49 .BI "void print_value(oid *objid, size_t objidlen, struct variable_list *variable)
  50 .br
  51 .BI "void fprint_value(FILE *" fp ", const oid *" objid ", size_t " objidlen ", struct variable_list *" variable );
  52 .br
  53 .BI "int snprint_value(char *" buf ", size_t " "len" ", const oid *" objid ", size_t " objidlen ", struct variable_list *" variable );
  54 .br
  55 .BI "int sprint_realloc_value(u_char **" buf ", size_t *" buf_len ", size_t *" out_len ", int " allow_realloc ", const oid *" objid ", size_t " objidlen ", struct variable_list *" variable );
  56 .PP
  57 .BI "void print_objid(const oid *" objid ", size_t " objidlen );
  58 .br
  59 .BI "void fprint_objid(FILE *" fp ", const oid *" objid ", size_t " objidlen );
  60 .br
  61 .BI "int snprint_objid(char *" buf ", size_t " "len" ", const oid *" objid ", size_t " objidlen );
  62 .br
  63 .BI "int sprint_realloc_objid(u_char **" buf ", size_t *" buf_len ", size_t *" out_len ", int "allow_realloc ", const oid *" objid ", size_t " objidlen );
  64 .PP
  65 .BI "void print_description(const oid *" objid ", size_t " objidlen );
  66 .br
  67 .BI "void fprint_description(FILE *" fp ", const oid *" objid ", size_t " objidlen );
  68 .PP
  69 .BI "void snmp_set_mib_warnings(int " level );
  70 .br
  71 .BI "void snmp_set_save_descriptions(int " save ");"
  72 .PP
  73 .SH DESCRIPTION
  74 The functions dealing with MIB modules fall into four groups.  Those
  75 dealing with initialisation and shutdown, those that read in and
  76 parse MIB files, those that search the MIB tree, and various output
  77 routines.
  78 .SS Initialisation and Shutdown
  79 .B init_mib
  80 is a convenience function that handles all calls to
  81 .BR add_mibdir ", " read_module " and " read_mib
  82 for standard applications.  It should be called before any other
  83 routine that manipulates or accesses the MIB tree.  This routine sets
  84 up various internal structures, as well as reading in the default MIB
  85 modules, as detailed below.
  86 .PP
  87 .B add_mibdir
  88 is used to define the range of directory locations which are searched
  89 for files containing MIB modules (one module per file).  By default,
  90 this will be set to the directory
  91 .I DATADIR/mibs
  92 but this can be overridden by setting the environment variable
  93 .I MIBDIRS
  94 to a (colon-separated) list of directories to search.
  95 Note that this does not actually load the MIB modules located
  96 in that directory, but is an initialisation step to make them available.
  97 This function returns a count of files found in the directory, or a -1
  98 if there is an error.
  99 .PP
 100 .B init_mib_internals
 101 sets up the internal structures, preparatory to reading in MIB
 102 modules.  It should be called after all calls to
 103 .BR add_mibdir ,
 104 and before and calls to
 105 .BR read_module .
 106 This is called automatically if
 107 .B init_mib
 108 is used.
 109 .PP
 110 .B shutdown_mib
 111 will clear the information that was gathered by
 112 .BR read_module ", " add_mibdir " and " add_module_replacement .
 113 It is strongly recommended that one does not invoke
 114 .BR shutdown_mib
 115 while there are SNMP sessions being actively managed.
 116 .SS Reading and Parsing MIBs
 117 .B add_module_replacement
 118 can be used to allow new MIB modules to obsolete older ones, without
 119 needing to amend the imports clauses of other modules.  It takes the
 120 names of the old and new modules, together with an indication of which
 121 portions of the old module are affected.
 122 .RS
 123 .TS
 124 tab(+);
 125 lb lb lb
 126 l  l  l.
 127 tag + len + load the new module when:
 128 NULL + 0 + always (the old module is a strict subset of the new)
 129 name + 0 + for the given tag only
 130 name + non-0 + for any identifier with this prefix
 131 .TE
 132 .RE
 133 It can also be used to handle errors in the module identifiers used
 134 in MIB import clauses (such as referring to
 135 .I RFC1213
 136 instead of
 137 .IR RFC1213-MIB ).
 138 .PP
 139 .B read_module
 140 locates and parses the module specified, together with any modules
 141 that it imports from, and adds the contents of these modules to the
 142 active MIB tree.  Note that
 143 .B add_mibdir
 144 must first be called to add the directory containing the file with the
 145 module definition, if this is not in the standard path.
 146 .br
 147 By default, the following MIB modules will be loaded:  IP-MIB, IF-MIB,
 148 TCP-MIB, UDP-MIB, SNMPv2-MIB, RFC1213-MIB, UCD-SNMP-MIB.
 149 This can be overridden by setting the environment variable
 150 .I MIBS
 151 to a (colon-separated) list of modules to load.
 152 If this variable starts with a plus character, then the specified modules
 153 are added to the default list.  Otherwise only those modules listed are
 154 loaded (together with any others they import from).
 155 If
 156 .I MIBS
 157 is set to
 158 .IR ALL ,
 159 .B read_all_mibs
 160 is called to load all the MIB files found in all the specified
 161 .IR MIBDIRS .
 162 .PP
 163 .B read_mib
 164 parses the file specified, together with any modules that it imports
 165 from, and adds the contents to the active MIB tree.  Such a file can
 166 contain more then one module, though care must be taken that any
 167 imports occur earlier in the file, if they are not to be read from the
 168 installed modules.  Note that the file specified does not need to be
 169 in any of the directories initialised by
 170 .B add_mibdir
 171 (or the default setup), though any imported modules do.
 172 .br
 173 The environment variable
 174 .I MIBFILES
 175 can be set to a (colon-separated) list of files containing MIBs to load.
 176 .PP
 177 .B read_objid
 178 takes a string containing a textual version of an object identifier
 179 (in either numeric or descriptor form), and transforms this into the
 180 corresponding list of sub-identifiers.  This is returned in the
 181 .I output
 182 parameter, with the number of sub-identifiers returned via
 183 .IR out_len .
 184 When called,
 185 .I out_len
 186 must hold the maximum length of the
 187 .I output
 188 array.
 189 This function returns a value of 1 if it succeeds in parsing the string
 190 and 0 otherwise.
 191 .SS Searching the MIB Tree
 192 .B get_module_node
 193 takes a descriptor and the name of a module, and returns the corresponding
 194 oid list, in the same way as
 195 .B read_objid
 196 above.
 197 .br
 198 If the module name is specified as "ANY", then this routine will
 199 assume that the descriptor given is unique within the tree, and will
 200 return the matching entry.  If this assumption is invalid, then the
 201 behaviour as to which variable is returned is implementation
 202 dependent.
 203 .SS Output
 204 .B print_mib
 205 will print out a representation of the currently active MIB tree to
 206 the specified FILE pointer.
 207 .PP
 208 .B print_variable
 209 will take an object identifier (as returned by
 210 .B read_objid
 211 or
 212 .BR get_module_node )
 213 and an instance of such a variable, and prints to the standard output
 214 the textual form of the object identifier together with the value
 215 of the variable.
 216 .B fprint_variable
 217 does the same, but prints to the FILE pointer specified by the initial
 218 parameter.
 219 .br
 220 .B snprint_variable
 221 prints the same information into the buffer pointed to by
 222 .I buf
 223 which is of length
 224 .IR len
 225 and returns either the number of characters printed, or -1 if the
 226 buffer was not large enough.  In the latter case,
 227 .I buf
 228 will typically contained a truncated version of the information (but
 229 this behaviour is not guaranteed).  This function replaces the
 230 obsolete function
 231 .BR sprint_variable .
 232 .br
 233 .B sprint_realloc_variable
 234 is the low-level function used to implement all these functions.  It
 235 prints to a specified offset in a string buffer.  The
 236 .I buf
 237 parameter points to a pointer to that buffer;
 238 .I buf_len
 239 points to a variable holding the current size of that buffer, and
 240 .I out_len
 241 points to a variable holding the offset to which to print.
 242 .I out_len
 243 will be updated to hold the offset of the character following the last
 244 one added to the buffer.  If
 245 .I allow_realloc
 246 is 1, the buffer will be dynamically expanded, as necessary, to hold
 247 the output; the variables pointed to by
 248 .I buf
 249 and
 250 .I buf_len
 251 will be updated.  If
 252 .I allow_realloc
 253 is 0, the buffer will not be dynamically expanded.
 254 .B sprint_realloc_variable
 255 returns 0 if
 256 .I allow_realloc
 257 is 1 and an attempt to allocate memory to expand the buffer fails, or
 258 if
 259 .I allow_realloc
 260 is 0 and the output wouldn't fit in the buffer.  Otherwise it returns
 261 1.  When using this function you should be careful to call
 262 .BR free (3)
 263 on
 264 .I *buf
 265 when you have finished with it.
 266 .PP
 267 .BR print_value ,
 268 .BR fprint_value ,
 269 .BR snprint_value
 270 and
 271 .B sprint_realloc_value
 272 do the same as the equivalent
 273 .B print_variable
 274 routines, but only displaying the value of the variable, without the
 275 corresponding object identifier.
 276 .PP
 277 .BR print_objid ,
 278 .BR fprint_objid ,
 279 .BR snprint_objid ,
 280 and
 281 .B sprint_realloc_objid
 282 .br
 283 take an object identifier (without an accompanying variable instance)
 284 and print out the textual representation.
 285 .PP
 286 .B print_description
 287 and
 288 .B fprint_description
 289 take an object identifier (as for
 290 .B print_objid
 291 above) and print out the associated DESCRIPTION clause.
 292 .b
 293 Note that there are no corresponding routines
 294 .B snprint_description
 295 or
 296 .BR sprint_realloc_description .
 297 By default the parser does not save descriptions since they may be
 298 huge.  In order to be able to print them, you must call
 299 .BR snmp_set_save_descriptions(1) .
 300
 301 In general the parser is silent about what strangenesses it sees in
 302 the MIB files. To get warnings reported, call
 303 .B snmp_set_mib_warnings
 304 with a
 305 .I level
 306 of 1 (or 2 for even more warnings).
 307 .SH "ENVIRONMENT VARIABLES"
 308 .TP 10
 309 MIBDIRS
 310 A colon separated list of directories to search for MIB modules.
 311 Default: LIBDIR/snmp/mibs
 312 .TP 10
 313 MIBFILES
 314 A colon separated list of files to load.
 315 Default: (none)
 316 .TP 10
 317 MIBS
 318 A colon separated list of MIB modules to load.
 319 Default: IP-MIB:IF-MIB:TCP-MIB:UDP-MIB:SNMPv2-MIB:RFC1213-MIB:UCD-SNMP-MIB.
 320 .SH "SEE ALSO"
 321 .BR snmp_api "(3)"