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.Pp 138.Bd -literal -offset indent 139#define SNMP_COMMUNITY_MAXLEN 128 140#define SNMP_MAX_BINDINGS 100 141 142struct snmp_pdu { 143 char community[SNMP_COMMUNITY_MAXLEN + 1]; 144 enum snmp_version version; 145 u_int type; 146 147 /* trap only */ 148 struct asn_oid enterprise; 149 u_char agent_addr[4]; 150 int32_t generic_trap; 151 int32_t specific_trap; 152 u_int32_t time_stamp; 153 154 /* others */ 155 int32_t request_id; 156 int32_t error_status; 157 int32_t error_index; 158 159 /* fixes for encoding */ 160 u_char *outer_ptr; 161 u_char *pdu_ptr; 162 u_char *vars_ptr; 163 164 struct snmp_value bindings[SNMP_MAX_BINDINGS]; 165 u_int nbindings; 166}; 167.Ed 168This structure contains a decoded SNMP PDU. 169.Fa version 170is one of 171.Bd -literal -offset indent 172enum snmp_version { 173 SNMP_Verr = 0, 174 SNMP_V1 = 1, 175 SNMP_V2c, 176}; 177.Ed 178and 179.Fa type 180is the type of the PDU. 181.Pp 182The function 183.Fn snmp_value_free 184is used to free all the dynamic allocated contents of an SNMP value. 185It does not free the structure pointed to by 186.Fa value 187itself. 188.Pp 189The function 190.Fn snmp_value_parse 191parses the ASCII representation of an SNMP value into its binary form. 192This function is mainly used by the configuration file reader of 193.Xr bsnmpd 1 . 194.Pp 195The function 196.Fn snmp_value_copy 197makes a deep copy of the value pointed to by 198.Fa from 199to the structure pointed to by 200.Fa to . 201It assumes that 202.Fa to 203is uninitialized and will overwrite its previous contents. 204It does not itself allocate the structure pointed to by 205.Fa to . 206.Pp 207The function 208.Fn snmp_pdu_free 209frees all the dynamically allocated components of the PDU. 210It does not itself free the structure pointed to by 211.Fa pdu . 212.Pp 213The function 214.Fn snmp_pdu_decode 215decodes the PDU pointed to by 216.Fa buf 217and stores the result into 218.Fa pdu . 219If an error occurs in a variable binding the (1 based) index of this binding 220is stored in the variable pointed to by 221.Fa ip . 222.Pp 223The function 224.Fn snmp_pdu_encode 225encodes the PDU 226.Fa pdu 227into the an octetstring in buffer 228.Fa buf . 229.Pp 230The function 231.Fn snmp_pdu_dump 232dumps the PDU in a human readable form by calling 233.Fn snmp_printf . 234.Pp 235The function 236.Fn TRUTH_MK 237takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1). 238The function 239.Fn TRUTH_GET 240takes an SNMP truth value and makes a C truth value (0 or 1). 241The function 242.Fn TRUTH_OK 243checks, whether its argument is a legal SNMP truth value. 244.Sh DIAGNOSTICS 245When an error occurs in any of the function the function pointed to 246by the global pointer 247.Bd -literal -offset indent 248extern void (*snmp_error)(const char *, ...); 249.Ed 250.Pp 251with a 252.Xr printf 3 253style format string. 254There is a default error handler in the library that prints a message 255starting with 256.Sq SNMP: 257followed by the error message to standard error. 258.Pp 259The function pointed to by 260.Bd -literal -offset indent 261extern void (*snmp_printf)(const char *, ...); 262.Ed 263.Pp 264is called by the 265.Fn snmp_pdu_dump 266function. 267The default handler is 268.Xr printf 3 . 269.Sh ERRORS 270.Fn snmp_pdu_decode 271will return one of the following return codes: 272.Bl -tag -width Er 273.It Bq Er SNMP_CODE_OK 274Success. 275.It Bq Er SNMP_CODE_FAILED 276The ASN.1 coding was wrong. 277.It Bq Er SNMP_CODE_BADLEN 278A variable binding value had a wrong length field. 279.It Bq Er SNMP_CODE_OORANGE 280A variable binding value was out of the allowed range. 281.It Bq Er SNMP_CODE_BADVERS 282The PDU is of an unsupported version. 283.It Bq Er SNMP_CODE_BADENQ 284There was an ASN.1 value with an unsupported tag. 285.El 286.Pp 287.Fn snmp_pdu_encode 288will return one of the following return codes: 289.Bl -tag -width Er 290.It Bq Er SNMP_CODE_OK 291Success. 292.It Bq Er SNMP_CODE_FAILED 293Encoding failed. 294.El 295.Sh SEE ALSO 296.Xr gensnmptree 1 , 297.Xr bsnmpd 1 , 298.Xr bsnmpagent 3 , 299.Xr bsnmpclient 3 , 300.Xr bsnmplib 3 301.Sh STANDARDS 302This implementation conforms to the applicable IETF RFCs and ITU-T 303recommendations. 304.Sh AUTHORS 305.An Hartmut Brandt Aq harti@freebsd.org 306