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

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

On Friday 31 October 2025 12:31:41 Alejandro Colomar wrote:
> Hi Jan, Pali,
> 
> On Fri, Oct 31, 2025 at 11:56:19AM +0100, Jan Kara wrote:
> > On Fri 31-10-25 11:44:14, 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.
> > 
> > Thanks! The patch looks good. Feel free to add:
> > 
> > Reviewed-by: Jan Kara <jack@suse.cz>
> 
> Thanks!
> 
> Pali, would you mind signing the patch?  One you do, I'll merge.

Hello, yes, that this fine.

Reviewed-by: Pali Rohár <pali@kernel.org>


For future improvements, it would be nice to adjust also other manpages
which refers to inode numbers:

  git grep -E '\<st_ino\>|\<stx_ino\>|\<d_ino\>'

> 
> Cheers,
> Alex
> 
> > 
> > 								Honza
> > 
> > > 
> > > 
> > > 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
> > > 
> > -- 
> > Jan Kara <jack@suse.com>
> > SUSE Labs, CR
> 
> -- 
> <https://www.alejandro-colomar.es>
> Use port 80 (that is, <...:80/>).