diff --git a/docs/Makefile.am b/docs/Makefile.am index ae2673ca9b..1cdb584b0b 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -22,6 +22,7 @@ DEVHELP_DIR=$(datadir)/gtk-doc/html/libvirt modules = \ libvirt-common \ libvirt-domain \ + libvirt-domain-checkpoint \ libvirt-domain-snapshot \ libvirt-event \ libvirt-host \ @@ -313,6 +314,7 @@ $(python_generated_files): $(APIBUILD_STAMP) $(APIBUILD_STAMP): $(srcdir)/apibuild.py \ $(top_srcdir)/include/libvirt/libvirt.h \ $(top_srcdir)/include/libvirt/libvirt-common.h.in \ + $(top_srcdir)/include/libvirt/libvirt-domain-checkpoint.h \ $(top_srcdir)/include/libvirt/libvirt-domain-snapshot.h \ $(top_srcdir)/include/libvirt/libvirt-domain.h \ $(top_srcdir)/include/libvirt/libvirt-event.h \ @@ -329,6 +331,7 @@ $(APIBUILD_STAMP): $(srcdir)/apibuild.py \ $(top_srcdir)/include/libvirt/libvirt-admin.h \ $(top_srcdir)/include/libvirt/virterror.h \ $(top_srcdir)/src/libvirt.c \ + $(top_srcdir)/src/libvirt-domain-checkpoint.c \ $(top_srcdir)/src/libvirt-domain-snapshot.c \ $(top_srcdir)/src/libvirt-domain.c \ $(top_srcdir)/src/libvirt-host.c \ diff --git a/docs/apibuild.py b/docs/apibuild.py index 9e04871220..dbdc1c95af 100755 --- a/docs/apibuild.py +++ b/docs/apibuild.py @@ -26,6 +26,7 @@ debugsym = None included_files = { "libvirt-common.h": "header with general libvirt API definitions", "libvirt-domain.h": "header with general libvirt API definitions", + "libvirt-domain-checkpoint.h": "header with general libvirt API definitions", "libvirt-domain-snapshot.h": "header with general libvirt API definitions", "libvirt-event.h": "header with general libvirt API definitions", "libvirt-host.h": "header with general libvirt API definitions", @@ -39,6 +40,7 @@ included_files = { "virterror.h": "header with error specific API definitions", "libvirt.c": "Main interfaces for the libvirt library", "libvirt-domain.c": "Domain interfaces for the libvirt library", + "libvirt-domain-checkpoint.c": "Domain checkpoint interfaces for the libvirt library", "libvirt-domain-snapshot.c": "Domain snapshot interfaces for the libvirt library", "libvirt-host.c": "Host interfaces for the libvirt library", "libvirt-interface.c": "Interface interfaces for the libvirt library", diff --git a/docs/docs.html.in b/docs/docs.html.in index 74af38002e..ba9514279a 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -94,6 +94,7 @@
Reference manual for the C public API, split in common, domain, + domain checkpoint, domain snapshot, error, event, diff --git a/include/libvirt/libvirt-domain-checkpoint.h b/include/libvirt/libvirt-domain-checkpoint.h new file mode 100644 index 0000000000..f4bd92e81c --- /dev/null +++ b/include/libvirt/libvirt-domain-checkpoint.h @@ -0,0 +1,137 @@ +/* + * libvirt-domain-checkpoint.h + * Summary: APIs for management of domain checkpoints + * Description: 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 + * . + */ + +#ifndef LIBVIRT_DOMAIN_CHECKPOINT_H +# define LIBVIRT_DOMAIN_CHECKPOINT_H + +# ifndef __VIR_LIBVIRT_H_INCLUDES__ +# error "Don't include this file directly, only use libvirt/libvirt.h" +# endif + +/** + * virDomainCheckpoint: + * + * A virDomainCheckpoint is a private structure representing a checkpoint of + * a domain. A checkpoint is useful for tracking which portions of the + * domain disks have been altered since a point in time, but by itself does + * not allow reverting back to that point in time. + */ +typedef struct _virDomainCheckpoint virDomainCheckpoint; + +/** + * virDomainCheckpointPtr: + * + * A virDomainCheckpointPtr is pointer to a virDomainCheckpoint + * private structure, and is the type used to reference a domain + * checkpoint in the API. + */ +typedef virDomainCheckpoint *virDomainCheckpointPtr; + +const char *virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint); +virDomainPtr virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint); +virConnectPtr virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint); + +typedef enum { + VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE = (1 << 0), /* Restore or alter + metadata */ + VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE = (1 << 1), /* use guest agent to + quiesce all mounted + file systems within + the domain */ +} virDomainCheckpointCreateFlags; + +/* Create a checkpoint using the current VM state. */ +virDomainCheckpointPtr virDomainCheckpointCreateXML(virDomainPtr domain, + const char *xmlDesc, + unsigned int flags); + +typedef enum { + VIR_DOMAIN_CHECKPOINT_XML_SECURE = (1 << 0), /* Include sensitive data */ + VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN = (1 << 1), /* Suppress + subelement */ + VIR_DOMAIN_CHECKPOINT_XML_SIZE = (1 << 2), /* Include dynamic + per- size */ +} virDomainCheckpointXMLFlags; + +/* Dump the XML of a checkpoint */ +char *virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +/** + * 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. */ +typedef enum { + VIR_DOMAIN_CHECKPOINT_LIST_ROOTS = (1 << 0), /* Filter by checkpoints + with no parents, when + listing a domain */ + VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS = (1 << 0), /* List all descendants, + not just children, when + listing a checkpoint */ + VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL = (1 << 1), /* Ensure parents occur + before children in + the resulting list */ + + VIR_DOMAIN_CHECKPOINT_LIST_LEAVES = (1 << 2), /* Filter by checkpoints + with no children */ + VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES = (1 << 3), /* Filter by checkpoints + that have children */ +} virDomainCheckpointListFlags; + +/* Get all checkpoint objects for this domain */ +int virDomainListAllCheckpoints(virDomainPtr domain, + virDomainCheckpointPtr **checkpoints, + unsigned int flags); + +/* Get all checkpoint object children for this checkpoint */ +int virDomainCheckpointListAllChildren(virDomainCheckpointPtr checkpoint, + virDomainCheckpointPtr **children, + unsigned int flags); + +/* Get a handle to a named checkpoint */ +virDomainCheckpointPtr virDomainCheckpointLookupByName(virDomainPtr domain, + const char *name, + unsigned int flags); + +/* Get a handle to the parent checkpoint, if one exists */ +virDomainCheckpointPtr virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +/* Delete a checkpoint */ +typedef enum { + VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN = (1 << 0), /* Also delete children */ + VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY = (1 << 1), /* Delete just metadata */ + VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY = (1 << 2), /* Delete just children */ +} virDomainCheckpointDeleteFlags; + +int virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +int virDomainCheckpointRef(virDomainCheckpointPtr checkpoint); +int virDomainCheckpointFree(virDomainCheckpointPtr checkpoint); + +#endif /* LIBVIRT_DOMAIN_CHECKPOINT_H */ diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h index 2dbd74d4f3..f160ee88b5 100644 --- a/include/libvirt/libvirt-domain.h +++ b/include/libvirt/libvirt-domain.h @@ -1800,6 +1800,9 @@ typedef enum { VIR_DOMAIN_UNDEFINE_NVRAM = (1 << 2), /* Also remove any nvram file */ VIR_DOMAIN_UNDEFINE_KEEP_NVRAM = (1 << 3), /* Keep nvram file */ + VIR_DOMAIN_UNDEFINE_CHECKPOINTS_METADATA = (1 << 4), /* If last use of domain, + then also remove any + checkpoint metadata */ /* Future undefine control flags should come here. */ } virDomainUndefineFlagsValues; @@ -1838,6 +1841,9 @@ typedef enum { VIR_CONNECT_LIST_DOMAINS_HAS_SNAPSHOT = 1 << 12, VIR_CONNECT_LIST_DOMAINS_NO_SNAPSHOT = 1 << 13, + + VIR_CONNECT_LIST_DOMAINS_HAS_CHECKPOINT = 1 << 14, + VIR_CONNECT_LIST_DOMAINS_NO_CHECKPOINT = 1 << 15, } virConnectListAllDomainsFlags; int virConnectListAllDomains (virConnectPtr conn, diff --git a/include/libvirt/libvirt.h b/include/libvirt/libvirt.h index 13de151cb6..f93e3bfa85 100644 --- a/include/libvirt/libvirt.h +++ b/include/libvirt/libvirt.h @@ -34,10 +34,7 @@ extern "C" { # include # include # include -/* FIXME: Temporary hack until later patch creates new - * libvirt-domain-checkpoint.h file */ -typedef struct _virDomainCheckpoint virDomainCheckpoint; -typedef virDomainCheckpoint *virDomainCheckpointPtr; +# include # include # include # include diff --git a/libvirt.spec.in b/libvirt.spec.in index 4dee2d8ac2..045c0fed1a 100644 --- a/libvirt.spec.in +++ b/libvirt.spec.in @@ -1862,6 +1862,7 @@ exit 0 %{_includedir}/libvirt/libvirt-admin.h %{_includedir}/libvirt/libvirt-common.h %{_includedir}/libvirt/libvirt-domain.h +%{_includedir}/libvirt/libvirt-domain-checkpoint.h %{_includedir}/libvirt/libvirt-domain-snapshot.h %{_includedir}/libvirt/libvirt-event.h %{_includedir}/libvirt/libvirt-host.h diff --git a/mingw-libvirt.spec.in b/mingw-libvirt.spec.in index df89d9f8b3..a20c4b7d74 100644 --- a/mingw-libvirt.spec.in +++ b/mingw-libvirt.spec.in @@ -264,6 +264,7 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-guests.sh %{mingw32_includedir}/libvirt/libvirt.h %{mingw32_includedir}/libvirt/libvirt-common.h %{mingw32_includedir}/libvirt/libvirt-domain.h +%{mingw32_includedir}/libvirt/libvirt-domain-checkpoint.h %{mingw32_includedir}/libvirt/libvirt-domain-snapshot.h %{mingw32_includedir}/libvirt/libvirt-event.h %{mingw32_includedir}/libvirt/libvirt-host.h @@ -354,6 +355,7 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-guests.sh %{mingw64_includedir}/libvirt/libvirt.h %{mingw64_includedir}/libvirt/libvirt-common.h %{mingw64_includedir}/libvirt/libvirt-domain.h +%{mingw64_includedir}/libvirt/libvirt-domain-checkpoint.h %{mingw64_includedir}/libvirt/libvirt-domain-snapshot.h %{mingw64_includedir}/libvirt/libvirt-event.h %{mingw64_includedir}/libvirt/libvirt-host.h diff --git a/po/POTFILES b/po/POTFILES index ab582ffbe9..5d0bf43f02 100644 --- a/po/POTFILES +++ b/po/POTFILES @@ -69,6 +69,7 @@ src/interface/interface_backend_netcf.c src/interface/interface_backend_udev.c src/internal.h src/libvirt-admin.c +src/libvirt-domain-checkpoint.c src/libvirt-domain-snapshot.c src/libvirt-domain.c src/libvirt-host.c diff --git a/src/Makefile.am b/src/Makefile.am index 0b562dc250..4a8cae11dc 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -167,6 +167,7 @@ DRIVER_SOURCES += \ $(DATATYPES_SOURCES) \ libvirt.c libvirt_internal.h \ libvirt-domain.c \ + libvirt-domain-checkpoint.c \ libvirt-domain-snapshot.c \ libvirt-host.c \ libvirt-interface.c \ @@ -719,6 +720,7 @@ libvirt_setuid_rpc_client_la_SOURCES = \ datatypes.c \ libvirt.c \ libvirt-domain.c \ + libvirt-domain-checkpoint.c \ libvirt-domain-snapshot.c \ libvirt-host.c \ libvirt-interface.c \ diff --git a/src/conf/virdomainmomentobjlist.h b/src/conf/virdomainmomentobjlist.h index 897d8d54d1..5b73175e8d 100644 --- a/src/conf/virdomainmomentobjlist.h +++ b/src/conf/virdomainmomentobjlist.h @@ -70,8 +70,9 @@ virDomainMomentObjPtr virDomainMomentAssignDef(virDomainMomentObjListPtr moments virDomainMomentDefPtr def); /* Various enum bits that map to public API filters. Note that the - * values of the internal bits are not necessarily the same as the - * public ones. */ + * values of the internal bits are not the same as the public ones for + * snapshot, however, this list should be kept in sync with the public + * ones for checkpoint. */ typedef enum { VIR_DOMAIN_MOMENT_LIST_ROOTS = (1 << 0), VIR_DOMAIN_MOMENT_LIST_DESCENDANTS = (1 << 0), diff --git a/src/driver-hypervisor.h b/src/driver-hypervisor.h index b15aaa36bc..c1632ae4c6 100644 --- a/src/driver-hypervisor.h +++ b/src/driver-hypervisor.h @@ -1327,6 +1327,37 @@ typedef int int *nparams, unsigned int flags); +typedef virDomainCheckpointPtr +(*virDrvDomainCheckpointCreateXML)(virDomainPtr domain, + const char *xmlDesc, + unsigned int flags); + +typedef char * +(*virDrvDomainCheckpointGetXMLDesc)(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +typedef int +(*virDrvDomainListAllCheckpoints)(virDomainPtr domain, + virDomainCheckpointPtr **checkpoints, + unsigned int flags); + +typedef int +(*virDrvDomainCheckpointListAllChildren)(virDomainCheckpointPtr checkpoint, + virDomainCheckpointPtr **children, + unsigned int flags); + +typedef virDomainCheckpointPtr +(*virDrvDomainCheckpointLookupByName)(virDomainPtr domain, + const char *name, + unsigned int flags); + +typedef virDomainCheckpointPtr +(*virDrvDomainCheckpointGetParent)(virDomainCheckpointPtr checkpoint, + unsigned int flags); + +typedef int +(*virDrvDomainCheckpointDelete)(virDomainCheckpointPtr checkpoint, + unsigned int flags); typedef struct _virHypervisorDriver virHypervisorDriver; typedef virHypervisorDriver *virHypervisorDriverPtr; @@ -1579,4 +1610,11 @@ struct _virHypervisorDriver { virDrvConnectBaselineHypervisorCPU connectBaselineHypervisorCPU; virDrvNodeGetSEVInfo nodeGetSEVInfo; virDrvDomainGetLaunchSecurityInfo domainGetLaunchSecurityInfo; + virDrvDomainCheckpointCreateXML domainCheckpointCreateXML; + virDrvDomainCheckpointGetXMLDesc domainCheckpointGetXMLDesc; + virDrvDomainListAllCheckpoints domainListAllCheckpoints; + virDrvDomainCheckpointListAllChildren domainCheckpointListAllChildren; + virDrvDomainCheckpointLookupByName domainCheckpointLookupByName; + virDrvDomainCheckpointGetParent domainCheckpointGetParent; + virDrvDomainCheckpointDelete domainCheckpointDelete; }; diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c new file mode 100644 index 0000000000..fa391f8a06 --- /dev/null +++ b/src/libvirt-domain-checkpoint.c @@ -0,0 +1,567 @@ +/* + * libvirt-domain-checkpoint.c: entry points for virDomainCheckpointPtr APIs + * + * 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 + * . + */ + +#include + +#include "datatypes.h" +#include "virlog.h" + +VIR_LOG_INIT("libvirt.domain-checkpoint"); + +#define VIR_FROM_THIS VIR_FROM_DOMAIN_CHECKPOINT + +/** + * virDomainCheckpointGetName: + * @checkpoint: a checkpoint object + * + * Get the public name for that checkpoint + * + * 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. + */ +const char * +virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint) +{ + VIR_DEBUG("checkpoint=%p", checkpoint); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, NULL); + + return checkpoint->name; +} + + +/** + * virDomainCheckpointGetDomain: + * @checkpoint: a checkpoint object + * + * Provides the domain pointer associated with a checkpoint. The + * reference counter on the domain is not increased by this + * call. + * + * Returns the domain or NULL. + */ +virDomainPtr +virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint) +{ + VIR_DEBUG("checkpoint=%p", checkpoint); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, NULL); + + return checkpoint->domain; +} + + +/** + * virDomainCheckpointGetConnect: + * @checkpoint: a checkpoint object + * + * Provides the connection pointer associated with a checkpoint. The + * reference counter on the connection is not increased by this + * call. + * + * Returns the connection or NULL. + */ +virConnectPtr +virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint) +{ + VIR_DEBUG("checkpoint=%p", checkpoint); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, NULL); + + return checkpoint->domain->conn; +} + + +/** + * virDomainCheckpointCreateXML: + * @domain: a domain object + * @xmlDesc: description of the checkpoint to create + * @flags: bitwise-OR of supported virDomainCheckpointCreateFlags + * + * Create a new checkpoint using @xmlDesc, with a top-level + * element, on a running @domain. Note that @xmlDesc + * must validate against the XML schema. + * + * See 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_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. + * + * Returns an (opaque) new virDomainCheckpointPtr on success or NULL + * on failure. + */ +virDomainCheckpointPtr +virDomainCheckpointCreateXML(virDomainPtr domain, + const char *xmlDesc, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "xmlDesc=%s, flags=0x%x", xmlDesc, flags); + + virResetLastError(); + + virCheckDomainReturn(domain, NULL); + conn = domain->conn; + + virCheckNonNullArgGoto(xmlDesc, error); + virCheckReadOnlyGoto(conn->flags, error); + + VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE, + VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE, + error); + + if (conn->driver->domainCheckpointCreateXML) { + virDomainCheckpointPtr ret; + ret = conn->driver->domainCheckpointCreateXML(domain, xmlDesc, flags); + if (!ret) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainCheckpointGetXMLDesc: + * @checkpoint: a domain checkpoint object + * @flags: bitwise-OR of supported virDomainCheckpointXMLFlags + * + * 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 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. + * + * Returns a 0 terminated UTF-8 encoded XML instance or NULL in case + * of error. The caller must free() the returned value. + */ +char * +virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint, + unsigned int flags) +{ + virConnectPtr conn; + VIR_DEBUG("checkpoint=%p, flags=0x%x", checkpoint, flags); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, NULL); + conn = checkpoint->domain->conn; + + if ((conn->flags & VIR_CONNECT_RO) && + (flags & VIR_DOMAIN_CHECKPOINT_XML_SECURE)) { + virReportError(VIR_ERR_OPERATION_DENIED, "%s", + _("virDomainCheckpointGetXMLDesc with secure flag")); + goto error; + } + + if (conn->driver->domainCheckpointGetXMLDesc) { + char *ret; + ret = conn->driver->domainCheckpointGetXMLDesc(checkpoint, flags); + if (!ret) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainListAllCheckpoints: + * @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 + * + * 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). + * + * 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. + */ +int +virDomainListAllCheckpoints(virDomainPtr domain, + virDomainCheckpointPtr **checkpoints, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "checkpoints=%p, flags=0x%x", checkpoints, flags); + + virResetLastError(); + + if (checkpoints) + *checkpoints = NULL; + + virCheckDomainReturn(domain, -1); + conn = domain->conn; + + if (conn->driver->domainListAllCheckpoints) { + int ret = conn->driver->domainListAllCheckpoints(domain, checkpoints, + flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainCheckpointListAllChildren: + * @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 + * + * 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). + * + * 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. + */ +int +virDomainCheckpointListAllChildren(virDomainCheckpointPtr checkpoint, + virDomainCheckpointPtr **children, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("checkpoint=%p, children=%p, flags=0x%x", + checkpoint, children, flags); + + virResetLastError(); + + if (children) + *children = NULL; + + virCheckDomainCheckpointReturn(checkpoint, -1); + conn = checkpoint->domain->conn; + + if (conn->driver->domainCheckpointListAllChildren) { + int ret = conn->driver->domainCheckpointListAllChildren(checkpoint, + children, + flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainCheckpointLookupByName: + * @domain: a domain object + * @name: name for the domain checkpoint + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Try to lookup a domain checkpoint based on its name. + * + * 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. + */ +virDomainCheckpointPtr +virDomainCheckpointLookupByName(virDomainPtr domain, + const char *name, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "name=%s, flags=0x%x", name, flags); + + virResetLastError(); + + virCheckDomainReturn(domain, NULL); + conn = domain->conn; + + virCheckNonNullArgGoto(name, error); + + if (conn->driver->domainCheckpointLookupByName) { + virDomainCheckpointPtr checkpoint; + checkpoint = conn->driver->domainCheckpointLookupByName(domain, name, + flags); + if (!checkpoint) + goto error; + return checkpoint; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainCheckpointGetParent: + * @checkpoint: a checkpoint object + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Get the parent checkpoint for @checkpoint, if any. + * + * virDomainCheckpointFree should be used to free the resources after the + * checkpoint object is no longer needed. + * + * 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. + */ +virDomainCheckpointPtr +virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("checkpoint=%p, flags=0x%x", checkpoint, flags); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, NULL); + conn = checkpoint->domain->conn; + + if (conn->driver->domainCheckpointGetParent) { + virDomainCheckpointPtr parent; + parent = conn->driver->domainCheckpointGetParent(checkpoint, flags); + if (!parent) + goto error; + return parent; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainCheckpointDelete: + * @checkpoint: the checkpoint to remove + * @flags: bitwise-OR of supported virDomainCheckpointDeleteFlags + * + * 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. + * + * Returns 0 on success, -1 on error. + */ +int +virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("checkpoint=%p, flags=0x%x", checkpoint, flags); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, -1); + conn = checkpoint->domain->conn; + + virCheckReadOnlyGoto(conn->flags, error); + + VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN, + VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY, + error); + + if (conn->driver->domainCheckpointDelete) { + int ret = conn->driver->domainCheckpointDelete(checkpoint, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainCheckpointRef: + * @checkpoint: the checkpoint to hold a reference on + * + * 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. + * + * Returns 0 in case of success and -1 in case of failure. + */ +int +virDomainCheckpointRef(virDomainCheckpointPtr checkpoint) +{ + VIR_DEBUG("checkpoint=%p, refs=%d", checkpoint, + checkpoint ? checkpoint->parent.u.s.refs : 0); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, -1); + + virObjectRef(checkpoint); + return 0; +} + + +/** + * virDomainCheckpointFree: + * @checkpoint: a domain checkpoint object + * + * Free the domain checkpoint object. The checkpoint itself is not modified. + * The data structure is freed and should not be used thereafter. + * + * Returns 0 in case of success and -1 in case of failure. + */ +int +virDomainCheckpointFree(virDomainCheckpointPtr checkpoint) +{ + VIR_DEBUG("checkpoint=%p", checkpoint); + + virResetLastError(); + + virCheckDomainCheckpointReturn(checkpoint, -1); + + virObjectUnref(checkpoint); + return 0; +} diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 3d12e7c125..2fe9bb8e91 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -6218,8 +6218,9 @@ virDomainDefineXMLFlags(virConnectPtr conn, const char *xml, unsigned int flags) * * If the domain has a managed save image (see * virDomainHasManagedSaveImage()), or if it is inactive and has any - * snapshot metadata (see virDomainSnapshotNum()), then the undefine will - * fail. See virDomainUndefineFlags() for more control. + * snapshot metadata (see virDomainSnapshotNum()) or checkpoint + * metadata (see virDomainListAllCheckpoints()), then the undefine + * will fail. See virDomainUndefineFlags() for more control. * * Returns 0 in case of success, -1 in case of error */ @@ -6276,6 +6277,16 @@ virDomainUndefine(virDomainPtr domain) * support snapshots, but where snapshots do not use libvirt metadata, * this flag has no effect. * + * If the domain is inactive and has any checkpoint metadata (see + * virDomainListAllCheckpoints()), then including + * VIR_DOMAIN_UNDEFINE_CHECKPOINTS_METADATA in @flags will also remove + * that metadata. Omitting the flag will cause the undefine of an + * inactive domain with checkpoints to fail. Active domains will + * retain checkpoint metadata until the (now-transient) domain halts, + * regardless of whether this flag is present. On hypervisors that + * support checkpoints, but where checkpoints do not use libvirt + * metadata, this flag has no effect. + * * If the domain has any nvram specified, the undefine process will fail * unless VIR_DOMAIN_UNDEFINE_KEEP_NVRAM is specified, or if * VIR_DOMAIN_UNDEFINE_NVRAM is specified to remove the nvram file. @@ -6436,7 +6447,9 @@ virConnectListDefinedDomains(virConnectPtr conn, char **const names, * VIR_CONNECT_LIST_DOMAINS_NO_AUTOSTART, for filtering based on autostart; * VIR_CONNECT_LIST_DOMAINS_HAS_SNAPSHOT and * VIR_CONNECT_LIST_DOMAINS_NO_SNAPSHOT, for filtering based on whether - * a domain has snapshots. + * a domain has snapshots; VIR_CONNECT_LIST_DOMAINS_HAS_CHECKPOINT and + * VIR_CONNECT_LIST_DOMAINS_NO_CHECKPOINT, for filtering based on whether + * a domain has checkpoints. * * Example of usage: * diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms index 18500ec8b2..54256b6317 100644 --- a/src/libvirt_public.syms +++ b/src/libvirt_public.syms @@ -836,4 +836,20 @@ LIBVIRT_5.5.0 { virNetworkPortSetParameters; } LIBVIRT_5.2.0; +LIBVIRT_5.6.0 { + global: + virDomainCheckpointCreateXML; + virDomainCheckpointDelete; + virDomainCheckpointFree; + virDomainCheckpointGetConnect; + virDomainCheckpointGetDomain; + virDomainCheckpointGetName; + virDomainCheckpointGetParent; + virDomainCheckpointGetXMLDesc; + virDomainCheckpointListAllChildren; + virDomainCheckpointLookupByName; + virDomainCheckpointRef; + virDomainListAllCheckpoints; +} LIBVIRT_5.5.0; + # .... define new API here using predicted next version number ....