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