diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/libnetgraph/netgraph.3 | 111 |
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 |
