Add more markup to the mbuf(9) manpage. This includes:

- tagging plaintext "mbuf", "mbuf cluster", and "mbuf chain"
  with .Vt (variable type) since all of them are ways of managing
  data, i.e., they can be seen as data types;

- using .Vt/.Va instead of .Li (literal) where appropriate;

- tagging plaintext words that actually refer to function arguments
  with .Fa.

Suggested by:	ru

1 files changed, 239 insertions, 92 deletions

diff --git a/share/man/man9/mbuf.9 b/share/man/man9/mbuf.9
index f9822b6..48d3794 100644
--- a/share/man/man9/mbuf.9
+++ b/share/man/man9/mbuf.9
@@ -121,30 +121,49 @@
 .Fn m_split "struct mbuf *mbuf" "int len" "int how"
 .\"
 .Sh DESCRIPTION
-An mbuf is a basic unit of memory management in the kernel IPC subsystem.
-Network packets and socket buffers are stored in mbufs.
-A network packet may span multiple mbufs arranged into a chain
+An
+.Vt mbuf
+is a basic unit of memory management in the kernel IPC subsystem.
+Network packets and socket buffers are stored in
+.Vt mbufs .
+A network packet may span multiple
+.Vt mbufs
+arranged into a
+.Vt mbuf chain
 (linked list),
 which allows adding or trimming
 network headers with little overhead.
 .Pp
-While a developer should not bother with mbuf internals without serious
+While a developer should not bother with
+.Vt mbuf
+internals without serious
 reason in order to avoid incompatibilities with future changes, it
-is useful to understand the mbuf's general structure.
+is useful to understand the general structure of an
+.Vt mbuf .
 .Pp
-An mbuf consists of a variable-sized header and a small internal
+An
+.Vt mbuf
+consists of a variable-sized header and a small internal
 buffer for data.
-The mbuf's total size,
+The total size of an
+.Vt mbuf ,
 .Dv MSIZE ,
 is a machine-dependent constant defined in
 .Pa machine/param.h .
-The mbuf header includes:
+The
+.Vt mbuf
+header includes:
 .Pp
 .Bl -tag -width "m_nextpkt" -compact -offset indent
 .It Va m_next
-a pointer to the next buffer in the chain
+a pointer to the next
+.Vt mbuf
+in the
+.Vt mbuf chain
 .It Va m_nextpkt
-a pointer to the next chain in the queue
+a pointer to the next
+.Vt mbuf chain
+in the queue
 .It Va m_data
 a pointer to the data
 .It Va m_len
@@ -152,10 +171,14 @@ the length of the data
 .It Va m_type
 the type of data
 .It Va m_flags
-the mbuf flags
+the
+.Vt mbuf
+flags
 .El
 .Pp
-The mbuf flag bits are defined as follows:
+The
+.Vt mbuf
+flag bits are defined as follows:
 .Bd -literal
 /* mbuf flags */
 #define	M_EXT		0x0001	/* has associated external storage */
@@ -176,7 +199,9 @@ The mbuf flag bits are defined as follows:
 #define	M_LASTFRAG	0x2000	/* packet is last fragment */
 .Ed
 .Pp
-The available mbuf types are defined as follows:
+The available
+.Vt mbuf
+types are defined as follows:
 .Bd -literal
 /* mbuf types */
 #define	MT_FREE		0	/* should be on free list */
@@ -191,32 +216,45 @@ The available mbuf types are defined as follows:
 If the
 .Dv M_PKTHDR
 flag is set, a
-.Li struct pkthdr m_pkthdr
-is added to the mbuf header.
+.Vt struct pkthdr Va m_pkthdr
+is added to the
+.Vt mbuf
+header.
 It contains a pointer to the interface
 the packet has been received from
-.Pq Fa struct ifnet *rcvif ,
+.Pq Vt struct ifnet Va *rcvif ,
 and the total packet length
-.Pq Fa int len .
+.Pq Vt int Va len .
 .Pp
-If small enough, data is stored in the mbuf's internal data buffer.
-If the data is sufficiently large, another mbuf may be added to the chain,
-or external storage may be associated with the mbuf.
+If small enough, data is stored in the internal data buffer of an
+.Vt mbuf .
+If the data is sufficiently large, another
+.Vt mbuf
+may be added to the
+.Vt mbuf chain ,
+or external storage may be associated with the
+.Vt mbuf .
 .Dv MHLEN
-bytes of data can fit into an mbuf with the
+bytes of data can fit into an
+.Vt mbuf
+with the
 .Dv M_PKTHDR
 flag set,
 .Dv MLEN
 bytes can otherwise.
 .Pp
