From: Richard W.M. Jones <rjones@redhat.com>
Date: Tue, 22 Nov 2011 13:18:32 +0000 (+0000)
Subject: df, testing: Add notes on virt-df numbers (thanks Kashyap Chamarthy).
X-Git-Tag: 1.14.3~1
X-Git-Url: http://git.annexia.org/?a=commitdiff_plain;h=de952fa9e8846aac11316d4bd39c069b15aec4ac;p=libguestfs.git

df, testing: Add notes on virt-df numbers (thanks Kashyap Chamarthy).
(cherry picked from commit 7b3137e664c3f4edf6ac7043a34c4166567e17bd)
---

diff --git a/df/virt-df.pod b/df/virt-df.pod
index df58b4c..24b3583 100755
--- a/df/virt-df.pod
+++ b/df/virt-df.pod
@@ -188,6 +188,32 @@ Enable tracing of libguestfs API calls.
 
 =back
 
+=head1 STATVFS NUMBERS
+
+C<virt-df> (and L<df(1)>) get information by issuing a L<statvfs(3)>
+system call.  You can get the same information directly, either from
+the host (using libguestfs) or inside the guest:
+
+=over 4
+
+=item From the host
+
+Run this command:
+
+ guestfish --ro -d GuestName -i statvfs /
+
+(change C</> to see stats for other filesystems).
+
+=item From inside the guest
+
+Run this command:
+
+ python -c 'import os; s = os.statvfs ("/"); print s'
+
+(change C</> to see stats for other filesystems).
+
+=back
+
 =head1 NOTE ABOUT CSV FORMAT
 
 Comma-separated values (CSV) is a deceptive format.  It I<seems> like
diff --git a/examples/guestfs-testing.pod b/examples/guestfs-testing.pod
index adf5b04..c35c3b8 100644
--- a/examples/guestfs-testing.pod
+++ b/examples/guestfs-testing.pod
@@ -102,7 +102,29 @@ L<virt-df(1)> lists disk space.  Run:
 
  virt-df
 
-Do the results match what's reported inside the guests?
+You can try comparing this to the results from L<df(1)> inside the
+guest, but there are some provisos:
+
+=over 4
+
+=item *
+
+The guest must be idle.
+
+=item *
+
+The guest disks must be synched using L<sync(1)>.
+
+=item *
+
+Any action such as booting the guest will write log files causing the
+numbers to change.
+
+=back
+
+We don't guarantee that the numbers will be identical even under these
+circumstances.  They should be similar.  It would indicate a bug if
+you saw greatly differing numbers.
 
 =head2 Try importing virt-df CSV output into a spreadsheet or database.