man/mib_api.3.def

.TH MIB_API 3 "22 Apr 2009" VVERSIONINFO "Net-SNMP"
.SH NAME
init_mib, add_mibdir, init_mib_internals,
add_module_replacement,
read_module, read_mib, read_all_mibs,
read_objid, read_module_node, get_module_node,
snmp_set_mib_warnings, snmp_set_save_descriptions,
shutdown_mib,
print_mib,
print_variable, fprint_variable, snprint_variable, sprint_realloc_variable,
print_value, fprint_value, snprint_value, sprint_realloc_value,
print_objid, fprint_objid, snprint_objid, sprint_realloc_objid,
print_description, fprint_description - mib_api functions
.SH SYNOPSIS
.B #include <net-snmp/mib_api.h>
.PP
.B "void init_mib(void);
.br
.BI "int add_mibdir(const char *" "dirname" );
.br
.BI "int add_module_replacement(const char *" "old_module" ", const char *" "new_module" ", const char *" "tag" ", int " "len" );
.br
.B "void init_mib_internals(void);
.br
.BI "struct tree *read_module(const char *" "name" );
.br
.BI "struct tree *read_mib(const char *" "filename" );
.br
.B "struct tree *read_all_mibs(void);
.PP
.B "void shutdown_mib(void);
.PP
.BI "void print_mib(FILE *" "fp" );
.PP
.BI "int read_objid(const char *" "input" ", oid *" "output" ", size_t *" "out_len" );
.br
.BI "int get_module_node(const char *" "name" ", const char *" "module" ", oid *" "objid" ", size_t *" "objidlen" );
.PP
.BI "void print_variable(const oid *" "objid" ", size_t " "objidlen" ", const netsnmp_variable_list *" "variable" );
.br
.BI "void fprint_variable(FILE *" fp ", const oid *" objid ", size_t " objidlen ", const netsnmp_variable_list *" variable );
.br
.BI "int snprint_variable(char *" "buf" ", size_t " "len" ", const oid *" "objid" ", size_t " "objidlen" ", const netsnmp_variable_list *" "variable" );
.br
.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 ", const netsnmp_variable_list *" variable );
.PP
.BI "void print_value(oid *objid, size_t objidlen, const netsnmp_variable_list *variable)
.br
.BI "void fprint_value(FILE *" fp ", const oid *" objid ", size_t " objidlen ", const netsnmp_variable_list *" variable );
.br
.BI "int snprint_value(char *" buf ", size_t " "len" ", const oid *" objid ", size_t " objidlen ", const netsnmp_variable_list *" variable );
.br
.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 ", const netsnmp_variable_list *" variable );
.PP
.BI "void print_objid(const oid *" objid ", size_t " objidlen );
.br
.BI "void fprint_objid(FILE *" fp ", const oid *" objid ", size_t " objidlen );
.br
.BI "int snprint_objid(char *" buf ", size_t " "len" ", const oid *" objid ", size_t " objidlen );
.br
.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 );
.PP
.BI "void print_description(oid *" objid ", size_t " objidlen ", int " width );
.br
.BI "void fprint_description(FILE *" fp ", const oid *" objid ", size_t " objidlen ", int " width );
.PP
.BI "void snmp_set_mib_warnings(int " level );
.br
.BI "void snmp_set_save_descriptions(int " save ");"
.PP
.SH DESCRIPTION
The functions dealing with MIB modules fall into four groups.  Those
dealing with initialisation and shutdown, those that read in and
parse MIB files, those that search the MIB tree, and various output
routines.
.SS Initialisation and Shutdown
.B init_mib
is a convenience function that handles all calls to
.BR add_mibdir ", " read_module " and " read_mib
for standard applications.  It should be called before any other
routine that manipulates or accesses the MIB tree.  This routine sets
up various internal structures, as well as reading in the default MIB
modules, as detailed below.
.PP
.B add_mibdir
is used to define the range of directory locations which are searched
for files containing MIB modules (one module per file).  By default,
this will be set to the directory
.I DATADIR/mibs
but this can be overridden by setting the environment variable
.I MIBDIRS
to a (colon-separated) list of directories to search.
Note that this does not actually load the MIB modules located
in that directory, but is an initialisation step to make them available.
This function returns a count of files found in the directory, or a -1
if there is an error.  
.PP
.B init_mib_internals
sets up the internal structures, preparatory to reading in MIB
modules.  It should be called after all calls to
.BR add_mibdir ,
and before and calls to
.BR read_module .
This is called automatically if
.B init_mib
is used.
.PP
.B shutdown_mib
will clear the information that was gathered by 
.BR read_module ", " add_mibdir " and " add_module_replacement .
It is strongly recommended that one does not invoke
.BR shutdown_mib
while there are SNMP sessions being actively managed.
.SS Reading and Parsing MIBs
.B add_module_replacement
can be used to allow new MIB modules to obsolete older ones, without
needing to amend the imports clauses of other modules.  It takes the
names of the old and new modules, together with an indication of which
portions of the old module are affected.
.RS
.TS
tab(+);
lb lb lb
l  l  l.
tag + len + load the new module when:
NULL + 0 + always (the old module is a strict subset of
 + + the new)
