--- name: "snmp_api" section: "3" platform: "linux" package: "libsnmp4.1-dev" version: "4.1.1-2.2" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/snmp_api" --- # snmp\_api(3) send and receive SNMP messages ## NAME snmp\_sess\_init, snmp\_open, snmp\_send, snmp\_free\_pdu, snmp\_select\_info, snmp\_read, snmp\_timeout, snmp\_close, snmp\_perror, snmp\_sess\_perror, snmp\_error, snmp\_api\_errstring - send and receive SNMP messages ## SYNOPSIS \#include \\ \#include \\ \#include \\ \#include \\ \#include \\ \#include \\ \#include \ void snmp\_sess\_init ( struct snmp\_session \* ); struct snmp\_session \* snmp\_open ( struct snmp\_session \*); **/\* Input parameter not used in active sessions \*/** int snmp\_send ( struct snmp\_session \*session, struct snmp\_pdu \*pdu ); int snmp\_select\_info ( int \*numfds, fd\_set \*fdset, struct timeval \*timeout, int \*block ); void snmp\_read ( fd\_set \*fdset ); void snmp\_timeout ( void ); int snmp\_close ( struct snmp\_session \*session ); void snmp\_free\_pdu ( struct snmp\_pdu \*pdu ); void snmp\_error ( struct snmp\_session \*session, int \*pcliberr, int \*psnmperr, char \*\*pperrstring ); char \*snmp\_api\_errstring ( int snmperr ); void snmp\_perror ( char \* msg ); **/\* for parsing errors only \*/** void snmp\_sess\_perror (char \* msg, struct snmp\_session \*); **/\* all other SNMP library errors \*/** ## DESCRIPTION *Snmp\_sess\_init* prepares a struct snmp\_session that sources transport characteristics and common information that will be used for a set of SNMP transactions. After this structure is passed to *snmp\_open* to create an SNMP session, the structure is not used. *Snmp\_open* returns a pointer to a newly-formed *struct snmp\_session* object, which the application must use to reference the active SNMP session. *Snmp\_send* and *snmp\_free\_pdu* each take as input a pointer to a *struct snmp\_pdu* object. This structure contains information that describes a transaction that will be performed over an open session. Consult snmp\_api.h for the definitions of these structures. *Snmp\_read, snmp\_select\_info,* and *snmp\_timeout* provide an interface for the use of the [*select*(2)](/select/2.md) system call so that SNMP transactions can occur asynchronously. *Snmp\_select\_info* is given the information that would have been passed to *select* in the absence of SNMP. For example, this might include window update information. This information is modified so that SNMP will get the service it requires from the call to *select.* In this case, *numfds, fdset,* and *timeout* correspond to the *nfds, readfds,* and *timeout* arguments to *select,* respectively. The only exception is that timeout must always point to an allocated (but perhaps uninitialized) *struct timeval.* If *timeout* would have been passed as NULL, *block* is set to true, and *timeout* is treated as undefined. This same rule applies upon return from *snmp\_select\_info.* After calling *snmp\_select\_info, select* is called with the returned data. When select returns, *snmp\_read* should be called with the *fd\_set* returned from *select* to read each SNMP socket that has input. If *select* times out, *snmp\_timeout* should be called to see if the timeout was intended for SNMP. ## DIAGNOSTICS Previous versions of the library used *snmp\_get\_errno* to read the global variable *snmp\_errno* which may have held the error status within the SNMP library. The existing method *snmp\_perror* should be used to log ASN.1 coding errors only. The new method *snmp\_sess\_perror* is provided to capture errors that occur during the processing of a particular SNMP session. *Snmp\_sess\_perror* calls *snmp\_error* function to obtain the "C" library error *errno* , the SNMP library error *snmperr* , and the SNMP library detailed error message that is associated with an error that occurred during a given session. Note that in all cases except one, *snmp\_sess\_perror* should be handed the *struct snmp\_session \** pointer returned from *snmp\_open.* If *snmp\_open* returns a null pointer, pass the INPUT *struct snmp\_session \** pointer used to call *snmp\_open.* Error return status from *snmp\_close* and *snmp\_send* is indicated by return of 0. A successful status will return a 1 for *snmp\_close* and then request id of the packet for *snmp\_send.* Upon successful return from *snmp\_send* the pdu will be freed by the library. Consult snmp\_api.h for the complete set of SNMP library error values. The SNMP library error value *snmperr* can be one of the following values: - SNMPERR\_GENERR A generic error occurred. - SNMPERR\_BAD\_LOCPORT The local port was bad because it had already been allocated or permission was denied. - SNMPERR\_BAD\_ADDRESS The host name or address given was not useable. - SNMPERR\_BAD\_SESSION The specified session was not open. - SNMPERR\_TOO\_LONG - SNMPERR\_NO\_SOCKET - SNMPERR\_V2\_IN\_V1 - SNMPERR\_V1\_IN\_V2 - SNMPERR\_BAD\_REPEATERS - SNMPERR\_BAD\_REPETITIONS - SNMPERR\_BAD\_ASN1\_BUILD - SNMPERR\_BAD\_SENDTO - SNMPERR\_BAD\_PARSE - SNMPERR\_BAD\_VERSION - SNMPERR\_NOAUTH\_DESPRIV - SNMPERR\_ABORT - SNMPERR\_UNKNOWN\_PDU - SNMPERR\_TIMEOUT A string representation of the error code can be obtained with *snmp\_api\_errstring*, and a standard error message may be printed using *snmp\_perror* that functions like the *perror* standard routine. ## SEE ALSO [select(2)](/select/2.md), snmp\_api.h