NETSNMP\_SESS\_API(3) Net-SNMP NETSNMP\_SESS\_API(3) # [NAME](#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\_synch\_response, snmp\_sess\_close, snmp\_sess\_error - session functions # [SYNOPSIS](#SYNOPSIS) **#include <net-snmp/session\_api.h>** **void snmp\_sess\_init(struct snmp\_session \*session);** **void \*snmp\_sess\_open(struct snmp\_session \*session);** **struct snmp\_session \*snmp\_sess\_session(void \*handle);** **int snmp\_sess\_send(void \*handle, struct snmp\_pdu \*pdu);** **int snmp\_sess\_async\_send(void \*handle,** **struct snmp\_pdu \*pdu,** **snmp\_callback callback,** **void \*callbackData);** **int snmp\_sess\_select\_info(void \*handle,** **int \*numfds, fd\_set \*fdset,** **struct timeval \*timeout,** **int \*block);** **int snmp\_sess\_read(void \*handle, fd\_set \*fdset);** **void snmp\_sess\_timeout(void \*handle);** **int snmp\_sess\_synch\_response ( void \*handle,** **netsnmp\_pdu \*pdu,** **netsnmp\_pdu \*\*response);** **int snmp\_sess\_close(void \*handle);** **void snmp\_sess\_error(void \*handle, int \*pcliberr,** **int \*psnmperr, char \*\*pperrstring);** # [DESCRIPTION](#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 (*handle* in the above prototypes) to identify a single session in lieu of a *session* pointer (as in the traditional API). **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\_sess\_open()** to create an SNMP session, the structure is no longer used. Instead the opaque pointer returned by **snmp\_sess\_open()** is used to refer to that session henceforth. 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()**. Rather the equivalent single session functions described here should be used. **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 a *pdu* parameter, which points to a struct snmp\_pdu object containing information that describes a transaction that will be performed over an open session. Consult snmp\_api.h for the definitions of these structures. With the *snmp\_sess\_async\_send()* call, *snmp\_sess\_read* will invoke the specified callback when the response is received. **snmp\_sess\_select\_info()**, **snmp\_sess\_read()** and **snmp\_sess\_timeout()** provide an interface for the use of the [**select**(2)](/man/os/net-snmp/select.2) system call so that SNMP transactions for a single session can occur asynchronously. **snmp\_sess\_select\_info()** is passed the information that would have been passed to [**select**(2)](/man/os/net-snmp/select.2) in the absence of SNMP. For example, this might include file descriptors associated with the main loop of a graphical application. This information is modified so that SNMP will get the service it requires from the call to [**select**(2)](/man/os/net-snmp/select.2). In this case, *numfds*, *fdset* and *timeout* correspond to the *nfds*, *readfds* and *timeout* arguments to [**select**(2)](/man/os/net-snmp/select.2) respectively. The only exception is that timeout must ALWAYS point to an allocated (but perhaps uninitialized) *struct timeval* (it cannot be NULL as for [**select**(2)](/man/os/net-snmp/select.2)). If *timeout* would have been passed as NULL, *block* is instead 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**(2)](/man/os/net-snmp/select.2) should be called with the returned data. When it returns, **snmp\_sess\_read()** should then be called with the *fd\_set* returned from [**select**(2)](/man/os/net-snmp/select.2). This will read any input from this session's SNMP socket. If [**select**(2)](/man/os/net-snmp/select.2) times out (that is, it returns zero), **snmp\_sess\_timeout()** should be called to see if a timeout has occurred on the SNMP session. *snmp\_sess\_synch\_response* is a convenience routine that will send the request, wait for the response and process it before returning. See the descriptions of *snmp\_sess\_send , snmp\_sess\_read* etc for details. # [DIAGNOSTICS](#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 a return value of 0. A successful status will return 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](#SNMPERR_GENERR) A generic error occurred. [SNMPERR\_BAD\_LOCPORT](#SNMPERR_BAD_LOCPORT) The local port was bad because it had already been allocated or permission was denied. [SNMPERR\_BAD\_ADDRESS](#SNMPERR_BAD_ADDRESS) The host name or address given was not useable. [SNMPERR\_BAD\_SESSION](#SNMPERR_BAD_SESSION) The specified session was not open. [SNMPERR\_TOO\_LONG](#SNMPERR_TOO_LONG) [SNMPERR\_NO\_SOCKET](#SNMPERR_NO_SOCKET) [SNMPERR\_V2\_IN\_V1](#SNMPERR_V2_IN_V1) [SNMPERR\_V1\_IN\_V2](#SNMPERR_V1_IN_V2) [SNMPERR\_BAD\_REPEATERS](#SNMPERR_BAD_REPEATERS) [SNMPERR\_BAD\_REPETITIONS](#SNMPERR_BAD_REPETITIONS) [SNMPERR\_BAD\_ASN1\_BUILD](#SNMPERR_BAD_ASN1_BUILD) [SNMPERR\_BAD\_SENDTO](#SNMPERR_BAD_SENDTO) [SNMPERR\_BAD\_RCVFROM](#SNMPERR_BAD_RCVFROM) [SNMPERR\_BAD\_PARSE](#SNMPERR_BAD_PARSE) [SNMPERR\_BAD\_VERSION](#SNMPERR_BAD_VERSION) [SNMPERR\_BAD\_COMMUNITY](#SNMPERR_BAD_COMMUNITY) [SNMPERR\_NOAUTH\_DESPRIV](#SNMPERR_NOAUTH_DESPRIV) [SNMPERR\_ABORT](#SNMPERR_ABORT) [SNMPERR\_UNKNOWN\_PDU](#SNMPERR_UNKNOWN_PDU) [SNMPERR\_TIMEOUT](#SNMPERR_TIMEOUT) # [SEE ALSO](#SEE_ALSO) [select(2)](/man/os/net-snmp/select.2), [netsnmp\_session\_api(3)](/man/os/net-snmp/netsnmp_session_api.3), [netsnmp\_pdu\_api(3)](/man/os/net-snmp/netsnmp_pdu_api.3), [netsnmp\_varbind\_api(3)](/man/os/net-snmp/netsnmp_varbind_api.3), [netsnmp\_mib\_api(3)](/man/os/net-snmp/netsnmp_mib_api.3), snmp\_api.h 19 May 2011 V5.9.5.2 --- Document: snmp_sess_session(3) from net-snmp 5.9.5.2-r12 (Chainguard OS) Source: https://github.com/net-snmp/net-snmp.git