diff options
author | harti <harti@FreeBSD.org> | 2005-10-04 14:41:06 +0000 |
---|---|---|
committer | harti <harti@FreeBSD.org> | 2005-10-04 14:41:06 +0000 |
commit | efb2dfa1774240830b3f74b7fe4ab8050cc1cda0 (patch) | |
tree | 939b9a00cfa4d79510a088859c9352b689740218 /contrib/bsnmp/lib/bsnmpclient.3 | |
parent | 2b366eef52ee173d11c8c3b0570cd771e5c0044a (diff) | |
download | FreeBSD-src-efb2dfa1774240830b3f74b7fe4ab8050cc1cda0.zip FreeBSD-src-efb2dfa1774240830b3f74b7fe4ab8050cc1cda0.tar.gz |
Virgin import of bsnmpd 1.11
Diffstat (limited to 'contrib/bsnmp/lib/bsnmpclient.3')
-rw-r--r-- | contrib/bsnmp/lib/bsnmpclient.3 | 233 |
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 |