[src/trunk]: src/share/man/man9 document mbuf tagging interfaces.

[yamt <yamt%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/503d8d3acff7
branches:  trunk
changeset: 569799:503d8d3acff7
user:      yamt <yamt%NetBSD.org@localhost>
date:      Mon Sep 06 18:23:31 2004 +0000

description:
document mbuf tagging interfaces.

diffstat:

 share/man/man9/Makefile |    4 +-
 share/man/man9/m_tag.9  |  220 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 222 insertions(+), 2 deletions(-)

diffs (242 lines):

diff -r cf412f396c02 -r 503d8d3acff7 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Mon Sep 06 18:12:54 2004 +0000
+++ b/share/man/man9/Makefile   Mon Sep 06 18:23:31 2004 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.164 2004/09/06 09:45:27 yamt Exp $
+#       $NetBSD: Makefile,v 1.165 2004/09/06 18:23:31 yamt Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -21,7 +21,7 @@
        kfilter_register.9 knote.9 \
        kprintf.9 kthread.9 linedisc.9 lock.9 log.9 ltsleep.9 \
        malloc.9 mbuf.9 mca.9 memcmp.9 memcpy.9 memmove.9 memset.9 \
-       microtime.9 mstohz.9 namecache.9 namei.9 need_resched.9 \
+       microtime.9 mstohz.9 m_tag.9 namecache.9 namei.9 need_resched.9 \
        opencrypto.9 \
        panic.9 pci.9 pci_configure_bus.9 pci_intr.9 pckbport.9 \
        pcmcia.9 pfil.9 physio.9 pmap.9 pmatch.9 pmc.9 \
diff -r cf412f396c02 -r 503d8d3acff7 share/man/man9/m_tag.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/m_tag.9    Mon Sep 06 18:23:31 2004 +0000
@@ -0,0 +1,220 @@
+.\"     $NetBSD: m_tag.9,v 1.1 2004/09/06 18:23:31 yamt Exp $
+.\"
+.\" Copyright (c)2004 YAMAMOTO Takashi,
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" ------------------------------------------------------------
+.Dd September 7, 2004
+.Dt M_TAG 9
+.Os
+.Sh NAME
+.Nm m_tag ,
+.Nm m_tag_get ,
+.Nm m_tag_free ,
+.Nm m_tag_prepend ,
+.Nm m_tag_unlink ,
+.Nm m_tag_delete ,
+.Nm m_tag_delete_chain ,
+.Nm m_tag_delete_nonpersistent ,
+.Nm m_tag_find ,
+.Nm m_tag_copy ,
+.Nm m_tag_copy_chain ,
+.Nm m_tag_init ,
+.Nm m_tag_first ,
+.Nm m_tag_next
+.Nd mbuf tagging interfaces
+.\" ------------------------------------------------------------
+.Sh SYNOPSIS
+.In sys/mbuf.h
+.Ft struct m_tag *
+.Fn m_tag_get "int type" "int len" "int wait"
+.Ft void
+.Fn m_tag_free "struct m_tag *t"
+.Ft void
+.Fn m_tag_prepend "struct mbuf *m" "struct m_tag *t"
+.Ft void
+.Fn m_tag_unlink "struct mbuf *m" "struct m_tag *t"
+.Ft void
+.Fn m_tag_delete "struct mbuf *m" "struct m_tag *t"
+.Ft void
+.Fn m_tag_delete_chain "struct mbuf *m" "struct m_tag *t"
+.Ft void
+.Fn m_tag_delete_nonpersistent "struct mbuf *"
+.Ft struct m_tag *
+.Fn m_tag_find "struct mbuf *m" "int type" "struct m_tag *t"
+.Ft struct m_tag *
+.Fn m_tag_copy "struct m_tag *m"
+.Ft int
+.Fn m_tag_copy_chain "struct mbuf *to" "struct mbuf *from"
+.Ft void
+.Fn m_tag_init "struct mbuf *m"
+.Ft struct m_tag *
+.Fn m_tag_first "struct mbuf *m"
+.Ft struct m_tag *
+.Fn m_tag_next "struct mbuf *m" "struct m_tag *t"
+.\" ------------------------------------------------------------
+.Sh DESCRIPTION
+The
+.Nm
+interface is used to "tag" mbufs.
+.\" XXX PACKET_TAG_*
+.\" ------------------------------------------------------------
+.Sh FUNCTIONS
+.Bl -tag -width compact
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn m_tag_get "type" "len" "wait"
+Allocate a mbuf tag.
+.Fa type
+is one of the
+.Dv PACKET_TAG_
+macros.
+.Fa len
+is size of data associated to the tag, in bytes.
+.Fa wait
+is either
+.Dv M_WAITOK
+or
+.Dv M_NOWAIT .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn m_tag_free "t"
+Free the mbuf tag
+.Fa t .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn m_tag_prepend "m" "t"
+Prepend the mbuf tag
+.Fa t
+to the mbuf
+.Fa m .
+.Fa t
+will become the first tag of the
+.Fa m .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn m_tag_unlink "m" "t"
+Unlink the mbuf tag
+.Fa t
+from the mbuf
+.Fa m .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn m_tag_delete "m" "t"
+The same as
+.Fn m_tag_unlink
+followed by
+.Fn m_tag_free .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn m_tag_delete_chain "m" "t"
+Unlink and free mbuf tags beginning from the mbuf tag
+.Fa t
+from the mbuf
+.Fa m .
+If
+.Fa t
+is
+.Dv NULL ,
+.Fn m_tag_delete_chain
+unlinks and frees all mbuf tags associated to the mbuf
+.Fa m .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn m_tag_delete_nonpersistent "m"
+Unlink and free all non persistent tags associated to the mbuf
+.Fa m .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn m_tag_find "m" "type" "t"
+Find a mbuf tag with type
+.Fa type
+after the mbuf tag
+.Fa t
+in the tag chain associated to the mbuf
+.Fa m .
+If
+.Fa t
+is
+.Dv NULL ,
+search from the first mbuf tag.
+If a mbuf tag is found, return a pointer to it.
+Otherwise return
+.Dv NULL .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn m_tag_copy "t"
+Copy a mbuf tag
+Fa t .
+Return a new mbuf tag on success.
+Otherwise return
+.Dv NULL .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn m_tag_copy_chain "to" "from"
+Copy all mbuf tags associated to the mbuf
+.Fa from
+to the mbuf
+.Fa to .
+If
+.Fa to
+already has any mbuf tags, they will be unlinked and freed beforehand.
+Return 1 on success.
+Otherwise return 0.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn m_tag_init "m"
+Initialize mbuf tag chain of the mbuf
+.Fa m .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn m_tag_first "m"
+Return the first mbuf tag associated to the mbuf
+.Fa m .
+Return
+.Dv NULL
+if no mbuf tags are found.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn m_tag_next "m" "t"
+Return the next mbuf tag after
+.Fa t
+associated to the mbuf
+.Fa m .
+Return
+.Dv NULL
+if
+.Fa t
+is the last tag in the chain.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.El
+.\" ------------------------------------------------------------
+.Sh CODE REFERENCES
+This section describes places within the
+.Nx
+source tree where actual code implementing the mbuf tagging interfaces
+can be found.
+All pathnames are relative to
+.Pa /usr/src .
+.Pp
+The mbuf tagging interfaces are implemented within the file
+.Pa sys/kern/uipc_mbuf2.c .
+.Pp
+.Dv PACKET_TAG_
+macros are defined in the file
+.Pa sys/sys/mbuf.h .
+.Sh SEE ALSO
+.Xr intro 9 ,
+.Xr mbuf 9 ,
+.Xr malloc 9
+.\" ------------------------------------------------------------
+.Sh BUGS
+the semantics of the term "persisitent tag" is vague.