From 07b24d30650d4dcb458c9cf63559fb826dfa8d81 Mon Sep 17 00:00:00 2001 From: Peter Krempa Date: Tue, 23 Aug 2022 13:19:38 +0200 Subject: [PATCH] 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 --- src/libvirt-domain-checkpoint.c | 11 +++++++++++ 1 file changed, 11 insertions(+) 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. *