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