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, 127 insertions, 0 deletions

diff --git a/share/man/man4/ng_socket.4 b/share/man/man4/ng_socket.4
new file mode 100644
index 0000000..31302a5
--- /dev/null
+++ b/share/man/man4/ng_socket.4
@@ -0,0 +1,127 @@
+.\" 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: ng_socket.8,v 1.5 1999/01/25 23:46:27 archie Exp $
+.\"
+.Dd January 19, 1999
+.Dt NG_SOCKET 8
+.Os FreeBSD 3
+.Sh NAME
+.Nm ng_socket
+.Nd netgraph socket node type
+.Sh SYNOPSIS
+.Fd #include <netgraph/ng_message.h>
+.Fd #include <netgraph/ng_socket.h>
+.Sh DESCRIPTION
+A
+.Nm socket
+node is both a BSD socket and a netgraph node. The
+.Nm socket
+node type allows user-mode processes to participate in the kernel
+.Xr netgraph 4
+networking subsystem using the BSD socket interface.
+.Pp
+A new
+.Nm socket
+node is created by creating a new socket of type
+.Dv NG_CONTROL
+in the protocol family
+.Dv PF_NETGRAPH ,
+using the
+.Xr socket 2
+system call.
+Any control messages received by the node are received using
+.Xr recvfrom 2 ;
+the socket address argument is a
+.Dv "struct sockaddr_ng"
+containing the sender's netgraph address. Conversely, control messages
+can be sent to any node by calling
+.Xr sendto 2 ,
+supplying the recipient's address in a
+.Dv "struct sockaddr_ng" .
+The
+.Xr bind 2
+system call may be used to assign a global netgraph name to the node.
+.Pp
+To transmit and receive netgraph data packets, a
+.Dv NG_DATA
+socket must also be created using
+.Xr socket 2
+and associated with a
+.Nm socket
+node.
+.Dv NG_DATA sockets do not automatically
+have nodes associated with them; they are bound to a specific node via the
+.Xr connect 2
+system call. The address argument is the netgraph address of the
+.Nm socket
+node already created. Once a data socket is associated with a node,
+any data packets received by the node are read using
+.Xr recvfrom 2
+and any packets to be sent out from the node are written using
+.Xr sendto 2 .
+In the case of data sockets, the
+.Dv "struct sockaddr_ng"
+contains the name of the
+.Em hook
+on which the data was received or should be sent.
+.Pp
+There is a user library that simplifies using netgraph sockets; see
+.Xr netgraph 3 .
+.Sh HOOKS
+This node type supports hooks with arbitrary names (as long as
+they are unique) and always accepts hook connection requests.
+.Sh CONTROL MESSAGES
+This node type supports only the generic control messages.
+.Sh SHUTDOWN
+This node type shuts down and disappears when both the associated
+.Dv NG_CONTROL
+and
+.Dv NG_DATA
+sockets have been closed, or a
+.Dv NGM_SHUTDOWN
+control message is received. In the latter case, attempts to write
+to the still-open sockets will return
+.Er ENOTCONN .
+.Sh BUGS
+It is not possible to reject the connection of a hook, though any
+data received on that hook can certainly be ignored.
+.Sh SEE ALSO
+.Xr socket 2 ,
+.Xr netgraph 3 ,
+.Xr netgraph 4 ,
+.Xr ngctl 8 .
+.Sh AUTHOR
+Julian Elisher <julian@whistle.com>