--- name: "mib_api" section: "3snmp" platform: "linux" package: "libsnmp-dev" version: "5.4.3~dfsg-2.8+deb7u1" release: "Debian 7 (Wheezy)" platforms: ["linux"] url: "https://new.carta.tech/mib_api/3snmp" --- # mib\_api(3snmp) mib\_api functions ## 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 ## SYNOPSIS **#include \** **void init\_mib(void);**\ **int add\_mibdir(const char \****dirname***);**\ **int add\_module\_replacement(const char \****old\_module***, const char \****new\_module***, const char \****tag***, int** *len***);**\ **void init\_mib\_internals(void);**\ **struct tree \*read\_module(const char \****name***);**\ **struct tree \*read\_mib(const char \****filename***);**\ **struct tree \*read\_all\_mibs(void);** **void shutdown\_mib(void);** **void print\_mib(FILE \****fp***);** **int read\_objid(const char \****input***, oid \****output***, size\_t \****out\_len***);**\ **int get\_module\_node(const char \****name***, const char \****module***, oid \****objid***, size\_t \****objidlen***);** **void print\_variable(const oid \****objid***, size\_t** *objidlen***, const netsnmp\_variable\_list \****variable***);**\ **void fprint\_variable(FILE \****fp***, const oid \****objid***, size\_t** *objidlen***, const netsnmp\_variable\_list \****variable***);**\ **int snprint\_variable(char \****buf***, size\_t** *len***, const oid \****objid***, size\_t** *objidlen***, const netsnmp\_variable\_list \****variable***);**\ **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***);** **void print\_value(oid \*objid, size\_t objidlen, const netsnmp\_variable\_list \*variable)**\ **void fprint\_value(FILE \****fp***, const oid \****objid***, size\_t** *objidlen***, const netsnmp\_variable\_list \****variable***);**\ **int snprint\_value(char \****buf***, size\_t** *len***, const oid \****objid***, size\_t** *objidlen***, const netsnmp\_variable\_list \****variable***);**\ **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***);** **void print\_objid(const oid \****objid***, size\_t** *objidlen***);**\ **void fprint\_objid(FILE \****fp***, const oid \****objid***, size\_t** *objidlen***);**\ **int snprint\_objid(char \****buf***, size\_t** *len***, const oid \****objid***, size\_t** *objidlen***);**\ **int sprint\_realloc\_objid(u\_char \*\****buf***, size\_t \****buf\_len***, size\_t \****out\_len***, int** *allow\_realloc***, const oid \****objid***, size\_t** *objidlen***);** **void print\_description(oid \****objid***, size\_t** *objidlen***, int** *width***);**\ **void fprint\_description(FILE \****fp***, const oid \****objid***, size\_t** *objidlen***, int** *width***);** **void snmp\_set\_mib\_warnings(int** *level***);**\ **void snmp\_set\_save\_descriptions(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 **init\_mib** is a convenience function that handles all calls to **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. **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 */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 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. **init\_mib\_internals** sets up the internal structures, preparatory to reading in MIB modules. It should be called after all calls to **add\_mibdir**, and before and calls to **read\_module**. This is called automatically if **init\_mib** is used. **shutdown\_mib** will clear the information that was gathered by **read\_module**, **add\_mibdir** and **add\_module\_replacement**. It is strongly recommended that one does not invoke **shutdown\_mib** while there are SNMP sessions being actively managed. ### Reading and Parsing MIBs **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. | | | | | --- | --- | --- | | **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 | 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*). **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 **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.\ 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-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 *MIBS* is set to *ALL*, **read\_all\_mibs** is called to load all the MIB files found in all the specified *MIBDIRS*. **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 **add\_mibdir** (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. **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 *output* parameter, with the number of sub-identifiers returned via *out\_len*. When called, *out\_len* must hold the maximum length of the *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. ### Searching the MIB Tree **get\_module\_node** takes a descriptor and the name of a module, and returns the corresponding oid list, in the same way as **read\_objid** 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 **print\_mib** will print out a representation of the currently active MIB tree to the specified FILE pointer. **print\_variable** will take an object identifier (as returned by **read\_objid** or **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. **fprint\_variable** does the same, but prints to the FILE pointer specified by the initial parameter.\ **snprint\_variable** prints the same information into the buffer pointed to by *buf* which is of length *len* and returns either the number of characters printed, or -1 if the buffer was not large enough. In the latter case, *buf* will typically contained a truncated version of the information (but this behaviour is not guaranteed). This function replaces the obsolete function **sprint\_variable**.\ **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 *buf* parameter points to a pointer to that buffer; *buf\_len* points to a variable holding the current size of that buffer, and *out\_len* points to a variable holding the offset to which to print. *out\_len* will be updated to hold the offset of the character following the last one added to the buffer. If *allow\_realloc* is 1, the buffer will be dynamically expanded, as necessary, to hold the output; the variables pointed to by *buf* and *buf\_len* will be updated. If *allow\_realloc* is 0, the buffer will not be dynamically expanded. **sprint\_realloc\_variable** returns 0 if *allow\_realloc* is 1 and an attempt to allocate memory to expand the buffer fails, or if *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 [**free**(3)](/free/3.md) on *\*buf* when you have finished with it. **print\_value**, **fprint\_value**, **snprint\_value** and **sprint\_realloc\_value** do the same as the equivalent **print\_variable** routines, but only displaying the value of the variable, without the corresponding object identifier. **print\_objid**, **fprint\_objid**, **snprint\_objid**, and **sprint\_realloc\_objid** take an object identifier (without an accompanying variable instance) and print out the textual representation. **print\_description***,* **fprint\_description***,* **snprint\_description***,* and **sprint\_realloc\_description** take an object identifier (as for **print\_objid** above) and print out a version of the MIB definition for that object, together with the full OID. The *width* argument controls how the OID is layed out. By default the parser does not save descriptions since they may be huge. In order to be able to print them, you must call **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 **snmp\_set\_mib\_warnings** with a *level* of 1 (or 2 for even more warnings). ## ENVIRONMENT VARIABLES - MIBDIRS A colon separated list of directories to search for MIB modules. 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 [**snmp\_api**(3)](/snmp_api/3.md)