contrib/bsnmp/lib/bsnmplib.3

   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>
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  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.
  19 .\"
  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
  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
  50 Begemot SNMP library
  51 .Pq libbsnmp, -lbsnmp
  52 .Sh SYNOPSIS
  53 .In bsnmp/asn1.h
  54 .In bsnmp/snmp.h
  55 .Ft void
  56 .Fn snmp_value_free "struct snmp_value *value"
  57 .Ft int
  58 .Fn snmp_value_parse "const char *buf" "enum snmp_syntax" "union snmp_values *value"
  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
  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
  79 struct 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;
  86             u_char              *octets;
  87           }                     octetstring;
  88           struct asn_oid        oid;
  89           u_char                ipaddress[4];
  90           uint32_t              uint32; /* also gauge32, counter32,
  91                                            unsigned32, timeticks */
  92           uint64_t              counter64;
  93         }                       v;
  94 };
  95 .Ed
  96 .Pp
  97 This structure represents one variable binding from an SNMP PDU.
  98 The field
  99 .Fa var
 100 is the ASN.1 of the variable that is bound.
 101 .Fa syntax
 102 contains either the syntax code of the value or an exception code for SNMPv2
 103 and may be one of:
 104 .Bd -literal -offset indent
 105 enum snmp_syntax {
 106         SNMP_SYNTAX_NULL        = 0,
 107         SNMP_SYNTAX_INTEGER,    /* == INTEGER32 */
 108         SNMP_SYNTAX_OCTETSTRING,
 109         SNMP_SYNTAX_OID,
 110         SNMP_SYNTAX_IPADDRESS,
 111         SNMP_SYNTAX_COUNTER,
 112         SNMP_SYNTAX_GAUGE,      /* == UNSIGNED32 */
 113         SNMP_SYNTAX_TIMETICKS,
 114
 115         /* v2 additions */
 116         SNMP_SYNTAX_COUNTER64,
 117         /* exceptions */
 118         SNMP_SYNTAX_NOSUCHOBJECT,
 119         SNMP_SYNTAX_NOSUCHINSTANCE,
 120         SNMP_SYNTAX_ENDOFMIBVIEW,
 121 };
 122 .Ed
 123 The field
 124 .Fa v
 125 holds the actual value depending on
 126 .Fa syntax .
 127 Note, that if
 128 .Fa syntax
 129 is
 130 .Li SNMP_SYNTAX_OCTETSTRING
 131 and
 132 .Fa v.octetstring.len
 133 is not zero,
 134 .Fa v.octetstring.octets
 135 points to a string allocated by
 136 .Xr malloc 3 .
 137 .Pp
 138 .Bd -literal -offset indent
 139 #define SNMP_COMMUNITY_MAXLEN   128
 140 #define SNMP_MAX_BINDINGS       100
 141
 142 struct snmp_pdu {
 143         char            community[SNMP_COMMUNITY_MAXLEN + 1];
 144         enum snmp_version version;
 145         u_int           type;
 146
 147         /* trap only */
 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;
 153
 154         /* others */
 155         int32_t         request_id;
 156         int32_t         error_status;
 157         int32_t         error_index;
 158
 159         /* fixes for encoding */
 160         u_char          *outer_ptr;
 161         u_char          *pdu_ptr;
 162         u_char          *vars_ptr;
 163
 164         struct snmp_value bindings[SNMP_MAX_BINDINGS];
 165         u_int           nbindings;
 166 };
 167 .Ed
 168 This structure contains a decoded SNMP PDU.
 169 .Fa version
 170 is one of
 171 .Bd -literal -offset indent
 172 enum snmp_version {
 173         SNMP_Verr = 0,
 174         SNMP_V1 = 1,
 175         SNMP_V2c,
 176 };
 177 .Ed
 178 and
 179 .Fa type
 180 is the type of the PDU.
 181 .Pp
 182 The function
 183 .Fn snmp_value_free
 184 is used to free all the dynamic allocated contents of an SNMP value.
 185 It does not free the structure pointed to by
 186 .Fa value
 187 itself.
 188 .Pp
 189 The function
 190 .Fn snmp_value_parse
 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
 193 .Xr bsnmpd 1 .
 194 .Pp
 195 The function
 196 .Fn snmp_value_copy
 197 makes a deep copy of the value pointed to by
 198 .Fa from
 199 to the structure pointed to by
 200 .Fa to .
 201 It assumes that
 202 .Fa to
 203 is uninitialized and will overwrite its previous contents.
 204 It does not itself allocate the structure pointed to by
 205 .Fa to .
 206 .Pp
 207 The function
 208 .Fn snmp_pdu_free
 209 frees all the dynamically allocated components of the PDU.
 210 It does not itself free the structure pointed to by
 211 .Fa pdu .
 212 .Pp
 213 The function
 214 .Fn snmp_pdu_decode
 215 decodes the PDU pointed to by
 216 .Fa buf
 217 and stores the result into
 218 .Fa pdu .
 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
 221 .Fa ip .
 222 .Pp
 223 The function
 224 .Fn snmp_pdu_encode
 225 encodes the PDU
 226 .Fa pdu
 227 into the an octetstring in buffer
 228 .Fa buf .
 229 .Pp
 230 The function
 231 .Fn snmp_pdu_dump
 232 dumps the PDU in a human readable form by calling
 233 .Fn snmp_printf .
 234 .Pp
 235 The function
 236 .Fn TRUTH_MK
 237 takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1).
 238 The function
 239 .Fn TRUTH_GET
 240 takes an SNMP truth value and makes a C truth value (0 or 1).
 241 The function
 242 .Fn TRUTH_OK
 243 checks, whether its argument is a legal SNMP truth value.
 244 .Sh DIAGNOSTICS
 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 *, ...);
 249 .Ed
 250 .Pp
 251 with a
 252 .Xr printf 3
 253 style format string.
 254 There is a default error handler in the library that prints a message
 255 starting with
 256 .Sq SNMP:
 257 followed by the error message to standard error.
 258 .Pp
 259 The function pointed to by
 260 .Bd -literal -offset indent
 261 extern void (*snmp_printf)(const char *, ...);
 262 .Ed
 263 .Pp
 264 is called by the
 265 .Fn snmp_pdu_dump
 266 function.
 267 The default handler is
 268 .Xr printf 3 .
 269 .Sh ERRORS
 270 .Fn snmp_pdu_decode
 271 will return one of the following return codes:
 272 .Bl -tag -width Er
 273 .It Bq Er SNMP_CODE_OK
 274 Success.
 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.
 285 .El
 286 .Pp
 287 .Fn snmp_pdu_encode
 288 will return one of the following return codes:
 289 .Bl -tag -width Er
 290 .It Bq Er SNMP_CODE_OK
 291 Success.
 292 .It Bq Er SNMP_CODE_FAILED
 293 Encoding failed.
 294 .El
 295 .Sh SEE ALSO
 296 .Xr gensnmptree 1 ,
 297 .Xr bsnmpd 1 ,
 298 .Xr bsnmpagent 3 ,
 299 .Xr bsnmpclient 3 ,
 300 .Xr bsnmplib 3
 301 .Sh STANDARDS
 302 This implementation conforms to the applicable IETF RFCs and ITU-T
 303 recommendations.
 304 .Sh AUTHORS
 305 .An Hartmut Brandt Aq harti@freebsd.org