take LOOKUP_{ROOT,ROOT_GRABBED,JUMPED} out of LOOKUP_... space

Separate field in nameidata (nd->state) holding the flags that
should be internal-only - that way we both get some spare bits
in LOOKUP_... and get simpler rules for nd->root lifetime rules,
since we can set the replacement of LOOKUP_ROOT (ND_ROOT_PRESET)
at the same time we set nd->root.

Signed-off-by: Al Viro <viro@zeniv.linux.org.uk>

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

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>

docs: path-lookup: update symlink description

instead of lookup_real()/vfs_create(), i_op->lookup() and
i_op->create() will be called directly.

update vfs_open() logic

should_follow_link is merged into lookup_last() or open_last_lookup()
which returns symlink name instead of an integer.

Signed-off-by: Fox Chen <foxhlchen@gmail.com>
Reviewed-by: NeilBrown <neilb@suse.de>
Link: https://lore.kernel.org/r/20210527091618.287093-13-foxhlchen@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: path-lookup: update get_link() ->follow_link description

get_link() is merged into pick_link(). i_op->follow_link is
replaced with i_op->get_link(). get_link() can return ERR_PTR(0)
which equals NULL.

Signed-off-by: Fox Chen <foxhlchen@gmail.com>
Reviewed-by: NeilBrown <neilb@suse.de>
Link: https://lore.kernel.org/r/20210527091618.287093-12-foxhlchen@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: path-lookup: update WALK_GET, WALK_PUT desc

WALK_GET is changed to WALK_TRAILING with a different meaning.
Here it should be WALK_NOFOLLOW. WALK_PUT dosn't exist, we have
WALK_MORE.

WALK_PUT == !WALK_MORE

And there is not should_follow_link().

Related commits:
commit 8c4efe22e7c4 ("namei: invert the meaning of WALK_FOLLOW")
commit 1c4ff1a87e46 ("namei: invert WALK_PUT logics")

Signed-off-by: Fox Chen <foxhlchen@gmail.com>
Reviewed-by: NeilBrown <neilb@suse.de>
[jc: applied language tweaks suggested by Neil]
Link: https://lore.kernel.org/r/20210527091618.287093-11-foxhlchen@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: path-lookup: no get_link()

no get_link() anymore. we have step_into() and pick_link().

walk_component() will call step_into(), in turn call pick_link,
and return symlink name.

Signed-off-by: Fox Chen <foxhlchen@gmail.com>
Reviewed-by: NeilBrown <neilb@suse.de>
Link: https://lore.kernel.org/r/20210527091618.287093-10-foxhlchen@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: path-lookup: update i_op->put_link and cookie description

No inode->put_link operation anymore. We use delayed_call to
deal with link destruction. Cookie has been replaced with
struct delayed_call.

