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

["Darrick J. Wong" <djwong@kernel.org>]

On Fri, Oct 31, 2025 at 11:44:14AM +0100, Alejandro Colomar wrote:
> 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,

nitpicking english:

"...is a mount point," ?

--D

> +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
> 
>