diff options
Diffstat (limited to 'lib/libnetgraph/netgraph.3')
| -rw-r--r-- | lib/libnetgraph/netgraph.3 | 398 |
1 files changed, 398 insertions, 0 deletions
diff --git a/lib/libnetgraph/netgraph.3 b/lib/libnetgraph/netgraph.3 new file mode 100644 index 0000000..d2ef8bd --- /dev/null +++ b/lib/libnetgraph/netgraph.3 @@ -0,0 +1,398 @@ +.\" 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 27, 2004 +.Dt NETGRAPH 3 +.Os +.Sh NAME +.Nm NgMkSockNode , +.Nm NgNameNode , +.Nm NgSendMsg , +.Nm NgSendAsciiMsg , +.Nm NgSendMsgReply , +.Nm NgRecvMsg , +.Nm NgAllocRecvMsg , +.Nm NgRecvAsciiMsg , +.Nm NgAllocRecvAsciiMsg , +.Nm NgSendData , +.Nm NgRecvData , +.Nm NgAllocRecvData , +.Nm NgSetDebug , +.Nm NgSetErrLog +.Nd netgraph user library +.Sh LIBRARY +.Lb libnetgraph +.Sh SYNOPSIS +.In 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 +.Fo NgSendMsg +.Fa "int cs" "const char *path" "int cookie" "int cmd" "const void *arg" +.Fa "size_t arglen" +.Fc +.Ft int +.Fn NgSendAsciiMsg "int cs" "const char *path" "const char *fmt" ... +.Ft int +.Fo NgSendMsgReply +.Fa "int cs" "const char *path" "struct ng_mesg *msg" "const void *arg" +.Fa "size_t arglen" +.Fc +.Ft int +.Fn NgRecvMsg "int cs" "struct ng_mesg *rep" "size_t replen" "char *path" +.Ft int +.Fn NgAllocRecvMsg "int cs" "struct ng_mesg **rep" "char *path" +.Ft int +.Fn NgRecvAsciiMsg "int cs" "struct ng_mesg *rep" "size_t replen" "char *path" +.Ft int +.Fn NgAllocRecvAsciiMsg "int cs" "struct ng_mesg **rep" "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 NgAllocRecvData "int ds" "u_char **buf" "char *hook" +.Ft int +.Fn NgSetDebug "int level" +.Ft void +.Fo NgSetErrLog +.Fa "void \*[lp]*log\*[rp]\*[lp]const char *fmt, ...\*[rp]" +.Fa "void \*[lp]*logx\*[rp]\*[lp]const char *fmt, ...\*[rp]" +.Fc +.Sh DESCRIPTION +These functions facilitate user-mode program participation in the kernel +.Xr netgraph 4 +graph-based networking system, by utilizing the netgraph +.Vt socket +node type (see +.Xr ng_socket 4 ) . +.Pp +The +.Fn NgMkSockNode +function should be called first, to create a new +.Vt socket +type netgraph node with associated control and data sockets. +If +.Fa name +is +.No non- Ns Dv NULL , +the node will have that global name assigned to it. +The +.Fa csp +and +.Fa dsp +arguments will be set to the newly opened control and data sockets +associated with the node; either +.Fa csp +or +.Fa dsp +may be +.Dv NULL +if only one socket is desired. +The +.Fn NgMkSockNode +function loads the +.Vt socket +node type KLD if it is not already loaded. +.Pp +The +.Fn NgNameNode +function assigns a global name to the node addressed by +.Fa path . +.Pp +The +.Fn NgSendMsg +function sends a binary control message from the +.Vt 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 , cmd , +and argument data are defined by the header file corresponding +to the type of the node being addressed. +The unique, non-negative token value chosen for use in the message +header is returned. +This value is typically used to associate replies. +.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 +The +.Fn NgSendAsciiMsg +function performs the same function as +.Fn NgSendMsg , +but adds support for +.Tn ASCII +encoding of control messages. +The +.Fn NgSendAsciiMsg +function formats its input a la +.Xr printf 3 +and then sends the resulting +.Tn 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 . +As with +.Fn NgSendMsg , +the message token value is returned. +Note that +.Tn ASCII +conversion may not be supported by all node types. +.Pp +The +.Fn NgRecvMsg +function 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 +.No non- Ns Dv NULL , +it must point to a buffer of at least +.Dv NG_PATHSIZ +bytes, which will be filled in (and +.Dv NUL +terminated) with the path to +the node from which the message was received. +.Pp +The length of the control message is returned. +A return value of zero indicates that the socket was closed. +.Pp +The +.Fn NgAllocRecvMsg +function works exactly like +.Fn NgRecvMsg , +except that the buffer for a message is dynamically allocated +to guarantee that a message is not truncated. +The size of the buffer is equal to the socket's receive buffer size. +The caller is responsible for freeing the buffer when it is no longer required. +.Pp +The +.Fn NgRecvAsciiMsg +function works exactly like +.Fn NgRecvMsg , +except that after the message is received, any binary arguments +are converted to +.Tn ASCII +by sending a +.Dv NGM_BINARY2ASCII +request back to the originating node. +The result is the same as +.Fn NgRecvMsg , +with the exception that the reply arguments field will contain a +.Dv NUL Ns -terminated +.Tn ASCII +version of the arguments (and the reply +header argument length field will be adjusted). +.Pp +The +.Fn NgAllocRecvAsciiMsg +function works exactly like +.Fn NgRecvAsciiMsg , +except that the buffer for a message is dynamically allocated +to guarantee that a message is not truncated. +The size of the buffer is equal to the socket's receive buffer size. +The caller is responsible for freeing the buffer when it is no longer required. +.Pp +The +.Fn NgSendData +function 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 +The +.Fn NgRecvData +function 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 +.No non- Ns Dv NULL , +it must point to a buffer of at least +.Dv NG_HOOKSIZ +bytes, which will be filled in (and +.Dv NUL +terminated) with the name of +the hook on which the data was received. +.Pp +The length of the packet is returned. +A return value of zero indicates that the socket was closed. +.Pp +The +.Fn NgAllocRecvData +function works exactly like +.Fn NgRecvData , +except that the buffer for a data packet is dynamically allocated +to guarantee that a data packet is not truncated. +The size of the buffer is equal to the socket's receive buffer size. +The caller is responsible for freeing the buffer when it is no longer required. +.Pp +The +.Fn NgSetDebug +and +.Fn NgSetErrLog +functions are used for debugging. +The +.Fn NgSetDebug +function 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 +.Tn ASCII +format; however, this results in additional messages being +sent which may interfere with debugging. +At even higher levels, +even these additional messages 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 +.Fl l Ns Li netgraph +flag to link in this library. +.Sh INITIALIZATION +To enable netgraph in your kernel, either your kernel must be +compiled with +.Cd "options NETGRAPH" +in the kernel configuration +file, or else the +.Xr netgraph 4 +and +.Xr ng_socket 4 +KLD modules must have been loaded via +.Xr kldload 8 . +.Sh RETURN VALUES +The +.Fn NgSetDebug +function returns the previous debug setting. +.Pp +The +.Fn NgSetErrLog +function has no return value. +.Pp +All other functions return \-1 if there was an error and set +.Va errno +accordingly. +.Pp +A return value of zero from +.Fn NgRecvMsg +or +.Fn NgRecvData +indicates that the netgraph socket has been closed. +.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 +.Tn ASCII +control message. +.It Bq Er EALREADY +The same structure field was specified twice in an +.Tn ASCII +control message. +.It Bq Er EINVAL +.Tn 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 select 2 , +.Xr socket 2 , +.Xr warnx 3 , +.Xr kld 4 , +.Xr netgraph 4 , +.Xr ng_socket 4 +.Sh HISTORY +The +.Nm netgraph +system was designed and first implemented at Whistle Communications, Inc.\& in +a version of +.Fx 2.2 +customized for the Whistle InterJet. +.Sh AUTHORS +.An "Archie Cobbs" Aq archie@FreeBSD.org |
