--- name: "snmp_sess_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_sess_api" --- # snmp\_sess\_api(3) ## NAME snmp\_sess\_init, snmp\_sess\_open, snmp\_sess\_session, snmp\_sess\_send, snmp\_sess\_async\_send, snmp\_sess\_select\_info, snmp\_sess\_read, snmp\_sess\_timeout, snmp\_sess\_close, snmp\_sess\_error ## SYNOPSIS \#include \\ \#include \\ \#include \\ \#include \\ \#include \\ \#include \\ \#include \ void snmp\_sess\_init ( struct snmp\_session \* ); void \* snmp\_sess\_open ( struct snmp\_session \* ); struct snmp\_session \* snmp\_sess\_session ( void \* ); int snmp\_sess\_send ( void \* opaque, struct snmp\_pdu \*pdu ); int snmp\_sess\_async\_send ( void \* opaque, struct snmp\_pdu \*pdu, snmp\_callback callback, void \* callbackData ); int snmp\_sess\_select\_info ( void \* opaque, int \*numfds, fd\_set \*fdset, struct timeval \*timeout, int \*block ); void snmp\_sess\_read ( void \* opaque, fd\_set \*fdset ); void snmp\_sess\_timeout ( void \* opaque ); int snmp\_sess\_close ( void \* opaque ); void snmp\_sess\_error ( void \* opaque, int \*pcliberr, int \*psnmperr, char \*\*pperrstring ); ## DESCRIPTION These functions define a subset of the API that can be used to manage single SNMP sessions in a multi-threaded application. Except for *snmp\_sess\_session,* these functions are single session versions of the traditional SNMP library API. Note that these functions use an *Opaque* pointer to identify a single session in lieu of a *session* pointer. *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 sessions that are created with *snmp\_sess\_open* are not affected by and should not be used with *snmp\_select\_info,* *snmp\_read,* *snmp\_timeout,* nor *snmp\_close.* Use the other functions described here with similar capabilities. *Snmp\_sess\_init* and *snmp\_sess\_open* each take as input a pointer to a struct snmp\_session object. This structure contains information for a set of transactions that will share similar transport characteristics. *Snmp\_sess\_session* takes the opaque session handle and returns a pointer to its associated struct snmp\_session. *Snmp\_sess\_send* and *snmp\_sess\_async\_send* each take as input an additional 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\_sess\_select\_info, snmp\_sess\_read,* and *snmp\_sess\_timeout* provide an interface for the use of the [*select*(2)](/select/2.md) system call so that SNMP transactions for a single session can occur asynchronously. *Snmp\_sess\_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\_sess\_select\_info, select* is called with the returned data. When select returns, *snmp\_sess\_read* is called with the *fd\_set* returned from *select.* This will read any input from this session's SNMP socket. If *select* times out, *snmp\_sess\_timeout* should be called to see if the timeout was intended for SNMP. ## DIAGNOSTICS Error return status from *snmp\_sess\_open* is indicated by return of a null pointer. Error return status from *snmp\_sess\_close* and *snmp\_sess\_send* is indicated by return of 0. A successful status will return a 1. Further information can be obtained by using *snmp\_sess\_error* to see what type of error has occurred. This function returns the SNMP "snmp\_errno" variable, the value of the system "errno" variable, and a string interpretation of both variables. The string must be freed after use by the caller. For errors returned by *snmp\_sess\_open,* use the corresponding function *snmp\_error* instead of *snmp\_sess\_error.* 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\_RCVFROM - SNMPERR\_BAD\_PARSE - SNMPERR\_BAD\_VERSION - SNMPERR\_BAD\_COMMUNITY - SNMPERR\_NOAUTH\_DESPRIV - SNMPERR\_ABORT - SNMPERR\_UNKNOWN\_PDU - SNMPERR\_TIMEOUT ## SEE ALSO [select(2)](/select/2.md), [snmp\_api(3)](/snmp_api/3.md), snmp\_api.h