[PATCH v3] 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>
Co-authored-by: Jan Kara <jack@suse.cz>
Cc: "G. Branden Robinson" <branden@debian.org>
Cc: <linux-fsdevel@vger.kernel.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

Hi Jan,

I've put your suggestions into the patch.  I've also removed the
sentence about POSIX, as Pali discussed with Branden.

At the bottom of the email is the range-diff against the previous
version.


Have a lovely day!
Alex

 man/man3/readdir.3      | 19 ++++++++++++++++++-
 man/man3type/stat.3type | 20 +++++++++++++++++++-
 2 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/man/man3/readdir.3 b/man/man3/readdir.3
index e1c7d2a6a..220643795 100644
--- a/man/man3/readdir.3
+++ b/man/man3/readdir.3
@@ -58,7 +58,24 @@ .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
+in the filesystem containing
+the directory on which
+.BR readdir ()
+was called.
+If the directory entry is the mount point,
+then
+.I .d_ino
+differs from
+.I .st_ino
+returned by
+.BR stat (2)
+on this file:
+.I .d_ino
+is the inode number of the mount point,
+while
+.I .st_ino
+is the inode number of the root directory of the mounted filesystem.
 .TP
 .I .d_off
 The value returned in
diff --git a/man/man3type/stat.3type b/man/man3type/stat.3type
index 76ee3765d..ea9acc5ec 100644
--- a/man/man3type/stat.3type
+++ b/man/man3type/stat.3type
@@ -66,7 +66,25 @@ .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
+in the filesystem on
+.IR .st_dev .
+If
+.BR stat (2)
+was called on the mount point,
+then
+.I .st_ino
+differs from
+.I .d_ino
+returned by
+.BR readdir (3)
+for the corresponding directory entry in the parent directory.
+In this case,
+.I .st_ino
+is the inode number of the root directory of the mounted filesystem,
+while
+.I .d_ino
+is the inode number of the mount point in the parent filesystem.
 .TP
 .I .st_mode
 This field contains the file type and mode.

Range-diff against v2:
1:  d3eeebe81 ! 1:  bfa7e72ea man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
    @@ Commit message
     
         Suggested-by: Pali Rohár <pali@kernel.org>
         Co-authored-by: Pali Rohár <pali@kernel.org>
    +    Co-authored-by: Jan Kara <jack@suse.cz>
         Cc: "G. Branden Robinson" <branden@debian.org>
         Cc: <linux-fsdevel@vger.kernel.org>
         Signed-off-by: Alejandro Colomar <alx@kernel.org>
    @@ man/man3/readdir.3: .SH DESCRIPTION
      .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
    ++This is the inode number of the file
    ++in the filesystem containing
    ++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 .st_ino
    ++returned by
    ++.BR stat (2)
    ++on this file:
     +.I .d_ino
    -+is the inode number of the underlying mount point,
    ++is the inode number of the 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.
    ++is the inode number of the root directory of the mounted filesystem.
      .TP
      .I .d_off
      The value returned in
    @@ man/man3type/stat.3type: .SH DESCRIPTION
      .TP
      .I .st_ino
     -This field contains the file's inode number.
    -+This field contains the file's inode number,
    -+which belongs to the
    ++This field contains the file's inode number
    ++in the filesystem on
     +.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.
    ++differs from
    ++.I .d_ino
    ++returned by
    ++.BR readdir (3)
    ++for the corresponding directory entry in the parent directory.
    ++In this case,
    ++.I .st_ino
    ++is the inode number of the root directory of the mounted filesystem,
    ++while
    ++.I .d_ino
    ++is the inode number of the mount point in the parent filesystem.
      .TP
      .I .st_mode
      This field contains the file type and mode.

base-commit: f305f7647d5cf62e7e764fb7a25c4926160c594f
-- 
2.51.0