libvirt: Module libvirt-domain-checkpoint from libvirt
Description: libvirt, virtualization, virtualization API

# Module libvirt-domain-checkpoint from libvirt

Provides APIs for the management of domain checkpoints

## Table of Contents

### Types

    typedef struct _virDomainCheckpoint virDomainCheckpoint
    typedef enum virDomainCheckpointCreateFlags
    typedef enum virDomainCheckpointDeleteFlags
    typedef enum virDomainCheckpointListFlags
    typedef virDomainCheckpoint * virDomainCheckpointPtr
    typedef enum virDomainCheckpointXMLFlags

### Functions

    virDomainCheckpointPtr	virDomainCheckpointCreateXML	(virDomainPtr domain,
    							 const char * xmlDesc,
    							 unsigned int flags)
    int	virDomainCheckpointDelete	(virDomainCheckpointPtr checkpoint,
    					 unsigned int flags)
    int	virDomainCheckpointFree		(virDomainCheckpointPtr checkpoint)
    virConnectPtr	virDomainCheckpointGetConnect	(virDomainCheckpointPtr checkpoint)
    virDomainPtr	virDomainCheckpointGetDomain	(virDomainCheckpointPtr checkpoint)
    const char *	virDomainCheckpointGetName	(virDomainCheckpointPtr checkpoint)
    virDomainCheckpointPtr	virDomainCheckpointGetParent	(virDomainCheckpointPtr checkpoint,
    							 unsigned int flags)
    char *	virDomainCheckpointGetXMLDesc	(virDomainCheckpointPtr checkpoint,
    					 unsigned int flags)
    int	virDomainCheckpointListAllChildren	(virDomainCheckpointPtr checkpoint,
    						 virDomainCheckpointPtr ** children,
    						 unsigned int flags)
    virDomainCheckpointPtr	virDomainCheckpointLookupByName	(virDomainPtr domain,
    							 const char * name,
    							 unsigned int flags)
    int	virDomainCheckpointRef		(virDomainCheckpointPtr checkpoint)
    int	virDomainListAllCheckpoints	(virDomainPtr domain,
    					 virDomainCheckpointPtr ** checkpoints,
    					 unsigned int flags)

## Description

### Types

### `virDomainCheckpoint`

    struct virDomainCheckpoint {

The content of this structure is not made public by the API

    }

### `virDomainCheckpointCreateFlags`

    enum virDomainCheckpointCreateFlags {

VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE | = | 1 (0x1; 1 << 0) | Restore or alter metadata
VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE | = | 2 (0x2; 1 << 1) | use guest agent to quiesce all mounted file systems within the domain
VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE_VALIDATE | = | 4 (0x4; 1 << 2) | validate disk data state when redefining a checkpoint

    }

### `virDomainCheckpointDeleteFlags`

Delete a checkpoint

    enum virDomainCheckpointDeleteFlags {

VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN | = | 1 (0x1; 1 << 0) | Also delete children
VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY | = | 2 (0x2; 1 << 1) | Delete just metadata
VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY | = | 4 (0x4; 1 << 2) | Delete just children

    }

### `virDomainCheckpointListFlags`

Flags valid for virDomainListAllCheckpoints() and virDomainCheckpointListAllChildren(). Note that the interpretation of flag (1<<0) depends on which function it is passed to; but serves to toggle the per-call default of whether the listing is shallow or recursive. Remaining bits come in groups; if all bits from a group are 0, then that group is not used to filter results.

    enum virDomainCheckpointListFlags {

VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS | = | 1 (0x1; 1 << 0) | List all descendants, not just children, when listing a checkpoint
VIR_DOMAIN_CHECKPOINT_LIST_ROOTS | = | 1 (0x1; 1 << 0) | Filter by checkpoints with no parents, when listing a domain
VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL | = | 2 (0x2; 1 << 1) | Ensure parents occur before children in the resulting list
VIR_DOMAIN_CHECKPOINT_LIST_LEAVES | = | 4 (0x4; 1 << 2) | Filter by checkpoints with no children
VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES | = | 8 (0x8; 1 << 3) | Filter by checkpoints that have children

    }

