4cf49a4355
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
212 lines
6.6 KiB
Groff
212 lines
6.6 KiB
Groff
.\" 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>
|