MBCHAIN(9)

🦋 NAME 🦋

okay so this is MBCHAIN(9), straight out of the Kernel Developer's Manual, and it's literally the whole glow-up kit for making mbuf chains out of different data types ✨

The page covers mbchain, mb_init, mb_initm, mb_done, mb_detach, mb_fixhdr, mb_reserve, mb_put_uint8, mb_put_uint16be, mb_put_uint16le, mb_put_uint32be, mb_put_uint32le, mb_put_int64be, mb_put_int64le, mb_put_mem, mb_put_mbuf, and mb_put_uio — a set of functions to build an mbuf chain from various data types. bestie, it's giving kernel-side arts and crafts 🎀

---

✨ SYNOPSIS ✨

options LIBMCHAIN
kldload libmchain

#include <sys/param.h>
#include <sys/uio.h>
#include <sys/mchain.h>

int
mb_init(struct mbchain *mbp);

void
mb_initm(struct mbchain *mbp, struct mbuf *m);

void
mb_done(struct mbchain *mbp);

struct mbuf *
mb_detach(struct mbchain *mbp);

int
mb_fixhdr(struct mbchain *mbp);

caddr_t
mb_reserve(struct mbchain *mbp, int size);

int
mb_put_uint8(struct mbchain *mbp, uint8_t x);

int
mb_put_uint16be(struct mbchain *mbp, uint16_t x);

int
mb_put_uint16le(struct mbchain *mbp, uint16_t x);

int
mb_put_uint32be(struct mbchain *mbp, uint32_t x);

int
mb_put_uint32le(struct mbchain *mbp, uint32_t x);

int
mb_put_int64be(struct mbchain *mbp, int64_t x);

int
mb_put_int64le(struct mbchain *mbp, int64_t x);

int
mb_put_mem(struct mbchain *mbp, c_caddr_t source, int size, int type);

int
mb_put_mbuf(struct mbchain *mbp, struct mbuf *m);

int
mb_put_uio(struct mbchain *mbp, struct uio *uiop, int size);

---

💖 DESCRIPTION 💖

These functions are used to compose mbuf chains from various data types. The mbchain structure is the working context, and you gotta initialize it with either mb_init() or mb_initm() first — no skipping steps, bestie 💅

It has these fields:

• mb_top (struct mbuf *) — a pointer to the top of the constructed mbuf chain.
• mb_cur (struct mbuf *) — a pointer to the currently filled mbuf.
• mb_mleft (int) — the number of bytes left in the current mbuf.
• mb_count (int) — the total number of bytes placed in the mbuf chain.
• mb_copy (mb_copy_t *) — a user-defined function to perform a copy into mbuf; useful if any unusual data conversion is necessary.
• mb_udata (void *) — user-supplied data which can be used in the mb_copy function.

The mb_done() function disposes an mbuf chain pointed to by the mbp->mb_top field and sets the field to NULL.

The mb_detach() function returns the value of the mbp->mb_top field and sets its value to NULL.

mb_fixhdr() recalculates the length of an mbuf chain and updates the m_pkthdr.len field of the first mbuf in the chain. It returns the calculated length.

mb_reserve() ensures that the object of the length specified by the size argument will fit in the current mbuf (mbuf allocation is performed if necessary), and advances all pointers as if the real data was placed. The returned value will point to the beginning of the reserved space. Note that the size of the object should not exceed MLEN bytes — that's the limit, okay? 🚧

All mb_put_*() functions perform an actual copy of the data into the mbuf chain. Functions which have le or be suffixes will perform conversion to the little- or big-endian data formats. endianness said what it said 🌈

mb_put_mem() copies size bytes of data specified by the source argument to an mbuf chain. The type argument specifies the method used to perform a copy, and can be one of the following:

• MB_MSYSTEM — use bcopy() function.
• MB_MUSER — use copyin(9) function.
• MB_MINLINE — use an “inline” loop which does not call any function.
• MB_MZERO — do not copy any data, but just fill the destination with zero bytes.
• MB_MCUSTOM — call function specified by the mbp->mb_copy field.

---

🫶 RETURN VALUES 🫶

All int functions except mb_fixhdr() return zero if successful and an error code otherwise. mb_fixhdr() is out here doing its own thing and returns the calculated length, periodt ✨

Note: after failure of any function, an mbuf chain is left in the broken state, and only mb_done() function can safely be called to destroy it. so like, do not keep poking the broken chain, bestie 😭💀

---

🧚 EXAMPLES 🧚

struct mbchain *mbp;
struct mbuf *m;

mb_init(mbp);
mb_put_uint8(mbp, 33);
mb_put_uint16le(mbp, length);
m = m_copym(mbp->mb_top, 0, M_COPYALL, M_WAIT);
send(m);
mb_done(mbp);

---

🌸 SEE ALSO 🌸

mbuf(9), mdchain(9) — go read those too, iykyk 💜

---

👑 AUTHORS 👑

This manual page was written by Boris Popov <bp@FreeBSD.org>.

---

Debian edition, dated February 20, 2001, page MBCHAIN(9) — that's the cute lil sign-off, bestie, mwah 💋🎀