[libvirt] [PATCH v6 3/9] snapshot: Various doc tweaks

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(a)redhat.com&gt; --- 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