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