BUFFERCACHE(9)

✨ NAME ✨

This is BUFFERCACHE(9) from the Kernel Developer's Manual, and the whole squad is buffercache, bread, breadn, bwrite, bawrite, bdwrite, getblk, geteblk, incore, allocbuf, and brelse — buffer cache interfaces, bestie. 💅

🌸 SYNOPSIS 🌸

#include <sys/buf.h>

int
bread(struct vnode *vp, daddr_t blkno, int size, int flags,
    buf_t **bpp);

int
breadn(struct vnode *vp, daddr_t blkno, int size, daddr_t rablks[],
    int rasizes[], int nrablks, int flags, buf_t **bpp);

int
bwrite(buf_t *bp);

void
bawrite(buf_t *bp);

void
bdwrite(buf_t *bp);

buf_t *
getblk(struct vnode *vp, daddr_t blkno, int size, int slpflag,
    int slptimeo);

buf_t *
geteblk(int size);

buf_t *
incore(struct vnode *vp, daddr_t blkno);

void
allocbuf(buf_t *bp, int size, int preserve);

void
brelse(buf_t *bp, int set);

💖 DESCRIPTION 💖

The buffercache interface is used by each filesystem to improve I/O performance using in-core caches of filesystem blocks. Honestly iconic behavior: keep the good stuff close so you don't have to go all the way to disk every time. ✨

The kernel memory used to cache a block is called a buffer, and it's described by a buf structure. And plot twist: a buf structure doesn't only describe a cached block — it's also used to describe an I/O request as a part of the disk driver interface. Multitasking queen. 👑

🔥 FUNCTIONS 🔥

bread(vp, blkno, size, flags, bpp)

Read a block corresponding to vp and blkno. The buffer comes back to you via bpp. The units of blkno are specifically the units used by the VOP_STRATEGY() routine for the vp vnode.

For device special files, blkno is in units of DEV_BSIZE and both blkno and size must be multiples of the underlying device's block size. For other files, blkno is in units chosen by the file system containing vp.

If the buffer is not found (i.e. the block is not cached in memory), bread() allocates a buffer with enough pages for size and reads the specified disk block into it.

The buffer returned by bread() is marked as busy. (The B_BUSY flag is set.) After manipulation of the buffer returned from bread(), the caller should unbusy it so that another thread can get it. If the buffer contents are modified and should be written back to disk, it should be unbusied using one of the variants of bwrite(). Otherwise, it should be unbusied using brelse().

breadn(vp, blkno, size, rablks, rasizes, nrablks, flags, bpp)

Get a buffer as bread(). In addition, breadn() will start read-ahead of blocks specified by rablks, rasizes, nrablks. It's giving "I already know what you're gonna need next" energy. 🔮

bwrite(bp)

Write a block. Start I/O for write using VOP_STRATEGY(). Then, unless the B_ASYNC flag is set in bp, bwrite() waits for the I/O to complete. Patient queen — it stays until it's done. ⏳

bawrite(bp)

Write a block asynchronously. Set the B_ASYNC flag in bp and simply call VOP_BWRITE(), which results in bwrite() for most filesystems. It's the "go on ahead, I'll catch up" version. 💨

bdwrite(bp)

Delayed write. Unlike bawrite(), bdwrite() won't start any I/O. It only marks the buffer as dirty (BO_DELWRI) and unbusies it. Lowkey the chillest writer in the group chat. 😌

getblk(vp, blkno, size, slpflag, slptimeo)

Get a block of requested size size that is associated with a given vnode and block offset, specified by vp and blkno. If it is found in the block cache, make it busy and return it. Otherwise, return an empty block of the correct size. It is up to the caller to ensure that the cached blocks are of the correct size.

If getblk() needs to sleep, slpflag and slptimeo are used as arguments for cv_timedwait(). Nap time is scheduled with those, bestie. 😴

geteblk(size)

Allocate an empty, disassociated block of a given size size. No vnode, no block offset, just a fresh little buffer with no attachments. 🌱

incore(vp, blkno)

Determine if a block associated to a given vnode and block offset is in the cache. If it is there, return a pointer to it. Note that incore() doesn't busy the buffer unlike getblk(). It's just peeking, not committing. 👀

allocbuf(bp, size, preserve)

Expand or contract the actual memory allocated to a buffer. If preserve is zero, the entire data in the buffer will be lost.

⚠️ Bestie, if preserve is zero, the entire data in the buffer will be lost. Not a drill. 😭

Otherwise, if the buffer shrinks, the truncated part of the data is lost, so it is up to the caller to have written it out first if needed; this routine will not start a write. If the buffer grows, it is the caller's responsibility to fill out the buffer's additional contents. So yes, you gotta handle the extra bits yourself. 🫶

brelse(bp, set)

Unbusy a buffer and release it to the free lists. The set argument is right there in the signature too; the description here just says unbusy + release, and that's the whole vibe. 💫

🧚 CODE REFERENCES 🧚

The buffer cache subsystem is implemented within the file sys/kern/vfs_bio.c. That's the source file to peek at if you want the full backstage tour. 🎬

🎀 SEE ALSO 🎀

• intro(9)
• bufferio(9)
• Xr vnode 9 — yes bestie, that's literally how it appears here 💀

Also, the reading list:

• Maurice J. Bach, The Design of the UNIX Operating System, Prentice Hall, 1986.
• Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, and John S. Quarterman, The Design and Implementation of the 4.4BSD Operating System, Addison Wesley, 1996.

---

💖 Cute sign-off: this page is from Debian, dated April 11, 2017, and it's the BUFFERCACHE(9) manual page. Bye bestie, go unbusy responsibly 🫶✨