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