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