Improving inode number documentation

["Pali Rohár" <pali@kernel.org>]

Hello Alex,

I would like to ask you, could you improve documentation about inode
numbers returned by readdir()/getdents() and stat()/statx() functions?

https://man7.org/linux/man-pages/man3/readdir.3.html
https://man7.org/linux/man-pages/man2/readdir.2.html
https://man7.org/linux/man-pages/man2/getdents.2.html
https://man7.org/linux/man-pages/man2/stat.2.html
https://man7.org/linux/man-pages/man2/statx.2.html
https://man7.org/linux/man-pages/man3/stat.3type.html
https://man7.org/linux/man-pages/man7/inode.7.html

The missing information in those documentations is the fact that the
dirent.d_ino does not have to be same as stat.st_ino/statx.stx_ino for
the same file or dir.

stat.st_ino number belongs to the stat.st_dev but dirent.d_ino belongs
to the st_dev of the directory on which was called opendir().

So for the mount points these two numbers are different. readdir()
returns the inode number of the underlying directory (which belongs to
the parent filesystem), but the stat() returns the inode number of the
root directory of the upper/mounted filesystem.

And I think same applies for mount-binded files, not just for mounted
directories.

Note that this Linux behavior (when readdir and stat returns different
inode numbers) is in POSIX readdir() specification called "historical"
and is described in RATIONALE section of POSIX readdir:
https://pubs.opengroup.org/onlinepubs/9799919799/functions/readdir.html

Therefore it would be nice to mention the fact in Linux readdir(3)
documentation, that Linux conforms to POSIX "historical implementation".

Pali