archive mirror
 help / color / mirror / Atom feed
From: "John Stoffel" <>
To: Jeff Layton <>
Subject: Re: [man-pages PATCH] statx, inode: document the new STATX_INO_VERSION field
Date: Sun, 28 Aug 2022 11:22:49 -0400	[thread overview]
Message-ID: <25355.34889.890961.350510@quad.stoffel.home> (raw)
In-Reply-To: <>

>>>>> "Jeff" == Jeff Layton <> writes:

Jeff> We're planning to expose the inode change attribute via statx. Document
Jeff> what this value means and what an observer can infer from a change in
Jeff> its value.

It might be nice to put in some more example verbiage of how this
would be used by userland.  For example, if you do a statx() call and
notice that the ino_version has changed... what would you do next to
find out what changed?  

Would you have to keep around an old copy of the statx() results and
then compare them to find the changes?  When talking to userland
people, don't assume they know anything about the kernel internals

Jeff> Signed-off-by: Jeff Layton <>
Jeff> ---
Jeff>  man2/statx.2 | 13 +++++++++++++
Jeff>  man7/inode.7 | 10 ++++++++++
Jeff>  2 files changed, 23 insertions(+)

Jeff> diff --git a/man2/statx.2 b/man2/statx.2
Jeff> index 0d1b4591f74c..644fb251f114 100644
Jeff> --- a/man2/statx.2
Jeff> +++ b/man2/statx.2
Jeff> @@ -62,6 +62,7 @@ struct statx {
Jeff>      __u32 stx_dev_major;   /* Major ID */
Jeff>      __u32 stx_dev_minor;   /* Minor ID */
Jeff>      __u64 stx_mnt_id;      /* Mount ID */
Jeff> +    __u64 stx_ino_version; /* Inode change attribute */
Jeff>  };
Jeff>  .EE
Jeff>  .in
Jeff> @@ -247,6 +248,7 @@ STATX_BTIME	Want stx_btime
Jeff>  	It is deprecated and should not be used.
Jeff>  STATX_MNT_ID	Want stx_mnt_id (since Linux 5.8)
Jeff> +STATX_INO_VERSION	Want stx_ino_version (since Linux 6.1)
Jeff>  .TE
Jeff>  .in
Jeff>  .PP
Jeff> @@ -411,6 +413,17 @@ and corresponds to the number in the first field in one of the records in
Jeff>  For further information on the above fields, see
Jeff>  .BR inode (7).
Jeff>  .\"
Jeff> +.TP
Jeff> +.I stx_ino_version
Jeff> +The inode version, also known as the inode change attribute. This
Jeff> +value is intended to change any time there is an inode status change. Any
Jeff> +operation that would cause the stx_ctime to change should also cause
Jeff> +stx_ino_version to change, even when there is no apparent change to the
Jeff> +stx_ctime due to timestamp granularity.
Jeff> +.IP
Jeff> +Note that an observer cannot infer anything about the nature or
Jeff> +magnitude of the change from the value of this field. A change in this value
Jeff> +only indicates that there may have been an explicit change in the inode.
Jeff>  .SS File attributes
Jeff>  The
Jeff>  .I stx_attributes
Jeff> diff --git a/man7/inode.7 b/man7/inode.7
Jeff> index 9b255a890720..d296bb6df70c 100644
Jeff> --- a/man7/inode.7
Jeff> +++ b/man7/inode.7
Jeff> @@ -184,6 +184,16 @@ Last status change timestamp (ctime)
Jeff>  This is the file's last status change timestamp.
Jeff>  It is changed by writing or by setting inode information
Jeff>  (i.e., owner, group, link count, mode, etc.).
Jeff> +.TP
Jeff> +Inode version (i_version)
Jeff> +(not returned in the \fIstat\fP structure); \fIstatx.stx_ino_version\fP
Jeff> +.IP
Jeff> +This is the inode change attribute. Any operation that would result in a ctime
Jeff> +change should also result in a change to this value. The value must change even
Jeff> +in the case where the ctime change is not evident due to timestamp granularity.
Jeff> +An observer cannot infer anything from the actual value about the nature or
Jeff> +magnitude of the change. If it is different from the last time it was checked,
Jeff> +then something may have made an explicit change to the inode.
Jeff>  .PP
Jeff>  The timestamp fields report time measured with a zero point at the
Jeff>  .IR Epoch ,
Jeff> -- 
Jeff> 2.37.2

  reply	other threads:[~2022-08-28 15:29 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-08-26 21:47 [man-pages PATCH] statx, inode: document the new STATX_INO_VERSION field Jeff Layton
2022-08-28 15:22 ` John Stoffel [this message]
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:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=25355.34889.890961.350510@quad.stoffel.home \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \

* 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).