### `virDomainCheckpointPtr`

    typedef virDomainCheckpoint * virDomainCheckpointPtr;

A virDomainCheckpointPtr is pointer to a virDomainCheckpoint private structure, and is the type used to reference a domain checkpoint in the API.

### `virDomainCheckpointXMLFlags`

    enum virDomainCheckpointXMLFlags {

VIR_DOMAIN_CHECKPOINT_XML_SECURE | = | 1 (0x1; 1 << 0) | Include sensitive data
VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN | = | 2 (0x2; 1 << 1) | Suppress <domain> subelement
VIR_DOMAIN_CHECKPOINT_XML_SIZE | = | 4 (0x4; 1 << 2) | Include dynamic per-<disk> size

    }

### Functions

### `virDomainCheckpointCreateXML`

    virDomainCheckpointPtr	virDomainCheckpointCreateXML	(virDomainPtr domain,
    							 const char * xmlDesc,
    							 unsigned int flags)

Create a new checkpoint using `xmlDesc`, with a top-level <domaincheckpoint> element, on a running `domain`. Note that `xmlDesc` must validate against the <domaincheckpoint> XML schema. Typically, it is more common to create a new checkpoint as part of kicking off a backup job with virDomainBackupBegin(); however, it is also possible to start a checkpoint without a backup.

See https://libvirt.org/formatcheckpoint.html#checkpoint-xml for more details on `xmlDesc`. In particular, some hypervisors may require particular disk formats, such as qcow2, in order to support this command; where `xmlDesc` can be used to limit the checkpoint to a working subset of the domain's disks.

If `flags` includes VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE, then this is a request to reinstate checkpoint metadata that was previously captured from virDomainCheckpointGetXMLDesc() before removing that metadata, rather than creating a new checkpoint. Note that while original creation can omit a number of elements from `xmlDesc` (and libvirt will supply sane defaults based on the domain state at that point in time), a redefinition must supply more elements (as the domain may have changed in the meantime, so that libvirt no longer has a way to resupply correct defaults). Not all hypervisors support this flag.

If `flags` includes VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE_VALIDATE along with VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE the state of the metadata related to the disk state of the redefined checkpoint is validated. Note that hypervisors may require that the `domain` is running to perform validation.

If `flags` includes VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE, then the libvirt will attempt to use guest agent to freeze and thaw all file systems in use within domain OS. However, if the guest agent is not 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.

domain
  a domain object
xmlDesc
  description of the checkpoint to create
flags
  bitwise-OR of supported virDomainCheckpointCreateFlags
Returns
  an (opaque) new virDomainCheckpointPtr on success or NULL on failure.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
domain | checkpoint | -
domain | fs-freeze | VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE

### `virDomainCheckpointDelete`

    int	virDomainCheckpointDelete	(virDomainCheckpointPtr checkpoint,
    					 unsigned int flags)

Removes a checkpoint from the domain.

When removing a checkpoint, the record of which portions of the disk were dirtied after the checkpoint will be merged into the record tracked by the parent checkpoint, if any.

If `flags` includes VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN, then any descendant checkpoints are also deleted. If `flags` includes VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY, then any descendant checkepoints are deleted, but this checkpoint remains. These two flags are mutually exclusive.

If `flags` includes VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY, then any checkpoint metadata tracked by libvirt is removed while keeping the checkpoint contents intact; if a hypervisor does not require any libvirt metadata to track checkpoints, then this flag is silently ignored.

checkpoint
  the checkpoint to remove
flags
  bitwise-OR of supported virDomainCheckpointDeleteFlags
Returns
  0 on success, -1 on error.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
domain | checkpoint | -

### `virDomainCheckpointFree`

    int	virDomainCheckpointFree		(virDomainCheckpointPtr checkpoint)

