VOP_LOOKUP(9)

💖 VOP_LOOKUP — bestie's guide to looking up a pathname component 💖

okay so real quick, this is the <cyan>VOP_LOOKUP(9)</cyan> page from the Kernel Developer's Manual. yes it's a kernel vnode op, no it's not scary, we're gonna get through it together 🫶

---

✨ NAME ✨

VOP_LOOKUP — lookup a component of a pathname

like, ONE component. one. not the whole path. she does her one job and she does it gorgeously 💅

---

✨ SYNOPSIS ✨

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

int
VOP_LOOKUP(struct vnode *dvp, struct vnode **vpp,
    struct componentname *cnp);

---

✨ DESCRIPTION ✨

so this entry point looks up a single pathname component in a given directory. one component. that's her whole thing. she ate 💅

and her arguments are, in order:

• dvp — the locked vnode of the directory we're searching. she comes locked, bestie, don't touch.
• vpp — the address of a variable where the resulting locked vnode should be stored. yes, locked again. the lock theme is strong here.
• cnp — the pathname component we're searching for. it's a pointer to a componentname structure, which looks exactly like this:

struct componentname {
        /*
         * Arguments to lookup.
         */
        u_long  cn_nameiop;     /* namei operation */
        u_long  cn_flags;       /* flags to namei */
        struct  thread *cn_thread;      /* thread requesting lookup */
        struct  ucred *cn_cred; /* credentials */
        int     cn_lkflags;     /* Lock flags LK_EXCLUSIVE or LK_SHARED */
        /*
         * Shared between lookup and commit routines.
         */
        char    *cn_pnbuf;      /* pathname buffer */
        char    *cn_nameptr;    /* pointer to looked up name */
        long    cn_namelen;     /* length of looked up component */
};

Convert a component of a pathname into a pointer to a locked vnode. This is a very central and rather complicated routine. If the file system is not maintained in a strict tree hierarchy, this can result in a deadlock situation. 😭 (not a cute deadlock. there is no cute deadlock.)

the cnp->cn_nameiop argument is LOOKUP, CREATE, RENAME, or DELETE, depending on what the caller intends to do with the object. and when CREATE, RENAME, or DELETE is specified, info that's usable for creating, renaming, or deleting a directory entry may get calculated. slay.

here's the overall outline of VOP_LOOKUP, verbatim, because she deserves her full moment:

      Check accessibility of directory.  Look for name in cache, if
      found, then return name.  Search for name in directory, goto
      to found or notfound as appropriate.

notfound:

      If creating or renaming and at end of pathname, return
      EJUSTRETURN, leaving info on available slots else return
      ENOENT.

found:

      If at end of path and deleting, return information to allow
      delete.  If at end of path and renaming, lock target inode
      and return info to allow rename.  If not at end, add name to
      cache; if at end and neither creating nor deleting, add name
      to cache.

see? notfound and found. two paths. she's branching, she's serving, she's iconic 🌈

---

🔒 LOCKS 🔒

the directory dvp should be locked on entry and on exit, no matter what the error condition is. yes, even then. even when everything's on fire 💀

and if an entry is found in the directory, it gets returned locked. told you. lock girlie fr fr.

---

🌸 RETURN VALUES 🌸

zero comes back, with *vpp set to the locked vnode of the file, if the component is found. easy.

but here's the lil plot twist 👑 — if the component being searched for is ".", then the vnode just has an extra reference added to it with vref(9). the caller must take care to release the locks appropriately in this case. no skipping that step, bestie, that's how you get leaks.

and if the component isn't found, and the operation is CREATE or RENAME, and the flag ISLASTCN is specified, and the operation would succeed — then the special return value EJUSTRETURN is returned. otherwise you get an appropriate error code. that's the deal.

---

💀 ERRORS 💀

• [ENOTDIR] — the vnode dvp does not represent a directory. she's not a directory, she's just standing there.
• [ENOENT] — the component dvp was not found in this directory. it's giving nowhere to be found 🙈
• [EACCES] — access for the specified operation is denied. permission? denied. periodt.
• [EJUSTRETURN] — a CREATE or RENAME operation would be successful. bestie this one isn't even really an error, she's just built different ✨

---

👀 SEE ALSO 👀

vnode(9), VOP_ACCESS(9), VOP_CREATE(9), VOP_MKDIR(9), VOP_MKNOD(9), VOP_RENAME(9), VOP_SYMLINK(9)

the whole friend group. go read them, iykyk 💜

---

📜 HISTORY 📜

the function VOP_LOOKUP appeared in 4.3BSD. an elder. a legend. a true original 🎀

---

🫶 AUTHORS 🫶

this manual page was written by Doug Rabson, with some text from comments in ufs_lookup.c. thank you Doug, king behavior 👑

---

and that's the whole page, bestie!! this version came to you from the Debian crew, dated August 8, 2018, filed under VOP_LOOKUP(9). now go lock your vnodes properly, mwah 💖✨🦋