FreeBSD Manual Pages
NETSNMP_SESS_API(3) Net-SNMP NETSNMP_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_synch_response, snmp_sess_close, snmp_sess_er- ror - 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_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 These functions define a subset of the API that can be used to manage sin- gle 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 proto- types) 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_time- out() nor snmp_close(). Rather the equivalent single session functions de- scribed 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 de- scribes 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 speci- fied 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 transac- tions 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 in- clude file descriptors associated with the main loop of a graphical appli- cation. 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 time- out correspond to the nfds, readfds and timeout arguments to select(2) re- spectively. The only exception is that timeout must ALWAYS point to an al- located (but perhaps uninitialized) struct timeval (it cannot be NULL as for select(2)). If timeout would have been passed as NULL, block is in- stead set to true, and timeout is treated as undefined. This same rule ap- plies 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 oc- curred on the SNMP session. snmp_sess_synch_response is a convenience routine that will send the re- quest, wait for the response and process it before returning. See the de- scriptions of snmp_sess_send , snmp_sess_read etc for details. 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 interpreta- tion 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), netsnmp_session_api(3), netsnmp_pdu_api(3), net- snmp_varbind_api(3), netsnmp_mib_api(3), snmp_api.h V5.9.5.2 19 May 2011 NETSNMP_SESS_API(3)
NAME | SYNOPSIS | DESCRIPTION | DIAGNOSTICS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=netsnmp_sess_api&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>