Manual Pages  — MBUF_TAGS

#include <sys/mbuf.h>

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 allocate, 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 automatically 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 distinguished by its type and cookie. The cookie is used to identify a specific module or API. The packet tags are attached to mbuf packet headers.

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 */
        uint16_t                m_tag_id;       /* Tag ID */
        uint16_t                m_tag_len;      /* Length of data */
        uint32_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 globally 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>.

queue(3), mbuf(9)