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.\"
| 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.\"
|
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
| 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
|