---
name: "snmp_sess_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/snmp_sess_api/3snmp"
---

# snmp\_sess\_api(3snmp)

session functions

## 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 - session functions

## 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\_close(void \****handle***);**

**void snmp\_sess\_error(void \****handle***, 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 (*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.

**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 passed the information that would have been passed to [**select**(2)](/select/2.md) 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)](/select/2.md). In this case, *numfds*, *fdset* and *timeout* correspond to the *nfds*, *readfds* and *timeout* arguments to [**select**(2)](/select/2.md) 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)](/select/2.md)). 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)](/select/2.md) 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)](/select/2.md). This will read any input from this session's SNMP socket.  If [**select**(2)](/select/2.md) times out (that is, it returns zero), **snmp\_sess\_timeout()** should be called to see if a timeout has occurred on the SNMP session.

## 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

  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**