-If external storage is being associated with an mbuf, the
+If external storage is being associated with an
+.Vt mbuf ,
+the
 .Va m_ext
 header is added at the cost of losing the internal data buffer.
 It includes a pointer to external storage, the size of the storage,
 a pointer to a function used for freeing the storage,
 a pointer to an optional argument that can be passed to the function,
 and a pointer to a reference counter.
-An mbuf using external storage has the
+An
+.Vt mbuf
+using external storage has the
 .Dv M_EXT
 flag set.
 .Pp
@@ -227,7 +265,9 @@ buffer,
 The allocation and management of the reference counter is handled by the
 subsystem.
 The developer can check whether the reference count for the
-given mbuf's external storage is greater than 1 with the
+external storage of a given
+.Vt mbuf
+is greater than 1 with the
 .Dv MEXT_IS_REF
 macro.
 Similarly, the developer can directly add and remove references,
@@ -238,23 +278,29 @@ and
 macros.
 .Pp
 The system also supplies a default type of external storage buffer called an
-.Dq mbuf cluster .
-Mbuf clusters can be allocated and configured with the use of the
+.Vt mbuf cluster .
+.Vt Mbuf clusters
+can be allocated and configured with the use of the
 .Dv MCLGET
 macro.
-Each cluster is
+Each
+.Vt mbuf cluster
+is
 .Dv MCLBYTES
 in size, where MCLBYTES is a machine-dependent constant.
 The system defines an advisory macro
 .Dv MINCLSIZE ,
-which is the smallest amount of data to put into a cluster.
+which is the smallest amount of data to put into an
+.Vt mbuf cluster .
 It's equal to the sum of
 .Dv MLEN
 and
 .Dv MHLEN .
-It is typically preferable to store data into an mbuf's data region, if size
-permits, as opposed to allocating a separate mbuf cluster to hold the same
-data.
+It is typically preferable to store data into the data region of an
+.Vt mbuf ,
+if size permits, as opposed to allocating a separate
+.Vt mbuf cluster
+to hold the same data.
 .\"
 .Ss Macros and Functions
 There are numerous predefined macros and functions that provide the
@@ -262,17 +308,25 @@ developer with common utilities.
 .\"
 .Bl -ohang -offset indent
 .It Fn mtod mbuf type
-Convert an mbuf pointer to a data pointer.
-The macro expands to the data pointer cast to the pointer of the specified type.
+Convert an
+.Fa mbuf
+pointer to a data pointer.
+The macro expands to the data pointer cast to the pointer of the specified
+.Fa type .
 .Sy Note :
-It is advisable to ensure that there is enough contiguous data in the mbuf.
+It is advisable to ensure that there is enough contiguous data in
+.Fa mbuf .
 See
 .Fn m_pullup
 for details.
 .It Fn MGET mbuf how type
-Allocate an mbuf and initialize it to contain internal data.
+Allocate an
+.Vt mbuf
+and initialize it to contain internal data.
 .Fa mbuf
-will point to the allocated mbuf on success, or be set to
+will point to the allocated
+.Vt mbuf
+on success, or be set to
 .Dv NULL
 on failure.
 The
@@ -292,11 +346,15 @@ kern.ipc.mbuf_wait
 .Xr ( sysctl 8
 tunable)
 number of ticks.
-A number of other mbuf-related
-functions and macros have the same argument because they may
-at some point need to allocate new mbufs.
+A number of other functions and macros related to
+.Vt mbufs
+have the same argument because they may
+at some point need to allocate new
+.Vt mbufs .
 .Pp
-Programmers should be careful not to confuse the mbuf allocation flag
+Programmers should be careful not to confuse the
+.Vt mbuf
+allocation flag
 .Dv M_DONTWAIT
 with the
 .Xr malloc 9
@@ -304,37 +362,50 @@ allocation flag,
 .Dv M_NOWAIT .
 They are not the same.
 .It Fn MGETHDR mbuf how type
-Allocate an mbuf and initialize it to contain a packet header
+Allocate an
+.Vt mbuf
+and initialize it to contain a packet header
 and internal data.
 See
 .Fn MGET
 for details.
 .It Fn MCLGET mbuf how
-Allocate and attach an mbuf cluster to an mbuf.
+Allocate and attach an
+.Vt mbuf cluster
+to
+.Fa mbuf .
 If the macro fails, the
 .Dv M_EXT
-flag won't be set in the mbuf.
+flag won't be set in
+.Fa mbuf .
 .It Fn M_PREPEND mbuf len how
-This macro operates on an mbuf chain.
+This macro operates on an
+.Vt mbuf chain .
 It is an optimized wrapper for
 .Fn m_prepend
 that can make use of possible empty space before data
 (e.g. left after trimming of a link-layer header).
-The new chain pointer or
+The new
+.Vt mbuf chain
+pointer or
 .Dv NULL
 is in
 .Fa mbuf
 after the call.
 .It Fn M_WRITABLE mbuf
