PBUF(9)

💖 PBUF(9) 💖 — the kernel dev manual, but make it cute

okay bestie, gather round, because today we're talking about pbuf and friends — and this is from the Kernel Developer's Manual, so yes, we're in the big leagues now 👑

✨ NAME ✨

pbuf, getpbuf, trypbuf, relpbuf — the girlies that manage physical buffers 💅

✨ SYNOPSIS ✨

#include <sys/param.h>
#include <sys/systm.h>
#include <sys/bio.h>
#include <sys/buf.h>

struct buf *
getpbuf(int *pfreecnt);

struct buf *
trypbuf(int *pfreecnt);

void
relpbuf(struct buf *bp, int *pfreecnt);

so yeah, four headers, three functions, one little struct buf * situation going on 🎀

✨ DESCRIPTION ✨

okay so. These functions are literally the ones that allocate and release physical buffers. That's the whole job. That's the vibe. 💖

The physical buffers get allocated at system startup, and they live in their own separate pool, apart from the main system buffers. Not me being like "we're not like other buffers" — they literally aren't 🦋 They're made for subsystems that cannot or should not depend on the main buffer pool (the swap pager is the iconic example, iykyk). Depending on how much memory the system has, it allocates between 16 and 256 physical buffers.

Every subsystem that allocates buffers through these calls is expected to manage its own percentage free counter, bestie — that's a you problem, not a pbuf problem 🙈 And here's the tea:

• If that value is initialized to -1, the number of buffers available to the subsystem is limited only by the number of physical buffers available.
• The number of buffers is stored in nswbuf, which is defined in <sys/buf.h> and initialized in cpu_startup().
• A recommended initialization value is 1/2 nswbuf. slay.

Now, the functions, one by one:

• getpbuf() — returns the first available buffer to the user. If there are no buffers available, it will sleep waiting for one to become available 😴 And if pfreecnt is zero, getpbuf() will sleep until it increases. pfreecnt gets decremented prior to returning.
• trypbuf() — returns the first available buffer. If there are no buffers available, NULL is returned. Also, if pfreecnt is zero, NULL is returned. pfreecnt is decremented prior to returning a valid buffer. And if NULL is returned, pfreecnt is not modified. no cap, it just doesn't touch it 🫶
• relpbuf() — releases the buffer back to the free list. If the buffer's b_rcred or b_wcred structures are not NULL, they are freed. See crfree(9) for that whole situation. And pfreecnt is incremented prior to returning ⭐

✨ RETURN VALUES ✨

getpbuf() and trypbuf() return a pointer to the buffer. In the case of trypbuf(), NULL can also be returned, which means there are no buffers available. that's it, that's the whole answer 💀

✨ AUTHORS ✨

This manual page was written by Chad David <davidc@acns.ab.ca> — give him his flowers 🌸

and that's the page, bestie!! this one came from the Debian build of the manual, dated July 9, 2001 — so yeah, it's vintage, it's iconic, it's giving "before you were born" energy 👑 go forth and manage your physical buffers responsibly, mwah 💜✨