.\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" .\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/lib/bsnmplib.3,v 1.9 2005/10/04 08:46:51 brandt_h Exp $ .\" .Dd October 4, 2005 .Dt BSNMPLIB 3 .Os .Sh NAME .Nm snmp_value_free , .Nm snmp_value_parse , .Nm snmp_value_copy , .Nm snmp_pdu_free , .Nm snmp_code snmp_pdu_decode , .Nm snmp_code snmp_pdu_encode , .Nm snmp_pdu_dump , .Nm TRUTH_MK , .Nm TRUTH_GET , .Nm TRUTH_OK .Nd "SNMP decoding and encoding library" .Sh LIBRARY Begemot SNMP library .Pq libbsnmp, -lbsnmp .Sh SYNOPSIS .In bsnmp/asn1.h .In bsnmp/snmp.h .Ft void .Fn snmp_value_free "struct snmp_value *value" .Ft int .Fn snmp_value_parse "const char *buf" "enum snmp_syntax" "union snmp_values *value" .Ft int .Fn snmp_value_copy "struct snmp_value *to" "const struct snmp_value *from" .Ft void .Fn snmp_pdu_free "struct snmp_pdu *value" .Ft enum snmp_code .Fn snmp_pdu_decode "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip" .Ft enum snmp_code .Fn snmp_pdu_encode "struct snmp_pdu *pdu" "struct asn_buf *buf" .Ft void .Fn snmp_pdu_dump "const struct snmp_pdu *pdu" .Ft int .Fn TRUTH_MK "F" .Ft int .Fn TRUTH_GET "T" .Ft int .Fn TRUTH_OK "T" .Sh DESCRIPTION The SNMP library contains routines to handle SNMP version 1 and 2 PDUs. There are two basic structures used throughout the library: .Bd -literal -offset indent 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]; uint32_t uint32; /* also gauge32, counter32, unsigned32, timeticks */ uint64_t counter64; } v; }; .Ed .Pp This structure represents one variable binding from an SNMP PDU. The field .Fa var is the ASN.1 of the variable that is bound. .Fa syntax contains either the syntax code of the value or an exception code for SNMPv2 and may be one of: .Bd -literal -offset indent 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, }; .Ed The field .Fa v holds the actual value depending on .Fa syntax . Note, that if .Fa syntax is .Li SNMP_SYNTAX_OCTETSTRING and .Fa v.octetstring.len is not zero, .Fa v.octetstring.octets points to a string allocated by .Xr malloc 3 . .Pp .Bd -literal -offset indent #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; }; .Ed This structure contains a decoded SNMP PDU. .Fa version is one of .Bd -literal -offset indent enum snmp_version { SNMP_Verr = 0, SNMP_V1 = 1, SNMP_V2c, }; .Ed and .Fa type is the type of the PDU. .Pp The function .Fn 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 .Fa value itself. .Pp The function .Fn 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 .Xr bsnmpd 1 . .Pp The function .Fn snmp_value_copy makes a deep copy of the value pointed to by .Fa from to the structure pointed to by .Fa to . It assumes that .Fa to is uninitialized and will overwrite its previous contents. It does not itself allocate the structure pointed to by .Fa to . .Pp The function .Fn snmp_pdu_free frees all the dynamically allocated components of the PDU. It does not itself free the structure pointed to by .Fa pdu . .Pp The function .Fn snmp_pdu_decode decodes the PDU pointed to by .Fa buf and stores the result into .Fa pdu . If an error occurs in a variable binding the (1 based) index of this binding is stored in the variable pointed to by .Fa ip . .Pp The function .Fn snmp_pdu_encode encodes the PDU .Fa pdu into the an octetstring in buffer .Fa buf . .Pp The function .Fn snmp_pdu_dump dumps the PDU in a human readable form by calling .Fn snmp_printf . .Pp The function .Fn TRUTH_MK takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1). The function .Fn TRUTH_GET takes an SNMP truth value and makes a C truth value (0 or 1). The function .Fn TRUTH_OK checks, whether its argument is a legal SNMP truth value. .Sh DIAGNOSTICS When an error occurs in any of the function the function pointed to by the global pointer .Bd -literal -offset indent extern void (*snmp_error)(const char *, ...); .Ed .Pp with a .Xr printf 3 style format string. There is a default error handler in the library that prints a message starting with .Sq SNMP: followed by the error message to standard error. .Pp The function pointed to by .Bd -literal -offset indent extern void (*snmp_printf)(const char *, ...); .Ed .Pp is called by the .Fn snmp_pdu_dump function. The default handler is .Xr printf 3 . .Sh ERRORS .Fn snmp_pdu_decode will return one of the following return codes: .Bl -tag -width Er .It Bq Er SNMP_CODE_OK Success. .It Bq Er SNMP_CODE_FAILED The ASN.1 coding was wrong. .It Bq Er SNMP_CODE_BADLEN A variable binding value had a wrong length field. .It Bq Er SNMP_CODE_OORANGE A variable binding value was out of the allowed range. .It Bq Er SNMP_CODE_BADVERS The PDU is of an unsupported version. .It Bq Er SNMP_CODE_BADENQ There was an ASN.1 value with an unsupported tag. .El .Pp .Fn snmp_pdu_encode will return one of the following return codes: .Bl -tag -width Er .It Bq Er SNMP_CODE_OK Success. .It Bq Er SNMP_CODE_FAILED Encoding failed. .El .Sh SEE ALSO .Xr gensnmptree 1 , .Xr bsnmpd 1 , .Xr bsnmpagent 3 , .Xr bsnmpclient 3 , .Xr bsnmplib 3 .Sh STANDARDS This implementation conforms to the applicable IETF RFCs and ITU-T recommendations. .Sh AUTHORS .An Hartmut Brandt Aq harti@FreeBSD.org