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