1 files changed, 267 insertions, 0 deletions
diff --git a/lib/libnetgraph/netgraph.3 b/lib/libnetgraph/netgraph.3
new file mode 100644
index 0000000..6926f96
--- /dev/null
+++ b/lib/libnetgraph/netgraph.3
@@ -0,0 +1,267 @@
+.\" Copyright (c) 1996-1999 Whistle Communications, Inc.
+.\" All rights reserved.
+.\" 
+.\" Subject to the following obligations and disclaimer of warranty, use and
+.\" redistribution of this software, in source or object code forms, with or
+.\" without modifications are expressly permitted by Whistle Communications;
+.\" provided, however, that:
+.\" 1. Any and all reproductions of the source or object code must include the
+.\"    copyright notice above and the following disclaimer of warranties; and
+.\" 2. No rights are granted, in any manner or form, to use Whistle
+.\"    Communications, Inc. trademarks, including the mark "WHISTLE
+.\"    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
+.\"    such appears in the above copyright notice or in the software.
+.\" 
+.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
+.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
+.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
+.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
+.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
+.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
+.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
+.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
+.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
+.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
+.\" OF SUCH DAMAGE.
+.\"
+.\" Author: Archie Cobbs <archie@whistle.com>
+.\"
+.\" $FreeBSD$
+.\" $Whistle: netgraph.3,v 1.7 1999/01/25 07:14:06 archie Exp $
+.\"
+.Dd January 19, 1999
+.Dt NETGRAPH 3
+.Os FreeBSD 3
+.Sh NAME
+.Nm NgMkSockNode ,
+.Nm NgNameNode ,
+.Nm NgSendMsg ,
+.Nm NgRecvMsg ,
+.Nm NgSendData ,
+.Nm NgRecvData ,
+.Nm NgSetDebug ,
+.Nm NgSetErrLog
+.Nd Netgraph user library
+.Sh SYNOPSIS
+.Fd #include <netgraph.h>
+.Ft int
+.Fn NgMkSockNode "const char *name" "int *csp" "int *dsp"
+.Ft int
+.Fn NgNameNode "int cs" "const char *path" "const char *fmt" "..."
+.Ft int
+.Fn NgSendMsg "int cs" "const char *path" "int cookie" "int cmd" "const void *arg" "size_t arglen"
+.Ft int
+.Fn NgSendAsciiMsg "int cs" "const char *path" "const char *fmt" "..."
+.Ft int
+.Fn NgSendMsgReply "int cs" "const char *path" "struct ng_mesg *msg" "const void *arg" "size_t arglen"
+.Ft int
+.Fn NgRecvMsg "int cs" "struct ng_mesg *rep" "size_t replen" "char *path"
+.Ft int
+.Fn NgRecvAsciiMsg "int cs" "struct ng_mesg *rep" "size_t replen" "char *path"
+.Ft int
+.Fn NgSendData "int ds" "const char *hook" "const u_char *buf" "size_t len"
+.Ft int
+.Fn NgRecvData "int ds" "u_char *buf" "size_t len" "char *hook"
+.Ft int
+.Fn NgSetDebug "int level"
+.Ft void
+.Fn NgSetErrLog "void (*log)(const char *fmt, ...)" "void (*logx)(const char *fmt, ...)"
+.Sh DESCRIPTION
+These functions facilitate user-mode program participation in the kernel
+.Xr netgraph 4
+graph-based networking system, by utilizing the netgraph
+.Em socket
+node type (see
+.Xr ng_socket 8 ")."
+.Pp
+.Fn NgMkSockNode
+should be called first, to create a new
+.Em socket
+type netgraph node with associated control and data sockets.  If
+.Fa name
+is non-NULL, the node will have that global name assigned to it.
+.Fa "*csp"
+and
+.Fa "*dsp"
+will be set to the newly opened control and data sockets
+associated with the node; either
+.Fa "csp"
+or
+.Fa "dsp"
+may be NULL if only one socket is desired.
+.Pp
+.Fn NgNameNode
+assigns a global name to the node addressed by
+.Fa path .
+.Pp
+.Fn NgSendMsg
+sends a binary control message from the socket node associated
+with control socket
+.Fa cs
+to the node addressed by
+.Fa path .
+The
+.Fa cookie
+indicates how to interpret
+.Fa cmd ,
+which indicates a specific command.
+Extra argument data (if any) is specified by
+.Fa arg
+and
+.Fa arglen .
+The
+.Fa cookie ,
+.Fa cmd ,
+and argument data are defined by the header file corresponding
+to the type of the node being addressed.
+.Pp
+Use
+.Fn NgSendMsgReply
+to send reply to a previously received control message.
+The original message header should be pointed to by
+.Fa msg .
+.Pp
+.Fn NgSendAsciiMsg
+performs the same function as
+.Fn NgSendMsg ,
+but adds support for ASCII encoding of control messages.
+.Fn NgSendAsciiMsg
+formats its input a la
+.Xr printf 3
+and then sends the resulting ASCII string to the node in a
+.Dv NGM_ASCII2BINARY
+control message.  The node returns a binary version of the
+message, which is then sent back to the node just as with
+.Fn NgSendMsg .
+Note that ASCII conversion may not be supported by all node types.
+.Pp
+.Fn NgRecvMsg
+reads the next control message received by the node associated with
+control socket
+.Fa cs .
+The message and any extra argument data must fit in
+.Fa replen
+bytes.
+If
+.Fa "path"
+is non-NULL, it must point to a buffer of at least
+.Dv "NG_PATHLEN + 1"
+bytes, which will be filled in (and NUL terminated) with the path to
+the node from which the message was received.
+.Pp
+.Fn NgRecvAsciiMsg
+works exactly like
+.Fn NgRecvMsg ,
+except that after the message is received, any binary arguments
+are converted to ASCII by sending a
+.Dv NGM_BINARY2ASCII
+request back to the originating node.  The result is the same as
+.Fn NgRecvAsciiMsg ,
+with the exception that the reply arguments field will contain
+a NUL-terminated ASCII version of the arguments (and the reply
+header argument length field will be adjusted).
+.Pp
+.Fn NgSendData
+writes a data packet out on the specified hook of the node corresponding
+to data socket
+.Fa ds .
+The node must already be connected to some other node via that hook.
+.Pp
+.Fn NgRecvData
+reads the next data packet (of up to
+.Fa len
+bytes) received by the node corresponding to data socket
+.Fa ds
+and stores it in
+.Fa buf ,
+which must be large enough to hold the entire packet.  If
+.Fa "hook"
+is non-NULL, it must point to a buffer of at least
+.Dv "NG_HOOKLEN + 1"
+bytes, which will be filled in (and NUL terminated) with the name of
+the hook on which the data was received.
+.Pp
+.Fn NgSetDebug
+and
+.Fn NgSetErrLog
+are used for debugging.
+.Fn NgSetDebug
+sets the debug level (if non-negative), and returns the old setting.
+Higher debug levels result in more verbosity.  The default is zero.
+All debug and error messages are logged via the functions
+specified in the most recent call to
+.Fn NgSetErrLog .
+The default logging functions are
+.Xr vwarn 3
+and
+.Xr vwarnx 3 .
+.Pp
+At debug level 3, the library attempts to display control message arguments
+in ASCII format; however, this results in additional messages being
+sent which may interfere with debugging.  At even higher levels,
+even these additional messagages will be displayed, etc.
+.Pp
+Note that
+.Xr select 2
+can be used on the data and the control sockets to detect the presence of
+incoming data and control messages, respectively.
+Data and control packets are always written and read atomically, i.e.,
+in one whole piece.
+.Pp
+User mode programs must be linked with the
+.Dv -lnetgraph
+flag to link in this library.
+.Sh INITIALIZATION
+To enable Netgraph in your kernel, either your kernel must be
+compiled with ``options NETGRAPH'' in the kernel configuration
+file, or else the
+.Xr netgraph 4
+and
+.Xr ng_socket 8
+KLD modules must have been loaded via
+.Xr kldload 8 .
+.Sh DIAGNOSTICS
+All functions except
+.Fn NgSetDebug
+and
+.Fn NgSetErrLog
+return -1 if there was an error and set errno accordingly.
+.Pp
+For
+.Fn NgSendAsciiMsg
+and
+.Fn NgRecvAsciiMsg ,
+the following additional errors are possible:
+.Bl -tag -width Er
+.It Bq Er ENOSYS
+The node type does not know how to encode or decode the control message.
+.It Bq Er ERANGE
+The encoded or decoded arguments were too long for the supplied buffer.
+.It Bq Er ENOENT
+An unknown structure field was seen in an ASCII control message.
+.It Bq Er EALREADY
+The same structure field was specified twice in an ASCII control message.
+.It Bq Er EINVAL
+ASCII control message parse error or illegal value.
+.It Bq Er E2BIG
+ASCII control message array or fixed width string buffer overflow.
+.El
+.Sh SEE ALSO
+.Xr netgraph 4 ,
+.Xr socket 2 ,
+.Xr select 2 ,
+.Xr warnx 3 ,
+.Xr ng_socket 8 .
+.Sh HISTORY
+The
+.Em netgraph
+system was designed and first implemented at Whistle Communications, Inc. in
+a version FreeBSD 2.2 customized for the Whistle InterJet.
+.Sh AUTHOR
+.An Archie Cobbs <archie@whistle.com>