-This macro will evaluate true if the mbuf is not marked
+This macro will evaluate true if
+.Fa mbuf
+is not marked
 .Dv M_RDONLY
-and if either the mbuf does not contain external storage or,
+and if either
+.Fa mbuf
+does not contain external storage or,
 if it does,
 then if the reference count of the storage is not greater than 1.
 The
 .Dv M_RDONLY
-flag can be set in the mbuf's
-.Va m_flags .
+flag can be set in
+.Fa mbuf->m_flags .
 This can be achieved during setup of the external storage,
 by passing the
 .Dv M_RDONLY
@@ -342,7 +413,8 @@ bit as a
 .Fa flags
 argument to the
 .Fn MEXTADD
-macro, or can be directly set in individual mbufs.
+macro, or can be directly set in individual
+.Vt mbufs .
 .El
 .Pp
 The functions are:
@@ -354,10 +426,16 @@ for non-critical paths.
 .It Fn m_getm orig len how type
 Allocate
 .Fa len
-bytes worth of mbufs and mbuf clusters if necessary and append the resulting
-allocated chain to the
-.Fa orig
-mbuf chain, if it is
+bytes worth of
+.Vt mbufs
+and
+.Vt mbuf clusters
+if necessary and append the resulting allocated
+.Vt mbuf chain
+to the
+.Vt mbuf chain
+.Fa orig ,
+if it is
 .No non- Ns Dv NULL .
 If the allocation fails at any point,
 free whatever was allocated and return
@@ -371,36 +449,55 @@ It is possible to use
 .Fn m_getm
 to either append
 .Fa len
-bytes to an existing mbuf or mbuf chain
+bytes to an existing
+.Vt mbuf
+or
+.Vt mbuf chain
 (for example, one which may be sitting in a pre-allocated ring)
-or to simply perform an all-or-nothing mbuf and mbuf cluster allocation.
+or to simply perform an all-or-nothing
+.Vt mbuf
+and
+.Vt mbuf cluster
+allocation.
 .It Fn m_gethdr how type
 A function version of
 .Fn MGETHDR
 for non-critical paths.
 .It Fn m_getclr how type
-Allocate an mbuf and zero out the data region.
+Allocate an
+.Vt mbuf
+and zero out the data region.
 .El
 .Pp
-The functions below operate on mbuf chains.
+The functions below operate on
+.Vt mbuf chains .
 .Bl -ohang -offset indent
 .It Fn m_freem mbuf
-Free an entire mbuf chain, including any external
-storage.
+Free an entire
+.Vt mbuf chain ,
+including any external storage.
 .\"
 .It Fn m_adj mbuf len
 Trim
 .Fa len
-bytes from the head of an mbuf chain if
+bytes from the head of an
+.Vt mbuf chain
+if
 .Fa len
 is positive, from the tail otherwise.
 .\"
 .It Fn m_prepend mbuf len how
-Allocate a new mbuf and prepend it to the chain, handle
+Allocate a new
+.Vt mbuf
+and prepend it to the
+.Vt mbuf chain ,
+handle
 .Dv M_PKTHDR
 properly.
 .Sy Note :
-It doesn't allocate any clusters, so
+It doesn't allocate any
+.Vt mbuf clusters ,
+so
 .Fa len
 must be less than
 .Dv MLEN
@@ -413,22 +510,32 @@ flag setting.
 .It Fn m_pullup mbuf len
 Arrange that the first
 .Fa len
-bytes of an mbuf chain are contiguous and lay in the data area of
+bytes of an
+.Vt mbuf chain
+are contiguous and lay in the data area of
 .Fa mbuf ,
 so they are accessible with
 .Fn mtod mbuf type .
-Return the new chain on success,
+Return the new
+.Vt mbuf chain
+on success,
 .Dv NULL
 on failure
-(the chain is freed in this case).
+(the
+.Vt mbuf chain
+is freed in this case).
 .Sy Note :
-It doesn't allocate any clusters, so
+It doesn't allocate any
+.Vt mbuf clusters ,
+so
 .Fa len
 must be less than
 .Dv MHLEN .
 .\"
 .It Fn m_copym mbuf offset len how
-Make a copy of an mbuf chain starting
+Make a copy of an
+.Vt mbuf chain
+starting
 .Fa offset
 bytes from the beginning, continuing for
 .Fa len
@@ -437,28 +544,38 @@ If
 .Fa len
 is
 .Dv M_COPYALL ,
-copy to the end of the mbuf chain.
+copy to the end of the
+.Vt mbuf chain .
 .Sy Note :
