[libvirt] [PATCH v6 3/9] snapshot: Various doc tweaks
Eric Blake
eblake at redhat.com
Tue Mar 26 06:13:47 UTC 2019
Since I was copying this text to form checkpoint XML and API
documentation, I might as well make improvements along the way. Most
of these changes are based on reviews of the checkpoint docs.
Among other things: grammar tweaks, point to a single source of
documentation rather than repeating verbosity, reword things for
easier legibility.
Signed-off-by: Eric Blake <eblake at redhat.com>
---
docs/formatsnapshot.html.in | 80 ++++++------
src/libvirt-domain-snapshot.c | 222 +++++++---------------------------
2 files changed, 89 insertions(+), 213 deletions(-)
diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in
index 146908ce76..1bbbf06205 100644
--- a/docs/formatsnapshot.html.in
+++ b/docs/formatsnapshot.html.in
@@ -99,16 +99,14 @@
</p>
<dl>
<dt><code>name</code></dt>
- <dd>The name for this snapshot. If the name is specified when
- initially creating the snapshot, then the snapshot will have
- that particular name. If the name is omitted when initially
- creating the snapshot, then libvirt will make up a name for
- the snapshot, based on the time when it was created.
+ <dd>The optional name for this snapshot. If the name is
+ omitted, libvirt will create a name based on the time of the
+ creation.
</dd>
<dt><code>description</code></dt>
- <dd>A human-readable description of the snapshot. If the
- description is omitted when initially creating the snapshot,
- then this field will be empty.
+ <dd>An optional human-readable description of the snapshot. If
+ the description is omitted when initially creating the
+ snapshot, then this field will be empty.
</dd>
<dt><code>memory</code></dt>
<dd>On input, this is an optional request for how to handle VM
@@ -200,46 +198,52 @@
</dl>
</dd>
<dt><code>creationTime</code></dt>
- <dd>The time this snapshot was created. The time is specified
- in seconds since the Epoch, UTC (i.e. Unix time). Readonly.
+ <dd>A readonly representation of the time this snapshot was
+ created. The time is specified in seconds since the Epoch,
+ UTC (i.e. Unix time).
</dd>
<dt><code>state</code></dt>
- <dd>The state of the domain at the time this snapshot was taken.
- If a full system snapshot was created, then this
- is the state of the domain at that time. When the domain is
- reverted to this snapshot, the domain's state will default to
- this state, unless overridden
+ <dd>A readonly representation of the state of the domain at the
+ time this snapshot was taken. If a full system snapshot was
+ created, then this is the state of the domain at that
+ time. When the domain is reverted to this snapshot, the
+ domain's state will default to this state, unless overridden
by <code>virDomainRevertToSnapshot()</code> flags to revert to
- a running or paused state. Additionally,
- this field can be the value "disk-snapshot"
- (<span class="since">since 0.9.5</span>) when it represents
- only a disk snapshot (no VM memory state), and reverting to this
- snapshot will default to an inactive guest. Readonly.
+ a running or paused state. Additionally, this field can be the
+ value "disk-snapshot" (<span class="since">since 0.9.5</span>)
+ when it represents only a disk snapshot (no VM memory state),
+ and reverting to this snapshot will default to an inactive
+ guest.
</dd>
<dt><code>parent</code></dt>
- <dd>The parent of this snapshot. If present, this element
- contains exactly one child element, name. This specifies the
- name of the parent snapshot of this snapshot, and is used to
- represent trees of snapshots. Readonly.
+ <dd>An optional readonly representation of the parent of this
+ snapshot. If present, this element contains exactly one child
+ element, <code>name</code>. This specifies the name of the
+ parent snapshot of this snapshot, and is used to represent
+ trees of snapshots.
</dd>
<dt><code>domain</code></dt>
- <dd>The domain that this snapshot was taken against. Older
- versions of libvirt stored only a single child element, uuid;
- reverting to a snapshot like this is risky if the current
- state of the domain differs from the state that the domain was
- created in, and requires the use of the
- <code>VIR_DOMAIN_SNAPSHOT_REVERT_FORCE</code> flag
+ <dd>A readonly representation of the domain that this snapshot
+ was taken against. Older versions of libvirt stored only a
+ single child element, uuid; reverting to a snapshot like this
+ is risky if the current state of the domain differs from the
+ state that the domain was created in, and requires the use of
+ the <code>VIR_DOMAIN_SNAPSHOT_REVERT_FORCE</code> flag
in <code>virDomainRevertToSnapshot()</code>. Newer versions
- of libvirt (<span class="since">since 0.9.5</span>) store the entire
- inactive <a href="formatdomain.html">domain configuration</a>
- at the time of the snapshot (<span class="since">since
- 0.9.5</span>). Readonly.
+ of libvirt (<span class="since">since 0.9.5</span>) store the
+ entire inactive <a href="formatdomain.html">domain
+ configuration</a> at the time of the snapshot
+ (<span class="since">since 0.9.5</span>). The domain will have
+ security-sensitive information omitted
+ unless the flag <code>VIR_DOMAIN_SNAPSHOT_XML_SECURE</code> is
+ provided on a read-write connection.
</dd>
<dt><code>cookie</code></dt>
- <dd>Save image cookie containing additional data libvirt may need to
- properly restore a domain from an active snapshot when such data
- cannot be stored directly in the <code>domain</code> to maintain
- compatibility with older libvirt or hypervisor. Readonly.
+ <dd>An optional readonly representation of a save image cookie
+ containing additional data libvirt may need to properly
+ restore a domain from an active snapshot when such data cannot
+ be stored directly in the <code>domain</code> to maintain
+ compatibility with older libvirt or hypervisor.
</dd>
</dl>
diff --git a/src/libvirt-domain-snapshot.c b/src/libvirt-domain-snapshot.c
index be9bf71af9..0c8023d9f6 100644
--- a/src/libvirt-domain-snapshot.c
+++ b/src/libvirt-domain-snapshot.c
@@ -142,8 +142,10 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
* 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
+ * domain's disk images are modified according to @xmlDesc, but
+ * libvirt does not track any metadata (similar to immediately calling
+ * virDomainSnapshotDelete() with
+ * VIR_DOMAIN_SNAPSHOT_DELETE_METADATA_ONLY). This flag is
* incompatible with VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE.
*
* If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_HALT, then the domain
@@ -203,7 +205,8 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
* 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.
+ * Returns an (opaque) new virDomainSnapshotPtr on success or NULL on
+ * failure.
*/
virDomainSnapshotPtr
virDomainSnapshotCreateXML(virDomainPtr domain,
@@ -260,7 +263,7 @@ virDomainSnapshotCreateXML(virDomainPtr domain,
* VIR_DOMAIN_SNAPSHOT_XML_SECURE; this flag is rejected on read-only
* connections.
*
- * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case
+ * Returns a 0 terminated UTF-8 encoded XML instance or NULL in case
* of error. The caller must free() the returned value.
*/
char *
@@ -308,37 +311,11 @@ virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot,
* @flags only if virDomainSnapshotListNames() can honor it, although
* the flag has no other effect here.
*
- * 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.
+ * 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 via the same @flags values as documented in
+ * virDomainListAllSnapshots().
*
* Returns the number of domain snapshots found or -1 in case of error.
*/
@@ -386,37 +363,11 @@ virDomainSnapshotNum(virDomainPtr domain, unsigned int flags)
* starting from that earlier snapshot; otherwise, the order of
* snapshots in the resulting list is unspecified.
*
- * 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.
+ * 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 via the same @flags values as documented in
+ * virDomainListAllSnapshots().
*
* Note that this command is inherently racy: another connection can
* define a new snapshot between a call to virDomainSnapshotNum() and
@@ -465,12 +416,12 @@ virDomainSnapshotListNames(virDomainPtr domain, char **names, int nameslen,
/**
* virDomainListAllSnapshots:
* @domain: a domain object
- * @snaps: pointer to variable to store the array containing snapshot objects,
+ * @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
+ * 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().
*
@@ -482,18 +433,15 @@ virDomainSnapshotListNames(virDomainPtr domain, char **names, int nameslen,
* otherwise, the order of snapshots in the resulting list is
* unspecified.
*
- * 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.
+ * 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 listed below. Within a group, bits are mutually
+ * exclusive, where all possible snapshots 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_SNAPSHOT_LIST_LEAVES and
* VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that
@@ -562,37 +510,11 @@ virDomainListAllSnapshots(virDomainPtr domain, virDomainSnapshotPtr **snaps,
* @flags only if virDomainSnapshotListChildrenNames() can honor it,
* although the flag has no other effect here.
*
- * 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.
+ * 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. Additional filters
+ * are provided via the same @flags values as documented in
+ * virDomainSnapshotListAllChildren().
*
* Returns the number of domain snapshots found or -1 in case of error.
*/
@@ -642,39 +564,12 @@ virDomainSnapshotNumChildren(virDomainSnapshotPtr snapshot, unsigned int flags)
* earlier snapshot; otherwise, the order of snapshots 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_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.
+ * 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. Additional filters
+ * are provided via the same @flags values as documented in
+ * virDomainSnapshotListAllChildren().
*
- * 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
@@ -725,7 +620,7 @@ virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot,
/**
* virDomainSnapshotListAllChildren:
* @snapshot: a domain snapshot object
- * @snaps: pointer to variable to store the array containing snapshot objects,
+ * @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
@@ -742,37 +637,14 @@ virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot,
* starting from that earlier snapshot; otherwise, the order of
* snapshots 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_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.
+ * 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. Additional filters
+ * are provided via the remaining @flags values as documented in
+ * virDomainListAllSnapshots(), with the exception that
+ * VIR_DOMAIN_SNAPSHOT_LIST_ROOTS is not supported (in fact,
+ * VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS has the same bit value but
+ * opposite semantics of widening rather than narrowing the listing).
*
* 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
--
2.20.1
More information about the libvir-list
mailing list