|
Packit |
fcad23 |
.TH NETSNMP_MIB_API 3 "13 Aug 2010" VVERSIONINFO "Net-SNMP"
|
|
Packit |
fcad23 |
.SH NAME
|
|
Packit |
fcad23 |
add_mibdir,
|
|
Packit |
fcad23 |
netsnmp_init_mib,
|
|
Packit |
fcad23 |
shutdown_mib,
|
|
Packit |
fcad23 |
netsnmp_read_module,
|
|
Packit |
fcad23 |
read_mib,
|
|
Packit |
fcad23 |
read_all_mibs,
|
|
Packit |
fcad23 |
add_module_replacement,
|
|
Packit |
fcad23 |
snmp_set_mib_errors,
|
|
Packit |
fcad23 |
snmp_set_mib_warnings,
|
|
Packit |
fcad23 |
snmp_set_save_descriptions,
|
|
Packit |
fcad23 |
read_objid,
|
|
Packit |
fcad23 |
snmp_parse_oid,
|
|
Packit |
fcad23 |
get_module_node,
|
|
Packit |
fcad23 |
print_mib,
|
|
Packit |
fcad23 |
print_objid,
|
|
Packit |
fcad23 |
fprint_objid,
|
|
Packit |
fcad23 |
snprint_objid,
|
|
Packit |
fcad23 |
print_description,
|
|
Packit |
fcad23 |
fprint_description,
|
|
Packit |
fcad23 |
snprint_description - netsnmp_mib_api functions
|
|
Packit |
fcad23 |
.SH SYNOPSIS
|
|
Packit |
fcad23 |
.B #include <net\-snmp/mib_api.h>
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.SS Initialisation and Shutdown
|
|
Packit |
fcad23 |
.BI "int add_mibdir(const char *" "dirname" );
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.B "void netsnmp_init_mib(void);
|
|
Packit |
fcad23 |
.\".br
|
|
Packit |
fcad23 |
.\".BI "void init_mib(void);" " (deprecated)"
|
|
Packit |
fcad23 |
.\".br
|
|
Packit |
fcad23 |
.\".BI "void init_mib_internals(void);" " (deprecated)"
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.B "void shutdown_mib(void);
|
|
Packit |
fcad23 |
.SS Reading and Parsing MIBs
|
|
Packit |
fcad23 |
.BI "struct tree *netsnmp_read_module(const char *" "name" );
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.\".BI "struct tree *read_module(const char *" "name" ");" " (deprecated)"
|
|
Packit |
fcad23 |
.\".PP
|
|
Packit |
fcad23 |
.BI "struct tree *read_mib(const char *" "filename" );
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.B "struct tree *read_all_mibs(void);
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.BI "int add_module_replacement(const char *" "old_module" ","
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI " const char *" "new_module" ","
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI " const char *" "tag" ", int " "len" );
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.BI "void snmp_set_mib_warnings(int " level );
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI "void snmp_set_mib_errors(int " level );
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI "void snmp_set_save_descriptions(int " save ");"
|
|
Packit |
fcad23 |
.SS Searching the MIB Tree
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.BI "int read_objid(const char *" "input" ","
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI " oid *" "objid" ", size_t *" "objidlen" );
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI "oid *snmp_parse_oid(const char *" "input" ","
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI " oid *" "objid" ", size_t *" "objidlen" );
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI "int get_module_node(const char *" "name" ", const char *" "module" ","
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI " oid *" "objid" ", size_t *" "objidlen" );
|
|
Packit |
fcad23 |
.SS Output
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.BI "void print_mib(FILE *" "fp" );
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.BI "void print_objid(const oid *" objid ", size_t " objidlen );
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI "void fprint_objid(FILE *" fp ","
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI " const oid *" objid ", size_t " objidlen ");"
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI "int snprint_objid(char *" buf ", size_t " "len" ","
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI " const oid *" objid ", size_t " objidlen ");"
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.BI "void print_description(const oid *" objid ", size_t " objidlen ", int " width );
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI "void fprint_description(FILE *" fp ","
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI " const oid *" objid ", size_t " objidlen ", int " width );
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI "int snprint_description(char *" buf ", size_t " "len" ","
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.BI " const oid *" objid ", size_t " objidlen ", int " width );
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.SH DESCRIPTION
|
|
Packit |
fcad23 |
The functions dealing with MIB modules fall into four groups - those
|
|
Packit |
fcad23 |
dealing with initialisation and shutdown, with reading in and parsing
|
|
Packit |
fcad23 |
MIB files, with searching the MIB tree, and output routines.
|
|
Packit |
fcad23 |
.SS Initialisation and Shutdown
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.B add_mibdir
|
|
Packit |
fcad23 |
is used to add the specified directory to the path of locations which are
|
|
Packit |
fcad23 |
searched for files containing MIB modules.
|
|
Packit |
fcad23 |
Note that this does not actually load the MIB modules located
|
|
Packit |
fcad23 |
in that directory, but is simply an initialisation step to make
|
|
Packit |
fcad23 |
them available to
|
|
Packit |
fcad23 |
.BR netsnmp_read_module .
|
|
Packit |
fcad23 |
This function returns a count of files found in the directory, or a \-1
|
|
Packit |
fcad23 |
if there is an error.
|
|
Packit |
fcad23 |
It should be called \fIbefore\fP invoking \fBnetsnmp_init_mib\fP.
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.\".B init_mib_internals
|
|
Packit |
fcad23 |
.\"sets up the internal structures, preparatory to reading in MIB
|
|
Packit |
fcad23 |
.\"modules. It should be called \fIafter\fP all calls to
|
|
Packit |
fcad23 |
.\".BR add_mibdir ,
|
|
Packit |
fcad23 |
.\"and before any calls to
|
|
Packit |
fcad23 |
.\".BR netsnmp_read_module .
|
|
Packit |
fcad23 |
.\".PP
|
|
Packit |
fcad23 |
.B netsnmp_init_mib
|
|
Packit |
fcad23 |
configures the MIB directory search path (using
|
|
Packit |
fcad23 |
.B add_mibdir
|
|
Packit |
fcad23 |
), sets up the internal MIB framework,
|
|
Packit |
fcad23 |
and then loads the appropriate MIB modules (using
|
|
Packit |
fcad23 |
.BR netsnmp_read_module " and " read_mib ")."
|
|
Packit |
fcad23 |
See the ENVIRONMENTAL VARIABLES section for details.
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
It should be called before any other
|
|
Packit |
fcad23 |
routine that manipulates or accesses the MIB tree
|
|
Packit |
fcad23 |
(but after any additional
|
|
Packit |
fcad23 |
.B add_mibdir
|
|
Packit |
fcad23 |
calls).
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.B shutdown_mib
|
|
Packit |
fcad23 |
will clear the information that was gathered by
|
|
Packit |
fcad23 |
.BR netsnmp_read_module ", " add_mibdir " and " add_module_replacement .
|
|
Packit |
fcad23 |
It is strongly recommended that one does not invoke
|
|
Packit |
fcad23 |
.BR shutdown_mib
|
|
Packit |
fcad23 |
while there are SNMP sessions being actively managed.
|
|
Packit |
fcad23 |
.SS Reading and Parsing MIBs
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.B netsnmp_read_module
|
|
Packit |
fcad23 |
takes the name of a MIB module (which need not be the same as the
|
|
Packit |
fcad23 |
name of the file that contains the module), locates this within the
|
|
Packit |
fcad23 |
configured list of MIB directories, and loads the definitions from
|
|
Packit |
fcad23 |
the module into the active MIB tree.
|
|
Packit |
fcad23 |
It also loads any MIB modules listed in the IMPORTS clause of this module.
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.B read_mib
|
|
Packit |
fcad23 |
is similar, but takes the name of the file containing the MIB module.
|
|
Packit |
fcad23 |
Note that this file need not be located within the MIB directory
|
|
Packit |
fcad23 |
search list (although any modules listed in the IMPORTS clause do).
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.B read_all_mibs
|
|
Packit |
fcad23 |
will read in all the MIB modules found on the MIB directory search list.
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
In general the parser is silent about what strangenesses it sees in
|
|
Packit |
fcad23 |
the MIB files. To get warnings reported, call
|
|
Packit |
fcad23 |
.B snmp_set_mib_warnings
|
|
Packit |
fcad23 |
with a
|
|
Packit |
fcad23 |
.I level
|
|
Packit |
fcad23 |
of 1 (or 2 for even more warnings).
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.B add_module_replacement
|
|
Packit |
fcad23 |
can be used to allow new MIB modules to obsolete older ones, without
|
|
Packit |
fcad23 |
needing to amend the IMPORTS clauses of other modules. It takes the
|
|
Packit |
fcad23 |
names of the old and new modules, together with an indication of which
|
|
Packit |
fcad23 |
portions of the old module are affected.
|
|
Packit |
fcad23 |
.RS
|
|
Packit |
fcad23 |
.TS
|
|
Packit |
fcad23 |
tab(+);
|
|
Packit |
fcad23 |
lb lb lb
|
|
Packit |
fcad23 |
l l l.
|
|
Packit |
fcad23 |
tag + len + load the new module when:
|
|
Packit |
fcad23 |
NULL + 0 + always (the old module is a strict subset of
|
|
Packit |
fcad23 |
+ + the new)
|
|
Packit |
fcad23 |
name + 0 + for the given tag only
|
|
Packit |
fcad23 |
name + non-0 + for any identifier with this prefix
|
|
Packit |
fcad23 |
.TE
|
|
Packit |
fcad23 |
.RE
|
|
Packit |
fcad23 |
It can also be used to handle errors in the module identifiers used
|
|
Packit |
fcad23 |
in MIB IMPORTS clauses (such as referring to
|
|
Packit |
fcad23 |
.I RFC1213
|
|
Packit |
fcad23 |
instead of
|
|
Packit |
fcad23 |
.IR RFC1213\-MIB ).
|
|
Packit |
fcad23 |
.SS Searching the MIB Tree
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.B read_objid
|
|
Packit |
fcad23 |
takes a string containing a textual version of an object identifier
|
|
Packit |
fcad23 |
(in either numeric or descriptor form), and transforms this into the
|
|
Packit |
fcad23 |
corresponding list of sub-identifiers. This is returned in the
|
|
Packit |
fcad23 |
.I output
|
|
Packit |
fcad23 |
parameter, with the number of sub-identifiers returned via
|
|
Packit |
fcad23 |
.IR out_len .
|
|
Packit |
fcad23 |
When called,
|
|
Packit |
fcad23 |
.I out_len
|
|
Packit |
fcad23 |
must hold the maximum length of the
|
|
Packit |
fcad23 |
.I output
|
|
Packit |
fcad23 |
array.
|
|
Packit |
fcad23 |
If multiple object identifiers are being processed, then this
|
|
Packit |
fcad23 |
length should be reset before each call.
|
|
Packit |
fcad23 |
This function returns a value of 1 if it succeeds in parsing the string
|
|
Packit |
fcad23 |
and 0 otherwise.
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.B snmp_parse_oid
|
|
Packit |
fcad23 |
is similar, but returns a pointer to the parsed OID buffer (or NULL).
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.B get_module_node
|
|
Packit |
fcad23 |
takes a descriptor and the name of a module, and returns the corresponding
|
|
Packit |
fcad23 |
oid list, in the same way as
|
|
Packit |
fcad23 |
.B read_objid
|
|
Packit |
fcad23 |
above.
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
If the module name is specified as "ANY", then this routine will
|
|
Packit |
fcad23 |
assume that the descriptor given is unique within the tree, and will
|
|
Packit |
fcad23 |
return the matching entry. If this assumption is invalid, then the
|
|
Packit |
fcad23 |
behaviour as to which variable is returned is implementation
|
|
Packit |
fcad23 |
dependent.
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
.SS Output
|
|
Packit |
fcad23 |
.B print_mib
|
|
Packit |
fcad23 |
will print out a representation of the currently active MIB tree to
|
|
Packit |
fcad23 |
the specified FILE pointer.
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.B print_objid
|
|
Packit |
fcad23 |
will take an object identifier (as returned by
|
|
Packit |
fcad23 |
.BR read_objid ", " snmp_parse_oid " or " get_module_node "),"
|
|
Packit |
fcad23 |
and prints the textual form of this OID to the standard output.
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.B fprint_objid
|
|
Packit |
fcad23 |
does the same, but prints to the FILE pointer specified by the initial
|
|
Packit |
fcad23 |
parameter.
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.B snprint_objid
|
|
Packit |
fcad23 |
prints the same information into the buffer pointed to by
|
|
Packit |
fcad23 |
.I buf
|
|
Packit |
fcad23 |
which is of length
|
|
Packit |
fcad23 |
.IR len .
|
|
Packit |
fcad23 |
It returns the number of characters printed, or \-1 if the
|
|
Packit |
fcad23 |
buffer was not large enough. In the latter case,
|
|
Packit |
fcad23 |
.I buf
|
|
Packit |
fcad23 |
will typically contain a truncated version of the information (but
|
|
Packit |
fcad23 |
this behaviour is not guaranteed).
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
.BR print_description ,
|
|
Packit |
fcad23 |
.BR fprint_description ,
|
|
Packit |
fcad23 |
and
|
|
Packit |
fcad23 |
.B snprint_description
|
|
Packit |
fcad23 |
take a similar object identifier
|
|
Packit |
fcad23 |
and print out a version of the MIB definition for that object,
|
|
Packit |
fcad23 |
together with the full OID. The
|
|
Packit |
fcad23 |
.I width
|
|
Packit |
fcad23 |
argument controls how the OID is layed out.
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
By default the parser does not save descriptions since they may be
|
|
Packit |
fcad23 |
huge. In order to be able to print them, it is necessary to invoke
|
|
Packit |
fcad23 |
.BI snmp_set_save_descriptions(1) before
|
|
Packit |
fcad23 |
calling
|
|
Packit |
fcad23 |
.B init_mib
|
|
Packit |
fcad23 |
(or similar).
|
|
Packit |
fcad23 |
.SH "ENVIRONMENT VARIABLES"
|
|
Packit |
fcad23 |
.PP
|
|
Packit |
fcad23 |
The main use of environmental variables with respect to these API calls
|
|
Packit |
fcad23 |
is to configure which MIB modules should be loaded, and where they are
|
|
Packit |
fcad23 |
located.
|
|
Packit |
fcad23 |
.TP 10
|
|
Packit |
fcad23 |
MIBDIRS
|
|
Packit |
fcad23 |
A colon separated list of directories to search for MIB modules.
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
Default: DATADIR/snmp/mibs
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
Used by
|
|
Packit |
fcad23 |
.BR init_mib ", " netsnmp_read_module ", " read_all_mibs
|
|
Packit |
fcad23 |
and (implicitly) by
|
|
Packit |
fcad23 |
.BR read_mib .
|
|
Packit |
fcad23 |
.TP 10
|
|
Packit |
fcad23 |
MIBS
|
|
Packit |
fcad23 |
A colon separated list of MIB modules to load.
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
The default list of modules will depend on how the Net-SNMP software
|
|
Packit |
fcad23 |
was originally compiled, but is typically:
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
IP\-MIB:\:IF\-MIB:\:TCP\-MIB:\:UDP\-MIB:\:SNMPv2\-MIB:\:RFC1213\-MIB:\:UCD\-SNMP\-MIB:\:HOST\-RESOURCES\-MIB
|
|
Packit |
fcad23 |
.IP
|
|
Packit |
fcad23 |
If the value of the
|
|
Packit |
fcad23 |
.B MIBS
|
|
Packit |
fcad23 |
environmental variable starts with a '+' character,
|
|
Packit |
fcad23 |
then these MIB modules will be added to the default list.
|
|
Packit |
fcad23 |
Otherwise these modules (plus any that they IMPORT from) will be loaded
|
|
Packit |
fcad23 |
.I instead
|
|
Packit |
fcad23 |
of the default list.
|
|
Packit |
fcad23 |
.IP
|
|
Packit |
fcad23 |
If the
|
|
Packit |
fcad23 |
.B MIBS
|
|
Packit |
fcad23 |
environmental variable has the value
|
|
Packit |
fcad23 |
.BR ALL " then " read_all_mibs
|
|
Packit |
fcad23 |
will be called to load the full collection of all available MIB modules.
|
|
Packit |
fcad23 |
.IP
|
|
Packit |
fcad23 |
Used by
|
|
Packit |
fcad23 |
.B init_mib
|
|
Packit |
fcad23 |
only.
|
|
Packit |
fcad23 |
.TP 10
|
|
Packit |
fcad23 |
MIBFILES
|
|
Packit |
fcad23 |
A colon separated list of files to load.
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
Default: (none)
|
|
Packit |
fcad23 |
.br
|
|
Packit |
fcad23 |
Used by
|
|
Packit |
fcad23 |
.B init_mib
|
|
Packit |
fcad23 |
only.
|
|
Packit |
fcad23 |
.SH "SEE ALSO"
|
|
Packit |
fcad23 |
netsnmp_session_api(3), netsnmp_pdu_api(3), netsnmp_varbind_api(3)
|