Virgin import of bsnmpd 1.11

1 files changed, 136 insertions, 97 deletions

diff --git a/contrib/bsnmp/lib/bsnmpclient.3 b/contrib/bsnmp/lib/bsnmpclient.3
index e932eba..ffcce83 100644
--- a/contrib/bsnmp/lib/bsnmpclient.3
+++ b/contrib/bsnmp/lib/bsnmpclient.3
@@ -29,9 +29,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $Begemot: bsnmp/lib/bsnmpclient.3,v 1.9 2005/05/23 11:10:12 brandt_h Exp $
+.\" $Begemot: bsnmp/lib/bsnmpclient.3,v 1.12 2005/10/04 08:46:50 brandt_h Exp $
 .\"
-.Dd May 23, 2005
+.Dd October 4, 2005
 .Dt BSNMPCLIENT 3
 .Os
 .Sh NAME
@@ -104,7 +104,8 @@ Begemot SNMP library
 .Fn snmp_dialog "struct snmp_pdu *req" "struct snmp_pdu *resp"
 .Sh DESCRIPTION
 The SNMP library contains routines to easily build SNMP client applications
-that use SNMP versions 1 or 2. Most of the routines use a
+that use SNMP versions 1 or 2.
+Most of the routines use a
 .Vt struct snmp_client :
 .Bd -literal -offset indent
 struct snmp_client {
@@ -145,9 +146,11 @@ struct snmp_client {
 The fields of this structure are described below.
 .Bl -tag -width "timeout_start"
 .It Va version
-This is the version of SNMP to use. See
+This is the version of SNMP to use.
+See
 .Xr bsnmplib 3
-for applicable values. The default version is
+for applicable values.
+The default version is
 .Li SNMP_V2c .
 .It Va trans
 If this is
@@ -163,12 +166,14 @@ It uses the
 .Va chost
 field as the path to the server's socket for local sockets.
 .It Va cport
-The SNMP agent's UDP port number. This may be a symbolic port number (from
-.Pa /etc/services
-or a numeric port number. If this field is
+The SNMP agent's UDP port number.
+This may be a symbolic port number (from
+.Pa /etc/services )
+or a numeric port number.
+If this field is
 .Li NULL
-(the default) the standard SNMP port is used. This field should not be changed
-directly but rather by calling
+(the default) the standard SNMP port is used.
+This field should not be changed directly but rather by calling
 .Fn snmp_client_set_port .
 .It Va chost
 The SNMP agent's host name, IP address or
@@ -178,46 +183,52 @@ If this is
 .Li NULL
 (the default)
 .Li localhost
-is assumed. This field should not be changed directly but rather through
-calling
+is assumed.
+This field should not be changed directly but rather through calling
 .Fn snmp_client_set_host .
 .It Va read_community
 This is the community name to be used for all requests except SET requests.
 The default is
 .Sq public .
 .It Va write_community
-The community name to be used for SET requests. The default is
+The community name to be used for SET requests.
+The default is
 .Sq private .
 .It Va timeout
-The maximum time to wait for responses to requests. If the time elapses, the
-request is resent up to
+The maximum time to wait for responses to requests.
+If the time elapses, the request is resent up to
 .Va retries
-times. The default is 3 seconds.
+times.
+The default is 3 seconds.
 .It Va retries
-Number of times a request PDU is to be resent. If set to 0, the request is
-sent only once. The default is 3 retransmissions.
+Number of times a request PDU is to be resent.
+If set to 0, the request is sent only once.
+The default is 3 retransmissions.
 .It Va dump_pdus
 If set to a non-zero value all received and sent PDUs are dumped via
 .Xr snmp_pdu_dump 3 .
 The default is not to dump PDUs.
 .It Va txbuflen
-The encoding buffer size to be allocated for transmitted PDUs. The default is
-10000 octets.
+The encoding buffer size to be allocated for transmitted PDUs.
+The default is 10000 octets.
 .It Va rxbuflen
-The decoding buffer size to be allocated for received PDUs. This is the size
-of the maximum PDU that can be received. The default is 10000 octets.
+The decoding buffer size to be allocated for received PDUs.
+This is the size of the maximum PDU that can be received.
+The default is 10000 octets.
 .It Va fd
 After calling
 .Fn snmp_open
 this is the file socket file descriptor used for sending and receiving PDUs.
 .It Va next_reqid
-The request id of the next PDU to send. Used internal by the library.
+The request id of the next PDU to send.
+Used internal by the library.
 .It Va max_reqid
-The maximum request id to use for outging PDUs. The default is
+The maximum request id to use for outgoing PDUs.
+The default is
 .Li INT32_MAX .
 .It Va min_reqid
-The minimum request id to use for outgoing PDUs. Request ids are allocated
-linerily starting at
+The minimum request id to use for outgoing PDUs.
+Request ids are allocated linearily starting at
 .Va min_reqid
 up to
 .Va max_reqid .
@@ -225,29 +236,30 @@ up to
 If an error happens, this field is set to a printable string describing the
 error.
 .It Va timeout_start
-This field must point to a function setting up a one shot timeout. After the
-timeout has elapsed, the given callback function must be called with the
-user argument. The
+This field must point to a function setting up a one shot timeout.
+After the timeout has elapsed, the given callback function must be called
+with the user argument.
+The
 .Fn timeout_start
 function must return a
 .Vt void *
 identifying the timeout.
 .It Va timeout_stop
-This field must be set to a function that stops a running timeout. The function
-will be called with the return value of the corresponding
+This field must be set to a function that stops a running timeout.
+The function will be called with the return value of the corresponding
 .Fn timeout_start
 function.
 .It Va local_path
-If in local socket mode, the name of the clients socket. Not needed by the
-application.
+If in local socket mode, the name of the clients socket.
+Not needed by the application.
 .El
 .Pp
 In the current implementation there is a global variable
 .Pp
 .D1 Vt extern struct snmp_client snmp_client ;
 .Pp
-that is used by all the library functions. The first call into the library must
-be a call to
+that is used by all the library functions.
+The first call into the library must be a call to
 .Fn snmp_client_init
 to initialize this global variable to the default values.
 After this call and before calling
@@ -271,23 +283,26 @@ If any of the arguments of the call is not
 .Li NULL
 the corresponding field in the global
 .Va snmp_client
-is set from the argument. Otherwise the values that are already in that variable
-are used.
+is set from the argument.
+Otherwise the values that are already in that variable are used.
 The function
 .Fn snmp_close
 closes the socket, stops all timeouts and frees all dynamically allocated
 resources.
 .Pp
-The next three functions are used to create request PDUs. The function
+The next three functions are used to create request PDUs.
+The function
 .Fn snmp_pdu_create
 initializes a PDU of type
 .Va op .
-It does not allocate space for the PDU itself. This is the responsibility of
-the caller.
+It does not allocate space for the PDU itself.
+This is the responsibility of the caller.
 .Fn snmp_add_binding
 adds bindings to the PDU and returns the (zero based) index of the first new
-binding. The arguments are pairs of pointer to the OIDs and syntax constants,
-terminated by a NULL. The call
+binding.
+The arguments are pairs of pointer to the OIDs and syntax constants,
+terminated by a NULL.
+The call
 .Bd -literal -offset indent
 snmp_add_binding(&pdu,
     &oid1, SNMP_SYNTAX_INTEGER,
@@ -297,15 +312,16 @@ snmp_add_binding(&pdu,
 .Pp
 adds two new bindings to the PDU and returns the index of the first one.
 It is the responsibility of the caller to set the value part of the binding
-if neccesary. The functions returns -1 if the maximum number of bindings
-is exhausted.
+if necessary.
+The functions returns -1 if the maximum number of bindings is exhausted.
 The function
 .Fn snmp_oid_append
-can be used to construct variable OIDs for requests. It takes a pointer
-to an
+can be used to construct variable OIDs for requests.
+It takes a pointer to an
 .Vt struct asn_oid
 that is to be constructed, a format string, and a number of arguments
-the type of which depends on the format string. The format string is interpreted
+the type of which depends on the format string.
+The format string is interpreted
 character by character in the following way:
 .Bl -tag -width ".It Li ( Va N Ns Li )"
 .It Li i
@@ -332,7 +348,8 @@ This format expects an argument of type
 .Vt const char *
 and appends
 .Va size
-characters from the string to the OID. The string may contain
+characters from the string to the OID.
+The string may contain
 .Li NUL
 characters.
 .It Li c
@@ -346,7 +363,8 @@ pointed to by the second argument.
 .Pp
 The function
 .Fn snmp_pdu_check
-may be used to check a response PDU. A number of checks are performed
+may be used to check a response PDU.
+A number of checks are performed
 (error code, equal number of bindings, syntaxes and values for SET PDUs).
 The function returns +1 if everything is ok, 0 if a NOSUCHNAME or similar
 error was detected, -1 if the response PDU had fatal errors
@@ -354,38 +372,43 @@ and -2 if
 .Fa resp
 is
 .Li NULL
-(a timeout occured).
+(a timeout occurred).
 .Pp
 The function
 .Fn snmp_pdu_send
-encodes and sends the given PDU. It records the PDU together with the callback
+encodes and sends the given PDU.
+It records the PDU together with the callback
 and user pointers in an internal list and arranges for retransmission if no
-response is received. When a response is received or the retransmission count
+response is received.
+When a response is received or the retransmission count
 is exceeded the callback
 .Fa func
 is called with the orignal request PDU, the response PDU and the user argument
 .Fa uarg .
 If the retransmit count is exceeded,
 .Fa func
-is called with the original request PDU, the reponse pointer set to
+is called with the original request PDU, the response pointer set to
 .Li NULL
 and the user argument
 .Fa uarg .
 The caller should not free the request PDU until the callback function is
-called. The callback function must free the request PDU and the response
-PDU (if not
+called.
+The callback function must free the request PDU and the response PDU (if not
 .Li NULL ).
 .Pp
 The function
 .Fn snmp_receive
-tries to receive a PDU. If the argument is zero, the function polls to see
+tries to receive a PDU.
+If the argument is zero, the function polls to see
 whether a packet is available, if the argument is non-zero, the function blocks
-until the next packet is received. The packet is delivered via the usual callback
+until the next packet is received.
+The packet is delivered via the usual callback
 mechanism (non-response packets are silently dropped).
 The function returns 0, if a packet was received and successfully dispatched,
--1 if an error occured or no packet was available (in polling mode).
+-1 if an error occurred or no packet was available (in polling mode).
 .Pp
-The next two functions are used to retrieve tables from SNMP agents. The use
+The next two functions are used to retrieve tables from SNMP agents.
+They use
 the following input structure, that describes the table:
 .Bd -literal -offset indent
 struct snmp_table {
@@ -394,7 +417,7 @@ struct snmp_table {
 	u_int			max_iter;
 	size_t			entry_size;
 	u_int			index_size;
-	u_int64_t		req_mask;
+	uint64_t		req_mask;
 
 	struct snmp_table_entry {
 	    asn_subid_t		subid;
@@ -410,15 +433,17 @@ The fields of this structure have the following meaning:
 This is the base OID of the table.
 .It Va last_change
 Some tables have a scalar variable of type TIMETICKS attached to them,
-that holds the time when the table was last changed. This OID should be
-the OID of this variable (without the \&.0 index). When the table is retrieved
+that holds the time when the table was last changed.
+This OID should be the OID of this variable (without the \&.0 index).
+When the table is retrieved
 with multiple GET requests, and the variable changes between two request,
 the table fetch is restarted.
 .It Va max_iter
 Maximum number of tries to fetch the table.
 .It Va entry_size
-The table fetching routines return a list of structure one for each table
-row. This variable is the size of one structure and used to
+The table fetching routines return a list of structures one for each table
+row.
+This variable is the size of one structure and used to
 .Xr malloc 3
 the structure.
 .It Va index_size
@@ -427,19 +452,22 @@ This is the number of index columns in the table.
 This is a bit mask with a 1 for each table column that is required.
 Bit 0 corresponds to the first element (index 0) in the array
 .Va entries ,
-bit 1 to the second (index 1) and so on. SNMP tables may be sparse. For sparse
-columns the bit should not be set. If the bit for a given column is set and
+bit 1 to the second (index 1) and so on.
+SNMP tables may be sparse.
+For sparse columns the bit should not be set.
+If the bit for a given column is set and
 the column value cannot be retrieved for a given row, the table fetch is
-restarted assuming that the table is currently beeing modified by the agent.
+restarted assuming that the table is currently being modified by the agent.
 The bits for the index columns are ignored.
 .It Va entries
-This is a variable sized array of column descriptors. This array is terminated
-by an element with syntax
+This is a variable sized array of column descriptors.
+This array is terminated by an element with syntax
 .Li SNMP_SYNTAX_NULL .
 The first
 .Va index_size
 elements describe all the index columns of the table, the rest are normal
-columns. If for a the column at
+columns.
+If for the column at
 .Ql entries[N]
 the expression
 .Ql req_mask & (1 << N)
@@ -447,12 +475,14 @@ yields true, the column is considered a required column.
 The fields of this the array elements have the following meaning:
 .Bl -tag -width "syntax"
 .It Va subid
-This is the OID subid of the column. This is ignored for index entries. Index
-entries are decoded according to the
+This is the OID subid of the column.
+This is ignored for index entries.
+Index entries are decoded according to the
 .Va syntax
 field.
 .It Va syntax
-This is the syntax of the column or index. A syntax of
+This is the syntax of the column or index.
+A syntax of
 .Li SNMP_SYNTAX_NULL
 terminates the array.
 .It Va offset
@@ -465,10 +495,11 @@ macro.
 .Pp
 Both table fetching functions return TAILQ (see
 .Xr queue 3 )
-of structures--one for each table row. These structures must start with a
+of structures--one for each table row.
+These structures must start with a
 .Fn TAILQ_ENTRY
 and a
-.Vt u_int64_t
+.Vt uint64_t
 and are allocated via
 .Xr malloc 3 .
 The
@@ -476,29 +507,33 @@ The
 argument of the table functions must point to a
 .Fn TAILQ_HEAD .
 The
-.Vt u_int64_t
+.Vt uint64_t
 fields, usually called
 .Va found
 is used to indicate which of the columns have been found for the given
-row. It is encoded like the
+row.
+It is encoded like the
 .Fa req_mask
 field.
 .Pp
 The function
 .Fn snmp_table_fetch
-synchronuosly fetches the given table. If everything is ok 0 is returned.
+synchronously fetches the given table.
+If everything is ok 0 is returned.
 Otherwise the function returns -1 and sets an appropriate error string.
 The function
 .Fn snmp_table_fetch_async
-fetches the tables asynchronuosly. If either the entire table is fetch, or
-an error occures the callback function
+fetches the tables asynchronously.
+If either the entire table is fetch, or
+an error occurs the callback function
 .Fa callback
 is called with the callers arguments
 .Fa list
 and
 .Fa uarg
 and a parameter that is either 0 if the table was fetched, or
--1 if there was an error. The function itself returns -1 if it could not
+-1 if there was an error.
+The function itself returns -1 if it could not
 initialize fetching of the table.
 .Pp
 The following table description is used to fetch the ATM interface table:
@@ -508,17 +543,17 @@ The following table description is used to fetch the ATM interface table:
  */
 struct atmif {
 	TAILQ_ENTRY(atmif) link;
-	u_int64_t	found;
+	uint64_t	found;
 	int32_t		index;
 	u_char		*ifname;
 	size_t		ifnamelen;
-	u_int32_t	node_id;
-	u_int32_t	pcr;
+	uint32_t	node_id;
+	uint32_t	pcr;
 	int32_t		media;
-	u_int32_t	vpi_bits;
-	u_int32_t	vci_bits;
-	u_int32_t	max_vpcs;
-	u_int32_t	max_vccs;
+	uint32_t	vpi_bits;
+	uint32_t	vci_bits;
+	uint32_t	max_vpcs;
+	uint32_t	max_vccs;
 	u_char		*esi;
 	size_t		esilen;
 	int32_t		carrier;
@@ -568,15 +603,18 @@ static const struct snmp_table atmif_table = {
 .Pp
 The function
 .Fn snmp_dialog
-is used to execute a synchonuous dialog with the agent. The request PDU
+is used to execute a synchonuous dialog with the agent.
+The request PDU
 .Fa req
-is sent and the function blocks until the response PDU is received. Note,
+is sent and the function blocks until the response PDU is received.
+Note,
 that asynchonuous receives are handled (i.e. callback functions of other send
-calls or table fetches may be called while in the function). The response
-PDU is returned in
+calls or table fetches may be called while in the function).
+The response PDU is returned in
 .Fa resp .
-If no reponse could be received after all timeouts and retries, the function
-returns -1. If a response was received 0 is returned.
+If no response could be received after all timeouts and retries, the function
+returns -1.
+If a response was received 0 is returned.
 .Pp
 The function
 .Fn snmp_parse_server
@@ -600,15 +638,16 @@ is the port in case of UDP transport.
 The function returns 0 in the case of success and return -1 and sets
 the error string in case of an error.
 .Sh DIAGNOSTICS
-If an error occures in any of the function an error indication as described
-above is returned. Additionally the function sets a printable error string
+If an error occurs in any of the function an error indication as described
+above is returned.
+Additionally the function sets a printable error string
 in the
 .Va error
 filed of
 .Va snmp_client .
 .Sh SEE ALSO
 .Xr gensnmptree 1 ,
-.Xr snmpd 1 ,
+.Xr bsnmpd 1 ,
 .Xr bsnmpagent 3 ,
 .Xr bsnmplib 3
 .Sh STANDARDS