1.\"
2.\" Copyright (c) 2004-2005
3.\" Hartmut Brandt.
4.\" All rights reserved.
5.\" Copyright (c) 2001-2003
6.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
7.\" All rights reserved.
8.\"
9.\" Author: Harti Brandt <harti@FreeBSD.org>
--- 16 unchanged lines hidden (view full) ---
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
30.\" SUCH DAMAGE.
31.\"
32.\" $Begemot: bsnmp/lib/bsnmplib.3,v 1.9 2005/10/04 08:46:51 brandt_h Exp $
33.\"
34.Dd October 4, 2005
35.Dt BSNMPLIB 3
36.Os
37.Sh NAME
38.Nm snmp_value_free ,
39.Nm snmp_value_parse ,
40.Nm snmp_value_copy ,
41.Nm snmp_pdu_free ,
42.Nm snmp_code snmp_pdu_decode ,
43.Nm snmp_code snmp_pdu_encode ,
44.Nm snmp_pdu_dump ,
45.Nm TRUTH_MK ,
46.Nm TRUTH_GET ,
47.Nm TRUTH_OK
48.Nd "SNMP decoding and encoding library"
49.Sh LIBRARY
50Begemot SNMP library
51.Pq libbsnmp, -lbsnmp
52.Sh SYNOPSIS
--- 6 unchanged lines hidden (view full) ---
59.Ft int
60.Fn snmp_value_copy "struct snmp_value *to" "const struct snmp_value *from"
61.Ft void
62.Fn snmp_pdu_free "struct snmp_pdu *value"
63.Ft enum snmp_code
64.Fn snmp_pdu_decode "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip"
65.Ft enum snmp_code
66.Fn snmp_pdu_encode "struct snmp_pdu *pdu" "struct asn_buf *buf"
67.Ft void
68.Fn snmp_pdu_dump "const struct snmp_pdu *pdu"
69.Ft int
70.Fn TRUTH_MK "F"
71.Ft int
72.Fn TRUTH_GET "T"
73.Ft int
74.Fn TRUTH_OK "T"
75.Sh DESCRIPTION
76The SNMP library contains routines to handle SNMP version 1 and 2 PDUs.
77There are two basic structures used throughout the library:
78.Bd -literal -offset indent
79struct snmp_value {
80 struct asn_oid var;
81 enum snmp_syntax syntax;
82 union snmp_values {
83 int32_t integer;/* also integer32 */
84 struct {
85 u_int len;
--- 43 unchanged lines hidden (view full) ---
129is
130.Li SNMP_SYNTAX_OCTETSTRING
131and
132.Fa v.octetstring.len
133is not zero,
134.Fa v.octetstring.octets
135points to a string allocated by
136.Xr malloc 3 .
137.Bd -literal -offset indent
138#define SNMP_COMMUNITY_MAXLEN 128
139#define SNMP_MAX_BINDINGS 100
140
141struct snmp_pdu {
142 char community[SNMP_COMMUNITY_MAXLEN + 1];
143 enum snmp_version version;
144 u_int type;
145
146 /* trap only */
147 struct asn_oid enterprise;
148 u_char agent_addr[4];
149 int32_t generic_trap;
150 int32_t specific_trap;
151 u_int32_t time_stamp;
152
153 /* others */
154 int32_t request_id;
155 int32_t error_status;
156 int32_t error_index;
157
158 /* fixes for encoding */
159 u_char *outer_ptr;
160 u_char *pdu_ptr;
161 u_char *vars_ptr;
162
163 struct snmp_value bindings[SNMP_MAX_BINDINGS];
164 u_int nbindings;
165};
166.Ed
167This structure contains a decoded SNMP PDU.
168.Fa version
169is one of
170.Bd -literal -offset indent
171enum snmp_version {
172 SNMP_Verr = 0,
173 SNMP_V1 = 1,
174 SNMP_V2c,
175};
176.Ed
177and
178.Fa type
179is the type of the PDU.
180.Pp
181The function
182.Fn snmp_value_free
183is used to free all the dynamic allocated contents of an SNMP value.
184It does not free the structure pointed to by
185.Fa value
186itself.
187.Pp
--- 30 unchanged lines hidden (view full) ---
218If an error occurs in a variable binding the (1 based) index of this binding
219is stored in the variable pointed to by
220.Fa ip .
221.Pp
222The function
223.Fn snmp_pdu_encode
224encodes the PDU
225.Fa pdu
226into the an octetstring in buffer
227.Fa buf .
228.Pp
229The function
230.Fn snmp_pdu_dump
231dumps the PDU in a human readable form by calling
232.Fn snmp_printf .
233.Pp
234The function
235.Fn TRUTH_MK
236takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1).
237The function
238.Fn TRUTH_GET
239takes an SNMP truth value and makes a C truth value (0 or 1).
240The function
241.Fn TRUTH_OK
242checks, whether its argument is a legal SNMP truth value.
--- 33 unchanged lines hidden (view full) ---
276.It Bq Er SNMP_CODE_BADLEN
277A variable binding value had a wrong length field.
278.It Bq Er SNMP_CODE_OORANGE
279A variable binding value was out of the allowed range.
280.It Bq Er SNMP_CODE_BADVERS
281The PDU is of an unsupported version.
282.It Bq Er SNMP_CODE_BADENQ
283There was an ASN.1 value with an unsupported tag.
284.El
285.Pp
286.Fn snmp_pdu_encode
287will return one of the following return codes:
288.Bl -tag -width Er
289.It Bq Er SNMP_CODE_OK
290Success.
291.It Bq Er SNMP_CODE_FAILED
292Encoding failed.
293.El
294.Sh SEE ALSO
295.Xr gensnmptree 1 ,
296.Xr bsnmpd 1 ,
297.Xr bsnmpagent 3 ,
298.Xr bsnmpclient 3 ,
299.Xr bsnmplib 3
300.Sh STANDARDS
301This implementation conforms to the applicable IETF RFCs and ITU-T
302recommendations.
303.Sh AUTHORS
304.An Hartmut Brandt Aq harti@FreeBSD.org
2.\" Copyright (c) 2004-2005
3.\" Hartmut Brandt.
4.\" All rights reserved.
5.\" Copyright (c) 2001-2003
6.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
7.\" All rights reserved.
8.\"
9.\" Author: Harti Brandt <harti@FreeBSD.org>
--- 16 unchanged lines hidden (view full) ---
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
30.\" SUCH DAMAGE.
31.\"
32.\" $Begemot: bsnmp/lib/bsnmplib.3,v 1.9 2005/10/04 08:46:51 brandt_h Exp $
33.\"
34.Dd October 4, 2005
35.Dt BSNMPLIB 3
36.Os
37.Sh NAME
38.Nm snmp_value_free ,
39.Nm snmp_value_parse ,
40.Nm snmp_value_copy ,
41.Nm snmp_pdu_free ,
42.Nm snmp_code snmp_pdu_decode ,
43.Nm snmp_code snmp_pdu_encode ,
44.Nm snmp_pdu_dump ,
45.Nm TRUTH_MK ,
46.Nm TRUTH_GET ,
47.Nm TRUTH_OK
48.Nd "SNMP decoding and encoding library"
49.Sh LIBRARY
50Begemot SNMP library
51.Pq libbsnmp, -lbsnmp
52.Sh SYNOPSIS
--- 6 unchanged lines hidden (view full) ---
59.Ft int
60.Fn snmp_value_copy "struct snmp_value *to" "const struct snmp_value *from"
61.Ft void
62.Fn snmp_pdu_free "struct snmp_pdu *value"
63.Ft enum snmp_code
64.Fn snmp_pdu_decode "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip"
65.Ft enum snmp_code
66.Fn snmp_pdu_encode "struct snmp_pdu *pdu" "struct asn_buf *buf"
67.Ft void
68.Fn snmp_pdu_dump "const struct snmp_pdu *pdu"
69.Ft int
70.Fn TRUTH_MK "F"
71.Ft int
72.Fn TRUTH_GET "T"
73.Ft int
74.Fn TRUTH_OK "T"
75.Sh DESCRIPTION
76The SNMP library contains routines to handle SNMP version 1 and 2 PDUs.
77There are two basic structures used throughout the library:
78.Bd -literal -offset indent
79struct snmp_value {
80 struct asn_oid var;
81 enum snmp_syntax syntax;
82 union snmp_values {
83 int32_t integer;/* also integer32 */
84 struct {
85 u_int len;
--- 43 unchanged lines hidden (view full) ---
129is
130.Li SNMP_SYNTAX_OCTETSTRING
131and
132.Fa v.octetstring.len
133is not zero,
134.Fa v.octetstring.octets
135points to a string allocated by
136.Xr malloc 3 .
137.Bd -literal -offset indent
138#define SNMP_COMMUNITY_MAXLEN 128
139#define SNMP_MAX_BINDINGS 100
140
141struct snmp_pdu {
142 char community[SNMP_COMMUNITY_MAXLEN + 1];
143 enum snmp_version version;
144 u_int type;
145
146 /* trap only */
147 struct asn_oid enterprise;
148 u_char agent_addr[4];
149 int32_t generic_trap;
150 int32_t specific_trap;
151 u_int32_t time_stamp;
152
153 /* others */
154 int32_t request_id;
155 int32_t error_status;
156 int32_t error_index;
157
158 /* fixes for encoding */
159 u_char *outer_ptr;
160 u_char *pdu_ptr;
161 u_char *vars_ptr;
162
163 struct snmp_value bindings[SNMP_MAX_BINDINGS];
164 u_int nbindings;
165};
166.Ed
167This structure contains a decoded SNMP PDU.
168.Fa version
169is one of
170.Bd -literal -offset indent
171enum snmp_version {
172 SNMP_Verr = 0,
173 SNMP_V1 = 1,
174 SNMP_V2c,
175};
176.Ed
177and
178.Fa type
179is the type of the PDU.
180.Pp
181The function
182.Fn snmp_value_free
183is used to free all the dynamic allocated contents of an SNMP value.
184It does not free the structure pointed to by
185.Fa value
186itself.
187.Pp
--- 30 unchanged lines hidden (view full) ---
218If an error occurs in a variable binding the (1 based) index of this binding
219is stored in the variable pointed to by
220.Fa ip .
221.Pp
222The function
223.Fn snmp_pdu_encode
224encodes the PDU
225.Fa pdu
226into the an octetstring in buffer
227.Fa buf .
228.Pp
229The function
230.Fn snmp_pdu_dump
231dumps the PDU in a human readable form by calling
232.Fn snmp_printf .
233.Pp
234The function
235.Fn TRUTH_MK
236takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1).
237The function
238.Fn TRUTH_GET
239takes an SNMP truth value and makes a C truth value (0 or 1).
240The function
241.Fn TRUTH_OK
242checks, whether its argument is a legal SNMP truth value.
--- 33 unchanged lines hidden (view full) ---
276.It Bq Er SNMP_CODE_BADLEN
277A variable binding value had a wrong length field.
278.It Bq Er SNMP_CODE_OORANGE
279A variable binding value was out of the allowed range.
280.It Bq Er SNMP_CODE_BADVERS
281The PDU is of an unsupported version.
282.It Bq Er SNMP_CODE_BADENQ
283There was an ASN.1 value with an unsupported tag.
284.El
285.Pp
286.Fn snmp_pdu_encode
287will return one of the following return codes:
288.Bl -tag -width Er
289.It Bq Er SNMP_CODE_OK
290Success.
291.It Bq Er SNMP_CODE_FAILED
292Encoding failed.
293.El
294.Sh SEE ALSO
295.Xr gensnmptree 1 ,
296.Xr bsnmpd 1 ,
297.Xr bsnmpagent 3 ,
298.Xr bsnmpclient 3 ,
299.Xr bsnmplib 3
300.Sh STANDARDS
301This implementation conforms to the applicable IETF RFCs and ITU-T
302recommendations.
303.Sh AUTHORS
304.An Hartmut Brandt Aq harti@FreeBSD.org