ML_INIT(9)

💖 ML_INIT(9) — mbuf list API 💖

Okay so this is ML_INIT(9), straight from the Kernel Developer's Manual, bestie. It's the mbuf list API page, and it's giving very useful data-structure realness for managing lists of mbufs between contexts. Slay.

---

✨ NAME ✨

The whole icon squad is ml_init, ml_enqueue, ml_dequeue, ml_enlist, ml_dechain, ml_len, ml_empty, ml_hdatalen, ml_purge, MBUF_LIST_INITIALIZER, MBUF_LIST_FIRST, MBUF_LIST_NEXT, and MBUF_LIST_FOREACH — aka the mbuf list API.

🌸 SYNOPSIS 🌸

#include <sys/mbuf.h>

void
ml_init(struct mbuf_list *ml);

void
ml_enqueue(struct mbuf_list *ml, struct mbuf *m);

struct mbuf *
ml_dequeue(struct mbuf_list *ml);

void
ml_enlist(struct mbuf_list *ml, struct mbuf_list *src);

struct mbuf *
ml_dechain(struct mbuf_list *ml);

unsigned int
ml_len(struct mbuf_list *ml);

int
ml_empty(struct mbuf_list *ml);

unsigned int
ml_hdatalen(struct mbuf_list *ml);

unsigned int
ml_purge(struct mbuf_list *ml);

struct mbuf_list
MBUF_LIST_INITIALIZER();

struct mbuf *
MBUF_LIST_FIRST(struct mbuf_list *ml);

struct mbuf *
MBUF_LIST_NEXT(struct mbuf *m);

MBUF_LIST_FOREACH(struct mbuf_list *ml, VARNAME);

🦋 DESCRIPTION 🦋

The mbuf list API provides implementations of data structures and operations for managing lists of mbufs between contexts. mbuf_list structures support the following functionality:

1. Insertion of a new mbuf at the end of the list.
2. Removal of an mbuf from the head of the list.

Here's the full cast, no skips, no cuts:

• ml_init(struct mbuf_list *ml) — Initialise the ml mbuf_list structure.
• MBUF_LIST_INITIALIZER() — An initialiser for an mbuf_list structure declaration.
• ml_enqueue(struct mbuf_list *ml, struct mbuf *m) — Enqueue mbuf m on the end of the ml mbuf list.
• ml_dequeue(struct mbuf_list *ml) — Dequeue an mbuf from the front of the ml mbuf list.
• ml_enlist(struct mbuf_list *ml, struct mbuf_list *src) — Enqueue all the mbufs on the src mbuf list on to the end of the ml mbuf list.
• ml_dechain(struct mbuf_list *ml) — Dequeues all mbufs from the ml mbuf list.
• ml_len(struct mbuf_list *ml) — Return the number of mbufs on the ml mbuf list.
• ml_empty(struct mbuf_list *ml) — Return if the ml mbuf list is empty.
• ml_hdatalen(struct mbuf_list *ml) — Return the number of bytes in the packet at the head of the ml mbuf list.
• ml_purge(struct mbuf_list *ml) — Free all the mbufs on the ml mbuf list.
• MBUF_LIST_FIRST(struct mbuf_list *ml) — Access the first mbuf in the ml mbuf list for traversal.
• MBUF_LIST_NEXT(struct mbuf *m) — Access the next mbuf in the mbuf list after m.
• MBUF_LIST_FOREACH(struct mbuf_list *ml, VARNAME) — A convenience macro that can be used to iterate over the contents of the ml mbuf list. VARNAME identifies the name (not the address) of an mbuf pointer that will be set to each entry on the list. Note that it is unsafe to modify the list while iterating over it.

🚨 Bestie, for real: it is unsafe to modify the list while iterating over it. The page says it, I'm saying it, we're all saying it. Do not do the chaotic thing.

⭐ CONTEXT ⭐

These specific ones can be called during autoconf, from process context, or from interrupt context:

• ml_init()
• ml_enqueue()
• ml_dequeue()
• ml_enlist()
• ml_dechain()
• ml_len()
• ml_empty()
• ml_purge()
• MBUF_LIST_INITIALIZER()
• MBUF_LIST_FIRST()
• MBUF_LIST_NEXT()
• MBUF_LIST_FOREACH()

💜 RETURN VALUES 💜

• ml_dequeue() — returns the mbuf that was at the head of its list. If the list was empty, NULL is returned.
• ml_dechain() — returns all the mbufs that were on the list via a pointer to an mbuf with the chain accessible via m_nextpkt members. If the list was empty, NULL is returned.
• ml_len() — returns the number of mbufs on the list.
• ml_empty() — returns a non-zero value if the list is empty, otherwise 0.
• ml_hdatalen() — returns the size of a packet on the list, or 0 if the list is empty.
• ml_purge() — returns the number of mbufs that were freed.
• MBUF_LIST_FIRST() — returns the first mbuf in the mbuf list, or NULL if the list is empty.
• MBUF_LIST_NEXT() — returns the next mbuf in the mbuf list, or NULL if the end of the list has been reached.

🌈 SEE ALSO 🌈

mbuf(9)

---

This page is from Debian, dated January 23, 2020 — mwah, and good luck out there 💅✨