Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
MBUF_TAGS(9)	       FreeBSD Kernel Developer's Manual	  MBUF_TAGS(9)

NAME
     mbuf_tags -- a framework for generic packet attributes

SYNOPSIS
     #include <sys/mbuf.h>

     struct m_tag *
     m_tag_alloc(u_int32_t cookie, int type, int len, int wait);

     struct m_tag *
     m_tag_copy(struct m_tag *t, int how);

     int
     m_tag_copy_chain(struct mbuf *to, struct mbuf *from, int how);

     void
     m_tag_delete(struct mbuf *m, struct m_tag *t);

     void
     m_tag_delete_chain(struct mbuf *m,	struct m_tag *t);

     void
     m_tag_delete_nonpersistent(struct mbuf *m);

     struct m_tag *
     m_tag_find(struct mbuf *m,	int type, struct m_tag *start);

     struct m_tag *
     m_tag_first(struct	mbuf *m);

     void
     m_tag_free(struct m_tag *t);

     struct m_tag *
     m_tag_get(int type, int len, int wait);

     void
     m_tag_init(struct mbuf *m);

     struct m_tag *
     m_tag_locate(struct mbuf *m, u_int32_t cookie, int	type,
	 struct	m_tag *t);

     struct m_tag *
     m_tag_next(struct mbuf *m,	struct m_tag *t);

     void
     m_tag_prepend(struct mbuf *m, struct m_tag	*t);

     void
     m_tag_unlink(struct mbuf *m, struct m_tag *t);

DESCRIPTION
     Mbuf tags allow additional	meta-data to be	associated with	in-flight
     packets by	providing a mechanism for the tagging of additional kernel
     memory onto packet	header mbufs.  Tags are	maintained in chains off of
     the mbuf(9) header, and maintained	using a	series of API calls to allo-
     cate, search, and delete tags.  Tags are identified using an ID and
     cookie that uniquely identify a class of data tagged onto the packet, and
     may contain an arbitrary amount of	additional storage.  Typical uses of
     mbuf tags include Mandatory Access	Control	(MAC) labels as	described in
     mac(9), IPsec policy information as described in ipsec(4),	and packet
     filter tags used by pf(4).

     Tags will be maintained across a variety of operations, including the
     copying of	packet headers using facilities	such as	M_COPY_PKTHDR()	and
     M_MOVE_PKTHDR().  Any tags	associated with	an mbuf	header will be auto-
     matically freed when the mbuf is freed, although some subsystems will
     wish to delete the	tags prior to that time.

     Packet tags are used by different kernel APIs to keep track of operations
     done or scheduled to happen to packets.  Each packet tag can be distin-
     guished by	its type and cookie.  The cookie is used to identify a spe-
     cific module or API.  The packet tags are attached	to mbuf	packet head-
     ers.

     The first sizeof(struct m_tag) bytes of a tag contain a struct m_tag:

     struct m_tag {
	     SLIST_ENTRY(m_tag)	     m_tag_link;     /*	List of	packet tags */
	     u_int16_t		     m_tag_id;	     /*	Tag ID */
	     u_int16_t		     m_tag_len;	     /*	Length of data */
	     u_int32_t		     m_tag_cookie;   /*	ABI/Module ID */
	     void		     (*m_tag_free)(struct m_tag	*);
     };

     The m_tag_link field is used to link tags together	(see queue(3) for more
     details).	The m_tag_id, m_tag_len	and m_tag_cookie fields	are set	to
     type, length, and cookie, respectively.  m_tag_free points	to
     m_tag_free_default().  Following this structure are m_tag_len bytes of
     space that	can be used to store tag-specific information.	Addressing
     this data region may be tricky.  A	safe way is embedding struct m_tag
     into a private data structure, as follows:

	   struct foo {
		   struct m_tag	   tag;
		   ...
	   };
	   struct foo *p = (struct foo *)m_tag_alloc(...);
	   struct m_tag	*mtag =	&p->tag;

     Note that OpenBSD does not	support	cookies, it needs m_tag_id to be glob-
     ally unique.  To keep compatibility with OpenBSD, a cookie
     MTAG_ABI_COMPAT is	provided along with some compatibility functions.
     When writing an OpenBSD compatible	code, one should be careful not	to
     take already used tag type.  Tag types are	defined	in <sys/mbuf.h>.

   Packet Tag Manipulation Functions
	   m_tag_alloc(cookie, type, len, wait)
	   Allocate a new tag of type type and cookie cookie with len bytes of
	   space following the tag header itself.  The wait argument is	passed
	   directly to malloc(9).  If successful, m_tag_alloc()	returns	a mem-
	   ory buffer of (len +	sizeof(struct m_tag)) bytes.  Otherwise, NULL
	   is returned.	 A compatibility function m_tag_get() is also pro-
	   vided.

	   m_tag_copy(tag, how)
	   Allocate a copy of tag.  The	how argument is	passed directly	to
	   m_tag_alloc().  The return values are the same as in	m_tag_alloc().

	   m_tag_copy_chain(tombuf, frommbuf, how)
	   Allocate and	copy all tags from mbuf	frommbuf to mbuf tombuf.
	   Returns 1 on	success, and 0 on failure.  In the latter case,	mbuf
	   tombuf loses	all its	tags, even previously present.

	   m_tag_delete(mbuf, tag)
	   Remove tag from mbuf's list and free	it.

	   m_tag_delete_chain(mbuf, tag)
	   Remove and free a packet tag	chain, starting	from tag.  If tag is
	   NULL, all tags are deleted.

	   m_tag_delete_nonpersistent(mbuf)
	   Traverse mbuf's tags	and delete those which do not have the
	   MTAG_PERSISTENT flag	set.

	   m_tag_first(mbuf)
	   Return the first tag	associated with	mbuf.

	   m_tag_free(tag)
	   Free	tag using its m_tag_free method.  The m_tag_free_default()
	   function is used by default.

	   m_tag_init(mbuf)
	   Initialize the tag storage for packet mbuf.

	   m_tag_locate(mbuf, cookie, type, tag)
	   Search for a	tag defined by type and	cookie in mbuf,	starting from
	   position specified by tag.  If the latter is	NULL, then search
	   through the whole list.  Upon success, a pointer to the first found
	   tag is returned.  In	either case, NULL is returned.	A compatibil-
	   ity function	m_tag_find() is	also provided.

	   m_tag_next(mbuf, tag)
	   Return tag next to tag in mbuf.  If absent, NULL is returned.

	   m_tag_prepend(mbuf, tag)
	   Add the new tag tag at the head of the tag list for packet mbuf.

	   m_tag_unlink(mbuf, tag)
	   Remove tag tag from the list	of tags	of packet mbuf.

CODE REFERENCES
     The tag-manipulating code is contained in the file	sys/kern/uipc_mbuf2.c.
     Inlined functions are defined in <sys/mbuf.h>.

SEE ALSO
     queue(3), mbuf(9)

HISTORY
     The packet	tags first appeared in OpenBSD 2.9 and were written by Angelos
     D.	Keromytis <angelos@openbsd.org>.

FreeBSD	9.2		       January 12, 2008			   FreeBSD 9.2

NAME | SYNOPSIS | DESCRIPTION | CODE REFERENCES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=mbuf_tags&sektion=9&manpath=FreeBSD+8.2-RELEASE>

home | help