MIBAPI(3) Net-SNMP MIBAPI(3)
NAME
initmib, addmibdir, initmibinternals, addmodulereplacement,
readmodule, readmib, readallmibs, readobjid, readmodulenode,
getmodulenode, snmpsetmibwarnings, snmpsetsavedescriptions,
shutdownmib, printmib, printvariable, fprintvariable, snprintvari-
able, sprintreallocvariable, printvalue, fprintvalue,
snprintvalue, sprintreallocvalue, printobjid, fprintobjid,
snprintobjid, sprintreallocobjid, printdescription, fprintdescrip-
tion - mibapi functions
SYNOPSIS
##include <>
void initmib(void);;
int addmibdir(char **dirname);;
int addmodulereplacement(char **oldmodule,, char **newmodule,, char
**tag,, int len);;
void initmibinternals(void);;
struct tree **readmodule(char **name);;
struct tree **readmib(char **filename);;
struct tree **readallmibs(void);;
void shutdownmib(void);;
void printmib(FILE **fp);;
int readobjid(char **input,, oid **output,, sizet **outlen);;
int getmodulenode(const char **name,, const char **module,, oid **objid,,
sizet **objidlen);;
void printvariable(const oid **objid,, sizet objidlen,, const net-
snmpvariablelist **variable);;
void fprintvariable(FILE **fp,, const oid **objid,, sizet objidlen,, const
netsnmpvariablelist **variable);;
int snprintvariable(char **buf,, sizet len,, const oid **objid,, sizet
objidlen,, const netsnmpvariablelist **variable);;
int sprintreallocvariable(uchar ****buf,, sizet **buflen,, sizet
**outlen,, int allowrealloc,, const oid **objid,, sizet objidlen,, const
netsnmpvariablelist **variable);;
void printvalue(oid **objid,, sizet objidlen,, const netsnmpvari-
ablelist **variable)
void fprintvalue(FILE **fp,, const oid **objid,, sizet objidlen,, const
netsnmpvariablelist **variable);;
int snprintvalue(char **buf,, sizet len,, const oid **objid,, sizet obji-
dlen,, const netsnmpvariablelist **variable);;
int sprintreallocvalue(uchar ****buf,, sizet **buflen,, sizet
**outlen,, int allowrealloc,, const oid **objid,, sizet objidlen,, const
netsnmpvariablelist **variable);;
void printobjid(const oid **objid,, sizet objidlen);;
void fprintobjid(FILE **fp,, const oid **objid,, sizet objidlen);;
int snprintobjid(char **buf,, sizet len,, const oid **objid,, sizet obji-
dlen);;
int sprintreallocobjid(uchar ****buf,, sizet **buflen,, sizet
**outlen,, int allowrealloc,, const oid **objid,, sizet objidlen);;
void printdescription(oid **objid,, sizet objidlen,, int width);;
void fprintdescription(FILE **fp,, const oid **objid,, sizet objidlen,,
int width);;
void snmpsetmibwarnings(int level);;
void snmpsetsavedescriptions(int save);;
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.
Initialisation and Shutdown
initmib is a convenience function that handles all calls to addmib-
dir, readmodule and readmib 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.
addmibdir 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 /usr/share/mibs but this can
be overridden by setting the environment variable 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 ini-
tialisation step to make them available. This function returns a count
of files found in the directory, or a -1 if there is an error.
initmibinternals sets up the internal structures, preparatory to
reading in MIB modules. It should be called after all calls to
addmibdir, and before and calls to readmodule. This is called auto-
matically if initmib is used.
shutdownmib will clear the information that was gathered by readmod-
ule, addmibdir and addmodulereplacement. It is strongly recommended
that one does not invoke shutdownmib while there are SNMP sessions
being actively managed.
Reading and Parsing MIBs
addmodulereplacement can be used to allow new MIB modules to obsolete
older ones, without needing to amend the imports clauses of other mod-
ules. It takes the names of the old and new modules, together with an
indication of which portions of the old module are affected.
tag len load the new module when::
NUL 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
It can also be used to handle errors in the module identifiers used in
MIB import clauses (such as referring to RFC1213 instead of
RFC1213-MIB).
readmodule 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 addmibdir must first be called to add
the directory containing the file with the module definition, if this
is not in the standard path.
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 MIBS to a (colon-sepa-
rated) 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 oth-
ers they import from). If MIBS is set to AL, readallmibs is called
to load all the MIB files found in all the specified MIBDIRS.
readmib 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 addmibdir (or the default
setup), though any imported modules do.
The environment variable MIBFILES can be set to a (colon-separated)
list of files containing MIBs to load.
readobjid 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 output parameter, with the number of sub-identifiers returned via
outlen. When called, outlen must hold the maximum length of the out-
put array. This function returns a value of 1 if it succeeds in pars-
ing the string and 0 otherwise.
Searching the MIB Tree
getmodulenode takes a descriptor and the name of a module, and
returns the corresponding oid list, in the same way as readobjid
above.
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.
Output
printmib will print out a representation of the currently active MIB
tree to the specified FILE pointer.
printvariable will take an object identifier (as returned by
readobjid or getmodulenode) 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. fprintvariable does the
same, but prints to the FILE pointer specified by the initial parame-
ter.
snprintvariable prints the same information into the buffer pointed to
by buf which is of length len and returns either the number of charac-
ters printed, or -1 if the buffer was not large enough. In the latter
case, buf will typically contained a truncated version of the informa-
tion (but this behaviour is not guaranteed). This function replaces
the obsolete function sprintvariable.
sprintreallocvariable is the low-level function used to implement all
these functions. It prints to a specified offset in a string buffer.
The buf parameter points to a pointer to that buffer; buflen points to
a variable holding the current size of that buffer, and outlen points
to a variable holding the offset to which to print. outlen will be
updated to hold the offset of the character following the last one
added to the buffer. If allowrealloc is 1, the buffer will be dynami-
cally expanded, as necessary, to hold the output; the variables pointed
to by buf and buflen will be updated. If allowrealloc is 0, the
buffer will not be dynamically expanded. sprintreallocvariable
returns 0 if allowrealloc is 1 and an attempt to allocate memory to
expand the buffer fails, or if allowrealloc 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 free(3) on *buf when you have
finished with it.
printvalue, fprintvalue, snprintvalue and sprintreallocvalue do
the same as the equivalent printvariable routines, but only displaying
the value of the variable, without the corresponding object identifier.
printobjid, fprintobjid, snprintobjid, and sprintreallocobjid take
an object identifier (without an accompanying variable instance) and
print out the textual representation.
printdescription and fprintdescription take an object identifier (as
for printobjid above) and print out the associated DESCRIPTION clause.
The width argument gives the number of subidentifiers of an OID, e.g.,
.1.3.6 is composed of 3 subidentifiers.
Note that there are no corresponding routines snprintdescription or
sprintreallocdescription. By default the parser does not save
descriptions since they may be huge. In order to be able to print
them, you must call snmpsetsavedescriptions(1).
In general the parser is silent about what strangenesses it sees in the
MIB files. To get warnings reported, call snmpsetmibwarnings with a
level of 1 (or 2 for even more warnings).
ENVIRONMENT VARIABLES
MIBDIRS A colon separated list of directories to search for MIB mod-
ules. Default: /usr/share/snmp/mibs
MIBFILES A colon separated list of files to load. Default: (none)
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.
SEE ALSO
snmpapi(3)
4.2 Berkeley Distribution 06 Mar 2002 MIBAPI(3)
|
