From: Michal Privoznik Date: Wed, 1 Jul 2020 11:47:04 +0000 (+0200) Subject: libvirt-storage: Document volume upload/download stream format X-Git-Tag: v6.7.0-rc1~74 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=70b67c98d99da9e0f14e9dec97b0047f97af05dc;p=thirdparty%2Flibvirt.git 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 Reviewed-by: Peter Krempa --- diff --git a/src/libvirt-storage.c b/src/libvirt-storage.c index a45c8b98c1..2a7cdca234 100644 --- 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