virStorageVolWipe: Document that wiping journaled FS is useless

So you have a libvirt volume that you want to wipe out. But lets
say that the volume is actually a file stored on a journaled
filesystem. Overwriting it with zeroes or a pattern does not mean
that corresponding physical location on the disk is overwritten
too, due to journaling. It's the same story with network based
volumes, copy-on-write filesystems, and so on. Since there is no
way that an userland application can write onto specific areas on
disk, all that we can do is document the fact.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>

diff --git a/src/libvirt-storage.c b/src/libvirt-storage.c
index bf09f7a6398464b64cb51eee3303b7191e66169a..1ce67455bb8872329677db49821ac94555326a29 100644 (file)
--- a/src/libvirt-storage.c
+++ b/src/libvirt-storage.c
@@ -1725,7 +1725,12 @@ virStorageVolDelete(virStorageVolPtr vol,
  * @vol: pointer to storage volume
  * @flags: extra flags; not used yet, so callers should always pass 0
  *
- * Ensure data previously on a volume is not accessible to future reads
+ * Ensure data previously on a volume is not accessible to future
+ * reads. Also note, that depending on the actual volume
+ * representation, this call may not really overwrite the
+ * physical location of the volume. For instance, files stored
+ * journaled, log structured, copy-on-write, versioned, and
+ * network file systems are known to be problematic.
  *
  * Returns 0 on success, or -1 on error
  */
@@ -1765,8 +1770,13 @@ virStorageVolWipe(virStorageVolPtr vol,
  * @algorithm: one of virStorageVolWipeAlgorithm
  * @flags: future flags, use 0 for now
  *
- * Similar to virStorageVolWipe, but one can choose
- * between different wiping algorithms.
+ * Similar to virStorageVolWipe, but one can choose between
+ * different wiping algorithms. Also note, that depending on the
+ * actual volume representation, this call may not really
+ * overwrite the physical location of the volume. For instance,
+ * files stored journaled, log structured, copy-on-write,
+ * versioned, and network file systems are known to be
+ * problematic.
  *
  * Returns 0 on success, or -1 on error.
  */