[PATCH 3/4] virDomainCheckpointCreateXML: Add disclaimer about creating checkpoints

Checkpoints created via virDomainCheckpointCreateXML are generally not very useful as they need to be coupled with a backup. Add a disclaimer to the docs explaining why users should use virDomainBackupBegin instead. Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- src/libvirt-domain-checkpoint.c | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c index de747aff01..078e999bf3 100644 --- a/src/libvirt-domain-checkpoint.c +++ b/src/libvirt-domain-checkpoint.c @@ -142,6 +142,16 @@ virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint) * present, an error is thrown. This flag is incompatible with * VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE. * + * Note: A checkpoint represent s point in time since which blocks changed by + * the hypervisor are tracked. The tracking of changed blocks notes only whether + * a block was modified, but does not preserve the old contents. This means that + * for a checkpoint to be generally usable for doing an incremental backup it's + * required to perform a backup at the same time as taking the checkpoint. + * This is done via the virDomainBackupBegin API, which also allows to create + * a checkpoint at the same time. virDomainCheckpointCreateXML is generally not + * useful for creating checkpoints but rather only for re-creating the libvirt + * metadata. + * * Returns an (opaque) new virDomainCheckpointPtr on success or NULL * on failure. * -- 2.37.1