From: Peter Krempa Date: Tue, 23 Aug 2022 11:19:38 +0000 (+0200) Subject: virDomainCheckpointCreateXML: Add disclaimer about creating checkpoints X-Git-Tag: v8.8.0-rc1~129 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=07b24d30650d4dcb458c9cf63559fb826dfa8d81;p=thirdparty%2Flibvirt.git 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 Reviewed-by: Jonathon Jongsma --- diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c index de747aff01..81107531b6 100644 --- a/src/libvirt-domain-checkpoint.c +++ b/src/libvirt-domain-checkpoint.c @@ -142,6 +142,17 @@ virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint) * present, an error is thrown. This flag is incompatible with * VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE. * + * Note: A checkpoint represents point in time after 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. + * The main purpose of checkpoints is to enable incremental backups. But for a + * checkpoint to be useful for this purpose, a backup must be performed at the + * same time as the checkpoint is created. + * This is done via the virDomainBackupBegin API, which also allows to create a + * checkpoint at the same time. Creating checkpoints with + * virDomainCheckpointCreateXML is generally only useful for re-creating the + * libvirt metadata. + * * Returns an (opaque) new virDomainCheckpointPtr on success or NULL * on failure. *