| bsnmpclient.3 (146525) | bsnmpclient.3 (150920) |
|---|---|
| 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.\" --- 15 unchanged lines hidden (view full) --- 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.\" | 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.\" --- 15 unchanged lines hidden (view full) --- 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/bsnmpclient.3,v 1.9 2005/05/23 11:10:12 brandt_h Exp $ | 32.\" $Begemot: bsnmp/lib/bsnmpclient.3,v 1.12 2005/10/04 08:46:50 brandt_h Exp $ |
| 33.\" | 33.\" |
| 34.Dd May 23, 2005 | 34.Dd October 4, 2005 |
| 35.Dt BSNMPCLIENT 3 36.Os 37.Sh NAME 38.Nm snmp_client , 39.Nm snmp_send_cb_f , 40.Nm snmp_timeout_cb_f , 41.Nm snmp_timeout_start_f , 42.Nm snmp_timeout_stop_f , --- 56 unchanged lines hidden (view full) --- 99.Ft int 100.Fn snmp_table_fetch "const struct snmp_table *descr" "void *list" 101.Ft int 102.Fn snmp_table_fetch_async "const struct snmp_table *descr" "void *list" "snmp_table_cb_f callback" "void *uarg" 103.Ft int 104.Fn snmp_dialog "struct snmp_pdu *req" "struct snmp_pdu *resp" 105.Sh DESCRIPTION 106The SNMP library contains routines to easily build SNMP client applications | 35.Dt BSNMPCLIENT 3 36.Os 37.Sh NAME 38.Nm snmp_client , 39.Nm snmp_send_cb_f , 40.Nm snmp_timeout_cb_f , 41.Nm snmp_timeout_start_f , 42.Nm snmp_timeout_stop_f , --- 56 unchanged lines hidden (view full) --- 99.Ft int 100.Fn snmp_table_fetch "const struct snmp_table *descr" "void *list" 101.Ft int 102.Fn snmp_table_fetch_async "const struct snmp_table *descr" "void *list" "snmp_table_cb_f callback" "void *uarg" 103.Ft int 104.Fn snmp_dialog "struct snmp_pdu *req" "struct snmp_pdu *resp" 105.Sh DESCRIPTION 106The SNMP library contains routines to easily build SNMP client applications |
| 107that use SNMP versions 1 or 2. Most of the routines use a | 107that use SNMP versions 1 or 2. 108Most of the routines use a |
| 108.Vt struct snmp_client : 109.Bd -literal -offset indent 110struct snmp_client { 111 enum snmp_version version; 112 int trans; /* transport type to use */ 113 114 /* these two are read-only for the application */ 115 char *cport; /* port number as string */ --- 24 unchanged lines hidden (view full) --- 140 /* private */ 141 char local_path[sizeof(SNMP_LOCAL_PATH)]; 142}; 143.Ed 144.Pp 145The fields of this structure are described below. 146.Bl -tag -width "timeout_start" 147.It Va version | 109.Vt struct snmp_client : 110.Bd -literal -offset indent 111struct snmp_client { 112 enum snmp_version version; 113 int trans; /* transport type to use */ 114 115 /* these two are read-only for the application */ 116 char *cport; /* port number as string */ --- 24 unchanged lines hidden (view full) --- 141 /* private */ 142 char local_path[sizeof(SNMP_LOCAL_PATH)]; 143}; 144.Ed 145.Pp 146The fields of this structure are described below. 147.Bl -tag -width "timeout_start" 148.It Va version |
| 148This is the version of SNMP to use. See | 149This is the version of SNMP to use. 150See |
| 149.Xr bsnmplib 3 | 151.Xr bsnmplib 3 |
| 150for applicable values. The default version is | 152for applicable values. 153The default version is |
| 151.Li SNMP_V2c . 152.It Va trans 153If this is 154.Dv SNMP_TRANS_LOC_DGRAM 155a local datagram socket is used. 156If it is 157.Dv SNMP_TRANS_LOC_STREAM 158a local stream socket is used. 159For 160.Dv SNMP_TRANS_UDP 161a UDP socket is created. 162It uses the 163.Va chost 164field as the path to the server's socket for local sockets. 165.It Va cport | 154.Li SNMP_V2c . 155.It Va trans 156If this is 157.Dv SNMP_TRANS_LOC_DGRAM 158a local datagram socket is used. 159If it is 160.Dv SNMP_TRANS_LOC_STREAM 161a local stream socket is used. 162For 163.Dv SNMP_TRANS_UDP 164a UDP socket is created. 165It uses the 166.Va chost 167field as the path to the server's socket for local sockets. 168.It Va cport |
| 166The SNMP agent's UDP port number. This may be a symbolic port number (from 167.Pa /etc/services 168or a numeric port number. If this field is | 169The SNMP agent's UDP port number. 170This may be a symbolic port number (from 171.Pa /etc/services ) 172or a numeric port number. 173If this field is |
| 169.Li NULL | 174.Li NULL |
| 170(the default) the standard SNMP port is used. This field should not be changed 171directly but rather by calling | 175(the default) the standard SNMP port is used. 176This field should not be changed directly but rather by calling |
| 172.Fn snmp_client_set_port . 173.It Va chost 174The SNMP agent's host name, IP address or 175.Ux 176domain socket path name. 177If this is 178.Li NULL 179(the default) 180.Li localhost | 177.Fn snmp_client_set_port . 178.It Va chost 179The SNMP agent's host name, IP address or 180.Ux 181domain socket path name. 182If this is 183.Li NULL 184(the default) 185.Li localhost |
| 181is assumed. This field should not be changed directly but rather through 182calling | 186is assumed. 187This field should not be changed directly but rather through calling |
| 183.Fn snmp_client_set_host . 184.It Va read_community 185This is the community name to be used for all requests except SET requests. 186The default is 187.Sq public . 188.It Va write_community | 188.Fn snmp_client_set_host . 189.It Va read_community 190This is the community name to be used for all requests except SET requests. 191The default is 192.Sq public . 193.It Va write_community |
| 189The community name to be used for SET requests. The default is | 194The community name to be used for SET requests. 195The default is |
| 190.Sq private . 191.It Va timeout | 196.Sq private . 197.It Va timeout |
| 192The maximum time to wait for responses to requests. If the time elapses, the 193request is resent up to | 198The maximum time to wait for responses to requests. 199If the time elapses, the request is resent up to |
| 194.Va retries | 200.Va retries |
| 195times. The default is 3 seconds. | 201times. 202The default is 3 seconds. |
| 196.It Va retries | 203.It Va retries |
| 197Number of times a request PDU is to be resent. If set to 0, the request is 198sent only once. The default is 3 retransmissions. | 204Number of times a request PDU is to be resent. 205If set to 0, the request is sent only once. 206The default is 3 retransmissions. |
| 199.It Va dump_pdus 200If set to a non-zero value all received and sent PDUs are dumped via 201.Xr snmp_pdu_dump 3 . 202The default is not to dump PDUs. 203.It Va txbuflen | 207.It Va dump_pdus 208If set to a non-zero value all received and sent PDUs are dumped via 209.Xr snmp_pdu_dump 3 . 210The default is not to dump PDUs. 211.It Va txbuflen |
| 204The encoding buffer size to be allocated for transmitted PDUs. The default is 20510000 octets. | 212The encoding buffer size to be allocated for transmitted PDUs. 213The default is 10000 octets. |
| 206.It Va rxbuflen | 214.It Va rxbuflen |
| 207The decoding buffer size to be allocated for received PDUs. This is the size 208of the maximum PDU that can be received. The default is 10000 octets. | 215The decoding buffer size to be allocated for received PDUs. 216This is the size of the maximum PDU that can be received. 217The default is 10000 octets. |
| 209.It Va fd 210After calling 211.Fn snmp_open 212this is the file socket file descriptor used for sending and receiving PDUs. 213.It Va next_reqid | 218.It Va fd 219After calling 220.Fn snmp_open 221this is the file socket file descriptor used for sending and receiving PDUs. 222.It Va next_reqid |
| 214The request id of the next PDU to send. Used internal by the library. | 223The request id of the next PDU to send. 224Used internal by the library. |
| 215.It Va max_reqid | 225.It Va max_reqid |
| 216The maximum request id to use for outging PDUs. The default is | 226The maximum request id to use for outgoing PDUs. 227The default is |
| 217.Li INT32_MAX . 218.It Va min_reqid | 228.Li INT32_MAX . 229.It Va min_reqid |
| 219The minimum request id to use for outgoing PDUs. Request ids are allocated 220linerily starting at | 230The minimum request id to use for outgoing PDUs. 231Request ids are allocated linearily starting at |
| 221.Va min_reqid 222up to 223.Va max_reqid . 224.It Va error 225If an error happens, this field is set to a printable string describing the 226error. 227.It Va timeout_start | 232.Va min_reqid 233up to 234.Va max_reqid . 235.It Va error 236If an error happens, this field is set to a printable string describing the 237error. 238.It Va timeout_start |
| 228This field must point to a function setting up a one shot timeout. After the 229timeout has elapsed, the given callback function must be called with the 230user argument. The | 239This field must point to a function setting up a one shot timeout. 240After the timeout has elapsed, the given callback function must be called 241with the user argument. 242The |
| 231.Fn timeout_start 232function must return a 233.Vt void * 234identifying the timeout. 235.It Va timeout_stop | 243.Fn timeout_start 244function must return a 245.Vt void * 246identifying the timeout. 247.It Va timeout_stop |
| 236This field must be set to a function that stops a running timeout. The function 237will be called with the return value of the corresponding | 248This field must be set to a function that stops a running timeout. 249The function will be called with the return value of the corresponding |
| 238.Fn timeout_start 239function. 240.It Va local_path | 250.Fn timeout_start 251function. 252.It Va local_path |
| 241If in local socket mode, the name of the clients socket. Not needed by the 242application. | 253If in local socket mode, the name of the clients socket. 254Not needed by the application. |
| 243.El 244.Pp 245In the current implementation there is a global variable 246.Pp 247.D1 Vt extern struct snmp_client snmp_client ; 248.Pp | 255.El 256.Pp 257In the current implementation there is a global variable 258.Pp 259.D1 Vt extern struct snmp_client snmp_client ; 260.Pp |
| 249that is used by all the library functions. The first call into the library must 250be a call to | 261that is used by all the library functions. 262The first call into the library must be a call to |
| 251.Fn snmp_client_init 252to initialize this global variable to the default values. 253After this call and before calling 254.Fn snmp_open 255the fields of the variable may be modified by the user. 256The modification of the 257.Va chost 258and --- 7 unchanged lines hidden (view full) --- 266.Fn snmp_open 267creates a UDP or 268.Ux 269domain socket and connects it to the agent's IP address and port. 270If any of the arguments of the call is not 271.Li NULL 272the corresponding field in the global 273.Va snmp_client | 263.Fn snmp_client_init 264to initialize this global variable to the default values. 265After this call and before calling 266.Fn snmp_open 267the fields of the variable may be modified by the user. 268The modification of the 269.Va chost 270and --- 7 unchanged lines hidden (view full) --- 278.Fn snmp_open 279creates a UDP or 280.Ux 281domain socket and connects it to the agent's IP address and port. 282If any of the arguments of the call is not 283.Li NULL 284the corresponding field in the global 285.Va snmp_client |
| 274is set from the argument. Otherwise the values that are already in that variable 275are used. | 286is set from the argument. 287Otherwise the values that are already in that variable are used. |
| 276The function 277.Fn snmp_close 278closes the socket, stops all timeouts and frees all dynamically allocated 279resources. 280.Pp | 288The function 289.Fn snmp_close 290closes the socket, stops all timeouts and frees all dynamically allocated 291resources. 292.Pp |
| 281The next three functions are used to create request PDUs. The function | 293The next three functions are used to create request PDUs. 294The function |
| 282.Fn snmp_pdu_create 283initializes a PDU of type 284.Va op . | 295.Fn snmp_pdu_create 296initializes a PDU of type 297.Va op . |
| 285It does not allocate space for the PDU itself. This is the responsibility of 286the caller. | 298It does not allocate space for the PDU itself. 299This is the responsibility of the caller. |
| 287.Fn snmp_add_binding 288adds bindings to the PDU and returns the (zero based) index of the first new | 300.Fn snmp_add_binding 301adds bindings to the PDU and returns the (zero based) index of the first new |
| 289binding. The arguments are pairs of pointer to the OIDs and syntax constants, 290terminated by a NULL. The call | 302binding. 303The arguments are pairs of pointer to the OIDs and syntax constants, 304terminated by a NULL. 305The call |
| 291.Bd -literal -offset indent 292snmp_add_binding(&pdu, 293 &oid1, SNMP_SYNTAX_INTEGER, 294 &oid2, SNMP_SYNTAX_OCTETSTRING, 295 NULL); 296.Ed 297.Pp 298adds two new bindings to the PDU and returns the index of the first one. 299It is the responsibility of the caller to set the value part of the binding | 306.Bd -literal -offset indent 307snmp_add_binding(&pdu, 308 &oid1, SNMP_SYNTAX_INTEGER, 309 &oid2, SNMP_SYNTAX_OCTETSTRING, 310 NULL); 311.Ed 312.Pp 313adds two new bindings to the PDU and returns the index of the first one. 314It is the responsibility of the caller to set the value part of the binding |
| 300if neccesary. The functions returns -1 if the maximum number of bindings 301is exhausted. | 315if necessary. 316The functions returns -1 if the maximum number of bindings is exhausted. |
| 302The function 303.Fn snmp_oid_append | 317The function 318.Fn snmp_oid_append |
| 304can be used to construct variable OIDs for requests. It takes a pointer 305to an | 319can be used to construct variable OIDs for requests. 320It takes a pointer to an |
| 306.Vt struct asn_oid 307that is to be constructed, a format string, and a number of arguments | 321.Vt struct asn_oid 322that is to be constructed, a format string, and a number of arguments |
| 308the type of which depends on the format string. The format string is interpreted | 323the type of which depends on the format string. 324The format string is interpreted |
| 309character by character in the following way: 310.Bl -tag -width ".It Li ( Va N Ns Li )" 311.It Li i 312This format expects an argument of type 313.Vt asn_subid_t 314and appends this as a single integer to the OID. 315.It Li a 316This format expects an argument of type --- 10 unchanged lines hidden (view full) --- 327.Va N 328must be a decimal number and is stored into an internal variable 329.Va size . 330.It Li b 331This format expects an argument of type 332.Vt const char * 333and appends 334.Va size | 325character by character in the following way: 326.Bl -tag -width ".It Li ( Va N Ns Li )" 327.It Li i 328This format expects an argument of type 329.Vt asn_subid_t 330and appends this as a single integer to the OID. 331.It Li a 332This format expects an argument of type --- 10 unchanged lines hidden (view full) --- 343.Va N 344must be a decimal number and is stored into an internal variable 345.Va size . 346.It Li b 347This format expects an argument of type 348.Vt const char * 349and appends 350.Va size |
| 335characters from the string to the OID. The string may contain | 351characters from the string to the OID. 352The string may contain |
| 336.Li NUL 337characters. 338.It Li c 339This format expects two arguments: one of type 340.Vt size_t 341and one of type 342.Vt const u_char * . 343The first argument gives the number of bytes to append to the OID from the string 344pointed to by the second argument. 345.El 346.Pp 347The function 348.Fn snmp_pdu_check | 353.Li NUL 354characters. 355.It Li c 356This format expects two arguments: one of type 357.Vt size_t 358and one of type 359.Vt const u_char * . 360The first argument gives the number of bytes to append to the OID from the string 361pointed to by the second argument. 362.El 363.Pp 364The function 365.Fn snmp_pdu_check |
| 349may be used to check a response PDU. A number of checks are performed | 366may be used to check a response PDU. 367A number of checks are performed |
| 350(error code, equal number of bindings, syntaxes and values for SET PDUs). 351The function returns +1 if everything is ok, 0 if a NOSUCHNAME or similar 352error was detected, -1 if the response PDU had fatal errors 353and -2 if 354.Fa resp 355is 356.Li NULL | 368(error code, equal number of bindings, syntaxes and values for SET PDUs). 369The function returns +1 if everything is ok, 0 if a NOSUCHNAME or similar 370error was detected, -1 if the response PDU had fatal errors 371and -2 if 372.Fa resp 373is 374.Li NULL |
| 357(a timeout occured). | 375(a timeout occurred). |
| 358.Pp 359The function 360.Fn snmp_pdu_send | 376.Pp 377The function 378.Fn snmp_pdu_send |
| 361encodes and sends the given PDU. It records the PDU together with the callback | 379encodes and sends the given PDU. 380It records the PDU together with the callback |
| 362and user pointers in an internal list and arranges for retransmission if no | 381and user pointers in an internal list and arranges for retransmission if no |
| 363response is received. When a response is received or the retransmission count | 382response is received. 383When a response is received or the retransmission count |
| 364is exceeded the callback 365.Fa func 366is called with the orignal request PDU, the response PDU and the user argument 367.Fa uarg . 368If the retransmit count is exceeded, 369.Fa func | 384is exceeded the callback 385.Fa func 386is called with the orignal request PDU, the response PDU and the user argument 387.Fa uarg . 388If the retransmit count is exceeded, 389.Fa func |
| 370is called with the original request PDU, the reponse pointer set to | 390is called with the original request PDU, the response pointer set to |
| 371.Li NULL 372and the user argument 373.Fa uarg . 374The caller should not free the request PDU until the callback function is | 391.Li NULL 392and the user argument 393.Fa uarg . 394The caller should not free the request PDU until the callback function is |
| 375called. The callback function must free the request PDU and the response 376PDU (if not | 395called. 396The callback function must free the request PDU and the response PDU (if not |
| 377.Li NULL ). 378.Pp 379The function 380.Fn snmp_receive | 397.Li NULL ). 398.Pp 399The function 400.Fn snmp_receive |
| 381tries to receive a PDU. If the argument is zero, the function polls to see | 401tries to receive a PDU. 402If the argument is zero, the function polls to see |
| 382whether a packet is available, if the argument is non-zero, the function blocks | 403whether a packet is available, if the argument is non-zero, the function blocks |
| 383until the next packet is received. The packet is delivered via the usual callback | 404until the next packet is received. 405The packet is delivered via the usual callback |
| 384mechanism (non-response packets are silently dropped). 385The function returns 0, if a packet was received and successfully dispatched, | 406mechanism (non-response packets are silently dropped). 407The function returns 0, if a packet was received and successfully dispatched, |
| 386-1 if an error occured or no packet was available (in polling mode). | 408-1 if an error occurred or no packet was available (in polling mode). |
| 387.Pp | 409.Pp |
| 388The next two functions are used to retrieve tables from SNMP agents. The use | 410The next two functions are used to retrieve tables from SNMP agents. 411They use |
| 389the following input structure, that describes the table: 390.Bd -literal -offset indent 391struct snmp_table { 392 struct asn_oid table; 393 struct asn_oid last_change; 394 u_int max_iter; 395 size_t entry_size; 396 u_int index_size; | 412the following input structure, that describes the table: 413.Bd -literal -offset indent 414struct snmp_table { 415 struct asn_oid table; 416 struct asn_oid last_change; 417 u_int max_iter; 418 size_t entry_size; 419 u_int index_size; |
| 397 u_int64_t req_mask; | 420 uint64_t req_mask; |
| 398 399 struct snmp_table_entry { 400 asn_subid_t subid; 401 enum snmp_syntax syntax; 402 off_t offset; 403 } entries[]; 404}; 405.Ed 406.Pp 407The fields of this structure have the following meaning: 408.Bl -tag -width "last_change" 409.It Va table 410This is the base OID of the table. 411.It Va last_change 412Some tables have a scalar variable of type TIMETICKS attached to them, | 421 422 struct snmp_table_entry { 423 asn_subid_t subid; 424 enum snmp_syntax syntax; 425 off_t offset; 426 } entries[]; 427}; 428.Ed 429.Pp 430The fields of this structure have the following meaning: 431.Bl -tag -width "last_change" 432.It Va table 433This is the base OID of the table. 434.It Va last_change 435Some tables have a scalar variable of type TIMETICKS attached to them, |
| 413that holds the time when the table was last changed. This OID should be 414the OID of this variable (without the \&.0 index). When the table is retrieved | 436that holds the time when the table was last changed. 437This OID should be the OID of this variable (without the \&.0 index). 438When the table is retrieved |
| 415with multiple GET requests, and the variable changes between two request, 416the table fetch is restarted. 417.It Va max_iter 418Maximum number of tries to fetch the table. 419.It Va entry_size | 439with multiple GET requests, and the variable changes between two request, 440the table fetch is restarted. 441.It Va max_iter 442Maximum number of tries to fetch the table. 443.It Va entry_size |
| 420The table fetching routines return a list of structure one for each table 421row. This variable is the size of one structure and used to | 444The table fetching routines return a list of structures one for each table 445row. 446This variable is the size of one structure and used to |
| 422.Xr malloc 3 423the structure. 424.It Va index_size 425This is the number of index columns in the table. 426.It Va req_mask 427This is a bit mask with a 1 for each table column that is required. 428Bit 0 corresponds to the first element (index 0) in the array 429.Va entries , | 447.Xr malloc 3 448the structure. 449.It Va index_size 450This is the number of index columns in the table. 451.It Va req_mask 452This is a bit mask with a 1 for each table column that is required. 453Bit 0 corresponds to the first element (index 0) in the array 454.Va entries , |
| 430bit 1 to the second (index 1) and so on. SNMP tables may be sparse. For sparse 431columns the bit should not be set. If the bit for a given column is set and | 455bit 1 to the second (index 1) and so on. 456SNMP tables may be sparse. 457For sparse columns the bit should not be set. 458If the bit for a given column is set and |
| 432the column value cannot be retrieved for a given row, the table fetch is | 459the column value cannot be retrieved for a given row, the table fetch is |
| 433restarted assuming that the table is currently beeing modified by the agent. | 460restarted assuming that the table is currently being modified by the agent. |
| 434The bits for the index columns are ignored. 435.It Va entries | 461The bits for the index columns are ignored. 462.It Va entries |
| 436This is a variable sized array of column descriptors. This array is terminated 437by an element with syntax | 463This is a variable sized array of column descriptors. 464This array is terminated by an element with syntax |
| 438.Li SNMP_SYNTAX_NULL . 439The first 440.Va index_size 441elements describe all the index columns of the table, the rest are normal | 465.Li SNMP_SYNTAX_NULL . 466The first 467.Va index_size 468elements describe all the index columns of the table, the rest are normal |
| 442columns. If for a the column at | 469columns. 470If for the column at |
| 443.Ql entries[N] 444the expression 445.Ql req_mask & (1 << N) 446yields true, the column is considered a required column. 447The fields of this the array elements have the following meaning: 448.Bl -tag -width "syntax" 449.It Va subid | 471.Ql entries[N] 472the expression 473.Ql req_mask & (1 << N) 474yields true, the column is considered a required column. 475The fields of this the array elements have the following meaning: 476.Bl -tag -width "syntax" 477.It Va subid |
| 450This is the OID subid of the column. This is ignored for index entries. Index 451entries are decoded according to the | 478This is the OID subid of the column. 479This is ignored for index entries. 480Index entries are decoded according to the |
| 452.Va syntax 453field. 454.It Va syntax | 481.Va syntax 482field. 483.It Va syntax |
| 455This is the syntax of the column or index. A syntax of | 484This is the syntax of the column or index. 485A syntax of |
| 456.Li SNMP_SYNTAX_NULL 457terminates the array. 458.It Va offset 459This is the starting offset of the value of the column in the return structures. 460This field can be set with the ISO-C 461.Fn offsetof 462macro. 463.El 464.El 465.Pp 466Both table fetching functions return TAILQ (see 467.Xr queue 3 ) | 486.Li SNMP_SYNTAX_NULL 487terminates the array. 488.It Va offset 489This is the starting offset of the value of the column in the return structures. 490This field can be set with the ISO-C 491.Fn offsetof 492macro. 493.El 494.El 495.Pp 496Both table fetching functions return TAILQ (see 497.Xr queue 3 ) |
| 468of structures--one for each table row. These structures must start with a | 498of structures--one for each table row. 499These structures must start with a |
| 469.Fn TAILQ_ENTRY 470and a | 500.Fn TAILQ_ENTRY 501and a |
| 471.Vt u_int64_t | 502.Vt uint64_t |
| 472and are allocated via 473.Xr malloc 3 . 474The 475.Fa list 476argument of the table functions must point to a 477.Fn TAILQ_HEAD . 478The | 503and are allocated via 504.Xr malloc 3 . 505The 506.Fa list 507argument of the table functions must point to a 508.Fn TAILQ_HEAD . 509The |
| 479.Vt u_int64_t | 510.Vt uint64_t |
| 480fields, usually called 481.Va found 482is used to indicate which of the columns have been found for the given | 511fields, usually called 512.Va found 513is used to indicate which of the columns have been found for the given |
| 483row. It is encoded like the | 514row. 515It is encoded like the |
| 484.Fa req_mask 485field. 486.Pp 487The function 488.Fn snmp_table_fetch | 516.Fa req_mask 517field. 518.Pp 519The function 520.Fn snmp_table_fetch |
| 489synchronuosly fetches the given table. If everything is ok 0 is returned. | 521synchronously fetches the given table. 522If everything is ok 0 is returned. |
| 490Otherwise the function returns -1 and sets an appropriate error string. 491The function 492.Fn snmp_table_fetch_async | 523Otherwise the function returns -1 and sets an appropriate error string. 524The function 525.Fn snmp_table_fetch_async |
| 493fetches the tables asynchronuosly. If either the entire table is fetch, or 494an error occures the callback function | 526fetches the tables asynchronously. 527If either the entire table is fetch, or 528an error occurs the callback function |
| 495.Fa callback 496is called with the callers arguments 497.Fa list 498and 499.Fa uarg 500and a parameter that is either 0 if the table was fetched, or | 529.Fa callback 530is called with the callers arguments 531.Fa list 532and 533.Fa uarg 534and a parameter that is either 0 if the table was fetched, or |
| 501-1 if there was an error. The function itself returns -1 if it could not | 535-1 if there was an error. 536The function itself returns -1 if it could not |
| 502initialize fetching of the table. 503.Pp 504The following table description is used to fetch the ATM interface table: 505.Bd -literal -offset indent 506/* 507 * ATM interface table 508 */ 509struct atmif { 510 TAILQ_ENTRY(atmif) link; | 537initialize fetching of the table. 538.Pp 539The following table description is used to fetch the ATM interface table: 540.Bd -literal -offset indent 541/* 542 * ATM interface table 543 */ 544struct atmif { 545 TAILQ_ENTRY(atmif) link; |
| 511 u_int64_t found; | 546 uint64_t found; |
| 512 int32_t index; 513 u_char *ifname; 514 size_t ifnamelen; | 547 int32_t index; 548 u_char *ifname; 549 size_t ifnamelen; |
| 515 u_int32_t node_id; 516 u_int32_t pcr; | 550 uint32_t node_id; 551 uint32_t pcr; |
| 517 int32_t media; | 552 int32_t media; |
| 518 u_int32_t vpi_bits; 519 u_int32_t vci_bits; 520 u_int32_t max_vpcs; 521 u_int32_t max_vccs; | 553 uint32_t vpi_bits; 554 uint32_t vci_bits; 555 uint32_t max_vpcs; 556 uint32_t max_vccs; |
| 522 u_char *esi; 523 size_t esilen; 524 int32_t carrier; 525}; 526TAILQ_HEAD(atmif_list, atmif); 527 528/* list of all ATM interfaces */ 529struct atmif_list atmif_list; --- 33 unchanged lines hidden (view full) --- 563\&... 564 if (snmp_table_fetch(&atmif_table, &atmif_list) != 0) 565 errx(1, "AtmIf table: %s", snmp_client.error); 566\&... 567.Ed 568.Pp 569The function 570.Fn snmp_dialog | 557 u_char *esi; 558 size_t esilen; 559 int32_t carrier; 560}; 561TAILQ_HEAD(atmif_list, atmif); 562 563/* list of all ATM interfaces */ 564struct atmif_list atmif_list; --- 33 unchanged lines hidden (view full) --- 598\&... 599 if (snmp_table_fetch(&atmif_table, &atmif_list) != 0) 600 errx(1, "AtmIf table: %s", snmp_client.error); 601\&... 602.Ed 603.Pp 604The function 605.Fn snmp_dialog |
| 571is used to execute a synchonuous dialog with the agent. The request PDU | 606is used to execute a synchonuous dialog with the agent. 607The request PDU |
| 572.Fa req | 608.Fa req |
| 573is sent and the function blocks until the response PDU is received. Note, | 609is sent and the function blocks until the response PDU is received. 610Note, |
| 574that asynchonuous receives are handled (i.e. callback functions of other send | 611that asynchonuous receives are handled (i.e. callback functions of other send |
| 575calls or table fetches may be called while in the function). The response 576PDU is returned in | 612calls or table fetches may be called while in the function). 613The response PDU is returned in |
| 577.Fa resp . | 614.Fa resp . |
| 578If no reponse could be received after all timeouts and retries, the function 579returns -1. If a response was received 0 is returned. | 615If no response could be received after all timeouts and retries, the function 616returns -1. 617If a response was received 0 is returned. |
| 580.Pp 581The function 582.Fn snmp_parse_server 583is used to parse an SNMP server specification string and fill in the 584fields of a 585.Vt struct snmp_client . 586The syntax of a server specification is 587.Pp --- 7 unchanged lines hidden (view full) --- 595.Va server 596is the server's host name in case of UDP and the path name in case 597of a local socket, and 598.Va port 599is the port in case of UDP transport. 600The function returns 0 in the case of success and return -1 and sets 601the error string in case of an error. 602.Sh DIAGNOSTICS | 618.Pp 619The function 620.Fn snmp_parse_server 621is used to parse an SNMP server specification string and fill in the 622fields of a 623.Vt struct snmp_client . 624The syntax of a server specification is 625.Pp --- 7 unchanged lines hidden (view full) --- 633.Va server 634is the server's host name in case of UDP and the path name in case 635of a local socket, and 636.Va port 637is the port in case of UDP transport. 638The function returns 0 in the case of success and return -1 and sets 639the error string in case of an error. 640.Sh DIAGNOSTICS |
| 603If an error occures in any of the function an error indication as described 604above is returned. Additionally the function sets a printable error string | 641If an error occurs in any of the function an error indication as described 642above is returned. 643Additionally the function sets a printable error string |
| 605in the 606.Va error 607filed of 608.Va snmp_client . 609.Sh SEE ALSO 610.Xr gensnmptree 1 , | 644in the 645.Va error 646filed of 647.Va snmp_client . 648.Sh SEE ALSO 649.Xr gensnmptree 1 , |
| 611.Xr snmpd 1 , | 650.Xr bsnmpd 1 , |
| 612.Xr bsnmpagent 3 , 613.Xr bsnmplib 3 614.Sh STANDARDS 615This implementation conforms to the applicable IETF RFCs and ITU-T 616recommendations. 617.Sh AUTHORS 618.An Hartmut Brandt Aq harti@freebsd.org 619.An Kendy Kutzner Aq kutzner@fokus.gmd.de | 651.Xr bsnmpagent 3 , 652.Xr bsnmplib 3 653.Sh STANDARDS 654This implementation conforms to the applicable IETF RFCs and ITU-T 655recommendations. 656.Sh AUTHORS 657.An Hartmut Brandt Aq harti@freebsd.org 658.An Kendy Kutzner Aq kutzner@fokus.gmd.de |