name + 0 + for the given tag only
name + non-0 + for any identifier with this prefix
.TE
.RE
It can also be used to handle errors in the module identifiers used
in MIB import clauses (such as referring to
.I RFC1213
instead of
.IR RFC1213-MIB ).
.PP
.B read_module
locates and parses the module specified, together with any modules
that it imports from, and adds the contents of these modules to the
active MIB tree.  Note that
.B add_mibdir
must first be called to add the directory containing the file with the
module definition, if this is not in the standard path.
.br
By default, the following MIB modules will be loaded:  IP-MIB, IF-MIB,
TCP-MIB, UDP-MIB, SNMPv2-MIB, RFC1213-MIB, UCD-SNMP-MIB.
This can be overridden by setting the environment variable
.I MIBS
to a (colon-separated) list of modules to load.
If this variable starts with a plus character, then the specified modules
are added to the default list.  Otherwise only those modules listed are
loaded (together with any others they import from).
If
.I MIBS
is set to
.IR ALL ,
.B read_all_mibs
is called to load all the MIB files found in all the specified
.IR MIBDIRS .
.PP
.B read_mib
parses the file specified, together with any modules that it imports
from, and adds the contents to the active MIB tree.  Such a file can
contain more then one module, though care must be taken that any
imports occur earlier in the file, if they are not to be read from the
installed modules.  Note that the file specified does not need to be
in any of the directories initialised by
.B add_mibdir
(or the default setup), though any imported modules do.
.br
The environment variable
.I MIBFILES
can be set to a (colon-separated) list of files containing MIBs to load.
.PP
.B read_objid
takes a string containing a textual version of an object identifier
(in either numeric or descriptor form), and transforms this into the
corresponding list of sub-identifiers.  This is returned in the
.I output
parameter, with the number of sub-identifiers returned via
.IR out_len .
When called, 
.I out_len
must hold the maximum length of the
.I output
array.
If multiple object identifiers are being processed, then this
length should be reset before each call.
This function returns a value of 1 if it succeeds in parsing the string
and 0 otherwise.
.SS Searching the MIB Tree
.B get_module_node
takes a descriptor and the name of a module, and returns the corresponding
oid list, in the same way as
.B read_objid
above.
.br
If the module name is specified as "ANY", then this routine will
assume that the descriptor given is unique within the tree, and will
return the matching entry.  If this assumption is invalid, then the
behaviour as to which variable is returned is implementation
dependent.
.SS Output
.B print_mib
will print out a representation of the currently active MIB tree to
the specified FILE pointer.
.PP
.B print_variable
will take an object identifier (as returned by
.B read_objid
or
.BR get_module_node )
and an instance of such a variable, and prints to the standard output
the textual form of the object identifier together with the value
of the variable.
.B fprint_variable
does the same, but prints to the FILE pointer specified by the initial
parameter.
.br
.B snprint_variable
prints the same information into the buffer pointed to by
.I buf
which is of length
.IR len 
and returns either the number of characters printed, or -1 if the
buffer was not large enough.  In the latter case,
.I buf
will typically contained a truncated version of the information (but
this behaviour is not guaranteed).  This function replaces the
obsolete function
.BR sprint_variable .
.br
.B sprint_realloc_variable
is the low-level function used to implement all these functions.  It
prints to a specified offset in a string buffer.  The
.I buf
parameter points to a pointer to that buffer;
.I buf_len
points to a variable holding the current size of that buffer, and
.I out_len
points to a variable holding the offset to which to print.
.I out_len
will be updated to hold the offset of the character following the last
one added to the buffer.  If
.I allow_realloc
is 1, the buffer will be dynamically expanded, as necessary, to hold
the output; the variables pointed to by
.I buf
and
.I buf_len
will be updated.  If
.I allow_realloc
is 0, the buffer will not be dynamically expanded.
.B sprint_realloc_variable
returns 0 if
.I allow_realloc
is 1 and an attempt to allocate memory to expand the buffer fails, or
if
.I allow_realloc
is 0 and the output wouldn't fit in the buffer.  Otherwise it returns
1.  When using this function you should be careful to call
.BR free (3)
on
.I *buf
when you have finished with it.
.PP
.BR print_value ,
.BR fprint_value ,
.BR snprint_value
and
.B sprint_realloc_value
do the same as the equivalent
.B print_variable
routines, but only displaying the value of the variable, without the
corresponding object identifier.
.PP
.BR print_objid ,
.BR fprint_objid ,
.BR snprint_objid ,
and
.B sprint_realloc_objid
take an object identifier (without an accompanying variable instance)
and print out the textual representation.
.PP
.BI print_description ,
.BI fprint_description ,
.BI snprint_description ,
and
.B sprint_realloc_description
take an object identifier (as for
.B print_objid
above) and print out a version of the MIB definition for that object,
together with the full OID. The
.I width
argument controls how the OID is layed out.
.PP
By default the parser does not save descriptions since they may be
huge.  In order to be able to print them, you must call
.BR snmp_set_save_descriptions(1) .
.PP
In general the parser is silent about what strangenesses it sees in
the MIB files. To get warnings reported, call
.B snmp_set_mib_warnings
with a
.I level
of 1 (or 2 for even more warnings).
.SH "ENVIRONMENT VARIABLES"
.TP 10
MIBDIRS
A colon separated list of directories to search for MIB modules.
Default: DATADIR/snmp/mibs
.TP 10
MIBFILES
A colon separated list of files to load.
Default: (none)
.TP 10
MIBS
A colon separated list of MIB modules to load.
Default: IP-MIB:IF-MIB:TCP-MIB:UDP-MIB:SNMPv2-MIB: RFC1213-MIB:UCD-SNMP-MIB.
.SH "SEE ALSO"
.BR snmp_api "(3)"