VNODE(9)

💖 VNODE(9) — the Kernel Developer's Manual glow-up 💖

okay bestie, gather round, because today we're talking about vnode(9) and honestly? it's the main character of the entire Unix filesystem. no cap. 🫶

---

✨ NAME ✨

vnode — the internal representation of a file or directory. literally what a file is, on the inside. 💅

---

✨ SYNOPSIS ✨

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

like, include both, don't skip the first one, she's there for a reason. 🎀

---

✨ DESCRIPTION ✨

okay so. the vnode is the focus of all file activity in Unix. everything. all of it. every file thing that happens? a vnode is involved. periodt.

a vnode is described by struct vnode. and here's the vibe: there is a unique vnode allocated for each active file, each current directory, each mounted-on file, each text file, and the root. like each one gets her own. 👑

---

💫 the three reference counts (yes, three, she's busy)

• v_usecount — the number of clients within the kernel which are using this vnode. this one is maintained by vref(9), vrele(9) and vput(9).
• v_holdcnt — the number of clients within the kernel who veto the recycling of this vnode. maintained by vhold(9) and vdrop(9). so when both the v_usecount and the v_holdcnt of a vnode reaches zero, the vnode gets put on the freelist and may be reused for another file — possibly in another file system 😳. the transition from the freelist is handled by getnewvnode(9).
• v_writecount — a count of the number of clients which are writing into the file. maintained by the open(2) and close(2) system calls.

---

🦋 the rules of holding a vnode

any call which returns a vnode (e.g., vget(9), VOP_LOOKUP(9), etc.) will increase the v_usecount of the vnode by one. that's the deal.

when the caller is finished with the vnode, it should release this reference by calling vrele(9) — or vput(9) if the vnode is locked. 🔐

bestie please actually release it. the reference is not a souvenir. 😭

---

🌸 other commonly used members of the vnode structure

• v_id — used to maintain consistency in the name cache.
• v_mount — points at the file system which owns the vnode.
• v_type — contains the type of object the vnode represents.
• v_data — used by file systems to store file system specific data with the vnode.
• v_op — used by the VOP_* macros to call functions in the file system which implement the vnode's functionality.

it's giving "small struct, enormous responsibility". 💀

---

✨ VNODE TYPES ✨

the v_type field, but make it a personality quiz:

• VNON — No type. (mystery era 🙈)
• VREG — A regular file; may be with or without VM object backing. If you want to make sure this get a backing object, call vnode_create_vobject().
• VDIR — A directory.
• VBLK — A block device; may be with or without VM object backing. If you want to make sure this get a backing object, call vnode_create_vobject().
• VCHR — A character device.
• VLNK — A symbolic link.
• VSOCK — A socket. Advisory locking will not work on this.
• VFIFO — A FIFO (named pipe). Advisory locking will not work on this.
• VBAD — Indicates that the vnode has been reclaimed. she's gone, she's resting, don't call her. 💀

---

✨ IMPLEMENTATION NOTES ✨

• VFIFO uses the "struct fileops" from /sys/kern/sys_pipe.c.
• VSOCK uses the "struct fileops" from /sys/kern/sys_socket.c.
• Everything else uses the one from /sys/kern/vfs_vnops.c.

the VFIFO/VSOCK code — which is why "struct fileops" is used at all — is an artifact of an incomplete integration of the VFS code into the kernel. lore. 🍓

and now the warning, listen up:

Calls to malloc(9) or free(9) when holding a vnode interlock, will cause a LOR (Lock Order Reversal) due to the intertwining of VM Objects and Vnodes.

do not do this. not even once. 🙏

---

✨ SEE ALSO ✨

malloc(9), VFS(9), VOP_ACCESS(9), VOP_ACLCHECK(9), VOP_ADVISE(9), VOP_ADVLOCK(9), VOP_ALLOCATE(9), VOP_ATTRIB(9), VOP_BWRITE(9), VOP_CREATE(9), VOP_FSYNC(9), VOP_GETACL(9), VOP_GETEXTATTR(9), VOP_GETPAGES(9), VOP_INACTIVE(9), VOP_IOCTL(9), VOP_LINK(9), VOP_LISTEXTATTR(9), VOP_LOCK(9), VOP_LOOKUP(9), VOP_OPENCLOSE(9), VOP_PATHCONF(9), VOP_PRINT(9), VOP_RDWR(9), VOP_READDIR(9), VOP_READLINK(9), VOP_REALLOCBLKS(9), VOP_REMOVE(9), VOP_RENAME(9), VOP_REVOKE(9), VOP_SETACL(9), VOP_SETEXTATTR(9), VOP_STRATEGY(9), VOP_VPTOCNP(9), VOP_VPTOFH(9)

that's the whole friend group. go say hi. 🌈

---

✨ AUTHORS ✨

This manual page was written by Doug Rabson. king behaviour, honestly. 👑

---

and that's the tea, bestie 💖 this one shipped with Debian, dated February 12, 2014, and it's still iconic. slay, vnode, slay. ✨🦋🎀💅