From 2e635246b52a2cee87aa143dd234db24f42640e4 Mon Sep 17 00:00:00 2001
From: Nikitas Angelinas <nangelinas@cray.com>
Date: Tue, 18 Sep 2018 20:28:28 -0700
Subject: [PATCH] LUDOC-414 utils: document the lfs data_version command

Update the lfs utility synopsis and table with a description of the
lfs data_version command.

Signed-off-by: Nikitas Angelinas <nangelinas@cray.com>
Change-Id: Id6c474dfdd8d8b5884b220768fbf59294a2efd86
Reviewed-on: https://review.whamcloud.com/33200
Tested-by: Jenkins
Reviewed-by: Andreas Dilger <adilger@whamcloud.com>
Reviewed-by: Joseph Gmitter <jgmitter@whamcloud.com>
---
 UserUtilities.xml | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/UserUtilities.xml b/UserUtilities.xml
index b60ba9e..7314279 100644
--- a/UserUtilities.xml
+++ b/UserUtilities.xml
@@ -22,6 +22,7 @@ lfs
 lfs changelog [--follow] <replaceable>mdt_name</replaceable> [startrec [endrec]]
 lfs changelog_clear <replaceable>mdt_name id endrec</replaceable>
 lfs check <replaceable>mds|osts|servers</replaceable>
+lfs data_version [-nrw] <replaceable>filename</replaceable>
 lfs df [-i] [-h] [--pool]-p <replaceable>fsname</replaceable>[.<replaceable>pool</replaceable>] [<replaceable>path</replaceable>] [--lazy]
 lfs find [[!] --atime|-A [-+]N] [[!] --mtime|-M [-+]N]
          [[!] --ctime|-C [-+]N] [--maxdepth|-D N] [--name|-n <replaceable>pattern</replaceable>]
@@ -171,6 +172,40 @@ lfs help
             </row>
             <row>
               <entry nameend="c2" namest="c1">
+                <para>
+                  <literal>data_version [-nrw]
+                  <replaceable>filename</replaceable></literal>
+                </para>
+              </entry>
+              <entry>
+		<para>Displays the current version of file data. If
+		<literal>-n</literal> is specified, the data version is read
+		without taking a lock. As a consequence, the data version could
+		be outdated if there are dirty caches on filesystem clients, but
+		this option will not force data flushes and has less of an
+		impact on the filesystem. If <literal>-r</literal> is specified,
+		the data version is read after dirty pages on clients are
+		flushed. If <literal>-w</literal> is specified, the data version
+		is read after all caching pages on clients are flushed.
+		</para>
+		<para>
+		Even with <literal>-r</literal> or <literal>-w</literal>, race
+		conditions are possible and the data version should be checked
+		before and after an operation to be confident the data did not
+		change during it.
+		</para>
+		<para>
+		The  data  version is the sum of the last committed transaction
+		numbers of all data objects of a file. It is used by HSM policy
+		engines for verifying that file data has not been changed during
+		an archive operation or before a release operation, and by OST
+		migration, primarily for verifying that file data has not been
+		changed during a data copy, when done in non-blocking mode.
+		</para>
+              </entry>
+            </row>
+            <row>
+              <entry nameend="c2" namest="c1">
                 <literal>df [-i] [-h] [--pool|-p 
                 <replaceable>fsname</replaceable>[.
                 <replaceable>pool</replaceable>] [
-- 
1.8.3.1