| blob | 8ea522556bdaf48a222f0a4e3e541d7cf203b91c |
1 .\" Copyright (c) 1996-1999 Whistle Communications, Inc.
2 .\" All rights reserved.
3 .\"
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.
14 .\"
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
31 .\" OF SUCH DAMAGE.
32 .\"
33 .\" Author: Archie Cobbs <archie@whistle.com>
34 .\"
35 .\" $FreeBSD: src/lib/libnetgraph/netgraph.3,v 1.4.2.10 2002/12/29 16:35:36 schweikh Exp $
36 .\" $Whistle: netgraph.3,v 1.7 1999/01/25 07:14:06 archie Exp $
37 .\"
38 .Dd January 27, 2004
39 .Dt NETGRAPH 3
40 .Os
41 .Sh NAME
42 .Nm NgMkSockNode ,
43 .Nm NgNameNode ,
44 .Nm NgSendMsg ,
45 .Nm NgSendAsciiMsg ,
46 .Nm NgSendReplyMsg ,
47 .Nm NgRecvMsg ,
48 .Nm NgAllocRecvMsg ,
49 .Nm NgRecvAsciiMsg ,
50 .Nm NgAllocRecvAsciiMsg ,
51 .Nm NgSendData ,
52 .Nm NgRecvData ,
53 .Nm NgAllocRecvData ,
54 .Nm NgSetDebug ,
55 .Nm NgSetErrLog
56 .Nd netgraph user library
57 .Sh LIBRARY
58 .Lb libnetgraph
59 .Sh SYNOPSIS
60 .In netgraph.h
61 .Ft int
62 .Fn NgMkSockNode "const char *name" "int *csp" "int *dsp"
63 .Ft int
64 .Fn NgNameNode "int cs" "const char *path" "const char *fmt" ...
65 .Ft int
66 .Fo NgSendMsg
67 .Fa "int cs" "const char *path" "int cookie" "int cmd" "const void *arg"
68 .Fa "size_t arglen"
69 .Fc
70 .Ft int
71 .Fn NgSendAsciiMsg "int cs" "const char *path" "const char *fmt" ...
72 .Ft int
73 .Fo NgSendReplyMsg
74 .Fa "int cs" "const char *path" "const struct ng_mesg *msg" "const void *arg"
75 .Fa "size_t arglen"
76 .Fc
77 .Ft int
78 .Fn NgRecvMsg "int cs" "struct ng_mesg *rep" "size_t replen" "char *path"
79 .Ft int
80 .Fn NgAllocRecvMsg "int cs" "struct ng_mesg **rep" "char *path"
81 .Ft int
82 .Fn NgRecvAsciiMsg "int cs" "struct ng_mesg *rep" "size_t replen" "char *path"
83 .Ft int
84 .Fn NgAllocRecvAsciiMsg "int cs" "struct ng_mesg **rep" "char *path"
85 .Ft int
86 .Fn NgSendData "int ds" "const char *hook" "const u_char *buf" "size_t len"
87 .Ft int
88 .Fn NgRecvData "int ds" "u_char *buf" "size_t len" "char *hook"
89 .Ft int
90 .Fn NgAllocRecvData "int ds" "u_char **buf" "char *hook"
91 .Ft int
92 .Fn NgSetDebug "int level"
93 .Ft void
94 .Fo NgSetErrLog
95 .Fa "void (*log)(const char *fmt, ...)"
96 .Fa "void (*logx)(const char *fmt, ...)"
97 .Fc
98 .Sh DESCRIPTION
99 These functions facilitate user-mode program participation in the kernel
100 .Xr netgraph 4
101 graph-based networking system, by utilizing the netgraph
102 .Vt socket
103 node type (see
104 .Xr ng_socket 4 ) .
105 .Pp
106 The
107 .Fn NgMkSockNode
108 function should be called first, to create a new
109 .Vt socket
110 type netgraph node with associated control and data sockets.
111 If
112 .Fa name
113 is
114 .No non- Ns Dv NULL ,
115 the node will have that global name assigned to it.
116 The
117 .Fa csp
118 and
119 .Fa dsp
120 arguments will be set to the newly opened control and data sockets
121 associated with the node; either
122 .Fa csp
123 or
124 .Fa dsp
125 may be
126 .Dv NULL
127 if only one socket is desired.
128 The
129 .Fn NgMkSockNode
130 function loads the
131 .Vt socket
132 node type KLD if it is not already loaded.
133 .Pp
134 The
135 .Fn NgNameNode
136 function assigns a global name to the node addressed by
137 .Fa path .
138 .Pp
139 The
140 .Fn NgSendMsg
141 function sends a binary control message from the
142 .Vt socket
143 node associated with control socket
144 .Fa cs
145 to the node addressed by
146 .Fa path .
147 The
148 .Fa cookie
149 indicates how to interpret
150 .Fa cmd ,
151 which indicates a specific command.
152 Extra argument data (if any) is specified by
153 .Fa arg
154 and
155 .Fa arglen .
156 The
157 .Fa cookie , cmd ,
158 and argument data are defined by the header file corresponding
159 to the type of the node being addressed.
160 The unique, non-negative token value chosen for use in the message
161 header is returned.
162 This value is typically used to associate replies.
163 .Pp
164 Use
165 .Fn NgSendReplyMsg
166 to send reply to a previously received control message.
167 The original message header should be pointed to by
168 .Fa msg .
169 .Pp
170 The
171 .Fn NgSendAsciiMsg
172 function performs the same function as
173 .Fn NgSendMsg ,
174 but adds support for
175 .Tn ASCII
176 encoding of control messages.
177 The
178 .Fn NgSendAsciiMsg
179 function formats its input a la
180 .Xr printf 3
181 and then sends the resulting
182 .Tn ASCII
183 string to the node in a
184 .Dv NGM_ASCII2BINARY
185 control message.
186 The node returns a binary version of the
187 message, which is then sent back to the node just as with
188 .Fn NgSendMsg .
189 As with
190 .Fn NgSendMsg ,
191 the message token value is returned.
192 Note that
193 .Tn ASCII
194 conversion may not be supported by all node types.
195 .Pp
196 The
197 .Fn NgRecvMsg
198 function reads the next control message received by the node associated with
199 control socket
200 .Fa cs .
201 The message and any extra argument data must fit in
202 .Fa replen
203 bytes.
204 If
205 .Fa path
206 is
207 .No non- Ns Dv NULL ,
208 it must point to a buffer of at least
209 .Dv NG_PATHSIZ
210 bytes, which will be filled in (and
211 .Dv NUL
212 terminated) with the path to
213 the node from which the message was received.
214 .Pp
215 The length of the control message is returned.
216 A return value of zero indicates that the socket was closed.
217 .Pp
218 The
219 .Fn NgAllocRecvMsg
220 function works exactly like
221 .Fn NgRecvMsg ,
222 except that the buffer for a message is dynamically allocated
223 to guarantee that a message is not truncated.
224 The size of the buffer is equal to the socket's receive buffer size.
225 The caller is responsible for freeing the buffer when it is no longer required.
226 .Pp
227 The
228 .Fn NgRecvAsciiMsg
229 function works exactly like
230 .Fn NgRecvMsg ,
231 except that after the message is received, any binary arguments
232 are converted to
233 .Tn ASCII
234 by sending a
235 .Dv NGM_BINARY2ASCII
236 request back to the originating node.
237 The result is the same as
238 .Fn NgRecvMsg ,
239 with the exception that the reply arguments field will contain a
240 .Dv NUL Ns -terminated
241 .Tn ASCII
242 version of the arguments (and the reply
243 header argument length field will be adjusted).
244 .Pp
245 The
246 .Fn NgAllocRecvAsciiMsg
247 function works exactly like
248 .Fn NgRecvAsciiMsg ,
249 except that the buffer for a message is dynamically allocated
250 to guarantee that a message is not truncated.
251 The size of the buffer is equal to the socket's receive buffer size.
252 The caller is responsible for freeing the buffer when it is no longer required.
253 .Pp
254 The
255 .Fn NgSendData
256 function writes a data packet out on the specified hook of the node
257 corresponding to data socket
258 .Fa ds .
259 The node must already be connected to some other node via that hook.
260 .Pp
261 The
262 .Fn NgRecvData
263 function reads the next data packet (of up to
264 .Fa len
265 bytes) received by the node corresponding to data socket
266 .Fa ds
267 and stores it in
268 .Fa buf ,
269 which must be large enough to hold the entire packet.
270 If
271 .Fa hook
272 is
273 .No non- Ns Dv NULL ,
274 it must point to a buffer of at least
275 .Dv NG_HOOKSIZ
276 bytes, which will be filled in (and
277 .Dv NUL
278 terminated) with the name of
279 the hook on which the data was received.
280 .Pp
281 The length of the packet is returned.
282 A return value of zero indicates that the socket was closed.
283 .Pp
284 The
285 .Fn NgAllocRecvData
286 function works exactly like
287 .Fn NgRecvData ,
288 except that the buffer for a data packet is dynamically allocated
289 to guarantee that a data packet is not truncated.
290 The size of the buffer is equal to the socket's receive buffer size.
291 The caller is responsible for freeing the buffer when it is no longer required.
292 .Pp
293 The
294 .Fn NgSetDebug
295 and
296 .Fn NgSetErrLog
297 functions are used for debugging.
298 The
299 .Fn NgSetDebug
300 function sets the debug level (if non-negative), and returns the old setting.
301 Higher debug levels result in more verbosity.
302 The default is zero.
303 All debug and error messages are logged via the functions
304 specified in the most recent call to
305 .Fn NgSetErrLog .
306 The default logging functions are
307 .Xr vwarn 3
308 and
309 .Xr vwarnx 3 .
310 .Pp
311 At debug level 3, the library attempts to display control message arguments
312 in
313 .Tn ASCII
314 format; however, this results in additional messages being
315 sent which may interfere with debugging.
316 At even higher levels,
317 even these additional messages will be displayed, etc.
318 .Pp
319 Note that
320 .Xr select 2
321 can be used on the data and the control sockets to detect the presence of
322 incoming data and control messages, respectively.
323 Data and control packets are always written and read atomically, i.e.,
324 in one whole piece.
325 .Pp
326 User mode programs must be linked with the
327 .Fl l Ns Li netgraph
328 flag to link in this library.
329 .Sh INITIALIZATION
330 To enable netgraph in your kernel, either your kernel must be
331 compiled with
332 .Cd "options NETGRAPH"
333 in the kernel configuration
334 file, or else the
335 .Xr netgraph 4
336 and
337 .Xr ng_socket 4
338 KLD modules must have been loaded via
339 .Xr kldload 8 .
340 .Sh RETURN VALUES
341 The
342 .Fn NgSetDebug
343 function returns the previous debug setting.
344 .Pp
345 The
346 .Fn NgSetErrLog
347 function has no return value.
348 .Pp
349 All other functions return \-1 if there was an error and set
350 .Va errno
351 accordingly.
352 .Pp
353 A return value of zero from
354 .Fn NgRecvMsg
355 or
356 .Fn NgRecvData
357 indicates that the netgraph socket has been closed.
358 .Pp
359 For
360 .Fn NgSendAsciiMsg
361 and
362 .Fn NgRecvAsciiMsg ,
363 the following additional errors are possible:
364 .Bl -tag -width Er
365 .It Bq Er ENOSYS
366 The node type does not know how to encode or decode the control message.
367 .It Bq Er ERANGE
368 The encoded or decoded arguments were too long for the supplied buffer.
369 .It Bq Er ENOENT
370 An unknown structure field was seen in an
371 .Tn ASCII
372 control message.
373 .It Bq Er EALREADY
374 The same structure field was specified twice in an
375 .Tn ASCII
376 control message.
377 .It Bq Er EINVAL
378 .Tn ASCII
379 control message parse error or illegal value.
380 .It Bq Er E2BIG
381 ASCII control message array or fixed width string buffer overflow.
382 .El
383 .Sh SEE ALSO
384 .Xr select 2 ,
385 .Xr socket 2 ,
386 .Xr warnx 3 ,
387 .Xr kld 4 ,
388 .Xr netgraph 4 ,
389 .Xr ng_socket 4
390 .Sh HISTORY
391 The
392 .Nm netgraph
393 system was designed and first implemented at Whistle Communications, Inc.\& in
394 a version of
395 .Fx 2.2
396 customized for the Whistle InterJet.
397 .Sh AUTHORS
398 .An Archie Cobbs Aq Mt archie@FreeBSD.org