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 .\" $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" "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