1MIB_API(3) Net-SNMP MIB_API(3)
2
6 init_mib, add_mibdir, init_mib_internals, add_module_replacement,
7 read_module, read_mib, read_all_mibs, read_objid, read_module_node,
8 get_module_node, snmp_set_mib_warnings, snmp_set_save_descriptions,
9 shutdown_mib, print_mib, print_variable, fprint_variable, snprint_vari‐
10 able, sprint_realloc_variable, print_value, fprint_value,
11 snprint_value, sprint_realloc_value, print_objid, fprint_objid,
12 snprint_objid, sprint_realloc_objid, print_description, fprint_descrip‐
13 tion - mib_api functions
14
16 #include <net-snmp/mib_api.h>
17 void init_mib(void);
19 int add_mibdir(const char *dirname);
20 int add_module_replacement(const char *old_module, const char *new_mod‐
21 ule, const char *tag, int len);
22 void init_mib_internals(void);
23 struct tree *read_module(const char *name);
24 struct tree *read_mib(const char *filename);
25 struct tree *read_all_mibs(void);
26 void shutdown_mib(void);
28 void print_mib(FILE *fp);
30 int read_objid(const char *input, oid *output, size_t *out_len);
32 int get_module_node(const char *name, const char *module, oid *objid,
33 size_t *objidlen);
34 void print_variable(const oid *objid, size_t objidlen, const net‐
36 snmp_variable_list *variable);
37 void fprint_variable(FILE *fp, const oid *objid, size_t objidlen, const
38 netsnmp_variable_list *variable);
39 int snprint_variable(char *buf, size_t len, const oid *objid, size_t
40 objidlen, const netsnmp_variable_list *variable);
41 int sprint_realloc_variable(u_char **buf, size_t *buf_len, size_t
42 *out_len, int allow_realloc, const oid *objid, size_t objidlen, const
43 netsnmp_variable_list *variable);
44 void print_value(oid *objid, size_t objidlen, const netsnmp_vari‐
46 able_list *variable)
47 void fprint_value(FILE *fp, const oid *objid, size_t objidlen, const
48 netsnmp_variable_list *variable);
49 int snprint_value(char *buf, size_t len, const oid *objid, size_t obji‐
50 dlen, const netsnmp_variable_list *variable);
51 int sprint_realloc_value(u_char **buf, size_t *buf_len, size_t
52 *out_len, int allow_realloc, const oid *objid, size_t objidlen, const
53 netsnmp_variable_list *variable);
54 void print_objid(const oid *objid, size_t objidlen);
56 void fprint_objid(FILE *fp, const oid *objid, size_t objidlen);
57 int snprint_objid(char *buf, size_t len, const oid *objid, size_t obji‐
58 dlen);
59 int sprint_realloc_objid(u_char **buf, size_t *buf_len, size_t
60 *out_len, int allow_realloc, const oid *objid, size_t objidlen);
61 void print_description(oid *objid, size_t objidlen, int width);
63 void fprint_description(FILE *fp, const oid *objid, size_t objidlen,
64 int width);
65 void snmp_set_mib_warnings(int level);
67 void snmp_set_save_descriptions(int save);
68
70 The functions dealing with MIB modules fall into four groups. Those
71 dealing with initialisation and shutdown, those that read in and parse
72 MIB files, those that search the MIB tree, and various output routines.
73 Initialisation and Shutdown
75 init_mib is a convenience function that handles all calls to add_mib‐
76 dir, read_module and read_mib for standard applications. It should be
77 called before any other routine that manipulates or accesses the MIB
78 tree. This routine sets up various internal structures, as well as
79 reading in the default MIB modules, as detailed below.
80 add_mibdir is used to define the range of directory locations which are
82 searched for files containing MIB modules (one module per file). By
83 default, this will be set to the directory /usr/share/mibs but this can
84 be overridden by setting the environment variable MIBDIRS to a (colon-
85 separated) list of directories to search. Note that this does not
86 actually load the MIB modules located in that directory, but is an ini‐
87 tialisation step to make them available. This function returns a count
88 of files found in the directory, or a -1 if there is an error.
89 init_mib_internals sets up the internal structures, preparatory to
91 reading in MIB modules. It should be called after all calls to
92 add_mibdir, and before and calls to read_module. This is called auto‐
93 matically if init_mib is used.
94 shutdown_mib will clear the information that was gathered by read_mod‐
96 ule, add_mibdir and add_module_replacement. It is strongly recommended
97 that one does not invoke shutdown_mib while there are SNMP sessions
98 being actively managed.
99 Reading and Parsing MIBs
101 add_module_replacement can be used to allow new MIB modules to obsolete
102 older ones, without needing to amend the imports clauses of other mod‐
103 ules. It takes the names of the old and new modules, together with an
104 indication of which portions of the old module are affected.
105 tag len load the new module when:
107 NULL 0 always (the old module is a strict subset of the new)
108 name 0 for the given tag only
109 name non-0 for any identifier with this prefix
110 It can also be used to handle errors in the module identifiers used in
111 MIB import clauses (such as referring to RFC1213 instead of
112 RFC1213-MIB).
113 read_module locates and parses the module specified, together with any
115 modules that it imports from, and adds the contents of these modules to
116 the active MIB tree. Note that add_mibdir must first be called to add
117 the directory containing the file with the module definition, if this
118 is not in the standard path.
119 By default, the following MIB modules will be loaded: IP-MIB, IF-MIB,
120 TCP-MIB, UDP-MIB, SNMPv2-MIB, RFC1213-MIB, UCD-SNMP-MIB. This can be
121 overridden by setting the environment variable MIBS to a (colon-sepa‐
122 rated) list of modules to load. If this variable starts with a plus
123 character, then the specified modules are added to the default list.
124 Otherwise only those modules listed are loaded (together with any oth‐
125 ers they import from). If MIBS is set to ALL, read_all_mibs is called
126 to load all the MIB files found in all the specified MIBDIRS.
127 read_mib parses the file specified, together with any modules that it
129 imports from, and adds the contents to the active MIB tree. Such a
130 file can contain more then one module, though care must be taken that
131 any imports occur earlier in the file, if they are not to be read from
132 the installed modules. Note that the file specified does not need to
133 be in any of the directories initialised by add_mibdir (or the default
134 setup), though any imported modules do.
135 The environment variable MIBFILES can be set to a (colon-separated)
136 list of files containing MIBs to load.
137 read_objid takes a string containing a textual version of an object
139 identifier (in either numeric or descriptor form), and transforms this
140 into the corresponding list of sub-identifiers. This is returned in
141 the output parameter, with the number of sub-identifiers returned via
142 out_len. When called, out_len must hold the maximum length of the out‐
143 put array. This function returns a value of 1 if it succeeds in pars‐
144 ing the string and 0 otherwise.
145 Searching the MIB Tree
147 get_module_node takes a descriptor and the name of a module, and
148 returns the corresponding oid list, in the same way as read_objid
149 above.
150 If the module name is specified as "ANY", then this routine will assume
151 that the descriptor given is unique within the tree, and will return
152 the matching entry. If this assumption is invalid, then the behaviour
153 as to which variable is returned is implementation dependent.
154 Output
156 print_mib will print out a representation of the currently active MIB
157 tree to the specified FILE pointer.
158 print_variable will take an object identifier (as returned by
160 read_objid or get_module_node) and an instance of such a variable, and
161 prints to the standard output the textual form of the object identifier
162 together with the value of the variable. fprint_variable does the
163 same, but prints to the FILE pointer specified by the initial parame‐
164 ter.
165 snprint_variable prints the same information into the buffer pointed to
166 by buf which is of length len and returns either the number of charac‐
167 ters printed, or -1 if the buffer was not large enough. In the latter
168 case, buf will typically contained a truncated version of the informa‐
169 tion (but this behaviour is not guaranteed). This function replaces
170 the obsolete function sprint_variable.
171 sprint_realloc_variable is the low-level function used to implement all
172 these functions. It prints to a specified offset in a string buffer.
173 The buf parameter points to a pointer to that buffer; buf_len points to
174 a variable holding the current size of that buffer, and out_len points
175 to a variable holding the offset to which to print. out_len will be
176 updated to hold the offset of the character following the last one
177 added to the buffer. If allow_realloc is 1, the buffer will be dynami‐
178 cally expanded, as necessary, to hold the output; the variables pointed
179 to by buf and buf_len will be updated. If allow_realloc is 0, the buf‐
180 fer will not be dynamically expanded. sprint_realloc_variable returns
181 0 if allow_realloc is 1 and an attempt to allocate memory to expand the
182 buffer fails, or if allow_realloc is 0 and the output wouldn't fit in
183 the buffer. Otherwise it returns 1. When using this function you
184 should be careful to call free(3) on *buf when you have finished with
185 it.
186 print_value, fprint_value, snprint_value and sprint_realloc_value do
188 the same as the equivalent print_variable routines, but only displaying
189 the value of the variable, without the corresponding object identifier.
190 print_objid, fprint_objid, snprint_objid, and sprint_realloc_objid take
192 an object identifier (without an accompanying variable instance) and
193 print out the textual representation.
194 print_description and fprint_description take an object identifier (as
196 for print_objid above) and print out the associated DESCRIPTION clause.
197 The width argument gives the number of subidentifiers of an OID, e.g.,
198 .1.3.6 is composed of 3 subidentifiers.
199 Note that there are no corresponding routines snprint_description or
201 sprint_realloc_description. By default the parser does not save
202 descriptions since they may be huge. In order to be able to print
203 them, you must call snmp_set_save_descriptions(1).
204 In general the parser is silent about what strangenesses it sees in the
206 MIB files. To get warnings reported, call snmp_set_mib_warnings with a
207 level of 1 (or 2 for even more warnings).
208
210 MIBDIRS A colon separated list of directories to search for MIB mod‐
211 ules. Default: /usr/share/snmp/mibs
212 MIBFILES A colon separated list of files to load. Default: (none)
214 MIBS A colon separated list of MIB modules to load. Default: IP-
216 MIB:IF-MIB:TCP-MIB:UDP-MIB:SNMPv2-MIB:RFC1213-MIB:UCD-SNMP-
217 MIB.
218
220 snmp_api(3)
2214.2 Berkeley Distribution 06 Mar 2002 MIB_API(3)