VNSUBR(9)

💅 VNSUBR(9) — high-level convenience functions for vnode operations 💅

okay so this is VNSUBR(9) from the Kernel Developer's Manual, and it's the high-level convenience squad for vnode operations. These functions are the friendly wrappers for simplified access to the vnode operations described in vnodeops(9). ✨

---

🎀 NAME 🎀

vnsubr, vn_bwrite, vn_close, vn_default_error, vn_isunder, vn_lock, vn_markexec, vn_marktext, vn_rdwr, vn_open, vn_bdev_open, vn_bdev_openpath, vn_stat, vn_writechk — high-level convenience functions for vnode operations.

---

🌸 SYNOPSIS 🌸

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

int
vn_bwrite(void *ap);

int
vn_close(struct vnode *vp, int flags, kauth_cred_t cred);

int
vn_default_error(void *v);

int
vn_isunder(struct vnode *dvp, struct vnode *rvp, struct lwp *l);

int
vn_lock(struct vnode *vp, int flags);

void
vn_markexec(struct vnode *vp);

void
vn_marktext(struct vnode *vp);

int
vn_open(struct vnode *at_dvp, struct pathbuf *pb, int nmode, int fmode,
    int cmode, struct vnode **ret_vp, bool *ret_domove, int *ret_fd);

int
vn_bdev_open(dev_t dev, struct vnode **vpp, struct lwp *l);

int
vn_bdev_openpath(struct pathbuf *pb, struct vnode **vpp, struct lwp *l);

int
vn_rdwr(enum uio_rw rw, struct vnode *vp, void *base, int len,
    off_t offset, enum uio_seg segflg, int ioflg, kauth_cred_t cred,
    size_t *aresid, struct lwp *l);

int
vn_readdir(file_t *fp, char *buf, int segflg, u_int count, int *done,
    struct lwp *l, off_t **cookies, int *ncookies);

int
vn_stat(struct vnode *vp, struct stat *sb);

int
vn_writechk(struct vnode *vp);

---

✨ DESCRIPTION ✨

The high-level functions on this page are convenience functions for simplified access to the vnode operations described in vnodeops(9). That's the whole thesis, bestie. 🫶

---

🦋 FUNCTIONS 🦋

vn_bwrite(ap)

Common code for block write operations. 🧱

vn_close(vp, flags, cred)

Common code for closing a vnode. vp is the unlocked vnode of the vnode you're closing. vn_close() locks the vnode, invokes the vnode operation VOP_CLOSE(9), and calls vput() to return the vnode to the freelist or holdlist. Important vibe: vn_close() expects an unlocked, referenced vnode and will dereference the vnode before returning. If it works, 0 comes back; otherwise you get an appropriate error. 💖

vn_default_error(v)

The generic "default" routine that just returns error. A file system uses it to specify unsupported operations in the vnode operations vector. It's the "sorry babe, not supported" slot. 🙈

vn_isunder(dvp, rvp, l)

Common code to check whether one directory specified by the vnode rvp can be found inside the directory specified by the vnode dvp. l is the calling process. vn_isunder() is meant to be used in chroot(2), chdir(2), fchdir(2), etc., to make sure chroot(2) actually means something. If it works, 0 is returned; otherwise 1 is returned. Yes bestie, 1. 🚨

vn_lock(vp, flags)

Common code to acquire the lock for vnode vp. flags tells it how to lock the vnode. The flags are:

• LK_SHARED — shared lock
• LK_EXCLUSIVE — exclusive lock
• LK_NOWAIT — do not sleep to await lock
• LK_RETRY — allow lock operation on dead vnode

If successful, 0 is returned; otherwise you get an appropriate error code. ⭐

🚫 vn_lock() must not be called when the vnode's reference count is zero.

vn_markexec(vp)

Common code to mark the vnode vp as containing executable code of a running process. 👑

vn_marktext(vp)

Common code to mark the vnode vp as being the text of a running process. 📝

vn_open(at_dvp, pb, nmode, fmode, cmode, ret_vp, ret_domove, ret_fd)

