FreeBSD Man Pages
home | helpMBUF_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 11.0 May 20, 2004 FreeBSD 11.0
NAME | SYNOPSIS | DESCRIPTION | CODE REFERENCES | SEE ALSO | HISTORY
Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mbuf_tags&sektion=9&manpath=FreeBSD+5.3-RELEASE>