lkml.org 
[lkml]   [2022]   [Sep]   [1]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
From
Subject[RFC PATCH v2] statx, inode: document the new STATX_INO_VERSION field
Date
I'm proposing to expose the inode change attribute via statx [1]. Document
what this value means and what an observer can infer from it changing.

Signed-off-by: Jeff Layton <jlayton@kernel.org>

[1]: https://lore.kernel.org/linux-nfs/20220826214703.134870-1-jlayton@kernel.org/T/#t
---
man2/statx.2 | 17 +++++++++++++++++
man7/inode.7 | 12 ++++++++++++
2 files changed, 29 insertions(+)

v2: revised the definition to be more strict, since that seemed to be
consensus on desired behavior. Spurious i_version bumps would now
be considered bugs, by this definition.

diff --git a/man2/statx.2 b/man2/statx.2
index 0d1b4591f74c..493e4e234809 100644
--- a/man2/statx.2
+++ b/man2/statx.2
@@ -62,6 +62,7 @@ struct statx {
__u32 stx_dev_major; /* Major ID */
__u32 stx_dev_minor; /* Minor ID */
__u64 stx_mnt_id; /* Mount ID */
+ __u64 stx_ino_version; /* Inode change attribute */
};
.EE
.in
@@ -247,6 +248,7 @@ STATX_BTIME Want stx_btime
STATX_ALL The same as STATX_BASIC_STATS | STATX_BTIME.
It is deprecated and should not be used.
STATX_MNT_ID Want stx_mnt_id (since Linux 5.8)
+STATX_INO_VERSION Want stx_ino_version (DRAFT)
.TE
.in
.PP
@@ -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.
.SS File attributes
The
.I stx_attributes
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.
.PP
The timestamp fields report time measured with a zero point at the
.IR Epoch ,
--
2.37.2
\
 
 \ /
  Last update: 2022-09-01 14:18    [W:0.874 / U:0.544 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site