Improve the documentation somewhat.

share/man/man4/ng_ether.4

@@ -34,7 +34,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd June 26, 2000
+.Dd April 21, 2004
 .Dt NG_ETHER 4
 .Os
 .Sh NAME
@@ -44,115 +44,119 @@
 .In netgraph/ng_ether.h
 .Sh DESCRIPTION
 The
-.Nm
+.Nm ether
 netgraph node type allows Ethernet interfaces to interact with
 the
 .Xr netgraph 4
 networking subsystem.
 Once the
 .Nm
-module is loaded in the kernel, a node is automatically created
+module is loaded into the kernel, a node is automatically created
 for each Ethernet interface in the system.
 Each node will attempt to name itself with the same name
 as the associated interface.
 All
-.Nm
+.Nm ether
 nodes are persistent for as long as the interface itself exists.
 .Pp
 Three hooks are supported:
-.Dv lower ,
-.Dv upper ,
+.Va lower , upper ,
 and
-.Dv orphans .
+.Va orphans .
 The hook name
-.Dv divert
+.Va divert
 may be used as an alias for
-.Dv lower ,
+.Va lower ,
 and is provided for backward compatibility.
-In reality the two names represent the same hook.
+In reality, the two names represent the same hook.
 .Pp
 The
-.Dv lower
+.Va lower
 hook is a connection to the raw Ethernet device.
-When connected, all incoming packets are diverted out this hook.
+When connected, all incoming packets are forwarded to this hook,
+instead of being passed to the kernel for upper layer processing.
 Writing to this hook results in a raw Ethernet frame being transmitted
 by the device.
 Normal outgoing packets are not affected by
-.Dv lower
+.Va lower
 being connected.
 .Pp
 The
-.Dv upper
+.Va upper
 hook is a connection to the upper protocol layers.
-When connected, all outgoing packets are diverted out this hook.
+When connected, all outgoing packets are forwarded to this hook,
+instead of being transmitted by the device.
 Writing to this hook results in a raw Ethernet frame being received by
 the kernel just as if it had come in over the wire.
 Normal incoming packets are not affected by
-.Dv upper
+.Va upper
 being connected.
 .Pp
 The
-.Dv orphans
+.Va orphans
 hook is equivalent to
-.Dv lower ,
+.Va lower ,
 except that only unrecognized packets (that would otherwise be discarded)
 are written to the hook, and normal incoming traffic is unaffected.
 At most one of
-.Dv orphans
+.Va orphans
 and
-.Dv lower
+.Va lower
 may be connected at any time.
 .Pp
 In all cases, frames are raw Ethernet frames with the standard
 14 byte Ethernet header (but no checksum).
 .Pp
 When no hooks are connected,
-.Dv upper
+.Va upper
 and
-.Dv lower
+.Va lower
 are in effect connected together,
 so that packets flow normally upwards and downwards.
 .Sh HOOKS
 This node type supports the following hooks:
-.Pp
-.Bl -tag -width orphans
-.It Dv lower
+.Bl -tag -width ".Va orphans"
+.It Va lower
 Connection to the lower device link layer.
-.It Dv upper
+.It Va upper
 Connection to the upper protocol layers.
-.It Dv orphans
+.It Va orphans
 Like
-.Dv lower ,
+.Va lower ,
 but only receives unrecognized packets.
 .El
 .Sh CONTROL MESSAGES
 This node type supports the generic control messages, plus the following:
-.Bl -tag -width foo
-.It Dv NGM_ETHER_GET_IFNAME
-Returns the name of the associated interface as a NUL-terminated ASCII string.
+.Bl -tag -width indent
+.It Dv NGM_ETHER_GET_IFNAME Pq Li getifname
+Returns the name of the associated interface as a
+.Dv NUL Ns -terminated
+.Tn ASCII
+string.
 Normally this is the same as the name of the node.
-.It Dv NGM_ETHER_GET_IFINDEX
+.It Dv NGM_ETHER_GET_IFINDEX Pq Li getifindex
 Returns the global index of the associated interface as a 32 bit integer.
-.It Dv NGM_ETHER_GET_ENADDR
+.It Dv NGM_ETHER_GET_ENADDR Pq Li getenaddr
 Returns the device's unique six byte Ethernet address.
