---
name: "mbuf_tags"
section: "9"
platform: "linux"
package: "freebsd-manpages"
version: "6.0-5"
release: "Debian 4.0 (Etch)"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/mbuf_tags"
---

# mbuf\_tags(9)

a framework for generic packet attributes

## 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)](/mbuf/9.md) 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 the storage of VLAN tags as described in [vlan(4)](/vlan/4.md), Mandatory Access Control (MAC) labels as described in [mac(9)](/mac/9.md), IPsec policy information as described in [ipsec(4)](/ipsec/4.md), and packet filter tags used by [pf(4)](/pf/4.md).

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 */
	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)](/queue/3.md) 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⟩.

### 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)](/malloc/9.md). If successful, **m\_tag\_alloc**() returns a memory buffer of (*len* + **sizeof**(*struct m\_tag*)) bytes. Otherwise, NULL is returned. A compatibility function **m\_tag\_get**() is also provided.

- **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 compatibility 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)](/queue/3.md), [mbuf(9)](/mbuf/9.md)

## HISTORY

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