Free the domain checkpoint object. The checkpoint itself is not modified. The data structure is freed and should not be used thereafter.

checkpoint
  a domain checkpoint object
Returns
  0 in case of success and -1 in case of failure.

### `virDomainCheckpointGetConnect`

    virConnectPtr	virDomainCheckpointGetConnect	(virDomainCheckpointPtr checkpoint)

Provides the connection pointer associated with a checkpoint. The reference counter on the connection is not increased by this call.

checkpoint
  a checkpoint object
Returns
  the connection or NULL.

### `virDomainCheckpointGetDomain`

    virDomainPtr	virDomainCheckpointGetDomain	(virDomainCheckpointPtr checkpoint)

Provides the domain pointer associated with a checkpoint. The reference counter on the domain is not increased by this call.

checkpoint
  a checkpoint object
Returns
  the domain or NULL.

### `virDomainCheckpointGetName`

    const char *	virDomainCheckpointGetName	(virDomainCheckpointPtr checkpoint)

Get the public name for that checkpoint

checkpoint
  a checkpoint object
Returns
  a pointer to the name or NULL, the string need not be deallocated as its lifetime will be the same as the checkpoint object.

### `virDomainCheckpointGetParent`

    virDomainCheckpointPtr	virDomainCheckpointGetParent	(virDomainCheckpointPtr checkpoint,
    							 unsigned int flags)

Get the parent checkpoint for `checkpoint`, if any.

virDomainCheckpointFree should be used to free the resources after the checkpoint object is no longer needed.

checkpoint
  a checkpoint object
flags
  extra flags; not used yet, so callers should always pass 0
Returns
  a domain checkpoint object or NULL in case of failure. If the given checkpoint is a root (no parent), then the VIR_ERR_NO_DOMAIN_CHECKPOINT error is raised.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
domain | read | -

### `virDomainCheckpointGetXMLDesc`

    char *	virDomainCheckpointGetXMLDesc	(virDomainCheckpointPtr checkpoint,
    					 unsigned int flags)

Provide an XML description of the domain checkpoint.

No security-sensitive data will be included unless `flags` contains VIR_DOMAIN_CHECKPOINT_XML_SECURE; this flag is rejected on read-only connections.

Normally, the XML description includes an element giving a full description of the domain at the time the checkpoint was created; to reduce parsing time, it will be suppressed when `flags` contains VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN.

By default, the XML description contains only static information that does not change over time. However, when `flags` contains VIR_DOMAIN_CHECKPOINT_XML_SIZE, each <disk> listing adds an additional attribute that shows an estimate of the current size in bytes that have been dirtied between the time the checkpoint was created and the current point in time. Note that updating the size may be expensive and data will be inaccurate once guest OS writes to the disk. Also note that hypervisors may require that the domain associated with `checkpoint` is running when VIR_DOMAIN_CHECKPOINT_XML_SIZE is used.

checkpoint
  a domain checkpoint object
flags
  bitwise-OR of supported virDomainCheckpointXMLFlags
Returns
  a 0 terminated UTF-8 encoded XML instance or NULL in case of error. The caller must free() the returned value.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
domain | read | -
domain | read-secure | VIR_DOMAIN_CHECKPOINT_XML_SECURE

### `virDomainCheckpointListAllChildren`

    int	virDomainCheckpointListAllChildren	(virDomainCheckpointPtr checkpoint,
    						 virDomainCheckpointPtr ** children,
    						 unsigned int flags)

Collect the list of domain checkpoints that are children of the given checkpoint, and allocate an array to store those objects.

If `flags` contains VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL, `checkpoints` is non-NULL, and no other connection is modifying checkpoints, then it is guaranteed that for any checkpoint in the resulting list, no checkpoints later in the list can be reached by a sequence of virDomainCheckpointGetParent() starting from that earlier checkpoint; otherwise, the order of checkpoints in the resulting list is unspecified.

