1.\" $NetBSD: m_tag.9,v 1.5 2010/12/02 12:54:13 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 78The 79.Nm 80interface is used to 81.Dq tag 82mbufs. 83.\" XXX PACKET_TAG_* 84.\" ------------------------------------------------------------ 85.Sh FUNCTIONS 86.Bl -tag -width compact 87.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 88.It Fn m_tag_get "type" "len" "wait" 89Allocate an mbuf tag. 90.Fa type 91is one of the 92.Dv PACKET_TAG_ 93macros. 94.Fa len 95is the size of the data associated with the tag, in bytes. 96.Fa wait 97is either 98.Dv M_WAITOK 99or 100.Dv M_NOWAIT . 101.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 102.It Fn m_tag_free "t" 103Free the mbuf tag 104.Fa t . 105.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 106.It Fn m_tag_prepend "m" "t" 107Prepend the mbuf tag 108.Fa t 109to the mbuf 110.Fa m . 111.Fa t 112will become the first tag of the mbuf 113.Fa m . 114When 115.Fa m 116is freed, 117.Fa t 118will also be freed. 119.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 120.It Fn m_tag_unlink "m" "t" 121Unlink the mbuf tag 122.Fa t 123from the mbuf 124.Fa m . 125.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 126.It Fn m_tag_delete "m" "t" 127The same as 128.Fn m_tag_unlink 129followed by 130.Fn m_tag_free . 131.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 132.It Fn m_tag_delete_chain "m" "t" 133Unlink and free mbuf tags beginning with the mbuf tag 134.Fa t 135from the mbuf 136.Fa m . 137If 138.Fa t 139is 140.Dv NULL , 141.Fn m_tag_delete_chain 142unlinks and frees all mbuf tags associated with the mbuf 143.Fa m . 144.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 145.It Fn m_tag_delete_nonpersistent "m" 146Unlink and free all non persistent tags associated with the mbuf 147.Fa m . 148.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 149.It Fn m_tag_find "m" "type" "t" 150Find an mbuf tag with type 151.Fa type 152after the mbuf tag 153.Fa t 154in the tag chain associated with the mbuf 155.Fa m . 156If 157.Fa t 158is 159.Dv NULL , 160search from the first mbuf tag. 161If an mbuf tag is found, return a pointer to it. 162Otherwise return 163.Dv NULL . 164.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 165.It Fn m_tag_copy "t" 166Copy an mbuf tag 167.Fa t . 168Return a new mbuf tag on success. 169Otherwise return 170.Dv NULL . 171.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 172.It Fn m_tag_copy_chain "to" "from" 173Copy all mbuf tags associated with the mbuf 174.Fa from 175to the mbuf 176.Fa to . 177If 178.Fa to 179already has any mbuf tags, they will be unlinked and freed beforehand. 180Return 1 on success. 181Otherwise return 0. 182.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 183.It Fn m_tag_init "m" 184Initialize mbuf tag chain of the mbuf 185.Fa m . 186.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 187.It Fn m_tag_first "m" 188Return the first mbuf tag associated with the mbuf 189.Fa m . 190Return 191.Dv NULL 192if no mbuf tags are found. 193.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 194.It Fn m_tag_next "m" "t" 195Return the next mbuf tag after 196.Fa t 197associated with the mbuf 198.Fa m . 199Return 200.Dv NULL 201if 202.Fa t 203is the last tag in the chain. 204.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 205.El 206.\" ------------------------------------------------------------ 207.Sh CODE REFERENCES 208The mbuf tagging interfaces are implemented within the file 209.Pa sys/kern/uipc_mbuf2.c . 210.Pp 211The 212.Dv PACKET_TAG_ 213macros are defined in the file 214.Pa sys/sys/mbuf.h . 215.Sh SEE ALSO 216.Xr intro 9 , 217.Xr malloc 9 , 218.Xr mbuf 9 219.\" ------------------------------------------------------------ 220.Sh BUGS 221The semantics of the term "persistent tag" are vague. 222