| snmp_netgraph.3 (128236) | snmp_netgraph.3 (131504) |
|---|---|
| 1.\" 2.\" Copyright (c) 2001-2003 3.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). 4.\" All rights reserved. 5.\" 6.\" Author: Harti Brandt <harti@freebsd.org> 7.\" 8.\" Redistribution of this software and documentation and use in source and --- 13 unchanged lines hidden (view full) --- 22.\" FRAUNHOFER FOKUS OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 23.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 25.\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 26.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 27.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 28.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29.\" | 1.\" 2.\" Copyright (c) 2001-2003 3.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). 4.\" All rights reserved. 5.\" 6.\" Author: Harti Brandt <harti@freebsd.org> 7.\" 8.\" Redistribution of this software and documentation and use in source and --- 13 unchanged lines hidden (view full) --- 22.\" FRAUNHOFER FOKUS OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 23.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 25.\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 26.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 27.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 28.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29.\" |
| 30.\" $FreeBSD: head/usr.sbin/bsnmpd/modules/snmp_netgraph/snmp_netgraph.3 128236 2004-04-14 16:11:05Z harti $ | 30.\" $FreeBSD: head/usr.sbin/bsnmpd/modules/snmp_netgraph/snmp_netgraph.3 131504 2004-07-02 23:52:20Z ru $ |
| 31.\" 32.Dd November 14, 2003 33.Dt snmp_netgraph 3 34.Os 35.Sh NAME 36.Nm snmp_netgraph , 37.Nm snmp_node , 38.Nm snmp_nodename , --- 91 unchanged lines hidden (view full) --- 130.Ft ng_ID_t 131.Fn ng_node_type "ng_ID_t id, char *type" 132.Ft int 133.Fn ng_peer_hook_id "ng_ID_t id" "const char *hook" "char *peerhook" 134.Sh DESCRIPTION 135The 136.Nm snmp_netgraph 137module implements a number of tables and scalars that enable remote access to | 31.\" 32.Dd November 14, 2003 33.Dt snmp_netgraph 3 34.Os 35.Sh NAME 36.Nm snmp_netgraph , 37.Nm snmp_node , 38.Nm snmp_nodename , --- 91 unchanged lines hidden (view full) --- 130.Ft ng_ID_t 131.Fn ng_node_type "ng_ID_t id, char *type" 132.Ft int 133.Fn ng_peer_hook_id "ng_ID_t id" "const char *hook" "char *peerhook" 134.Sh DESCRIPTION 135The 136.Nm snmp_netgraph 137module implements a number of tables and scalars that enable remote access to |
| 138the netgraph subsystem. It also exports a number of global variables and | 138the netgraph subsystem. 139It also exports a number of global variables and |
| 139functions, that allow other modules to easily use the netgraph system. 140.Pp 141If upon start up of the module the variable 142.Va begemotNgControlNodeName 143is not empty the module opens a netgraph socket and names that socket node. 144If the variable is empty, the socket is created, as soon as the variable is | 140functions, that allow other modules to easily use the netgraph system. 141.Pp 142If upon start up of the module the variable 143.Va begemotNgControlNodeName 144is not empty the module opens a netgraph socket and names that socket node. 145If the variable is empty, the socket is created, as soon as the variable is |
| 145written with a non-empty name. The socket can be closed by writing an empty 146string to the variable. The socket itself and its name are available in | 146written with a non-empty name. 147The socket can be closed by writing an empty 148string to the variable. 149The socket itself and its name are available in |
| 147.Va snmp_node 148and 149.Va snmp_nodename . 150.Ss SENDING AND RECEIVING MESSAGES AND DATA 151There are three functions for sending control message: 152.Bl -tag -width ".It Fn ng_output_node" 153.It Fn ng_output 154sends a control message along the given --- 9 unchanged lines hidden (view full) --- 164.Pp 165Each of these functions takes the following arguments: 166.Bl -tag -width ".It Fa cookie" 167.It Fa cookie 168is the node specific command cookie, 169.It Fa opcode 170is the node specific code for the operation to performa, 171.It Fa arg | 150.Va snmp_node 151and 152.Va snmp_nodename . 153.Ss SENDING AND RECEIVING MESSAGES AND DATA 154There are three functions for sending control message: 155.Bl -tag -width ".It Fn ng_output_node" 156.It Fn ng_output 157sends a control message along the given --- 9 unchanged lines hidden (view full) --- 167.Pp 168Each of these functions takes the following arguments: 169.Bl -tag -width ".It Fa cookie" 170.It Fa cookie 171is the node specific command cookie, 172.It Fa opcode 173is the node specific code for the operation to performa, 174.It Fa arg |
| 172is a pointer to the message itself. This message must start with a | 175is a pointer to the message itself. 176This message must start with a |
| 173.Vt struct ng_mesg . 174.It Fa arglen 175is the overall length of the message (header plus arguments). 176.El 177The functions return the message id that can be used to match incoming responses 178or -1 if an error occurs. 179.Pp 180Another class of functions is used to send a control message and to wait for | 177.Vt struct ng_mesg . 178.It Fa arglen 179is the overall length of the message (header plus arguments). 180.El 181The functions return the message id that can be used to match incoming responses 182or -1 if an error occurs. 183.Pp 184Another class of functions is used to send a control message and to wait for |
| 181a matching response. Note, that this operation blocks the daemon, so use it 182only if you are sure that the response will happen. There is a maximum timeout | 185a matching response. 186Note, that this operation blocks the daemon, so use it 187only if you are sure that the response will happen. 188There is a maximum timeout |
| 183that is configurable in the MIB variable 184.Va begemotNgTimeout . 185Other messages arriving while the functions are waiting for the response are 186queued and delivered on the next call to the module's idle function. 187.Bl -tag -width ".It Fn ng_output_node" 188.It Fn ng_dialog 189sends a control message along the given 190.Fa path --- 5 unchanged lines hidden (view full) --- 196.It Fn ng_dialog_id 197sends a control message to the node with id 198.Fa id 199and waits for a matching response. 200.El 201.Pp 202All three functions take the same arguments as the 203.Fn ng_output* | 189that is configurable in the MIB variable 190.Va begemotNgTimeout . 191Other messages arriving while the functions are waiting for the response are 192queued and delivered on the next call to the module's idle function. 193.Bl -tag -width ".It Fn ng_output_node" 194.It Fn ng_dialog 195sends a control message along the given 196.Fa path --- 5 unchanged lines hidden (view full) --- 202.It Fn ng_dialog_id 203sends a control message to the node with id 204.Fa id 205and waits for a matching response. 206.El 207.Pp 208All three functions take the same arguments as the 209.Fn ng_output* |
| 204functions. The functions return the reponse message in a buffer allocated by | 210functions. 211The functions return the reponse message in a buffer allocated by |
| 205.Xr malloc 3 | 212.Xr malloc 3 |
| 206or NULL in case of an error. The maximum size of the response buffer can be | 213or NULL in case of an error. 214The maximum size of the response buffer can be |
| 207configured in the variable 208.Va begemotNgResBufSiz . 209.Pp 210A data message can be send with the function 211.Fn ng_send_data . 212This function takes the name of the 213.Va snmp_node Ns 's 214hook through which to send the data, a pointer to the message buffer and | 215configured in the variable 216.Va begemotNgResBufSiz . 217.Pp 218A data message can be send with the function 219.Fn ng_send_data . 220This function takes the name of the 221.Va snmp_node Ns 's 222hook through which to send the data, a pointer to the message buffer and |
| 215the size of the message. It returns -1 if an error happens. | 223the size of the message. 224It returns -1 if an error happens. |
| 216.Ss ASYNCHRONOUS CONTROL AND DATA MESSAGES 217A module can register functions to asynchronuosly receive control and data 218message. 219.Pp 220The function 221.Fn ng_register_cookie | 225.Ss ASYNCHRONOUS CONTROL AND DATA MESSAGES 226A module can register functions to asynchronuosly receive control and data 227message. 228.Pp 229The function 230.Fn ng_register_cookie |
| 222registers a control message receive function. If a control message is | 231registers a control message receive function. 232If a control message is |
| 223received, that is not consumed by the dialog functions, the list of registerred | 233received, that is not consumed by the dialog functions, the list of registerred |
| 224control message receive functions is scanned. If the cookie in the received | 234control message receive functions is scanned. 235If the cookie in the received |
| 225message is the same as the 226.Fa cookie 227argument to the 228.Fn ng_register_cookie 229call and the 230.Fn 231.Fa id 232argument to the 233.Fn ng_register_cookie 234call was either 0 or equals the node id which sent the control message, the 235handler function 236.Fa func 237is called with a pointer to the received message, the hook on which the 238message was received (or NULL if it was received not on a hook), the id 239of the sender's node and the 240.Fa uarg | 236message is the same as the 237.Fa cookie 238argument to the 239.Fn ng_register_cookie 240call and the 241.Fn 242.Fa id 243argument to the 244.Fn ng_register_cookie 245call was either 0 or equals the node id which sent the control message, the 246handler function 247.Fa func 248is called with a pointer to the received message, the hook on which the 249message was received (or NULL if it was received not on a hook), the id 250of the sender's node and the 251.Fa uarg |
| 241argument of the registration call. The handler function should not modify | 252argument of the registration call. 253The handler function should not modify |
| 242the contents of the message, because more than one function may be registered 243to the same cookie and node id. 244.Pp 245A control message registration can be undone by calling 246.Fn ng_unregister_cookie 247with the return value of the registration call. 248If an error occures while registering, 249.Fn ng_register_cookie 250returns NULL. 251.Pp 252A module can call 253.Fn ng_register_hook 254to register a callback for data messages on one of the 255.Va snmp_node Ns 's | 254the contents of the message, because more than one function may be registered 255to the same cookie and node id. 256.Pp 257A control message registration can be undone by calling 258.Fn ng_unregister_cookie 259with the return value of the registration call. 260If an error occures while registering, 261.Fn ng_register_cookie 262returns NULL. 263.Pp 264A module can call 265.Fn ng_register_hook 266to register a callback for data messages on one of the 267.Va snmp_node Ns 's |
| 256hooks. If a data message is received on that hook, the callback function | 268hooks. 269If a data message is received on that hook, the callback function |
| 257.Fa func 258is called with the hook name, a pointer to the data message, the size of 259the message and the argument 260.Fa uarg | 270.Fa func 271is called with the hook name, a pointer to the data message, the size of 272the message and the argument 273.Fa uarg |
| 261to the registration function. The message should be treated as read-only. | 274to the registration function. 275The message should be treated as read-only. |
| 262A data message registration can be undone by calling 263.Fn ng_unregister_hook 264with the return value of the registration call. 265If an error occures while registering, 266.Fn ng_register_hook 267returns NULL. 268.Pp 269The function --- 16 unchanged lines hidden (view full) --- 286The function 287.Fn ng_node_node 288retrieves the name of the node with id 289.Fa id 290and writes it to the buffer pointed to by 291.Fa name . 292This buffer should be at least 293.Li NG_NODESIZ | 276A data message registration can be undone by calling 277.Fn ng_unregister_hook 278with the return value of the registration call. 279If an error occures while registering, 280.Fn ng_register_hook 281returns NULL. 282.Pp 283The function --- 16 unchanged lines hidden (view full) --- 300The function 301.Fn ng_node_node 302retrieves the name of the node with id 303.Fa id 304and writes it to the buffer pointed to by 305.Fa name . 306This buffer should be at least 307.Li NG_NODESIZ |
| 294bytes long. The function returns the node id or 0 if the | 308bytes long. 309The function returns the node id or 0 if the |
| 295node is not found 296.Pp 297The function 298.Fn ng_node_type 299retrieves the name of the node with id 300.Fa id 301and writes it to the buffer pointed to by 302.Fa type . 303This buffer should be at least 304.Li NG_TYPESIZ | 310node is not found 311.Pp 312The function 313.Fn ng_node_type 314retrieves the name of the node with id 315.Fa id 316and writes it to the buffer pointed to by 317.Fa type . 318This buffer should be at least 319.Li NG_TYPESIZ |
| 305bytes long. The function returns the node id or 0 if the | 320bytes long. 321The function returns the node id or 0 if the |
| 306node is not found. 307.Pp 308The function 309.Fn ng_peer_hook_id 310writes the name of the peer hook of the hook 311.Fa hook 312on the node with 313.Fa id 314to the buffer pointed to by 315.Fa peer_hook . 316The buffer should be at least 317.Li NG_HOOKSIZ | 322node is not found. 323.Pp 324The function 325.Fn ng_peer_hook_id 326writes the name of the peer hook of the hook 327.Fa hook 328on the node with 329.Fa id 330to the buffer pointed to by 331.Fa peer_hook . 332The buffer should be at least 333.Li NG_HOOKSIZ |
| 318bytes long. The function returns 0 if the node and the hook is found, -1 319otherwise. The function skips intermediate tee nodes (see | 334bytes long. 335The function returns 0 if the node and the hook is found, -1 336otherwise. 337The function skips intermediate tee nodes (see |
| 320.Xr ng_tee 4 ). 321.Pp 322The function 323.Fn ng_next_node_id 324returns the node id of the peer node that is on the other side of hook 325.Fa hook 326of node 327.Fa id . --- 15 unchanged lines hidden (view full) --- 343who's hook 344.Fa peerhook 345will be connected to 346.Fa hook 347of node 348.Fa id . 349If 350.Fa name | 338.Xr ng_tee 4 ). 339.Pp 340The function 341.Fn ng_next_node_id 342returns the node id of the peer node that is on the other side of hook 343.Fa hook 344of node 345.Fa id . --- 15 unchanged lines hidden (view full) --- 361who's hook 362.Fa peerhook 363will be connected to 364.Fa hook 365of node 366.Fa id . 367If 368.Fa name |
| 351is not NULL the new node is named with this name. The function returns | 369is not NULL the new node is named with this name. 370The function returns |
| 352The node id of the new node or 0 if an error happens. 353.Pp 354The functions 355.Fn ng_connect_node 356and 357.Fn ng_connect_id 358make a new hook connecting 359.Fa ourhook --- 58 unchanged lines hidden --- | 371The node id of the new node or 0 if an error happens. 372.Pp 373The functions 374.Fn ng_connect_node 375and 376.Fn ng_connect_id 377make a new hook connecting 378.Fa ourhook --- 58 unchanged lines hidden --- |