bsnmplib(3)

NAME

snmp_value_free, snmp_value_parse, snmp_value_copy,

snmp_pdu_free,
snmp_code snmp_pdu_decode, snmp_code snmp_pdu_encode,

snmp_pdu_dump,
TRUTH_MK, TRUTH_GET, TRUTH_OK - SNMP decoding and encoding

library

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 inte

ger32 */
struct {

u_int len;
u_char *octets;

} octetstring;
struct asn_oid oid;
u_char ipaddress[4];
uint32_t uint32; /* also

gauge32, counter32,

unsigned32,

timeticks */

uint64_t counter64;

} v;

};

This structure represents one variable binding from an SNMP

PDU. The
field var is the ASN.1 of the variable that is bound.

syntax contains
either the syntax code of the value or an exception code for

SNMPv2 and
may be one of:

enum snmp_syntax {

SNMP_SYNTAX_NULL = 0,
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 mal

loc(3).

#define SNMP_COMMUNITY_MAXLEN 128
#define SNMP_MAX_BINDINGS 100

struct snmp_pdu {

char community[SNMP_COMMUNI

TY_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,
SNMP_V2c,

};

and type is the type of the PDU.

The function snmp_value_free() is used to free all the dy

namic allocated
contents of an SNMP value. It does not free the structure

pointed to by
value itself.

The function snmp_value_parse() parses the ASCII representa

tion of an
SNMP value into its binary form. This function is mainly

used by the
configuration file reader of bsnmpd(1).

The function snmp_value_copy() makes a deep copy of the val

ue pointed to
by from to the structure pointed to by to. It assumes that

to is uninitialized 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 allo

cated components 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 vari

able 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 octetstring in buffer buf.

The function snmp_pdu_dump() dumps the PDU in a human read

able 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

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 han

dler 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]

A variable binding value was out of the

allowed range.

[SNMP_CODE_BADVERS]

The PDU is of an unsupported version.

[SNMP_CODE_BADENQ]

There was an ASN.1 value with an unsup

ported tag.

snmp_pdu_encode() will return one of the following return

codes:

[SNMP_CODE_OK] Success.

[SNMP_CODE_FAILED]

Encoding failed.

SEE ALSO

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

bsnmplib(3)

STANDARDS

This implementation conforms to the applicable IETF RFCs and

ITU-T recommendations.

AUTHORS

Hartmut Brandt <harti@freebsd.org>

BSD October 4, 2005

BSD