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
     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 free(9).
     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 struc-
     ture, 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.  free(9) 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.3			 May 20, 2004			   FreeBSD 9.3

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+5.3-RELEASE>

home | help