Common code for vnode open operations. at_dvp, if it's not NULL, gives the directory that relative paths start from, as per openat(2). pb gives the pathname. nmode, fmode, and cmode specify additional namei(9) flags, the open(2) flags (converted to F* from O_* form), and the access mode (permissions) for creation, respectively. nmode is restricted to one or perhaps both of the flags TRYEMULROOT and NOCHROOT. Other name(9) modes should be selected via fmode(). 🫶

ret_vp, ret_domove, and ret_fd encode the possible return values. When called, vn_open() checks permissions and invokes the VOP_OPEN(9) or VOP_CREATE(9) vnode operations. If the operation is unsuccessful, an appropriate error code is returned; otherwise, 0 is returned. If a vnode is produced, it is returned locked via ret_vp. If a file descriptor number is produced instead, the pointer passed via ret_vp is NULL, the file descriptor is returned via ret_fd, and ret_domove returns a value that is true if the file descriptor should be moved rather than copied. These cases correspond to the internal errors EMOVEFD and EDUPFD, respectively. See errno(9) for more info. Callers that are unprepared to handle file descriptors can set ret_fd and ret_domove to NULL; in that case, an operation that would produce a file descriptor will instead fail with EOPNOTSUPP. 💀

vn_bdev_open(dev, vpp, l)

Opens a block device by its device number for reading and writing, and stores the vnode pointer into *vpp. l is the calling process. The vnode can be closed and freed with vn_close. 🧚

vn_bdev_openpath(pb, vpp, l)

Works like vn_bdev_open() but looks up a file system path pb to determine the device ID. 🦋

vn_rdwr(rw, vp, base, len, offset, segflg, ioflg, cred, aresid, l)

Common code to package up an I/O request on a vnode into a uio and then perform the I/O. rw specifies whether the I/O is a read (UIO_READ) or write (UIO_WRITE) operation. The vnode is vp. l and cred are the calling lwp and its credentials. If ioflg contains IO_NODELOCKED, it is expected that the vnode is locked. ioflg will be passed to VOP_READ()/VOP_WRITE(). The remaining arguments specify the uio parameters; for more on those, see uiomove(9). 🔥

vn_readdir(fp, buf, segflg, count, done, l, cookies, ncookies)

Common code for reading the contents of a directory. fp is the file structure, and buf is the buffer for placing the struct dirent structures. cookies and ncookies specify the addresses for the list and number of directory seek cookies generated for NFS. Both cookies and ncookies should be NULL if they aren't required to be returned by vn_readdir(). If it works, 0 is returned; otherwise you get an appropriate error code. 📂

vn_stat(vp, sb)

Common code for a vnode stat operation. The vnode is vp, and sb is the buffer for returning the stat information. vn_stat() basically calls the vnode operation VOP_GETATTR(9) and transfers the contents of a vattr structure into a struct stat. If it works, 0 is returned; otherwise you get an appropriate error code. 📊

vn_writechk(vp)

Common code to check for write permission on the vnode vp. A vnode is read-only if it is in use as a process's text image. If the vnode is read-only, ETEXTBSY is returned; otherwise 0 is returned to indicate that the vnode can be written to. ⚠️

---

💀 ERRORS 💀

• [EBUSY] — The LK_NOWAIT flag was set and vn_lock() would have slept. 😴
• [ENOENT] — The vnode has been reclaimed and is dead. This error is only returned if the LK_RETRY flag is not passed to vn_lock(). 🪦
• [ETXTBSY] — You can't write to a vnode because it is a process's text image. 🚫

---

🔥 CODE REFERENCES 🔥

The high-level convenience functions are implemented within sys/kern/vfs_vnops.c and sys/sys/vnode.h. 🛠️

---

🌈 SEE ALSO 🌈

file(9), intro(9), lock(9), namei(9), vattr(9), vfs(9), vnode(9), vnodeops(9) 💖

---

💖 okay that's the whole manual-page vibe check, bestie — this one is from Debian, dated June 28, 2021. mwah 💋