git: 854e1fd69218 - main - mbuf.9: Document mtodo

From: John Baldwin <jhb_at_FreeBSD.org>
Date: Thu, 28 Dec 2023 19:18:16 UTC
The branch main has been updated by jhb:

URL: https://cgit.FreeBSD.org/src/commit/?id=854e1fd692185749fea092b1431efd4a8e09c2eb

commit 854e1fd692185749fea092b1431efd4a8e09c2eb
Author:     John Baldwin <jhb@FreeBSD.org>
AuthorDate: 2023-12-28 19:17:22 +0000
Commit:     John Baldwin <jhb@FreeBSD.org>
CommitDate: 2023-12-28 19:17:45 +0000

    mbuf.9: Document mtodo
    
    mtodo() accepts an mbuf and offset and returns a void * pointer to the
    requested offset into the mbuf's associated data.  Similar to mtod(),
    no bounds checking is performed.
    
    Reviewed by:    imp, markj
    Sponsored by:   Chelsio Communications
    Differential Revision:  https://reviews.freebsd.org/D43215
---
 share/man/man9/Makefile |  1 +
 share/man/man9/mbuf.9   | 24 +++++++++++++++++++-----
 2 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 81de035defb9..6bc814334f5d 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1516,6 +1516,7 @@ MLINKS+=\
 	mbuf.9 m_pullup.9 \
 	mbuf.9 m_split.9 \
 	mbuf.9 mtod.9 \
+	mbuf.9 mtodo.9 \
 	mbuf.9 M_TRAILINGSPACE.9 \
 	mbuf.9 m_unshare.9 \
 	mbuf.9 M_WRITABLE.9
diff --git a/share/man/man9/mbuf.9 b/share/man/man9/mbuf.9
index 7c69ef86f63f..0b03d697b8bf 100644
--- a/share/man/man9/mbuf.9
+++ b/share/man/man9/mbuf.9
@@ -22,7 +22,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd August 8, 2021
+.Dd December 28, 2023
 .Dt MBUF 9
 .Os
 .\"
@@ -52,7 +52,10 @@
 .Fc
 .\"
 .Ss Mbuf utility macros
+.Ft type
 .Fn mtod "struct mbuf *mbuf" "type"
+.Ft void *
+.Fn mtodo "struct mbuf *mbuf" "offset"
 .Fn M_ALIGN "struct mbuf *mbuf" "u_int len"
 .Fn MH_ALIGN "struct mbuf *mbuf" "u_int len"
 .Ft int
@@ -394,6 +397,14 @@ It is advisable to ensure that there is enough contiguous data in
 See
 .Fn m_pullup
 for details.
+.It Fn mtodo mbuf offset
+Return a data pointer at an offset (in bytes) into the data attached to
+.Fa mbuf .
+Returns a
+.Ft void *
+pointer .
+.Sy Note :
+The caller must ensure that the offset is in bounds of the attached data.
 .It Fn MGET mbuf how type
 Allocate an
 .Vt mbuf
@@ -773,7 +784,9 @@ in the
 are contiguous and lay in the data area of
 .Fa mbuf ,
 so they are accessible with
-.Fn mtod mbuf type .
+.Fn mtod
+or
+.Fn mtodo .
 .Fa len
 must be smaller than, or equal to, the size of an
 .Vt mbuf cluster .
@@ -787,12 +800,13 @@ to the data contained in the returned mbuf is stored in
 If
 .Fa offsetp
 is NULL, the region may be accessed using
-.Fn mtod mbuf type .
+.Fn mtod mbuf type
+or
+.Fn mtodo mbuf 0 .
 If
 .Fa offsetp
 is non-NULL, the region may be accessed using
-.Fn mtod mbuf uint8_t
-+ *offsetp.
+.Fn mtodo mbuf *offsetp .
 The region of the mbuf chain between its beginning and
 .Fa offset
 is not modified, therefore it is safe to hold pointers to data within