# Module libvirt-domain-checkpoint from libvirt

Provides APIs for the management of domain checkpoints Copyright (C) 2006-2019 Red Hat, Inc. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library. If not, see http://www.gnu.org/licenses/.

## 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`

    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`

    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

    }

### `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 <a href="formatcheckpoint.html#CheckpointAttributes">Checkpoint XML</a> 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.

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.

### `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.

### `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.

### `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.

### `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.

### `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.

### `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 virDomainCheckpoinListFlags
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.