


SNMP_API(3)            C LIBRARY FUNCTIONS            SNMP_API(3)



NAME
     snmp_open, snmp_close, snmp_send, snmp_read,  snmp_free_pdu,
     snmp_select_info,  snmp_timeout - send and receive SNMP mes-
     sages

SYNOPSIS
     #include <sys/types>
     #include <netinet/in.h>
     #include <sys/time.h>
     #include "snmp.h"
     #include "snmp_impl.h"
     #include "asn1.h"
     #include "snmp_api.c"

     extern int snmp_errno;

     struct snmp_session *snmp_open(session)
     struct snmp_session *session;

     int snmp_close(session)
     struct snmp_session *session;

     int snmp_send(session, pdu)
     struct snmp_session *session;
     struct snmp_pdu *pdu;

     void snmp_read(fdset)
     fd_set *fdset;

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

     void snmp_timeout()

     void snmp_free_pdu(pdu)
     struct snmp_pdu *pdu;

DESCRIPTION
     _S_n_m_p__o_p_e_n, _s_n_m_p__c_l_o_s_e, and _s_n_m_p__s_e_n_d each take  as  input  a
     pointer to an object with the following structure.  In addi-
     tion, _s_n_m_p__o_p_e_n also returns a pointer  to  an  object  with
     this  structure.   This structure contains information for a
     set  of  transactions  that  will  share  similar  transport
     characteristics.

          typedef struct sockaddr_in  ipaddr;

          struct snmp_session {
              u_char  *community;  /* community for outgoing requests. */



Sun Release 4.1    Last change: Sept 17, 1989                   1






SNMP_API(3)            C LIBRARY FUNCTIONS            SNMP_API(3)



              int       community_len;  /* Length of community name. */
              int       retries;   /* Number of retries before timeout. */
              long    timeout;    /* Number of uS until first timeout, then exponential backoff */
              char    *peername;   /* Domain name or dotted IP address of default peer */
              u_short remote_port;/* UDP port number of peer. */
              u_short local_port; /* My UDP port number, 0 for default, picked randomly */

              /* Authentication function or NULL if null authentication is used */
              u_char  *(*authenticator)();

              int       (*callback)();  /* Function to interpret incoming data */

              /* Pointer to data that the callback function may consider important */
              void    *callback_magic;
          };

          /*
           * Set fields in session and pdu to the following to get a default or unconfigured value.
           */
          #define SNMP_DEFAULT_COMMUNITY_LEN  0/* for default community name */
          #define SNMP_DEFAULT_RETRIES      -1
          #define SNMP_DEFAULT_TIMEOUT      -1
          #define SNMP_DEFAULT_REMPORT      0
          #define SNMP_DEFAULT_REQID        0
          #define SNMP_DEFAULT_ERRSTAT      -1
          #define SNMP_DEFAULT_ERRINDEX     -1
          #define SNMP_DEFAULT_ADDRESS      0
          #define SNMP_DEFAULT_PEERNAME     NULL
          #define SNMP_DEFAULT_ENTERPRISE_LENGTH  0
          #define SNMP_DEFAULT_TIME         0

          /*
           * This routine must be supplied by the application:
           *
           * u_char *authenticator(pdu, length, community, community_len)
           * u_char *pdu;          The rest of the PDU to be authenticated
           * int *length;          The length of the PDU (updated by the authenticator)
           * u_char *community;    The community name to authenticate under.
           * int    community_len  The length of the community name.
           *
           * Returns the authenticated pdu, or NULL if authentication failed.
           * If null authentication is used, the authenticator in snmp_session can be
           * set to NULL(0).
           */

          /*
           * This routine must be supplied by the application:
           *
           * int callback(operation, session, reqid, pdu, magic)
           * int operation;
           * struct snmp_session *session;    The session authenticated under.
           * int reqid;                The request id of this pdu (0 for TRAP)



Sun Release 4.1    Last change: Sept 17, 1989                   2






SNMP_API(3)            C LIBRARY FUNCTIONS            SNMP_API(3)



           * struct snmp_pdu *pdu;     The pdu information.
           * void *magic               A link to the data for this routine.
           *
           * Returns 1 if request was successful, 0 if it should be kept pending.
           * Any data in the pdu must be copied because it will be freed elsewhere.
           * Operations are defined below:
           */
          #define RECEIVED_MESSAGE   1
          #define TIMED_OUT      2

     _S_n_m_p__s_e_n_d and _s_n_m_p__f_r_e_e__p_d_u each take as input a pointer  to
     an object with the following structure.  This structure con-
     tains information that describes a transaction that will  be
     performed over an open session.

          struct snmp_pdu {
              ipaddr  address;     /* Address of peer */

              int       command;   /* Type of this PDU */

              u_long  reqid;  /* Request id */
              u_long  errstat;     /* Error status */
              u_long  errindex;    /* Error index */

              /* Trap information */
              oid       *enterprise;/* System OID */
              int       enterprise_length;
              ipaddr  agent_addr;  /* address of object generating trap */
              int       trap_type; /* trap type */
              int       specific_type;  /* specific type */
              u_long  time;   /* Uptime */

              struct variable_list *variables;
          };


          struct variable_list {
              struct variable_list *next_variable;    /* NULL for last variable */
              oid       *name;  /* Object identifier of variable */
              int       name_length;    /* number of subid's in name */
              u_char  type;   /* ASN type of variable */
              union { /* value of variable */
               long *integer;
               u_char    *string;
               oid  *objid;
              } val;
              int       val_len;
          };

     _S_n_m_p__r_e_a_d, _s_n_m_p__s_e_l_e_c_t__i_n_f_o,  and  _s_n_m_p__t_i_m_e_o_u_t  provide  an
     interface  for  the use of the _s_e_l_e_c_t(2) system call so that
     SNMP transactions can occur asynchronously.



