iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: path-lookup: use bare function() rather than literals

Browse Source 
As suggested by Matthew Wilcox and Jonathan Corbet, drop ``...``
literals around function names of this patchset.

Signed-off-by: Fox Chen <foxhlchen@gmail.com>
Reviewed-by: NeilBrown <neilb@suse.de>
Link: https://lore.kernel.org/r/20210527091618.287093-14-foxhlchen@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Fox Chen 2021-05-27 17:16:18 +08:00 committed by Jonathan Corbet
parent ef4aa53f36
commit 8943474a41
1 changed files with 35 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
Documentation/filesystems/path-lookup.rst
View File

@ -450,13 +450,13 @@ 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.
As the last step of ``walk_component()``, ``step_into()`` will be called either
As the last step of walk_component(), step_into() will be called either
directly from walk_component() or from handle_dots(). It calls
``handle_mounts()``, to check and handle mount points, in which a new
handle_mounts(), to check and handle mount points, in which a new
``struct path`` is created containing a counted reference to the new dentry and
a reference to the new ``vfsmount`` which is only counted if it is
different from the previous ``vfsmount``. Then if there is
a symbolic link, ``step_into()`` calls ``pick_link()`` to deal with it,
a symbolic link, step_into() calls pick_link() to deal with it,
otherwise it installs the new ``struct path`` in the ``struct nameidata``, and
drops the unneeded references.
@ -472,8 +472,8 @@ Handling the final component
``nd->last_type`` to refer to the final component of the path. It does
not call ``walk_component()`` that last time. Handling that final
component remains for the caller to sort out. Those callers are
``path_lookupat()``, ``path_parentat()`` and
``path_openat()`` each of which handles the differing requirements of
path_lookupat(), path_parentat() and
path_openat() each of which handles the differing requirements of
different system calls.
``path_parentat()`` is clearly the simplest - it just wraps a little bit
@ -489,17 +489,17 @@ object is wanted such as by ``stat()`` or ``chmod()``. It essentially just
calls ``walk_component()`` on the final component through a call to
``lookup_last()``. ``path_lookupat()`` returns just the final dentry.
It is worth noting that when flag ``LOOKUP_MOUNTPOINT`` is set,
``path_lookupat()`` will unset LOOKUP_JUMPED in nameidata so that in the
subsequent path traversal ``d_weak_revalidate()`` won't be called.
path_lookupat() will unset LOOKUP_JUMPED in nameidata so that in the
subsequent path traversal d_weak_revalidate() won't be called.
This is important when unmounting a filesystem that is inaccessible, such as
one provided by a dead NFS server.
Finally ``path_openat()`` is used for the ``open()`` system call; it
contains, in support functions starting with "``open_last_lookups()``", all the
contains, in support functions starting with "open_last_lookups()", all the
complexity needed to handle the different subtleties of O_CREAT (with
or without O_EXCL), final "``/``" characters, and trailing symbolic
links. We will revisit this in the final part of this series, which
focuses on those symbolic links. "``open_last_lookups()``" will sometimes, but
focuses on those symbolic links. "open_last_lookups()" will sometimes, but
not always, take ``i_rwsem``, depending on what it finds.
Each of these, or the functions which call them, need to be alert to
@ -651,9 +651,9 @@ RCU-walk finds it cannot stop gracefully, it simply gives up and
restarts from the top with REF-walk.
This pattern of "try RCU-walk, if that fails try REF-walk" can be
clearly seen in functions like ``filename_lookup()``,
``filename_parentat()``,
``do_filp_open()``, and ``do_file_open_root()``. These four
clearly seen in functions like filename_lookup(),
filename_parentat(),
do_filp_open(), and do_file_open_root(). These four
correspond roughly to the three ``path_*()`` functions we met earlier,
each of which calls ``link_path_walk()``. The ``path_*()`` functions are
called using different mode flags until a mode is found which works.
@ -1069,8 +1069,8 @@ all the data structures it references are safe to be accessed while
holding no counted reference, only the RCU lock. A callback
``struct delayed_called`` will be passed to ``->get_link()``:
file systems can set their own put_link function and argument through
``set_delayed_call()``. Later on, when VFS wants to put link, it will call
``do_delayed_call()`` to invoke that callback function with the argument.
set_delayed_call(). Later on, when VFS wants to put link, it will call
do_delayed_call() to invoke that callback function with the argument.
In order for the reference to each symlink to be dropped when the walk completes,
whether in RCU-walk or REF-walk, the symlink stack needs to contain,
@ -1103,7 +1103,7 @@ doesn't need to notice. Getting this ``name`` variable on and off the
stack is very straightforward; pushing and popping the references is
a little more complex.
When a symlink is found, ``walk_component()`` calls ``pick_link()`` via ``step_into()``
When a symlink is found, walk_component() calls pick_link() via step_into()
which returns the link from the filesystem.
Providing that operation is successful, the old path ``name`` is placed on the
stack, and the new value is used as the ``name`` for a while. When the end of
@ -1136,10 +1136,10 @@ Symlinks with no final component
A pair of special-case symlinks deserve a little further explanation.
Both result in a new ``struct path`` (with mount and dentry) being set
up in the ``nameidata``, and result in ``pick_link()`` returning ``NULL``.
up in the ``nameidata``, and result in pick_link() returning ``NULL``.
The more obvious case is a symlink to "``/``". All symlinks starting
with "``/``" are detected in ``pick_link()`` which resets the ``nameidata``
with "``/``" are detected in pick_link() which resets the ``nameidata``
to point to the effective filesystem root. If the symlink only
contains "``/``" then there is nothing more to do, no components at all,
so ``NULL`` is returned to indicate that the symlink can be released and
@ -1157,9 +1157,9 @@ target file, not just the name of it. When you ``readlink`` these
objects you get a name that might refer to the same file - unless it
has been unlinked or mounted over. When ``walk_component()`` follows
one of these, the ``->get_link()`` method in "procfs" doesn't return
a string name, but instead calls ``nd_jump_link()`` which updates the
a string name, but instead calls nd_jump_link() which updates the
``nameidata`` in place to point to that target. ``->get_link()`` then
returns ``NULL``. Again there is no final component and ``pick_link()``
returns ``NULL``. Again there is no final component and pick_link()
returns ``NULL``.
Following the symlink in the final component
@ -1177,35 +1177,35 @@ potentially need to call ``link_path_walk()`` again and again on
successive symlinks until one is found that doesn't point to another
symlink.
This case is handled by relevant callers of ``link_path_walk()``, such as
``path_lookupat()``, ``path_openat()`` using a loop that calls ``link_path_walk()``,
and then handles the final component by calling ``open_last_lookups()`` or
``lookup_last()``. If it is a symlink that needs to be followed,
``open_last_lookups()`` or ``lookup_last()`` will set things up properly and
This case is handled by relevant callers of link_path_walk(), such as
path_lookupat(), path_openat() using a loop that calls link_path_walk(),
and then handles the final component by calling open_last_lookups() or
lookup_last(). If it is a symlink that needs to be followed,
open_last_lookups() or lookup_last() will set things up properly and
return the path so that the loop repeats, calling
``link_path_walk()`` again. This could loop as many as 40 times if the last
link_path_walk() again. This could loop as many as 40 times if the last
component of each symlink is another symlink.
Of the various functions that examine the final component,
``open_last_lookups()`` is the most interesting as it works in tandem
with ``do_open()`` for opening a file. Part of ``open_last_lookups()`` runs
with ``i_rwsem`` held and this part is in a separate function: ``lookup_open()``.
open_last_lookups() is the most interesting as it works in tandem
with do_open() for opening a file. Part of open_last_lookups() runs
with ``i_rwsem`` held and this part is in a separate function: lookup_open().
Explaining ``open_last_lookups()`` and ``do_open()`` completely is beyond the scope
Explaining open_last_lookups() and do_open() completely is beyond the scope
of this article, but a few highlights should help those interested in exploring
the code.
1. Rather than just finding the target file, ``do_open()`` is used after
``open_last_lookup()`` to open
1. Rather than just finding the target file, do_open() is used after
open_last_lookup() to open
it. If the file was found in the dcache, then ``vfs_open()`` is used for
this. If not, then ``lookup_open()`` will either call ``atomic_open()`` (if
the filesystem provides it) to combine the final lookup with the open, or
will perform the separate ``i_op->lookup()`` and ``i_op->create()`` steps
directly. In the later case the actual "open" of this newly found or
created file will be performed by ``vfs_open()``, just as if the name
created file will be performed by vfs_open(), just as if the name
were found in the dcache.
2. ``vfs_open()`` can fail with ``-EOPENSTALE`` if the cached information
2. vfs_open() can fail with ``-EOPENSTALE`` if the cached information
wasn't quite current enough. If it's in RCU-walk ``-ECHILD`` will be returned
otherwise ``-ESTALE`` is returned. When ``-ESTALE`` is returned, the caller may
retry with ``LOOKUP_REVAL`` flag set.
@ -1218,8 +1218,8 @@ the code.
will create a file called ``/tmp/bar``. This is not permitted if
``O_EXCL`` is set but otherwise is handled for an O_CREAT open much
like for a non-creating open: ``lookup_last()`` or ``open_last_lookup()``
returns a non ``NULL`` value, and ``link_path_walk()`` gets called and the
like for a non-creating open: lookup_last() or open_last_lookup()
returns a non ``NULL`` value, and link_path_walk() gets called and the
open process continues on the symlink that was found.
Updating the access time