share/man/man9/m_tag.9

   1 .\"     $NetBSD: m_tag.9,v 1.3 2004/09/07 13:55:22 wiz Exp $
   2 .\"
   3 .\" Copyright (c)2004 YAMAMOTO Takashi,
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" ------------------------------------------------------------
  28 .Dd September 7, 2004
  29 .Dt M_TAG 9
  30 .Os
  31 .Sh NAME
  32 .Nm m_tag ,
  33 .Nm m_tag_get ,
  34 .Nm m_tag_free ,
  35 .Nm m_tag_prepend ,
  36 .Nm m_tag_unlink ,
  37 .Nm m_tag_delete ,
  38 .Nm m_tag_delete_chain ,
  39 .Nm m_tag_delete_nonpersistent ,
  40 .Nm m_tag_find ,
  41 .Nm m_tag_copy ,
  42 .Nm m_tag_copy_chain ,
  43 .Nm m_tag_init ,
  44 .Nm m_tag_first ,
  45 .Nm m_tag_next
  46 .Nd mbuf tagging interfaces
  47 .\" ------------------------------------------------------------
  48 .Sh SYNOPSIS
  49 .In sys/mbuf.h
  50 .Ft struct m_tag *
  51 .Fn m_tag_get "int type" "int len" "int wait"
  52 .Ft void
  53 .Fn m_tag_free "struct m_tag *t"
  54 .Ft void
  55 .Fn m_tag_prepend "struct mbuf *m" "struct m_tag *t"
  56 .Ft void
  57 .Fn m_tag_unlink "struct mbuf *m" "struct m_tag *t"
  58 .Ft void
  59 .Fn m_tag_delete "struct mbuf *m" "struct m_tag *t"
  60 .Ft void
  61 .Fn m_tag_delete_chain "struct mbuf *m" "struct m_tag *t"
  62 .Ft void
  63 .Fn m_tag_delete_nonpersistent "struct mbuf *"
  64 .Ft struct m_tag *
  65 .Fn m_tag_find "struct mbuf *m" "int type" "struct m_tag *t"
  66 .Ft struct m_tag *
  67 .Fn m_tag_copy "struct m_tag *m"
  68 .Ft int
  69 .Fn m_tag_copy_chain "struct mbuf *to" "struct mbuf *from"
  70 .Ft void
  71 .Fn m_tag_init "struct mbuf *m"
  72 .Ft struct m_tag *
  73 .Fn m_tag_first "struct mbuf *m"
  74 .Ft struct m_tag *
  75 .Fn m_tag_next "struct mbuf *m" "struct m_tag *t"
  76 .\" ------------------------------------------------------------
  77 .Sh DESCRIPTION
  78 The
  79 .Nm
  80 interface is used to
  81 .Dq tag
  82 mbufs.
  83 .\" XXX PACKET_TAG_*
  84 .\" ------------------------------------------------------------
  85 .Sh FUNCTIONS
  86 .Bl -tag -width compact
  87 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  88 .It Fn m_tag_get "type" "len" "wait"
  89 Allocate an mbuf tag.
  90 .Fa type
  91 is one of the
  92 .Dv PACKET_TAG_
  93 macros.
  94 .Fa len
  95 is the size of the data associated with the tag, in bytes.
  96 .Fa wait
  97 is either
  98 .Dv M_WAITOK
  99 or
 100 .Dv M_NOWAIT .
 101 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 102 .It Fn m_tag_free "t"
 103 Free the mbuf tag
 104 .Fa t .
 105 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 106 .It Fn m_tag_prepend "m" "t"
 107 Prepend the mbuf tag
 108 .Fa t
 109 to the mbuf
 110 .Fa m .
 111 .Fa t
 112 will become the first tag of the mbuf
 113 .Fa m .
 114 When
 115 .Fa m
 116 is freed,
 117 .Fa t
 118 will also be freed.
 119 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 120 .It Fn m_tag_unlink "m" "t"
 121 Unlink the mbuf tag
 122 .Fa t
 123 from the mbuf
 124 .Fa m .
 125 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 126 .It Fn m_tag_delete "m" "t"
 127 The same as
 128 .Fn m_tag_unlink
 129 followed by
 130 .Fn m_tag_free .
 131 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 132 .It Fn m_tag_delete_chain "m" "t"
 133 Unlink and free mbuf tags beginning with the mbuf tag
 134 .Fa t
 135 from the mbuf
 136 .Fa m .
 137 If
 138 .Fa t
 139 is
 140 .Dv NULL ,
 141 .Fn m_tag_delete_chain
 142 unlinks and frees all mbuf tags associated with the mbuf
 143 .Fa m .
 144 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 145 .It Fn m_tag_delete_nonpersistent "m"
 146 Unlink and free all non persistent tags associated with the mbuf
 147 .Fa m .
 148 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 149 .It Fn m_tag_find "m" "type" "t"
 150 Find an mbuf tag with type
 151 .Fa type
 152 after the mbuf tag
 153 .Fa t
 154 in the tag chain associated with the mbuf
 155 .Fa m .
 156 If
 157 .Fa t
 158 is
 159 .Dv NULL ,
 160 search from the first mbuf tag.
 161 If an mbuf tag is found, return a pointer to it.
 162 Otherwise return
 163 .Dv NULL .
 164 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 165 .It Fn m_tag_copy "t"
 166 Copy an mbuf tag
 167 .Fa t .
 168 Return a new mbuf tag on success.
 169 Otherwise return
 170 .Dv NULL .
 171 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 172 .It Fn m_tag_copy_chain "to" "from"
 173 Copy all mbuf tags associated with the mbuf
 174 .Fa from
 175 to the mbuf
 176 .Fa to .
 177 If
 178 .Fa to
 179 already has any mbuf tags, they will be unlinked and freed beforehand.
 180 Return 1 on success.
 181 Otherwise return 0.
 182 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 183 .It Fn m_tag_init "m"
 184 Initialize mbuf tag chain of the mbuf
 185 .Fa m .
 186 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 187 .It Fn m_tag_first "m"
 188 Return the first mbuf tag associated with the mbuf
 189 .Fa m .
 190 Return
 191 .Dv NULL
 192 if no mbuf tags are found.
 193 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 194 .It Fn m_tag_next "m" "t"
 195 Return the next mbuf tag after
 196 .Fa t
 197 associated with the mbuf
 198 .Fa m .
 199 Return
 200 .Dv NULL
 201 if
 202 .Fa t
 203 is the last tag in the chain.
 204 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 205 .El
 206 .\" ------------------------------------------------------------
 207 .Sh CODE REFERENCES
 208 This section describes places within the
 209 .Nx
 210 source tree where actual code implementing the mbuf tagging interfaces
 211 can be found.
 212 All pathnames are relative to
 213 .Pa /usr/src .
 214 .Pp
 215 The mbuf tagging interfaces are implemented within the file
 216 .Pa sys/kern/uipc_mbuf2.c .
 217 .Pp
 218 The
 219 .Dv PACKET_TAG_
 220 macros are defined in the file
 221 .Pa sys/sys/mbuf.h .
 222 .Sh SEE ALSO
 223 .Xr intro 9 ,
 224 .Xr malloc 9 ,
 225 .Xr mbuf 9
 226 .\" ------------------------------------------------------------
 227 .Sh BUGS
 228 The semantics of the term "persistent tag" are vague.