Sun Release 4.1    Last change: Sept 17, 1989                   3






SNMP_API(3)            C LIBRARY FUNCTIONS            SNMP_API(3)



     _S_n_m_p__s_e_l_e_c_t__i_n_f_o is given the information  that  would  have
     been  passed to _s_e_l_e_c_t in the absence of SNMP.  For example,
     this might include window update information.  This informa-
     tion  is  modified  so  that  SNMP  will  get the service it
     requires from the call to  _s_e_l_e_c_t.  In  this  case,  _n_u_m_f_d_s,
     _f_d_s_e_t,  and  _t_i_m_e_o_u_t  correspond  to  the _n_f_d_s, _r_e_a_d_f_d_s, and
     _t_i_m_e_o_u_t arguments to _s_e_l_e_c_t, respectively.  The only  excep-
     tion  is that timeout must always point to an allocated (but
     perhaps uninitialized) _s_t_r_u_c_t _t_i_m_e_v_a_l. If _t_i_m_e_o_u_t would have
     been  passed  as  NULL, _b_l_o_c_k is set to true, and _t_i_m_e_o_u_t is
     treated as undefined.  This same rule  applies  upon  return
     from _s_n_m_p__s_e_l_e_c_t__i_n_f_o.

     After calling _s_n_m_p__s_e_l_e_c_t__i_n_f_o, _s_e_l_e_c_t is  called  with  the
     returned  data.   When  select  returns, _s_n_m_p__r_e_a_d is called
     with the _f_d__s_e_t returned from _s_e_l_e_c_t.  This  will  read  all
     SNMP  sockets with input.  If _s_e_l_e_c_t times out, _s_n_m_p__t_i_m_e_o_u_t
     should be called to see if  the  timeout  was  intended  for
     SNMP.

DIAGNOSTICS
     Error return status from _s_n_m_p__o_p_e_n is indicated by return of
     a  null  pointer.   Error  return status from _s_n_m_p__c_l_o_s_e and
     _s_n_m_p__s_e_n_d is indicated by return of 0.  A successful  status
     will  return  a 1.  The external integer _s_n_m_p__e_r_r_n_o may then
     be checked to see what type of error has occurred

     _s_n_m_p__e_r_r_n_o can have the following values:

          SNMPERR_GENERR       A generic error occurred.

          SNMPERR_BAD_LOCPORT  The local port was bad because  it
                               had already been allocated or per-
                               mission was denied.

          SNMPERR_BAD_ADDRESS  The host name or address given was
                               not useable.

          SNMPERR_BAD_SESSION  The  specified  session  was   not
                               open.

SEE ALSO
     select(2), snmp_api.h












Sun Release 4.1    Last change: Sept 17, 1989                   4



