1 .\" Copyright (c) 1996-1999 Whistle Communications, Inc.
2 .\" All rights reserved.
4 .\" Subject to the following obligations and disclaimer of warranty, use and
5 .\" redistribution of this software, in source or object code forms, with or
6 .\" without modifications are expressly permitted by Whistle Communications;
7 .\" provided, however, that:
8 .\" 1. Any and all reproductions of the source or object code must include the
9 .\" copyright notice above and the following disclaimer of warranties; and
10 .\" 2. No rights are granted, in any manner or form, to use Whistle
11 .\" Communications, Inc. trademarks, including the mark "WHISTLE
12 .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as
13 .\" such appears in the above copyright notice or in the software.
15 .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
16 .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
17 .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
18 .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
20 .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
21 .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
22 .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
23 .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
24 .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
25 .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
26 .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
27 .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30 .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
33 .\" Author: Archie Cobbs <archie@whistle.com>
34 .\" $Whistle: netgraph.3,v 1.7 1999/01/25 07:14:06 archie Exp $
48 .Nm NgAllocRecvAsciiMsg ,
54 .Nd netgraph user library
60 .Fn NgMkSockNode "const char *name" "int *csp" "int *dsp"
62 .Fn NgNameNode "int cs" "const char *path" "const char *fmt" ...
65 .Fa "int cs" "const char *path" "int cookie" "int cmd" "const void *arg"
69 .Fn NgSendAsciiMsg "int cs" "const char *path" "const char *fmt" ...
72 .Fa "int cs" "const char *path" "struct ng_mesg *msg" "const void *arg"
76 .Fn NgRecvMsg "int cs" "struct ng_mesg *rep" "size_t replen" "char *path"
78 .Fn NgAllocRecvMsg "int cs" "struct ng_mesg **rep" "char *path"
80 .Fn NgRecvAsciiMsg "int cs" "struct ng_mesg *rep" "size_t replen" "char *path"
82 .Fn NgAllocRecvAsciiMsg "int cs" "struct ng_mesg **rep" "char *path"
84 .Fn NgSendData "int ds" "const char *hook" "const u_char *buf" "size_t len"
86 .Fn NgRecvData "int ds" "u_char *buf" "size_t len" "char *hook"
88 .Fn NgAllocRecvData "int ds" "u_char **buf" "char *hook"
90 .Fn NgSetDebug "int level"
93 .Fa "void \*[lp]*log\*[rp]\*[lp]const char *fmt, ...\*[rp]"
94 .Fa "void \*[lp]*logx\*[rp]\*[lp]const char *fmt, ...\*[rp]"
97 These functions facilitate user-mode program participation in the kernel
99 graph-based networking system, by utilizing the netgraph
106 function should be called first, to create a new
108 type netgraph node with associated control and data sockets.
112 .No non- Ns Dv NULL ,
113 the node will have that global name assigned to it.
118 arguments will be set to the newly opened control and data sockets
119 associated with the node; either
125 if only one socket is desired.
130 node type KLD if it is not already loaded.
134 function assigns a global name to the node addressed by
139 function sends a binary control message from the
141 node associated with control socket
143 to the node addressed by
147 indicates how to interpret
149 which indicates a specific command.
150 Extra argument data (if any) is specified by
156 and argument data are defined by the header file corresponding
157 to the type of the node being addressed.
158 The unique, non-negative token value chosen for use in the message
160 This value is typically used to associate replies.
164 to send reply to a previously received control message.
165 The original message header should be pointed to by
170 function performs the same function as
174 encoding of control messages.
177 function formats its input a la
179 and then sends the resulting
181 string to the node in a
184 The node returns a binary version of the
185 message, which is then sent back to the node just as with
189 the message token value is returned.
192 conversion may not be supported by all node types.
196 function reads the next control message received by the node associated with
199 The message and any extra argument data must fit in
205 .No non- Ns Dv NULL ,
206 it must point to a buffer of at least
208 bytes, which will be filled in (and
210 terminated) with the path to
211 the node from which the message was received.
213 The length of the control message is returned.
214 A return value of zero indicates that the socket was closed.
218 function works exactly like
220 except that the buffer for a message is dynamically allocated
221 to guarantee that a message is not truncated.
222 The size of the buffer is equal to the socket's receive buffer size.
223 The caller is responsible for freeing the buffer when it is no longer required.
227 function works exactly like
229 except that after the message is received, any binary arguments
234 request back to the originating node.
235 The result is the same as
237 with the exception that the reply arguments field will contain a
238 .Dv NUL Ns -terminated
240 version of the arguments (and the reply
241 header argument length field will be adjusted).
244 .Fn NgAllocRecvAsciiMsg
245 function works exactly like
247 except that the buffer for a message is dynamically allocated
248 to guarantee that a message is not truncated.
249 The size of the buffer is equal to the socket's receive buffer size.
250 The caller is responsible for freeing the buffer when it is no longer required.
254 function writes a data packet out on the specified hook of the node
255 corresponding to data socket
257 The node must already be connected to some other node via that hook.
261 function reads the next data packet (of up to
263 bytes) received by the node corresponding to data socket
267 which must be large enough to hold the entire packet.
271 .No non- Ns Dv NULL ,
272 it must point to a buffer of at least
274 bytes, which will be filled in (and
276 terminated) with the name of
277 the hook on which the data was received.
279 The length of the packet is returned.
280 A return value of zero indicates that the socket was closed.
284 function works exactly like
286 except that the buffer for a data packet is dynamically allocated
287 to guarantee that a data packet is not truncated.
288 The size of the buffer is equal to the socket's receive buffer size.
289 The caller is responsible for freeing the buffer when it is no longer required.
295 functions are used for debugging.
298 function sets the debug level (if non-negative), and returns the old setting.
299 Higher debug levels result in more verbosity.
301 All debug and error messages are logged via the functions
302 specified in the most recent call to
304 The default logging functions are
309 At debug level 3, the library attempts to display control message arguments
312 format; however, this results in additional messages being
313 sent which may interfere with debugging.
314 At even higher levels,
315 even these additional messages will be displayed, etc.
319 can be used on the data and the control sockets to detect the presence of
320 incoming data and control messages, respectively.
321 Data and control packets are always written and read atomically, i.e.,
324 User mode programs must be linked with the
326 flag to link in this library.
328 To enable netgraph in your kernel, either your kernel must be
330 .Cd "options NETGRAPH"
331 in the kernel configuration
336 KLD modules must have been loaded via
341 function returns the previous debug setting.
345 function has no return value.
347 All other functions return \-1 if there was an error and set
351 A return value of zero from
355 indicates that the netgraph socket has been closed.
361 the following additional errors are possible:
364 The node type does not know how to encode or decode the control message.
366 The encoded or decoded arguments were too long for the supplied buffer.
368 An unknown structure field was seen in an
372 The same structure field was specified twice in an
377 control message parse error or illegal value.
379 ASCII control message array or fixed width string buffer overflow.
391 system was designed and first implemented at Whistle Communications, Inc.\& in
394 customized for the Whistle InterJet.
396 .An Archie Cobbs Aq Mt archie@FreeBSD.org