Manpages - netsnmp_sess_api.3

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

#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/,*

int snmp_sess_select_info(void **/handle/,*

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

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) 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) 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). In this case, numfds, fdset and timeout correspond to the nfds, readfds and timeout arguments to *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)). 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) 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). This will read any input from this session’s SNMP socket. If *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.

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

select(2), netsnmp_session_api(3), netsnmp_pdu_api(3), netsnmp_varbind_api(3), netsnmp_mib_api(3), snmp_api.h