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