man/mib_api.3

.TH MIB_API 3 "18 Dec 1999"
.UC 5
.SH NAME
init_mib, add_mibdir, init_mib_internals,
read_module, read_mib, read_all_mibs,
read_objid, read_module_node,
print_mib,
print_variable, print_value, print_objid, print_description - mib_api functions
.SH SYNOPSIS
.B "#include <stdio.h>
.br
.B "#include <sys/types.h>
.br
.B "#include <ucd-snmp/asn1.h>
.br
.B #include <ucd-snmp/mib.h>
.br
.B #include <ucd-snmp/parse.h>
.PP
.B "void init_mib( void )
.br
.B "int add_mibdir( char *dirname )
.br
.B "int add_module_replacement( char *old_module, char *new_module, char *tag, int len )
.br
.B "void init_mib_internals( void )
.br
.B "struct tree *read_module( char *name )
.br
.B "struct tree *read_mib( char *filename )
.br
.B "struct tree *read_all_mibs( void )
.PP
.B "void print_mib( FILE *fp)
.PP
.B "int read_objid( char *input, oid *output, int *out_len)
.br
.B "int get_module_node( char *name, char *module, oid *objid, int *objidlen )
.PP
.B "void print_variable( oid *objid, int objidlen, struct variable_list *variable)
.br
.B "void print_value( oid *objid, int objidlen, struct variable_list *variable)
.br
.B "void print_objid( oid *objid, int objidlen);
.br
.B "void print_description( oid *objid, int objidlen);
.br
.B "void snmp_set_mib_warnings( int );
.br
.B "void snmp_set_save_descriptions( int );
.PP
.SH DESCRIPTION
The functions dealing with MIB modules fall into four groups.
Those dealing with initialisation, those that read in and parse MIB files,
those that search the MIB tree, and various output routines.

.I init_mib
is a convenience function that handles all calls to
.I add_mibdir, read_module
and
.I 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.

.I 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.  

.I init_mib_internals
sets up the internal structures, preparatory to reading in MIB modules.
It should be called after all calls to
.IR add_mibdir ,
and before and calls to
.IR read_module .
This is called automatically if
.I init_mib
is used.

.I 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
.I RFC1213-MIB
).

.I 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
.I 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 ,
.I read_all_mibs
is called to load all the MIB files found in all the specified
.IR MIBDIRS .


.I 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
.I 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.

.I 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, out_len must hold the maximum length of the
.I output
array.
This function returns a value of 1 if it succeeds in parsing the string
and 0 otherwise.

.I get_module_node
takes a descriptor and the name of a module, and returns the corresponding
oid list, in the same way as
.I 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.

.I print_mib
will print out a representation of the currently active MIB tree to
the specified FILE pointer.

.I print_variable
will take an object identifier (as returned by
.I read_objid
or
.I get_module_node
) and an instance of such a variable, and prints out
the textual form of the object identifier together with the value
of the variable.
.br
A related routine
.I sprint_variable
takes an initial parameter of a string buffer, in which to print this
information.

.I print_value
and
.I sprint_value
do the same as the equivalent
.I print_variable
routines, but only displaying the value of the variable, without
the corresponding object identifier>

.I print_objid
and
.I sprint_objid
.br
take an object identifier (without an accompanying variable instance)
and print out the textual representation.
.br
Note that identifiers lying within the mib-2, experimental
or private subtrees are listed from this point onwards,
rather than with the full object identifier.

.I print_description
takes an object identifier (as for
.I print_objid
above) and prints out the associated description.
.b
Note that there is no corresponding routine
.I sprint_description

By default the parser does not save descriptions - they may be huge.
In order to be able to print them, you must call
.IR "snmp_set_save_descriptions(1)" .

In general the parser is silent about what strangenesses it sees
in the mib files. To get warnings reported, call
.I snmp_set_mib_warnings
with a parameter of \fI1\fR (or \fI2\fR for even more warnings).

.SH "ENVIRONMENT VARIABLES"
.TP 10
MIBDIRS
A colon separated list of directories to search for MIB modules.
Default: LIBDIR/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"
snmp_api(3)