PHYSIO(9)

💫 PHYSIO(9) — the physio man page, but make it make sense 💫

okay bestie, so this is a page from the Kernel Developer's Manual (section 9, kernel-adjacent, very demure, very mindful) and it's all about physio — the little helper that kicks off I/O on raw devices. 🎀 lowkey iconic of the kernel devs to document it. let's get into it ✨

---

🌸 NAME 🌸

physio — initiate I/O on raw devices. that's it. that's the whole vibe. 💅

---

✨ SYNOPSIS ✨

first, the little summoning circle of includes:

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

and then the function itself, looking all official:

int
physio(struct cdev *dev, struct uio *uio, int ioflag);

---

🦋 DESCRIPTION 🦋

okay so physio() is a helper function — and like, a particularly helpful one — that usually gets called from character device read() and write() routines to start I/O on a user process buffer. it's giving "middle management of the kernel" but make it cute. 🔥

the max amount of data you can transfer with each call? that's decided by dev->si_iosize_max. no cap. that's the ceiling. 🙈

what physio() does is take your I/O request, converts it into a strategy() request, and then hands that new request over to the driver's strategy() routine for processing. passing the baton. very main character energy. 👑

here's the slightly spicy part: since uio normally describes user space addresses, physio() has to lock those pages into memory. how? by calling vmapbuf() for the appropriate pages. locked in, literally. 🔒

also physio() always awaits the completion of the entire requested transfer before returning — unless an error condition gets detected earlier. so it's not one of those "fire and forget" situations, it's a "wait for the whole thing, no skipping ahead" situation. 💯

and a break-down of the arguments, because we love a list:

• dev — the device number that identifies the device you're interacting with. it's the "who" of the whole operation. 🫶
• uio — the description of the entire transfer, as requested by the user process. right now, the results of passing a uio structure with the uio_segflg set to anything other than UIO_USERSPACE are undefined. so like… don't. fr fr, don't. 💀
• ioflag — the ioflag argument from the read() or write() function that's calling physio(). it just comes along for the ride. 🚗

---

🍓 RETURN VALUES 🍓

if everything slays, physio() returns 0. 🎉

EFAULT gets returned if the address range described by uio is not accessible by the requesting process. like, the memory said "not today". 😭

beyond that, physio() will return any error resulting from calls to the device strategy routine — and it figures that out by examining the B_ERROR buffer flag and the b_error field. detective work. 🕵️‍♀️

⚠️ little note bestie: the actual transfer size may be less than what was requested by uio if the device signals an "end of file" condition. so don't come for it, it's literally just what the device said. 💅

---

🌈 SEE ALSO 🌈

• read(2)
• write(2)

iykyk, go read those if you want the full picture. 📚

---

💜 HISTORY 💜

real ones know: the physio manual page is originally from NetBSD, with minor changes so it applies to FreeBSD. giving credit where it's due, periodt. 🫡

and the physio call itself has been completely re-written to provide higher I/O and paging performance. glow-up of the century, honestly. 🔥✨

---

kiss kiss, that's the page 💋 — this little gem is from the Debian edition of the man page, dated January 19, 2012, and it's PHYSIO(9) all the way down. 🧚‍♀️🎀 love u, bye! 🦋