Whistle's Netgraph link-layer (sometimes more) networking infrastructure.

Been in production for 3 years now. Gives Instant Frame relay to if_sr
and if_ar drivers, and PPPOE support soon. See:
ftp://ftp.whistle.com/pub/archie/netgraph/index.html
for on-line manual pages.

Reviewed by: Doug Rabson (dfr@freebsd.org)
Obtained from:  Whistle CVS tree

1 files changed, 211 insertions, 0 deletions

diff --git a/lib/libnetgraph/netgraph.3 b/lib/libnetgraph/netgraph.3
new file mode 100644
index 0000000..dc9df04
--- /dev/null
+++ b/lib/libnetgraph/netgraph.3
@@ -0,0 +1,211 @@
+.\" 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 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 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 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 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 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
+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
+Netgraph is not part of the standard FreeBSD kernel. To enable it,
+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.
+.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>