diff options
Diffstat (limited to 'contrib/bsnmp/lib/bsnmplib.3')
| -rw-r--r-- | contrib/bsnmp/lib/bsnmplib.3 | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/contrib/bsnmp/lib/bsnmplib.3 b/contrib/bsnmp/lib/bsnmplib.3 new file mode 100644 index 0000000..13f9651 --- /dev/null +++ b/contrib/bsnmp/lib/bsnmplib.3 @@ -0,0 +1,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.2 2002/08/16 10:02:53 hbb 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 brandt@fokus.gmd.de |
