| blob | 0e3e43cb083ead66fe2ce6fc5ce88552f67b4d5c |
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 19, 1999
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 NgRecvAsciiMsg ,
49 .Nm NgSendData ,
50 .Nm NgRecvData ,
51 .Nm NgSetDebug ,
52 .Nm NgSetErrLog
53 .Nd netgraph user library
54 .Sh LIBRARY
55 .Lb libnetgraph
56 .Sh SYNOPSIS
57 .In netgraph.h
58 .Ft int
59 .Fn NgMkSockNode "const char *name" "int *csp" "int *dsp"
60 .Ft int
61 .Fn NgNameNode "int cs" "const char *path" "const char *fmt" "..."
62 .Ft int
63 .Fn NgSendMsg "int cs" "const char *path" "int cookie" "int cmd" "const void *arg" "size_t arglen"
64 .Ft int
65 .Fn NgSendAsciiMsg "int cs" "const char *path" "const char *fmt" "..."
66 .Ft int
67 .Fn NgSendReplyMsg "int cs" "const char *path" "const struct ng_mesg *msg" "const void *arg" "size_t arglen"
68 .Ft int
69 .Fn NgRecvMsg "int cs" "struct ng_mesg *rep" "size_t replen" "char *path"
70 .Ft int
71 .Fn NgRecvAsciiMsg "int cs" "struct ng_mesg *rep" "size_t replen" "char *path"
72 .Ft int
73 .Fn NgSendData "int ds" "const char *hook" "const u_char *buf" "size_t len"
74 .Ft int
75 .Fn NgRecvData "int ds" "u_char *buf" "size_t len" "char *hook"
76 .Ft int
77 .Fn NgSetDebug "int level"
78 .Ft void
79 .Fn NgSetErrLog "void (*log)(const char *fmt, ...)" "void (*logx)(const char *fmt, ...)"
80 .Sh DESCRIPTION
81 These functions facilitate user-mode program participation in the kernel
82 .Xr netgraph 4
83 graph-based networking system, by utilizing the netgraph
84 .Em socket
85 node type (see
86 .Xr ng_socket 4 ) .
87 .Pp
88 .Fn NgMkSockNode
89 should be called first, to create a new
90 .Em socket
91 type netgraph node with associated control and data sockets. If
92 .Fa name
93 is non-NULL, the node will have that global name assigned to it.
94 .Fa "*csp"
95 and
96 .Fa "*dsp"
97 will be set to the newly opened control and data sockets
98 associated with the node; either
99 .Fa "csp"
100 or
101 .Fa "dsp"
102 may be NULL if only one socket is desired.
103 .Fn NgMkSockNode
104 loads the socket node type KLD if it's not already loaded.
105 .Pp
106 .Fn NgNameNode
107 assigns a global name to the node addressed by
108 .Fa path .
109 .Pp
110 .Fn NgSendMsg
111 sends a binary control message from the socket node associated
112 with control socket
113 .Fa cs
114 to the node addressed by
115 .Fa path .
116 The
117 .Fa cookie
118 indicates how to interpret
119 .Fa cmd ,
120 which indicates a specific command.
121 Extra argument data (if any) is specified by
122 .Fa arg
123 and
124 .Fa arglen .
125 The
126 .Fa cookie ,
127 .Fa cmd ,
128 and argument data are defined by the header file corresponding
129 to the type of the node being addressed.
130 The unique, non-negative token value chosen for use in the message
131 header is returned. This value is typically used to associate replies.
132 .Pp
133 Use
134 .Fn NgSendReplyMsg
135 to send reply to a previously received control message.
136 The original message header should be pointed to by
137 .Fa msg .
138 .Pp
139 .Fn NgSendAsciiMsg
140 performs the same function as
141 .Fn NgSendMsg ,
142 but adds support for
143 .Tn ASCII
144 encoding of control messages.
145 .Fn NgSendAsciiMsg
146 formats its input a la
147 .Xr printf 3
148 and then sends the resulting
149 .Tn ASCII
150 string to the node in a
151 .Dv NGM_ASCII2BINARY
152 control message. The node returns a binary version of the
153 message, which is then sent back to the node just as with
154 .Fn NgSendMsg .
155 As with
156 .Fn NgSendMsg ,
157 the message token value is returned.
158 Note that
159 .Tn ASCII
160 conversion may not be supported by all node types.
161 .Pp
162 .Fn NgRecvMsg
163 reads the next control message received by the node associated with
164 control socket
165 .Fa cs .
166 The message and any extra argument data must fit in
167 .Fa replen
168 bytes.
169 If
170 .Fa "path"
171 is non-NULL, it must point to a buffer of at least
172 .Dv "NG_PATHSIZ"
173 bytes, which will be filled in (and NUL terminated) with the path to
174 the node from which the message was received.
175 .Pp
176 The length of the control message is returned.
177 A return value of zero indicates that the socket was closed.
178 .Pp
179 .Fn NgRecvAsciiMsg
180 works exactly like
181 .Fn NgRecvMsg ,
182 except that after the message is received, any binary arguments
183 are converted to
184 .Tn ASCII
185 by sending a
186 .Dv NGM_BINARY2ASCII
187 request back to the originating node. The result is the same as
188 .Fn NgRecvAsciiMsg ,
189 with the exception that the reply arguments field will contain
190 a NUL-terminated
191 .Tn ASCII
192 version of the arguments (and the reply
193 header argument length field will be adjusted).
194 .Pp
195 .Fn NgSendData
196 writes a data packet out on the specified hook of the node corresponding
197 to data socket
198 .Fa ds .
199 The node must already be connected to some other node via that hook.
200 .Pp
201 .Fn NgRecvData
202 reads the next data packet (of up to
203 .Fa len
204 bytes) received by the node corresponding to data socket
205 .Fa ds
206 and stores it in
207 .Fa buf ,
208 which must be large enough to hold the entire packet. If
209 .Fa "hook"
210 is non-NULL, it must point to a buffer of at least
211 .Dv "NG_HOOKSIZ"
212 bytes, which will be filled in (and NUL terminated) with the name of
213 the hook on which the data was received.
214 .Pp
215 The length of the packet is returned.
216 A return value of zero indicates that the socket was closed.
217 .Pp
218 .Fn NgSetDebug
219 and
220 .Fn NgSetErrLog
221 are used for debugging.
222 .Fn NgSetDebug
223 sets the debug level (if non-negative), and returns the old setting.
224 Higher debug levels result in more verbosity. The default is zero.
225 All debug and error messages are logged via the functions
226 specified in the most recent call to
227 .Fn NgSetErrLog .
228 The default logging functions are
229 .Xr vwarn 3
230 and
231 .Xr vwarnx 3 .
232 .Pp
233 At debug level 3, the library attempts to display control message arguments
234 in
235 .Tn ASCII
236 format; however, this results in additional messages being
237 sent which may interfere with debugging. At even higher levels,
238 even these additional messages will be displayed, etc.
239 .Pp
240 Note that
241 .Xr select 2
242 can be used on the data and the control sockets to detect the presence of
243 incoming data and control messages, respectively.
244 Data and control packets are always written and read atomically, i.e.,
245 in one whole piece.
246 .Pp
247 User mode programs must be linked with the
248 .Dv -lnetgraph
249 flag to link in this library.
250 .Sh INITIALIZATION
251 To enable Netgraph in your kernel, either your kernel must be
252 compiled with
253 .Cd options NETGRAPH
254 in the kernel configuration
255 file, or else the
256 .Xr netgraph 4
257 and
258 .Xr ng_socket 4
259 KLD modules must have been loaded via
260 .Xr kldload 8 .
261 .Sh RETURN VALUES
262 .Fn NgSetDebug
263 returns the previous debug setting.
264 .Fn NgSetErrLog
265 has no return value.
266 All other functions return \-1 if there was an error and set
267 .Va errno
268 accordingly.
269 A return value of zero from
270 .Fn NgRecvMsg
271 or
272 .Fn NgRecvData
273 indicates that the netgraph socket has been closed.
274 .Pp
275 For
276 .Fn NgSendAsciiMsg
277 and
278 .Fn NgRecvAsciiMsg ,
279 the following additional errors are possible:
280 .Bl -tag -width Er
281 .It Bq Er ENOSYS
282 The node type does not know how to encode or decode the control message.
283 .It Bq Er ERANGE
284 The encoded or decoded arguments were too long for the supplied buffer.
285 .It Bq Er ENOENT
286 An unknown structure field was seen in an
287 .Tn ASCII
288 control message.
289 .It Bq Er EALREADY
290 The same structure field was specified twice in an
291 .Tn ASCII
292 control message.
293 .It Bq Er EINVAL
294 .Tn ASCII
295 control message parse error or illegal value.
296 .It Bq Er E2BIG
297 ASCII control message array or fixed width string buffer overflow.
298 .El
299 .Sh SEE ALSO
300 .Xr select 2 ,
301 .Xr socket 2 ,
302 .Xr warnx 3 ,
303 .Xr kld 4 ,
304 .Xr netgraph 4 ,
305 .Xr ng_socket 4
306 .Sh HISTORY
307 The
308 .Nm netgraph
309 system was designed and first implemented at Whistle Communications, Inc. in
310 a version of
311 .Fx 2.2
312 customized for the Whistle InterJet.
313 .Sh AUTHORS
314 .An Archie Cobbs Aq Mt archie@whistle.com