1.\" $NetBSD: m_tag.9,v 1.8 2018/11/15 10:23:55 maxv 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 November 15, 2018 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_find , 40.Nm m_tag_copy , 41.Nm m_tag_copy_chain 42.Nd mbuf tagging interfaces 43.\" ------------------------------------------------------------ 44.Sh SYNOPSIS 45.In sys/mbuf.h 46.Ft struct m_tag * 47.Fn m_tag_get "int type" "int len" "int wait" 48.Ft void 49.Fn m_tag_free "struct m_tag *t" 50.Ft void 51.Fn m_tag_prepend "struct mbuf *m" "struct m_tag *t" 52.Ft void 53.Fn m_tag_unlink "struct mbuf *m" "struct m_tag *t" 54.Ft void 55.Fn m_tag_delete "struct mbuf *m" "struct m_tag *t" 56.Ft void 57.Fn m_tag_delete_chain "struct mbuf *m" 58.Ft struct m_tag * 59.Fn m_tag_find "struct mbuf *m" "int type" 60.Ft struct m_tag * 61.Fn m_tag_copy "struct m_tag *m" 62.Ft int 63.Fn m_tag_copy_chain "struct mbuf *to" "struct mbuf *from" 64.\" ------------------------------------------------------------ 65.Sh DESCRIPTION 66The 67.Nm 68interface is used to 69.Dq tag 70mbufs. 71.\" XXX PACKET_TAG_* 72.\" ------------------------------------------------------------ 73.Sh FUNCTIONS 74.Bl -tag -width compact 75.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 76.It Fn m_tag_get "type" "len" "wait" 77Allocate an mbuf tag. 78.Fa type 79is one of the 80.Dv PACKET_TAG_ 81macros. 82.Fa len 83is the size of the data associated with the tag, in bytes. 84.Fa wait 85is either 86.Dv M_WAITOK 87or 88.Dv M_NOWAIT . 89.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 90.It Fn m_tag_free "t" 91Free the mbuf tag 92.Fa t . 93.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 94.It Fn m_tag_prepend "m" "t" 95Prepend the mbuf tag 96.Fa t 97to the mbuf 98.Fa m . 99.Fa t 100will become the first tag of the mbuf 101.Fa m . 102When 103.Fa m 104is freed, 105.Fa t 106will also be freed. 107.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 108.It Fn m_tag_unlink "m" "t" 109Unlink the mbuf tag 110.Fa t 111from the mbuf 112.Fa m . 113.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 114.It Fn m_tag_delete "m" "t" 115The same as 116.Fn m_tag_unlink 117followed by 118.Fn m_tag_free . 119.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 120.It Fn m_tag_delete_chain "m" 121Unlink and free mbuf tags from the mbuf 122.Fa m . 123.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 124.It Fn m_tag_find "m" "type" 125Find an mbuf tag with type 126.Fa type 127in the tag chain associated with the mbuf 128.Fa m . 129If an mbuf tag is found, return a pointer to it. 130Otherwise return 131.Dv NULL . 132.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 133.It Fn m_tag_copy "t" 134Copy an mbuf tag 135.Fa t . 136Return a new mbuf tag on success. 137Otherwise return 138.Dv NULL . 139.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 140.It Fn m_tag_copy_chain "to" "from" 141Copy all mbuf tags associated with the mbuf 142.Fa from 143to the mbuf 144.Fa to . 145If 146.Fa to 147already has any mbuf tags, they will be unlinked and freed beforehand. 148Return 1 on success. 149Otherwise return 0. 150.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 151.El 152.\" ------------------------------------------------------------ 153.Sh CODE REFERENCES 154The mbuf tagging interfaces are implemented within the file 155.Pa sys/kern/uipc_mbuf.c . 156.Pp 157The 158.Dv PACKET_TAG_ 159macros are defined in the file 160.Pa sys/sys/mbuf.h . 161.Sh SEE ALSO 162.Xr intro 9 , 163.Xr malloc 9 , 164.Xr mbuf 9 165.\" ------------------------------------------------------------ 166.Sh BUGS 167The semantics of the term "persistent tag" are vague. 168