-.It Dv NGM_ETHER_SET_ENADDR
+.It Dv NGM_ETHER_SET_ENADDR Pq Li setenaddr
 Sets the device's unique six byte Ethernet address.
 This control message is equivalent to using the
 .Dv SIOCSIFLLADDR
 .Xr ioctl 2
 system call.
-.It Dv NGM_ETHER_SET_PROMISC
+.It Dv NGM_ETHER_SET_PROMISC Pq Li setpromisc
 Enable or disable promiscuous mode.
 This message includes a single 32 bit integer flag that enables or
 disables promiscuous mode on the interface.
-.It Dv NGM_ETHER_GET_PROMISC
+Any non-zero value enables promiscuous mode.
+.It Dv NGM_ETHER_GET_PROMISC Pq Li getpromisc
 Get the current value of the node's promiscuous flag.
 The returned value is always either one or zero.
 Note that this flag reflects the node's own promiscuous setting
 and does not necessarily reflect the promiscuous state of the actual
 interface, which can be affected by other means (e.g.,
 .Xr bpf 4 ) .
-.It Dv NGM_ETHER_SET_AUTOSRC
+.It Dv NGM_ETHER_SET_AUTOSRC Pq Li setautosrc
 Sets the automatic source address override flag.
 This message includes a single 32 bit integer flag that causes
 all outgoing packets to have their source Ethernet
@@ -160,38 +164,41 @@ address field overwritten with the device's unique Ethernet address.
 If this flag is set to zero, the source address in outgoing packets
 is not modified.
 The default setting for this flag is enabled.
-.It Dv NGM_ETHER_GET_AUTOSRC
+.It Dv NGM_ETHER_GET_AUTOSRC Pq Li getautosrc
 Get the current value of the node's source address override flag.
 The returned value is always either one or zero.
 .El
 .Sh SHUTDOWN
-This node is persistent for as long as the interface exists.
-Upon receipt of a
+This node is persistent for as long as the corresponding interface exists.
+Upon receipt of the
 .Dv NGM_SHUTDOWN
 control message, all hooks are disconnected, promiscuous mode is disabled,
-and the source address override flag is reenabled,
+and the source address override flag is re-enabled,
 but the node is not removed.
-If the interface itself is detached (e.g., because of PCCARD removal), the
+If the interface itself is detached (e.g., because of PC Card removal), the
 node disappears as well.
 .Sh EXAMPLES
 This command dumps all unrecognized packets received by the
-.Dv fxp0
-interface to standard output decoded in hex and ASCII:
-.Bd -literal -offset indent
-nghook -a fxp0: orphans
-.Ed
+.Dq Li fxp0
+interface to standard output decoded in hex and
+.Tn ASCII :
+.Pp
+.Dl "nghook -a fxp0: orphans"
 .Pp
 This command sends the contents of
-.Dv foo.pkt
+.Pa sample.pkt
 out the interface
-.Dv fxp0 :
-.Bd -literal -offset indent
-cat foo.pkt | nghook fxp0: orphans
-.Ed
+.Dq Li fxp0 :
+.Pp
+.Dl "cat sample.pkt | nghook fxp0: orphans"
 .Pp
 These commands insert an
 .Xr ng_tee 4
-node between the lower and upper protocol layers, which can be used for
+node between the
+.Va lower
+and
+.Va upper
+protocol layers, which can be used for
 tracing packet flow, statistics, etc.:
 .Bd -literal -offset indent
 ngctl mkpeer fxp0: tee lower right
@@ -199,16 +206,16 @@ ngctl connect fxp0: lower upper left
 .Ed
 .Sh BUGS
 The automatic KLD module loading mechanism that works for most
-other netgraph node types does not work for the
-.Nm
+other Netgraph node types does not work for the
+.Nm ether
 node type,
 because
-.Nm
+.Nm ether
 nodes are not created on demand; instead, they are created when
 Ethernet interfaces are attached or when the KLD is first loaded.
 Therefore, if the KLD is not statically compiled into the kernel,
 it is necessary to load the KLD manually in order to bring the
-.Nm
+.Nm ether
 nodes into existence.
 .Sh SEE ALSO
 .Xr arp 4 ,