From: NeilBrown <neilb@suse.de>
To: Fox Chen <foxhlchen@gmail.com>,
corbet@lwn.net, vegard.nossum@oracle.com,
viro@zeniv.linux.org.uk, rdunlap@infradead.org,
grandmaster@al2klimov.de
Cc: Fox Chen <foxhlchen@gmail.com>,
linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH 01/12] docs: path-lookup: update follow_managed() part
Date: Thu, 28 Jan 2021 14:20:59 +1100 [thread overview]
Message-ID: <87h7n1hhlw.fsf@notabene.neil.brown.name> (raw)
In-Reply-To: <20210126072443.33066-2-foxhlchen@gmail.com>
[-- Attachment #1: Type: text/plain, Size: 2668 bytes --]
On Tue, Jan 26 2021, Fox Chen wrote:
> No follow_managed() anymore, handle_mounts(),
> traverse_mounts(), will do the job.
> see commit: 9deed3ebca244663530782631834e706a86a8c8f
>
> Signed-off-by: Fox Chen <foxhlchen@gmail.com>
> ---
> Documentation/filesystems/path-lookup.rst | 6 +++---
> 1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/filesystems/path-lookup.rst b/Documentation/filesystems/path-lookup.rst
> index c482e1619e77..e778db767120 100644
> --- a/Documentation/filesystems/path-lookup.rst
> +++ b/Documentation/filesystems/path-lookup.rst
> @@ -448,8 +448,8 @@ described. If it finds a ``LAST_NORM`` component it first calls
> filesystem to revalidate the result if it is that sort of filesystem.
> If that doesn't get a good result, it calls "``lookup_slow()``" which
> takes ``i_rwsem``, rechecks the cache, and then asks the filesystem
> -to find a definitive answer. Each of these will call
> -``follow_managed()`` (as described below) to handle any mount points.
> +to find a definitive answer. In ``step_into()``, ``handle_mount()`` will be
> +called to handle any mount point.
The text now introduces step_into() without any hint as to why that is
relevant at this point.
It is a bit awkward to explain succinctly because while lookup_fast and
lookup_slow return a dentry which is passed to step_into(), handle_dots()
calls step_into() itself.
This is a general problem with this sort of documentation. It weaves a
story and when the code changes, you might need to completely re-weave
the story.
I don't have a good suggestion for how to fix this text, but at the
least it needs to be made clear the walk_component() calls step_into(),
either directly or via handle_dots().
>
> In the absence of symbolic links, ``walk_component()`` creates a new
> ``struct path`` containing a counted reference to the new dentry and a
> @@ -536,7 +536,7 @@ tree, but a few notes specifically related to path lookup are in order
> here.
>
> The Linux VFS has a concept of "managed" dentries which is reflected
> -in function names such as "``follow_managed()``". There are three
> +in function names such as "``traverse_mounts()``". There are three
Here you've completely broken the story. Saying
The VFS has a concept of "managed" dentries which is reflected in
function names like "traverse_mounts()"
makes no sense at all.
Again, I cannot offer any quick fix.
NeilBrown
> potentially interesting things about these dentries corresponding
> to three different flags that might be set in ``dentry->d_flags``:
>
> --
> 2.30.0
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 853 bytes --]
next prev parent reply other threads:[~2021-01-28 3:21 UTC|newest]
Thread overview: 26+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-01-26 7:24 [PATCH 00/12] docs: path-lookup: Update pathlookup docs Fox Chen
2021-01-26 7:24 ` [PATCH 01/12] docs: path-lookup: update follow_managed() part Fox Chen
2021-01-26 14:03 ` Greg KH
2021-01-27 1:11 ` Fox Chen
2021-01-28 3:20 ` NeilBrown [this message]
2021-01-26 7:24 ` [PATCH 02/12] docs: path-lookup: update path_to_nameidata() parth Fox Chen
2021-01-28 3:24 ` NeilBrown
2021-01-26 7:24 ` [PATCH 03/12] docs: path-lookup: update path_mountpoint() part Fox Chen
2021-01-28 3:28 ` NeilBrown
2021-01-26 7:24 ` [PATCH 04/12] docs: path-lookup: update do_last() part Fox Chen
2021-01-28 3:50 ` NeilBrown
2021-01-26 7:24 ` [PATCH 05/12] docs: path-lookup: remove filename_mountpoint Fox Chen
2021-01-26 7:24 ` [PATCH 06/12] docs: path-lookup: Add macro name to symlink limit description Fox Chen
2021-01-26 7:24 ` [PATCH 07/12] docs: path-lookup: i_op->follow_link replaced with i_op->get_link Fox Chen
2021-01-28 3:53 ` NeilBrown
2021-01-26 7:24 ` [PATCH 08/12] docs: path-lookup: update i_op->put_link and cookie description Fox Chen
2021-01-28 3:50 ` NeilBrown
2021-01-26 7:24 ` [PATCH 09/12] docs: path-lookup: no get_link() Fox Chen
2021-01-26 7:24 ` [PATCH 10/12] docs: path-lookup: update WALK_GET, WALK_PUT desc Fox Chen
2021-01-26 7:24 ` [PATCH 11/12] docs: path-lookup: update get_link() ->follow_link description Fox Chen
2021-01-26 7:24 ` [PATCH 12/12] docs: path-lookup: update symlink description Fox Chen
2021-01-26 7:30 ` [PATCH 00/12] docs: path-lookup: Update pathlookup docs Fox Chen
2021-01-26 20:31 ` Jonathan Corbet
2021-01-28 1:23 ` Fox Chen
2021-01-28 3:58 ` NeilBrown
2021-01-29 1:29 ` Fox Chen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87h7n1hhlw.fsf@notabene.neil.brown.name \
--to=neilb@suse.de \
--cc=corbet@lwn.net \
--cc=foxhlchen@gmail.com \
--cc=grandmaster@al2klimov.de \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=rdunlap@infradead.org \
--cc=vegard.nossum@oracle.com \
--cc=viro@zeniv.linux.org.uk \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).