vfs_rename(9)

💅 vfs_rename(9) — straight outta the Kernel API Manual ✨

okay bestie, buckle up: this is vfs_rename(9), the manpage about renaming filesystem objects, and she is a lot. 🎀

🦋 NAME 🦋

vfs_rename — rename a filesystem object 🔥

✨ SYNOPSIS ✨

int vfs_rename (struct renamedata *rd );

🎀 ARGUMENTS 🎀

• rd — pointer to struct renamedata info. that’s the vibe check, bestie 🫶

💖 DESCRIPTION 💖

First things first: the caller must hold multiple mutexes — see lock_rename). 🔒😭

If vfs_rename discovers a delegation in need of breaking at either the source or destination, it will return -EWOULDBLOCK and return a reference to the inode in delegated_inode. The caller should then break the delegation and retry. Because breaking a delegation may take a long time, the caller should drop all locks before doing so. 🌀💀

Alternatively, a caller may pass NULL for delegated_inode. This may be appropriate for callers that expect the underlying filesystem not to be NFS exported. 🙈✨

Then we get to the absolute worst of all namespace operations — renaming a directory. "Perverted" doesn’t even start to describe it. Somebody in UCB had a heck of a trip... Problems: 😵‍💫

• a) we can get into loop creation. 🔁
• b) race potential — two innocent renames can create a loop together. That’s where 4.4BSD screws up. Current fix: serialization on sb->s_vfs_rename_mutex. We might be more accurate, but that’s another story. 🌪️
• c) we may have to lock up to four objects — parents and victim (if it exists), and source (if it’s a non-directory or a subdirectory that moves to different parent). And that — after we got ->i_rwsem on parents (until then we don’t know whether the target exists). Solution: try to be smart with locking order for inodes. We rely on the fact that tree topology may change only under ->s_vfs_rename_mutex and that parent of the object we move will be locked. Thus we can rank directories by the tree (ancestors first) and rank all non-directories after them. That works since everybody except rename does "lock parent, lookup, lock child" and rename is under ->s_vfs_rename_mutex. HOWEVER, it relies on the assumption that any object with ->lookup has no more than 1 dentry. If "hybrid" objects will ever appear, we’d better make sure that there’s no link(2) for them. 🔐👑
• d) conversion from fhandle to dentry may come in the wrong moment — when we are removing the target. Solution: we will have to grab ->i_rwsem in the fhandle_to_dentry code. [FIXME - current nfsfh.c relies on ->i_rwsem on parents, which works but leads to some truly excessive locking] 😭🔥

🌈 SEE ALSO 🌈

• Kernel file ./fs/namei.c 👀
• check_acl(9), acl_permission_check(9), generic_permission(9), do_inode_permission(9), sb_permission(9), inode_permission(9)
• path_get(9), path_put(9), path_connected(9), try_to_unlazy(9), try_to_unlazy_next(9), complete_walk(9), may_follow_link(9), safe_hardlink_source(9), may_linkat(9), may_create_in_sticky(9), lookup_fast(9)
• start_dirop(9), end_dirop(9), kern_path_parent(9), vfs_path_parent_lookup(9), vfs_path_lookup(9), try_lookup_noperm(9), lookup_noperm(9), lookup_one(9), lookup_one_unlocked(9), lookup_one_positive_killable(9), lookup_one_positive_unlocked(9), lookup_noperm_unlocked(9)
• start_creating(9), start_removing(9), start_creating_killable(9), start_removing_killable(9), start_creating_noperm(9), start_removing_noperm(9), start_creating_dentry(9), start_removing_dentry(9), __start_renaming(9), start_renaming(9), start_renaming_dentry(9), start_renaming_two_dentries(9)
• vfs_prepare_mode(9), vfs_create(9), atomic_open(9), vfs_lookup_open(9), vfs_tmpfile(9), kernel_tmpfile_open(9), end_creating_path(9), dentry_create(9), vfs_mknod(9), vfs_mkdir(9), vfs_rmdir(9), vfs_unlink(9), vfs_symlink(9), vfs_link(9), vfs_readlink(9), vfs_get_link(9), page_get_link(9), page_put_link(9)

💖 and that’s the whole vfs_rename(9) saga, bestie. The footer bits say source/version ./fs and date October 2026 — iconic, no cap. 🎀✨🫶