2 .\" Copyright (c) 2004-2005
4 .\" All rights reserved.
5 .\" Copyright (c) 2001-2003
6 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
7 .\" All rights reserved.
9 .\" Author: Harti Brandt <harti@freebsd.org>
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
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.
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
32 .\" $Begemot: bsnmp/lib/bsnmplib.3,v 1.9 2005/10/04 08:46:51 brandt_h Exp $
39 .Nm snmp_value_parse ,
42 .Nm snmp_code snmp_pdu_decode ,
43 .Nm snmp_code snmp_pdu_encode ,
48 .Nd "SNMP decoding and encoding library"
56 .Fn snmp_value_free "struct snmp_value *value"
58 .Fn snmp_value_parse "const char *buf" "enum snmp_syntax" "union snmp_values *value"
60 .Fn snmp_value_copy "struct snmp_value *to" "const struct snmp_value *from"
62 .Fn snmp_pdu_free "struct snmp_pdu *value"
64 .Fn snmp_pdu_decode "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip"
66 .Fn snmp_pdu_encode "struct snmp_pdu *pdu" "struct asn_buf *buf"
68 .Fn snmp_pdu_dump "const struct snmp_pdu *pdu"
76 The SNMP library contains routines to handle SNMP version 1 and 2 PDUs.
77 There are two basic structures used throughout the library:
78 .Bd -literal -offset indent
81 enum snmp_syntax syntax;
83 int32_t integer;/* also integer32 */
90 uint32_t uint32; /* also gauge32, counter32,
91 unsigned32, timeticks */
97 This structure represents one variable binding from an SNMP PDU.
100 is the ASN.1 of the variable that is bound.
102 contains either the syntax code of the value or an exception code for SNMPv2
104 .Bd -literal -offset indent
106 SNMP_SYNTAX_NULL = 0,
107 SNMP_SYNTAX_INTEGER, /* == INTEGER32 */
108 SNMP_SYNTAX_OCTETSTRING,
110 SNMP_SYNTAX_IPADDRESS,
112 SNMP_SYNTAX_GAUGE, /* == UNSIGNED32 */
113 SNMP_SYNTAX_TIMETICKS,
116 SNMP_SYNTAX_COUNTER64,
118 SNMP_SYNTAX_NOSUCHOBJECT,
119 SNMP_SYNTAX_NOSUCHINSTANCE,
120 SNMP_SYNTAX_ENDOFMIBVIEW,
125 holds the actual value depending on
130 .Li SNMP_SYNTAX_OCTETSTRING
132 .Fa v.octetstring.len
134 .Fa v.octetstring.octets
135 points to a string allocated by
138 .Bd -literal -offset indent
139 #define SNMP_COMMUNITY_MAXLEN 128
140 #define SNMP_MAX_BINDINGS 100
143 char community[SNMP_COMMUNITY_MAXLEN + 1];
144 enum snmp_version version;
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;
156 int32_t error_status;
159 /* fixes for encoding */
164 struct snmp_value bindings[SNMP_MAX_BINDINGS];
168 This structure contains a decoded SNMP PDU.
171 .Bd -literal -offset indent
180 is the type of the PDU.
184 is used to free all the dynamic allocated contents of an SNMP value.
185 It does not free the structure pointed to by
191 parses the ASCII representation of an SNMP value into its binary form.
192 This function is mainly used by the configuration file reader of
197 makes a deep copy of the value pointed to by
199 to the structure pointed to by
203 is uninitialized and will overwrite its previous contents.
204 It does not itself allocate the structure pointed to by
209 frees all the dynamically allocated components of the PDU.
210 It does not itself free the structure pointed to by
215 decodes the PDU pointed to by
217 and stores the result into
219 If an error occurs in a variable binding the (1 based) index of this binding
220 is stored in the variable pointed to by
227 into the an octetstring in buffer
232 dumps the PDU in a human readable form by calling
237 takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1).
240 takes an SNMP truth value and makes a C truth value (0 or 1).
243 checks, whether its argument is a legal SNMP truth value.
245 When an error occurs in any of the function the function pointed to
246 by the global pointer
247 .Bd -literal -offset indent
248 extern void (*snmp_error)(const char *, ...);
254 There is a default error handler in the library that prints a message
257 followed by the error message to standard error.
259 The function pointed to by
260 .Bd -literal -offset indent
261 extern void (*snmp_printf)(const char *, ...);
267 The default handler is
271 will return one of the following return codes:
273 .It Bq Er SNMP_CODE_OK
275 .It Bq Er SNMP_CODE_FAILED
276 The ASN.1 coding was wrong.
277 .It Bq Er SNMP_CODE_BADLEN
278 A variable binding value had a wrong length field.
279 .It Bq Er SNMP_CODE_OORANGE
280 A variable binding value was out of the allowed range.
281 .It Bq Er SNMP_CODE_BADVERS
282 The PDU is of an unsupported version.
283 .It Bq Er SNMP_CODE_BADENQ
284 There was an ASN.1 value with an unsupported tag.
288 will return one of the following return codes:
290 .It Bq Er SNMP_CODE_OK
292 .It Bq Er SNMP_CODE_FAILED
302 This implementation conforms to the applicable IETF RFCs and ITU-T
305 .An Hartmut Brandt Aq harti@freebsd.org