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