Re: [RFC PATCH v2] statx, inode: document the new STATX_INO_VERSION field

[Jeff Layton <jlayton@kernel.org>]

On Thu, 2022-09-01 at 18:12 +0200, Florian Weimer wrote:
> * Jeff Layton:
> 
> > @@ -411,6 +413,21 @@ and corresponds to the number in the first field in one of the records in
> >  For further information on the above fields, see
> >  .BR inode (7).
> >  .\"
> > +.TP
> > +.I stx_ino_version
> > +The inode version, also known as the inode change attribute. This
> > +value must change any time there is an inode status change. Any
> > +operation that would cause the
> > +.I stx_ctime
> > +to change must also cause
> > +.I stx_ino_version
> > +to change, even when there is no apparent change to the
> > +.I stx_ctime
> > +due to coarse timestamp granularity.
> > +.IP
> > +An observer cannot infer anything about the nature or magnitude of the change
> > +from the value of this field. A change in this value only indicates that
> > +there has been an explicit change in the inode.
> 
> What happens if the file system does not support i_version?
> 

The STATX_INO_VERSION bit will not be set in stx_mask field of the
response.

> > diff --git a/man7/inode.7 b/man7/inode.7
> > index 9b255a890720..d5e0890a52c0 100644
> > --- a/man7/inode.7
> > +++ b/man7/inode.7
> > @@ -184,6 +184,18 @@ Last status change timestamp (ctime)
> >  This is the file's last status change timestamp.
> >  It is changed by writing or by setting inode information
> >  (i.e., owner, group, link count, mode, etc.).
> > +.TP
> > +Inode version (i_version)
> > +(not returned in the \fIstat\fP structure); \fIstatx.stx_ino_version\fP
> > +.IP
> > +This is the inode change attribute. Any operation that would result in a change
> > +to \fIstatx.stx_ctime\fP must result in a change to this value. The value must
> > +change even in the case where the ctime change is not evident due to coarse
> > +timestamp granularity.
> > +.IP
> > +An observer cannot infer anything from the returned value about the nature or
> > +magnitude of the change. If the returned value is different from the last time
> > +it was checked, then something has made an explicit change to the inode.
> 
> What is the wraparound behavior for i_version?  Does it use the full
> 64-bit range?
> 

All of the existing implementations use all 64 bits. If you were to
increment a 64 bit value every nanosecond, it will take >500 years for
it to wrap. I'm hoping that's good enough. ;)

The implementation that all of the local Linux filesystems use track
whether the value has been queried using one bit, so there you only get
63 bits of counter.

My original thinking here was that we should leave the spec "loose" to
allow for implementations that may not be based on a counter. E.g. could
some filesystem do this instead by hashing certain metadata?

It's arguable though that the NFSv4 spec requires that this be based on
a counter, as the client is required to increment it in the case of
write delegations.

> If the system crashes without flushing disks, is it possible to observe
> new file contents without a change of i_version?

Yes, I think that's possible given the current implementations.

We don't have a great scheme to combat that at the moment, other than
looking at this in conjunction with the ctime. As long as the clock
doesn't jump backward after the crash and it takes more than one jiffy
to get the host back up, then you can be reasonably sure that
i_version+ctime should never repeat.

Maybe that's worth adding to the NOTES section of the manpage?
-- 
Jeff Layton <jlayton@kernel.org>