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