From: Jeff Layton <jlayton@kernel.org>
To: tytso@mit.edu, adilger.kernel@dilger.ca, djwong@kernel.org,
david@fromorbit.com, trondmy@hammerspace.com, neilb@suse.de,
viro@zeniv.linux.org.uk, zohar@linux.ibm.com, xiubli@redhat.com,
chuck.lever@oracle.com, lczerner@redhat.com, jack@suse.cz,
brauner@kernel.org, linux-man@vger.kernel.org
Cc: linux-api@vger.kernel.org, linux-btrfs@vger.kernel.org,
linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org,
linux-ceph@vger.kernel.org, linux-ext4@vger.kernel.org,
linux-nfs@vger.kernel.org, linux-xfs@vger.kernel.org
Subject: [man-pages PATCH] statx, inode: document the new STATX_INO_VERSION field
Date: Fri, 26 Aug 2022 17:47:47 -0400 [thread overview]
Message-ID: <20220826214747.134964-1-jlayton@kernel.org> (raw)
We're planning to expose the inode change attribute via statx. Document
what this value means and what an observer can infer from a change in
its value.
Signed-off-by: Jeff Layton <jlayton@kernel.org>
---
man2/statx.2 | 13 +++++++++++++
man7/inode.7 | 10 ++++++++++
2 files changed, 23 insertions(+)
diff --git a/man2/statx.2 b/man2/statx.2
index 0d1b4591f74c..644fb251f114 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 (since Linux 6.1)
.TE
.in
.PP
@@ -411,6 +413,17 @@ 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 is intended to change any time there is an inode status change. Any
+operation that would cause the stx_ctime to change should also cause
+stx_ino_version to change, even when there is no apparent change to the
+stx_ctime due to timestamp granularity.
+.IP
+Note that 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 may have 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..d296bb6df70c 100644
--- a/man7/inode.7
+++ b/man7/inode.7
@@ -184,6 +184,16 @@ 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 ctime
+change should also result in a change to this value. The value must change even
+in the case where the ctime change is not evident due to timestamp granularity.
+An observer cannot infer anything from the actual value about the nature or
+magnitude of the change. If it is different from the last time it was checked,
+then something may have 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
next reply other threads:[~2022-08-26 21:49 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-08-26 21:47 Jeff Layton [this message]
2022-08-28 15:22 ` [man-pages PATCH] statx, inode: document the new STATX_INO_VERSION field John Stoffel
2022-08-29 12:37 ` Jeff Layton
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220826214747.134964-1-jlayton@kernel.org \
--to=jlayton@kernel.org \
--cc=adilger.kernel@dilger.ca \
--cc=brauner@kernel.org \
--cc=chuck.lever@oracle.com \
--cc=david@fromorbit.com \
--cc=djwong@kernel.org \
--cc=jack@suse.cz \
--cc=lczerner@redhat.com \
--cc=linux-api@vger.kernel.org \
--cc=linux-btrfs@vger.kernel.org \
--cc=linux-ceph@vger.kernel.org \
--cc=linux-ext4@vger.kernel.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-man@vger.kernel.org \
--cc=linux-nfs@vger.kernel.org \
--cc=linux-xfs@vger.kernel.org \
--cc=neilb@suse.de \
--cc=trondmy@hammerspace.com \
--cc=tytso@mit.edu \
--cc=viro@zeniv.linux.org.uk \
--cc=xiubli@redhat.com \
--cc=zohar@linux.ibm.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).