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