libvirt-storage: Document volume upload/download stream format

For libvirt, the volume is just a binary blob and it doesn't
interpret data on volume upload/download. But as it turns out,
this unspoken assumption is not clear to our users. Document it
explicitly.

Suggested in: https://bugzilla.redhat.com/show_bug.cgi?id=1851023#c17

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>

diff --git a/src/libvirt-storage.c b/src/libvirt-storage.c
index a45c8b98c1529c955e0d620b3d649da980bee44f..2a7cdca234113a7ff606cac22e1da6016c60bf1f 100644 (file)
--- a/src/libvirt-storage.c
+++ b/src/libvirt-storage.c
@@ -1590,7 +1590,10 @@ virStorageVolCreateXMLFrom(virStoragePoolPtr pool,
  *
  * Download the content of the volume as a stream. If @length
  * is zero, then the remaining contents of the volume after
- * @offset will be downloaded.
+ * @offset will be downloaded. Please note that the stream
+ * transports the volume itself as is, so the downloaded data may
+ * not correspond to guest OS visible state in cases when a
+ * complex storage format such as qcow2 or vmdk is used.
  *
  * If VIR_STORAGE_VOL_DOWNLOAD_SPARSE_STREAM is set in @flags
  * effective transmission of holes is enabled. This assumes using
@@ -1663,7 +1666,10 @@ virStorageVolDownload(virStorageVolPtr vol,
  * will fail if @offset + @length exceeds the size of the
  * volume. Otherwise, if @length is non-zero, an error
  * will be raised if an attempt is made to upload greater
- * than @length bytes of data.
+ * than @length bytes of data. Please note that the stream
+ * transports the volume itself as is, so the downloaded data may
+ * not correspond to guest OS visible state in cases when a
+ * complex storage format such as qcow2 or vmdk is used.
  *
  * If VIR_STORAGE_VOL_UPLOAD_SPARSE_STREAM is set in @flags
  * effective transmission of holes is enabled. This assumes using