diff mbox series

[v2,3/5] fs: fix __lookup_mnt() documentation

Message ID 20230202-fs-move-mount-replace-v2-3-f53cd31d6392@kernel.org (mailing list archive)
State Mainlined, archived
Headers show
Series fs: allow to mount beneath top mount | expand

Commit Message

Christian Brauner March 28, 2023, 4:13 p.m. UTC
The comment on top of __lookup_mnt() states that it finds the first
mount implying that there could be multiple mounts mounted at the same
dentry with the same parent.

This was true on old kernels where __lookup_mnt() could encounter a
stack of child mounts such that each child had the same parent mount and
was mounted at the same dentry. These were called "shadow mounts" and
were created during mount propagation. So back then if a mount @m in the
destination propagation tree already had a child mount @p mounted at
@mp then any mount @n we propagated to @m at the same @mp would be
appended after the preexisting mount @p in @mount_hashtable.

This hasn't been the case for quite a while now and I don't see an
obvious way how such mount stacks could be created in another way. And
if that's possible it would invalidate assumptions made in other parts
of the code.

So for a long time on all relevant kernels the child-parent relationship
is unique per dentry. So given a child mount @c mounted at its parent
mount @p on dentry @mp means that @c is the only child mounted on
@p at @mp. Should a mount @m be propagated to @p on @mp then @m will be
mounted on @p at @mp and the preexisting child @c will be remounted on
top of @m at @m->mnt_root.

Signed-off-by: Christian Brauner <brauner@kernel.org>
---
 fs/namespace.c | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

Comments

Seth Forshee April 5, 2023, 7:32 p.m. UTC | #1
On Tue, Mar 28, 2023 at 06:13:08PM +0200, Christian Brauner wrote:
> The comment on top of __lookup_mnt() states that it finds the first
> mount implying that there could be multiple mounts mounted at the same
> dentry with the same parent.
> 
> This was true on old kernels where __lookup_mnt() could encounter a
> stack of child mounts such that each child had the same parent mount and
> was mounted at the same dentry. These were called "shadow mounts" and
> were created during mount propagation. So back then if a mount @m in the
> destination propagation tree already had a child mount @p mounted at
> @mp then any mount @n we propagated to @m at the same @mp would be
> appended after the preexisting mount @p in @mount_hashtable.
> 
> This hasn't been the case for quite a while now and I don't see an
> obvious way how such mount stacks could be created in another way. And
> if that's possible it would invalidate assumptions made in other parts
> of the code.
> 
> So for a long time on all relevant kernels the child-parent relationship
> is unique per dentry. So given a child mount @c mounted at its parent
> mount @p on dentry @mp means that @c is the only child mounted on
> @p at @mp. Should a mount @m be propagated to @p on @mp then @m will be
> mounted on @p at @mp and the preexisting child @c will be remounted on
> top of @m at @m->mnt_root.
> 
> Signed-off-by: Christian Brauner <brauner@kernel.org>

I've been confused by the comment on __lookup_mnt() before, so this is a
helpful update.

Reviewed-by: Seth Forshee (DigitalOcean) <sforshee@kernel.org>
diff mbox series

Patch

diff --git a/fs/namespace.c b/fs/namespace.c
index 154569fd7343..42dc87f86f34 100644
--- a/fs/namespace.c
+++ b/fs/namespace.c
@@ -658,9 +658,16 @@  static bool legitimize_mnt(struct vfsmount *bastard, unsigned seq)
 	return false;
 }
 
-/*
- * find the first mount at @dentry on vfsmount @mnt.
- * call under rcu_read_lock()
+/**
+ * __lookup_mnt - find child mount
+ * @mnt:	parent mount
+ * @dentry:	mountpoint
+ *
+ * If @mnt has a child mount mounted @dentry find and return it. If a
+ * mount is found it is unique, i.e., there are no shadow child mounts
+ * with @mnt as parent and mounted at @dentry.
+ *
+ * Return: The child of @mnt mounted @dentry or NULL if there is none.
  */
 struct mount *__lookup_mnt(struct vfsmount *mnt, struct dentry *dentry)
 {