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