-The copy is read-only, because clusters are not
-copied, only their reference counts are incremented.
+The copy is read-only, because the
+.Vt mbuf clusters
+are not copied, only their reference counts are incremented.
 .\"
 .It Fn m_copypacket mbuf how
 Copy an entire packet including header, which must be present.
 This is an optimized version of the common case
 .Fn m_copym mbuf 0 M_COPYALL how .
 .Sy Note :
-the copy is read-only, because clusters are not
-copied, only their reference counts are incremented.
+the copy is read-only, because the
+.Vt mbuf clusters
+are not copied, only their reference counts are incremented.
 .\"
 .It Fn m_dup mbuf how
-Copy a packet header mbuf chain into a completely new chain, including
-copying any mbuf clusters.
+Copy a packet header
+.Vt mbuf chain
+into a completely new
+.Vt mbuf chain ,
+including copying any
+.Vt mbuf clusters .
 Use this instead of
 .Fn m_copypacket
-when you need a writable copy of an mbuf chain.
+when you need a writable copy of an
+.Vt mbuf chain .
 .\"
 .It Fn m_copydata mbuf offset len buf
-Copy data from an mbuf chain starting
+Copy data from an
+.Vt mbuf chain
+starting
 .Fa off
 bytes from the beginning, continuing for
 .Fa len
@@ -470,27 +587,45 @@ Copy
 .Fa len
 bytes from the buffer
 .Fa buf
-back into the indicated mbuf chain,
+back into the indicated
+.Vt mbuf chain ,
 starting at
 .Fa offset
-bytes from the beginning of the chain, extending the mbuf chain if necessary.
+bytes from the beginning of the
+.Vt mbuf chain ,
+extending the
+.Vt mbuf chain
+if necessary.
 .Sy Note :
-It doesn't allocate any clusters, just adds mbufs to the chain.
+It doesn't allocate any
+.Vt mbuf clusters ,
+just adds
+.Vt mbufs
+to the
+.Vt mbuf chain .
 It's safe to set
 .Fa offset
-beyond the current chain end: zeroed mbufs will be allocated to fill the
-space.
+beyond the current
+.Vt mbuf chain
+end: zeroed
+.Vt mbufs
+will be allocated to fill the space.
 .\"
 .It Fn m_length buf last
-Return the length of the mbuf chain, and optionally a pointer to the last mbuf.
+Return the length of the
+.Vt mbuf chain ,
+and optionally a pointer to the last
+.Vt mbuf .
 .\"
 .It Fn m_fixhdr buf
-Set the packet-header length to the length of the mbuf chain.
+Set the packet-header length to the length of the
+.Vt mbuf chain .
 .\"
 .It Fn m_devget buf len offset ifp copy
 Copy data from a device local memory pointed to by
 .Fa buf
-to an mbuf chain.
+to an
+.Vt mbuf chain .
 The copy is done using a specified copy routine
 .Fa copy ,
 or
@@ -505,7 +640,9 @@ Concatenate
 .Fa n
 to
 .Fa m .
-Both chains must be of the same type.
+Both
+.Vt mbuf chains
+must be of the same type.
 .Fa N
 is still valid after the function returned.
 .Sy Note :
@@ -514,13 +651,17 @@ It does not handle
 and friends.
 .\"
 .It Fn m_split mbuf len how
-Partition an mbuf chain in two pieces, returning the tail:
+Partition an
+.Vt mbuf chain
+in two pieces, returning the tail:
 all but the first
 .Fa len
 bytes.
 In case of failure, it returns
 .Dv NULL
-and attempts to restore the chain to its original state.
+and attempts to restore the
+.Vt mbuf chain
+to its original state.
 .El
 .Sh STRESS TESTING
 When running a kernel compiled with the option
@@ -529,14 +670,19 @@ the following
 .Xr sysctl 8 Ns
 -controlled options may be used to create
 various failure/extreme cases for testing of network drivers
-and other mbuf-reliant parts of the kernel.
+and other parts of the kernel that rely on
+.Vt mbufs .
 .Bl -tag -width ident
 .It Va net.inet.ip.mbuf_frag_size
 Causes
 .Fn ip_output
-to fragment outgoing mbuf chains into fragments of the specified size.
+to fragment outgoing
+.Vt mbuf chains
+into fragments of the specified size.
 Setting this variable to 1 is an excellent way to
-test the long mbuf chain handling ability of network drivers.
+test the long
+.Vt mbuf chain
+handling ability of network drivers.
 .It Va kern.ipc.m_defragrandomfailures
 Causes the function
 .Fn m_defrag
@@ -550,7 +696,8 @@ should be tested with this feature.
 See above.
 .Sh HISTORY
 .\" Please correct me if I'm wrong
-Mbufs appeared in an early version of
+.Vt Mbufs
+appeared in an early version of
 .Bx .
 Besides for being used for network packets, they were used
 to store various dynamic structures, such as routing table