attach_recursive_mnt(9)

💅 attach_recursive_mnt(9) — Kernel API Manual, bestie edition ✨

okay so this is attach_recursive_mnt(9) from the Kernel API Manual, and it's genuinely one of those "attach a source mount tree" functions that looks scary but is so slay once you get it 💖

---

🎀 NAME

attach_recursive_mnt — attach a source mount tree 🌸

---

✨ SYNOPSIS

int attach_recursive_mnt (struct mount *source_mnt , const struct
       pinned_mountpoint *dest );

---

🫶 ARGUMENTS

• source_mnt — the mount tree you wanna attach, bestie 🌈
• dest — the context for mounting at the place where the tree should go ✨

---

💅 NOTE

so this next part is literally the vibe check table 👑 — it explains the semantics when a source mount of a given type is attached to a destination mount of a given type. read it carefully, no skipping 🙈

       ---------------------------------------------------------------------------
       |         BIND MOUNT OPERATION
       |
       |**************************************************************************
       | source-->| shared        |       private  |       slave    |
       unbindable | | dest     |               |                |
       |            | |   |      |               |                |
       |            | |   v      |               |                |
       |            |
       |**************************************************************************
       |  shared  | shared (++)   |     shared (+) |     shared(+++)|  invalid
       | |          |               |                |                |
       | |non-shared| shared (+)    |      private   |      slave (*) |
       invalid   |
       ***************************************************************************

A bind operation clones the source mount and mounts the clone on the destination mount. that's the whole bit 💫

Here's the legend, bestie 🍓:

• (++) — the cloned mount is propagated to all the mounts in the propagation tree of the destination mount, and the cloned mount is added to the peer group of the source mount 🔥
• (+) — the cloned mount is created under the destination mount and is marked as shared. the cloned mount is added to the peer group of the source mount ✨
• (+++) — the mount is propagated to all the mounts in the propagation tree of the destination mount, and the cloned mount is made slave of the same master as that of the source mount. the cloned mount is marked as 'shared and slave' 👑
• (*) — the cloned mount is made a slave of the same master as that of the source mount 💜

---

and now the move side of things 🦋:

       ---------------------------------------------------------------------------
       |                    MOVE MOUNT OPERATION
       |
       |**************************************************************************
       | source-->| shared        |       private  |       slave    |
       unbindable | | dest     |               |                |
       |            | |   |      |               |                |
       |            | |   v      |               |                |
       |            |
       |**************************************************************************
       |  shared  | shared (+)    |     shared (+) |    shared(+++) |  invalid
       | |          |               |                |                |
       | |non-shared| shared (+*)   |      private   |    slave (*)   |
       unbindable |
       ***************************************************************************

Legend for the move table, periodt 💅:

• (+) — the mount is moved to the destination. and is then propagated to all the mounts in the propagation tree of the destination mount 🌟
• (+*) — the mount is moved to the destination. that's it, that's the whole thing 💖
• (+++) — the mount is moved to the destination and is then propagated to all the mounts belonging to the destination mount's propagation tree. the mount is marked as 'shared and slave' 🎀
• (*) — the mount continues to be a slave at the new location 🧚

---

if the source mount is a tree, the operations explained above is applied to each mount in the tree 🌈 — like, every single one, no cap.

fr fr warning 🙈: must be called without spinlocks held, since this function can sleep in allocations. do nottt hold those spinlocks, bestie, it will not end well 😭

---

🔒 CONTEXT

The function expects namespace_lock to be held. that's non-negotiable, it's giving very "you must have the lock" energy 👑

---

⭐ RETURN

If source_mnt was successfully attached, 0 is returned 🎉. Otherwise a negative error code is returned 💀.

---

💜 SEE ALSO

Kernel file ./fs/namespace.c — and the whole friend group 💖:

• mnt_get_write_access(9)
• mnt_want_write(9)
• mnt_get_write_access_file(9)
• mnt_want_write_file(9)
• mnt_put_write_access(9)
• mnt_drop_write(9)
• mnt_hold_writers(9)
• mnt_unhold_writers(9)
• __lookup_mnt(9)
• lookup_mnt(9)
• attach_mnt(9)
• vfs_create_mount(9)
• path_is_mountpoint(9)
• may_umount_tree(9)
• may_umount(9)
• clone_private_mount(9)
• do_lock_mount(9)
• path_overmounted(9)
• can_move_mount_beneath(9)
• mnt_set_expiry(9)
• mnt_allow_writers(9)

---

kay that's the whole page, you ate that 🫶 go attach some mount trees responsibly, mwah 💋

source: ./fs — version vibes from October 2026, attach_recursive_mnt(9) ✨ periodt 💅