VN_DEALLOCATE(9)

🎀 VN_DEALLOCATE 🎀

okay so bestie, this is from the Kernel Developer's Manual, section 9 — yes, the kernel one, we're in the big leagues now 💅. Sit down, hydrate, and let's talk about vn_deallocate.

---

✨ NAME ✨

vn_deallocate — zero and/or deallocate storage from a file. that's it, that's the whole vibe. it zeroes stuff and frees up the backing storage. iconic behavior honestly 🫶

---

✨ SYNOPSIS ✨

#include <sys/param.h>
#include <sys/vnode.h>

int
vn_deallocate(struct vnode *vp, off_t *offset, off_t *length, int flags,
    int ioflag, struct ucred *active_cred, struct ucred *file_cred);

like, you gotta include both headers, no skipping, they're a package deal 🎀 and the return type is int, okay?

---

✨ DESCRIPTION ✨

so the vn_deallocate() function zeros and/or deallocates backing storage space from a file — literally both, that "and/or" is doing so much work and we love her for it. 💖

but here's the catch, bestie — this bad girl only works on vnodes with VREG type. only regular files. don't come at her with anything else, she will not entertain it 😭

the arguments (let me introduce you) 🫶

• vp — the vnode of the file. the main character, literally.
• offset — the starting offset of the operation range. where the party begins.
• length — the length of the operation range. this must be greater than 0 — no zero-length shenanigans, it's giving boundaries and honestly, respect.
• flags — the control flags of the operation. this should be set to 0 for now — yes, just zero, that's the assignment, don't overthink it.
• ioflag — directives and hints to be given to the file system. the little whispers in the fs's ear ✨
• active_cred — the user credentials of the calling thread. who even are you, identify yourself 🪪
• file_cred — the credentials installed on the file description pointing to the vnode, or NOCRED. either you've got creds or you've got NOCRED, no in-between.

---

the ioflag situation 🌈

the ioflag() argument gives directives and hints to the file system, and it may include one or more of these babies:

• IO_NODELOCKED — the vnode was locked before the call. you handled that already, look at you go 👑
• IO_RANGELOCKED — rangelock was owned around the call. rangelocked and ready 🔒
• IO_NOMACCHECK — skip MAC checking in the call. we're not doing the MAC check today, moving on 💀
• IO_SYNC — do I/O synchronously. no shortcuts, we wait.
• IO_DIRECT — attempt to bypass buffer cache. going straight to the source, main character energy fr fr 🔥

---

what happens to *offset and *length after 👀

okay this is the part that actually matters, pay attention:

*offset and *length are updated to reflect the unprocessed operation range</u> of the call. so like, whatever didn't get processed? that's what they tell you afterwards. very transparent of them 💖

and for a successful completion:

• *length is updated to be the value 0 — yup, zero, all done, nothing left 🌸
• *offset is incremented by the number of bytes zeroed before the end-of-file. she moved up by exactly how much got zeroed before EOF, no more no less.

---

✨ RETURN VALUES ✨

upon successful completion, the value 0 is returned; otherwise the appropriate error is returned.

so basically: zero = slay 💅, anything else = the appropriate error, and she will let you know.

---

✨ SEE ALSO ✨

• vnode(9)
• VOP_DEALLOCATE(9)

go read those too bestie, they're literally friends with this page 🦋

---

✨ AUTHORS ✨

vn_deallocate and this manual page was written by Ka Ho Ng <khng@FreeBSD.org> under sponsorship from the FreeBSD Foundation. give her a round of applause, we stan a sponsored kernel dev 👏👑💜

---

and that's the whole page bestie — no cap, every flag accounted for. this one shipped on Debian, dated August 25, 2021, so if you're citing it: Debian, August 25, 2021, VN_DEALLOCATE(9). mwah 💋🎀✨