[PATCH v2] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino

[Alejandro Colomar <alx@kernel.org>]

Suggested-by: Pali Rohár <pali@kernel.org>
Co-authored-by: Pali Rohár <pali@kernel.org>
Cc: "G. Branden Robinson" <branden@debian.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

Hi Jan,

Would you mind reviewing this?  The thread started here:
<https://lore.kernel.org/linux-man/20250525103344.fe27ugiytfyoadz5@pali/T/#u>.

Hi Branden,

I wasn't able to do anything after your request from
<https://lore.kernel.org/linux-man/20250525103344.fe27ugiytfyoadz5@pali/T/#m1bd706844fd322b2b0f9090ceac68e7ba29200eb>.
Pali will probably be better placed to do that, since he authored that
text.

Hi Pali,

Sorry for being so slow with this!  I wasn't able to work on this until
now.


Have a lovely night!
Alex

 man/man3/readdir.3      | 22 +++++++++++++++++++++-
 man/man3type/stat.3type | 16 +++++++++++++++-
 2 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/man/man3/readdir.3 b/man/man3/readdir.3
index e1c7d2a6a..368e98e6e 100644
--- a/man/man3/readdir.3
+++ b/man/man3/readdir.3
@@ -58,7 +58,27 @@ .SH DESCRIPTION
 structure are as follows:
 .TP
 .I .d_ino
-This is the inode number of the file.
+This is the inode number of the file,
+which belongs to the filesystem
+.I .st_dev
+(see
+.BR stat (3type))
+of the directory on which
+.BR readdir ()
+was called.
+If the directory entry is the mount point,
+then
+.I .d_ino
+differs from
+.IR .st_ino :
+.I .d_ino
+is the inode number of the underlying mount point,
+while
+.I .st_ino
+is the inode number of the mounted file system.
+According to POSIX,
+this Linux behavior is considered to be a bug,
+but is nevertheless conforming.
 .TP
 .I .d_off
 The value returned in
diff --git a/man/man3type/stat.3type b/man/man3type/stat.3type
index f3c312bf0..b87195766 100644
--- a/man/man3type/stat.3type
+++ b/man/man3type/stat.3type
@@ -66,7 +66,21 @@ .SH DESCRIPTION
 macros may be useful to decompose the device ID in this field.)
 .TP
 .I .st_ino
-This field contains the file's inode number.
+This field contains the file's inode number,
+which belongs to the
+.IR .st_dev .
+If
+.BR stat (2)
+was called on the mount point,
+then
+.I .d_ino
+differs from
+.IR .st_ino :
+.I .d_ino
+is the inode number of the underlying mount point,
+while
+.I .st_ino
+is the inode number of the mounted file system.
 .TP
 .I .st_mode
 This field contains the file type and mode.

base-commit: abac986a3283e679b6b323f58ab6677bc49a05e0
-- 
2.51.0