1.\" 2.\" Copyright (c) 2004-2005 3.\" Hartmut Brandt. 4.\" All rights reserved. 5.\" Copyright (c) 2001-2003 6.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). 7.\" All rights reserved. 8.\" 9.\" Author: Harti Brandt <harti@FreeBSD.org> 10.\" 11.\" Redistribution and use in source and binary forms, with or without 12.\" modification, are permitted provided that the following conditions 13.\" are met: 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in the 18.\" documentation and/or other materials provided with the distribution. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" $Begemot: bsnmp/lib/bsnmplib.3,v 1.9 2005/10/04 08:46:51 brandt_h Exp $ 33.\" 34.Dd October 4, 2005 35.Dt BSNMPLIB 3 36.Os 37.Sh NAME 38.Nm snmp_value_free , 39.Nm snmp_value_parse , 40.Nm snmp_value_copy , 41.Nm snmp_pdu_free , 42.Nm snmp_code snmp_pdu_decode , 43.Nm snmp_code snmp_pdu_encode , 44.Nm snmp_pdu_dump , 45.Nm TRUTH_MK , 46.Nm TRUTH_GET , 47.Nm TRUTH_OK 48.Nd "SNMP decoding and encoding library" 49.Sh LIBRARY 50Begemot SNMP library 51.Pq libbsnmp, -lbsnmp 52.Sh SYNOPSIS 53.In bsnmp/asn1.h 54.In bsnmp/snmp.h 55.Ft void 56.Fn snmp_value_free "struct snmp_value *value" 57.Ft int 58.Fn snmp_value_parse "const char *buf" "enum snmp_syntax" "union snmp_values *value" 59.Ft int 60.Fn snmp_value_copy "struct snmp_value *to" "const struct snmp_value *from" 61.Ft void 62.Fn snmp_pdu_free "struct snmp_pdu *value" 63.Ft enum snmp_code 64.Fn snmp_pdu_decode "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip" 65.Ft enum snmp_code 66.Fn snmp_pdu_encode "struct snmp_pdu *pdu" "struct asn_buf *buf" 67.Ft void 68.Fn snmp_pdu_dump "const struct snmp_pdu *pdu" 69.Ft int 70.Fn TRUTH_MK "F" 71.Ft int 72.Fn TRUTH_GET "T" 73.Ft int 74.Fn TRUTH_OK "T" 75.Sh DESCRIPTION 76The SNMP library contains routines to handle SNMP version 1 and 2 PDUs. 77There are two basic structures used throughout the library: 78.Bd -literal -offset indent 79struct snmp_value { 80 struct asn_oid var; 81 enum snmp_syntax syntax; 82 union snmp_values { 83 int32_t integer;/* also integer32 */ 84 struct { 85 u_int len; 86 u_char *octets; 87 } octetstring; 88 struct asn_oid oid; 89 u_char ipaddress[4]; 90 uint32_t uint32; /* also gauge32, counter32, 91 unsigned32, timeticks */ 92 uint64_t counter64; 93 } v; 94}; 95.Ed 96.Pp 97This structure represents one variable binding from an SNMP PDU. 98The field 99.Fa var 100is the ASN.1 of the variable that is bound. 101.Fa syntax 102contains either the syntax code of the value or an exception code for SNMPv2 103and may be one of: 104.Bd -literal -offset indent 105enum snmp_syntax { 106 SNMP_SYNTAX_NULL = 0, 107 SNMP_SYNTAX_INTEGER, /* == INTEGER32 */ 108 SNMP_SYNTAX_OCTETSTRING, 109 SNMP_SYNTAX_OID, 110 SNMP_SYNTAX_IPADDRESS, 111 SNMP_SYNTAX_COUNTER, 112 SNMP_SYNTAX_GAUGE, /* == UNSIGNED32 */ 113 SNMP_SYNTAX_TIMETICKS, 114 115 /* v2 additions */ 116 SNMP_SYNTAX_COUNTER64, 117 /* exceptions */ 118 SNMP_SYNTAX_NOSUCHOBJECT, 119 SNMP_SYNTAX_NOSUCHINSTANCE, 120 SNMP_SYNTAX_ENDOFMIBVIEW, 121}; 122.Ed 123The field 124.Fa v 125holds the actual value depending on 126.Fa syntax . 127Note, that if 128.Fa syntax 129is 130.Li SNMP_SYNTAX_OCTETSTRING 131and 132.Fa v.octetstring.len 133is not zero, 134.Fa v.octetstring.octets 135points to a string allocated by 136.Xr malloc 3 . 137.Bd -literal -offset indent 138#define SNMP_COMMUNITY_MAXLEN 128 139#define SNMP_MAX_BINDINGS 100 140 141struct snmp_pdu { 142 char community[SNMP_COMMUNITY_MAXLEN + 1]; 143 enum snmp_version version; 144 u_int type; 145 146 /* trap only */ 147 struct asn_oid enterprise; 148 u_char agent_addr[4]; 149 int32_t generic_trap; 150 int32_t specific_trap; 151 u_int32_t time_stamp; 152 153 /* others */ 154 int32_t request_id; 155 int32_t error_status; 156 int32_t error_index; 157 158 /* fixes for encoding */ 159 u_char *outer_ptr; 160 u_char *pdu_ptr; 161 u_char *vars_ptr; 162 163 struct snmp_value bindings[SNMP_MAX_BINDINGS]; 164 u_int nbindings; 165}; 166.Ed 167This structure contains a decoded SNMP PDU. 168.Fa version 169is one of 170.Bd -literal -offset indent 171enum snmp_version { 172 SNMP_Verr = 0, 173 SNMP_V1 = 1, 174 SNMP_V2c, 175}; 176.Ed 177and 178.Fa type 179is the type of the PDU. 180.Pp 181The function 182.Fn snmp_value_free 183is used to free all the dynamic allocated contents of an SNMP value. 184It does not free the structure pointed to by 185.Fa value 186itself. 187.Pp 188The function 189.Fn snmp_value_parse 190parses the ASCII representation of an SNMP value into its binary form. 191This function is mainly used by the configuration file reader of 192.Xr bsnmpd 1 . 193.Pp 194The function 195.Fn snmp_value_copy 196makes a deep copy of the value pointed to by 197.Fa from 198to the structure pointed to by 199.Fa to . 200It assumes that 201.Fa to 202is uninitialized and will overwrite its previous contents. 203It does not itself allocate the structure pointed to by 204.Fa to . 205.Pp 206The function 207.Fn snmp_pdu_free 208frees all the dynamically allocated components of the PDU. 209It does not itself free the structure pointed to by 210.Fa pdu . 211.Pp 212The function 213.Fn snmp_pdu_decode 214decodes the PDU pointed to by 215.Fa buf 216and stores the result into 217.Fa pdu . 218If an error occurs in a variable binding the (1 based) index of this binding 219is stored in the variable pointed to by 220.Fa ip . 221.Pp 222The function 223.Fn snmp_pdu_encode 224encodes the PDU 225.Fa pdu 226into the an octetstring in buffer 227.Fa buf . 228.Pp 229The function 230.Fn snmp_pdu_dump 231dumps the PDU in a human readable form by calling 232.Fn snmp_printf . 233.Pp 234The function 235.Fn TRUTH_MK 236takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1). 237The function 238.Fn TRUTH_GET 239takes an SNMP truth value and makes a C truth value (0 or 1). 240The function 241.Fn TRUTH_OK 242checks, whether its argument is a legal SNMP truth value. 243.Sh DIAGNOSTICS 244When an error occurs in any of the function the function pointed to 245by the global pointer 246.Bd -literal -offset indent 247extern void (*snmp_error)(const char *, ...); 248.Ed 249.Pp 250with a 251.Xr printf 3 252style format string. 253There is a default error handler in the library that prints a message 254starting with 255.Sq SNMP: 256followed by the error message to standard error. 257.Pp 258The function pointed to by 259.Bd -literal -offset indent 260extern void (*snmp_printf)(const char *, ...); 261.Ed 262.Pp 263is called by the 264.Fn snmp_pdu_dump 265function. 266The default handler is 267.Xr printf 3 . 268.Sh ERRORS 269.Fn snmp_pdu_decode 270will return one of the following return codes: 271.Bl -tag -width Er 272.It Bq Er SNMP_CODE_OK 273Success. 274.It Bq Er SNMP_CODE_FAILED 275The ASN.1 coding was wrong. 276.It Bq Er SNMP_CODE_BADLEN 277A variable binding value had a wrong length field. 278.It Bq Er SNMP_CODE_OORANGE 279A variable binding value was out of the allowed range. 280.It Bq Er SNMP_CODE_BADVERS 281The PDU is of an unsupported version. 282.It Bq Er SNMP_CODE_BADENQ 283There was an ASN.1 value with an unsupported tag. 284.El 285.Pp 286.Fn snmp_pdu_encode 287will return one of the following return codes: 288.Bl -tag -width Er 289.It Bq Er SNMP_CODE_OK 290Success. 291.It Bq Er SNMP_CODE_FAILED 292Encoding failed. 293.El 294.Sh SEE ALSO 295.Xr gensnmptree 1 , 296.Xr bsnmpd 1 , 297.Xr bsnmpagent 3 , 298.Xr bsnmpclient 3 , 299.Xr bsnmplib 3 300.Sh STANDARDS 301This implementation conforms to the applicable IETF RFCs and ITU-T 302recommendations. 303.Sh AUTHORS 304.An Hartmut Brandt Aq harti@FreeBSD.org 305