summaryrefslogtreecommitdiffstats
path: root/lib
diff options
context:
space:
mode:
Diffstat (limited to 'lib')
-rw-r--r--lib/libnetgraph/netgraph.3111
1 files changed, 72 insertions, 39 deletions
diff --git a/lib/libnetgraph/netgraph.3 b/lib/libnetgraph/netgraph.3
index b50ccee..8520170 100644
--- a/lib/libnetgraph/netgraph.3
+++ b/lib/libnetgraph/netgraph.3
@@ -55,13 +55,19 @@
.Ft int
.Fn NgMkSockNode "const char *name" "int *csp" "int *dsp"
.Ft int
-.Fn NgNameNode "int cs" "const char *path" "const char *fmt" "..."
+.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"
+.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" "..."
+.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"
+.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
@@ -73,35 +79,45 @@
.Ft int
.Fn NgSetDebug "int level"
.Ft void
-.Fn NgSetErrLog "void (*log)(const char *fmt, ...)" "void (*logx)(const char *fmt, ...)"
+.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
-.Em socket
+.Vt socket
node type (see
.Xr ng_socket 4 ) .
.Pp
The
.Fn NgMkSockNode
function should be called first, to create a new
-.Em socket
-type netgraph node with associated control and data sockets. If
+.Vt 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.
+is
+.No non- Ns Dv NULL ,
+the node will have that global name assigned to it.
The
-.Fa "csp"
+.Fa csp
and
-.Fa "dsp"
+.Fa dsp
arguments will be set to the newly opened control and data sockets
associated with the node; either
-.Fa "csp"
+.Fa csp
or
-.Fa "dsp"
-may be NULL if only one socket is desired.
+.Fa dsp
+may be
+.Dv NULL
+if only one socket is desired.
The
.Fn NgMkSockNode
-function loads the socket node type KLD if it's not already loaded.
+function loads the
+.Vt socket
+node type KLD if it is not already loaded.
.Pp
The
.Fn NgNameNode
@@ -110,8 +126,9 @@ function assigns a global name to the node addressed by
.Pp
The
.Fn NgSendMsg
-function sends a binary control message from the socket node associated
-with control socket
+function sends a binary control message from the
+.Vt socket
+node associated with control socket
.Fa cs
to the node addressed by
.Fa path .
@@ -125,12 +142,12 @@ Extra argument data (if any) is specified by
and
.Fa arglen .
The
-.Fa cookie ,
-.Fa cmd ,
+.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.
+header is returned.
+This value is typically used to associate replies.
.Pp
Use
.Fn NgSendMsgReply
@@ -153,7 +170,8 @@ 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
+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
@@ -172,10 +190,14 @@ 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_PATHSIZ"
-bytes, which will be filled in (and NUL terminated) with the path to
+.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.
@@ -190,10 +212,11 @@ are converted to
.Tn ASCII
by sending a
.Dv NGM_BINARY2ASCII
-request back to the originating node. The result is the same as
+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
+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).
@@ -213,11 +236,16 @@ 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_HOOKSIZ"
-bytes, which will be filled in (and NUL terminated) with the name of
+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.
@@ -231,7 +259,8 @@ 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.
+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 .
@@ -244,7 +273,8 @@ 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,
+sent which may interfere with debugging.
+At even higher levels,
even these additional messages will be displayed, etc.
.Pp
Note that
@@ -255,12 +285,12 @@ 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
+.Fl l Ns Li netgraph
flag to link in this library.
.Sh INITIALIZATION
-To enable Netgraph in your kernel, either your kernel must be
+To enable netgraph in your kernel, either your kernel must be
compiled with
-.Dq options NETGRAPH
+.Cd "options NETGRAPH"
in the kernel configuration
file, or else the
.Xr netgraph 4
@@ -272,12 +302,15 @@ KLD modules must have been loaded via
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
@@ -323,4 +356,4 @@ a version of
.Fx 2.2
customized for the Whistle InterJet.
.Sh AUTHORS
-.An Archie Cobbs Aq archie@whistle.com
+.An "Archie Cobbs" Aq archie@FreeBSD.org
OpenPOWER on IntegriCloud