Related commit: commit fceef393a538 ("switch ->get_link() to
delayed_call, kill ->put_link()")

Signed-off-by: Fox Chen <foxhlchen@gmail.com>
Reviewed-by: NeilBrown <neilb@suse.de>
Link: https://lore.kernel.org/r/20210527091618.287093-9-foxhlchen@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: path-lookup: i_op->follow_link replaced with i_op->get_link

follow_link has been replaced by get_link() which can be
called in RCU mode.

see commit: commit 6b2553918d8b ("replace ->follow_link() with
new method that could stay in RCU mode")

Signed-off-by: Fox Chen <foxhlchen@gmail.com>
Reviewed-by: NeilBrown <neilb@suse.de>
Link: https://lore.kernel.org/r/20210527091618.287093-8-foxhlchen@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: path-lookup: Add macro name to symlink limit description

Add macro name MAXSYMLINKS to the symlink limit description, so
that it is consistent with path name length description above.

Signed-off-by: Fox Chen <foxhlchen@gmail.com>
Reviewed-by: NeilBrown <neilb@suse.de>
Link: https://lore.kernel.org/r/20210527091618.287093-7-foxhlchen@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: path-lookup: remove filename_mountpoint

No filename_mountpoint any more
see commit: commit 161aff1d93ab ("LOOKUP_MOUNTPOINT:
fold path_mountpointat() into path_lookupat()")

Without filename_mountpoint and path_mountpoint(), the
numbers should be four & three:

"These four correspond roughly to the three path_*() functions"

Signed-off-by: Fox Chen <foxhlchen@gmail.com>
Reviewed-by: NeilBrown <neilb@suse.de>
Link: https://lore.kernel.org/r/20210527091618.287093-6-foxhlchen@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: path-lookup: update do_last() part

traling_symlink() was merged into lookup_last, do_last().

do_last() has later been split into open_last_lookups()
and do_open().

see related commit: commit c5971b8c6354 ("take post-lookup
part of do_last() out of loop")

Signed-off-by: Fox Chen <foxhlchen@gmail.com>
Reviewed-by: NeilBrown <neilb@suse.de>
Link: https://lore.kernel.org/r/20210527091618.287093-5-foxhlchen@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: path-lookup: update path_mountpoint() part

path_mountpoint() doesn't exist anymore. Have been folded
into path_lookup_at when flag is set with LOOKUP_MOUNTPOINT.
Check commit: commit 161aff1d93abf0e ("LOOKUP_MOUNTPOINT: fold
path_mountpointat() into path_lookupat()")

Signed-off-by: Fox Chen <foxhlchen@gmail.com>
Reviewed-by: NeilBrown <neilb@suse.de>
Link: https://lore.kernel.org/r/20210527091618.287093-4-foxhlchen@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: path-lookup: update path_to_nameidata() part

No path_to_namei() anymore, step_into() will be called.
Related commit: commit c99687a03a78 ("fold path_to_nameidata()
into its only remaining caller")

Signed-off-by: Fox Chen <foxhlchen@gmail.com>
Reviewed-by: NeilBrown <neilb@suse.de>
Link: https://lore.kernel.org/r/20210527091618.287093-3-foxhlchen@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: path-lookup: update follow_managed() part

No follow_managed() anymore, handle_mounts(),
traverse_mounts(), will do the job.
see commit 9deed3ebca24 ("new helper: traverse_mounts()")

Signed-off-by: Fox Chen <foxhlchen@gmail.com>
Reviewed-by: NeilBrown <neilb@suse.de>
Link: https://lore.kernel.org/r/20210527091618.287093-2-foxhlchen@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: path-lookup: markup fixes for emphasis

Underscores were being used for emphasis, but these are rendered verbatim
in HTML output. reStructuredText uses asterisks for emphasis. I *think* I
caught all of them.

Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Link: https://lore.kernel.org/r/20200727121525.28103-2-vegard.nossum@oracle.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: path-lookup: more markup fixes

"xxx``at``" makes the `` appear verbatim in the HTML output. I've opted
for changing this into ``*at()`` to harmonise this with the use of * seen
later in the same document (and add the parentheses to clarify that this
is a system/function call).

``path_``* also makes `` appear in the HTML output, but we can fix it by
moving the * into the ``. Also add the parantheses here.

Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Link: https://lore.kernel.org/r/20200727121525.28103-1-vegard.nossum@oracle.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: path-lookup: fix HTML entity mojibake

Two cases of "<" somehow turned into "&lt;". I noticed it on
<https://www.kernel.org/doc/html/latest/filesystems/path-lookup.html>.

I've verified that the HTML output is correct with this patch.

Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Link: https://lore.kernel.org/r/20200727114527.23944-1-vegard.nossum@oracle.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: filesystems: path-lookup: drop doubled word

Drop the doubled word "to".

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Alexander Viro <viro@zeniv.linux.org.uk>
Cc: linux-fsdevel@vger.kernel.org
Link: https://lore.kernel.org/r/20200703214325.31036-9-rdunlap@infradead.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Replace HTTP links with HTTPS ones: Documentation/filesystems

Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.

Deterministic algorithm:
For each file:
If not .svg:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.

Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200621133552.46371-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

sanitize handling of nd->last_type, kill LAST_BIND

->last_type values are set in 3 places: path_init() (sets to LAST_ROOT),
link_path_walk (LAST_NORM/DOT/DOTDOT) and pick_link (LAST_BIND).

The are checked in walk_component(), lookup_last() and do_last().
They also get copied to the caller by filename_parentat(). In the last
3 cases the value is what we had at the return from link_path_walk().
In case of walk_component() it's either directly downstream from
assignment in link_path_walk() or, when called by lookup_last(), the
value we have at the return from link_path_walk().

The value at the entry into link_path_walk() can survive to return only
if the pathname contains nothing but slashes. Note that pick_link()
never returns such - pure jumps are handled directly. So for the calls
of link_path_walk() for trailing symlinks it does not matter what value
had been there at the entry; the value at the return won't depend upon it.

There are 3 call chains that might have pick_link() storing LAST_BIND:

1) pick_link() from step_into() from walk_component() from
link_path_walk(). In that case we will either be parsing the next
component immediately after return into link_path_walk(), which will
overwrite the ->last_type before anyone has a chance to look at it,
or we'll fail, in which case nobody will be looking at ->last_type at all.

2) pick_link() from step_into() from walk_component() from lookup_last().
The value is never looked at due to the above; it won't affect the value
seen at return from any link_path_walk().

3) pick_link() from step_into() from do_last(). Ditto.

In other words, assignemnt in pick_link() is pointless, and so is
LAST_BIND itself; nothing ever looks at that value. Kill it off.
And make link_path_walk() _always_ assign ->last_type - in the only
case when the value at the entry might survive to the return that value
is always LAST_ROOT, inherited from path_init(). Move that assignment
from path_init() into the beginning of link_path_walk(), to consolidate
the things.

Historical note: LAST_BIND used to be used for the kludge with trailing
pure jump symlinks (extra iteration through the top-level loop).
No point keeping it anymore...

Signed-off-by: Al Viro <viro@zeniv.linux.org.uk>

Documentation: path-lookup: include new LOOKUP flags

Now that we have new LOOKUP flags, we should document them in the
relevant path-walking documentation. And now that we've settled on a
common name for nd_jump_link() style symlinks ("magic links"), use that
term where magic-link semantics are described.

Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
Signed-off-by: Al Viro <viro@zeniv.linux.org.uk>

docs: Bring some order to filesystem documentation

Documentation/filesystems is, like much of the rest of the kernel's
documentation, a jumble of unorganized information. Split the
documentation into categories and try to bring some order to the top-level
index.rst files. No text changes other than a few section-introductory
blurbs; this is all just moving stuff around.

Cc: linux-fsdevel@vger.kernel.org
Cc: Al Viro <viro@zeniv.linux.org.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/filesystems: fix title underline lengths in path-lookup.rst

Fix Sphinx warnings in path-lookup.rst:

Documentation/filesystems/path-lookup.rst:347: WARNING: Title underline too short.
Documentation/filesystems/path-lookup.rst:358: WARNING: Title underline too short.
[...]

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: NeilBrown <neilb@suse.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: improve pathname-lookup document structure

Get rid of some unneeded structural elements around the new (to RST)
pathname-lookup document.

Signed-off-by: NeilBrown <neilb@suse.com>
[ jc: grabbed from email and changelog added ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: convert path-lookup from markdown to resturctured text

This allows the document to be integrated with the main documentation
tree.
Changes include:
- rename from .md to .rst
- use `` for code, not single `
- use correct sub-section marking
- fix indented blocks, both code and non-code
- fix external-link markup

Signed-off-by: NeilBrown <neilb@suse.com>
[jc: changed the toctree organization a bit]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>