By default, this command covers only direct children. It is also possible to expand things to cover all descendants, when `flags` includes VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS. Additional are provided via the remaining `flags` values as documented in virDomainListAllCheckpoints(), with the exception that VIR_DOMAIN_CHECKPOINT_LIST_ROOTS is not supported (in fact, VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS has the same bit value but opposite semantics of widening rather than narrowing the listing).

checkpoint
  a domain checkpoint object
children
  pointer to variable to store the array containing checkpoint objects or NULL if the list is not required (just returns number of checkpoints)
flags
  bitwise-OR of supported virDomainCheckpointListFlags
Returns
  the number of domain checkpoints found or -1 and sets `children` to NULL in case of error. On success, the array stored into `children` is guaranteed to have an extra allocated element set to NULL but not included in the return count, to make iteration easier. The caller is responsible for calling virDomainCheckpointFree() on each array element, then calling free() on `children`.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
domain | read | -

### `virDomainCheckpointLookupByName`

    virDomainCheckpointPtr	virDomainCheckpointLookupByName	(virDomainPtr domain,
    							 const char * name,
    							 unsigned int flags)

Try to lookup a domain checkpoint based on its name.

domain
  a domain object
name
  name for the domain checkpoint
flags
  extra flags; not used yet, so callers should always pass 0
Returns
  a domain checkpoint object or NULL in case of failure. If the domain checkpoint cannot be found, then the VIR_ERR_NO_DOMAIN_CHECKPOINT error is raised.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
domain | read | -

### `virDomainCheckpointRef`

    int	virDomainCheckpointRef		(virDomainCheckpointPtr checkpoint)

Increment the reference count on the checkpoint. For each additional call to this method, there shall be a corresponding call to virDomainCheckpointFree to release the reference count, once the caller no longer needs the reference to this object.

This method is typically useful for applications where multiple threads are using a connection, and it is required that the connection and domain remain open until all threads have finished using the checkpoint. ie, each new thread using a checkpoint would increment the reference count.

checkpoint
  the checkpoint to hold a reference on
Returns
  0 in case of success and -1 in case of failure.

### `virDomainListAllCheckpoints`

    int	virDomainListAllCheckpoints	(virDomainPtr domain,
    					 virDomainCheckpointPtr ** checkpoints,
    					 unsigned int flags)

Collect the list of domain checkpoints for the given domain and allocate an array to store those objects.

If `flags` contains VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL, `checkpoints` is non-NULL, and no other connection is modifying checkpoints, then it is guaranteed that for any checkpoint in the resulting list, no checkpoints later in the list can be reached by a sequence of virDomainCheckpointGetParent() starting from that earlier checkpoint; otherwise, the order of checkpoints in the resulting list is unspecified.

By default, this command covers all checkpoints. It is also possible to limit things to just checkpoints with no parents, when `flags` includes VIR_DOMAIN_CHECKPOINT_LIST_ROOTS. Additional filters are provided in groups listed below. Within a group, bits are mutually exclusive, where all possible checkpoints are described by exactly one bit from the group. Some hypervisors might reject particular flags where it cannot make a distinction for filtering. If the set of filter flags selected forms an impossible combination, the hypervisor may return either 0 or an error.

The first group of `flags` is VIR_DOMAIN_CHECKPOINT_LIST_LEAVES and VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES, to filter based on checkpoints that have no further children (a leaf checkpoint).

domain
  a domain object
checkpoints
  pointer to variable to store the array containing checkpoint object, or NULL if the list is not required (just returns number of checkpoints)
flags
  bitwise-OR of supported virDomainCheckpointListFlags
Returns
  the number of domain checkpoints found or -1 and sets `checkpoints` to NULL in case of error. On success, the array stored into `checkpoints` is guaranteed to have an extra allocated element set to NULL but not included in the return count, to make iteration easier. The caller is responsible for calling virDomainCheckpointFree() on each array element, then calling free() on `checkpoints`.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
domain | read | -