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 integer32 */ |
|||||
|
struct { |
||||||
|
u_int |
len; |
|||||
|
u_char |
*octets; |
|||||
|
} |
octetstring; |
|||||
|
struct asn_oid |
oid; |
|||||
|
u_char |
ipaddress[4]; |
|||||
|
u_int32_t |
uint32; |
/* also gauge32, counter32, |
||||
|
unsigned32, timeticks */ |
||||||
|
u_int64_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 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, | |
|
SNMP_V2c, |
};
and type is the type of the PDU.
The function snmp_value_free() is used to free all the dynamic 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 representation of an SNMP value into its binary form. This function is mainly used by the configuration file reader of snmpd(1).
The function snmp_value_copy() makes a deep copy of the value 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 allocated 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 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 octetstring 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 occures 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]
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 unsupported tag.
snmp_pdu_encode() will return one of the following return codes:
[SNMP_CODE_OK]
Success.
[SNMP_CODE_FAILED]
Encoding failed.
SEE ALSO
snmpd(1), gensnmptree(1), bsnmplib(3) bsnmpclient(3), bsnmpagent(3)
STANDARDS
This implementation conforms to the applicable IETF RFCs and ITU-T recommendations.
AUTHORS
Hartmut Brandt <harti [AT] freebsd.org>
BSD August 15, 2002 BSD