[libvirt] [PATCH 03/12] Move virDomainSnapshot related APIs out of libvirt.c

Introduce a src/libvirt-domain-snapshot.c file to hold all the methods related to the virDomainSnapshot type. --- docs/apibuild.py | 1 + po/POTFILES.in | 1 + src/Makefile.am | 2 + src/datatypes.h | 1 + src/libvirt-domain-snapshot.c | 1222 +++++++++++++++++++++++++++++++++++++++++ src/libvirt.c | 1194 ---------------------------------------- 6 files changed, 1227 insertions(+), 1194 deletions(-) create mode 100644 src/libvirt-domain-snapshot.c diff --git a/docs/apibuild.py b/docs/apibuild.py index 30e224d..b5bd936 100755 --- a/docs/apibuild.py +++ b/docs/apibuild.py @@ -24,6 +24,7 @@ included_files = { "libvirt.h": "header with general libvirt API definitions", "virterror.h": "header with error specific API definitions", "libvirt.c": "Main interfaces for the libvirt library", + "libvirt-domain-snapshot.c": "Domain snapshot interfaces for the libvirt library", "virerror.c": "implements error handling and reporting code for libvirt", "virevent.c": "event loop for monitoring file handles", "virtypedparam.c": "virTypedParameters APIs", diff --git a/po/POTFILES.in b/po/POTFILES.in index 59be2e6..6f88a15 100644 --- a/po/POTFILES.in +++ b/po/POTFILES.in @@ -57,6 +57,7 @@ src/interface/interface_backend_netcf.c src/interface/interface_backend_udev.c src/internal.h src/libvirt.c +src/libvirt-domain-snapshot.c src/libvirt-lxc.c src/libvirt-qemu.c src/locking/lock_daemon.c diff --git a/src/Makefile.am b/src/Makefile.am index 7521bde..1b0a97d 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -189,6 +189,7 @@ DRIVER_SOURCES = \ fdstream.c fdstream.h \ $(NODE_INFO_SOURCES) \ libvirt.c libvirt_internal.h \ + libvirt-domain-snapshot.c \ locking/lock_manager.c locking/lock_manager.h \ locking/lock_driver.h \ locking/lock_driver_nop.h locking/lock_driver_nop.c \ @@ -2186,6 +2187,7 @@ libvirt_setuid_rpc_client_la_SOURCES = \ remote/lxc_protocol.c \ datatypes.c \ libvirt.c \ + libvirt-domain-snapshot.c \ libvirt-lxc.c \ $(NULL) diff --git a/src/datatypes.h b/src/datatypes.h index 5868ce3..1d6c382 100644 --- a/src/datatypes.h +++ b/src/datatypes.h @@ -27,6 +27,7 @@ # include "driver.h" # include "virthread.h" # include "virobject.h" +# include "viruuid.h" extern virClassPtr virConnectClass; extern virClassPtr virDomainClass; diff --git a/src/libvirt-domain-snapshot.c b/src/libvirt-domain-snapshot.c new file mode 100644 index 0000000..3b41a37 --- /dev/null +++ b/src/libvirt-domain-snapshot.c @@ -0,0 +1,1222 @@ +/* + * libvirt-domain-snapshot.c: entry points for virDomainSnapshotPtr APIs + * + * Copyright (C) 2006-2014 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/>;. + */ + +#include <config.h> + +#include "datatypes.h" +#include "virlog.h" + +VIR_LOG_INIT("libvirt.domain-snapshot"); + +#define VIR_FROM_THIS VIR_FROM_NONE + +/** + * virDomainSnapshotGetName: + * @snapshot: a snapshot object + * + * Get the public name for that snapshot + * + * Returns a pointer to the name or NULL, the string need not be deallocated + * as its lifetime will be the same as the snapshot object. + */ +const char * +virDomainSnapshotGetName(virDomainSnapshotPtr snapshot) +{ + VIR_DEBUG("snapshot=%p", snapshot); + + virResetLastError(); + + virCheckDomainSnapshotReturn(snapshot, NULL); + + return snapshot->name; +} + + +/** + * virDomainSnapshotGetDomain: + * @snapshot: a snapshot object + * + * Provides the domain pointer associated with a snapshot. The + * reference counter on the domain is not increased by this + * call. + * + * WARNING: When writing libvirt bindings in other languages, do not use this + * function. Instead, store the domain and the snapshot object together. + * + * Returns the domain or NULL. + */ +virDomainPtr +virDomainSnapshotGetDomain(virDomainSnapshotPtr snapshot) +{ + VIR_DEBUG("snapshot=%p", snapshot); + + virResetLastError(); + + virCheckDomainSnapshotReturn(snapshot, NULL); + + return snapshot->domain; +} + + +/** + * virDomainSnapshotGetConnect: + * @snapshot: a snapshot object + * + * Provides the connection pointer associated with a snapshot. The + * reference counter on the connection is not increased by this + * call. + * + * WARNING: When writing libvirt bindings in other languages, do not use this + * function. Instead, store the connection and the snapshot object together. + * + * Returns the connection or NULL. + */ +virConnectPtr +virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot) +{ + VIR_DEBUG("snapshot=%p", snapshot); + + virResetLastError(); + + virCheckDomainSnapshotReturn(snapshot, NULL); + + return snapshot->domain->conn; +} + + +/** + * virDomainSnapshotCreateXML: + * @domain: a domain object + * @xmlDesc: string containing an XML description of the domain + * @flags: bitwise-OR of virDomainSnapshotCreateFlags + * + * Creates a new snapshot of a domain based on the snapshot xml + * contained in xmlDesc. + * + * If @flags is 0, the domain can be active, in which case the + * snapshot will be a system checkpoint (both disk state and runtime + * VM state such as RAM contents), where reverting to the snapshot is + * the same as resuming from hibernation (TCP connections may have + * timed out, but everything else picks up where it left off); or + * the domain can be inactive, in which case the snapshot includes + * just the disk state prior to booting. The newly created snapshot + * becomes current (see virDomainSnapshotCurrent()), and is a child + * of any previous current snapshot. + * + * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE, then this + * is a request to reinstate snapshot metadata that was previously + * discarded, rather than creating a new snapshot. This can be used + * to recreate a snapshot hierarchy on a destination, then remove it + * on the source, in order to allow migration (since migration + * normally fails if snapshot metadata still remains on the source + * machine). When redefining snapshot metadata, the current snapshot + * will not be altered unless the VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT + * flag is also present. It is an error to request the + * VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT flag without + * VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE. On some hypervisors, + * redefining an existing snapshot can be used to alter host-specific + * portions of the domain XML to be used during revert (such as + * backing filenames associated with disk devices), but must not alter + * guest-visible layout. When redefining a snapshot name that does + * not exist, the hypervisor may validate that reverting to the + * snapshot appears to be possible (for example, disk images have + * snapshot contents by the requested name). Not all hypervisors + * support these flags. + * + * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_NO_METADATA, then the + * domain's disk images are modified according to @xmlDesc, but then + * the just-created snapshot has its metadata deleted. This flag is + * incompatible with VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE. + * + * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_HALT, then the domain + * will be inactive after the snapshot completes, regardless of whether + * it was active before; otherwise, a running domain will still be + * running after the snapshot. This flag is invalid on transient domains, + * and is incompatible with VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE. + * + * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_LIVE, then the domain + * is not paused while creating the snapshot. This increases the size + * of the memory dump file, but reduces downtime of the guest while + * taking the snapshot. Some hypervisors only support this flag during + * external checkpoints. + * + * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY, then the + * snapshot will be limited to the disks described in @xmlDesc, and no + * VM state will be saved. For an active guest, the disk image may be + * inconsistent (as if power had been pulled), and specifying this + * with the VIR_DOMAIN_SNAPSHOT_CREATE_HALT flag risks data loss. + * + * If @flags includes VIR_DOMAIN_SNAPSHOT_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. Moreover, this flag requires + * VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY to be passed as well. + * + * By default, if the snapshot involves external files, and any of the + * destination files already exist as a non-empty regular file, the + * snapshot is rejected to avoid losing contents of those files. + * However, if @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_REUSE_EXT, + * then the destination files must be pre-created manually with + * the correct image format and metadata including backing store path + * (this allows a management app to pre-create files with relative backing + * file names, rather than the default of creating with absolute backing + * file names). Note that setting incorrect metadata in the pre-created + * image may lead to the VM being unable to start. + * + * Be aware that although libvirt prefers to report errors up front with + * no other effect, some hypervisors have certain types of failures where + * the overall command can easily fail even though the guest configuration + * was partially altered (for example, if a disk snapshot request for two + * disks fails on the second disk, but the first disk alteration cannot be + * rolled back). If this API call fails, it is therefore normally + * necessary to follow up with virDomainGetXMLDesc() and check each disk + * to determine if any partial changes occurred. However, if @flags + * contains VIR_DOMAIN_SNAPSHOT_CREATE_ATOMIC, then libvirt guarantees + * that this command will not alter any disks unless the entire set of + * changes can be done atomically, making failure recovery simpler (note + * that it is still possible to fail after disks have changed, but only + * in the much rarer cases of running out of memory or disk space). + * + * Some hypervisors may prevent this operation if there is a current + * block copy operation; in that case, use virDomainBlockJobAbort() + * to stop the block copy first. + * + * virDomainSnapshotFree should be used to free the resources after the + * snapshot object is no longer needed. + * + * Returns an (opaque) virDomainSnapshotPtr on success, NULL on failure. + */ +virDomainSnapshotPtr +virDomainSnapshotCreateXML(virDomainPtr domain, + const char *xmlDesc, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "xmlDesc=%s, flags=%x", xmlDesc, flags); + + virResetLastError(); + + virCheckDomainReturn(domain, NULL); + conn = domain->conn; + + virCheckNonNullArgGoto(xmlDesc, error); + virCheckReadOnlyGoto(conn->flags, error); + + if ((flags & VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT) && + !(flags & VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE)) { + virReportInvalidArg(flags, + _("use of 'current' flag in %s requires " + "'redefine' flag"), + __FUNCTION__); + goto error; + } + if ((flags & VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE) && + (flags & VIR_DOMAIN_SNAPSHOT_CREATE_NO_METADATA)) { + virReportInvalidArg(flags, + _("'redefine' and 'no metadata' flags in %s are " + "mutually exclusive"), + __FUNCTION__); + goto error; + } + if ((flags & VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE) && + (flags & VIR_DOMAIN_SNAPSHOT_CREATE_HALT)) { + virReportInvalidArg(flags, + _("'redefine' and 'halt' flags in %s are mutually " + "exclusive"), + __FUNCTION__); + goto error; + } + + if (conn->driver->domainSnapshotCreateXML) { + virDomainSnapshotPtr ret; + ret = conn->driver->domainSnapshotCreateXML(domain, xmlDesc, flags); + if (!ret) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainSnapshotGetXMLDesc: + * @snapshot: a domain snapshot object + * @flags: bitwise-OR of subset of virDomainXMLFlags + * + * Provide an XML description of the domain snapshot. + * + * No security-sensitive data will be included unless @flags contains + * VIR_DOMAIN_XML_SECURE; this flag is rejected on read-only + * connections. For this API, @flags should not contain either + * VIR_DOMAIN_XML_INACTIVE or VIR_DOMAIN_XML_UPDATE_CPU. + * + * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error. + * the caller must free() the returned value. + */ +char * +virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot, + unsigned int flags) +{ + virConnectPtr conn; + VIR_DEBUG("snapshot=%p, flags=%x", snapshot, flags); + + virResetLastError(); + + virCheckDomainSnapshotReturn(snapshot, NULL); + conn = snapshot->domain->conn; + + if ((conn->flags & VIR_CONNECT_RO) && (flags & VIR_DOMAIN_XML_SECURE)) { + virReportError(VIR_ERR_OPERATION_DENIED, "%s", + _("virDomainSnapshotGetXMLDesc with secure flag")); + goto error; + } + + if (conn->driver->domainSnapshotGetXMLDesc) { + char *ret; + ret = conn->driver->domainSnapshotGetXMLDesc(snapshot, flags); + if (!ret) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainSnapshotNum: + * @domain: a domain object + * @flags: bitwise-OR of supported virDomainSnapshotListFlags + * + * Provides the number of domain snapshots for this domain. + * + * By default, this command covers all snapshots; it is also possible to + * limit things to just snapshots with no parents, when @flags includes + * VIR_DOMAIN_SNAPSHOT_LIST_ROOTS. Additional filters are provided in + * groups, where each group contains bits that describe mutually exclusive + * attributes of a snapshot, and where all bits within a group describe + * all possible snapshots. Some hypervisors might reject explicit bits + * from a group where the hypervisor cannot make a distinction. For a + * group supported by a given hypervisor, the behavior when no bits of a + * group are set is identical to the behavior when all bits in that group + * are set. When setting bits from more than one group, it is possible to + * select an impossible combination, in that case a hypervisor may return + * either 0 or an error. + * + * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and + * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that + * have no further children (a leaf snapshot). + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and + * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on + * whether they have metadata that would prevent the removal of the last + * reference to a domain. + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE, + * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY, + * for filtering snapshots based on what domain state is tracked by the + * snapshot. + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and + * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on + * whether the snapshot is stored inside the disk images or as + * additional files. + * + * Returns the number of domain snapshots found or -1 in case of error. + */ +int +virDomainSnapshotNum(virDomainPtr domain, unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "flags=%x", flags); + + virResetLastError(); + + virCheckDomainReturn(domain, -1); + + conn = domain->conn; + if (conn->driver->domainSnapshotNum) { + int ret = conn->driver->domainSnapshotNum(domain, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainSnapshotListNames: + * @domain: a domain object + * @names: array to collect the list of names of snapshots + * @nameslen: size of @names + * @flags: bitwise-OR of supported virDomainSnapshotListFlags + * + * Collect the list of domain snapshots for the given domain, and store + * their names in @names. The value to use for @nameslen can be determined + * by virDomainSnapshotNum() with the same @flags. + * + * By default, this command covers all snapshots; it is also possible to + * limit things to just snapshots with no parents, when @flags includes + * VIR_DOMAIN_SNAPSHOT_LIST_ROOTS. Additional filters are provided in + * groups, where each group contains bits that describe mutually exclusive + * attributes of a snapshot, and where all bits within a group describe + * all possible snapshots. Some hypervisors might reject explicit bits + * from a group where the hypervisor cannot make a distinction. For a + * group supported by a given hypervisor, the behavior when no bits of a + * group are set is identical to the behavior when all bits in that group + * are set. When setting bits from more than one group, it is possible to + * select an impossible combination, in that case a hypervisor may return + * either 0 or an error. + * + * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and + * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that + * have no further children (a leaf snapshot). + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and + * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on + * whether they have metadata that would prevent the removal of the last + * reference to a domain. + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE, + * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY, + * for filtering snapshots based on what domain state is tracked by the + * snapshot. + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and + * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on + * whether the snapshot is stored inside the disk images or as + * additional files. + * + * Note that this command is inherently racy: another connection can + * define a new snapshot between a call to virDomainSnapshotNum() and + * this call. You are only guaranteed that all currently defined + * snapshots were listed if the return is less than @nameslen. Likewise, + * you should be prepared for virDomainSnapshotLookupByName() to fail when + * converting a name from this call into a snapshot object, if another + * connection deletes the snapshot in the meantime. For more control over + * the results, see virDomainListAllSnapshots(). + * + * Returns the number of domain snapshots found or -1 in case of error. + * The caller is responsible to call free() for each member of the array. + */ +int +virDomainSnapshotListNames(virDomainPtr domain, char **names, int nameslen, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "names=%p, nameslen=%d, flags=%x", + names, nameslen, flags); + + virResetLastError(); + + virCheckDomainReturn(domain, -1); + conn = domain->conn; + + virCheckNonNullArgGoto(names, error); + virCheckNonNegativeArgGoto(nameslen, error); + + if (conn->driver->domainSnapshotListNames) { + int ret = conn->driver->domainSnapshotListNames(domain, names, + nameslen, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainListAllSnapshots: + * @domain: a domain object + * @snaps: pointer to variable to store the array containing snapshot objects, + * or NULL if the list is not required (just returns number of + * snapshots) + * @flags: bitwise-OR of supported virDomainSnapshotListFlags + * + * Collect the list of domain snapshots for the given domain, and allocate + * an array to store those objects. This API solves the race inherent in + * virDomainSnapshotListNames(). + * + * By default, this command covers all snapshots; it is also possible to + * limit things to just snapshots with no parents, when @flags includes + * VIR_DOMAIN_SNAPSHOT_LIST_ROOTS. Additional filters are provided in + * groups, where each group contains bits that describe mutually exclusive + * attributes of a snapshot, and where all bits within a group describe + * all possible snapshots. Some hypervisors might reject explicit bits + * from a group where the hypervisor cannot make a distinction. For a + * group supported by a given hypervisor, the behavior when no bits of a + * group are set is identical to the behavior when all bits in that group + * are set. When setting bits from more than one group, it is possible to + * select an impossible combination, in that case a hypervisor may return + * either 0 or an error. + * + * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and + * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that + * have no further children (a leaf snapshot). + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and + * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on + * whether they have metadata that would prevent the removal of the last + * reference to a domain. + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE, + * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY, + * for filtering snapshots based on what domain state is tracked by the + * snapshot. + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and + * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on + * whether the snapshot is stored inside the disk images or as + * additional files. + * + * Returns the number of domain snapshots found or -1 and sets @snaps to + * NULL in case of error. On success, the array stored into @snaps 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 virDomainSnapshotFree() on each array element, then calling + * free() on @snaps. + */ +int +virDomainListAllSnapshots(virDomainPtr domain, virDomainSnapshotPtr **snaps, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "snaps=%p, flags=%x", snaps, flags); + + virResetLastError(); + + if (snaps) + *snaps = NULL; + + virCheckDomainReturn(domain, -1); + conn = domain->conn; + + if (conn->driver->domainListAllSnapshots) { + int ret = conn->driver->domainListAllSnapshots(domain, snaps, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainSnapshotNumChildren: + * @snapshot: a domain snapshot object + * @flags: bitwise-OR of supported virDomainSnapshotListFlags + * + * Provides the number of child snapshots for this domain snapshot. + * + * By default, this command covers only direct children; it is also possible + * to expand things to cover all descendants, when @flags includes + * VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Also, some filters are provided in + * groups, where each group contains bits that describe mutually exclusive + * attributes of a snapshot, and where all bits within a group describe + * all possible snapshots. Some hypervisors might reject explicit bits + * from a group where the hypervisor cannot make a distinction. For a + * group supported by a given hypervisor, the behavior when no bits of a + * group are set is identical to the behavior when all bits in that group + * are set. When setting bits from more than one group, it is possible to + * select an impossible combination, in that case a hypervisor may return + * either 0 or an error. + * + * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and + * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that + * have no further children (a leaf snapshot). + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and + * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on + * whether they have metadata that would prevent the removal of the last + * reference to a domain. + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE, + * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY, + * for filtering snapshots based on what domain state is tracked by the + * snapshot. + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and + * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on + * whether the snapshot is stored inside the disk images or as + * additional files. + * + * Returns the number of domain snapshots found or -1 in case of error. + */ +int +virDomainSnapshotNumChildren(virDomainSnapshotPtr snapshot, unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("snapshot=%p, flags=%x", snapshot, flags); + + virResetLastError(); + + virCheckDomainSnapshotReturn(snapshot, -1); + conn = snapshot->domain->conn; + + if (conn->driver->domainSnapshotNumChildren) { + int ret = conn->driver->domainSnapshotNumChildren(snapshot, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainSnapshotListChildrenNames: + * @snapshot: a domain snapshot object + * @names: array to collect the list of names of snapshots + * @nameslen: size of @names + * @flags: bitwise-OR of supported virDomainSnapshotListFlags + * + * Collect the list of domain snapshots that are children of the given + * snapshot, and store their names in @names. The value to use for + * @nameslen can be determined by virDomainSnapshotNumChildren() with + * the same @flags. + * + * By default, this command covers only direct children; it is also possible + * to expand things to cover all descendants, when @flags includes + * VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Also, some filters are provided in + * groups, where each group contains bits that describe mutually exclusive + * attributes of a snapshot, and where all bits within a group describe + * all possible snapshots. Some hypervisors might reject explicit bits + * from a group where the hypervisor cannot make a distinction. For a + * group supported by a given hypervisor, the behavior when no bits of a + * group are set is identical to the behavior when all bits in that group + * are set. When setting bits from more than one group, it is possible to + * select an impossible combination, in that case a hypervisor may return + * either 0 or an error. + * + * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and + * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that + * have no further children (a leaf snapshot). + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and + * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on + * whether they have metadata that would prevent the removal of the last + * reference to a domain. + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE, + * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY, + * for filtering snapshots based on what domain state is tracked by the + * snapshot. + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and + * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on + * whether the snapshot is stored inside the disk images or as + * additional files. + * + * Returns the number of domain snapshots found or -1 in case of error. + * Note that this command is inherently racy: another connection can + * define a new snapshot between a call to virDomainSnapshotNumChildren() + * and this call. You are only guaranteed that all currently defined + * snapshots were listed if the return is less than @nameslen. Likewise, + * you should be prepared for virDomainSnapshotLookupByName() to fail when + * converting a name from this call into a snapshot object, if another + * connection deletes the snapshot in the meantime. For more control over + * the results, see virDomainSnapshotListAllChildren(). + * + * Returns the number of domain snapshots found or -1 in case of error. + * The caller is responsible to call free() for each member of the array. + */ +int +virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot, + char **names, int nameslen, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("snapshot=%p, names=%p, nameslen=%d, flags=%x", + snapshot, names, nameslen, flags); + + virResetLastError(); + + virCheckDomainSnapshotReturn(snapshot, -1); + conn = snapshot->domain->conn; + + virCheckNonNullArgGoto(names, error); + virCheckNonNegativeArgGoto(nameslen, error); + + if (conn->driver->domainSnapshotListChildrenNames) { + int ret = conn->driver->domainSnapshotListChildrenNames(snapshot, + names, + nameslen, + flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainSnapshotListAllChildren: + * @snapshot: a domain snapshot object + * @snaps: pointer to variable to store the array containing snapshot objects, + * or NULL if the list is not required (just returns number of + * snapshots) + * @flags: bitwise-OR of supported virDomainSnapshotListFlags + * + * Collect the list of domain snapshots that are children of the given + * snapshot, and allocate an array to store those objects. This API solves + * the race inherent in virDomainSnapshotListChildrenNames(). + * + * By default, this command covers only direct children; it is also possible + * to expand things to cover all descendants, when @flags includes + * VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Also, some filters are provided in + * groups, where each group contains bits that describe mutually exclusive + * attributes of a snapshot, and where all bits within a group describe + * all possible snapshots. Some hypervisors might reject explicit bits + * from a group where the hypervisor cannot make a distinction. For a + * group supported by a given hypervisor, the behavior when no bits of a + * group are set is identical to the behavior when all bits in that group + * are set. When setting bits from more than one group, it is possible to + * select an impossible combination, in that case a hypervisor may return + * either 0 or an error. + * + * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and + * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that + * have no further children (a leaf snapshot). + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and + * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on + * whether they have metadata that would prevent the removal of the last + * reference to a domain. + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE, + * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY, + * for filtering snapshots based on what domain state is tracked by the + * snapshot. + * + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and + * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on + * whether the snapshot is stored inside the disk images or as + * additional files. + * + * Returns the number of domain snapshots found or -1 and sets @snaps to + * NULL in case of error. On success, the array stored into @snaps 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 virDomainSnapshotFree() on each array element, then calling + * free() on @snaps. + */ +int +virDomainSnapshotListAllChildren(virDomainSnapshotPtr snapshot, + virDomainSnapshotPtr **snaps, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("snapshot=%p, snaps=%p, flags=%x", snapshot, snaps, flags); + + virResetLastError(); + + if (snaps) + *snaps = NULL; + + virCheckDomainSnapshotReturn(snapshot, -1); + conn = snapshot->domain->conn; + + if (conn->driver->domainSnapshotListAllChildren) { + int ret = conn->driver->domainSnapshotListAllChildren(snapshot, snaps, + flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainSnapshotLookupByName: + * @domain: a domain object + * @name: name for the domain snapshot + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Try to lookup a domain snapshot based on its name. + * + * Returns a domain snapshot object or NULL in case of failure. If the + * domain snapshot cannot be found, then the VIR_ERR_NO_DOMAIN_SNAPSHOT + * error is raised. + */ +virDomainSnapshotPtr +virDomainSnapshotLookupByName(virDomainPtr domain, + const char *name, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "name=%s, flags=%x", name, flags); + + virResetLastError(); + + virCheckDomainReturn(domain, NULL); + conn = domain->conn; + + virCheckNonNullArgGoto(name, error); + + if (conn->driver->domainSnapshotLookupByName) { + virDomainSnapshotPtr dom; + dom = conn->driver->domainSnapshotLookupByName(domain, name, flags); + if (!dom) + goto error; + return dom; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainHasCurrentSnapshot: + * @domain: pointer to the domain object + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Determine if the domain has a current snapshot. + * + * Returns 1 if such snapshot exists, 0 if it doesn't, -1 on error. + */ +int +virDomainHasCurrentSnapshot(virDomainPtr domain, unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "flags=%x", flags); + + virResetLastError(); + + virCheckDomainReturn(domain, -1); + conn = domain->conn; + + if (conn->driver->domainHasCurrentSnapshot) { + int ret = conn->driver->domainHasCurrentSnapshot(domain, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainSnapshotCurrent: + * @domain: a domain object + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Get the current snapshot for a domain, if any. + * + * virDomainSnapshotFree should be used to free the resources after the + * snapshot object is no longer needed. + * + * Returns a domain snapshot object or NULL in case of failure. If the + * current domain snapshot cannot be found, then the VIR_ERR_NO_DOMAIN_SNAPSHOT + * error is raised. + */ +virDomainSnapshotPtr +virDomainSnapshotCurrent(virDomainPtr domain, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DOMAIN_DEBUG(domain, "flags=%x", flags); + + virResetLastError(); + + virCheckDomainReturn(domain, NULL); + conn = domain->conn; + + if (conn->driver->domainSnapshotCurrent) { + virDomainSnapshotPtr snap; + snap = conn->driver->domainSnapshotCurrent(domain, flags); + if (!snap) + goto error; + return snap; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainSnapshotGetParent: + * @snapshot: a snapshot object + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Get the parent snapshot for @snapshot, if any. + * + * virDomainSnapshotFree should be used to free the resources after the + * snapshot object is no longer needed. + * + * Returns a domain snapshot object or NULL in case of failure. If the + * given snapshot is a root (no parent), then the VIR_ERR_NO_DOMAIN_SNAPSHOT + * error is raised. + */ +virDomainSnapshotPtr +virDomainSnapshotGetParent(virDomainSnapshotPtr snapshot, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("snapshot=%p, flags=%x", snapshot, flags); + + virResetLastError(); + + virCheckDomainSnapshotReturn(snapshot, NULL); + conn = snapshot->domain->conn; + + if (conn->driver->domainSnapshotGetParent) { + virDomainSnapshotPtr snap; + snap = conn->driver->domainSnapshotGetParent(snapshot, flags); + if (!snap) + goto error; + return snap; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return NULL; +} + + +/** + * virDomainSnapshotIsCurrent: + * @snapshot: a snapshot object + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Determine if the given snapshot is the domain's current snapshot. See + * also virDomainHasCurrentSnapshot(). + * + * Returns 1 if current, 0 if not current, or -1 on error. + */ +int +virDomainSnapshotIsCurrent(virDomainSnapshotPtr snapshot, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("snapshot=%p, flags=%x", snapshot, flags); + + virResetLastError(); + + virCheckDomainSnapshotReturn(snapshot, -1); + conn = snapshot->domain->conn; + + if (conn->driver->domainSnapshotIsCurrent) { + int ret; + ret = conn->driver->domainSnapshotIsCurrent(snapshot, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainSnapshotHasMetadata: + * @snapshot: a snapshot object + * @flags: extra flags; not used yet, so callers should always pass 0 + * + * Determine if the given snapshot is associated with libvirt metadata + * that would prevent the deletion of the domain. + * + * Returns 1 if the snapshot has metadata, 0 if the snapshot exists without + * help from libvirt, or -1 on error. + */ +int +virDomainSnapshotHasMetadata(virDomainSnapshotPtr snapshot, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("snapshot=%p, flags=%x", snapshot, flags); + + virResetLastError(); + + virCheckDomainSnapshotReturn(snapshot, -1); + conn = snapshot->domain->conn; + + if (conn->driver->domainSnapshotHasMetadata) { + int ret; + ret = conn->driver->domainSnapshotHasMetadata(snapshot, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainRevertToSnapshot: + * @snapshot: a domain snapshot object + * @flags: bitwise-OR of virDomainSnapshotRevertFlags + * + * Revert the domain to a given snapshot. + * + * Normally, the domain will revert to the same state the domain was + * in while the snapshot was taken (whether inactive, running, or + * paused), except that disk snapshots default to reverting to + * inactive state. Including VIR_DOMAIN_SNAPSHOT_REVERT_RUNNING in + * @flags overrides the snapshot state to guarantee a running domain + * after the revert; or including VIR_DOMAIN_SNAPSHOT_REVERT_PAUSED in + * @flags guarantees a paused domain after the revert. These two + * flags are mutually exclusive. While a persistent domain does not + * need either flag, it is not possible to revert a transient domain + * into an inactive state, so transient domains require the use of one + * of these two flags. + * + * Reverting to any snapshot discards all configuration changes made since + * the last snapshot. Additionally, reverting to a snapshot from a running + * domain is a form of data loss, since it discards whatever is in the + * guest's RAM at the time. Since the very nature of keeping snapshots + * implies the intent to roll back state, no additional confirmation is + * normally required for these lossy effects. + * + * However, there are two particular situations where reverting will + * be refused by default, and where @flags must include + * VIR_DOMAIN_SNAPSHOT_REVERT_FORCE to acknowledge the risks. 1) Any + * attempt to revert to a snapshot that lacks the metadata to perform + * ABI compatibility checks (generally the case for snapshots that + * lack a full <domain> when listed by virDomainSnapshotGetXMLDesc(), + * such as those created prior to libvirt 0.9.5). 2) Any attempt to + * revert a running domain to an active state that requires starting a + * new hypervisor instance rather than reusing the existing hypervisor + * (since this would terminate all connections to the domain, such as + * such as VNC or Spice graphics) - this condition arises from active + * snapshots that are provably ABI incomaptible, as well as from + * inactive snapshots with a @flags request to start the domain after + * the revert. + * + * Returns 0 if the creation is successful, -1 on error. + */ +int +virDomainRevertToSnapshot(virDomainSnapshotPtr snapshot, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("snapshot=%p, flags=%x", snapshot, flags); + + virResetLastError(); + + virCheckDomainSnapshotReturn(snapshot, -1); + conn = snapshot->domain->conn; + + virCheckReadOnlyGoto(conn->flags, error); + + if ((flags & VIR_DOMAIN_SNAPSHOT_REVERT_RUNNING) && + (flags & VIR_DOMAIN_SNAPSHOT_REVERT_PAUSED)) { + virReportInvalidArg(flags, + _("running and paused flags in %s are mutually " + "exclusive"), + __FUNCTION__); + goto error; + } + + if (conn->driver->domainRevertToSnapshot) { + int ret = conn->driver->domainRevertToSnapshot(snapshot, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainSnapshotDelete: + * @snapshot: a domain snapshot object + * @flags: bitwise-OR of supported virDomainSnapshotDeleteFlags + * + * Delete the snapshot. + * + * If @flags is 0, then just this snapshot is deleted, and changes + * from this snapshot are automatically merged into children + * snapshots. If @flags includes VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN, + * then this snapshot and any descendant snapshots are deleted. If + * @flags includes VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN_ONLY, then any + * descendant snapshots are deleted, but this snapshot remains. These + * two flags are mutually exclusive. + * + * If @flags includes VIR_DOMAIN_SNAPSHOT_DELETE_METADATA_ONLY, then + * any snapshot metadata tracked by libvirt is removed while keeping + * the snapshot contents intact; if a hypervisor does not require any + * libvirt metadata to track snapshots, then this flag is silently + * ignored. + * + * Returns 0 if the selected snapshot(s) were successfully deleted, + * -1 on error. + */ +int +virDomainSnapshotDelete(virDomainSnapshotPtr snapshot, + unsigned int flags) +{ + virConnectPtr conn; + + VIR_DEBUG("snapshot=%p, flags=%x", snapshot, flags); + + virResetLastError(); + + virCheckDomainSnapshotReturn(snapshot, -1); + conn = snapshot->domain->conn; + + virCheckReadOnlyGoto(conn->flags, error); + + if ((flags & VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN) && + (flags & VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN_ONLY)) { + virReportInvalidArg(flags, + _("children and children_only flags in %s are " + "mutually exclusive"), + __FUNCTION__); + goto error; + } + + if (conn->driver->domainSnapshotDelete) { + int ret = conn->driver->domainSnapshotDelete(snapshot, flags); + if (ret < 0) + goto error; + return ret; + } + + virReportUnsupportedError(); + error: + virDispatchError(conn); + return -1; +} + + +/** + * virDomainSnapshotRef: + * @snapshot: the snapshot to hold a reference on + * + * Increment the reference count on the snapshot. For each + * additional call to this method, there shall be a corresponding + * call to virDomainSnapshotFree 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 snapshot. ie, each new thread using a snapshot would + * increment the reference count. + * + * Returns 0 in case of success and -1 in case of failure. + */ +int +virDomainSnapshotRef(virDomainSnapshotPtr snapshot) +{ + VIR_DEBUG("snapshot=%p, refs=%d", snapshot, + snapshot ? snapshot->object.u.s.refs : 0); + + virResetLastError(); + + virCheckDomainSnapshotReturn(snapshot, -1); + + virObjectRef(snapshot); + return 0; +} + + +/** + * virDomainSnapshotFree: + * @snapshot: a domain snapshot object + * + * Free the domain snapshot object. The snapshot 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 +virDomainSnapshotFree(virDomainSnapshotPtr snapshot) +{ + VIR_DEBUG("snapshot=%p", snapshot); + + virResetLastError(); + + virCheckDomainSnapshotReturn(snapshot, -1); + + virObjectUnref(snapshot); + return 0; +} diff --git a/src/libvirt.c b/src/libvirt.c index c6af39d..f02f0d9 100644 --- a/src/libvirt.c +++ b/src/libvirt.c @@ -18269,1200 +18269,6 @@ virDomainManagedSaveRemove(virDomainPtr dom, unsigned int flags) } -/** - * virDomainSnapshotGetName: - * @snapshot: a snapshot object - * - * Get the public name for that snapshot - * - * Returns a pointer to the name or NULL, the string need not be deallocated - * as its lifetime will be the same as the snapshot object. - */ -const char * -virDomainSnapshotGetName(virDomainSnapshotPtr snapshot) -{ - VIR_DEBUG("snapshot=%p", snapshot); - - virResetLastError(); - - virCheckDomainSnapshotReturn(snapshot, NULL); - - return snapshot->name; -} - - -/** - * virDomainSnapshotGetDomain: - * @snapshot: a snapshot object - * - * Provides the domain pointer associated with a snapshot. The - * reference counter on the domain is not increased by this - * call. - * - * WARNING: When writing libvirt bindings in other languages, do not use this - * function. Instead, store the domain and the snapshot object together. - * - * Returns the domain or NULL. - */ -virDomainPtr -virDomainSnapshotGetDomain(virDomainSnapshotPtr snapshot) -{ - VIR_DEBUG("snapshot=%p", snapshot); - - virResetLastError(); - - virCheckDomainSnapshotReturn(snapshot, NULL); - - return snapshot->domain; -} - - -/** - * virDomainSnapshotGetConnect: - * @snapshot: a snapshot object - * - * Provides the connection pointer associated with a snapshot. The - * reference counter on the connection is not increased by this - * call. - * - * WARNING: When writing libvirt bindings in other languages, do not use this - * function. Instead, store the connection and the snapshot object together. - * - * Returns the connection or NULL. - */ -virConnectPtr -virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot) -{ - VIR_DEBUG("snapshot=%p", snapshot); - - virResetLastError(); - - virCheckDomainSnapshotReturn(snapshot, NULL); - - return snapshot->domain->conn; -} - - -/** - * virDomainSnapshotCreateXML: - * @domain: a domain object - * @xmlDesc: string containing an XML description of the domain - * @flags: bitwise-OR of virDomainSnapshotCreateFlags - * - * Creates a new snapshot of a domain based on the snapshot xml - * contained in xmlDesc. - * - * If @flags is 0, the domain can be active, in which case the - * snapshot will be a system checkpoint (both disk state and runtime - * VM state such as RAM contents), where reverting to the snapshot is - * the same as resuming from hibernation (TCP connections may have - * timed out, but everything else picks up where it left off); or - * the domain can be inactive, in which case the snapshot includes - * just the disk state prior to booting. The newly created snapshot - * becomes current (see virDomainSnapshotCurrent()), and is a child - * of any previous current snapshot. - * - * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE, then this - * is a request to reinstate snapshot metadata that was previously - * discarded, rather than creating a new snapshot. This can be used - * to recreate a snapshot hierarchy on a destination, then remove it - * on the source, in order to allow migration (since migration - * normally fails if snapshot metadata still remains on the source - * machine). When redefining snapshot metadata, the current snapshot - * will not be altered unless the VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT - * flag is also present. It is an error to request the - * VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT flag without - * VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE. On some hypervisors, - * redefining an existing snapshot can be used to alter host-specific - * portions of the domain XML to be used during revert (such as - * backing filenames associated with disk devices), but must not alter - * guest-visible layout. When redefining a snapshot name that does - * not exist, the hypervisor may validate that reverting to the - * snapshot appears to be possible (for example, disk images have - * snapshot contents by the requested name). Not all hypervisors - * support these flags. - * - * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_NO_METADATA, then the - * domain's disk images are modified according to @xmlDesc, but then - * the just-created snapshot has its metadata deleted. This flag is - * incompatible with VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE. - * - * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_HALT, then the domain - * will be inactive after the snapshot completes, regardless of whether - * it was active before; otherwise, a running domain will still be - * running after the snapshot. This flag is invalid on transient domains, - * and is incompatible with VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE. - * - * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_LIVE, then the domain - * is not paused while creating the snapshot. This increases the size - * of the memory dump file, but reduces downtime of the guest while - * taking the snapshot. Some hypervisors only support this flag during - * external checkpoints. - * - * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY, then the - * snapshot will be limited to the disks described in @xmlDesc, and no - * VM state will be saved. For an active guest, the disk image may be - * inconsistent (as if power had been pulled), and specifying this - * with the VIR_DOMAIN_SNAPSHOT_CREATE_HALT flag risks data loss. - * - * If @flags includes VIR_DOMAIN_SNAPSHOT_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. Moreover, this flag requires - * VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY to be passed as well. - * - * By default, if the snapshot involves external files, and any of the - * destination files already exist as a non-empty regular file, the - * snapshot is rejected to avoid losing contents of those files. - * However, if @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_REUSE_EXT, - * then the destination files must be pre-created manually with - * the correct image format and metadata including backing store path - * (this allows a management app to pre-create files with relative backing - * file names, rather than the default of creating with absolute backing - * file names). Note that setting incorrect metadata in the pre-created - * image may lead to the VM being unable to start. - * - * Be aware that although libvirt prefers to report errors up front with - * no other effect, some hypervisors have certain types of failures where - * the overall command can easily fail even though the guest configuration - * was partially altered (for example, if a disk snapshot request for two - * disks fails on the second disk, but the first disk alteration cannot be - * rolled back). If this API call fails, it is therefore normally - * necessary to follow up with virDomainGetXMLDesc() and check each disk - * to determine if any partial changes occurred. However, if @flags - * contains VIR_DOMAIN_SNAPSHOT_CREATE_ATOMIC, then libvirt guarantees - * that this command will not alter any disks unless the entire set of - * changes can be done atomically, making failure recovery simpler (note - * that it is still possible to fail after disks have changed, but only - * in the much rarer cases of running out of memory or disk space). - * - * Some hypervisors may prevent this operation if there is a current - * block copy operation; in that case, use virDomainBlockJobAbort() - * to stop the block copy first. - * - * virDomainSnapshotFree should be used to free the resources after the - * snapshot object is no longer needed. - * - * Returns an (opaque) virDomainSnapshotPtr on success, NULL on failure. - */ -virDomainSnapshotPtr -virDomainSnapshotCreateXML(virDomainPtr domain, - const char *xmlDesc, - unsigned int flags) -{ - virConnectPtr conn; - - VIR_DOMAIN_DEBUG(domain, "xmlDesc=%s, flags=%x", xmlDesc, flags); - - virResetLastError(); - - virCheckDomainReturn(domain, NULL); - conn = domain->conn; - - virCheckNonNullArgGoto(xmlDesc, error); - virCheckReadOnlyGoto(conn->flags, error); - - if ((flags & VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT) && - !(flags & VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE)) { - virReportInvalidArg(flags, - _("use of 'current' flag in %s requires " - "'redefine' flag"), - __FUNCTION__); - goto error; - } - if ((flags & VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE) && - (flags & VIR_DOMAIN_SNAPSHOT_CREATE_NO_METADATA)) { - virReportInvalidArg(flags, - _("'redefine' and 'no metadata' flags in %s are " - "mutually exclusive"), - __FUNCTION__); - goto error; - } - if ((flags & VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE) && - (flags & VIR_DOMAIN_SNAPSHOT_CREATE_HALT)) { - virReportInvalidArg(flags, - _("'redefine' and 'halt' flags in %s are mutually " - "exclusive"), - __FUNCTION__); - goto error; - } - - if (conn->driver->domainSnapshotCreateXML) { - virDomainSnapshotPtr ret; - ret = conn->driver->domainSnapshotCreateXML(domain, xmlDesc, flags); - if (!ret) - goto error; - return ret; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return NULL; -} - - -/** - * virDomainSnapshotGetXMLDesc: - * @snapshot: a domain snapshot object - * @flags: bitwise-OR of subset of virDomainXMLFlags - * - * Provide an XML description of the domain snapshot. - * - * No security-sensitive data will be included unless @flags contains - * VIR_DOMAIN_XML_SECURE; this flag is rejected on read-only - * connections. For this API, @flags should not contain either - * VIR_DOMAIN_XML_INACTIVE or VIR_DOMAIN_XML_UPDATE_CPU. - * - * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error. - * the caller must free() the returned value. - */ -char * -virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot, - unsigned int flags) -{ - virConnectPtr conn; - VIR_DEBUG("snapshot=%p, flags=%x", snapshot, flags); - - virResetLastError(); - - virCheckDomainSnapshotReturn(snapshot, NULL); - conn = snapshot->domain->conn; - - if ((conn->flags & VIR_CONNECT_RO) && (flags & VIR_DOMAIN_XML_SECURE)) { - virReportError(VIR_ERR_OPERATION_DENIED, "%s", - _("virDomainSnapshotGetXMLDesc with secure flag")); - goto error; - } - - if (conn->driver->domainSnapshotGetXMLDesc) { - char *ret; - ret = conn->driver->domainSnapshotGetXMLDesc(snapshot, flags); - if (!ret) - goto error; - return ret; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return NULL; -} - - -/** - * virDomainSnapshotNum: - * @domain: a domain object - * @flags: bitwise-OR of supported virDomainSnapshotListFlags - * - * Provides the number of domain snapshots for this domain. - * - * By default, this command covers all snapshots; it is also possible to - * limit things to just snapshots with no parents, when @flags includes - * VIR_DOMAIN_SNAPSHOT_LIST_ROOTS. Additional filters are provided in - * groups, where each group contains bits that describe mutually exclusive - * attributes of a snapshot, and where all bits within a group describe - * all possible snapshots. Some hypervisors might reject explicit bits - * from a group where the hypervisor cannot make a distinction. For a - * group supported by a given hypervisor, the behavior when no bits of a - * group are set is identical to the behavior when all bits in that group - * are set. When setting bits from more than one group, it is possible to - * select an impossible combination, in that case a hypervisor may return - * either 0 or an error. - * - * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and - * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that - * have no further children (a leaf snapshot). - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and - * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on - * whether they have metadata that would prevent the removal of the last - * reference to a domain. - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE, - * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY, - * for filtering snapshots based on what domain state is tracked by the - * snapshot. - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and - * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on - * whether the snapshot is stored inside the disk images or as - * additional files. - * - * Returns the number of domain snapshots found or -1 in case of error. - */ -int -virDomainSnapshotNum(virDomainPtr domain, unsigned int flags) -{ - virConnectPtr conn; - - VIR_DOMAIN_DEBUG(domain, "flags=%x", flags); - - virResetLastError(); - - virCheckDomainReturn(domain, -1); - - conn = domain->conn; - if (conn->driver->domainSnapshotNum) { - int ret = conn->driver->domainSnapshotNum(domain, flags); - if (ret < 0) - goto error; - return ret; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return -1; -} - - -/** - * virDomainSnapshotListNames: - * @domain: a domain object - * @names: array to collect the list of names of snapshots - * @nameslen: size of @names - * @flags: bitwise-OR of supported virDomainSnapshotListFlags - * - * Collect the list of domain snapshots for the given domain, and store - * their names in @names. The value to use for @nameslen can be determined - * by virDomainSnapshotNum() with the same @flags. - * - * By default, this command covers all snapshots; it is also possible to - * limit things to just snapshots with no parents, when @flags includes - * VIR_DOMAIN_SNAPSHOT_LIST_ROOTS. Additional filters are provided in - * groups, where each group contains bits that describe mutually exclusive - * attributes of a snapshot, and where all bits within a group describe - * all possible snapshots. Some hypervisors might reject explicit bits - * from a group where the hypervisor cannot make a distinction. For a - * group supported by a given hypervisor, the behavior when no bits of a - * group are set is identical to the behavior when all bits in that group - * are set. When setting bits from more than one group, it is possible to - * select an impossible combination, in that case a hypervisor may return - * either 0 or an error. - * - * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and - * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that - * have no further children (a leaf snapshot). - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and - * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on - * whether they have metadata that would prevent the removal of the last - * reference to a domain. - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE, - * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY, - * for filtering snapshots based on what domain state is tracked by the - * snapshot. - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and - * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on - * whether the snapshot is stored inside the disk images or as - * additional files. - * - * Note that this command is inherently racy: another connection can - * define a new snapshot between a call to virDomainSnapshotNum() and - * this call. You are only guaranteed that all currently defined - * snapshots were listed if the return is less than @nameslen. Likewise, - * you should be prepared for virDomainSnapshotLookupByName() to fail when - * converting a name from this call into a snapshot object, if another - * connection deletes the snapshot in the meantime. For more control over - * the results, see virDomainListAllSnapshots(). - * - * Returns the number of domain snapshots found or -1 in case of error. - * The caller is responsible to call free() for each member of the array. - */ -int -virDomainSnapshotListNames(virDomainPtr domain, char **names, int nameslen, - unsigned int flags) -{ - virConnectPtr conn; - - VIR_DOMAIN_DEBUG(domain, "names=%p, nameslen=%d, flags=%x", - names, nameslen, flags); - - virResetLastError(); - - virCheckDomainReturn(domain, -1); - conn = domain->conn; - - virCheckNonNullArgGoto(names, error); - virCheckNonNegativeArgGoto(nameslen, error); - - if (conn->driver->domainSnapshotListNames) { - int ret = conn->driver->domainSnapshotListNames(domain, names, - nameslen, flags); - if (ret < 0) - goto error; - return ret; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return -1; -} - - -/** - * virDomainListAllSnapshots: - * @domain: a domain object - * @snaps: pointer to variable to store the array containing snapshot objects, - * or NULL if the list is not required (just returns number of - * snapshots) - * @flags: bitwise-OR of supported virDomainSnapshotListFlags - * - * Collect the list of domain snapshots for the given domain, and allocate - * an array to store those objects. This API solves the race inherent in - * virDomainSnapshotListNames(). - * - * By default, this command covers all snapshots; it is also possible to - * limit things to just snapshots with no parents, when @flags includes - * VIR_DOMAIN_SNAPSHOT_LIST_ROOTS. Additional filters are provided in - * groups, where each group contains bits that describe mutually exclusive - * attributes of a snapshot, and where all bits within a group describe - * all possible snapshots. Some hypervisors might reject explicit bits - * from a group where the hypervisor cannot make a distinction. For a - * group supported by a given hypervisor, the behavior when no bits of a - * group are set is identical to the behavior when all bits in that group - * are set. When setting bits from more than one group, it is possible to - * select an impossible combination, in that case a hypervisor may return - * either 0 or an error. - * - * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and - * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that - * have no further children (a leaf snapshot). - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and - * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on - * whether they have metadata that would prevent the removal of the last - * reference to a domain. - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE, - * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY, - * for filtering snapshots based on what domain state is tracked by the - * snapshot. - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and - * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on - * whether the snapshot is stored inside the disk images or as - * additional files. - * - * Returns the number of domain snapshots found or -1 and sets @snaps to - * NULL in case of error. On success, the array stored into @snaps 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 virDomainSnapshotFree() on each array element, then calling - * free() on @snaps. - */ -int -virDomainListAllSnapshots(virDomainPtr domain, virDomainSnapshotPtr **snaps, - unsigned int flags) -{ - virConnectPtr conn; - - VIR_DOMAIN_DEBUG(domain, "snaps=%p, flags=%x", snaps, flags); - - virResetLastError(); - - if (snaps) - *snaps = NULL; - - virCheckDomainReturn(domain, -1); - conn = domain->conn; - - if (conn->driver->domainListAllSnapshots) { - int ret = conn->driver->domainListAllSnapshots(domain, snaps, flags); - if (ret < 0) - goto error; - return ret; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return -1; -} - - -/** - * virDomainSnapshotNumChildren: - * @snapshot: a domain snapshot object - * @flags: bitwise-OR of supported virDomainSnapshotListFlags - * - * Provides the number of child snapshots for this domain snapshot. - * - * By default, this command covers only direct children; it is also possible - * to expand things to cover all descendants, when @flags includes - * VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Also, some filters are provided in - * groups, where each group contains bits that describe mutually exclusive - * attributes of a snapshot, and where all bits within a group describe - * all possible snapshots. Some hypervisors might reject explicit bits - * from a group where the hypervisor cannot make a distinction. For a - * group supported by a given hypervisor, the behavior when no bits of a - * group are set is identical to the behavior when all bits in that group - * are set. When setting bits from more than one group, it is possible to - * select an impossible combination, in that case a hypervisor may return - * either 0 or an error. - * - * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and - * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that - * have no further children (a leaf snapshot). - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and - * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on - * whether they have metadata that would prevent the removal of the last - * reference to a domain. - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE, - * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY, - * for filtering snapshots based on what domain state is tracked by the - * snapshot. - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and - * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on - * whether the snapshot is stored inside the disk images or as - * additional files. - * - * Returns the number of domain snapshots found or -1 in case of error. - */ -int -virDomainSnapshotNumChildren(virDomainSnapshotPtr snapshot, unsigned int flags) -{ - virConnectPtr conn; - - VIR_DEBUG("snapshot=%p, flags=%x", snapshot, flags); - - virResetLastError(); - - virCheckDomainSnapshotReturn(snapshot, -1); - conn = snapshot->domain->conn; - - if (conn->driver->domainSnapshotNumChildren) { - int ret = conn->driver->domainSnapshotNumChildren(snapshot, flags); - if (ret < 0) - goto error; - return ret; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return -1; -} - - -/** - * virDomainSnapshotListChildrenNames: - * @snapshot: a domain snapshot object - * @names: array to collect the list of names of snapshots - * @nameslen: size of @names - * @flags: bitwise-OR of supported virDomainSnapshotListFlags - * - * Collect the list of domain snapshots that are children of the given - * snapshot, and store their names in @names. The value to use for - * @nameslen can be determined by virDomainSnapshotNumChildren() with - * the same @flags. - * - * By default, this command covers only direct children; it is also possible - * to expand things to cover all descendants, when @flags includes - * VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Also, some filters are provided in - * groups, where each group contains bits that describe mutually exclusive - * attributes of a snapshot, and where all bits within a group describe - * all possible snapshots. Some hypervisors might reject explicit bits - * from a group where the hypervisor cannot make a distinction. For a - * group supported by a given hypervisor, the behavior when no bits of a - * group are set is identical to the behavior when all bits in that group - * are set. When setting bits from more than one group, it is possible to - * select an impossible combination, in that case a hypervisor may return - * either 0 or an error. - * - * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and - * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that - * have no further children (a leaf snapshot). - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and - * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on - * whether they have metadata that would prevent the removal of the last - * reference to a domain. - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE, - * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY, - * for filtering snapshots based on what domain state is tracked by the - * snapshot. - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and - * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on - * whether the snapshot is stored inside the disk images or as - * additional files. - * - * Returns the number of domain snapshots found or -1 in case of error. - * Note that this command is inherently racy: another connection can - * define a new snapshot between a call to virDomainSnapshotNumChildren() - * and this call. You are only guaranteed that all currently defined - * snapshots were listed if the return is less than @nameslen. Likewise, - * you should be prepared for virDomainSnapshotLookupByName() to fail when - * converting a name from this call into a snapshot object, if another - * connection deletes the snapshot in the meantime. For more control over - * the results, see virDomainSnapshotListAllChildren(). - * - * Returns the number of domain snapshots found or -1 in case of error. - * The caller is responsible to call free() for each member of the array. - */ -int -virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot, - char **names, int nameslen, - unsigned int flags) -{ - virConnectPtr conn; - - VIR_DEBUG("snapshot=%p, names=%p, nameslen=%d, flags=%x", - snapshot, names, nameslen, flags); - - virResetLastError(); - - virCheckDomainSnapshotReturn(snapshot, -1); - conn = snapshot->domain->conn; - - virCheckNonNullArgGoto(names, error); - virCheckNonNegativeArgGoto(nameslen, error); - - if (conn->driver->domainSnapshotListChildrenNames) { - int ret = conn->driver->domainSnapshotListChildrenNames(snapshot, - names, - nameslen, - flags); - if (ret < 0) - goto error; - return ret; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return -1; -} - - -/** - * virDomainSnapshotListAllChildren: - * @snapshot: a domain snapshot object - * @snaps: pointer to variable to store the array containing snapshot objects, - * or NULL if the list is not required (just returns number of - * snapshots) - * @flags: bitwise-OR of supported virDomainSnapshotListFlags - * - * Collect the list of domain snapshots that are children of the given - * snapshot, and allocate an array to store those objects. This API solves - * the race inherent in virDomainSnapshotListChildrenNames(). - * - * By default, this command covers only direct children; it is also possible - * to expand things to cover all descendants, when @flags includes - * VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Also, some filters are provided in - * groups, where each group contains bits that describe mutually exclusive - * attributes of a snapshot, and where all bits within a group describe - * all possible snapshots. Some hypervisors might reject explicit bits - * from a group where the hypervisor cannot make a distinction. For a - * group supported by a given hypervisor, the behavior when no bits of a - * group are set is identical to the behavior when all bits in that group - * are set. When setting bits from more than one group, it is possible to - * select an impossible combination, in that case a hypervisor may return - * either 0 or an error. - * - * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and - * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that - * have no further children (a leaf snapshot). - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and - * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on - * whether they have metadata that would prevent the removal of the last - * reference to a domain. - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE, - * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY, - * for filtering snapshots based on what domain state is tracked by the - * snapshot. - * - * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and - * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on - * whether the snapshot is stored inside the disk images or as - * additional files. - * - * Returns the number of domain snapshots found or -1 and sets @snaps to - * NULL in case of error. On success, the array stored into @snaps 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 virDomainSnapshotFree() on each array element, then calling - * free() on @snaps. - */ -int -virDomainSnapshotListAllChildren(virDomainSnapshotPtr snapshot, - virDomainSnapshotPtr **snaps, - unsigned int flags) -{ - virConnectPtr conn; - - VIR_DEBUG("snapshot=%p, snaps=%p, flags=%x", snapshot, snaps, flags); - - virResetLastError(); - - if (snaps) - *snaps = NULL; - - virCheckDomainSnapshotReturn(snapshot, -1); - conn = snapshot->domain->conn; - - if (conn->driver->domainSnapshotListAllChildren) { - int ret = conn->driver->domainSnapshotListAllChildren(snapshot, snaps, - flags); - if (ret < 0) - goto error; - return ret; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return -1; -} - - -/** - * virDomainSnapshotLookupByName: - * @domain: a domain object - * @name: name for the domain snapshot - * @flags: extra flags; not used yet, so callers should always pass 0 - * - * Try to lookup a domain snapshot based on its name. - * - * Returns a domain snapshot object or NULL in case of failure. If the - * domain snapshot cannot be found, then the VIR_ERR_NO_DOMAIN_SNAPSHOT - * error is raised. - */ -virDomainSnapshotPtr -virDomainSnapshotLookupByName(virDomainPtr domain, - const char *name, - unsigned int flags) -{ - virConnectPtr conn; - - VIR_DOMAIN_DEBUG(domain, "name=%s, flags=%x", name, flags); - - virResetLastError(); - - virCheckDomainReturn(domain, NULL); - conn = domain->conn; - - virCheckNonNullArgGoto(name, error); - - if (conn->driver->domainSnapshotLookupByName) { - virDomainSnapshotPtr dom; - dom = conn->driver->domainSnapshotLookupByName(domain, name, flags); - if (!dom) - goto error; - return dom; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return NULL; -} - - -/** - * virDomainHasCurrentSnapshot: - * @domain: pointer to the domain object - * @flags: extra flags; not used yet, so callers should always pass 0 - * - * Determine if the domain has a current snapshot. - * - * Returns 1 if such snapshot exists, 0 if it doesn't, -1 on error. - */ -int -virDomainHasCurrentSnapshot(virDomainPtr domain, unsigned int flags) -{ - virConnectPtr conn; - - VIR_DOMAIN_DEBUG(domain, "flags=%x", flags); - - virResetLastError(); - - virCheckDomainReturn(domain, -1); - conn = domain->conn; - - if (conn->driver->domainHasCurrentSnapshot) { - int ret = conn->driver->domainHasCurrentSnapshot(domain, flags); - if (ret < 0) - goto error; - return ret; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return -1; -} - - -/** - * virDomainSnapshotCurrent: - * @domain: a domain object - * @flags: extra flags; not used yet, so callers should always pass 0 - * - * Get the current snapshot for a domain, if any. - * - * virDomainSnapshotFree should be used to free the resources after the - * snapshot object is no longer needed. - * - * Returns a domain snapshot object or NULL in case of failure. If the - * current domain snapshot cannot be found, then the VIR_ERR_NO_DOMAIN_SNAPSHOT - * error is raised. - */ -virDomainSnapshotPtr -virDomainSnapshotCurrent(virDomainPtr domain, - unsigned int flags) -{ - virConnectPtr conn; - - VIR_DOMAIN_DEBUG(domain, "flags=%x", flags); - - virResetLastError(); - - virCheckDomainReturn(domain, NULL); - conn = domain->conn; - - if (conn->driver->domainSnapshotCurrent) { - virDomainSnapshotPtr snap; - snap = conn->driver->domainSnapshotCurrent(domain, flags); - if (!snap) - goto error; - return snap; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return NULL; -} - - -/** - * virDomainSnapshotGetParent: - * @snapshot: a snapshot object - * @flags: extra flags; not used yet, so callers should always pass 0 - * - * Get the parent snapshot for @snapshot, if any. - * - * virDomainSnapshotFree should be used to free the resources after the - * snapshot object is no longer needed. - * - * Returns a domain snapshot object or NULL in case of failure. If the - * given snapshot is a root (no parent), then the VIR_ERR_NO_DOMAIN_SNAPSHOT - * error is raised. - */ -virDomainSnapshotPtr -virDomainSnapshotGetParent(virDomainSnapshotPtr snapshot, - unsigned int flags) -{ - virConnectPtr conn; - - VIR_DEBUG("snapshot=%p, flags=%x", snapshot, flags); - - virResetLastError(); - - virCheckDomainSnapshotReturn(snapshot, NULL); - conn = snapshot->domain->conn; - - if (conn->driver->domainSnapshotGetParent) { - virDomainSnapshotPtr snap; - snap = conn->driver->domainSnapshotGetParent(snapshot, flags); - if (!snap) - goto error; - return snap; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return NULL; -} - - -/** - * virDomainSnapshotIsCurrent: - * @snapshot: a snapshot object - * @flags: extra flags; not used yet, so callers should always pass 0 - * - * Determine if the given snapshot is the domain's current snapshot. See - * also virDomainHasCurrentSnapshot(). - * - * Returns 1 if current, 0 if not current, or -1 on error. - */ -int -virDomainSnapshotIsCurrent(virDomainSnapshotPtr snapshot, - unsigned int flags) -{ - virConnectPtr conn; - - VIR_DEBUG("snapshot=%p, flags=%x", snapshot, flags); - - virResetLastError(); - - virCheckDomainSnapshotReturn(snapshot, -1); - conn = snapshot->domain->conn; - - if (conn->driver->domainSnapshotIsCurrent) { - int ret; - ret = conn->driver->domainSnapshotIsCurrent(snapshot, flags); - if (ret < 0) - goto error; - return ret; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return -1; -} - - -/** - * virDomainSnapshotHasMetadata: - * @snapshot: a snapshot object - * @flags: extra flags; not used yet, so callers should always pass 0 - * - * Determine if the given snapshot is associated with libvirt metadata - * that would prevent the deletion of the domain. - * - * Returns 1 if the snapshot has metadata, 0 if the snapshot exists without - * help from libvirt, or -1 on error. - */ -int -virDomainSnapshotHasMetadata(virDomainSnapshotPtr snapshot, - unsigned int flags) -{ - virConnectPtr conn; - - VIR_DEBUG("snapshot=%p, flags=%x", snapshot, flags); - - virResetLastError(); - - virCheckDomainSnapshotReturn(snapshot, -1); - conn = snapshot->domain->conn; - - if (conn->driver->domainSnapshotHasMetadata) { - int ret; - ret = conn->driver->domainSnapshotHasMetadata(snapshot, flags); - if (ret < 0) - goto error; - return ret; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return -1; -} - - -/** - * virDomainRevertToSnapshot: - * @snapshot: a domain snapshot object - * @flags: bitwise-OR of virDomainSnapshotRevertFlags - * - * Revert the domain to a given snapshot. - * - * Normally, the domain will revert to the same state the domain was - * in while the snapshot was taken (whether inactive, running, or - * paused), except that disk snapshots default to reverting to - * inactive state. Including VIR_DOMAIN_SNAPSHOT_REVERT_RUNNING in - * @flags overrides the snapshot state to guarantee a running domain - * after the revert; or including VIR_DOMAIN_SNAPSHOT_REVERT_PAUSED in - * @flags guarantees a paused domain after the revert. These two - * flags are mutually exclusive. While a persistent domain does not - * need either flag, it is not possible to revert a transient domain - * into an inactive state, so transient domains require the use of one - * of these two flags. - * - * Reverting to any snapshot discards all configuration changes made since - * the last snapshot. Additionally, reverting to a snapshot from a running - * domain is a form of data loss, since it discards whatever is in the - * guest's RAM at the time. Since the very nature of keeping snapshots - * implies the intent to roll back state, no additional confirmation is - * normally required for these lossy effects. - * - * However, there are two particular situations where reverting will - * be refused by default, and where @flags must include - * VIR_DOMAIN_SNAPSHOT_REVERT_FORCE to acknowledge the risks. 1) Any - * attempt to revert to a snapshot that lacks the metadata to perform - * ABI compatibility checks (generally the case for snapshots that - * lack a full <domain> when listed by virDomainSnapshotGetXMLDesc(), - * such as those created prior to libvirt 0.9.5). 2) Any attempt to - * revert a running domain to an active state that requires starting a - * new hypervisor instance rather than reusing the existing hypervisor - * (since this would terminate all connections to the domain, such as - * such as VNC or Spice graphics) - this condition arises from active - * snapshots that are provably ABI incomaptible, as well as from - * inactive snapshots with a @flags request to start the domain after - * the revert. - * - * Returns 0 if the creation is successful, -1 on error. - */ -int -virDomainRevertToSnapshot(virDomainSnapshotPtr snapshot, - unsigned int flags) -{ - virConnectPtr conn; - - VIR_DEBUG("snapshot=%p, flags=%x", snapshot, flags); - - virResetLastError(); - - virCheckDomainSnapshotReturn(snapshot, -1); - conn = snapshot->domain->conn; - - virCheckReadOnlyGoto(conn->flags, error); - - if ((flags & VIR_DOMAIN_SNAPSHOT_REVERT_RUNNING) && - (flags & VIR_DOMAIN_SNAPSHOT_REVERT_PAUSED)) { - virReportInvalidArg(flags, - _("running and paused flags in %s are mutually " - "exclusive"), - __FUNCTION__); - goto error; - } - - if (conn->driver->domainRevertToSnapshot) { - int ret = conn->driver->domainRevertToSnapshot(snapshot, flags); - if (ret < 0) - goto error; - return ret; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return -1; -} - - -/** - * virDomainSnapshotDelete: - * @snapshot: a domain snapshot object - * @flags: bitwise-OR of supported virDomainSnapshotDeleteFlags - * - * Delete the snapshot. - * - * If @flags is 0, then just this snapshot is deleted, and changes - * from this snapshot are automatically merged into children - * snapshots. If @flags includes VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN, - * then this snapshot and any descendant snapshots are deleted. If - * @flags includes VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN_ONLY, then any - * descendant snapshots are deleted, but this snapshot remains. These - * two flags are mutually exclusive. - * - * If @flags includes VIR_DOMAIN_SNAPSHOT_DELETE_METADATA_ONLY, then - * any snapshot metadata tracked by libvirt is removed while keeping - * the snapshot contents intact; if a hypervisor does not require any - * libvirt metadata to track snapshots, then this flag is silently - * ignored. - * - * Returns 0 if the selected snapshot(s) were successfully deleted, - * -1 on error. - */ -int -virDomainSnapshotDelete(virDomainSnapshotPtr snapshot, - unsigned int flags) -{ - virConnectPtr conn; - - VIR_DEBUG("snapshot=%p, flags=%x", snapshot, flags); - - virResetLastError(); - - virCheckDomainSnapshotReturn(snapshot, -1); - conn = snapshot->domain->conn; - - virCheckReadOnlyGoto(conn->flags, error); - - if ((flags & VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN) && - (flags & VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN_ONLY)) { - virReportInvalidArg(flags, - _("children and children_only flags in %s are " - "mutually exclusive"), - __FUNCTION__); - goto error; - } - - if (conn->driver->domainSnapshotDelete) { - int ret = conn->driver->domainSnapshotDelete(snapshot, flags); - if (ret < 0) - goto error; - return ret; - } - - virReportUnsupportedError(); - error: - virDispatchError(conn); - return -1; -} - - -/** - * virDomainSnapshotRef: - * @snapshot: the snapshot to hold a reference on - * - * Increment the reference count on the snapshot. For each - * additional call to this method, there shall be a corresponding - * call to virDomainSnapshotFree 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 snapshot. ie, each new thread using a snapshot would - * increment the reference count. - * - * Returns 0 in case of success and -1 in case of failure. - */ -int -virDomainSnapshotRef(virDomainSnapshotPtr snapshot) -{ - VIR_DEBUG("snapshot=%p, refs=%d", snapshot, - snapshot ? snapshot->object.u.s.refs : 0); - - virResetLastError(); - - virCheckDomainSnapshotReturn(snapshot, -1); - - virObjectRef(snapshot); - return 0; -} - - -/** - * virDomainSnapshotFree: - * @snapshot: a domain snapshot object - * - * Free the domain snapshot object. The snapshot 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 -virDomainSnapshotFree(virDomainSnapshotPtr snapshot) -{ - VIR_DEBUG("snapshot=%p", snapshot); - - virResetLastError(); - - virCheckDomainSnapshotReturn(snapshot, -1); - - virObjectUnref(snapshot); - return 0; -} - /** * virDomainOpenConsole: -- 2.1.0