Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

snmp_sess_session (3)

Name

snmp_sess_session - 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, 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

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_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_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
       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()  pro-
       vide 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.

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  val-
       ues:

         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 use-
                                  able.

         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

ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+-----------------------------------------------+
       |ATTRIBUTE TYPE |               ATTRIBUTE VALUE                 |
       +---------------+-----------------------------------------------+
       |Availability   | system/management/snmp/net-snmp/documentation |
       +---------------+-----------------------------------------------+
       |Stability      | Volatile                                      |
       +---------------+-----------------------------------------------+
SEE ALSO
       select(2),     netsnmp_session_api(3),     netsnmp_pdu_api(3),     net-
       snmp_varbind_api(3), netsnmp_mib_api(3), snmp_api.h



NOTES
       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source  was  downloaded  from   http://ftp.ntua.gr/mirror/net-snmp/net-
       snmp/5.7.3/net-snmp-5.7.3.tar.gz

       Further information about this software can be found on the open source
       community website at http://www.net-snmp.org/.



V5.7.3                            19 May 2011              NETSNMP_SESS_API(3)