manpagez: man pages & more
man snmp_sess_timeout(3)
Home | html | info | man
snmp_sess_api(3)                   Net-SNMP                   snmp_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_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() 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.


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



SEE ALSO

       select(2), snmp_api(3), snmp_api.h



4.2 Berkeley Distribution         07 Mar 2002                 snmp_sess_api(3)

Mac OS X 10.6 - Generated Thu Sep 17 20:22:55 CDT 2009
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.