LIBRARY

     Begemot SNMP library (libbsnmp, -lbsnmp)

SYNOPSIS

     #include <bsnmp/asn1.h>
     #include <bsnmp/snmp.h>

     void
     snmp_value_free(struct snmp_value *value);

     int
     snmp_value_parse(const char *buf, enum snmp_syntax,
         union snmp_values *value);

     int
     snmp_value_copy(struct snmp_value *to, const struct snmp_value *from);

     void
     snmp_pdu_free(struct snmp_pdu *value);

     enum snmp_code
     snmp_pdu_decode(struct asn_buf *buf, struct snmp_pdu *pdu, int32_t *ip);

     enum snmp_code
     snmp_pdu_encode(struct snmp_pdu *pdu, struct asn_buf *buf);

     void
     snmp_pdu_dump(const struct snmp_pdu *pdu);

     int
     TRUTH_MK(F);

     int
     TRUTH_GET(T);

     int
     TRUTH_OK(T);

DESCRIPTION

     The SNMP library contains routines to handle SNMP version 1 and 2 PDUs.
     There are two basic structures used throughout the library:

           struct snmp_value {
                   struct asn_oid          var;
                   enum snmp_syntax        syntax;
                   union snmp_values {
                     int32_t               integer;/* also integer32 */
                     struct {
                       u_int               len;
                       u_char              *octets;
                     }                     octetstring;
                     struct asn_oid        oid;

                   SNMP_SYNTAX_INTEGER,    /* == INTEGER32 */
                   SNMP_SYNTAX_OCTETSTRING,
                   SNMP_SYNTAX_OID,
                   SNMP_SYNTAX_IPADDRESS,
                   SNMP_SYNTAX_COUNTER,
                   SNMP_SYNTAX_GAUGE,      /* == UNSIGNED32 */
                   SNMP_SYNTAX_TIMETICKS,

                   /* v2 additions */
                   SNMP_SYNTAX_COUNTER64,
                   /* exceptions */
                   SNMP_SYNTAX_NOSUCHOBJECT,
                   SNMP_SYNTAX_NOSUCHINSTANCE,
                   SNMP_SYNTAX_ENDOFMIBVIEW,
           };
     The field v holds the actual value depending on syntax.  Note, that if
     syntax is SNMP_SYNTAX_OCTETSTRING and v.octetstring.len is not zero,
     v.octetstring.octets points to a string allocated by malloc(3).

           #define SNMP_COMMUNITY_MAXLEN   128
           #define SNMP_MAX_BINDINGS       100

           struct snmp_pdu {
                   char            community[SNMP_COMMUNITY_MAXLEN + 1];
                   enum snmp_version version;
                   u_int           type;

                   /* trap only */
                   struct asn_oid  enterprise;
                   u_char          agent_addr[4];
                   int32_t         generic_trap;
                   int32_t         specific_trap;
                   u_int32_t       time_stamp;

                   /* others */
                   int32_t         request_id;
                   int32_t         error_status;
                   int32_t         error_index;

                   /* fixes for encoding */
                   u_char          *outer_ptr;
                   u_char          *pdu_ptr;
                   u_char          *vars_ptr;

                   struct snmp_value bindings[SNMP_MAX_BINDINGS];
                   u_int           nbindings;
           };
     This structure contains a decoded SNMP PDU.  version is one of

           enum snmp_version {
                   SNMP_Verr = 0,
                   SNMP_V1 = 1,

     tialized and will overwrite its previous contents.  It does not itself
     allocate the structure pointed to by to.

     The function snmp_pdu_free() frees all the dynamically allocated compo-
     nents of the PDU.  It does not itself free the structure pointed to by
     pdu.

     The function snmp_pdu_decode() decodes the PDU pointed to by buf and
     stores the result into pdu.  If an error occurs in a variable binding the
     (1 based) index of this binding is stored in the variable pointed to by
     ip.

     The function snmp_pdu_encode() encodes the PDU pdu into the an octet-
     string in buffer buf.

     The function snmp_pdu_dump() dumps the PDU in a human readable form by
     calling snmp_printf().

     The function TRUTH_MK() takes a C truth value (zero or non-zero) and
     makes an SNMP truth value (2 or 1).  The function TRUTH_GET() takes an
     SNMP truth value and makes a C truth value (0 or 1).  The function
     TRUTH_OK() checks, whether its argument is a legal SNMP truth value.

DIAGNOSTICS

     When an error occurs in any of the function the function pointed to by
     the global pointer

           extern void (*snmp_error)(const char *, ...);

     with a printf(3) style format string.  There is a default error handler
     in the library that prints a message starting with `SNMP:' followed by
     the error message to standard error.

     The function pointed to by

           extern void (*snmp_printf)(const char *, ...);

     is called by the snmp_pdu_dump() function.  The default handler is
     printf(3).

ERRORS

     snmp_pdu_decode() will return one of the following return codes:

     [SNMP_CODE_OK]     Success.

     [SNMP_CODE_FAILED]
                        The ASN.1 coding was wrong.

     [SNMP_CODE_BADLEN]
                        A variable binding value had a wrong length field.

     [SNMP_CODE_OORANGE]

SEE ALSO

     gensnmptree(1), bsnmpd(1), bsnmpagent(3), bsnmpclient(3), bsnmplib(3)

STANDARDS

     This implementation conforms to the applicable IETF RFCs and ITU-T recom-
     mendations.

AUTHORS

     Hartmut Brandt <harti@freebsd.org>

BSD                             October 4, 2005                            BSD