Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

snmp_read (3)

Name

snmp_read - snmp_sess_init, snmp_open, snmp_send, snmp_async_send, snmp_select_info, snmp_read, snmp_timeout, snmp_synch_response, snmp_close, snmp_perror, snmp_sess_perror, snmp_error, netsnmp_session_api functions

Synopsis

#include <net-snmp/session_api.h>

void snmp_sess_init ( netsnmp_session*sess);

netsnmp_session* snmp_open ( netsnmp_session *sess);
/* Input parameter not used in active sessions */

int snmp_send ( netsnmp_session *session,
netsnmp_pdu *pdu);

int snmp_async_send ( netsnmp_session *session,
netsnmp_pdu *pdu,
snmp_callback callback,
void *callbackData);

int snmp_select_info ( int * numfds,fd_set *fdset,
struct timeval *timeout,int *block);

void snmp_read ( fd_set *fdset);

void snmp_timeout ( void );

int snmp_synch_response ( netsnmp_session *session,
netsnmp_pdu *pdu,
netsnmp_pdu **response);

int snmp_close ( netsnmp_session *session);
int snmp_close_sessions ( void );

Error Reporting
(Move to output_api(3))
void snmp_error ( netsnmp_session *session,
int *pcliberr,int *psnmperr,char **pperrstring);

char *snmp_api_errstring ( intsnmperr);

void snmp_perror ( char *msg);
/* for parsing errors only */

void snmp_sess_perror (char *msg,netsnmp_session *sess);
/* all other SNMP library errors */

Description

NETSNMP_SESSION_API(3)             Net-SNMP             NETSNMP_SESSION_API(3)



NAME
       snmp_sess_init,       snmp_open,       snmp_send,      snmp_async_send,
       snmp_select_info,   snmp_read,    snmp_timeout,    snmp_synch_response,
       snmp_close,       snmp_perror,       snmp_sess_perror,      snmp_error,
       snmp_api_errstring - netsnmp_session_api functions

SYNOPSIS
       #include <net-snmp/session_api.h>

       void snmp_sess_init ( netsnmp_session*sess);

       netsnmp_session* snmp_open ( netsnmp_session *sess);
              /* Input parameter not used in active sessions */

       int snmp_send ( netsnmp_session *session,
              netsnmp_pdu *pdu);

       int snmp_async_send ( netsnmp_session *session,
                                       netsnmp_pdu *pdu,
                                       snmp_callback callback,
                                       void *callbackData);

       int snmp_select_info ( int * numfds,fd_set *fdset,
              struct timeval *timeout,int *block);

       void snmp_read ( fd_set *fdset);

       void snmp_timeout ( void );

       int snmp_synch_response ( netsnmp_session *session,
              netsnmp_pdu *pdu,
              netsnmp_pdu **response);

       int snmp_close ( netsnmp_session *session);
       int snmp_close_sessions ( void );

   Error Reporting
       (Move to output_api(3))
       void snmp_error ( netsnmp_session *session,
              int *pcliberr,int *psnmperr,char **pperrstring);

       char *snmp_api_errstring ( intsnmperr);

       void snmp_perror ( char *msg);
              /* for parsing errors only */

       void snmp_sess_perror (char *msg,netsnmp_session *sess);
              /* all other SNMP library errors */

DESCRIPTION
       Snmp_sess_init prepares a netsnmp_session that sources transport  char-
       acteristics  and common information that will be used for a set of SNMP
       transactions.  After this structure is passed to snmp_open to create an
       SNMP session, the structure is not used.

       Snmp_open  returns  a pointer to a newly-formed netsnmp_session object,
       which the application must use to reference the active SNMP session.

       snmp_send and snmp_async_send() each take as input a pointer to a  net-
       snmp_pdu  object.  This structure contains 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_async_send() call, snmp_read will  invoke  the  specified
       callback when the response is received.

       Snmp_read,  snmp_select_info, and snmp_timeout provide an interface for
       the use of the select(2) system call  so  that  SNMP  transactions  can
       occur asynchronously.

       Snmp_select_info  is  given the information that would have been passed
       to select in the absence of SNMP.  For example, this might include win-
       dow update information.  This information is modified so that SNMP will
       get the service it requires from the call to  select.   In  this  case,
       numfds, fdset, and timeout correspond to the nfds, readfds, and timeout
       arguments to select, respectively.  The only exception is that  timeout
       must  always  point  to an allocated (but perhaps uninitialized) struct
       timeval.  If timeout would have been passed as NULL, block  is  set  to
       true, and timeout is treated as undefined.  This same rule applies upon
       return from snmp_select_info.

       After calling snmp_select_info, select  is  called  with  the  returned
       data.   When select returns, snmp_read should be called with the fd_set
       returned from select to read each  SNMP  socket  that  has  input.   If
       select  times  out, snmp_timeout should be called to see if the timeout
       was intended for SNMP.

       snmp_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_send ,  snmp_read etc for details.

DIAGNOSTICS
       Previous versions of the library used snmp_get_errno to read the global
       variable  snmp_errno  which  may  have held the error status within the
       SNMP library.  The existing method snmp_perror should be  used  to  log
       ASN.1 coding errors only.

       The  new  method  snmp_sess_perror  is  provided to capture errors that
       occur  during  the   processing   of   a   particular   SNMP   session.
       Snmp_sess_perror  calls  snmp_error  function to obtain the "C" library
       error errno , the SNMP library error snmperr ,  and  the  SNMP  library
       detailed  error  message that is associated with an error that occurred
       during a given session.

       Note that in all cases except one, snmp_sess_perror  should  be  handed
       the  netsnmp_session  *  pointer returned from snmp_open.  If snmp_open
       returns a null pointer, pass the INPUT netsnmp_session *  pointer  used
       to call snmp_open.

       Error  return  status  from  snmp_close  and  snmp_send is indicated by
       return of 0.  A successful status will return a 1  for  snmp_close  and
       the  request  id  of  the packet for snmp_send.  Upon successful return
       from snmp_send the pdu will be freed by the library.

       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_PARSE

         SNMPERR_BAD_VERSION

         SNMPERR_NOAUTH_DESPRIV

         SNMPERR_ABORT

         SNMPERR_UNKNOWN_PDU

         SNMPERR_TIMEOUT

       A  string  representation  of  the  error  code  can  be  obtained with
       snmp_api_errstring, and a standard error message may be  printed  using
       snmp_perror that functions like the perror standard routine.


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_sess_api(3), netsnmp_mib_api(3), netsnmp_pdu_api(3),
       netsnmp_varbind_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_SESSION_API(3)