diff options
Diffstat (limited to 'man/mib_api.3.def')
| -rw-r--r-- | man/mib_api.3.def | 322 |
1 files changed, 322 insertions, 0 deletions
diff --git a/man/mib_api.3.def b/man/mib_api.3.def new file mode 100644 index 0000000..2818273 --- /dev/null +++ b/man/mib_api.3.def @@ -0,0 +1,322 @@ +.TH MIB_API 3 "06 Mar 2002" VVERSIONINFO "Net-SNMP" +.UC 5 +.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)" |