checkpoint: Mention that VIR_DOMAIN_CHECKPOINT_XML_SIZE is expensive and stale

Data is valid only when queried as guest writes may increase the backup
size.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>

diff --git a/docs/formatcheckpoint.rst b/docs/formatcheckpoint.rst
index e45745390ab21af69d1444e6db3c6a32d937ebbf..f159f2a7a38968f13696375c99f049bcf7b5acd9 100644 (file)
--- a/docs/formatcheckpoint.rst
+++ b/docs/formatcheckpoint.rst
@@ -86,6 +86,10 @@ The top-level ``domaincheckpoint`` element may contain the following elements:
          perform a dynamic query of the estimated size in bytes of the changes
          made since the checkpoint was created.
 
+         Note that updating the backup ``size`` may be expensive and
+         the actual required size may increase if the guest OS is actively
+         writing to the disk.
+
 ``creationTime``
    A readonly representation of the time this checkpoint was created. The time
    is specified in seconds since the Epoch, UTC (i.e. Unix time).

diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c
index 50627c486c0b0833228289cecf2e3d6fa166e926..8a7b55dcd20750794b35b602ade31ef70605b59a 100644 (file)
--- a/src/libvirt-domain-checkpoint.c
+++ b/src/libvirt-domain-checkpoint.c
@@ -191,7 +191,8 @@ virDomainCheckpointCreateXML(virDomainPtr domain,
  * VIR_DOMAIN_CHECKPOINT_XML_SIZE, each <disk> listing adds an additional
  * attribute that shows an estimate of the current size in bytes that
  * have been dirtied between the time the checkpoint was created and the
- * current point in time.
+ * current point in time. Note that updating the size may be expensive and
+ * data will be inaccurate once guest OS writes to the disk.
  *
  * Returns a 0 terminated UTF-8 encoded XML instance or NULL in case
  * of error. The caller must free() the returned value.