lib/libnetgraph7/netgraph.3

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