It doesn't need to fail the test if a reentrant function is found in a comment. Fixes: | ... | prohibit_nonreentrant | libvirt/ci/helper:33: default=os.getlogin(), # exempt from syntax-check | libvirt/include/libvirt/libvirt-storage.h:223: VIR_STORAGE_VOL_WIPE_ALG_PFITZNER7 = 6, /* 7-pass random (Since: v1.0.0) */ | libvirt/include/libvirt/libvirt-storage.h:225: VIR_STORAGE_VOL_WIPE_ALG_PFITZNER33 = 7, /* 33-pass random (Since: v1.0.0) */ | libvirt/include/libvirt/libvirt-storage.h:227: VIR_STORAGE_VOL_WIPE_ALG_RANDOM = 8, /* 1-pass random (Since: v1.0.0) */ Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- build-aux/syntax-check.mk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build-aux/syntax-check.mk b/build-aux/syntax-check.mk index a6e3ada300..eb403f3d3f 100644 --- a/build-aux/syntax-check.mk +++ b/build-aux/syntax-check.mk @@ -300,7 +300,7 @@ sc_prohibit_PATH_MAX: include $(top_srcdir)/build-aux/Makefile.nonreentrant sc_prohibit_nonreentrant: @prohibit="\\<(${NON_REENTRANT_RE}) *\\(" \ - exclude='exempt from syntax-check' \ + exclude='exempt from syntax-check|\/\*.*\*\/' \ halt="use re-entrant functions (usually ending with _r)" \ $(_sc_search_regexp) -- 2.35.1

On Thu, Apr 21, 2022 at 02:11:03PM +0200, Peter Krempa wrote: Yeah. Sure. Thanks, Victor

On Wed, Apr 20, 2022 at 21:07:51 +0200, Victor Toso wrote: This patch should not be needed once we will not need to have an override for 'virDomainFree'. IMO a better solution would be to exclude python files from the check.

scripts/apibuild.py does not handle well enum's with comments between values. The outcome depends on whether the enum value has its own docstring or not and if there is spaces between the enum values or not. Either way, virConnectListAllNodeDeviceFlags documentation is explicit that this enum is about filtering node devices. We can move the information that it is either by "capability" or "active" state to the block of comment above. Using git diff --word-diff to show the fixed ouput xml (redacted). <enum name='VIR_CONNECT_LIST_NODE_DEVICES_ACTIVE' ... [-info='Inactive-]{+info='Active+} devices'/> <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_AP_CARD' ... [-info='vDPA-]{+info='s390 AP Card+} device'/> <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_AP_MATRIX' ... [-Queue'/>-]{+Matrix'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_AP_QUEUE' ... [-Card device'/>-]{+Queue'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_CCW_DEV' ... [-info='Mediated-]{+info='CCW+} device'/> <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_CSS_DEV' ... [-info='CCW-]{+info='CSS+} device'/> <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_DRM' ... [-info='Capable of scsi_generic'/>-]{+info='DRM device'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_FC_HOST' ... [-info='Storage device'/>-]{+info='FC Host Bus Adapter'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_MDEV' ... [-info='Capable of mediated devices'/>-]{+info='Mediated device'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_MDEV_TYPES' ... [-info='DRM device'/>-]{+info='Capable of mediated devices'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_NET' ... [-info='USB interface'/>-]{+info='Network device'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_PCI_DEV' ... [-info='System capability'/>-]{+info='PCI device'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI' ... [-Target'/>-]{+device'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_GENERIC' ... [-vport'/>-]{+scsi_generic'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_HOST' ... [-info='Network device'/>-]{+info='SCSI Host Bus Adapter'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_TARGET' ... [-Host Bus Adapter'/>-]{+Target'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_STORAGE' ... [-info='SCSI-]{+info='Storage+} device'/> <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_SYSTEM' ... [-info='filter the devices by cap type'/>-]{+info='System capability'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_USB_DEV' ... [-info='PCI-]{+info='USB+} device'/> <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_USB_INTERFACE' ... [-device'/>-]{+interface'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_VDPA' ... [-info='CSS-]{+info='vDPA+} device'/> <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_VPD' ... [-info='s390 AP Matrix'/>-]{+info='Device with VPD'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_VPORTS' ... [-info='FC Host Bus Adapter'/>-]{+info='Capable of vport'/>+} <enum name='VIR_CONNECT_LIST_NODE_DEVICES_INACTIVE' ... [-info='Device with VPD filter the devices by active state'/>-]{+info='Inactive devices'/>+} Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- include/libvirt/libvirt-nodedev.h | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/include/libvirt/libvirt-nodedev.h b/include/libvirt/libvirt-nodedev.h index 0c01d51aab..8efcd7f506 100644 --- a/include/libvirt/libvirt-nodedev.h +++ b/include/libvirt/libvirt-nodedev.h @@ -60,9 +60,9 @@ int virNodeListDevices (virConnectPtr conn, /* * virConnectListAllNodeDevices: * - * Flags used to filter the returned node devices. */ + * Flags used to filter either by capability or active state, the + * returned node devices. */ typedef enum { - /* filter the devices by cap type */ VIR_CONNECT_LIST_NODE_DEVICES_CAP_SYSTEM = 1 << 0, /* System capability */ VIR_CONNECT_LIST_NODE_DEVICES_CAP_PCI_DEV = 1 << 1, /* PCI device */ VIR_CONNECT_LIST_NODE_DEVICES_CAP_USB_DEV = 1 << 2, /* USB device */ @@ -86,7 +86,6 @@ typedef enum { VIR_CONNECT_LIST_NODE_DEVICES_CAP_AP_MATRIX = 1 << 20, /* s390 AP Matrix */ VIR_CONNECT_LIST_NODE_DEVICES_CAP_VPD = 1 << 21, /* Device with VPD */ - /* filter the devices by active state */ VIR_CONNECT_LIST_NODE_DEVICES_INACTIVE = 1 << 30, /* Inactive devices */ VIR_CONNECT_LIST_NODE_DEVICES_ACTIVE = 1U << 31, /* Active devices */ } virConnectListAllNodeDeviceFlags; -- 2.35.1

virConnectAuthPtrDefault is the only variable that we export and with the documentation being at the C file, it makes harder to find it. With this patch, the documentation of this variable can be found by those who look at the header file for guidance plus, it will also be included in the XML API, as the followup patch will fix apibuild.py to store what is documented in the header file for this variable. Note that the apibuild, does not do the same with .c files. It'd require adding it for (parsing) recursion, similar to what is done for functions. Considering the pros/cons, seems more reasonable to move the docstring to the header file instead. Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- include/libvirt/libvirt-host.h | 13 +++++++++++++ src/libvirt.c | 11 +---------- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/include/libvirt/libvirt-host.h b/include/libvirt/libvirt-host.h index 1dc4b8a147..8cccf2921f 100644 --- a/include/libvirt/libvirt-host.h +++ b/include/libvirt/libvirt-host.h @@ -562,6 +562,19 @@ struct _virConnectAuth { typedef struct _virConnectAuth virConnectAuth; typedef virConnectAuth *virConnectAuthPtr; +/* + * virConnectAuthPtrDefault: + * + * A default implementation of the authentication callbacks. This + * implementation is suitable for command line based tools. It will + * prompt for username, passwords, realm and one time keys as needed. + * It will print on STDOUT, and read from STDIN. If this is not + * suitable for the application's needs an alternative implementation + * should be provided. + * + * Since: v0.4.1 + * + */ VIR_EXPORT_VAR virConnectAuthPtr virConnectAuthPtrDefault; /** diff --git a/src/libvirt.c b/src/libvirt.c index 45315f484c..6cda75d1ca 100644 --- a/src/libvirt.c +++ b/src/libvirt.c @@ -197,16 +197,7 @@ static virConnectAuth virConnectAuthDefault = { NULL, }; -/* - * virConnectAuthPtrDefault - * - * A default implementation of the authentication callbacks. This - * implementation is suitable for command line based tools. It will - * prompt for username, passwords, realm and one time keys as needed. - * It will print on STDOUT, and read from STDIN. If this is not - * suitable for the application's needs an alternative implementation - * should be provided. - */ +/* Explanation in the header file */ virConnectAuthPtr virConnectAuthPtrDefault = &virConnectAuthDefault; static bool virGlobalError; -- 2.35.1

Either create or append to existing docstring, the version (git tag) that a given enum value was introduced in the format: Since: v1.2.3 Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- include/libvirt/libvirt-domain-checkpoint.h | 28 +- include/libvirt/libvirt-domain-snapshot.h | 60 +- include/libvirt/libvirt-domain.h | 1183 +++++++++++-------- include/libvirt/libvirt-event.h | 8 +- include/libvirt/libvirt-host.h | 58 +- include/libvirt/libvirt-interface.h | 8 +- include/libvirt/libvirt-network.h | 88 +- include/libvirt/libvirt-nodedev.h | 66 +- include/libvirt/libvirt-nwfilter.h | 4 +- include/libvirt/libvirt-secret.h | 36 +- include/libvirt/libvirt-storage.h | 120 +- include/libvirt/libvirt-stream.h | 12 +- include/libvirt/virterror.h | 406 +++---- 13 files changed, 1121 insertions(+), 956 deletions(-) diff --git a/include/libvirt/libvirt-domain-checkpoint.h b/include/libvirt/libvirt-domain-checkpoint.h index a2f97531f8..a59578b857 100644 --- a/include/libvirt/libvirt-domain-checkpoint.h +++ b/include/libvirt/libvirt-domain-checkpoint.h @@ -52,13 +52,13 @@ virConnectPtr virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint); typedef enum { VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE = (1 << 0), /* Restore or alter - metadata */ + metadata (Since: v5.6.0) */ VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE = (1 << 1), /* use guest agent to quiesce all mounted file systems within - the domain */ + the domain (Since: v5.6.0) */ VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE_VALIDATE = (1 << 2), /* validate disk data state - when redefining a checkpoint */ + when redefining a checkpoint (Since: v6.10.0) */ } virDomainCheckpointCreateFlags; /* Create a checkpoint using the current VM state. */ @@ -67,11 +67,11 @@ virDomainCheckpointPtr virDomainCheckpointCreateXML(virDomainPtr domain, unsigned int flags); typedef enum { - VIR_DOMAIN_CHECKPOINT_XML_SECURE = (1 << 0), /* Include sensitive data */ + VIR_DOMAIN_CHECKPOINT_XML_SECURE = (1 << 0), /* Include sensitive data (Since: v5.6.0) */ VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN = (1 << 1), /* Suppress <domain> - subelement */ + subelement (Since: v5.6.0) */ VIR_DOMAIN_CHECKPOINT_XML_SIZE = (1 << 2), /* Include dynamic - per-<disk> size */ + per-<disk> size (Since: v5.6.0) */ } virDomainCheckpointXMLFlags; /* Dump the XML of a checkpoint */ @@ -90,18 +90,18 @@ char *virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint, typedef enum { VIR_DOMAIN_CHECKPOINT_LIST_ROOTS = (1 << 0), /* Filter by checkpoints with no parents, when - listing a domain */ + listing a domain (Since: v5.6.0) */ VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS = (1 << 0), /* List all descendants, not just children, when - listing a checkpoint */ + listing a checkpoint (Since: v5.6.0) */ VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL = (1 << 1), /* Ensure parents occur before children in - the resulting list */ + the resulting list (Since: v5.6.0) */ VIR_DOMAIN_CHECKPOINT_LIST_LEAVES = (1 << 2), /* Filter by checkpoints - with no children */ + with no children (Since: v5.6.0) */ VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES = (1 << 3), /* Filter by checkpoints - that have children */ + that have children (Since: v5.6.0) */ } virDomainCheckpointListFlags; /* Get all checkpoint objects for this domain */ @@ -125,9 +125,9 @@ virDomainCheckpointPtr virDomainCheckpointGetParent(virDomainCheckpointPtr check /* Delete a checkpoint */ typedef enum { - VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN = (1 << 0), /* Also delete children */ - VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY = (1 << 1), /* Delete just metadata */ - VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY = (1 << 2), /* Delete just children */ + VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN = (1 << 0), /* Also delete children (Since: v5.6.0) */ + VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY = (1 << 1), /* Delete just metadata (Since: v5.6.0) */ + VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY = (1 << 2), /* Delete just children (Since: v5.6.0) */ } virDomainCheckpointDeleteFlags; int virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint, diff --git a/include/libvirt/libvirt-domain-snapshot.h b/include/libvirt/libvirt-domain-snapshot.h index d729d1a532..5dffabb764 100644 --- a/include/libvirt/libvirt-domain-snapshot.h +++ b/include/libvirt/libvirt-domain-snapshot.h @@ -51,28 +51,28 @@ virConnectPtr virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot); typedef enum { VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE = (1 << 0), /* Restore or alter - metadata */ + metadata (Since: v0.9.5) */ VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT = (1 << 1), /* With redefine, make - snapshot current */ + snapshot current (Since: v0.9.5) */ VIR_DOMAIN_SNAPSHOT_CREATE_NO_METADATA = (1 << 2), /* Make snapshot without - remembering it */ + remembering it (Since: v0.9.5) */ VIR_DOMAIN_SNAPSHOT_CREATE_HALT = (1 << 3), /* Stop running guest - after snapshot */ + after snapshot (Since: v0.9.5) */ VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY = (1 << 4), /* disk snapshot, not - full system */ + full system (Since: v0.9.5) */ VIR_DOMAIN_SNAPSHOT_CREATE_REUSE_EXT = (1 << 5), /* reuse any existing - external files */ + external files (Since: v0.9.10) */ VIR_DOMAIN_SNAPSHOT_CREATE_QUIESCE = (1 << 6), /* use guest agent to quiesce all mounted file systems within - the domain */ + the domain (Since: v0.9.10) */ VIR_DOMAIN_SNAPSHOT_CREATE_ATOMIC = (1 << 7), /* atomically avoid - partial changes */ + partial changes (Since: v0.9.11) */ VIR_DOMAIN_SNAPSHOT_CREATE_LIVE = (1 << 8), /* create the snapshot while the guest is - running */ + running (Since: v1.0.1) */ VIR_DOMAIN_SNAPSHOT_CREATE_VALIDATE = (1 << 9), /* validate the XML - against the schema */ + against the schema (Since: v5.6.0) */ } virDomainSnapshotCreateFlags; /* Take a snapshot of the current VM state */ @@ -81,7 +81,7 @@ virDomainSnapshotPtr virDomainSnapshotCreateXML(virDomainPtr domain, unsigned int flags); typedef enum { - VIR_DOMAIN_SNAPSHOT_XML_SECURE = VIR_DOMAIN_XML_SECURE, /* dump security sensitive information too */ + VIR_DOMAIN_SNAPSHOT_XML_SECURE = VIR_DOMAIN_XML_SECURE, /* dump security sensitive information too (Since: v5.1.0) */ } virDomainSnapshotXMLFlags; /* Dump the XML of a snapshot */ @@ -102,45 +102,45 @@ char *virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot, typedef enum { VIR_DOMAIN_SNAPSHOT_LIST_ROOTS = (1 << 0), /* Filter by snapshots with no parents, when - listing a domain */ + listing a domain (Since: v0.9.5) */ VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS = (1 << 0), /* List all descendants, not just children, when listing a snapshot */ - /* For historical reasons, groups do not use contiguous bits. */ + /* For historical reasons, groups do not use contiguous bits. (Since: v0.9.7) */ VIR_DOMAIN_SNAPSHOT_LIST_LEAVES = (1 << 2), /* Filter by snapshots - with no children */ + with no children (Since: v0.9.7) */ VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES = (1 << 3), /* Filter by snapshots - that have children */ + that have children (Since: v0.9.13) */ VIR_DOMAIN_SNAPSHOT_LIST_METADATA = (1 << 1), /* Filter by snapshots - which have metadata */ + which have metadata (Since: v0.9.5) */ VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA = (1 << 4), /* Filter by snapshots - with no metadata */ + with no metadata (Since: v0.9.13) */ VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE = (1 << 5), /* Filter by snapshots taken while guest was - shut off */ + shut off (Since: v1.0.1) */ VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE = (1 << 6), /* Filter by snapshots taken while guest was active, and with - memory state */ + memory state (Since: v1.0.1) */ VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY = (1 << 7), /* Filter by snapshots taken while guest was active, but without - memory state */ + memory state (Since: v1.0.1) */ VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL = (1 << 8), /* Filter by snapshots stored internal to - disk images */ + disk images (Since: v1.0.1) */ VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL = (1 << 9), /* Filter by snapshots that use files external - to disk images */ + to disk images (Since: v1.0.1) */ VIR_DOMAIN_SNAPSHOT_LIST_TOPOLOGICAL = (1 << 10), /* Ensure parents occur before children in - the resulting list */ + the resulting list (Since: v5.2.0) */ } virDomainSnapshotListFlags; /* Return the number of snapshots for this domain */ @@ -195,10 +195,10 @@ int virDomainSnapshotHasMetadata(virDomainSnapshotPtr snapshot, unsigned int flags); typedef enum { - VIR_DOMAIN_SNAPSHOT_REVERT_RUNNING = 1 << 0, /* Run after revert */ - VIR_DOMAIN_SNAPSHOT_REVERT_PAUSED = 1 << 1, /* Pause after revert */ - VIR_DOMAIN_SNAPSHOT_REVERT_FORCE = 1 << 2, /* Allow risky reverts */ - VIR_DOMAIN_SNAPSHOT_REVERT_RESET_NVRAM = 1 << 3, /* Re-initialize NVRAM from template */ + VIR_DOMAIN_SNAPSHOT_REVERT_RUNNING = 1 << 0, /* Run after revert (Since: v0.9.5) */ + VIR_DOMAIN_SNAPSHOT_REVERT_PAUSED = 1 << 1, /* Pause after revert (Since: v0.9.5) */ + VIR_DOMAIN_SNAPSHOT_REVERT_FORCE = 1 << 2, /* Allow risky reverts (Since: v0.9.7) */ + VIR_DOMAIN_SNAPSHOT_REVERT_RESET_NVRAM = 1 << 3, /* Re-initialize NVRAM from template (Since: v8.1.0) */ } virDomainSnapshotRevertFlags; /* Revert the domain to a point-in-time snapshot. The @@ -210,9 +210,9 @@ int virDomainRevertToSnapshot(virDomainSnapshotPtr snapshot, /* Delete a snapshot */ typedef enum { - VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN = (1 << 0), /* Also delete children */ - VIR_DOMAIN_SNAPSHOT_DELETE_METADATA_ONLY = (1 << 1), /* Delete just metadata */ - VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN_ONLY = (1 << 2), /* Delete just children */ + VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN = (1 << 0), /* Also delete children (Since: v0.8.0) */ + VIR_DOMAIN_SNAPSHOT_DELETE_METADATA_ONLY = (1 << 1), /* Delete just metadata (Since: v0.9.5) */ + VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN_ONLY = (1 << 2), /* Delete just children (Since: v0.9.5) */ } virDomainSnapshotDeleteFlags; int virDomainSnapshotDelete(virDomainSnapshotPtr snapshot, diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h index 1275f4530d..de2d14d4af 100644 --- a/include/libvirt/libvirt-domain.h +++ b/include/libvirt/libvirt-domain.h @@ -49,15 +49,15 @@ typedef virDomain *virDomainPtr; * A domain may be in different states at a given point in time */ typedef enum { - VIR_DOMAIN_NOSTATE = 0, /* no state */ - VIR_DOMAIN_RUNNING = 1, /* the domain is running */ - VIR_DOMAIN_BLOCKED = 2, /* the domain is blocked on resource */ - VIR_DOMAIN_PAUSED = 3, /* the domain is paused by user */ - VIR_DOMAIN_SHUTDOWN= 4, /* the domain is being shut down */ - VIR_DOMAIN_SHUTOFF = 5, /* the domain is shut off */ - VIR_DOMAIN_CRASHED = 6, /* the domain is crashed */ + VIR_DOMAIN_NOSTATE = 0, /* no state (Since: v0.0.1) */ + VIR_DOMAIN_RUNNING = 1, /* the domain is running (Since: v0.0.1) */ + VIR_DOMAIN_BLOCKED = 2, /* the domain is blocked on resource (Since: v0.0.1) */ + VIR_DOMAIN_PAUSED = 3, /* the domain is paused by user (Since: v0.0.1) */ + VIR_DOMAIN_SHUTDOWN= 4, /* the domain is being shut down (Since: v0.0.1) */ + VIR_DOMAIN_SHUTOFF = 5, /* the domain is shut off (Since: v0.0.1) */ + VIR_DOMAIN_CRASHED = 6, /* the domain is crashed (Since: v0.0.2) */ VIR_DOMAIN_PMSUSPENDED = 7, /* the domain is suspended by guest - power management */ + power management (Since: v0.9.11) */ # ifdef VIR_ENUM_SENTINELS VIR_DOMAIN_LAST @@ -65,114 +65,116 @@ typedef enum { * NB: this enum value will increase over time as new states are * added to the libvirt API. It reflects the last state supported * by this version of the libvirt API. + * + * Since: v0.9.5 */ # endif } virDomainState; typedef enum { - VIR_DOMAIN_NOSTATE_UNKNOWN = 0, + VIR_DOMAIN_NOSTATE_UNKNOWN = 0, /* (Since: v0.9.2) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_NOSTATE_LAST + VIR_DOMAIN_NOSTATE_LAST /* (Since: v0.9.10) */ # endif } virDomainNostateReason; typedef enum { - VIR_DOMAIN_RUNNING_UNKNOWN = 0, - VIR_DOMAIN_RUNNING_BOOTED = 1, /* normal startup from boot */ - VIR_DOMAIN_RUNNING_MIGRATED = 2, /* migrated from another host */ - VIR_DOMAIN_RUNNING_RESTORED = 3, /* restored from a state file */ - VIR_DOMAIN_RUNNING_FROM_SNAPSHOT = 4, /* restored from snapshot */ - VIR_DOMAIN_RUNNING_UNPAUSED = 5, /* returned from paused state */ - VIR_DOMAIN_RUNNING_MIGRATION_CANCELED = 6, /* returned from migration */ - VIR_DOMAIN_RUNNING_SAVE_CANCELED = 7, /* returned from failed save process */ + VIR_DOMAIN_RUNNING_UNKNOWN = 0, /* (Since: v0.9.2) */ + VIR_DOMAIN_RUNNING_BOOTED = 1, /* normal startup from boot (Since: v0.9.2) */ + VIR_DOMAIN_RUNNING_MIGRATED = 2, /* migrated from another host (Since: v0.9.2) */ + VIR_DOMAIN_RUNNING_RESTORED = 3, /* restored from a state file (Since: v0.9.2) */ + VIR_DOMAIN_RUNNING_FROM_SNAPSHOT = 4, /* restored from snapshot (Since: v0.9.2) */ + VIR_DOMAIN_RUNNING_UNPAUSED = 5, /* returned from paused state (Since: v0.9.2) */ + VIR_DOMAIN_RUNNING_MIGRATION_CANCELED = 6, /* returned from migration (Since: v0.9.2) */ + VIR_DOMAIN_RUNNING_SAVE_CANCELED = 7, /* returned from failed save process (Since: v0.9.2) */ VIR_DOMAIN_RUNNING_WAKEUP = 8, /* returned from pmsuspended due to - wakeup event */ - VIR_DOMAIN_RUNNING_CRASHED = 9, /* resumed from crashed */ - VIR_DOMAIN_RUNNING_POSTCOPY = 10, /* running in post-copy migration mode */ + wakeup event (Since: v0.9.11) */ + VIR_DOMAIN_RUNNING_CRASHED = 9, /* resumed from crashed (Since: v1.1.1) */ + VIR_DOMAIN_RUNNING_POSTCOPY = 10, /* running in post-copy migration mode (Since: v1.3.3) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_RUNNING_LAST + VIR_DOMAIN_RUNNING_LAST /* (Since: v0.9.10) */ # endif } virDomainRunningReason; typedef enum { - VIR_DOMAIN_BLOCKED_UNKNOWN = 0, /* the reason is unknown */ + VIR_DOMAIN_BLOCKED_UNKNOWN = 0, /* the reason is unknown (Since: v0.9.2) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_BLOCKED_LAST + VIR_DOMAIN_BLOCKED_LAST /* (Since: v0.9.10) */ # endif } virDomainBlockedReason; typedef enum { - VIR_DOMAIN_PAUSED_UNKNOWN = 0, /* the reason is unknown */ - VIR_DOMAIN_PAUSED_USER = 1, /* paused on user request */ - VIR_DOMAIN_PAUSED_MIGRATION = 2, /* paused for offline migration */ - VIR_DOMAIN_PAUSED_SAVE = 3, /* paused for save */ - VIR_DOMAIN_PAUSED_DUMP = 4, /* paused for offline core dump */ - VIR_DOMAIN_PAUSED_IOERROR = 5, /* paused due to a disk I/O error */ - VIR_DOMAIN_PAUSED_WATCHDOG = 6, /* paused due to a watchdog event */ - VIR_DOMAIN_PAUSED_FROM_SNAPSHOT = 7, /* paused after restoring from snapshot */ - VIR_DOMAIN_PAUSED_SHUTTING_DOWN = 8, /* paused during shutdown process */ - VIR_DOMAIN_PAUSED_SNAPSHOT = 9, /* paused while creating a snapshot */ - VIR_DOMAIN_PAUSED_CRASHED = 10, /* paused due to a guest crash */ - VIR_DOMAIN_PAUSED_STARTING_UP = 11, /* the domain is being started */ - VIR_DOMAIN_PAUSED_POSTCOPY = 12, /* paused for post-copy migration */ - VIR_DOMAIN_PAUSED_POSTCOPY_FAILED = 13, /* paused after failed post-copy */ + VIR_DOMAIN_PAUSED_UNKNOWN = 0, /* the reason is unknown (Since: v0.9.2) */ + VIR_DOMAIN_PAUSED_USER = 1, /* paused on user request (Since: v0.9.2) */ + VIR_DOMAIN_PAUSED_MIGRATION = 2, /* paused for offline migration (Since: v0.9.2) */ + VIR_DOMAIN_PAUSED_SAVE = 3, /* paused for save (Since: v0.9.2) */ + VIR_DOMAIN_PAUSED_DUMP = 4, /* paused for offline core dump (Since: v0.9.2) */ + VIR_DOMAIN_PAUSED_IOERROR = 5, /* paused due to a disk I/O error (Since: v0.9.2) */ + VIR_DOMAIN_PAUSED_WATCHDOG = 6, /* paused due to a watchdog event (Since: v0.9.2) */ + VIR_DOMAIN_PAUSED_FROM_SNAPSHOT = 7, /* paused after restoring from snapshot (Since: v0.9.2) */ + VIR_DOMAIN_PAUSED_SHUTTING_DOWN = 8, /* paused during shutdown process (Since: v0.9.5) */ + VIR_DOMAIN_PAUSED_SNAPSHOT = 9, /* paused while creating a snapshot (Since: v1.0.1) */ + VIR_DOMAIN_PAUSED_CRASHED = 10, /* paused due to a guest crash (Since: v1.1.1) */ + VIR_DOMAIN_PAUSED_STARTING_UP = 11, /* the domain is being started (Since: v1.2.14) */ + VIR_DOMAIN_PAUSED_POSTCOPY = 12, /* paused for post-copy migration (Since: v1.3.3) */ + VIR_DOMAIN_PAUSED_POSTCOPY_FAILED = 13, /* paused after failed post-copy (Since: v1.3.3) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_PAUSED_LAST + VIR_DOMAIN_PAUSED_LAST /* (Since: v0.9.10) */ # endif } virDomainPausedReason; typedef enum { - VIR_DOMAIN_SHUTDOWN_UNKNOWN = 0, /* the reason is unknown */ - VIR_DOMAIN_SHUTDOWN_USER = 1, /* shutting down on user request */ + VIR_DOMAIN_SHUTDOWN_UNKNOWN = 0, /* the reason is unknown (Since: v0.9.2) */ + VIR_DOMAIN_SHUTDOWN_USER = 1, /* shutting down on user request (Since: v0.9.2) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_SHUTDOWN_LAST + VIR_DOMAIN_SHUTDOWN_LAST /* (Since: v0.9.10) */ # endif } virDomainShutdownReason; typedef enum { - VIR_DOMAIN_SHUTOFF_UNKNOWN = 0, /* the reason is unknown */ - VIR_DOMAIN_SHUTOFF_SHUTDOWN = 1, /* normal shutdown */ - VIR_DOMAIN_SHUTOFF_DESTROYED = 2, /* forced poweroff */ - VIR_DOMAIN_SHUTOFF_CRASHED = 3, /* domain crashed */ - VIR_DOMAIN_SHUTOFF_MIGRATED = 4, /* migrated to another host */ - VIR_DOMAIN_SHUTOFF_SAVED = 5, /* saved to a file */ - VIR_DOMAIN_SHUTOFF_FAILED = 6, /* domain failed to start */ + VIR_DOMAIN_SHUTOFF_UNKNOWN = 0, /* the reason is unknown (Since: v0.9.2) */ + VIR_DOMAIN_SHUTOFF_SHUTDOWN = 1, /* normal shutdown (Since: v0.9.2) */ + VIR_DOMAIN_SHUTOFF_DESTROYED = 2, /* forced poweroff (Since: v0.9.2) */ + VIR_DOMAIN_SHUTOFF_CRASHED = 3, /* domain crashed (Since: v0.9.2) */ + VIR_DOMAIN_SHUTOFF_MIGRATED = 4, /* migrated to another host (Since: v0.9.2) */ + VIR_DOMAIN_SHUTOFF_SAVED = 5, /* saved to a file (Since: v0.9.2) */ + VIR_DOMAIN_SHUTOFF_FAILED = 6, /* domain failed to start (Since: v0.9.2) */ VIR_DOMAIN_SHUTOFF_FROM_SNAPSHOT = 7, /* restored from a snapshot which was - * taken while domain was shutoff */ + * taken while domain was shutoff (Since: v0.9.2) */ VIR_DOMAIN_SHUTOFF_DAEMON = 8, /* daemon decides to kill domain - during reconnection processing */ + during reconnection processing (Since: v4.10.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_SHUTOFF_LAST + VIR_DOMAIN_SHUTOFF_LAST /* (Since: v0.9.10) */ # endif } virDomainShutoffReason; typedef enum { - VIR_DOMAIN_CRASHED_UNKNOWN = 0, /* crashed for unknown reason */ - VIR_DOMAIN_CRASHED_PANICKED = 1, /* domain panicked */ + VIR_DOMAIN_CRASHED_UNKNOWN = 0, /* crashed for unknown reason (Since: v0.9.2) */ + VIR_DOMAIN_CRASHED_PANICKED = 1, /* domain panicked (Since: v1.1.1) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_CRASHED_LAST + VIR_DOMAIN_CRASHED_LAST /* (Since: v0.9.10) */ # endif } virDomainCrashedReason; typedef enum { - VIR_DOMAIN_PMSUSPENDED_UNKNOWN = 0, + VIR_DOMAIN_PMSUSPENDED_UNKNOWN = 0, /* (Since: v0.9.11) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_PMSUSPENDED_LAST + VIR_DOMAIN_PMSUSPENDED_LAST /* (Since: v0.9.11) */ # endif } virDomainPMSuspendedReason; typedef enum { - VIR_DOMAIN_PMSUSPENDED_DISK_UNKNOWN = 0, + VIR_DOMAIN_PMSUSPENDED_DISK_UNKNOWN = 0, /* (Since: v1.0.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_PMSUSPENDED_DISK_LAST + VIR_DOMAIN_PMSUSPENDED_DISK_LAST /* (Since: v1.0.0) */ # endif } virDomainPMSuspendedDiskReason; @@ -182,17 +184,17 @@ typedef enum { * Current state of a control interface to the domain. */ typedef enum { - VIR_DOMAIN_CONTROL_OK = 0, /* operational, ready to accept commands */ + VIR_DOMAIN_CONTROL_OK = 0, /* operational, ready to accept commands (Since: v0.9.3) */ VIR_DOMAIN_CONTROL_JOB = 1, /* background job is running (can be monitored by virDomainGetJobInfo); only - limited set of commands may be allowed */ - VIR_DOMAIN_CONTROL_OCCUPIED = 2, /* occupied by a running command */ + limited set of commands may be allowed (Since: v0.9.3) */ + VIR_DOMAIN_CONTROL_OCCUPIED = 2, /* occupied by a running command (Since: v0.9.3) */ VIR_DOMAIN_CONTROL_ERROR = 3, /* unusable, domain cannot be fully operated, possible reason is provided - in the details field */ + in the details field (Since: v0.9.3) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_CONTROL_LAST + VIR_DOMAIN_CONTROL_LAST /* (Since: v0.9.10) */ # endif } virDomainControlState; @@ -203,16 +205,16 @@ typedef enum { */ typedef enum { VIR_DOMAIN_CONTROL_ERROR_REASON_NONE = 0, /* server didn't provide a - reason */ + reason (Since: v1.2.14) */ VIR_DOMAIN_CONTROL_ERROR_REASON_UNKNOWN = 1, /* unknown reason for the - error */ + error (Since: v1.2.14) */ VIR_DOMAIN_CONTROL_ERROR_REASON_MONITOR = 2, /* monitor connection is - broken */ + broken (Since: v1.2.14) */ VIR_DOMAIN_CONTROL_ERROR_REASON_INTERNAL = 3, /* error caused due to - internal failure in libvirt + internal failure in libvirt (Since: v1.2.14) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_CONTROL_ERROR_REASON_LAST + VIR_DOMAIN_CONTROL_ERROR_REASON_LAST /* (Since: v1.2.14) */ # endif } virDomainControlErrorReason; @@ -258,10 +260,10 @@ typedef virDomainControlInfo *virDomainControlInfoPtr; * These enums should not conflict with those of virTypedParameterFlags. */ typedef enum { - VIR_DOMAIN_AFFECT_CURRENT = 0, /* Affect current domain state. */ - VIR_DOMAIN_AFFECT_LIVE = 1 << 0, /* Affect running domain state. */ + VIR_DOMAIN_AFFECT_CURRENT = 0, /* Affect current domain state. (Since: v0.9.2) */ + VIR_DOMAIN_AFFECT_LIVE = 1 << 0, /* Affect running domain state. (Since: v0.9.2) */ VIR_DOMAIN_AFFECT_CONFIG = 1 << 1, /* Affect persistent domain state. */ - /* 1 << 2 is reserved for virTypedParameterFlags */ + /* 1 << 2 is reserved for virTypedParameterFlags (Since: v0.9.2) */ } virDomainModificationImpact; /** @@ -296,13 +298,13 @@ typedef virDomainInfo *virDomainInfoPtr; * Domain. */ typedef enum { - VIR_DOMAIN_NONE = 0, /* Default behavior */ - VIR_DOMAIN_START_PAUSED = 1 << 0, /* Launch guest in paused state */ - VIR_DOMAIN_START_AUTODESTROY = 1 << 1, /* Automatically kill guest when virConnectPtr is closed */ - VIR_DOMAIN_START_BYPASS_CACHE = 1 << 2, /* Avoid file system cache pollution */ - VIR_DOMAIN_START_FORCE_BOOT = 1 << 3, /* Boot, discarding any managed save */ - VIR_DOMAIN_START_VALIDATE = 1 << 4, /* Validate the XML document against schema */ - VIR_DOMAIN_START_RESET_NVRAM = 1 << 5, /* Re-initialize NVRAM from template */ + VIR_DOMAIN_NONE = 0, /* Default behavior (Since: v0.0.1) */ + VIR_DOMAIN_START_PAUSED = 1 << 0, /* Launch guest in paused state (Since: v0.8.2) */ + VIR_DOMAIN_START_AUTODESTROY = 1 << 1, /* Automatically kill guest when virConnectPtr is closed (Since: v0.9.3) */ + VIR_DOMAIN_START_BYPASS_CACHE = 1 << 2, /* Avoid file system cache pollution (Since: v0.9.4) */ + VIR_DOMAIN_START_FORCE_BOOT = 1 << 3, /* Boot, discarding any managed save (Since: v0.9.5) */ + VIR_DOMAIN_START_VALIDATE = 1 << 4, /* Validate the XML document against schema (Since: v1.2.12) */ + VIR_DOMAIN_START_RESET_NVRAM = 1 << 5, /* Re-initialize NVRAM from template (Since: v8.1.0) */ } virDomainCreateFlags; @@ -585,9 +587,9 @@ typedef virDomainInterfaceStatsStruct *virDomainInterfaceStatsPtr; * Memory Statistics Tags: */ typedef enum { - /* The total amount of data read from swap space (in kB). */ + /* The total amount of data read from swap space (in kB). (Since: v0.7.5) */ VIR_DOMAIN_MEMORY_STAT_SWAP_IN = 0, - /* The total amount of memory written out to swap space (in kB). */ + /* The total amount of memory written out to swap space (in kB). (Since: v0.7.5) */ VIR_DOMAIN_MEMORY_STAT_SWAP_OUT = 1, /* @@ -595,14 +597,24 @@ typedef enum { * that is not available. When servicing the page fault, if disk IO is * required, it is considered a major fault. If not, it is a minor fault. * These are expressed as the number of faults that have occurred. + * + * Since: v0.7.5 + * */ VIR_DOMAIN_MEMORY_STAT_MAJOR_FAULT = 2, + + /* + * Since: v0.7.5 + */ VIR_DOMAIN_MEMORY_STAT_MINOR_FAULT = 3, /* * The amount of memory left completely unused by the system. Memory that * is available but used for reclaimable caches should NOT be reported as * free. This value is expressed in kB. + * + * Since: v0.7.5 + * */ VIR_DOMAIN_MEMORY_STAT_UNUSED = 4, @@ -611,52 +623,82 @@ typedef enum { * may be less than the amount of memory assigned to the domain if a * balloon driver is in use or if the guest OS does not initialize all * assigned pages. This value is expressed in kB. + * + * Since: v0.7.5 + * */ VIR_DOMAIN_MEMORY_STAT_AVAILABLE = 5, - /* Current balloon value (in KB). */ + /* + * Current balloon value (in KB). + * + * Since: v0.9.3 + * + */ VIR_DOMAIN_MEMORY_STAT_ACTUAL_BALLOON = 6, /* Resident Set Size of the process running the domain. This value - * is in kB */ + * is in kB + * + * Since: v0.9.10 + */ VIR_DOMAIN_MEMORY_STAT_RSS = 7, /* * How much the balloon can be inflated without pushing the guest system * to swap, corresponds to 'Available' in /proc/meminfo + * + * Since: v2.1.0 + * */ VIR_DOMAIN_MEMORY_STAT_USABLE = 8, - /* Timestamp of the last update of statistics, in seconds. */ + /* + * Timestamp of the last update of statistics, in seconds. + * + * Since: v2.1.0 + */ VIR_DOMAIN_MEMORY_STAT_LAST_UPDATE = 9, /* * The amount of memory, that can be quickly reclaimed without * additional I/O (in kB). Typically these pages are used for caching files * from disk. + * + * Since: v4.6.0 + * */ VIR_DOMAIN_MEMORY_STAT_DISK_CACHES = 10, /* * The number of successful huge page allocations from inside the domain via * virtio balloon. + * + * Since: v5.4.0 + * */ VIR_DOMAIN_MEMORY_STAT_HUGETLB_PGALLOC = 11, /* * The number of failed huge page allocations from inside the domain via * virtio balloon. + * + * Since: v5.4.0 + * */ VIR_DOMAIN_MEMORY_STAT_HUGETLB_PGFAIL = 12, /* * The number of statistics supported by this version of the interface. * To add new statistics, add them to the enum and increase this value. + * + * Since: v0.7.5 + * */ VIR_DOMAIN_MEMORY_STAT_NR = 13, # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_MEMORY_STAT_LAST = VIR_DOMAIN_MEMORY_STAT_NR + VIR_DOMAIN_MEMORY_STAT_LAST = VIR_DOMAIN_MEMORY_STAT_NR /* (Since: v0.9.10) */ # endif } virDomainMemoryStatTags; @@ -672,11 +714,11 @@ typedef virDomainMemoryStatStruct *virDomainMemoryStatPtr; /* Domain core dump flags. */ typedef enum { - VIR_DUMP_CRASH = (1 << 0), /* crash after dump */ - VIR_DUMP_LIVE = (1 << 1), /* live dump */ - VIR_DUMP_BYPASS_CACHE = (1 << 2), /* avoid file system cache pollution */ - VIR_DUMP_RESET = (1 << 3), /* reset domain after dump finishes */ - VIR_DUMP_MEMORY_ONLY = (1 << 4), /* use dump-guest-memory */ + VIR_DUMP_CRASH = (1 << 0), /* crash after dump (Since: v0.7.5) */ + VIR_DUMP_LIVE = (1 << 1), /* live dump (Since: v0.7.5) */ + VIR_DUMP_BYPASS_CACHE = (1 << 2), /* avoid file system cache pollution (Since: v0.9.4) */ + VIR_DUMP_RESET = (1 << 3), /* reset domain after dump finishes (Since: v0.9.7) */ + VIR_DUMP_MEMORY_ONLY = (1 << 4), /* use dump-guest-memory (Since: v0.9.13) */ } virDomainCoreDumpFlags; /** @@ -685,20 +727,22 @@ typedef enum { * Values for specifying different formats of domain core dumps. */ typedef enum { - VIR_DOMAIN_CORE_DUMP_FORMAT_RAW, /* dump guest memory in raw format */ + VIR_DOMAIN_CORE_DUMP_FORMAT_RAW, /* dump guest memory in raw format (Since: v1.2.3) */ VIR_DOMAIN_CORE_DUMP_FORMAT_KDUMP_ZLIB, /* kdump-compressed format, with - * zlib compression */ + * zlib compression (Since: v1.2.3) */ VIR_DOMAIN_CORE_DUMP_FORMAT_KDUMP_LZO, /* kdump-compressed format, with - * lzo compression */ + * lzo compression (Since: v1.2.3) */ VIR_DOMAIN_CORE_DUMP_FORMAT_KDUMP_SNAPPY, /* kdump-compressed format, with - * snappy compression */ - VIR_DOMAIN_CORE_DUMP_FORMAT_WIN_DMP, /* Windows full crashdump format */ + * snappy compression (Since: v1.2.3) */ + VIR_DOMAIN_CORE_DUMP_FORMAT_WIN_DMP, /* Windows full crashdump format (Since: v7.4.0) */ # ifdef VIR_ENUM_SENTINELS VIR_DOMAIN_CORE_DUMP_FORMAT_LAST /* * NB: this enum value will increase over time as new formats are * added to the libvirt API. It reflects the last format supported * by this version of the libvirt API. + * + * Since: v1.2.3 */ # endif } virDomainCoreDumpFormat; @@ -710,6 +754,9 @@ typedef enum { * The migration may never converge if the domain is changing its memory * faster then it can be transferred. The domain can be manually paused * anytime during migration using virDomainSuspend. + * + * Since: v0.3.2 + * */ VIR_MIGRATE_LIVE = (1 << 0), @@ -718,6 +765,9 @@ typedef enum { * controls the migration process. In peer-to-peer mode, the source * libvirtd controls the migration by calling the destination daemon * directly. + * + * Since: v0.7.2 + * */ VIR_MIGRATE_PEER2PEER = (1 << 1), @@ -728,6 +778,9 @@ typedef enum { * * Note the less-common spelling that we're stuck with: * VIR_MIGRATE_TUNNELLED should be VIR_MIGRATE_TUNNELED. + * + * Since: v0.7.2 + * */ VIR_MIGRATE_TUNNELLED = (1 << 2), @@ -735,17 +788,26 @@ typedef enum { * migration. If the domain was persistent on the source host and * VIR_MIGRATE_UNDEFINE_SOURCE is not used, it will end up persistent on * both hosts. + * + * Since: v0.7.3 + * */ VIR_MIGRATE_PERSIST_DEST = (1 << 3), /* Undefine the domain on the source host once migration successfully * finishes. + * + * Since: v0.7.3 + * */ VIR_MIGRATE_UNDEFINE_SOURCE = (1 << 4), /* Leave the domain suspended on the destination host. virDomainResume (on * the virDomainPtr returned by the migration API) has to be called * explicitly to resume domain's virtual CPUs. + * + * Since: v0.7.5 + * */ VIR_MIGRATE_PAUSED = (1 << 5), @@ -755,6 +817,9 @@ typedef enum { * disks should be migrated. * * This flag and VIR_MIGRATE_NON_SHARED_INC are mutually exclusive. + * + * Since: v0.8.2 + * */ VIR_MIGRATE_NON_SHARED_DISK = (1 << 6), @@ -765,6 +830,9 @@ typedef enum { * on the source host. * * This flag and VIR_MIGRATE_NON_SHARED_DISK are mutually exclusive. + * + * Since: v0.8.2 + * */ VIR_MIGRATE_NON_SHARED_INC = (1 << 7), @@ -772,6 +840,9 @@ typedef enum { * process. This flag is used automatically when both sides support it. * Explicitly setting this flag will cause migration to fail if either the * source or the destination does not support it. + * + * Since: v0.9.4 + * */ VIR_MIGRATE_CHANGE_PROTECTION = (1 << 8), @@ -782,6 +853,9 @@ typedef enum { * without explicitly setting cache mode to "none". Migrating such domains * is unsafe unless the disk images are stored on coherent clustered * filesystem, such as GFS2 or GPFS. + * + * Since: v0.9.11 + * */ VIR_MIGRATE_UNSAFE = (1 << 9), @@ -791,6 +865,9 @@ typedef enum { * * Offline migration may not copy disk storage or any other file based * storage (such as UEFI variables). + * + * Since: v1.0.1 + * */ VIR_MIGRATE_OFFLINE = (1 << 10), @@ -798,11 +875,17 @@ typedef enum { * VIR_MIGRATE_PARAM_COMPRESSION. A hypervisor default method will be used * if this parameter is omitted. Individual compression methods can be * tuned via their specific VIR_MIGRATE_PARAM_COMPRESSION_* parameters. + * + * Since: v1.0.3 + * */ VIR_MIGRATE_COMPRESSED = (1 << 11), /* Cancel migration if a soft error (such as I/O error) happens during * migration. + * + * Since: v1.1.0 + * */ VIR_MIGRATE_ABORT_ON_ERROR = (1 << 12), @@ -811,6 +894,9 @@ typedef enum { * not change its memory faster than a hypervisor can transfer the changed * memory to the destination host. VIR_MIGRATE_PARAM_AUTO_CONVERGE_* * parameters can be used to tune the algorithm. + * + * Since: v1.2.3 + * */ VIR_MIGRATE_AUTO_CONVERGE = (1 << 13), @@ -828,6 +914,9 @@ typedef enum { * most of the host's memory). Doing so may be dangerous to both the * domain and the host itself since the host's kernel may run out of * memory. + * + * Since: v1.2.9 + * */ VIR_MIGRATE_RDMA_PIN_ALL = (1 << 14), @@ -835,6 +924,9 @@ typedef enum { * migration. However, the migration will start normally and * virDomainMigrateStartPostCopy needs to be called to switch it into the * post-copy mode. See virDomainMigrateStartPostCopy for more details. + * + * Since: v1.3.3 + * */ VIR_MIGRATE_POSTCOPY = (1 << 15), @@ -842,12 +934,18 @@ typedef enum { * to use the TLS environment configured by the hypervisor in order to * perform the migration. If incorrectly configured on either source or * destination, the migration will fail. + * + * Since: v3.2.0 + * */ VIR_MIGRATE_TLS = (1 << 16), /* Send memory pages to the destination host through several network * connections. See VIR_MIGRATE_PARAM_PARALLEL_* parameters for * configuring the parallel migration. + * + * Since: v5.2.0 + * */ VIR_MIGRATE_PARALLEL = (1 << 17), @@ -858,6 +956,9 @@ typedef enum { * * Requires one of VIR_MIGRATE_NON_SHARED_DISK, VIR_MIGRATE_NON_SHARED_INC * to be present as well. + * + * Since: v8.0.0 + * */ VIR_MIGRATE_NON_SHARED_SYNCHRONOUS_WRITES = (1 << 18), @@ -1138,7 +1239,7 @@ int virDomainMigrateSetCompressionCache(virDomainPtr domain, /* Domain migration speed flags. */ typedef enum { - /* Set or get maximum speed of post-copy migration. */ + /* Set or get maximum speed of post-copy migration. (Since: v5.1.0) */ VIR_DOMAIN_MIGRATE_MAX_SPEED_POSTCOPY = (1 << 0), } virDomainMigrateMaxSpeedFlags; @@ -1200,12 +1301,12 @@ virDomainPtr virDomainLookupByUUIDString (virConnectPtr conn, const char *uuid); typedef enum { - VIR_DOMAIN_SHUTDOWN_DEFAULT = 0, /* hypervisor choice */ - VIR_DOMAIN_SHUTDOWN_ACPI_POWER_BTN = (1 << 0), /* Send ACPI event */ - VIR_DOMAIN_SHUTDOWN_GUEST_AGENT = (1 << 1), /* Use guest agent */ - VIR_DOMAIN_SHUTDOWN_INITCTL = (1 << 2), /* Use initctl */ - VIR_DOMAIN_SHUTDOWN_SIGNAL = (1 << 3), /* Send a signal */ - VIR_DOMAIN_SHUTDOWN_PARAVIRT = (1 << 4), /* Use paravirt guest control */ + VIR_DOMAIN_SHUTDOWN_DEFAULT = 0, /* hypervisor choice (Since: v0.9.10) */ + VIR_DOMAIN_SHUTDOWN_ACPI_POWER_BTN = (1 << 0), /* Send ACPI event (Since: v0.9.10) */ + VIR_DOMAIN_SHUTDOWN_GUEST_AGENT = (1 << 1), /* Use guest agent (Since: v0.9.10) */ + VIR_DOMAIN_SHUTDOWN_INITCTL = (1 << 2), /* Use initctl (Since: v1.0.1) */ + VIR_DOMAIN_SHUTDOWN_SIGNAL = (1 << 3), /* Send a signal (Since: v1.0.1) */ + VIR_DOMAIN_SHUTDOWN_PARAVIRT = (1 << 4), /* Use paravirt guest control (Since: v1.2.5) */ } virDomainShutdownFlagValues; int virDomainShutdown (virDomainPtr domain); @@ -1213,12 +1314,12 @@ int virDomainShutdownFlags (virDomainPtr domain, unsigned int flags); typedef enum { - VIR_DOMAIN_REBOOT_DEFAULT = 0, /* hypervisor choice */ - VIR_DOMAIN_REBOOT_ACPI_POWER_BTN = (1 << 0), /* Send ACPI event */ - VIR_DOMAIN_REBOOT_GUEST_AGENT = (1 << 1), /* Use guest agent */ - VIR_DOMAIN_REBOOT_INITCTL = (1 << 2), /* Use initctl */ - VIR_DOMAIN_REBOOT_SIGNAL = (1 << 3), /* Send a signal */ - VIR_DOMAIN_REBOOT_PARAVIRT = (1 << 4), /* Use paravirt guest control */ + VIR_DOMAIN_REBOOT_DEFAULT = 0, /* hypervisor choice (Since: v0.9.10) */ + VIR_DOMAIN_REBOOT_ACPI_POWER_BTN = (1 << 0), /* Send ACPI event (Since: v0.9.10) */ + VIR_DOMAIN_REBOOT_GUEST_AGENT = (1 << 1), /* Use guest agent (Since: v0.9.10) */ + VIR_DOMAIN_REBOOT_INITCTL = (1 << 2), /* Use initctl (Since: v1.0.1) */ + VIR_DOMAIN_REBOOT_SIGNAL = (1 << 3), /* Send a signal (Since: v1.0.1) */ + VIR_DOMAIN_REBOOT_PARAVIRT = (1 << 4), /* Use paravirt guest control (Since: v1.2.5) */ } virDomainRebootFlagValues; int virDomainReboot (virDomainPtr domain, @@ -1235,9 +1336,9 @@ int virDomainDestroy (virDomainPtr domain); * virDomainDestroyFlags() function */ typedef enum { - VIR_DOMAIN_DESTROY_DEFAULT = 0, /* Default behavior - could lead to data loss!! */ - VIR_DOMAIN_DESTROY_GRACEFUL = 1 << 0, /* only SIGTERM, no SIGKILL */ - VIR_DOMAIN_DESTROY_REMOVE_LOGS = 1 << 1, /* remove VM logs on destroy */ + VIR_DOMAIN_DESTROY_DEFAULT = 0, /* Default behavior - could lead to data loss!! (Since: v0.9.10) */ + VIR_DOMAIN_DESTROY_GRACEFUL = 1 << 0, /* only SIGTERM, no SIGKILL (Since: v0.9.10) */ + VIR_DOMAIN_DESTROY_REMOVE_LOGS = 1 << 1, /* remove VM logs on destroy (Since: v8.3.0) */ } virDomainDestroyFlagsValues; int virDomainDestroyFlags (virDomainPtr domain, @@ -1267,10 +1368,10 @@ int virDomainPMWakeup (virDomainPtr domain, * flags apply to all these functions. */ typedef enum { - VIR_DOMAIN_SAVE_BYPASS_CACHE = 1 << 0, /* Avoid file system cache pollution */ - VIR_DOMAIN_SAVE_RUNNING = 1 << 1, /* Favor running over paused */ - VIR_DOMAIN_SAVE_PAUSED = 1 << 2, /* Favor paused over running */ - VIR_DOMAIN_SAVE_RESET_NVRAM = 1 << 3, /* Re-initialize NVRAM from template */ + VIR_DOMAIN_SAVE_BYPASS_CACHE = 1 << 0, /* Avoid file system cache pollution (Since: v0.9.4) */ + VIR_DOMAIN_SAVE_RUNNING = 1 << 1, /* Favor running over paused (Since: v0.9.5) */ + VIR_DOMAIN_SAVE_PAUSED = 1 << 2, /* Favor paused over running (Since: v0.9.5) */ + VIR_DOMAIN_SAVE_RESET_NVRAM = 1 << 3, /* Re-initialize NVRAM from template (Since: v8.1.0) */ } virDomainSaveRestoreFlags; int virDomainSave (virDomainPtr domain, @@ -1520,12 +1621,12 @@ int virDomainGetMemoryParameters(virDomainPtr domain, /* Memory size modification flags. */ typedef enum { - /* See virDomainModificationImpact for these flags. */ + /* See virDomainModificationImpact for these flags. (Since: v1.0.0) */ VIR_DOMAIN_MEM_CURRENT = VIR_DOMAIN_AFFECT_CURRENT, VIR_DOMAIN_MEM_LIVE = VIR_DOMAIN_AFFECT_LIVE, VIR_DOMAIN_MEM_CONFIG = VIR_DOMAIN_AFFECT_CONFIG, - /* Additionally, these flags may be bitwise-OR'd in. */ + /* Additionally, these flags may be bitwise-OR'd in. (Since: v1.0.0) */ VIR_DOMAIN_MEM_MAXIMUM = (1 << 2), /* affect Max rather than current */ } virDomainMemoryModFlags; @@ -1538,13 +1639,13 @@ typedef enum { * a domain. */ typedef enum { - VIR_DOMAIN_NUMATUNE_MEM_STRICT = 0, - VIR_DOMAIN_NUMATUNE_MEM_PREFERRED = 1, - VIR_DOMAIN_NUMATUNE_MEM_INTERLEAVE = 2, - VIR_DOMAIN_NUMATUNE_MEM_RESTRICTIVE = 3, + VIR_DOMAIN_NUMATUNE_MEM_STRICT = 0, /* (Since: v0.9.9) */ + VIR_DOMAIN_NUMATUNE_MEM_PREFERRED = 1, /* (Since: v0.9.9) */ + VIR_DOMAIN_NUMATUNE_MEM_INTERLEAVE = 2, /* (Since: v0.9.9) */ + VIR_DOMAIN_NUMATUNE_MEM_RESTRICTIVE = 3, /* (Since: v7.3.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_NUMATUNE_MEM_LAST /* This constant is subject to change */ + VIR_DOMAIN_NUMATUNE_MEM_LAST /* This constant is subject to change (Since: v0.9.9) */ # endif } virDomainNumatuneMemMode; @@ -1597,8 +1698,8 @@ int virDomainGetSecurityLabel (virDomainPtr domain, virSecurityLabelPtr seclabel); typedef enum { - VIR_DOMAIN_GET_HOSTNAME_LEASE = (1 << 0), /* Parse DHCP lease file */ - VIR_DOMAIN_GET_HOSTNAME_AGENT = (1 << 1), /* Query qemu guest agent */ + VIR_DOMAIN_GET_HOSTNAME_LEASE = (1 << 0), /* Parse DHCP lease file (Since: v6.1.0) */ + VIR_DOMAIN_GET_HOSTNAME_AGENT = (1 << 1), /* Query qemu guest agent (Since: v6.1.0) */ } virDomainGetHostnameFlags; char * virDomainGetHostname (virDomainPtr domain, @@ -1607,12 +1708,12 @@ int virDomainGetSecurityLabelList (virDomainPtr domain, virSecurityLabelPtr* seclabels); typedef enum { - VIR_DOMAIN_METADATA_DESCRIPTION = 0, /* Operate on <description> */ - VIR_DOMAIN_METADATA_TITLE = 1, /* Operate on <title> */ - VIR_DOMAIN_METADATA_ELEMENT = 2, /* Operate on <metadata> */ + VIR_DOMAIN_METADATA_DESCRIPTION = 0, /* Operate on <description> (Since: v0.9.10) */ + VIR_DOMAIN_METADATA_TITLE = 1, /* Operate on <title> (Since: v0.9.10) */ + VIR_DOMAIN_METADATA_ELEMENT = 2, /* Operate on <metadata> (Since: v0.9.10) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_METADATA_LAST + VIR_DOMAIN_METADATA_LAST /* (Since: v0.9.10) */ # endif } virDomainMetadataType; @@ -1640,14 +1741,14 @@ virDomainGetMetadata(virDomainPtr domain, */ typedef enum { - VIR_DOMAIN_XML_SECURE = (1 << 0), /* dump security sensitive information too */ - VIR_DOMAIN_XML_INACTIVE = (1 << 1), /* dump inactive domain information */ - VIR_DOMAIN_XML_UPDATE_CPU = (1 << 2), /* update guest CPU requirements according to host CPU */ - VIR_DOMAIN_XML_MIGRATABLE = (1 << 3), /* dump XML suitable for migration */ + VIR_DOMAIN_XML_SECURE = (1 << 0), /* dump security sensitive information too (Since: v0.3.3) */ + VIR_DOMAIN_XML_INACTIVE = (1 << 1), /* dump inactive domain information (Since: v0.3.3) */ + VIR_DOMAIN_XML_UPDATE_CPU = (1 << 2), /* update guest CPU requirements according to host CPU (Since: v0.8.0) */ + VIR_DOMAIN_XML_MIGRATABLE = (1 << 3), /* dump XML suitable for migration (Since: v1.0.0) */ } virDomainXMLFlags; typedef enum { - VIR_DOMAIN_SAVE_IMAGE_XML_SECURE = VIR_DOMAIN_XML_SECURE, /* dump security sensitive information too */ + VIR_DOMAIN_SAVE_IMAGE_XML_SECURE = VIR_DOMAIN_XML_SECURE, /* dump security sensitive information too (Since: v5.1.0) */ } virDomainSaveImageXMLFlags; char * virDomainGetXMLDesc (virDomainPtr domain, @@ -1752,7 +1853,7 @@ int virDomainBlockPeek (virDomainPtr dom, * Flags available for virDomainBlockResize(). */ typedef enum { - VIR_DOMAIN_BLOCK_RESIZE_BYTES = 1 << 0, /* size in bytes instead of KiB */ + VIR_DOMAIN_BLOCK_RESIZE_BYTES = 1 << 0, /* size in bytes instead of KiB (Since: v0.9.11) */ } virDomainBlockResizeFlags; int virDomainBlockResize (virDomainPtr dom, @@ -1814,8 +1915,8 @@ int virDomainMemoryStats (virDomainPtr dom, /* Memory peeking flags. */ typedef enum { - VIR_MEMORY_VIRTUAL = 1 << 0, /* addresses are virtual addresses */ - VIR_MEMORY_PHYSICAL = 1 << 1, /* addresses are physical addresses */ + VIR_MEMORY_VIRTUAL = 1 << 0, /* addresses are virtual addresses (Since: v0.4.4) */ + VIR_MEMORY_PHYSICAL = 1 << 1, /* addresses are physical addresses (Since: v0.7.0) */ } virDomainMemoryFlags; int virDomainMemoryPeek (virDomainPtr dom, @@ -1825,7 +1926,7 @@ int virDomainMemoryPeek (virDomainPtr dom, unsigned int flags); typedef enum { - VIR_DOMAIN_DEFINE_VALIDATE = (1 << 0), /* Validate the XML document against schema */ + VIR_DOMAIN_DEFINE_VALIDATE = (1 << 0), /* Validate the XML document against schema (Since: v1.2.12) */ } virDomainDefineFlags; /* @@ -1841,18 +1942,18 @@ int virDomainUndefine (virDomainPtr domain); typedef enum { VIR_DOMAIN_UNDEFINE_MANAGED_SAVE = (1 << 0), /* Also remove any - managed save */ + managed save (Since: v0.9.4) */ VIR_DOMAIN_UNDEFINE_SNAPSHOTS_METADATA = (1 << 1), /* If last use of domain, then also remove any - snapshot metadata */ + snapshot metadata (Since: v0.9.5) */ VIR_DOMAIN_UNDEFINE_NVRAM = (1 << 2), /* Also remove any - nvram file */ - VIR_DOMAIN_UNDEFINE_KEEP_NVRAM = (1 << 3), /* Keep nvram file */ + nvram file (Since: v1.2.9) */ + VIR_DOMAIN_UNDEFINE_KEEP_NVRAM = (1 << 3), /* Keep nvram file (Since: v2.3.0) */ VIR_DOMAIN_UNDEFINE_CHECKPOINTS_METADATA = (1 << 4), /* If last use of domain, then also remove any checkpoint metadata */ - /* Future undefine control flags should come here. */ + /* Future undefine control flags should come here. (Since: v5.6.0) */ } virDomainUndefineFlagsValues; @@ -1870,28 +1971,28 @@ int virConnectListDefinedDomains (virConnectPtr conn, * then that group is not used to filter results. */ typedef enum { - VIR_CONNECT_LIST_DOMAINS_ACTIVE = 1 << 0, - VIR_CONNECT_LIST_DOMAINS_INACTIVE = 1 << 1, + VIR_CONNECT_LIST_DOMAINS_ACTIVE = 1 << 0, /* (Since: v0.9.13) */ + VIR_CONNECT_LIST_DOMAINS_INACTIVE = 1 << 1, /* (Since: v0.9.13) */ - VIR_CONNECT_LIST_DOMAINS_PERSISTENT = 1 << 2, - VIR_CONNECT_LIST_DOMAINS_TRANSIENT = 1 << 3, + VIR_CONNECT_LIST_DOMAINS_PERSISTENT = 1 << 2, /* (Since: v0.9.13) */ + VIR_CONNECT_LIST_DOMAINS_TRANSIENT = 1 << 3, /* (Since: v0.9.13) */ - VIR_CONNECT_LIST_DOMAINS_RUNNING = 1 << 4, - VIR_CONNECT_LIST_DOMAINS_PAUSED = 1 << 5, - VIR_CONNECT_LIST_DOMAINS_SHUTOFF = 1 << 6, - VIR_CONNECT_LIST_DOMAINS_OTHER = 1 << 7, + VIR_CONNECT_LIST_DOMAINS_RUNNING = 1 << 4, /* (Since: v0.9.13) */ + VIR_CONNECT_LIST_DOMAINS_PAUSED = 1 << 5, /* (Since: v0.9.13) */ + VIR_CONNECT_LIST_DOMAINS_SHUTOFF = 1 << 6, /* (Since: v0.9.13) */ + VIR_CONNECT_LIST_DOMAINS_OTHER = 1 << 7, /* (Since: v0.9.13) */ - VIR_CONNECT_LIST_DOMAINS_MANAGEDSAVE = 1 << 8, - VIR_CONNECT_LIST_DOMAINS_NO_MANAGEDSAVE = 1 << 9, + VIR_CONNECT_LIST_DOMAINS_MANAGEDSAVE = 1 << 8, /* (Since: v0.9.13) */ + VIR_CONNECT_LIST_DOMAINS_NO_MANAGEDSAVE = 1 << 9, /* (Since: v0.9.13) */ - VIR_CONNECT_LIST_DOMAINS_AUTOSTART = 1 << 10, - VIR_CONNECT_LIST_DOMAINS_NO_AUTOSTART = 1 << 11, + VIR_CONNECT_LIST_DOMAINS_AUTOSTART = 1 << 10, /* (Since: v0.9.13) */ + VIR_CONNECT_LIST_DOMAINS_NO_AUTOSTART = 1 << 11, /* (Since: v0.9.13) */ - VIR_CONNECT_LIST_DOMAINS_HAS_SNAPSHOT = 1 << 12, - VIR_CONNECT_LIST_DOMAINS_NO_SNAPSHOT = 1 << 13, + VIR_CONNECT_LIST_DOMAINS_HAS_SNAPSHOT = 1 << 12, /* (Since: v0.9.13) */ + VIR_CONNECT_LIST_DOMAINS_NO_SNAPSHOT = 1 << 13, /* (Since: v0.9.13) */ - VIR_CONNECT_LIST_DOMAINS_HAS_CHECKPOINT = 1 << 14, - VIR_CONNECT_LIST_DOMAINS_NO_CHECKPOINT = 1 << 15, + VIR_CONNECT_LIST_DOMAINS_HAS_CHECKPOINT = 1 << 14, /* (Since: v5.6.0) */ + VIR_CONNECT_LIST_DOMAINS_NO_CHECKPOINT = 1 << 15, /* (Since: v5.6.0) */ } virConnectListAllDomainsFlags; int virConnectListAllDomains (virConnectPtr conn, @@ -1916,18 +2017,18 @@ int virDomainSetAutostart (virDomainPtr domain, */ typedef enum { - VIR_VCPU_OFFLINE = 0, /* the virtual CPU is offline */ - VIR_VCPU_RUNNING = 1, /* the virtual CPU is running */ - VIR_VCPU_BLOCKED = 2, /* the virtual CPU is blocked on resource */ + VIR_VCPU_OFFLINE = 0, /* the virtual CPU is offline (Since: v0.1.4) */ + VIR_VCPU_RUNNING = 1, /* the virtual CPU is running (Since: v0.1.4) */ + VIR_VCPU_BLOCKED = 2, /* the virtual CPU is blocked on resource (Since: v0.1.4) */ # ifdef VIR_ENUM_SENTINELS - VIR_VCPU_LAST + VIR_VCPU_LAST /* (Since: v0.9.10) */ # endif } virVcpuState; typedef enum { - VIR_VCPU_INFO_CPU_OFFLINE = -1, /* the vCPU is offline */ - VIR_VCPU_INFO_CPU_UNAVAILABLE = -2, /* the hypervisor does not expose real CPU information */ + VIR_VCPU_INFO_CPU_OFFLINE = -1, /* the vCPU is offline (Since: v6.10.0) */ + VIR_VCPU_INFO_CPU_UNAVAILABLE = -2, /* the hypervisor does not expose real CPU information (Since: v6.10.0) */ } virVcpuHostCpuState; typedef struct _virVcpuInfo virVcpuInfo; @@ -1941,14 +2042,14 @@ typedef virVcpuInfo *virVcpuInfoPtr; /* Flags for controlling virtual CPU hot-plugging. */ typedef enum { - /* See virDomainModificationImpact for these flags. */ + /* See virDomainModificationImpact for these flags. (Since: v1.0.0) */ VIR_DOMAIN_VCPU_CURRENT = VIR_DOMAIN_AFFECT_CURRENT, VIR_DOMAIN_VCPU_LIVE = VIR_DOMAIN_AFFECT_LIVE, VIR_DOMAIN_VCPU_CONFIG = VIR_DOMAIN_AFFECT_CONFIG, - /* Additionally, these flags may be bitwise-OR'd in. */ - VIR_DOMAIN_VCPU_MAXIMUM = (1 << 2), /* Max rather than current count */ - VIR_DOMAIN_VCPU_GUEST = (1 << 3), /* Modify state of the cpu in the guest */ + /* Additionally, these flags may be bitwise-OR'd in. (Since: v1.0.0) */ + VIR_DOMAIN_VCPU_MAXIMUM = (1 << 2), /* Max rather than current count (Since: v1.1.0) */ + VIR_DOMAIN_VCPU_GUEST = (1 << 3), /* Modify state of the cpu in the guest (Since: v2.4.0) */ VIR_DOMAIN_VCPU_HOTPLUGGABLE = (1 << 4), /* Make vcpus added hot(un)pluggable */ } virDomainVcpuFlags; @@ -2159,12 +2260,12 @@ int virDomainGetVcpus (virDomainPtr domain, typedef enum { - /* See virDomainModificationImpact for these flags. */ + /* See virDomainModificationImpact for these flags. (Since: v1.0.0) */ VIR_DOMAIN_DEVICE_MODIFY_CURRENT = VIR_DOMAIN_AFFECT_CURRENT, VIR_DOMAIN_DEVICE_MODIFY_LIVE = VIR_DOMAIN_AFFECT_LIVE, VIR_DOMAIN_DEVICE_MODIFY_CONFIG = VIR_DOMAIN_AFFECT_CONFIG, - /* Additionally, these flags may be bitwise-OR'd in. */ + /* Additionally, these flags may be bitwise-OR'd in. (Since: v1.0.0) */ VIR_DOMAIN_DEVICE_MODIFY_FORCE = (1 << 2), /* Forcibly modify device (ex. force eject a cdrom) */ } virDomainDeviceModifyFlags; @@ -2191,34 +2292,34 @@ struct _virDomainStatsRecord { }; typedef enum { - VIR_DOMAIN_STATS_STATE = (1 << 0), /* return domain state */ - VIR_DOMAIN_STATS_CPU_TOTAL = (1 << 1), /* return domain CPU info */ - VIR_DOMAIN_STATS_BALLOON = (1 << 2), /* return domain balloon info */ - VIR_DOMAIN_STATS_VCPU = (1 << 3), /* return domain virtual CPU info */ - VIR_DOMAIN_STATS_INTERFACE = (1 << 4), /* return domain interfaces info */ - VIR_DOMAIN_STATS_BLOCK = (1 << 5), /* return domain block info */ - VIR_DOMAIN_STATS_PERF = (1 << 6), /* return domain perf event info */ - VIR_DOMAIN_STATS_IOTHREAD = (1 << 7), /* return iothread poll info */ - VIR_DOMAIN_STATS_MEMORY = (1 << 8), /* return domain memory info */ - VIR_DOMAIN_STATS_DIRTYRATE = (1 << 9), /* return domain dirty rate info */ + VIR_DOMAIN_STATS_STATE = (1 << 0), /* return domain state (Since: v1.2.8) */ + VIR_DOMAIN_STATS_CPU_TOTAL = (1 << 1), /* return domain CPU info (Since: v1.2.9) */ + VIR_DOMAIN_STATS_BALLOON = (1 << 2), /* return domain balloon info (Since: v1.2.9) */ + VIR_DOMAIN_STATS_VCPU = (1 << 3), /* return domain virtual CPU info (Since: v1.2.9) */ + VIR_DOMAIN_STATS_INTERFACE = (1 << 4), /* return domain interfaces info (Since: v1.2.9) */ + VIR_DOMAIN_STATS_BLOCK = (1 << 5), /* return domain block info (Since: v1.2.9) */ + VIR_DOMAIN_STATS_PERF = (1 << 6), /* return domain perf event info (Since: v1.3.3) */ + VIR_DOMAIN_STATS_IOTHREAD = (1 << 7), /* return iothread poll info (Since: v4.10.0) */ + VIR_DOMAIN_STATS_MEMORY = (1 << 8), /* return domain memory info (Since: v6.0.0) */ + VIR_DOMAIN_STATS_DIRTYRATE = (1 << 9), /* return domain dirty rate info (Since: v7.2.0) */ } virDomainStatsTypes; typedef enum { - VIR_CONNECT_GET_ALL_DOMAINS_STATS_ACTIVE = VIR_CONNECT_LIST_DOMAINS_ACTIVE, - VIR_CONNECT_GET_ALL_DOMAINS_STATS_INACTIVE = VIR_CONNECT_LIST_DOMAINS_INACTIVE, + VIR_CONNECT_GET_ALL_DOMAINS_STATS_ACTIVE = VIR_CONNECT_LIST_DOMAINS_ACTIVE, /* (Since: v1.2.8) */ + VIR_CONNECT_GET_ALL_DOMAINS_STATS_INACTIVE = VIR_CONNECT_LIST_DOMAINS_INACTIVE, /* (Since: v1.2.8) */ - VIR_CONNECT_GET_ALL_DOMAINS_STATS_PERSISTENT = VIR_CONNECT_LIST_DOMAINS_PERSISTENT, - VIR_CONNECT_GET_ALL_DOMAINS_STATS_TRANSIENT = VIR_CONNECT_LIST_DOMAINS_TRANSIENT, + VIR_CONNECT_GET_ALL_DOMAINS_STATS_PERSISTENT = VIR_CONNECT_LIST_DOMAINS_PERSISTENT, /* (Since: v1.2.8) */ + VIR_CONNECT_GET_ALL_DOMAINS_STATS_TRANSIENT = VIR_CONNECT_LIST_DOMAINS_TRANSIENT, /* (Since: v1.2.8) */ - VIR_CONNECT_GET_ALL_DOMAINS_STATS_RUNNING = VIR_CONNECT_LIST_DOMAINS_RUNNING, - VIR_CONNECT_GET_ALL_DOMAINS_STATS_PAUSED = VIR_CONNECT_LIST_DOMAINS_PAUSED, - VIR_CONNECT_GET_ALL_DOMAINS_STATS_SHUTOFF = VIR_CONNECT_LIST_DOMAINS_SHUTOFF, - VIR_CONNECT_GET_ALL_DOMAINS_STATS_OTHER = VIR_CONNECT_LIST_DOMAINS_OTHER, + VIR_CONNECT_GET_ALL_DOMAINS_STATS_RUNNING = VIR_CONNECT_LIST_DOMAINS_RUNNING, /* (Since: v1.2.8) */ + VIR_CONNECT_GET_ALL_DOMAINS_STATS_PAUSED = VIR_CONNECT_LIST_DOMAINS_PAUSED, /* (Since: v1.2.8) */ + VIR_CONNECT_GET_ALL_DOMAINS_STATS_SHUTOFF = VIR_CONNECT_LIST_DOMAINS_SHUTOFF, /* (Since: v1.2.8) */ + VIR_CONNECT_GET_ALL_DOMAINS_STATS_OTHER = VIR_CONNECT_LIST_DOMAINS_OTHER, /* (Since: v1.2.8) */ VIR_CONNECT_GET_ALL_DOMAINS_STATS_NOWAIT = 1 << 29, /* report statistics that can be obtained - immediately without any blocking */ - VIR_CONNECT_GET_ALL_DOMAINS_STATS_BACKING = 1 << 30, /* include backing chain for block stats */ - VIR_CONNECT_GET_ALL_DOMAINS_STATS_ENFORCE_STATS = 1U << 31, /* enforce requested stats */ + immediately without any blocking (Since: v4.5.0) */ + VIR_CONNECT_GET_ALL_DOMAINS_STATS_BACKING = 1 << 30, /* include backing chain for block stats (Since: v1.2.12) */ + VIR_CONNECT_GET_ALL_DOMAINS_STATS_ENFORCE_STATS = 1U << 31, /* enforce requested stats (Since: v1.2.8) */ } virConnectGetAllDomainStatsFlags; int virConnectGetAllDomainStats(virConnectPtr conn, @@ -2482,30 +2583,45 @@ int virDomainSetPerfEvents(virDomainPtr dom, * Describes various possible block jobs. */ typedef enum { - /* Placeholder */ + /* Placeholder (Since: v0.9.4) */ VIR_DOMAIN_BLOCK_JOB_TYPE_UNKNOWN = 0, /* Block Pull (virDomainBlockPull, or virDomainBlockRebase without - * flags), job ends on completion */ + * flags), job ends on completion + * + * Since: v0.9.4 + */ VIR_DOMAIN_BLOCK_JOB_TYPE_PULL = 1, /* Block Copy (virDomainBlockCopy, or virDomainBlockRebase with - * flags), job exists as long as mirroring is active */ + * flags), job exists as long as mirroring is active + * + * Since: v0.9.12 + */ VIR_DOMAIN_BLOCK_JOB_TYPE_COPY = 2, /* Block Commit (virDomainBlockCommit without flags), job ends on - * completion */ + * completion + * + * Since: v0.10.2 + */ VIR_DOMAIN_BLOCK_JOB_TYPE_COMMIT = 3, /* Active Block Commit (virDomainBlockCommit with flags), job - * exists as long as sync is active */ + * exists as long as sync is active + * + * Since: v1.2.6 + */ VIR_DOMAIN_BLOCK_JOB_TYPE_ACTIVE_COMMIT = 4, - /* Backup (virDomainBackupBegin) */ + /* Backup (virDomainBackupBegin) + * + * Since: v6.0.0 + */ VIR_DOMAIN_BLOCK_JOB_TYPE_BACKUP = 5, # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_BLOCK_JOB_TYPE_LAST + VIR_DOMAIN_BLOCK_JOB_TYPE_LAST /* (Since: v0.9.10) */ # endif } virDomainBlockJobType; @@ -2517,8 +2633,8 @@ typedef enum { * active commit job */ typedef enum { - VIR_DOMAIN_BLOCK_JOB_ABORT_ASYNC = 1 << 0, - VIR_DOMAIN_BLOCK_JOB_ABORT_PIVOT = 1 << 1, + VIR_DOMAIN_BLOCK_JOB_ABORT_ASYNC = 1 << 0, /* (Since: v0.9.12) */ + VIR_DOMAIN_BLOCK_JOB_ABORT_PIVOT = 1 << 1, /* (Since: v0.9.12) */ } virDomainBlockJobAbortFlags; int virDomainBlockJobAbort(virDomainPtr dom, const char *disk, @@ -2527,7 +2643,7 @@ int virDomainBlockJobAbort(virDomainPtr dom, const char *disk, /* Flags for use with virDomainGetBlockJobInfo */ typedef enum { VIR_DOMAIN_BLOCK_JOB_INFO_BANDWIDTH_BYTES = 1 << 0, /* bandwidth in bytes/s - instead of MiB/s */ + instead of MiB/s (Since: v1.2.9) */ } virDomainBlockJobInfoFlags; /* An iterator for monitoring block job operations */ @@ -2556,7 +2672,7 @@ int virDomainGetBlockJobInfo(virDomainPtr dom, const char *disk, /* Flags for use with virDomainBlockJobSetSpeed */ typedef enum { VIR_DOMAIN_BLOCK_JOB_SPEED_BANDWIDTH_BYTES = 1 << 0, /* bandwidth in bytes/s - instead of MiB/s */ + instead of MiB/s (Since: v1.2.9) */ } virDomainBlockJobSetSpeedFlags; int virDomainBlockJobSetSpeed(virDomainPtr dom, const char *disk, @@ -2566,7 +2682,7 @@ int virDomainBlockJobSetSpeed(virDomainPtr dom, const char *disk, * of the flags for virDomainBlockRebase) */ typedef enum { VIR_DOMAIN_BLOCK_PULL_BANDWIDTH_BYTES = 1 << 6, /* bandwidth in bytes/s - instead of MiB/s */ + instead of MiB/s (Since: v1.2.9) */ } virDomainBlockPullFlags; int virDomainBlockPull(virDomainPtr dom, const char *disk, @@ -2579,18 +2695,18 @@ int virDomainBlockPull(virDomainPtr dom, const char *disk, */ typedef enum { VIR_DOMAIN_BLOCK_REBASE_SHALLOW = 1 << 0, /* Limit copy to top of source - backing chain */ + backing chain (Since: v0.9.12) */ VIR_DOMAIN_BLOCK_REBASE_REUSE_EXT = 1 << 1, /* Reuse existing external - file for a copy */ - VIR_DOMAIN_BLOCK_REBASE_COPY_RAW = 1 << 2, /* Make destination file raw */ - VIR_DOMAIN_BLOCK_REBASE_COPY = 1 << 3, /* Start a copy job */ + file for a copy (Since: v0.9.12) */ + VIR_DOMAIN_BLOCK_REBASE_COPY_RAW = 1 << 2, /* Make destination file raw (Since: v0.9.12) */ + VIR_DOMAIN_BLOCK_REBASE_COPY = 1 << 3, /* Start a copy job (Since: v0.9.12) */ VIR_DOMAIN_BLOCK_REBASE_RELATIVE = 1 << 4, /* Keep backing chain referenced using relative - names */ + names (Since: v1.2.7) */ VIR_DOMAIN_BLOCK_REBASE_COPY_DEV = 1 << 5, /* Treat destination as block - device instead of file */ + device instead of file (Since: v1.2.9) */ VIR_DOMAIN_BLOCK_REBASE_BANDWIDTH_BYTES = 1 << 6, /* bandwidth in bytes/s - instead of MiB/s */ + instead of MiB/s (Since: v1.2.9) */ } virDomainBlockRebaseFlags; int virDomainBlockRebase(virDomainPtr dom, const char *disk, @@ -2603,17 +2719,20 @@ int virDomainBlockRebase(virDomainPtr dom, const char *disk, * Flags available for virDomainBlockCopy(). */ typedef enum { - /* Limit copy to top of source backing chain */ + /* Limit copy to top of source backing chain (Since: v1.2.8) */ VIR_DOMAIN_BLOCK_COPY_SHALLOW = 1 << 0, - /* Reuse existing external file for a copy */ + /* Reuse existing external file for a copy (Since: v1.2.8) */ VIR_DOMAIN_BLOCK_COPY_REUSE_EXT = 1 << 1, - /* Don't force usage of recoverable job for the copy operation */ + /* Don't force usage of recoverable job for the copy operation (Since: v3.5.0) */ VIR_DOMAIN_BLOCK_COPY_TRANSIENT_JOB = 1 << 2, /* Force the copy job to synchronously propagate guest writes into - * the destination image, so that the copy is guaranteed to converge */ + * the destination image, so that the copy is guaranteed to converge + * + * Since: v8.0.0 + */ VIR_DOMAIN_BLOCK_COPY_SYNCHRONOUS_WRITES = 1 << 3, } virDomainBlockCopyFlags; @@ -2669,17 +2788,17 @@ int virDomainBlockCopy(virDomainPtr dom, const char *disk, */ typedef enum { VIR_DOMAIN_BLOCK_COMMIT_SHALLOW = 1 << 0, /* NULL base means next backing - file, not whole chain */ + file, not whole chain (Since: v0.10.2) */ VIR_DOMAIN_BLOCK_COMMIT_DELETE = 1 << 1, /* Delete any files that are now invalid after their contents - have been committed */ + have been committed (Since: v0.10.2) */ VIR_DOMAIN_BLOCK_COMMIT_ACTIVE = 1 << 2, /* Allow a two-phase commit when - top is the active layer */ + top is the active layer (Since: v1.2.6) */ VIR_DOMAIN_BLOCK_COMMIT_RELATIVE = 1 << 3, /* keep the backing chain referenced using relative - names */ + names (Since: v1.2.7) */ VIR_DOMAIN_BLOCK_COMMIT_BANDWIDTH_BYTES = 1 << 4, /* bandwidth in bytes/s - instead of MiB/s */ + instead of MiB/s (Since: v1.2.9) */ } virDomainBlockCommitFlags; int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, @@ -2864,12 +2983,12 @@ virDomainGetBlockIoTune(virDomainPtr dom, * Disk I/O error. */ typedef enum { - VIR_DOMAIN_DISK_ERROR_NONE = 0, /* no error */ - VIR_DOMAIN_DISK_ERROR_UNSPEC = 1, /* unspecified I/O error */ - VIR_DOMAIN_DISK_ERROR_NO_SPACE = 2, /* no space left on the device */ + VIR_DOMAIN_DISK_ERROR_NONE = 0, /* no error (Since: v0.9.10) */ + VIR_DOMAIN_DISK_ERROR_UNSPEC = 1, /* unspecified I/O error (Since: v0.9.10) */ + VIR_DOMAIN_DISK_ERROR_NO_SPACE = 2, /* no space left on the device (Since: v0.9.10) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_DISK_ERROR_LAST + VIR_DOMAIN_DISK_ERROR_LAST /* (Since: v0.9.10) */ # endif } virDomainDiskErrorCode; @@ -2898,16 +3017,16 @@ int virDomainGetDiskErrors(virDomainPtr dom, * Enum to specify which keycode mapping is in use for virDomainSendKey(). */ typedef enum { - VIR_KEYCODE_SET_LINUX = 0, - VIR_KEYCODE_SET_XT = 1, - VIR_KEYCODE_SET_ATSET1 = 2, - VIR_KEYCODE_SET_ATSET2 = 3, - VIR_KEYCODE_SET_ATSET3 = 4, - VIR_KEYCODE_SET_OSX = 5, - VIR_KEYCODE_SET_XT_KBD = 6, - VIR_KEYCODE_SET_USB = 7, - VIR_KEYCODE_SET_WIN32 = 8, - VIR_KEYCODE_SET_QNUM = 9, + VIR_KEYCODE_SET_LINUX = 0, /* (Since: v0.9.3) */ + VIR_KEYCODE_SET_XT = 1, /* (Since: v0.9.3) */ + VIR_KEYCODE_SET_ATSET1 = 2, /* (Since: v0.9.3) */ + VIR_KEYCODE_SET_ATSET2 = 3, /* (Since: v0.9.3) */ + VIR_KEYCODE_SET_ATSET3 = 4, /* (Since: v0.9.3) */ + VIR_KEYCODE_SET_OSX = 5, /* (Since: v0.9.4) */ + VIR_KEYCODE_SET_XT_KBD = 6, /* (Since: v0.9.4) */ + VIR_KEYCODE_SET_USB = 7, /* (Since: v0.9.4) */ + VIR_KEYCODE_SET_WIN32 = 8, /* (Since: v0.9.4) */ + VIR_KEYCODE_SET_QNUM = 9, /* (Since: v4.2.0) */ # ifdef VIR_ENUM_SENTINELS VIR_KEYCODE_SET_LAST @@ -2915,6 +3034,8 @@ typedef enum { * NB: this enum value will increase over time as new keycode sets are * added to the libvirt API. It reflects the last keycode set supported * by this version of the libvirt API. + * + * Since: v0.9.4 */ # endif } virKeycodeSet; @@ -2951,80 +3072,80 @@ int virDomainSendKey(virDomainPtr domain, * mapping in Linux. */ typedef enum { - VIR_DOMAIN_PROCESS_SIGNAL_NOP = 0, /* No constant in POSIX/Linux */ - VIR_DOMAIN_PROCESS_SIGNAL_HUP = 1, /* SIGHUP */ - VIR_DOMAIN_PROCESS_SIGNAL_INT = 2, /* SIGINT */ - VIR_DOMAIN_PROCESS_SIGNAL_QUIT = 3, /* SIGQUIT */ - VIR_DOMAIN_PROCESS_SIGNAL_ILL = 4, /* SIGILL */ - VIR_DOMAIN_PROCESS_SIGNAL_TRAP = 5, /* SIGTRAP */ - VIR_DOMAIN_PROCESS_SIGNAL_ABRT = 6, /* SIGABRT */ - VIR_DOMAIN_PROCESS_SIGNAL_BUS = 7, /* SIGBUS */ - VIR_DOMAIN_PROCESS_SIGNAL_FPE = 8, /* SIGFPE */ - VIR_DOMAIN_PROCESS_SIGNAL_KILL = 9, /* SIGKILL */ - - VIR_DOMAIN_PROCESS_SIGNAL_USR1 = 10, /* SIGUSR1 */ - VIR_DOMAIN_PROCESS_SIGNAL_SEGV = 11, /* SIGSEGV */ - VIR_DOMAIN_PROCESS_SIGNAL_USR2 = 12, /* SIGUSR2 */ - VIR_DOMAIN_PROCESS_SIGNAL_PIPE = 13, /* SIGPIPE */ - VIR_DOMAIN_PROCESS_SIGNAL_ALRM = 14, /* SIGALRM */ - VIR_DOMAIN_PROCESS_SIGNAL_TERM = 15, /* SIGTERM */ - VIR_DOMAIN_PROCESS_SIGNAL_STKFLT = 16, /* Not in POSIX (SIGSTKFLT on Linux )*/ - VIR_DOMAIN_PROCESS_SIGNAL_CHLD = 17, /* SIGCHLD */ - VIR_DOMAIN_PROCESS_SIGNAL_CONT = 18, /* SIGCONT */ - VIR_DOMAIN_PROCESS_SIGNAL_STOP = 19, /* SIGSTOP */ - - VIR_DOMAIN_PROCESS_SIGNAL_TSTP = 20, /* SIGTSTP */ - VIR_DOMAIN_PROCESS_SIGNAL_TTIN = 21, /* SIGTTIN */ - VIR_DOMAIN_PROCESS_SIGNAL_TTOU = 22, /* SIGTTOU */ - VIR_DOMAIN_PROCESS_SIGNAL_URG = 23, /* SIGURG */ - VIR_DOMAIN_PROCESS_SIGNAL_XCPU = 24, /* SIGXCPU */ - VIR_DOMAIN_PROCESS_SIGNAL_XFSZ = 25, /* SIGXFSZ */ - VIR_DOMAIN_PROCESS_SIGNAL_VTALRM = 26, /* SIGVTALRM */ - VIR_DOMAIN_PROCESS_SIGNAL_PROF = 27, /* SIGPROF */ - VIR_DOMAIN_PROCESS_SIGNAL_WINCH = 28, /* Not in POSIX (SIGWINCH on Linux) */ - VIR_DOMAIN_PROCESS_SIGNAL_POLL = 29, /* SIGPOLL (also known as SIGIO on Linux) */ - - VIR_DOMAIN_PROCESS_SIGNAL_PWR = 30, /* Not in POSIX (SIGPWR on Linux) */ - VIR_DOMAIN_PROCESS_SIGNAL_SYS = 31, /* SIGSYS (also known as SIGUNUSED on Linux) */ - VIR_DOMAIN_PROCESS_SIGNAL_RT0 = 32, /* SIGRTMIN */ - VIR_DOMAIN_PROCESS_SIGNAL_RT1 = 33, /* SIGRTMIN + 1 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT2 = 34, /* SIGRTMIN + 2 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT3 = 35, /* SIGRTMIN + 3 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT4 = 36, /* SIGRTMIN + 4 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT5 = 37, /* SIGRTMIN + 5 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT6 = 38, /* SIGRTMIN + 6 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT7 = 39, /* SIGRTMIN + 7 */ - - VIR_DOMAIN_PROCESS_SIGNAL_RT8 = 40, /* SIGRTMIN + 8 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT9 = 41, /* SIGRTMIN + 9 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT10 = 42, /* SIGRTMIN + 10 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT11 = 43, /* SIGRTMIN + 11 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT12 = 44, /* SIGRTMIN + 12 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT13 = 45, /* SIGRTMIN + 13 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT14 = 46, /* SIGRTMIN + 14 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT15 = 47, /* SIGRTMIN + 15 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT16 = 48, /* SIGRTMIN + 16 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT17 = 49, /* SIGRTMIN + 17 */ - - VIR_DOMAIN_PROCESS_SIGNAL_RT18 = 50, /* SIGRTMIN + 18 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT19 = 51, /* SIGRTMIN + 19 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT20 = 52, /* SIGRTMIN + 20 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT21 = 53, /* SIGRTMIN + 21 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT22 = 54, /* SIGRTMIN + 22 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT23 = 55, /* SIGRTMIN + 23 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT24 = 56, /* SIGRTMIN + 24 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT25 = 57, /* SIGRTMIN + 25 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT26 = 58, /* SIGRTMIN + 26 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT27 = 59, /* SIGRTMIN + 27 */ - - VIR_DOMAIN_PROCESS_SIGNAL_RT28 = 60, /* SIGRTMIN + 28 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT29 = 61, /* SIGRTMIN + 29 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT30 = 62, /* SIGRTMIN + 30 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT31 = 63, /* SIGRTMIN + 31 */ - VIR_DOMAIN_PROCESS_SIGNAL_RT32 = 64, /* SIGRTMIN + 32 / SIGRTMAX */ + VIR_DOMAIN_PROCESS_SIGNAL_NOP = 0, /* No constant in POSIX/Linux (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_HUP = 1, /* SIGHUP (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_INT = 2, /* SIGINT (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_QUIT = 3, /* SIGQUIT (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_ILL = 4, /* SIGILL (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_TRAP = 5, /* SIGTRAP (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_ABRT = 6, /* SIGABRT (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_BUS = 7, /* SIGBUS (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_FPE = 8, /* SIGFPE (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_KILL = 9, /* SIGKILL (Since: v1.0.1) */ + + VIR_DOMAIN_PROCESS_SIGNAL_USR1 = 10, /* SIGUSR1 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_SEGV = 11, /* SIGSEGV (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_USR2 = 12, /* SIGUSR2 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_PIPE = 13, /* SIGPIPE (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_ALRM = 14, /* SIGALRM (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_TERM = 15, /* SIGTERM (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_STKFLT = 16, /* Not in POSIX (SIGSTKFLT on Linux (Since: v1.0.1) )*/ + VIR_DOMAIN_PROCESS_SIGNAL_CHLD = 17, /* SIGCHLD (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_CONT = 18, /* SIGCONT (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_STOP = 19, /* SIGSTOP (Since: v1.0.1) */ + + VIR_DOMAIN_PROCESS_SIGNAL_TSTP = 20, /* SIGTSTP (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_TTIN = 21, /* SIGTTIN (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_TTOU = 22, /* SIGTTOU (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_URG = 23, /* SIGURG (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_XCPU = 24, /* SIGXCPU (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_XFSZ = 25, /* SIGXFSZ (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_VTALRM = 26, /* SIGVTALRM (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_PROF = 27, /* SIGPROF (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_WINCH = 28, /* Not in POSIX (SIGWINCH on Linux) (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_POLL = 29, /* SIGPOLL (also known as SIGIO on Linux) (Since: v1.0.1) */ + + VIR_DOMAIN_PROCESS_SIGNAL_PWR = 30, /* Not in POSIX (SIGPWR on Linux) (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_SYS = 31, /* SIGSYS (also known as SIGUNUSED on Linux) (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT0 = 32, /* SIGRTMIN (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT1 = 33, /* SIGRTMIN + 1 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT2 = 34, /* SIGRTMIN + 2 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT3 = 35, /* SIGRTMIN + 3 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT4 = 36, /* SIGRTMIN + 4 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT5 = 37, /* SIGRTMIN + 5 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT6 = 38, /* SIGRTMIN + 6 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT7 = 39, /* SIGRTMIN + 7 (Since: v1.0.1) */ + + VIR_DOMAIN_PROCESS_SIGNAL_RT8 = 40, /* SIGRTMIN + 8 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT9 = 41, /* SIGRTMIN + 9 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT10 = 42, /* SIGRTMIN + 10 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT11 = 43, /* SIGRTMIN + 11 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT12 = 44, /* SIGRTMIN + 12 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT13 = 45, /* SIGRTMIN + 13 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT14 = 46, /* SIGRTMIN + 14 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT15 = 47, /* SIGRTMIN + 15 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT16 = 48, /* SIGRTMIN + 16 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT17 = 49, /* SIGRTMIN + 17 (Since: v1.0.1) */ + + VIR_DOMAIN_PROCESS_SIGNAL_RT18 = 50, /* SIGRTMIN + 18 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT19 = 51, /* SIGRTMIN + 19 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT20 = 52, /* SIGRTMIN + 20 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT21 = 53, /* SIGRTMIN + 21 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT22 = 54, /* SIGRTMIN + 22 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT23 = 55, /* SIGRTMIN + 23 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT24 = 56, /* SIGRTMIN + 24 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT25 = 57, /* SIGRTMIN + 25 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT26 = 58, /* SIGRTMIN + 26 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT27 = 59, /* SIGRTMIN + 27 (Since: v1.0.1) */ + + VIR_DOMAIN_PROCESS_SIGNAL_RT28 = 60, /* SIGRTMIN + 28 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT29 = 61, /* SIGRTMIN + 29 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT30 = 62, /* SIGRTMIN + 30 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT31 = 63, /* SIGRTMIN + 31 (Since: v1.0.1) */ + VIR_DOMAIN_PROCESS_SIGNAL_RT32 = 64, /* SIGRTMIN + 32 / SIGRTMAX (Since: v1.0.1) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_PROCESS_SIGNAL_LAST + VIR_DOMAIN_PROCESS_SIGNAL_LAST /* (Since: v1.0.1) */ # endif } virDomainProcessSignal; @@ -3051,18 +3172,18 @@ virDomainPtr virDomainCreateLinux (virConnectPtr conn, * a virDomainEventType is emitted during domain lifecycle events */ typedef enum { - VIR_DOMAIN_EVENT_DEFINED = 0, - VIR_DOMAIN_EVENT_UNDEFINED = 1, - VIR_DOMAIN_EVENT_STARTED = 2, - VIR_DOMAIN_EVENT_SUSPENDED = 3, - VIR_DOMAIN_EVENT_RESUMED = 4, - VIR_DOMAIN_EVENT_STOPPED = 5, - VIR_DOMAIN_EVENT_SHUTDOWN = 6, - VIR_DOMAIN_EVENT_PMSUSPENDED = 7, - VIR_DOMAIN_EVENT_CRASHED = 8, + VIR_DOMAIN_EVENT_DEFINED = 0, /* (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_UNDEFINED = 1, /* (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_STARTED = 2, /* (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_SUSPENDED = 3, /* (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_RESUMED = 4, /* (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_STOPPED = 5, /* (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_SHUTDOWN = 6, /* (Since: v0.9.8) */ + VIR_DOMAIN_EVENT_PMSUSPENDED = 7, /* (Since: v0.10.2) */ + VIR_DOMAIN_EVENT_CRASHED = 8, /* (Since: v1.1.1) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_LAST + VIR_DOMAIN_EVENT_LAST /* (Since: v0.9.10) */ # endif } virDomainEventType; @@ -3072,13 +3193,13 @@ typedef enum { * Details on the cause of a 'defined' lifecycle event */ typedef enum { - VIR_DOMAIN_EVENT_DEFINED_ADDED = 0, /* Newly created config file */ - VIR_DOMAIN_EVENT_DEFINED_UPDATED = 1, /* Changed config file */ - VIR_DOMAIN_EVENT_DEFINED_RENAMED = 2, /* Domain was renamed */ - VIR_DOMAIN_EVENT_DEFINED_FROM_SNAPSHOT = 3, /* Config was restored from a snapshot */ + VIR_DOMAIN_EVENT_DEFINED_ADDED = 0, /* Newly created config file (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_DEFINED_UPDATED = 1, /* Changed config file (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_DEFINED_RENAMED = 2, /* Domain was renamed (Since: v1.2.19) */ + VIR_DOMAIN_EVENT_DEFINED_FROM_SNAPSHOT = 3, /* Config was restored from a snapshot (Since: v1.3.3) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_DEFINED_LAST + VIR_DOMAIN_EVENT_DEFINED_LAST /* (Since: v0.9.10) */ # endif } virDomainEventDefinedDetailType; @@ -3088,11 +3209,11 @@ typedef enum { * Details on the cause of an 'undefined' lifecycle event */ typedef enum { - VIR_DOMAIN_EVENT_UNDEFINED_REMOVED = 0, /* Deleted the config file */ - VIR_DOMAIN_EVENT_UNDEFINED_RENAMED = 1, /* Domain was renamed */ + VIR_DOMAIN_EVENT_UNDEFINED_REMOVED = 0, /* Deleted the config file (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_UNDEFINED_RENAMED = 1, /* Domain was renamed (Since: v1.2.19) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_UNDEFINED_LAST + VIR_DOMAIN_EVENT_UNDEFINED_LAST /* (Since: v0.9.10) */ # endif } virDomainEventUndefinedDetailType; @@ -3102,14 +3223,14 @@ typedef enum { * Details on the cause of a 'started' lifecycle event */ typedef enum { - VIR_DOMAIN_EVENT_STARTED_BOOTED = 0, /* Normal startup from boot */ - VIR_DOMAIN_EVENT_STARTED_MIGRATED = 1, /* Incoming migration from another host */ - VIR_DOMAIN_EVENT_STARTED_RESTORED = 2, /* Restored from a state file */ - VIR_DOMAIN_EVENT_STARTED_FROM_SNAPSHOT = 3, /* Restored from snapshot */ - VIR_DOMAIN_EVENT_STARTED_WAKEUP = 4, /* Started due to wakeup event */ + VIR_DOMAIN_EVENT_STARTED_BOOTED = 0, /* Normal startup from boot (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_STARTED_MIGRATED = 1, /* Incoming migration from another host (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_STARTED_RESTORED = 2, /* Restored from a state file (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_STARTED_FROM_SNAPSHOT = 3, /* Restored from snapshot (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_STARTED_WAKEUP = 4, /* Started due to wakeup event (Since: v0.9.11) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_STARTED_LAST + VIR_DOMAIN_EVENT_STARTED_LAST /* (Since: v0.9.10) */ # endif } virDomainEventStartedDetailType; @@ -3119,18 +3240,18 @@ typedef enum { * Details on the cause of a 'suspended' lifecycle event */ typedef enum { - VIR_DOMAIN_EVENT_SUSPENDED_PAUSED = 0, /* Normal suspend due to admin pause */ - VIR_DOMAIN_EVENT_SUSPENDED_MIGRATED = 1, /* Suspended for offline migration */ - VIR_DOMAIN_EVENT_SUSPENDED_IOERROR = 2, /* Suspended due to a disk I/O error */ - VIR_DOMAIN_EVENT_SUSPENDED_WATCHDOG = 3, /* Suspended due to a watchdog firing */ - VIR_DOMAIN_EVENT_SUSPENDED_RESTORED = 4, /* Restored from paused state file */ - VIR_DOMAIN_EVENT_SUSPENDED_FROM_SNAPSHOT = 5, /* Restored from paused snapshot */ - VIR_DOMAIN_EVENT_SUSPENDED_API_ERROR = 6, /* suspended after failure during libvirt API call */ - VIR_DOMAIN_EVENT_SUSPENDED_POSTCOPY = 7, /* suspended for post-copy migration */ - VIR_DOMAIN_EVENT_SUSPENDED_POSTCOPY_FAILED = 8, /* suspended after failed post-copy */ + VIR_DOMAIN_EVENT_SUSPENDED_PAUSED = 0, /* Normal suspend due to admin pause (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_SUSPENDED_MIGRATED = 1, /* Suspended for offline migration (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_SUSPENDED_IOERROR = 2, /* Suspended due to a disk I/O error (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_SUSPENDED_WATCHDOG = 3, /* Suspended due to a watchdog firing (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_SUSPENDED_RESTORED = 4, /* Restored from paused state file (Since: v0.9.5) */ + VIR_DOMAIN_EVENT_SUSPENDED_FROM_SNAPSHOT = 5, /* Restored from paused snapshot (Since: v0.9.5) */ + VIR_DOMAIN_EVENT_SUSPENDED_API_ERROR = 6, /* suspended after failure during libvirt API call (Since: v1.0.1) */ + VIR_DOMAIN_EVENT_SUSPENDED_POSTCOPY = 7, /* suspended for post-copy migration (Since: v1.3.3) */ + VIR_DOMAIN_EVENT_SUSPENDED_POSTCOPY_FAILED = 8, /* suspended after failed post-copy (Since: v1.3.3) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_SUSPENDED_LAST + VIR_DOMAIN_EVENT_SUSPENDED_LAST /* (Since: v0.9.10) */ # endif } virDomainEventSuspendedDetailType; @@ -3140,14 +3261,14 @@ typedef enum { * Details on the cause of a 'resumed' lifecycle event */ typedef enum { - VIR_DOMAIN_EVENT_RESUMED_UNPAUSED = 0, /* Normal resume due to admin unpause */ - VIR_DOMAIN_EVENT_RESUMED_MIGRATED = 1, /* Resumed for completion of migration */ - VIR_DOMAIN_EVENT_RESUMED_FROM_SNAPSHOT = 2, /* Resumed from snapshot */ + VIR_DOMAIN_EVENT_RESUMED_UNPAUSED = 0, /* Normal resume due to admin unpause (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_RESUMED_MIGRATED = 1, /* Resumed for completion of migration (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_RESUMED_FROM_SNAPSHOT = 2, /* Resumed from snapshot (Since: v0.9.5) */ VIR_DOMAIN_EVENT_RESUMED_POSTCOPY = 3, /* Resumed, but migration is still - running in post-copy mode */ + running in post-copy mode (Since: v1.3.3) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_RESUMED_LAST + VIR_DOMAIN_EVENT_RESUMED_LAST /* (Since: v0.9.10) */ # endif } virDomainEventResumedDetailType; @@ -3157,16 +3278,16 @@ typedef enum { * Details on the cause of a 'stopped' lifecycle event */ typedef enum { - VIR_DOMAIN_EVENT_STOPPED_SHUTDOWN = 0, /* Normal shutdown */ - VIR_DOMAIN_EVENT_STOPPED_DESTROYED = 1, /* Forced poweroff from host */ - VIR_DOMAIN_EVENT_STOPPED_CRASHED = 2, /* Guest crashed */ - VIR_DOMAIN_EVENT_STOPPED_MIGRATED = 3, /* Migrated off to another host */ - VIR_DOMAIN_EVENT_STOPPED_SAVED = 4, /* Saved to a state file */ - VIR_DOMAIN_EVENT_STOPPED_FAILED = 5, /* Host emulator/mgmt failed */ - VIR_DOMAIN_EVENT_STOPPED_FROM_SNAPSHOT = 6, /* offline snapshot loaded */ + VIR_DOMAIN_EVENT_STOPPED_SHUTDOWN = 0, /* Normal shutdown (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_STOPPED_DESTROYED = 1, /* Forced poweroff from host (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_STOPPED_CRASHED = 2, /* Guest crashed (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_STOPPED_MIGRATED = 3, /* Migrated off to another host (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_STOPPED_SAVED = 4, /* Saved to a state file (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_STOPPED_FAILED = 5, /* Host emulator/mgmt failed (Since: v0.5.0) */ + VIR_DOMAIN_EVENT_STOPPED_FROM_SNAPSHOT = 6, /* offline snapshot loaded (Since: v0.8.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_STOPPED_LAST + VIR_DOMAIN_EVENT_STOPPED_LAST /* (Since: v0.9.10) */ # endif } virDomainEventStoppedDetailType; @@ -3177,19 +3298,22 @@ typedef enum { * Details on the cause of a 'shutdown' lifecycle event */ typedef enum { - /* Guest finished shutdown sequence */ + /* Guest finished shutdown sequence (Since: v0.9.8) */ VIR_DOMAIN_EVENT_SHUTDOWN_FINISHED = 0, /* Domain finished shutting down after request from the guest itself - * (e.g. hardware-specific action) */ + * (e.g. hardware-specific action) (Since: v3.4.0) */ VIR_DOMAIN_EVENT_SHUTDOWN_GUEST = 1, /* Domain finished shutting down after request from the host (e.g. killed by - * a signal) */ + * a signal) + * + * Since: v3.4.0 + */ VIR_DOMAIN_EVENT_SHUTDOWN_HOST = 2, # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_SHUTDOWN_LAST + VIR_DOMAIN_EVENT_SHUTDOWN_LAST /* (Since: v0.9.10) */ # endif } virDomainEventShutdownDetailType; @@ -3199,11 +3323,11 @@ typedef enum { * Details on the cause of a 'pmsuspended' lifecycle event */ typedef enum { - VIR_DOMAIN_EVENT_PMSUSPENDED_MEMORY = 0, /* Guest was PM suspended to memory */ - VIR_DOMAIN_EVENT_PMSUSPENDED_DISK = 1, /* Guest was PM suspended to disk */ + VIR_DOMAIN_EVENT_PMSUSPENDED_MEMORY = 0, /* Guest was PM suspended to memory (Since: v0.10.2) */ + VIR_DOMAIN_EVENT_PMSUSPENDED_DISK = 1, /* Guest was PM suspended to disk (Since: v1.0.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_PMSUSPENDED_LAST + VIR_DOMAIN_EVENT_PMSUSPENDED_LAST /* (Since: v0.10.2) */ # endif } virDomainEventPMSuspendedDetailType; @@ -3213,11 +3337,11 @@ typedef enum { * Details on the cause of a 'crashed' lifecycle event */ typedef enum { - VIR_DOMAIN_EVENT_CRASHED_PANICKED = 0, /* Guest was panicked */ - VIR_DOMAIN_EVENT_CRASHED_CRASHLOADED = 1, /* Guest was crashloaded */ + VIR_DOMAIN_EVENT_CRASHED_PANICKED = 0, /* Guest was panicked (Since: v1.1.1) */ + VIR_DOMAIN_EVENT_CRASHED_CRASHLOADED = 1, /* Guest was crashloaded (Since: v6.1.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_CRASHED_LAST + VIR_DOMAIN_EVENT_CRASHED_LAST /* (Since: v1.1.1) */ # endif } virDomainEventCrashedDetailType; @@ -3227,14 +3351,14 @@ typedef enum { * Recipient of a memory failure event. */ typedef enum { - /* memory failure at hypersivor memory address space */ + /* memory failure at hypersivor memory address space (Since: v6.9.0) */ VIR_DOMAIN_EVENT_MEMORY_FAILURE_RECIPIENT_HYPERVISOR = 0, - /* memory failure at guest memory address space */ + /* memory failure at guest memory address space (Since: v6.9.0) */ VIR_DOMAIN_EVENT_MEMORY_FAILURE_RECIPIENT_GUEST = 1, # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_MEMORY_FAILURE_RECIPIENT_LAST + VIR_DOMAIN_EVENT_MEMORY_FAILURE_RECIPIENT_LAST /* (Since: v6.9.0) */ # endif } virDomainMemoryFailureRecipientType; @@ -3246,35 +3370,50 @@ typedef enum { */ typedef enum { /* the memory failure could be ignored. This will only be the case for - * action-optional failures. */ + * action-optional failures. + * + * Since: v6.9.0 + */ VIR_DOMAIN_EVENT_MEMORY_FAILURE_ACTION_IGNORE = 0, /* memory failure occurred in guest memory, the guest enabled MCE handling * mechanism, and hypervisor could inject the MCE into the guest - * successfully. */ + * successfully. + * + * Since: v6.9.0 + */ VIR_DOMAIN_EVENT_MEMORY_FAILURE_ACTION_INJECT = 1, /* the failure is unrecoverable. This occurs for action-required failures - * if the recipient is the hypervisor; hypervisor will exit. */ + * if the recipient is the hypervisor; hypervisor will exit. + * + * Since: v6.9.0 + */ VIR_DOMAIN_EVENT_MEMORY_FAILURE_ACTION_FATAL = 2, /* the failure is unrecoverable but confined to the guest. This occurs if - * the recipient is a guest which is not ready to handle memory failures. */ + * the recipient is a guest which is not ready to handle memory failures. + * + * Since: v6.9.0 + */ VIR_DOMAIN_EVENT_MEMORY_FAILURE_ACTION_RESET = 3, # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_MEMORY_FAILURE_ACTION_LAST + VIR_DOMAIN_EVENT_MEMORY_FAILURE_ACTION_LAST /* (Since: v6.9.0) */ # endif } virDomainMemoryFailureActionType; typedef enum { /* whether a memory failure event is action-required or action-optional - * (e.g. a failure during memory scrub). */ + * (e.g. a failure during memory scrub). (Since: v6.9.0) */ VIR_DOMAIN_MEMORY_FAILURE_ACTION_REQUIRED = (1 << 0), /* whether the failure occurred while the previous failure was still in - * progress. */ + * progress. + * + * Since: v6.9.0 + */ VIR_DOMAIN_MEMORY_FAILURE_RECURSIVE = (1 << 1), } virDomainMemoryFailureFlags; @@ -3311,15 +3450,15 @@ int virDomainIsPersistent(virDomainPtr dom); int virDomainIsUpdated(virDomainPtr dom); typedef enum { - VIR_DOMAIN_JOB_NONE = 0, /* No job is active */ - VIR_DOMAIN_JOB_BOUNDED = 1, /* Job with a finite completion time */ - VIR_DOMAIN_JOB_UNBOUNDED = 2, /* Job without a finite completion time */ - VIR_DOMAIN_JOB_COMPLETED = 3, /* Job has finished, but isn't cleaned up */ - VIR_DOMAIN_JOB_FAILED = 4, /* Job hit error, but isn't cleaned up */ - VIR_DOMAIN_JOB_CANCELLED = 5, /* Job was aborted, but isn't cleaned up */ + VIR_DOMAIN_JOB_NONE = 0, /* No job is active (Since: v0.7.7) */ + VIR_DOMAIN_JOB_BOUNDED = 1, /* Job with a finite completion time (Since: v0.7.7) */ + VIR_DOMAIN_JOB_UNBOUNDED = 2, /* Job without a finite completion time (Since: v0.7.7) */ + VIR_DOMAIN_JOB_COMPLETED = 3, /* Job has finished, but isn't cleaned up (Since: v0.7.7) */ + VIR_DOMAIN_JOB_FAILED = 4, /* Job hit error, but isn't cleaned up (Since: v0.7.7) */ + VIR_DOMAIN_JOB_CANCELLED = 5, /* Job was aborted, but isn't cleaned up (Since: v0.7.7) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_JOB_LAST + VIR_DOMAIN_JOB_LAST /* (Since: v0.9.10) */ # endif } virDomainJobType; @@ -3367,9 +3506,9 @@ struct _virDomainJobInfo { */ typedef enum { VIR_DOMAIN_JOB_STATS_COMPLETED = 1 << 0, /* return stats of a recently - * completed job */ + * completed job (Since: v1.2.9) */ VIR_DOMAIN_JOB_STATS_KEEP_COMPLETED = 1 << 1, /* don't remove completed - stats when reading them */ + stats when reading them (Since: v6.0.0) */ } virDomainGetJobStatsFlags; int virDomainGetJobInfo(virDomainPtr dom, @@ -3382,19 +3521,19 @@ int virDomainGetJobStats(virDomainPtr domain, int virDomainAbortJob(virDomainPtr dom); typedef enum { - VIR_DOMAIN_JOB_OPERATION_UNKNOWN = 0, - VIR_DOMAIN_JOB_OPERATION_START = 1, - VIR_DOMAIN_JOB_OPERATION_SAVE = 2, - VIR_DOMAIN_JOB_OPERATION_RESTORE = 3, - VIR_DOMAIN_JOB_OPERATION_MIGRATION_IN = 4, - VIR_DOMAIN_JOB_OPERATION_MIGRATION_OUT = 5, - VIR_DOMAIN_JOB_OPERATION_SNAPSHOT = 6, - VIR_DOMAIN_JOB_OPERATION_SNAPSHOT_REVERT = 7, - VIR_DOMAIN_JOB_OPERATION_DUMP = 8, - VIR_DOMAIN_JOB_OPERATION_BACKUP = 9, + VIR_DOMAIN_JOB_OPERATION_UNKNOWN = 0, /* (Since: v3.3.0) */ + VIR_DOMAIN_JOB_OPERATION_START = 1, /* (Since: v3.3.0) */ + VIR_DOMAIN_JOB_OPERATION_SAVE = 2, /* (Since: v3.3.0) */ + VIR_DOMAIN_JOB_OPERATION_RESTORE = 3, /* (Since: v3.3.0) */ + VIR_DOMAIN_JOB_OPERATION_MIGRATION_IN = 4, /* (Since: v3.3.0) */ + VIR_DOMAIN_JOB_OPERATION_MIGRATION_OUT = 5, /* (Since: v3.3.0) */ + VIR_DOMAIN_JOB_OPERATION_SNAPSHOT = 6, /* (Since: v3.3.0) */ + VIR_DOMAIN_JOB_OPERATION_SNAPSHOT_REVERT = 7, /* (Since: v3.3.0) */ + VIR_DOMAIN_JOB_OPERATION_DUMP = 8, /* (Since: v3.3.0) */ + VIR_DOMAIN_JOB_OPERATION_BACKUP = 9, /* (Since: v6.0.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_JOB_OPERATION_LAST + VIR_DOMAIN_JOB_OPERATION_LAST /* (Since: v3.3.0) */ # endif } virDomainJobOperation; @@ -3769,16 +3908,16 @@ typedef void (*virConnectDomainEventRTCChangeCallback)(virConnectPtr conn, * The action that is to be taken due to the watchdog device firing */ typedef enum { - VIR_DOMAIN_EVENT_WATCHDOG_NONE = 0, /* No action, watchdog ignored */ - VIR_DOMAIN_EVENT_WATCHDOG_PAUSE, /* Guest CPUs are paused */ - VIR_DOMAIN_EVENT_WATCHDOG_RESET, /* Guest CPUs are reset */ - VIR_DOMAIN_EVENT_WATCHDOG_POWEROFF, /* Guest is forcibly powered off */ - VIR_DOMAIN_EVENT_WATCHDOG_SHUTDOWN, /* Guest is requested to gracefully shutdown */ - VIR_DOMAIN_EVENT_WATCHDOG_DEBUG, /* No action, a debug message logged */ - VIR_DOMAIN_EVENT_WATCHDOG_INJECTNMI,/* Inject a non-maskable interrupt into guest */ + VIR_DOMAIN_EVENT_WATCHDOG_NONE = 0, /* No action, watchdog ignored (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_WATCHDOG_PAUSE, /* Guest CPUs are paused (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_WATCHDOG_RESET, /* Guest CPUs are reset (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_WATCHDOG_POWEROFF, /* Guest is forcibly powered off (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_WATCHDOG_SHUTDOWN, /* Guest is requested to gracefully shutdown (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_WATCHDOG_DEBUG, /* No action, a debug message logged (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_WATCHDOG_INJECTNMI,/* Inject a non-maskable interrupt into guest (Since: v1.2.17) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_WATCHDOG_LAST + VIR_DOMAIN_EVENT_WATCHDOG_LAST /* (Since: v0.9.10) */ # endif } virDomainEventWatchdogAction; @@ -3804,12 +3943,12 @@ typedef void (*virConnectDomainEventWatchdogCallback)(virConnectPtr conn, * The action that is to be taken due to an IO error occurring */ typedef enum { - VIR_DOMAIN_EVENT_IO_ERROR_NONE = 0, /* No action, IO error ignored */ - VIR_DOMAIN_EVENT_IO_ERROR_PAUSE, /* Guest CPUs are paused */ - VIR_DOMAIN_EVENT_IO_ERROR_REPORT, /* IO error reported to guest OS */ + VIR_DOMAIN_EVENT_IO_ERROR_NONE = 0, /* No action, IO error ignored (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_IO_ERROR_PAUSE, /* Guest CPUs are paused (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_IO_ERROR_REPORT, /* IO error reported to guest OS (Since: v0.8.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_IO_ERROR_LAST + VIR_DOMAIN_EVENT_IO_ERROR_LAST /* (Since: v0.9.10) */ # endif } virDomainEventIOErrorAction; @@ -3867,12 +4006,12 @@ typedef void (*virConnectDomainEventIOErrorReasonCallback)(virConnectPtr conn, * The phase of the graphics client connection */ typedef enum { - VIR_DOMAIN_EVENT_GRAPHICS_CONNECT = 0, /* Initial socket connection established */ - VIR_DOMAIN_EVENT_GRAPHICS_INITIALIZE, /* Authentication & setup completed */ - VIR_DOMAIN_EVENT_GRAPHICS_DISCONNECT, /* Final socket disconnection */ + VIR_DOMAIN_EVENT_GRAPHICS_CONNECT = 0, /* Initial socket connection established (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_GRAPHICS_INITIALIZE, /* Authentication & setup completed (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_GRAPHICS_DISCONNECT, /* Final socket disconnection (Since: v0.8.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_GRAPHICS_LAST + VIR_DOMAIN_EVENT_GRAPHICS_LAST /* (Since: v0.9.10) */ # endif } virDomainEventGraphicsPhase; @@ -3882,12 +4021,12 @@ typedef enum { * The type of address for the connection */ typedef enum { - VIR_DOMAIN_EVENT_GRAPHICS_ADDRESS_IPV4, /* IPv4 address */ - VIR_DOMAIN_EVENT_GRAPHICS_ADDRESS_IPV6, /* IPv6 address */ - VIR_DOMAIN_EVENT_GRAPHICS_ADDRESS_UNIX, /* UNIX socket path */ + VIR_DOMAIN_EVENT_GRAPHICS_ADDRESS_IPV4, /* IPv4 address (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_GRAPHICS_ADDRESS_IPV6, /* IPv6 address (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_GRAPHICS_ADDRESS_UNIX, /* UNIX socket path (Since: v0.9.7) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_GRAPHICS_ADDRESS_LAST + VIR_DOMAIN_EVENT_GRAPHICS_ADDRESS_LAST /* (Since: v0.9.10) */ # endif } virDomainEventGraphicsAddressType; @@ -3969,13 +4108,13 @@ typedef void (*virConnectDomainEventGraphicsCallback)(virConnectPtr conn, * virDomainBlockCopy(), or virDomainBlockCommit() operation */ typedef enum { - VIR_DOMAIN_BLOCK_JOB_COMPLETED = 0, - VIR_DOMAIN_BLOCK_JOB_FAILED = 1, - VIR_DOMAIN_BLOCK_JOB_CANCELED = 2, - VIR_DOMAIN_BLOCK_JOB_READY = 3, + VIR_DOMAIN_BLOCK_JOB_COMPLETED = 0, /* (Since: v0.9.4) */ + VIR_DOMAIN_BLOCK_JOB_FAILED = 1, /* (Since: v0.9.4) */ + VIR_DOMAIN_BLOCK_JOB_CANCELED = 2, /* (Since: v0.9.12) */ + VIR_DOMAIN_BLOCK_JOB_READY = 3, /* (Since: v1.0.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_BLOCK_JOB_LAST + VIR_DOMAIN_BLOCK_JOB_LAST /* (Since: v0.9.10) */ # endif } virConnectDomainEventBlockJobStatus; @@ -4017,15 +4156,21 @@ typedef void (*virConnectDomainEventBlockJobCallback)(virConnectPtr conn, */ typedef enum { /* Removable media changed to empty according to startup policy as source - * was missing. oldSrcPath is set, newSrcPath is NULL */ + * was missing. oldSrcPath is set, newSrcPath is NULL + * + * Since: v0.9.7 + * */ VIR_DOMAIN_EVENT_DISK_CHANGE_MISSING_ON_START = 0, /* Disk was dropped from domain as source file was missing. - * oldSrcPath is set, newSrcPath is NULL */ + * oldSrcPath is set, newSrcPath is NULL + * + * Since: v1.1.2 + * */ VIR_DOMAIN_EVENT_DISK_DROP_MISSING_ON_START = 1, # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_DISK_CHANGE_LAST + VIR_DOMAIN_EVENT_DISK_CHANGE_LAST /* (Since: v0.9.10) */ # endif } virConnectDomainEventDiskChangeReason; @@ -4062,11 +4207,11 @@ typedef void (*virConnectDomainEventDiskChangeCallback)(virConnectPtr conn, * The reason describing why the callback was called */ typedef enum { - VIR_DOMAIN_EVENT_TRAY_CHANGE_OPEN = 0, - VIR_DOMAIN_EVENT_TRAY_CHANGE_CLOSE, + VIR_DOMAIN_EVENT_TRAY_CHANGE_OPEN = 0, /* (Since: v0.9.11) */ + VIR_DOMAIN_EVENT_TRAY_CHANGE_CLOSE, /* (Since: v0.9.11) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_EVENT_TRAY_CHANGE_LAST + VIR_DOMAIN_EVENT_TRAY_CHANGE_LAST /* (Since: v0.9.11) */ # endif } virDomainEventTrayChangeReason; @@ -4579,21 +4724,21 @@ typedef void (*virConnectDomainEventTunableCallback)(virConnectPtr conn, typedef enum { - VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_STATE_CONNECTED = 1, /* agent connected */ - VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_STATE_DISCONNECTED = 2, /* agent disconnected */ + VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_STATE_CONNECTED = 1, /* agent connected (Since: v1.2.11) */ + VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_STATE_DISCONNECTED = 2, /* agent disconnected (Since: v1.2.11) */ # ifdef VIR_ENUM_SENTINELS - VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_STATE_LAST + VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_STATE_LAST /* (Since: v1.2.11) */ # endif } virConnectDomainEventAgentLifecycleState; typedef enum { - VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_REASON_UNKNOWN = 0, /* unknown state change reason */ - VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_REASON_DOMAIN_STARTED = 1, /* state changed due to domain start */ - VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_REASON_CHANNEL = 2, /* channel state changed */ + VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_REASON_UNKNOWN = 0, /* unknown state change reason (Since: v1.2.11) */ + VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_REASON_DOMAIN_STARTED = 1, /* state changed due to domain start (Since: v1.2.11) */ + VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_REASON_CHANNEL = 2, /* channel state changed (Since: v1.2.11) */ # ifdef VIR_ENUM_SENTINELS - VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_REASON_LAST + VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_REASON_LAST /* (Since: v1.2.11) */ # endif } virConnectDomainEventAgentLifecycleReason; @@ -4713,33 +4858,33 @@ typedef void (*virConnectDomainEventMemoryDeviceSizeChangeCallback)(virConnectPt * signature of callback function will be used. */ typedef enum { - VIR_DOMAIN_EVENT_ID_LIFECYCLE = 0, /* virConnectDomainEventCallback */ - VIR_DOMAIN_EVENT_ID_REBOOT = 1, /* virConnectDomainEventGenericCallback */ - VIR_DOMAIN_EVENT_ID_RTC_CHANGE = 2, /* virConnectDomainEventRTCChangeCallback */ - VIR_DOMAIN_EVENT_ID_WATCHDOG = 3, /* virConnectDomainEventWatchdogCallback */ - VIR_DOMAIN_EVENT_ID_IO_ERROR = 4, /* virConnectDomainEventIOErrorCallback */ - VIR_DOMAIN_EVENT_ID_GRAPHICS = 5, /* virConnectDomainEventGraphicsCallback */ - VIR_DOMAIN_EVENT_ID_IO_ERROR_REASON = 6, /* virConnectDomainEventIOErrorReasonCallback */ - VIR_DOMAIN_EVENT_ID_CONTROL_ERROR = 7, /* virConnectDomainEventGenericCallback */ - VIR_DOMAIN_EVENT_ID_BLOCK_JOB = 8, /* virConnectDomainEventBlockJobCallback */ - VIR_DOMAIN_EVENT_ID_DISK_CHANGE = 9, /* virConnectDomainEventDiskChangeCallback */ - VIR_DOMAIN_EVENT_ID_TRAY_CHANGE = 10, /* virConnectDomainEventTrayChangeCallback */ - VIR_DOMAIN_EVENT_ID_PMWAKEUP = 11, /* virConnectDomainEventPMWakeupCallback */ - VIR_DOMAIN_EVENT_ID_PMSUSPEND = 12, /* virConnectDomainEventPMSuspendCallback */ - VIR_DOMAIN_EVENT_ID_BALLOON_CHANGE = 13, /* virConnectDomainEventBalloonChangeCallback */ - VIR_DOMAIN_EVENT_ID_PMSUSPEND_DISK = 14, /* virConnectDomainEventPMSuspendDiskCallback */ - VIR_DOMAIN_EVENT_ID_DEVICE_REMOVED = 15, /* virConnectDomainEventDeviceRemovedCallback */ - VIR_DOMAIN_EVENT_ID_BLOCK_JOB_2 = 16, /* virConnectDomainEventBlockJobCallback */ - VIR_DOMAIN_EVENT_ID_TUNABLE = 17, /* virConnectDomainEventTunableCallback */ - VIR_DOMAIN_EVENT_ID_AGENT_LIFECYCLE = 18,/* virConnectDomainEventAgentLifecycleCallback */ - VIR_DOMAIN_EVENT_ID_DEVICE_ADDED = 19, /* virConnectDomainEventDeviceAddedCallback */ - VIR_DOMAIN_EVENT_ID_MIGRATION_ITERATION = 20, /* virConnectDomainEventMigrationIterationCallback */ - VIR_DOMAIN_EVENT_ID_JOB_COMPLETED = 21, /* virConnectDomainEventJobCompletedCallback */ - VIR_DOMAIN_EVENT_ID_DEVICE_REMOVAL_FAILED = 22, /* virConnectDomainEventDeviceRemovalFailedCallback */ - VIR_DOMAIN_EVENT_ID_METADATA_CHANGE = 23, /* virConnectDomainEventMetadataChangeCallback */ - VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD = 24, /* virConnectDomainEventBlockThresholdCallback */ - VIR_DOMAIN_EVENT_ID_MEMORY_FAILURE = 25, /* virConnectDomainEventMemoryFailureCallback */ - VIR_DOMAIN_EVENT_ID_MEMORY_DEVICE_SIZE_CHANGE = 26, /* virConnectDomainEventMemoryDeviceSizeChangeCallback */ + VIR_DOMAIN_EVENT_ID_LIFECYCLE = 0, /* virConnectDomainEventCallback (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_ID_REBOOT = 1, /* virConnectDomainEventGenericCallback (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_ID_RTC_CHANGE = 2, /* virConnectDomainEventRTCChangeCallback (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_ID_WATCHDOG = 3, /* virConnectDomainEventWatchdogCallback (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_ID_IO_ERROR = 4, /* virConnectDomainEventIOErrorCallback (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_ID_GRAPHICS = 5, /* virConnectDomainEventGraphicsCallback (Since: v0.8.0) */ + VIR_DOMAIN_EVENT_ID_IO_ERROR_REASON = 6, /* virConnectDomainEventIOErrorReasonCallback (Since: v0.8.1) */ + VIR_DOMAIN_EVENT_ID_CONTROL_ERROR = 7, /* virConnectDomainEventGenericCallback (Since: v0.9.2) */ + VIR_DOMAIN_EVENT_ID_BLOCK_JOB = 8, /* virConnectDomainEventBlockJobCallback (Since: v0.9.4) */ + VIR_DOMAIN_EVENT_ID_DISK_CHANGE = 9, /* virConnectDomainEventDiskChangeCallback (Since: v0.9.7) */ + VIR_DOMAIN_EVENT_ID_TRAY_CHANGE = 10, /* virConnectDomainEventTrayChangeCallback (Since: v0.9.11) */ + VIR_DOMAIN_EVENT_ID_PMWAKEUP = 11, /* virConnectDomainEventPMWakeupCallback (Since: v0.9.11) */ + VIR_DOMAIN_EVENT_ID_PMSUSPEND = 12, /* virConnectDomainEventPMSuspendCallback (Since: v0.9.11) */ + VIR_DOMAIN_EVENT_ID_BALLOON_CHANGE = 13, /* virConnectDomainEventBalloonChangeCallback (Since: v0.10.0) */ + VIR_DOMAIN_EVENT_ID_PMSUSPEND_DISK = 14, /* virConnectDomainEventPMSuspendDiskCallback (Since: v1.0.0) */ + VIR_DOMAIN_EVENT_ID_DEVICE_REMOVED = 15, /* virConnectDomainEventDeviceRemovedCallback (Since: v1.1.1) */ + VIR_DOMAIN_EVENT_ID_BLOCK_JOB_2 = 16, /* virConnectDomainEventBlockJobCallback (Since: v1.2.6) */ + VIR_DOMAIN_EVENT_ID_TUNABLE = 17, /* virConnectDomainEventTunableCallback (Since: v1.2.9) */ + VIR_DOMAIN_EVENT_ID_AGENT_LIFECYCLE = 18,/* virConnectDomainEventAgentLifecycleCallback (Since: v1.2.11) */ + VIR_DOMAIN_EVENT_ID_DEVICE_ADDED = 19, /* virConnectDomainEventDeviceAddedCallback (Since: v1.2.15) */ + VIR_DOMAIN_EVENT_ID_MIGRATION_ITERATION = 20, /* virConnectDomainEventMigrationIterationCallback (Since: v1.3.2) */ + VIR_DOMAIN_EVENT_ID_JOB_COMPLETED = 21, /* virConnectDomainEventJobCompletedCallback (Since: v1.3.3) */ + VIR_DOMAIN_EVENT_ID_DEVICE_REMOVAL_FAILED = 22, /* virConnectDomainEventDeviceRemovalFailedCallback (Since: v1.3.4) */ + VIR_DOMAIN_EVENT_ID_METADATA_CHANGE = 23, /* virConnectDomainEventMetadataChangeCallback (Since: v3.0.0) */ + VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD = 24, /* virConnectDomainEventBlockThresholdCallback (Since: v3.2.0) */ + VIR_DOMAIN_EVENT_ID_MEMORY_FAILURE = 25, /* virConnectDomainEventMemoryFailureCallback (Since: v6.9.0) */ + VIR_DOMAIN_EVENT_ID_MEMORY_DEVICE_SIZE_CHANGE = 26, /* virConnectDomainEventMemoryDeviceSizeChangeCallback (Since: v7.9.0) */ # ifdef VIR_ENUM_SENTINELS VIR_DOMAIN_EVENT_ID_LAST @@ -4747,6 +4892,8 @@ typedef enum { * NB: this enum value will increase over time as new events are * added to the libvirt API. It reflects the last event ID supported * by this version of the libvirt API. + * + * Since: v0.8.0 */ # endif } virDomainEventID; @@ -4773,9 +4920,9 @@ typedef enum { VIR_DOMAIN_CONSOLE_FORCE = (1 << 0), /* abort a (possibly) active console connection to force a new - connection */ + connection (Since: v0.9.11) */ VIR_DOMAIN_CONSOLE_SAFE = (1 << 1), /* check if the console driver supports - safe console operations */ + safe console operations (Since: v0.9.11) */ } virDomainConsoleFlags; int virDomainOpenConsole(virDomainPtr dom, @@ -4791,7 +4938,7 @@ int virDomainOpenConsole(virDomainPtr dom, typedef enum { VIR_DOMAIN_CHANNEL_FORCE = (1 << 0), /* abort a (possibly) active channel connection to force a new - connection */ + connection (Since: v1.0.2) */ } virDomainChannelFlags; int virDomainOpenChannel(virDomainPtr dom, @@ -4800,7 +4947,7 @@ int virDomainOpenChannel(virDomainPtr dom, unsigned int flags); typedef enum { - VIR_DOMAIN_OPEN_GRAPHICS_SKIPAUTH = (1 << 0), + VIR_DOMAIN_OPEN_GRAPHICS_SKIPAUTH = (1 << 0), /* (Since: v0.9.7) */ } virDomainOpenGraphicsFlags; int virDomainOpenGraphics(virDomainPtr dom, @@ -4857,7 +5004,7 @@ int virDomainGetTime(virDomainPtr dom, unsigned int flags); typedef enum { - VIR_DOMAIN_TIME_SYNC = (1 << 0), /* Re-sync domain time from domain's RTC */ + VIR_DOMAIN_TIME_SYNC = (1 << 0), /* Re-sync domain time from domain's RTC (Since: v1.2.5) */ } virDomainSetTimeFlags; int virDomainSetTime(virDomainPtr dom, @@ -4873,12 +5020,12 @@ int virDomainSetTime(virDomainPtr dom, * 0.9.2. */ typedef enum { - VIR_DOMAIN_SCHED_FIELD_INT = VIR_TYPED_PARAM_INT, - VIR_DOMAIN_SCHED_FIELD_UINT = VIR_TYPED_PARAM_UINT, - VIR_DOMAIN_SCHED_FIELD_LLONG = VIR_TYPED_PARAM_LLONG, - VIR_DOMAIN_SCHED_FIELD_ULLONG = VIR_TYPED_PARAM_ULLONG, - VIR_DOMAIN_SCHED_FIELD_DOUBLE = VIR_TYPED_PARAM_DOUBLE, - VIR_DOMAIN_SCHED_FIELD_BOOLEAN = VIR_TYPED_PARAM_BOOLEAN, + VIR_DOMAIN_SCHED_FIELD_INT = VIR_TYPED_PARAM_INT, /* (Since: v0.2.3) */ + VIR_DOMAIN_SCHED_FIELD_UINT = VIR_TYPED_PARAM_UINT, /* (Since: v0.2.3) */ + VIR_DOMAIN_SCHED_FIELD_LLONG = VIR_TYPED_PARAM_LLONG, /* (Since: v0.2.3) */ + VIR_DOMAIN_SCHED_FIELD_ULLONG = VIR_TYPED_PARAM_ULLONG, /* (Since: v0.2.3) */ + VIR_DOMAIN_SCHED_FIELD_DOUBLE = VIR_TYPED_PARAM_DOUBLE, /* (Since: v0.2.3) */ + VIR_DOMAIN_SCHED_FIELD_BOOLEAN = VIR_TYPED_PARAM_BOOLEAN, /* (Since: v0.2.3) */ } virSchedParameterType; /** @@ -4917,12 +5064,12 @@ typedef virSchedParameter *virSchedParameterPtr; * 0.9.2. */ typedef enum { - VIR_DOMAIN_BLKIO_PARAM_INT = VIR_TYPED_PARAM_INT, - VIR_DOMAIN_BLKIO_PARAM_UINT = VIR_TYPED_PARAM_UINT, - VIR_DOMAIN_BLKIO_PARAM_LLONG = VIR_TYPED_PARAM_LLONG, - VIR_DOMAIN_BLKIO_PARAM_ULLONG = VIR_TYPED_PARAM_ULLONG, - VIR_DOMAIN_BLKIO_PARAM_DOUBLE = VIR_TYPED_PARAM_DOUBLE, - VIR_DOMAIN_BLKIO_PARAM_BOOLEAN = VIR_TYPED_PARAM_BOOLEAN, + VIR_DOMAIN_BLKIO_PARAM_INT = VIR_TYPED_PARAM_INT, /* (Since: v0.9.0) */ + VIR_DOMAIN_BLKIO_PARAM_UINT = VIR_TYPED_PARAM_UINT, /* (Since: v0.9.0) */ + VIR_DOMAIN_BLKIO_PARAM_LLONG = VIR_TYPED_PARAM_LLONG, /* (Since: v0.9.0) */ + VIR_DOMAIN_BLKIO_PARAM_ULLONG = VIR_TYPED_PARAM_ULLONG, /* (Since: v0.9.0) */ + VIR_DOMAIN_BLKIO_PARAM_DOUBLE = VIR_TYPED_PARAM_DOUBLE, /* (Since: v0.9.0) */ + VIR_DOMAIN_BLKIO_PARAM_BOOLEAN = VIR_TYPED_PARAM_BOOLEAN, /* (Since: v0.9.0) */ } virBlkioParameterType; /** @@ -4961,12 +5108,12 @@ typedef virBlkioParameter *virBlkioParameterPtr; * 0.9.2. */ typedef enum { - VIR_DOMAIN_MEMORY_PARAM_INT = VIR_TYPED_PARAM_INT, - VIR_DOMAIN_MEMORY_PARAM_UINT = VIR_TYPED_PARAM_UINT, - VIR_DOMAIN_MEMORY_PARAM_LLONG = VIR_TYPED_PARAM_LLONG, - VIR_DOMAIN_MEMORY_PARAM_ULLONG = VIR_TYPED_PARAM_ULLONG, - VIR_DOMAIN_MEMORY_PARAM_DOUBLE = VIR_TYPED_PARAM_DOUBLE, - VIR_DOMAIN_MEMORY_PARAM_BOOLEAN = VIR_TYPED_PARAM_BOOLEAN, + VIR_DOMAIN_MEMORY_PARAM_INT = VIR_TYPED_PARAM_INT, /* (Since: v0.8.5) */ + VIR_DOMAIN_MEMORY_PARAM_UINT = VIR_TYPED_PARAM_UINT, /* (Since: v0.8.5) */ + VIR_DOMAIN_MEMORY_PARAM_LLONG = VIR_TYPED_PARAM_LLONG, /* (Since: v0.8.5) */ + VIR_DOMAIN_MEMORY_PARAM_ULLONG = VIR_TYPED_PARAM_ULLONG, /* (Since: v0.8.5) */ + VIR_DOMAIN_MEMORY_PARAM_DOUBLE = VIR_TYPED_PARAM_DOUBLE, /* (Since: v0.8.5) */ + VIR_DOMAIN_MEMORY_PARAM_BOOLEAN = VIR_TYPED_PARAM_BOOLEAN, /* (Since: v0.8.5) */ } virMemoryParameterType; /** @@ -4998,12 +5145,12 @@ typedef struct _virTypedParameter virMemoryParameter; typedef virMemoryParameter *virMemoryParameterPtr; typedef enum { - VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_LEASE = 0, /* Parse DHCP lease file */ - VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_AGENT = 1, /* Query qemu guest agent */ - VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_ARP = 2, /* Query ARP tables */ + VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_LEASE = 0, /* Parse DHCP lease file (Since: v1.2.14) */ + VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_AGENT = 1, /* Query qemu guest agent (Since: v1.2.14) */ + VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_ARP = 2, /* Query ARP tables (Since: v4.2.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_LAST + VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_LAST /* (Since: v1.2.14) */ # endif } virDomainInterfaceAddressesSource; @@ -5032,7 +5179,7 @@ int virDomainInterfaceAddresses(virDomainPtr dom, void virDomainInterfaceFree(virDomainInterfacePtr iface); typedef enum { - VIR_DOMAIN_PASSWORD_ENCRYPTED = 1 << 0, /* the password is already encrypted */ + VIR_DOMAIN_PASSWORD_ENCRYPTED = 1 << 0, /* the password is already encrypted (Since: v1.2.16) */ } virDomainSetUserPasswordFlags; int virDomainSetUserPassword(virDomainPtr dom, @@ -5065,25 +5212,25 @@ int virDomainSetBlockThreshold(virDomainPtr domain, unsigned int flags); typedef enum { - VIR_DOMAIN_LIFECYCLE_POWEROFF = 0, - VIR_DOMAIN_LIFECYCLE_REBOOT = 1, - VIR_DOMAIN_LIFECYCLE_CRASH = 2, + VIR_DOMAIN_LIFECYCLE_POWEROFF = 0, /* (Since: v3.9.0) */ + VIR_DOMAIN_LIFECYCLE_REBOOT = 1, /* (Since: v3.9.0) */ + VIR_DOMAIN_LIFECYCLE_CRASH = 2, /* (Since: v3.9.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_LIFECYCLE_LAST + VIR_DOMAIN_LIFECYCLE_LAST /* (Since: v3.9.0) */ # endif } virDomainLifecycle; typedef enum { - VIR_DOMAIN_LIFECYCLE_ACTION_DESTROY = 0, - VIR_DOMAIN_LIFECYCLE_ACTION_RESTART = 1, - VIR_DOMAIN_LIFECYCLE_ACTION_RESTART_RENAME = 2, - VIR_DOMAIN_LIFECYCLE_ACTION_PRESERVE = 3, - VIR_DOMAIN_LIFECYCLE_ACTION_COREDUMP_DESTROY = 4, - VIR_DOMAIN_LIFECYCLE_ACTION_COREDUMP_RESTART = 5, + VIR_DOMAIN_LIFECYCLE_ACTION_DESTROY = 0, /* (Since: v3.9.0) */ + VIR_DOMAIN_LIFECYCLE_ACTION_RESTART = 1, /* (Since: v3.9.0) */ + VIR_DOMAIN_LIFECYCLE_ACTION_RESTART_RENAME = 2, /* (Since: v3.9.0) */ + VIR_DOMAIN_LIFECYCLE_ACTION_PRESERVE = 3, /* (Since: v3.9.0) */ + VIR_DOMAIN_LIFECYCLE_ACTION_COREDUMP_DESTROY = 4, /* (Since: v3.9.0) */ + VIR_DOMAIN_LIFECYCLE_ACTION_COREDUMP_RESTART = 5, /* (Since: v3.9.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_LIFECYCLE_ACTION_LAST + VIR_DOMAIN_LIFECYCLE_ACTION_LAST /* (Since: v3.9.0) */ # endif } virDomainLifecycleAction; @@ -5178,13 +5325,13 @@ int virDomainSetLaunchSecurityState(virDomainPtr domain, unsigned int flags); typedef enum { - VIR_DOMAIN_GUEST_INFO_USERS = (1 << 0), /* return active users */ - VIR_DOMAIN_GUEST_INFO_OS = (1 << 1), /* return OS information */ - VIR_DOMAIN_GUEST_INFO_TIMEZONE = (1 << 2), /* return timezone information */ - VIR_DOMAIN_GUEST_INFO_HOSTNAME = (1 << 3), /* return hostname information */ - VIR_DOMAIN_GUEST_INFO_FILESYSTEM = (1 << 4), /* return filesystem information */ - VIR_DOMAIN_GUEST_INFO_DISKS = (1 << 5), /* return disks information */ - VIR_DOMAIN_GUEST_INFO_INTERFACES = (1 << 6), /* return interfaces information */ + VIR_DOMAIN_GUEST_INFO_USERS = (1 << 0), /* return active users (Since: v5.7.0) */ + VIR_DOMAIN_GUEST_INFO_OS = (1 << 1), /* return OS information (Since: v5.7.0) */ + VIR_DOMAIN_GUEST_INFO_TIMEZONE = (1 << 2), /* return timezone information (Since: v5.7.0) */ + VIR_DOMAIN_GUEST_INFO_HOSTNAME = (1 << 3), /* return hostname information (Since: v5.7.0) */ + VIR_DOMAIN_GUEST_INFO_FILESYSTEM = (1 << 4), /* return filesystem information (Since: v5.7.0) */ + VIR_DOMAIN_GUEST_INFO_DISKS = (1 << 5), /* return disks information (Since: v7.0.0) */ + VIR_DOMAIN_GUEST_INFO_INTERFACES = (1 << 6), /* return interfaces information (Since: v7.10.0) */ } virDomainGuestInfoTypes; int virDomainGetGuestInfo(virDomainPtr domain, @@ -5194,9 +5341,9 @@ int virDomainGetGuestInfo(virDomainPtr domain, unsigned int flags); typedef enum { - VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK = -2, - VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_DEFAULT = -1, - VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_NOWAIT = 0, + VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK = -2, /* (Since: v5.10.0) */ + VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_DEFAULT = -1, /* (Since: v5.10.0) */ + VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_NOWAIT = 0, /* (Since: v5.10.0) */ } virDomainAgentResponseTimeoutValues; int virDomainAgentSetResponseTimeout(virDomainPtr domain, @@ -5205,7 +5352,7 @@ int virDomainAgentSetResponseTimeout(virDomainPtr domain, typedef enum { VIR_DOMAIN_BACKUP_BEGIN_REUSE_EXTERNAL = (1 << 0), /* reuse separately - provided images */ + provided images (Since: v6.0.0) */ } virDomainBackupBeginFlags; int virDomainBackupBegin(virDomainPtr domain, @@ -5222,8 +5369,8 @@ int virDomainAuthorizedSSHKeysGet(virDomainPtr domain, unsigned int flags); typedef enum { - VIR_DOMAIN_AUTHORIZED_SSH_KEYS_SET_APPEND = (1 << 0), /* don't truncate file, just append */ - VIR_DOMAIN_AUTHORIZED_SSH_KEYS_SET_REMOVE = (1 << 1), /* remove keys, instead of adding them */ + VIR_DOMAIN_AUTHORIZED_SSH_KEYS_SET_APPEND = (1 << 0), /* don't truncate file, just append (Since: v6.10.0) */ + VIR_DOMAIN_AUTHORIZED_SSH_KEYS_SET_REMOVE = (1 << 1), /* remove keys, instead of adding them (Since: v6.10.0) */ } virDomainAuthorizedSSHKeysSetFlags; @@ -5234,8 +5381,8 @@ int virDomainAuthorizedSSHKeysSet(virDomainPtr domain, unsigned int flags); typedef enum { - VIR_DOMAIN_MESSAGE_DEPRECATION = (1 << 0), - VIR_DOMAIN_MESSAGE_TAINTING = (1 << 1), + VIR_DOMAIN_MESSAGE_DEPRECATION = (1 << 0), /* (Since: v7.1.0) */ + VIR_DOMAIN_MESSAGE_TAINTING = (1 << 1), /* (Since: v7.1.0) */ } virDomainMessageType; int virDomainGetMessages(virDomainPtr domain, @@ -5249,14 +5396,14 @@ int virDomainGetMessages(virDomainPtr domain, */ typedef enum { VIR_DOMAIN_DIRTYRATE_UNSTARTED = 0, /* the dirtyrate calculation has - not been started */ + not been started (Since: v7.2.0) */ VIR_DOMAIN_DIRTYRATE_MEASURING = 1, /* the dirtyrate calculation is - measuring */ + measuring (Since: v7.2.0) */ VIR_DOMAIN_DIRTYRATE_MEASURED = 2, /* the dirtyrate calculation is - completed */ + completed (Since: v7.2.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_DOMAIN_DIRTYRATE_LAST + VIR_DOMAIN_DIRTYRATE_LAST /* (Since: v7.2.0) */ # endif } virDomainDirtyRateStatus; @@ -5268,9 +5415,9 @@ typedef enum { * */ typedef enum { - VIR_DOMAIN_DIRTYRATE_MODE_PAGE_SAMPLING = 0, /* default mode - page-sampling */ - VIR_DOMAIN_DIRTYRATE_MODE_DIRTY_BITMAP = 1 << 0, /* dirty-bitmap mode */ - VIR_DOMAIN_DIRTYRATE_MODE_DIRTY_RING = 1 << 1, /* dirty-ring mode */ + VIR_DOMAIN_DIRTYRATE_MODE_PAGE_SAMPLING = 0, /* default mode - page-sampling (Since: v8.1.0) */ + VIR_DOMAIN_DIRTYRATE_MODE_DIRTY_BITMAP = 1 << 0, /* dirty-bitmap mode (Since: v8.1.0) */ + VIR_DOMAIN_DIRTYRATE_MODE_DIRTY_RING = 1 << 1, /* dirty-ring mode (Since: v8.1.0) */ } virDomainDirtyRateCalcFlags; int virDomainStartDirtyRateCalc(virDomainPtr domain, diff --git a/include/libvirt/libvirt-event.h b/include/libvirt/libvirt-event.h index facdc3a3ec..f86a55ecf6 100644 --- a/include/libvirt/libvirt-event.h +++ b/include/libvirt/libvirt-event.h @@ -36,10 +36,10 @@ * this construct. */ typedef enum { - VIR_EVENT_HANDLE_READABLE = (1 << 0), - VIR_EVENT_HANDLE_WRITABLE = (1 << 1), - VIR_EVENT_HANDLE_ERROR = (1 << 2), - VIR_EVENT_HANDLE_HANGUP = (1 << 3), + VIR_EVENT_HANDLE_READABLE = (1 << 0), /* (Since: v0.5.0) */ + VIR_EVENT_HANDLE_WRITABLE = (1 << 1), /* (Since: v0.5.0) */ + VIR_EVENT_HANDLE_ERROR = (1 << 2), /* (Since: v0.5.0) */ + VIR_EVENT_HANDLE_HANGUP = (1 << 3), /* (Since: v0.5.0) */ } virEventHandleType; /** diff --git a/include/libvirt/libvirt-host.h b/include/libvirt/libvirt-host.h index 8cccf2921f..15e4e7ea72 100644 --- a/include/libvirt/libvirt-host.h +++ b/include/libvirt/libvirt-host.h @@ -51,12 +51,12 @@ typedef virConnect *virConnectPtr; * transitioned to. */ typedef enum { - VIR_NODE_SUSPEND_TARGET_MEM = 0, - VIR_NODE_SUSPEND_TARGET_DISK = 1, - VIR_NODE_SUSPEND_TARGET_HYBRID = 2, + VIR_NODE_SUSPEND_TARGET_MEM = 0, /* (Since: v0.9.8) */ + VIR_NODE_SUSPEND_TARGET_DISK = 1, /* (Since: v0.9.8) */ + VIR_NODE_SUSPEND_TARGET_HYBRID = 2, /* (Since: v0.9.8) */ # ifdef VIR_ENUM_SENTINELS - VIR_NODE_SUSPEND_TARGET_LAST /* This constant is subject to change */ + VIR_NODE_SUSPEND_TARGET_LAST /* This constant is subject to change (Since: v0.9.8) */ # endif } virNodeSuspendTarget; @@ -185,7 +185,7 @@ struct _virNodeInfo { * Value for specifying request for the total CPU time/utilization */ typedef enum { - VIR_NODE_CPU_STATS_ALL_CPUS = -1, + VIR_NODE_CPU_STATS_ALL_CPUS = -1, /* (Since: v0.9.3) */ } virNodeGetCPUStatsAllCPUs; /** @@ -263,7 +263,7 @@ struct _virNodeCPUStats { * Value for specifying request for the total memory of all cells. */ typedef enum { - VIR_NODE_MEMORY_STATS_ALL_CELLS = -1, + VIR_NODE_MEMORY_STATS_ALL_CELLS = -1, /* (Since: v0.9.3) */ } virNodeGetMemoryStatsAllCells; /** @@ -499,24 +499,24 @@ int virNodeGetSEVInfo (virConnectPtr conn, * Flags when opening a connection to a hypervisor */ typedef enum { - VIR_CONNECT_RO = (1 << 0), /* A readonly connection */ - VIR_CONNECT_NO_ALIASES = (1 << 1), /* Don't try to resolve URI aliases */ + VIR_CONNECT_RO = (1 << 0), /* A readonly connection (Since: v0.4.1) */ + VIR_CONNECT_NO_ALIASES = (1 << 1), /* Don't try to resolve URI aliases (Since: v0.9.7) */ } virConnectFlags; typedef enum { - VIR_CRED_USERNAME = 1, /* Identity to act as */ - VIR_CRED_AUTHNAME = 2, /* Identify to authorize as */ - VIR_CRED_LANGUAGE = 3, /* RFC 1766 languages, comma separated */ - VIR_CRED_CNONCE = 4, /* client supplies a nonce */ - VIR_CRED_PASSPHRASE = 5, /* Passphrase secret */ - VIR_CRED_ECHOPROMPT = 6, /* Challenge response */ - VIR_CRED_NOECHOPROMPT = 7, /* Challenge response */ - VIR_CRED_REALM = 8, /* Authentication realm */ - VIR_CRED_EXTERNAL = 9, /* Externally managed credential */ + VIR_CRED_USERNAME = 1, /* Identity to act as (Since: v0.4.1) */ + VIR_CRED_AUTHNAME = 2, /* Identify to authorize as (Since: v0.4.1) */ + VIR_CRED_LANGUAGE = 3, /* RFC 1766 languages, comma separated (Since: v0.4.1) */ + VIR_CRED_CNONCE = 4, /* client supplies a nonce (Since: v0.4.1) */ + VIR_CRED_PASSPHRASE = 5, /* Passphrase secret (Since: v0.4.1) */ + VIR_CRED_ECHOPROMPT = 6, /* Challenge response (Since: v0.4.1) */ + VIR_CRED_NOECHOPROMPT = 7, /* Challenge response (Since: v0.4.1) */ + VIR_CRED_REALM = 8, /* Authentication realm (Since: v0.4.1) */ + VIR_CRED_EXTERNAL = 9, /* Externally managed credential (Since: v0.4.1) */ # ifdef VIR_ENUM_SENTINELS - VIR_CRED_LAST /* More may be added - expect the unexpected */ + VIR_CRED_LAST /* More may be added - expect the unexpected (Since: v0.9.10) */ # endif } virConnectCredentialType; @@ -770,21 +770,21 @@ int virConnectIsAlive(virConnectPtr conn); */ typedef enum { - VIR_CPU_COMPARE_ERROR = -1, - VIR_CPU_COMPARE_INCOMPATIBLE = 0, - VIR_CPU_COMPARE_IDENTICAL = 1, - VIR_CPU_COMPARE_SUPERSET = 2, + VIR_CPU_COMPARE_ERROR = -1, /* (Since: v0.7.5) */ + VIR_CPU_COMPARE_INCOMPATIBLE = 0, /* (Since: v0.7.5) */ + VIR_CPU_COMPARE_IDENTICAL = 1, /* (Since: v0.7.5) */ + VIR_CPU_COMPARE_SUPERSET = 2, /* (Since: v0.7.5) */ # ifdef VIR_ENUM_SENTINELS - VIR_CPU_COMPARE_LAST + VIR_CPU_COMPARE_LAST /* (Since: v0.9.10) */ # endif } virCPUCompareResult; typedef enum { VIR_CONNECT_COMPARE_CPU_FAIL_INCOMPATIBLE = (1 << 0), /* treat incompatible - CPUs as failure */ + CPUs as failure (Since: v1.2.6) */ VIR_CONNECT_COMPARE_CPU_VALIDATE_XML = (1 << 1), /* validate the xml - document */ + document (Since: v6.9.0) */ } virConnectCompareCPUFlags; int virConnectCompareCPU(virConnectPtr conn, @@ -809,8 +809,8 @@ int virConnectGetCPUModelNames(virConnectPtr conn, * Flags when getting XML description of a computed CPU */ typedef enum { - VIR_CONNECT_BASELINE_CPU_EXPAND_FEATURES = (1 << 0), /* show all features */ - VIR_CONNECT_BASELINE_CPU_MIGRATABLE = (1 << 1), /* filter out non-migratable features */ + VIR_CONNECT_BASELINE_CPU_EXPAND_FEATURES = (1 << 0), /* show all features (Since: v1.1.2) */ + VIR_CONNECT_BASELINE_CPU_MIGRATABLE = (1 << 1), /* filter out non-migratable features (Since: v1.2.14) */ } virConnectBaselineCPUFlags; char *virConnectBaselineCPU(virConnectPtr conn, @@ -837,10 +837,10 @@ int virNodeGetFreePages(virConnectPtr conn, typedef enum { VIR_NODE_ALLOC_PAGES_ADD = 0, /* Add @pageCounts to the pages pool. This - can be used only to size up the pool. */ + can be used only to size up the pool. (Since: v1.2.9) */ VIR_NODE_ALLOC_PAGES_SET = (1 << 0), /* Don't add @pageCounts, instead set passed number of pages. This can be - used to free allocated pages. */ + used to free allocated pages. (Since: v1.2.9) */ } virNodeAllocPagesFlags; int virNodeAllocPages(virConnectPtr conn, diff --git a/include/libvirt/libvirt-interface.h b/include/libvirt/libvirt-interface.h index 803cb33ffe..64bcb08c94 100644 --- a/include/libvirt/libvirt-interface.h +++ b/include/libvirt/libvirt-interface.h @@ -59,8 +59,8 @@ int virConnectListDefinedInterfaces (virConnectPtr conn, * Flags used to filter the returned interfaces. */ typedef enum { - VIR_CONNECT_LIST_INTERFACES_INACTIVE = 1 << 0, - VIR_CONNECT_LIST_INTERFACES_ACTIVE = 1 << 1, + VIR_CONNECT_LIST_INTERFACES_INACTIVE = 1 << 0, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_INTERFACES_ACTIVE = 1 << 1, /* (Since: v0.10.2) */ } virConnectListAllInterfacesFlags; int virConnectListAllInterfaces (virConnectPtr conn, @@ -76,11 +76,11 @@ const char* virInterfaceGetName (virInterfacePtr iface); const char* virInterfaceGetMACString (virInterfacePtr iface); typedef enum { - VIR_INTERFACE_XML_INACTIVE = 1 << 0 /* dump inactive interface information */ + VIR_INTERFACE_XML_INACTIVE = 1 << 0 /* dump inactive interface information (Since: v0.7.3) */ } virInterfaceXMLFlags; typedef enum { - VIR_INTERFACE_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema */ + VIR_INTERFACE_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema (Since: v7.7.0) */ } virInterfaceDefineFlags; char * virInterfaceGetXMLDesc (virInterfacePtr iface, diff --git a/include/libvirt/libvirt-network.h b/include/libvirt/libvirt-network.h index 80bd03878b..ad02e4d5f4 100644 --- a/include/libvirt/libvirt-network.h +++ b/include/libvirt/libvirt-network.h @@ -28,7 +28,7 @@ # endif typedef enum { - VIR_NETWORK_XML_INACTIVE = (1 << 0), /* dump inactive network information */ + VIR_NETWORK_XML_INACTIVE = (1 << 0), /* dump inactive network information (Since: v0.9.10) */ } virNetworkXMLFlags; /** @@ -89,14 +89,14 @@ int virConnectListDefinedNetworks (virConnectPtr conn, * are exclusive attributes of a network. */ typedef enum { - VIR_CONNECT_LIST_NETWORKS_INACTIVE = 1 << 0, - VIR_CONNECT_LIST_NETWORKS_ACTIVE = 1 << 1, + VIR_CONNECT_LIST_NETWORKS_INACTIVE = 1 << 0, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_NETWORKS_ACTIVE = 1 << 1, /* (Since: v0.10.2) */ - VIR_CONNECT_LIST_NETWORKS_PERSISTENT = 1 << 2, - VIR_CONNECT_LIST_NETWORKS_TRANSIENT = 1 << 3, + VIR_CONNECT_LIST_NETWORKS_PERSISTENT = 1 << 2, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_NETWORKS_TRANSIENT = 1 << 3, /* (Since: v0.10.2) */ - VIR_CONNECT_LIST_NETWORKS_AUTOSTART = 1 << 4, - VIR_CONNECT_LIST_NETWORKS_NO_AUTOSTART = 1 << 5, + VIR_CONNECT_LIST_NETWORKS_AUTOSTART = 1 << 4, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_NETWORKS_NO_AUTOSTART = 1 << 5, /* (Since: v0.10.2) */ } virConnectListAllNetworksFlags; int virConnectListAllNetworks (virConnectPtr conn, @@ -114,7 +114,7 @@ virNetworkPtr virNetworkLookupByUUIDString (virConnectPtr conn, const char *uuid); typedef enum { - VIR_NETWORK_CREATE_VALIDATE = 1 << 0, /* Validate the XML document against schema */ + VIR_NETWORK_CREATE_VALIDATE = 1 << 0, /* Validate the XML document against schema (Since: v7.8.0) */ } virNetworkCreateFlags; /* @@ -127,7 +127,7 @@ virNetworkPtr virNetworkCreateXMLFlags(virConnectPtr conn, unsigned int flags); typedef enum { - VIR_NETWORK_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema */ + VIR_NETWORK_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema (Since: v7.7.0) */ } virNetworkDefineFlags; /* @@ -152,13 +152,13 @@ int virNetworkUndefine (virNetworkPtr network); * */ typedef enum { - VIR_NETWORK_UPDATE_COMMAND_NONE = 0, /* (invalid) */ - VIR_NETWORK_UPDATE_COMMAND_MODIFY = 1, /* modify an existing element */ - VIR_NETWORK_UPDATE_COMMAND_DELETE = 2, /* delete an existing element */ - VIR_NETWORK_UPDATE_COMMAND_ADD_LAST = 3, /* add an element at end of list */ - VIR_NETWORK_UPDATE_COMMAND_ADD_FIRST = 4, /* add an element at start of list */ + VIR_NETWORK_UPDATE_COMMAND_NONE = 0, /* (invalid (Since: v0.10.2) */ + VIR_NETWORK_UPDATE_COMMAND_MODIFY = 1, /* modify an existing element (Since: v0.10.2) */ + VIR_NETWORK_UPDATE_COMMAND_DELETE = 2, /* delete an existing element (Since: v0.10.2) */ + VIR_NETWORK_UPDATE_COMMAND_ADD_LAST = 3, /* add an element at end of list (Since: v0.10.2) */ + VIR_NETWORK_UPDATE_COMMAND_ADD_FIRST = 4, /* add an element at start of list (Since: v0.10.2) */ # ifdef VIR_ENUM_SENTINELS - VIR_NETWORK_UPDATE_COMMAND_LAST + VIR_NETWORK_UPDATE_COMMAND_LAST /* (Since: v0.10.2) */ # endif } virNetworkUpdateCommand; @@ -170,21 +170,21 @@ typedef enum { * */ typedef enum { - VIR_NETWORK_SECTION_NONE = 0, /* (invalid) */ - VIR_NETWORK_SECTION_BRIDGE = 1, /* <bridge> */ - VIR_NETWORK_SECTION_DOMAIN = 2, /* <domain> */ - VIR_NETWORK_SECTION_IP = 3, /* <ip> */ - VIR_NETWORK_SECTION_IP_DHCP_HOST = 4, /* <ip>/<dhcp>/<host> */ - VIR_NETWORK_SECTION_IP_DHCP_RANGE = 5, /* <ip>/<dhcp>/<range> */ - VIR_NETWORK_SECTION_FORWARD = 6, /* <forward> */ - VIR_NETWORK_SECTION_FORWARD_INTERFACE = 7, /* <forward>/<interface> */ - VIR_NETWORK_SECTION_FORWARD_PF = 8, /* <forward>/<pf> */ - VIR_NETWORK_SECTION_PORTGROUP = 9, /* <portgroup> */ - VIR_NETWORK_SECTION_DNS_HOST = 10, /* <dns>/<host> */ - VIR_NETWORK_SECTION_DNS_TXT = 11, /* <dns>/<txt> */ - VIR_NETWORK_SECTION_DNS_SRV = 12, /* <dns>/<srv> */ + VIR_NETWORK_SECTION_NONE = 0, /* (invalid (Since: v0.10.2) */ + VIR_NETWORK_SECTION_BRIDGE = 1, /* <bridge> (Since: v0.10.2) */ + VIR_NETWORK_SECTION_DOMAIN = 2, /* <domain> (Since: v0.10.2) */ + VIR_NETWORK_SECTION_IP = 3, /* <ip> (Since: v0.10.2) */ + VIR_NETWORK_SECTION_IP_DHCP_HOST = 4, /* <ip>/<dhcp>/<host> (Since: v0.10.2) */ + VIR_NETWORK_SECTION_IP_DHCP_RANGE = 5, /* <ip>/<dhcp>/<range> (Since: v0.10.2) */ + VIR_NETWORK_SECTION_FORWARD = 6, /* <forward> (Since: v0.10.2) */ + VIR_NETWORK_SECTION_FORWARD_INTERFACE = 7, /* <forward>/<interface> (Since: v0.10.2) */ + VIR_NETWORK_SECTION_FORWARD_PF = 8, /* <forward>/<pf> (Since: v0.10.2) */ + VIR_NETWORK_SECTION_PORTGROUP = 9, /* <portgroup> (Since: v0.10.2) */ + VIR_NETWORK_SECTION_DNS_HOST = 10, /* <dns>/<host> (Since: v0.10.2) */ + VIR_NETWORK_SECTION_DNS_TXT = 11, /* <dns>/<txt> (Since: v0.10.2) */ + VIR_NETWORK_SECTION_DNS_SRV = 12, /* <dns>/<srv> (Since: v0.10.2) */ # ifdef VIR_ENUM_SENTINELS - VIR_NETWORK_SECTION_LAST + VIR_NETWORK_SECTION_LAST /* (Since: v0.10.2) */ # endif } virNetworkUpdateSection; @@ -195,9 +195,9 @@ typedef enum { */ typedef enum { VIR_NETWORK_UPDATE_AFFECT_CURRENT = 0, /* affect live if network is active, - config if it's not active */ - VIR_NETWORK_UPDATE_AFFECT_LIVE = 1 << 0, /* affect live state of network only */ - VIR_NETWORK_UPDATE_AFFECT_CONFIG = 1 << 1, /* affect persistent config only */ + config if it's not active (Since: v0.10.2) */ + VIR_NETWORK_UPDATE_AFFECT_LIVE = 1 << 0, /* affect live state of network only (Since: v0.10.2) */ + VIR_NETWORK_UPDATE_AFFECT_CONFIG = 1 << 1, /* affect persistent config only (Since: v0.10.2) */ } virNetworkUpdateFlags; /* @@ -248,13 +248,13 @@ int virNetworkIsPersistent(virNetworkPtr net); * a virNetworkEventLifecycleType is emitted during network lifecycle events */ typedef enum { - VIR_NETWORK_EVENT_DEFINED = 0, - VIR_NETWORK_EVENT_UNDEFINED = 1, - VIR_NETWORK_EVENT_STARTED = 2, - VIR_NETWORK_EVENT_STOPPED = 3, + VIR_NETWORK_EVENT_DEFINED = 0, /* (Since: v1.2.1) */ + VIR_NETWORK_EVENT_UNDEFINED = 1, /* (Since: v1.2.1) */ + VIR_NETWORK_EVENT_STARTED = 2, /* (Since: v1.2.1) */ + VIR_NETWORK_EVENT_STOPPED = 3, /* (Since: v1.2.1) */ # ifdef VIR_ENUM_SENTINELS - VIR_NETWORK_EVENT_LAST + VIR_NETWORK_EVENT_LAST /* (Since: v1.2.1) */ # endif } virNetworkEventLifecycleType; @@ -294,7 +294,7 @@ typedef void (*virConnectNetworkEventLifecycleCallback)(virConnectPtr conn, * signature of callback function will be used. */ typedef enum { - VIR_NETWORK_EVENT_ID_LIFECYCLE = 0, /* virConnectNetworkEventLifecycleCallback */ + VIR_NETWORK_EVENT_ID_LIFECYCLE = 0, /* virConnectNetworkEventLifecycleCallback (Since: v1.2.1) */ # ifdef VIR_ENUM_SENTINELS VIR_NETWORK_EVENT_ID_LAST @@ -302,16 +302,18 @@ typedef enum { * NB: this enum value will increase over time as new events are * added to the libvirt API. It reflects the last event ID supported * by this version of the libvirt API. + * + * Since: v1.2.1 */ # endif } virNetworkEventID; typedef enum { - VIR_IP_ADDR_TYPE_IPV4, - VIR_IP_ADDR_TYPE_IPV6, + VIR_IP_ADDR_TYPE_IPV4, /* (Since: v1.2.6) */ + VIR_IP_ADDR_TYPE_IPV6, /* (Since: v1.2.6) */ # ifdef VIR_ENUM_SENTINELS - VIR_IP_ADDR_TYPE_LAST + VIR_IP_ADDR_TYPE_LAST /* (Since: v1.2.6) */ # endif } virIPAddrType; @@ -373,8 +375,8 @@ virNetworkPortLookupByUUIDString(virNetworkPtr net, const char *uuidstr); typedef enum { - VIR_NETWORK_PORT_CREATE_RECLAIM = (1 << 0), /* reclaim existing used resources */ - VIR_NETWORK_PORT_CREATE_VALIDATE = (1 << 1), /* Validate the XML document against schema */ + VIR_NETWORK_PORT_CREATE_RECLAIM = (1 << 0), /* reclaim existing used resources (Since: v5.5.0) */ + VIR_NETWORK_PORT_CREATE_VALIDATE = (1 << 1), /* Validate the XML document against schema (Since: v7.8.0) */ } virNetworkPortCreateFlags; virNetworkPortPtr diff --git a/include/libvirt/libvirt-nodedev.h b/include/libvirt/libvirt-nodedev.h index 8efcd7f506..4e68d09814 100644 --- a/include/libvirt/libvirt-nodedev.h +++ b/include/libvirt/libvirt-nodedev.h @@ -63,31 +63,31 @@ int virNodeListDevices (virConnectPtr conn, * Flags used to filter either by capability or active state, the * returned node devices. */ typedef enum { - VIR_CONNECT_LIST_NODE_DEVICES_CAP_SYSTEM = 1 << 0, /* System capability */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_PCI_DEV = 1 << 1, /* PCI device */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_USB_DEV = 1 << 2, /* USB device */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_USB_INTERFACE = 1 << 3, /* USB interface */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_NET = 1 << 4, /* Network device */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_HOST = 1 << 5, /* SCSI Host Bus Adapter */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_TARGET = 1 << 6, /* SCSI Target */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI = 1 << 7, /* SCSI device */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_STORAGE = 1 << 8, /* Storage device */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_FC_HOST = 1 << 9, /* FC Host Bus Adapter */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_VPORTS = 1 << 10, /* Capable of vport */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_GENERIC = 1 << 11, /* Capable of scsi_generic */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_DRM = 1 << 12, /* DRM device */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_MDEV_TYPES = 1 << 13, /* Capable of mediated devices */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_MDEV = 1 << 14, /* Mediated device */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_CCW_DEV = 1 << 15, /* CCW device */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_CSS_DEV = 1 << 16, /* CSS device */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_VDPA = 1 << 17, /* vDPA device */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_AP_CARD = 1 << 18, /* s390 AP Card device */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_AP_QUEUE = 1 << 19, /* s390 AP Queue */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_AP_MATRIX = 1 << 20, /* s390 AP Matrix */ - VIR_CONNECT_LIST_NODE_DEVICES_CAP_VPD = 1 << 21, /* Device with VPD */ - - VIR_CONNECT_LIST_NODE_DEVICES_INACTIVE = 1 << 30, /* Inactive devices */ - VIR_CONNECT_LIST_NODE_DEVICES_ACTIVE = 1U << 31, /* Active devices */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_SYSTEM = 1 << 0, /* System capability (Since: v0.10.2) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_PCI_DEV = 1 << 1, /* PCI device (Since: v0.10.2) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_USB_DEV = 1 << 2, /* USB device (Since: v0.10.2) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_USB_INTERFACE = 1 << 3, /* USB interface (Since: v0.10.2) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_NET = 1 << 4, /* Network device (Since: v0.10.2) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_HOST = 1 << 5, /* SCSI Host Bus Adapter (Since: v0.10.2) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_TARGET = 1 << 6, /* SCSI Target (Since: v0.10.2) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI = 1 << 7, /* SCSI device (Since: v0.10.2) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_STORAGE = 1 << 8, /* Storage device (Since: v0.10.2) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_FC_HOST = 1 << 9, /* FC Host Bus Adapter (Since: v1.0.4) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_VPORTS = 1 << 10, /* Capable of vport (Since: v1.0.4) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_GENERIC = 1 << 11, /* Capable of scsi_generic (Since: v1.1.0) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_DRM = 1 << 12, /* DRM device (Since: v3.1.0) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_MDEV_TYPES = 1 << 13, /* Capable of mediated devices (Since: v3.4.0) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_MDEV = 1 << 14, /* Mediated device (Since: v3.4.0) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_CCW_DEV = 1 << 15, /* CCW device (Since: v3.4.0) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_CSS_DEV = 1 << 16, /* CSS device (Since: v6.8.0) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_VDPA = 1 << 17, /* vDPA device (Since: v6.9.0) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_AP_CARD = 1 << 18, /* s390 AP Card device (Since: v7.0.0) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_AP_QUEUE = 1 << 19, /* s390 AP Queue (Since: v7.0.0) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_AP_MATRIX = 1 << 20, /* s390 AP Matrix (Since: v7.0.0) */ + VIR_CONNECT_LIST_NODE_DEVICES_CAP_VPD = 1 << 21, /* Device with VPD (Since: v7.9.0) */ + + VIR_CONNECT_LIST_NODE_DEVICES_INACTIVE = 1 << 30, /* Inactive devices (Since: v7.3.0) */ + VIR_CONNECT_LIST_NODE_DEVICES_ACTIVE = 1U << 31, /* Active devices (Since: v7.3.0) */ } virConnectListAllNodeDeviceFlags; int virConnectListAllNodeDevices (virConnectPtr conn, @@ -167,8 +167,8 @@ int virNodeDeviceIsActive(virNodeDevicePtr dev); * signature of callback function will be used. */ typedef enum { - VIR_NODE_DEVICE_EVENT_ID_LIFECYCLE = 0, /* virConnectNodeDeviceEventLifecycleCallback */ - VIR_NODE_DEVICE_EVENT_ID_UPDATE = 1, /* virConnectNodeDeviceEventGenericCallback */ + VIR_NODE_DEVICE_EVENT_ID_LIFECYCLE = 0, /* virConnectNodeDeviceEventLifecycleCallback (Since: v2.2.0) */ + VIR_NODE_DEVICE_EVENT_ID_UPDATE = 1, /* virConnectNodeDeviceEventGenericCallback (Since: v2.2.0) */ # ifdef VIR_ENUM_SENTINELS VIR_NODE_DEVICE_EVENT_ID_LAST @@ -176,6 +176,8 @@ typedef enum { * NB: this enum value will increase over time as new events are * added to the libvirt API. It reflects the last event ID supported * by this version of the libvirt API. + * + * Since: v2.2.0 */ # endif } virNodeDeviceEventID; @@ -214,13 +216,13 @@ int virConnectNodeDeviceEventDeregisterAny(virConnectPtr conn, * lifecycle events */ typedef enum { - VIR_NODE_DEVICE_EVENT_CREATED = 0, - VIR_NODE_DEVICE_EVENT_DELETED = 1, - VIR_NODE_DEVICE_EVENT_DEFINED = 2, - VIR_NODE_DEVICE_EVENT_UNDEFINED = 3, + VIR_NODE_DEVICE_EVENT_CREATED = 0, /* (Since: v2.2.0) */ + VIR_NODE_DEVICE_EVENT_DELETED = 1, /* (Since: v2.2.0) */ + VIR_NODE_DEVICE_EVENT_DEFINED = 2, /* (Since: v7.3.0) */ + VIR_NODE_DEVICE_EVENT_UNDEFINED = 3, /* (Since: v7.3.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_NODE_DEVICE_EVENT_LAST + VIR_NODE_DEVICE_EVENT_LAST /* (Since: v2.2.0) */ # endif } virNodeDeviceEventLifecycleType; diff --git a/include/libvirt/libvirt-nwfilter.h b/include/libvirt/libvirt-nwfilter.h index 4e28801006..aa8872e156 100644 --- a/include/libvirt/libvirt-nwfilter.h +++ b/include/libvirt/libvirt-nwfilter.h @@ -81,7 +81,7 @@ virNWFilterPtr virNWFilterLookupByUUIDString (virConnectPtr conn, const char *uuid); typedef enum { - VIR_NWFILTER_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema */ + VIR_NWFILTER_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema (Since: v7.7.0) */ } virNWFilterDefineFlags; /* @@ -109,7 +109,7 @@ int virNWFilterFree (virNWFilterPtr nwfilter); */ typedef enum { - VIR_NWFILTER_BINDING_CREATE_VALIDATE = 1 << 0, /* Validate the XML document against schema */ + VIR_NWFILTER_BINDING_CREATE_VALIDATE = 1 << 0, /* Validate the XML document against schema (Since: v7.8.0) */ } virNWFilterBindingCreateFlags; const char* virNWFilterGetName (virNWFilterPtr nwfilter); diff --git a/include/libvirt/libvirt-secret.h b/include/libvirt/libvirt-secret.h index 82e18b8611..94722a46af 100644 --- a/include/libvirt/libvirt-secret.h +++ b/include/libvirt/libvirt-secret.h @@ -38,12 +38,12 @@ typedef struct _virSecret virSecret; typedef virSecret *virSecretPtr; typedef enum { - VIR_SECRET_USAGE_TYPE_NONE = 0, - VIR_SECRET_USAGE_TYPE_VOLUME = 1, - VIR_SECRET_USAGE_TYPE_CEPH = 2, - VIR_SECRET_USAGE_TYPE_ISCSI = 3, - VIR_SECRET_USAGE_TYPE_TLS = 4, - VIR_SECRET_USAGE_TYPE_VTPM = 5, + VIR_SECRET_USAGE_TYPE_NONE = 0, /* (Since: v0.7.1) */ + VIR_SECRET_USAGE_TYPE_VOLUME = 1, /* (Since: v0.7.1) */ + VIR_SECRET_USAGE_TYPE_CEPH = 2, /* (Since: v0.9.7) */ + VIR_SECRET_USAGE_TYPE_ISCSI = 3, /* (Since: v1.0.4) */ + VIR_SECRET_USAGE_TYPE_TLS = 4, /* (Since: v2.3.0) */ + VIR_SECRET_USAGE_TYPE_VTPM = 5, /* (Since: v5.6.0) */ # ifdef VIR_ENUM_SENTINELS VIR_SECRET_USAGE_TYPE_LAST @@ -51,6 +51,8 @@ typedef enum { * NB: this enum value will increase over time as new usage types are * added to the libvirt API. It reflects the last usage type supported * by this version of the libvirt API. + * + * Since: v0.9.7 */ # endif } virSecretUsageType; @@ -69,13 +71,13 @@ int virConnectListSecrets (virConnectPtr conn, */ typedef enum { VIR_CONNECT_LIST_SECRETS_EPHEMERAL = 1 << 0, /* kept in memory, never - stored persistently */ - VIR_CONNECT_LIST_SECRETS_NO_EPHEMERAL = 1 << 1, + stored persistently (Since: v0.10.2) */ + VIR_CONNECT_LIST_SECRETS_NO_EPHEMERAL = 1 << 1, /* (Since: v0.10.2) */ VIR_CONNECT_LIST_SECRETS_PRIVATE = 1 << 2, /* not revealed to any caller of libvirt, nor to any other - node */ - VIR_CONNECT_LIST_SECRETS_NO_PRIVATE = 1 << 3, + node (Since: v0.10.2) */ + VIR_CONNECT_LIST_SECRETS_NO_PRIVATE = 1 << 3, /* (Since: v0.10.2) */ } virConnectListAllSecretsFlags; int virConnectListAllSecrets(virConnectPtr conn, @@ -90,7 +92,7 @@ virSecretPtr virSecretLookupByUsage(virConnectPtr conn, const char *usageID); typedef enum { - VIR_SECRET_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema */ + VIR_SECRET_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema (Since: v7.7.0) */ } virSecretDefineFlags; virSecretPtr virSecretDefineXML (virConnectPtr conn, @@ -131,8 +133,8 @@ int virSecretFree (virSecretPtr secret); * signature of callback function will be used. */ typedef enum { - VIR_SECRET_EVENT_ID_LIFECYCLE = 0, /* virConnectSecretEventLifecycleCallback */ - VIR_SECRET_EVENT_ID_VALUE_CHANGED = 1, /* virConnectSecretEventGenericCallback */ + VIR_SECRET_EVENT_ID_LIFECYCLE = 0, /* virConnectSecretEventLifecycleCallback (Since: v3.0.0) */ + VIR_SECRET_EVENT_ID_VALUE_CHANGED = 1, /* virConnectSecretEventGenericCallback (Since: v3.0.0) */ # ifdef VIR_ENUM_SENTINELS VIR_SECRET_EVENT_ID_LAST @@ -140,6 +142,8 @@ typedef enum { * NB: this enum value will increase over time as new events are * added to the libvirt API. It reflects the last event ID supported * by this version of the libvirt API. + * + * Since: v3.0.0 */ # endif } virSecretEventID; @@ -178,11 +182,11 @@ int virConnectSecretEventDeregisterAny(virConnectPtr conn, * lifecycle events */ typedef enum { - VIR_SECRET_EVENT_DEFINED = 0, - VIR_SECRET_EVENT_UNDEFINED = 1, + VIR_SECRET_EVENT_DEFINED = 0, /* (Since: v3.0.0) */ + VIR_SECRET_EVENT_UNDEFINED = 1, /* (Since: v3.0.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_SECRET_EVENT_LAST + VIR_SECRET_EVENT_LAST /* (Since: v3.0.0) */ # endif } virSecretEventLifecycleType; diff --git a/include/libvirt/libvirt-storage.h b/include/libvirt/libvirt-storage.h index bee738880d..9ffcdc6180 100644 --- a/include/libvirt/libvirt-storage.h +++ b/include/libvirt/libvirt-storage.h @@ -45,45 +45,51 @@ typedef virStoragePool *virStoragePoolPtr; typedef enum { - VIR_STORAGE_POOL_INACTIVE = 0, /* Not running */ - VIR_STORAGE_POOL_BUILDING = 1, /* Initializing pool, not available */ - VIR_STORAGE_POOL_RUNNING = 2, /* Running normally */ - VIR_STORAGE_POOL_DEGRADED = 3, /* Running degraded */ - VIR_STORAGE_POOL_INACCESSIBLE = 4, /* Running, but not accessible */ + VIR_STORAGE_POOL_INACTIVE = 0, /* Not running (Since: v0.4.1) */ + VIR_STORAGE_POOL_BUILDING = 1, /* Initializing pool, not available (Since: v0.4.1) */ + VIR_STORAGE_POOL_RUNNING = 2, /* Running normally (Since: v0.4.1) */ + VIR_STORAGE_POOL_DEGRADED = 3, /* Running degraded (Since: v0.4.1) */ + VIR_STORAGE_POOL_INACCESSIBLE = 4, /* Running, but not accessible (Since: v0.8.2) */ # ifdef VIR_ENUM_SENTINELS - VIR_STORAGE_POOL_STATE_LAST + VIR_STORAGE_POOL_STATE_LAST /* (Since: v0.9.10) */ # endif } virStoragePoolState; typedef enum { - VIR_STORAGE_POOL_BUILD_NEW = 0, /* Regular build from scratch */ - VIR_STORAGE_POOL_BUILD_REPAIR = (1 << 0), /* Repair / reinitialize */ - VIR_STORAGE_POOL_BUILD_RESIZE = (1 << 1), /* Extend existing pool */ - VIR_STORAGE_POOL_BUILD_NO_OVERWRITE = (1 << 2), /* Do not overwrite existing pool */ - VIR_STORAGE_POOL_BUILD_OVERWRITE = (1 << 3), /* Overwrite data */ + VIR_STORAGE_POOL_BUILD_NEW = 0, /* Regular build from scratch (Since: v0.4.1) */ + VIR_STORAGE_POOL_BUILD_REPAIR = (1 << 0), /* Repair / reinitialize (Since: v0.4.1) */ + VIR_STORAGE_POOL_BUILD_RESIZE = (1 << 1), /* Extend existing pool (Since: v0.4.1) */ + VIR_STORAGE_POOL_BUILD_NO_OVERWRITE = (1 << 2), /* Do not overwrite existing pool (Since: v0.9.5) */ + VIR_STORAGE_POOL_BUILD_OVERWRITE = (1 << 3), /* Overwrite data (Since: v0.9.5) */ } virStoragePoolBuildFlags; typedef enum { - VIR_STORAGE_POOL_DELETE_NORMAL = 0, /* Delete metadata only (fast) */ - VIR_STORAGE_POOL_DELETE_ZEROED = 1 << 0, /* Clear all data to zeros (slow) */ + VIR_STORAGE_POOL_DELETE_NORMAL = 0, /* Delete metadata only (fast) (Since: v0.4.1) */ + VIR_STORAGE_POOL_DELETE_ZEROED = 1 << 0, /* Clear all data to zeros (slow) (Since: v0.4.1) */ } virStoragePoolDeleteFlags; typedef enum { - /* Create the pool but do not perform pool build */ + /* Create the pool but do not perform pool build (Since: v1.3.1) */ VIR_STORAGE_POOL_CREATE_NORMAL = 0, - /* Create the pool and perform pool build without any flags */ + /* Create the pool and perform pool build without any flags (Since: v1.3.1) */ VIR_STORAGE_POOL_CREATE_WITH_BUILD = 1 << 0, /* Create the pool and perform pool build using the * VIR_STORAGE_POOL_BUILD_OVERWRITE flag. This is mutually - * exclusive to VIR_STORAGE_POOL_CREATE_WITH_BUILD_NO_OVERWRITE */ + * exclusive to VIR_STORAGE_POOL_CREATE_WITH_BUILD_NO_OVERWRITE + * + * Since: v1.3.1 + */ VIR_STORAGE_POOL_CREATE_WITH_BUILD_OVERWRITE = 1 << 1, /* Create the pool and perform pool build using the * VIR_STORAGE_POOL_BUILD_NO_OVERWRITE flag. This is mutually - * exclusive to VIR_STORAGE_POOL_CREATE_WITH_BUILD_OVERWRITE */ + * exclusive to VIR_STORAGE_POOL_CREATE_WITH_BUILD_OVERWRITE + * + * Since: v1.3.1 + */ VIR_STORAGE_POOL_CREATE_WITH_BUILD_NO_OVERWRITE = 1 << 2, } virStoragePoolCreateFlags; @@ -116,46 +122,46 @@ typedef virStorageVol *virStorageVolPtr; typedef enum { - VIR_STORAGE_VOL_FILE = 0, /* Regular file based volumes */ - VIR_STORAGE_VOL_BLOCK = 1, /* Block based volumes */ - VIR_STORAGE_VOL_DIR = 2, /* Directory-passthrough based volume */ - VIR_STORAGE_VOL_NETWORK = 3, /* Network volumes like RBD (RADOS Block Device) */ + VIR_STORAGE_VOL_FILE = 0, /* Regular file based volumes (Since: v0.4.1) */ + VIR_STORAGE_VOL_BLOCK = 1, /* Block based volumes (Since: v0.4.1) */ + VIR_STORAGE_VOL_DIR = 2, /* Directory-passthrough based volume (Since: v0.9.5) */ + VIR_STORAGE_VOL_NETWORK = 3, /* Network volumes like RBD (RADOS Block Device) (Since: v0.9.13) */ VIR_STORAGE_VOL_NETDIR = 4, /* Network accessible directory that can - * contain other network volumes */ - VIR_STORAGE_VOL_PLOOP = 5, /* Ploop based volumes */ + * contain other network volumes (Since: v1.2.0) */ + VIR_STORAGE_VOL_PLOOP = 5, /* Ploop based volumes (Since: v1.3.4) */ # ifdef VIR_ENUM_SENTINELS - VIR_STORAGE_VOL_LAST + VIR_STORAGE_VOL_LAST /* (Since: v0.9.10) */ # endif } virStorageVolType; typedef enum { - VIR_STORAGE_VOL_DELETE_NORMAL = 0, /* Delete metadata only (fast) */ - VIR_STORAGE_VOL_DELETE_ZEROED = 1 << 0, /* Clear all data to zeros (slow) */ - VIR_STORAGE_VOL_DELETE_WITH_SNAPSHOTS = 1 << 1, /* Force removal of volume, even if in use */ + VIR_STORAGE_VOL_DELETE_NORMAL = 0, /* Delete metadata only (fast) (Since: v0.4.1) */ + VIR_STORAGE_VOL_DELETE_ZEROED = 1 << 0, /* Clear all data to zeros (slow) (Since: v0.4.1) */ + VIR_STORAGE_VOL_DELETE_WITH_SNAPSHOTS = 1 << 1, /* Force removal of volume, even if in use (Since: v1.2.21) */ } virStorageVolDeleteFlags; typedef enum { - VIR_STORAGE_VOL_WIPE_ALG_ZERO = 0, /* 1-pass, all zeroes */ + VIR_STORAGE_VOL_WIPE_ALG_ZERO = 0, /* 1-pass, all zeroes (Since: v0.9.10) */ VIR_STORAGE_VOL_WIPE_ALG_NNSA = 1, /* 4-pass NNSA Policy Letter - NAP-14.1-C (XVI-8) */ + NAP-14.1-C (XVI-8) (Since: v0.9.10) */ VIR_STORAGE_VOL_WIPE_ALG_DOD = 2, /* 4-pass DoD 5220.22-M section - 8-306 procedure */ + 8-306 procedure (Since: v0.9.10) */ VIR_STORAGE_VOL_WIPE_ALG_BSI = 3, /* 9-pass method recommended by the German Center of Security in - Information Technologies */ - VIR_STORAGE_VOL_WIPE_ALG_GUTMANN = 4, /* The canonical 35-pass sequence */ + Information Technologies (Since: v0.9.10) */ + VIR_STORAGE_VOL_WIPE_ALG_GUTMANN = 4, /* The canonical 35-pass sequence (Since: v0.9.10) */ VIR_STORAGE_VOL_WIPE_ALG_SCHNEIER = 5, /* 7-pass method described by Bruce Schneier in "Applied - Cryptography" (1996) */ - VIR_STORAGE_VOL_WIPE_ALG_PFITZNER7 = 6, /* 7-pass random */ + Cryptography" (1996) (Since: v0.9.10) */ + VIR_STORAGE_VOL_WIPE_ALG_PFITZNER7 = 6, /* 7-pass random (Since: v0.9.10) */ - VIR_STORAGE_VOL_WIPE_ALG_PFITZNER33 = 7, /* 33-pass random */ + VIR_STORAGE_VOL_WIPE_ALG_PFITZNER33 = 7, /* 33-pass random (Since: v0.9.10) */ - VIR_STORAGE_VOL_WIPE_ALG_RANDOM = 8, /* 1-pass random */ + VIR_STORAGE_VOL_WIPE_ALG_RANDOM = 8, /* 1-pass random (Since: v0.9.10) */ VIR_STORAGE_VOL_WIPE_ALG_TRIM = 9, /* 1-pass, trim all data on the - volume by using TRIM or DISCARD */ + volume by using TRIM or DISCARD (Since: v1.3.2) */ # ifdef VIR_ENUM_SENTINELS VIR_STORAGE_VOL_WIPE_ALG_LAST @@ -163,6 +169,8 @@ typedef enum { * NB: this enum value will increase over time as new algorithms are * added to the libvirt API. It reflects the last algorithm supported * by this version of the libvirt API. + * + * Since: v0.9.10 */ # endif } virStorageVolWipeAlgorithm; @@ -186,7 +194,7 @@ struct _virStorageVolInfo { typedef virStorageVolInfo *virStorageVolInfoPtr; typedef enum { - VIR_STORAGE_XML_INACTIVE = (1 << 0), /* dump inactive pool/volume information */ + VIR_STORAGE_XML_INACTIVE = (1 << 0), /* dump inactive pool/volume information (Since: v0.9.13) */ } virStorageXMLFlags; /* @@ -273,7 +281,7 @@ virStoragePoolPtr virStoragePoolLookupByTargetPath(virConnectPtr conn, const char *path); typedef enum { - VIR_STORAGE_POOL_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema */ + VIR_STORAGE_POOL_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema (Since: v7.7.0) */ } virStoragePoolDefineFlags; /* @@ -346,8 +354,8 @@ const char* virStorageVolGetName (virStorageVolPtr vol); const char* virStorageVolGetKey (virStorageVolPtr vol); typedef enum { - VIR_STORAGE_VOL_CREATE_PREALLOC_METADATA = 1 << 0, - VIR_STORAGE_VOL_CREATE_REFLINK = 1 << 1, /* perform a btrfs lightweight copy */ + VIR_STORAGE_VOL_CREATE_PREALLOC_METADATA = 1 << 0, /* (Since: v1.0.1) */ + VIR_STORAGE_VOL_CREATE_REFLINK = 1 << 1, /* perform a btrfs lightweight copy (Since: v1.2.13) */ } virStorageVolCreateFlags; virStorageVolPtr virStorageVolCreateXML (virStoragePoolPtr pool, @@ -359,7 +367,7 @@ virStorageVolPtr virStorageVolCreateXMLFrom (virStoragePoolPtr pool, unsigned int flags); typedef enum { - VIR_STORAGE_VOL_DOWNLOAD_SPARSE_STREAM = 1 << 0, /* Use sparse stream */ + VIR_STORAGE_VOL_DOWNLOAD_SPARSE_STREAM = 1 << 0, /* Use sparse stream (Since: v3.4.0) */ } virStorageVolDownloadFlags; int virStorageVolDownload (virStorageVolPtr vol, @@ -368,7 +376,7 @@ int virStorageVolDownload (virStorageVolPtr vol, unsigned long long length, unsigned int flags); typedef enum { - VIR_STORAGE_VOL_UPLOAD_SPARSE_STREAM = 1 << 0, /* Use sparse stream */ + VIR_STORAGE_VOL_UPLOAD_SPARSE_STREAM = 1 << 0, /* Use sparse stream (Since: v3.4.0) */ } virStorageVolUploadFlags; int virStorageVolUpload (virStorageVolPtr vol, @@ -397,9 +405,9 @@ char * virStorageVolGetXMLDesc (virStorageVolPtr pool, char * virStorageVolGetPath (virStorageVolPtr vol); typedef enum { - VIR_STORAGE_VOL_RESIZE_ALLOCATE = 1 << 0, /* force allocation of new size */ - VIR_STORAGE_VOL_RESIZE_DELTA = 1 << 1, /* size is relative to current */ - VIR_STORAGE_VOL_RESIZE_SHRINK = 1 << 2, /* allow decrease in capacity */ + VIR_STORAGE_VOL_RESIZE_ALLOCATE = 1 << 0, /* force allocation of new size (Since: v0.9.10) */ + VIR_STORAGE_VOL_RESIZE_DELTA = 1 << 1, /* size is relative to current (Since: v0.9.10) */ + VIR_STORAGE_VOL_RESIZE_SHRINK = 1 << 2, /* allow decrease in capacity (Since: v0.9.10) */ } virStorageVolResizeFlags; int virStorageVolResize (virStorageVolPtr vol, @@ -425,8 +433,8 @@ int virStoragePoolIsPersistent(virStoragePoolPtr pool); * signature of callback function will be used. */ typedef enum { - VIR_STORAGE_POOL_EVENT_ID_LIFECYCLE = 0, /* virConnectStoragePoolEventLifecycleCallback */ - VIR_STORAGE_POOL_EVENT_ID_REFRESH = 1, /* virConnectStoragePoolEventGenericCallback */ + VIR_STORAGE_POOL_EVENT_ID_LIFECYCLE = 0, /* virConnectStoragePoolEventLifecycleCallback (Since: v2.0.0) */ + VIR_STORAGE_POOL_EVENT_ID_REFRESH = 1, /* virConnectStoragePoolEventGenericCallback (Since: v2.0.0) */ # ifdef VIR_ENUM_SENTINELS VIR_STORAGE_POOL_EVENT_ID_LAST @@ -434,6 +442,8 @@ typedef enum { * NB: this enum value will increase over time as new events are * added to the libvirt API. It reflects the last event ID supported * by this version of the libvirt API. + * + * Since: v2.0.0 */ # endif } virStoragePoolEventID; @@ -472,15 +482,15 @@ int virConnectStoragePoolEventDeregisterAny(virConnectPtr conn, * lifecycle events */ typedef enum { - VIR_STORAGE_POOL_EVENT_DEFINED = 0, - VIR_STORAGE_POOL_EVENT_UNDEFINED = 1, - VIR_STORAGE_POOL_EVENT_STARTED = 2, - VIR_STORAGE_POOL_EVENT_STOPPED = 3, - VIR_STORAGE_POOL_EVENT_CREATED = 4, - VIR_STORAGE_POOL_EVENT_DELETED = 5, + VIR_STORAGE_POOL_EVENT_DEFINED = 0, /* (Since: v2.0.0) */ + VIR_STORAGE_POOL_EVENT_UNDEFINED = 1, /* (Since: v2.0.0) */ + VIR_STORAGE_POOL_EVENT_STARTED = 2, /* (Since: v2.0.0) */ + VIR_STORAGE_POOL_EVENT_STOPPED = 3, /* (Since: v2.0.0) */ + VIR_STORAGE_POOL_EVENT_CREATED = 4, /* (Since: v3.8.0) */ + VIR_STORAGE_POOL_EVENT_DELETED = 5, /* (Since: v3.8.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_STORAGE_POOL_EVENT_LAST + VIR_STORAGE_POOL_EVENT_LAST /* (Since: v2.0.0) */ # endif } virStoragePoolEventLifecycleType; diff --git a/include/libvirt/libvirt-stream.h b/include/libvirt/libvirt-stream.h index 076f9ee8b8..d69131030b 100644 --- a/include/libvirt/libvirt-stream.h +++ b/include/libvirt/libvirt-stream.h @@ -29,7 +29,7 @@ typedef enum { - VIR_STREAM_NONBLOCK = (1 << 0), + VIR_STREAM_NONBLOCK = (1 << 0), /* (Since: v0.7.2) */ } virStreamFlags; virStreamPtr virStreamNew(virConnectPtr conn, @@ -45,7 +45,7 @@ int virStreamRecv(virStreamPtr st, size_t nbytes); typedef enum { - VIR_STREAM_RECV_STOP_AT_HOLE = (1 << 0), + VIR_STREAM_RECV_STOP_AT_HOLE = (1 << 0), /* (Since: v3.4.0) */ } virStreamRecvFlagsValues; int virStreamRecvFlags(virStreamPtr st, @@ -230,10 +230,10 @@ int virStreamSparseRecvAll(virStreamPtr stream, void *opaque); typedef enum { - VIR_STREAM_EVENT_READABLE = (1 << 0), - VIR_STREAM_EVENT_WRITABLE = (1 << 1), - VIR_STREAM_EVENT_ERROR = (1 << 2), - VIR_STREAM_EVENT_HANGUP = (1 << 3), + VIR_STREAM_EVENT_READABLE = (1 << 0), /* (Since: v0.7.2) */ + VIR_STREAM_EVENT_WRITABLE = (1 << 1), /* (Since: v0.7.2) */ + VIR_STREAM_EVENT_ERROR = (1 << 2), /* (Since: v0.7.2) */ + VIR_STREAM_EVENT_HANGUP = (1 << 3), /* (Since: v0.7.2) */ } virStreamEventType; diff --git a/include/libvirt/virterror.h b/include/libvirt/virterror.h index 57986931fd..3c1b27a36f 100644 --- a/include/libvirt/virterror.h +++ b/include/libvirt/virterror.h @@ -36,9 +36,9 @@ extern "C" { * Indicates the level of an error */ typedef enum { - VIR_ERR_NONE = 0, - VIR_ERR_WARNING = 1, /* A simple warning */ - VIR_ERR_ERROR = 2 /* An error */ + VIR_ERR_NONE = 0, /* (Since: v0.1.0) */ + VIR_ERR_WARNING = 1, /* A simple warning (Since: v0.1.0) */ + VIR_ERR_ERROR = 2 /* An error (Since: v0.1.0) */ } virErrorLevel; /** @@ -48,98 +48,98 @@ typedef enum { * stable, with all additions placed at the end since libvirt 0.1.0. */ typedef enum { - VIR_FROM_NONE = 0, - VIR_FROM_XEN = 1, /* Error at Xen hypervisor layer */ - VIR_FROM_XEND = 2, /* Error at connection with xend daemon */ - VIR_FROM_XENSTORE = 3, /* Error at connection with xen store */ - VIR_FROM_SEXPR = 4, /* Error in the S-Expression code */ - - VIR_FROM_XML = 5, /* Error in the XML code */ - VIR_FROM_DOM = 6, /* Error when operating on a domain */ - VIR_FROM_RPC = 7, /* Error in the XML-RPC code */ + VIR_FROM_NONE = 0, /* (Since: v0.1.0) */ + VIR_FROM_XEN = 1, /* Error at Xen hypervisor layer (Since: v0.1.0) */ + VIR_FROM_XEND = 2, /* Error at connection with xend daemon (Since: v0.1.0) */ + VIR_FROM_XENSTORE = 3, /* Error at connection with xen store (Since: v0.1.0) */ + VIR_FROM_SEXPR = 4, /* Error in the S-Expression code (Since: v0.1.0) */ + + VIR_FROM_XML = 5, /* Error in the XML code (Since: v0.1.0) */ + VIR_FROM_DOM = 6, /* Error when operating on a domain (Since: v0.1.0) */ + VIR_FROM_RPC = 7, /* Error in the XML-RPC code (Since: v0.1.1) */ VIR_FROM_PROXY = 8, /* Error in the proxy code; unused since - 0.8.6 */ - VIR_FROM_CONF = 9, /* Error in the configuration file handling */ - - VIR_FROM_QEMU = 10, /* Error at the QEMU daemon */ - VIR_FROM_NET = 11, /* Error when operating on a network */ - VIR_FROM_TEST = 12, /* Error from test driver */ - VIR_FROM_REMOTE = 13, /* Error from remote driver */ - VIR_FROM_OPENVZ = 14, /* Error from OpenVZ driver */ - - VIR_FROM_XENXM = 15, /* Error at Xen XM layer */ - VIR_FROM_STATS_LINUX = 16, /* Error in the Linux Stats code */ - VIR_FROM_LXC = 17, /* Error from Linux Container driver */ - VIR_FROM_STORAGE = 18, /* Error from storage driver */ - VIR_FROM_NETWORK = 19, /* Error from network config */ - - VIR_FROM_DOMAIN = 20, /* Error from domain config */ - VIR_FROM_UML = 21, /* Error at the UML driver; unused since 5.0.0 */ - VIR_FROM_NODEDEV = 22, /* Error from node device monitor */ - VIR_FROM_XEN_INOTIFY = 23, /* Error from xen inotify layer */ - VIR_FROM_SECURITY = 24, /* Error from security framework */ - - VIR_FROM_VBOX = 25, /* Error from VirtualBox driver */ - VIR_FROM_INTERFACE = 26, /* Error when operating on an interface */ + 0.8.6 (Since: v0.1.3) */ + VIR_FROM_CONF = 9, /* Error in the configuration file handling (Since: v0.1.6) */ + + VIR_FROM_QEMU = 10, /* Error at the QEMU daemon (Since: v0.2.0) */ + VIR_FROM_NET = 11, /* Error when operating on a network (Since: v0.2.0) */ + VIR_FROM_TEST = 12, /* Error from test driver (Since: v0.2.3) */ + VIR_FROM_REMOTE = 13, /* Error from remote driver (Since: v0.2.3) */ + VIR_FROM_OPENVZ = 14, /* Error from OpenVZ driver (Since: v0.3.1) */ + + VIR_FROM_XENXM = 15, /* Error at Xen XM layer (Since: v0.4.1) */ + VIR_FROM_STATS_LINUX = 16, /* Error in the Linux Stats code (Since: v0.4.1) */ + VIR_FROM_LXC = 17, /* Error from Linux Container driver (Since: v0.4.2) */ + VIR_FROM_STORAGE = 18, /* Error from storage driver (Since: v0.4.1) */ + VIR_FROM_NETWORK = 19, /* Error from network config (Since: v0.4.6) */ + + VIR_FROM_DOMAIN = 20, /* Error from domain config (Since: v0.4.6) */ + VIR_FROM_UML = 21, /* Error at the UML driver; unused since 5.0.0 (Since: v0.5.0) */ + VIR_FROM_NODEDEV = 22, /* Error from node device monitor (Since: v0.5.0) */ + VIR_FROM_XEN_INOTIFY = 23, /* Error from xen inotify layer (Since: v0.5.0) */ + VIR_FROM_SECURITY = 24, /* Error from security framework (Since: v0.6.1) */ + + VIR_FROM_VBOX = 25, /* Error from VirtualBox driver (Since: v0.6.3) */ + VIR_FROM_INTERFACE = 26, /* Error when operating on an interface (Since: v0.6.4) */ VIR_FROM_ONE = 27, /* The OpenNebula driver no longer exists. - Retained for ABI/API compat only */ - VIR_FROM_ESX = 28, /* Error from ESX driver */ - VIR_FROM_PHYP = 29, /* Error from the phyp driver, unused since 6.0.0 */ - - VIR_FROM_SECRET = 30, /* Error from secret storage */ - VIR_FROM_CPU = 31, /* Error from CPU driver */ - VIR_FROM_XENAPI = 32, /* Error from XenAPI */ - VIR_FROM_NWFILTER = 33, /* Error from network filter driver */ - VIR_FROM_HOOK = 34, /* Error from Synchronous hooks */ - - VIR_FROM_DOMAIN_SNAPSHOT = 35,/* Error from domain snapshot */ - VIR_FROM_AUDIT = 36, /* Error from auditing subsystem */ - VIR_FROM_SYSINFO = 37, /* Error from sysinfo/SMBIOS */ - VIR_FROM_STREAMS = 38, /* Error from I/O streams */ - VIR_FROM_VMWARE = 39, /* Error from VMware driver */ - - VIR_FROM_EVENT = 40, /* Error from event loop impl */ - VIR_FROM_LIBXL = 41, /* Error from libxenlight driver */ - VIR_FROM_LOCKING = 42, /* Error from lock manager */ - VIR_FROM_HYPERV = 43, /* Error from Hyper-V driver */ - VIR_FROM_CAPABILITIES = 44, /* Error from capabilities */ - - VIR_FROM_URI = 45, /* Error from URI handling */ - VIR_FROM_AUTH = 46, /* Error from auth handling */ - VIR_FROM_DBUS = 47, /* Error from DBus */ - VIR_FROM_PARALLELS = 48, /* Error from Parallels */ - VIR_FROM_DEVICE = 49, /* Error from Device */ - - VIR_FROM_SSH = 50, /* Error from libssh2 connection transport */ - VIR_FROM_LOCKSPACE = 51, /* Error from lockspace */ - VIR_FROM_INITCTL = 52, /* Error from initctl device communication */ - VIR_FROM_IDENTITY = 53, /* Error from identity code */ - VIR_FROM_CGROUP = 54, /* Error from cgroups */ - - VIR_FROM_ACCESS = 55, /* Error from access control manager */ - VIR_FROM_SYSTEMD = 56, /* Error from systemd code */ - VIR_FROM_BHYVE = 57, /* Error from bhyve driver */ - VIR_FROM_CRYPTO = 58, /* Error from crypto code */ - VIR_FROM_FIREWALL = 59, /* Error from firewall */ - - VIR_FROM_POLKIT = 60, /* Error from polkit code */ - VIR_FROM_THREAD = 61, /* Error from thread utils */ - VIR_FROM_ADMIN = 62, /* Error from admin backend */ - VIR_FROM_LOGGING = 63, /* Error from log manager */ - VIR_FROM_XENXL = 64, /* Error from Xen xl config code */ - - VIR_FROM_PERF = 65, /* Error from perf */ - VIR_FROM_LIBSSH = 66, /* Error from libssh connection transport */ - VIR_FROM_RESCTRL = 67, /* Error from resource control */ - VIR_FROM_FIREWALLD = 68, /* Error from firewalld */ - VIR_FROM_DOMAIN_CHECKPOINT = 69, /* Error from domain checkpoint */ - - VIR_FROM_TPM = 70, /* Error from TPM */ - VIR_FROM_BPF = 71, /* Error from BPF code */ - VIR_FROM_CH = 72, /* Error from Cloud-Hypervisor driver */ + Retained for ABI/API compat only (Since: v0.6.4) */ + VIR_FROM_ESX = 28, /* Error from ESX driver (Since: v0.7.0) */ + VIR_FROM_PHYP = 29, /* Error from the phyp driver, unused since 6.0.0 (Since: v0.7.0) */ + + VIR_FROM_SECRET = 30, /* Error from secret storage (Since: v0.7.1) */ + VIR_FROM_CPU = 31, /* Error from CPU driver (Since: v0.7.5) */ + VIR_FROM_XENAPI = 32, /* Error from XenAPI (Since: v0.8.0) */ + VIR_FROM_NWFILTER = 33, /* Error from network filter driver (Since: v0.8.0) */ + VIR_FROM_HOOK = 34, /* Error from Synchronous hooks (Since: v0.8.0) */ + + VIR_FROM_DOMAIN_SNAPSHOT = 35,/* Error from domain snapshot (Since: v0.8.0) */ + VIR_FROM_AUDIT = 36, /* Error from auditing subsystem (Since: v0.8.5) */ + VIR_FROM_SYSINFO = 37, /* Error from sysinfo/SMBIOS (Since: v0.8.6) */ + VIR_FROM_STREAMS = 38, /* Error from I/O streams (Since: v0.8.6) */ + VIR_FROM_VMWARE = 39, /* Error from VMware driver (Since: v0.8.7) */ + + VIR_FROM_EVENT = 40, /* Error from event loop impl (Since: v0.9.0) */ + VIR_FROM_LIBXL = 41, /* Error from libxenlight driver (Since: v0.9.0) */ + VIR_FROM_LOCKING = 42, /* Error from lock manager (Since: v0.9.2) */ + VIR_FROM_HYPERV = 43, /* Error from Hyper-V driver (Since: v0.9.5) */ + VIR_FROM_CAPABILITIES = 44, /* Error from capabilities (Since: v0.9.8) */ + + VIR_FROM_URI = 45, /* Error from URI handling (Since: v0.9.11) */ + VIR_FROM_AUTH = 46, /* Error from auth handling (Since: v0.9.11) */ + VIR_FROM_DBUS = 47, /* Error from DBus (Since: v0.9.12) */ + VIR_FROM_PARALLELS = 48, /* Error from Parallels (Since: v0.10.0) */ + VIR_FROM_DEVICE = 49, /* Error from Device (Since: v0.10.0) */ + + VIR_FROM_SSH = 50, /* Error from libssh2 connection transport (Since: v0.10.0) */ + VIR_FROM_LOCKSPACE = 51, /* Error from lockspace (Since: v1.0.0) */ + VIR_FROM_INITCTL = 52, /* Error from initctl device communication (Since: v1.0.1) */ + VIR_FROM_IDENTITY = 53, /* Error from identity code (Since: v1.0.4) */ + VIR_FROM_CGROUP = 54, /* Error from cgroups (Since: v1.0.5) */ + + VIR_FROM_ACCESS = 55, /* Error from access control manager (Since: v1.1.0) */ + VIR_FROM_SYSTEMD = 56, /* Error from systemd code (Since: v1.1.1) */ + VIR_FROM_BHYVE = 57, /* Error from bhyve driver (Since: v1.2.2) */ + VIR_FROM_CRYPTO = 58, /* Error from crypto code (Since: v1.2.3) */ + VIR_FROM_FIREWALL = 59, /* Error from firewall (Since: v1.2.4) */ + + VIR_FROM_POLKIT = 60, /* Error from polkit code (Since: v1.2.9) */ + VIR_FROM_THREAD = 61, /* Error from thread utils (Since: v1.2.14) */ + VIR_FROM_ADMIN = 62, /* Error from admin backend (Since: v1.2.17) */ + VIR_FROM_LOGGING = 63, /* Error from log manager (Since: v1.3.0) */ + VIR_FROM_XENXL = 64, /* Error from Xen xl config code (Since: v1.3.2) */ + + VIR_FROM_PERF = 65, /* Error from perf (Since: v1.3.3) */ + VIR_FROM_LIBSSH = 66, /* Error from libssh connection transport (Since: v2.5.0) */ + VIR_FROM_RESCTRL = 67, /* Error from resource control (Since: v3.7.0) */ + VIR_FROM_FIREWALLD = 68, /* Error from firewalld (Since: v5.1.0) */ + VIR_FROM_DOMAIN_CHECKPOINT = 69, /* Error from domain checkpoint (Since: v5.2.0) */ + + VIR_FROM_TPM = 70, /* Error from TPM (Since: v5.6.0) */ + VIR_FROM_BPF = 71, /* Error from BPF code (Since: v5.10.0) */ + VIR_FROM_CH = 72, /* Error from Cloud-Hypervisor driver (Since: v7.5.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_ERR_DOMAIN_LAST + VIR_ERR_DOMAIN_LAST /* (Since: v0.9.13) */ # endif } virErrorDomain; @@ -207,137 +207,137 @@ struct _virError { * } */ typedef enum { - VIR_ERR_OK = 0, - VIR_ERR_INTERNAL_ERROR = 1, /* internal error */ - VIR_ERR_NO_MEMORY = 2, /* memory allocation failure */ - VIR_ERR_NO_SUPPORT = 3, /* no support for this function */ - VIR_ERR_UNKNOWN_HOST = 4, /* could not resolve hostname */ - VIR_ERR_NO_CONNECT = 5, /* can't connect to hypervisor */ - VIR_ERR_INVALID_CONN = 6, /* invalid connection object */ - VIR_ERR_INVALID_DOMAIN = 7, /* invalid domain object */ - VIR_ERR_INVALID_ARG = 8, /* invalid function argument */ - VIR_ERR_OPERATION_FAILED = 9, /* a command to hypervisor failed */ - VIR_ERR_GET_FAILED = 10, /* a HTTP GET command to failed */ - VIR_ERR_POST_FAILED = 11, /* a HTTP POST command to failed */ - VIR_ERR_HTTP_ERROR = 12, /* unexpected HTTP error code */ - VIR_ERR_SEXPR_SERIAL = 13, /* failure to serialize an S-Expr */ + VIR_ERR_OK = 0, /* (Since: v0.1.0) */ + VIR_ERR_INTERNAL_ERROR = 1, /* internal error (Since: v0.1.0) */ + VIR_ERR_NO_MEMORY = 2, /* memory allocation failure (Since: v0.1.0) */ + VIR_ERR_NO_SUPPORT = 3, /* no support for this function (Since: v0.1.0) */ + VIR_ERR_UNKNOWN_HOST = 4, /* could not resolve hostname (Since: v0.1.0) */ + VIR_ERR_NO_CONNECT = 5, /* can't connect to hypervisor (Since: v0.1.0) */ + VIR_ERR_INVALID_CONN = 6, /* invalid connection object (Since: v0.1.0) */ + VIR_ERR_INVALID_DOMAIN = 7, /* invalid domain object (Since: v0.1.0) */ + VIR_ERR_INVALID_ARG = 8, /* invalid function argument (Since: v0.1.0) */ + VIR_ERR_OPERATION_FAILED = 9, /* a command to hypervisor failed (Since: v0.1.0) */ + VIR_ERR_GET_FAILED = 10, /* a HTTP GET command to failed (Since: v0.1.0) */ + VIR_ERR_POST_FAILED = 11, /* a HTTP POST command to failed (Since: v0.1.0) */ + VIR_ERR_HTTP_ERROR = 12, /* unexpected HTTP error code (Since: v0.1.0) */ + VIR_ERR_SEXPR_SERIAL = 13, /* failure to serialize an S-Expr (Since: v0.1.0) */ VIR_ERR_NO_XEN = 14, /* could not open Xen hypervisor - control */ - VIR_ERR_XEN_CALL = 15, /* failure doing an hypervisor call */ - VIR_ERR_OS_TYPE = 16, /* unknown OS type */ - VIR_ERR_NO_KERNEL = 17, /* missing kernel information */ - VIR_ERR_NO_ROOT = 18, /* missing root device information */ - VIR_ERR_NO_SOURCE = 19, /* missing source device information */ - VIR_ERR_NO_TARGET = 20, /* missing target device information */ - VIR_ERR_NO_NAME = 21, /* missing domain name information */ - VIR_ERR_NO_OS = 22, /* missing domain OS information */ - VIR_ERR_NO_DEVICE = 23, /* missing domain devices information */ - VIR_ERR_NO_XENSTORE = 24, /* could not open Xen Store control */ - VIR_ERR_DRIVER_FULL = 25, /* too many drivers registered */ + control (Since: v0.1.0) */ + VIR_ERR_XEN_CALL = 15, /* failure doing an hypervisor call (Since: v0.1.0) */ + VIR_ERR_OS_TYPE = 16, /* unknown OS type (Since: v0.1.0) */ + VIR_ERR_NO_KERNEL = 17, /* missing kernel information (Since: v0.1.0) */ + VIR_ERR_NO_ROOT = 18, /* missing root device information (Since: v0.1.0) */ + VIR_ERR_NO_SOURCE = 19, /* missing source device information (Since: v0.1.0) */ + VIR_ERR_NO_TARGET = 20, /* missing target device information (Since: v0.1.0) */ + VIR_ERR_NO_NAME = 21, /* missing domain name information (Since: v0.1.0) */ + VIR_ERR_NO_OS = 22, /* missing domain OS information (Since: v0.1.0) */ + VIR_ERR_NO_DEVICE = 23, /* missing domain devices information (Since: v0.1.0) */ + VIR_ERR_NO_XENSTORE = 24, /* could not open Xen Store control (Since: v0.1.0) */ + VIR_ERR_DRIVER_FULL = 25, /* too many drivers registered (Since: v0.1.0) */ VIR_ERR_CALL_FAILED = 26, /* not supported by the drivers - (DEPRECATED) */ + (DEPRECATED) (Since: v0.1.0) */ VIR_ERR_XML_ERROR = 27, /* an XML description is not well - formed or broken */ - VIR_ERR_DOM_EXIST = 28, /* the domain already exist */ + formed or broken (Since: v0.1.1) */ + VIR_ERR_DOM_EXIST = 28, /* the domain already exist (Since: v0.1.1) */ VIR_ERR_OPERATION_DENIED = 29, /* operation forbidden on read-only - connections */ - VIR_ERR_OPEN_FAILED = 30, /* failed to open a conf file */ - VIR_ERR_READ_FAILED = 31, /* failed to read a conf file */ - VIR_ERR_PARSE_FAILED = 32, /* failed to parse a conf file */ + connections (Since: v0.1.4) */ + VIR_ERR_OPEN_FAILED = 30, /* failed to open a conf file (Since: v0.1.6) */ + VIR_ERR_READ_FAILED = 31, /* failed to read a conf file (Since: v0.1.6) */ + VIR_ERR_PARSE_FAILED = 32, /* failed to parse a conf file (Since: v0.1.6) */ VIR_ERR_CONF_SYNTAX = 33, /* failed to parse the syntax of a - conf file */ - VIR_ERR_WRITE_FAILED = 34, /* failed to write a conf file */ - VIR_ERR_XML_DETAIL = 35, /* detail of an XML error */ - VIR_ERR_INVALID_NETWORK = 36, /* invalid network object */ - VIR_ERR_NETWORK_EXIST = 37, /* the network already exist */ - VIR_ERR_SYSTEM_ERROR = 38, /* general system call failure */ - VIR_ERR_RPC = 39, /* some sort of RPC error */ - VIR_ERR_GNUTLS_ERROR = 40, /* error from a GNUTLS call */ - VIR_WAR_NO_NETWORK = 41, /* failed to start network */ + conf file (Since: v0.1.6) */ + VIR_ERR_WRITE_FAILED = 34, /* failed to write a conf file (Since: v0.1.6) */ + VIR_ERR_XML_DETAIL = 35, /* detail of an XML error (Since: v0.1.9) */ + VIR_ERR_INVALID_NETWORK = 36, /* invalid network object (Since: v0.2.0) */ + VIR_ERR_NETWORK_EXIST = 37, /* the network already exist (Since: v0.2.0) */ + VIR_ERR_SYSTEM_ERROR = 38, /* general system call failure (Since: v0.2.1) */ + VIR_ERR_RPC = 39, /* some sort of RPC error (Since: v0.2.3) */ + VIR_ERR_GNUTLS_ERROR = 40, /* error from a GNUTLS call (Since: v0.2.3) */ + VIR_WAR_NO_NETWORK = 41, /* failed to start network (Since: v0.2.3) */ VIR_ERR_NO_DOMAIN = 42, /* domain not found or unexpectedly - disappeared */ - VIR_ERR_NO_NETWORK = 43, /* network not found */ - VIR_ERR_INVALID_MAC = 44, /* invalid MAC address */ - VIR_ERR_AUTH_FAILED = 45, /* authentication failed */ - VIR_ERR_INVALID_STORAGE_POOL = 46, /* invalid storage pool object */ - VIR_ERR_INVALID_STORAGE_VOL = 47, /* invalid storage vol object */ - VIR_WAR_NO_STORAGE = 48, /* failed to start storage */ - VIR_ERR_NO_STORAGE_POOL = 49, /* storage pool not found */ - VIR_ERR_NO_STORAGE_VOL = 50, /* storage volume not found */ - VIR_WAR_NO_NODE = 51, /* failed to start node driver */ - VIR_ERR_INVALID_NODE_DEVICE = 52, /* invalid node device object */ - VIR_ERR_NO_NODE_DEVICE = 53, /* node device not found */ - VIR_ERR_NO_SECURITY_MODEL = 54, /* security model not found */ + disappeared (Since: v0.3.0) */ + VIR_ERR_NO_NETWORK = 43, /* network not found (Since: v0.3.0) */ + VIR_ERR_INVALID_MAC = 44, /* invalid MAC address (Since: v0.3.1) */ + VIR_ERR_AUTH_FAILED = 45, /* authentication failed (Since: v0.4.1) */ + VIR_ERR_INVALID_STORAGE_POOL = 46, /* invalid storage pool object (Since: v0.4.1) */ + VIR_ERR_INVALID_STORAGE_VOL = 47, /* invalid storage vol object (Since: v0.4.1) */ + VIR_WAR_NO_STORAGE = 48, /* failed to start storage (Since: v0.4.1) */ + VIR_ERR_NO_STORAGE_POOL = 49, /* storage pool not found (Since: v0.4.1) */ + VIR_ERR_NO_STORAGE_VOL = 50, /* storage volume not found (Since: v0.4.1) */ + VIR_WAR_NO_NODE = 51, /* failed to start node driver (Since: v0.5.0) */ + VIR_ERR_INVALID_NODE_DEVICE = 52, /* invalid node device object (Since: v0.5.0) */ + VIR_ERR_NO_NODE_DEVICE = 53, /* node device not found (Since: v0.5.0) */ + VIR_ERR_NO_SECURITY_MODEL = 54, /* security model not found (Since: v0.6.1) */ VIR_ERR_OPERATION_INVALID = 55, /* operation is not applicable at this - time */ - VIR_WAR_NO_INTERFACE = 56, /* failed to start interface driver */ - VIR_ERR_NO_INTERFACE = 57, /* interface driver not running */ - VIR_ERR_INVALID_INTERFACE = 58, /* invalid interface object */ + time (Since: v0.6.4) */ + VIR_WAR_NO_INTERFACE = 56, /* failed to start interface driver (Since: v0.6.4) */ + VIR_ERR_NO_INTERFACE = 57, /* interface driver not running (Since: v0.6.4) */ + VIR_ERR_INVALID_INTERFACE = 58, /* invalid interface object (Since: v0.6.4) */ VIR_ERR_MULTIPLE_INTERFACES = 59, /* more than one matching interface - found */ - VIR_WAR_NO_NWFILTER = 60, /* failed to start nwfilter driver */ - VIR_ERR_INVALID_NWFILTER = 61, /* invalid nwfilter object */ - VIR_ERR_NO_NWFILTER = 62, /* nw filter pool not found */ - VIR_ERR_BUILD_FIREWALL = 63, /* nw filter pool not found */ - VIR_WAR_NO_SECRET = 64, /* failed to start secret storage */ - VIR_ERR_INVALID_SECRET = 65, /* invalid secret */ - VIR_ERR_NO_SECRET = 66, /* secret not found */ + found (Since: v0.7.0) */ + VIR_WAR_NO_NWFILTER = 60, /* failed to start nwfilter driver (Since: v0.8.0) */ + VIR_ERR_INVALID_NWFILTER = 61, /* invalid nwfilter object (Since: v0.8.0) */ + VIR_ERR_NO_NWFILTER = 62, /* nw filter pool not found (Since: v0.8.0) */ + VIR_ERR_BUILD_FIREWALL = 63, /* nw filter pool not found (Since: v0.8.0) */ + VIR_WAR_NO_SECRET = 64, /* failed to start secret storage (Since: v0.7.1) */ + VIR_ERR_INVALID_SECRET = 65, /* invalid secret (Since: v0.7.1) */ + VIR_ERR_NO_SECRET = 66, /* secret not found (Since: v0.7.1) */ VIR_ERR_CONFIG_UNSUPPORTED = 67, /* unsupported configuration - construct */ - VIR_ERR_OPERATION_TIMEOUT = 68, /* timeout occurred during operation */ + construct (Since: v0.7.3) */ + VIR_ERR_OPERATION_TIMEOUT = 68, /* timeout occurred during operation (Since: v0.7.3) */ VIR_ERR_MIGRATE_PERSIST_FAILED = 69,/* a migration worked, but making the - VM persist on the dest host failed */ - VIR_ERR_HOOK_SCRIPT_FAILED = 70, /* a synchronous hook script failed */ - VIR_ERR_INVALID_DOMAIN_SNAPSHOT = 71,/* invalid domain snapshot */ - VIR_ERR_NO_DOMAIN_SNAPSHOT = 72, /* domain snapshot not found */ - VIR_ERR_INVALID_STREAM = 73, /* stream pointer not valid */ + VM persist on the dest host failed (Since: v0.7.3) */ + VIR_ERR_HOOK_SCRIPT_FAILED = 70, /* a synchronous hook script failed (Since: v0.8.0) */ + VIR_ERR_INVALID_DOMAIN_SNAPSHOT = 71,/* invalid domain snapshot (Since: v0.8.0) */ + VIR_ERR_NO_DOMAIN_SNAPSHOT = 72, /* domain snapshot not found (Since: v0.8.0) */ + VIR_ERR_INVALID_STREAM = 73, /* stream pointer not valid (Since: v0.9.0) */ VIR_ERR_ARGUMENT_UNSUPPORTED = 74, /* valid API use but unsupported by - the given driver */ - VIR_ERR_STORAGE_PROBE_FAILED = 75, /* storage pool probe failed */ - VIR_ERR_STORAGE_POOL_BUILT = 76, /* storage pool already built */ + the given driver (Since: v0.9.4) */ + VIR_ERR_STORAGE_PROBE_FAILED = 75, /* storage pool probe failed (Since: v0.9.5) */ + VIR_ERR_STORAGE_POOL_BUILT = 76, /* storage pool already built (Since: v0.9.5) */ VIR_ERR_SNAPSHOT_REVERT_RISKY = 77, /* force was not requested for a - risky domain snapshot revert */ + risky domain snapshot revert (Since: v0.9.7) */ VIR_ERR_OPERATION_ABORTED = 78, /* operation on a domain was - canceled/aborted by user */ - VIR_ERR_AUTH_CANCELLED = 79, /* authentication cancelled */ - VIR_ERR_NO_DOMAIN_METADATA = 80, /* The metadata is not present */ - VIR_ERR_MIGRATE_UNSAFE = 81, /* Migration is not safe */ - VIR_ERR_OVERFLOW = 82, /* integer overflow */ - VIR_ERR_BLOCK_COPY_ACTIVE = 83, /* action prevented by block copy job */ + canceled/aborted by user (Since: v0.9.9) */ + VIR_ERR_AUTH_CANCELLED = 79, /* authentication cancelled (Since: v0.9.10) */ + VIR_ERR_NO_DOMAIN_METADATA = 80, /* The metadata is not present (Since: v0.9.10) */ + VIR_ERR_MIGRATE_UNSAFE = 81, /* Migration is not safe (Since: v0.9.11) */ + VIR_ERR_OVERFLOW = 82, /* integer overflow (Since: v0.9.11) */ + VIR_ERR_BLOCK_COPY_ACTIVE = 83, /* action prevented by block copy job (Since: v0.9.12) */ VIR_ERR_OPERATION_UNSUPPORTED = 84, /* The requested operation is not - supported */ - VIR_ERR_SSH = 85, /* error in ssh transport driver */ + supported (Since: v0.10.0) */ + VIR_ERR_SSH = 85, /* error in ssh transport driver (Since: v0.10.0) */ VIR_ERR_AGENT_UNRESPONSIVE = 86, /* guest agent is unresponsive, - not running or not usable */ - VIR_ERR_RESOURCE_BUSY = 87, /* resource is already in use */ + not running or not usable (Since: v0.10.0) */ + VIR_ERR_RESOURCE_BUSY = 87, /* resource is already in use (Since: v1.0.0) */ VIR_ERR_ACCESS_DENIED = 88, /* operation on the object/resource - was denied */ - VIR_ERR_DBUS_SERVICE = 89, /* error from a dbus service */ - VIR_ERR_STORAGE_VOL_EXIST = 90, /* the storage vol already exists */ - VIR_ERR_CPU_INCOMPATIBLE = 91, /* given CPU is incompatible with host CPU */ - VIR_ERR_XML_INVALID_SCHEMA = 92, /* XML document doesn't validate against schema */ - VIR_ERR_MIGRATE_FINISH_OK = 93, /* Finish API succeeded but it is expected to return NULL */ - VIR_ERR_AUTH_UNAVAILABLE = 94, /* authentication unavailable */ - VIR_ERR_NO_SERVER = 95, /* Server was not found */ - VIR_ERR_NO_CLIENT = 96, /* Client was not found */ + was denied (Since: v1.1.0) */ + VIR_ERR_DBUS_SERVICE = 89, /* error from a dbus service (Since: v1.1.1) */ + VIR_ERR_STORAGE_VOL_EXIST = 90, /* the storage vol already exists (Since: v1.1.4) */ + VIR_ERR_CPU_INCOMPATIBLE = 91, /* given CPU is incompatible with host CPU (Since: v1.2.6) */ + VIR_ERR_XML_INVALID_SCHEMA = 92, /* XML document doesn't validate against schema (Since: v1.2.12) */ + VIR_ERR_MIGRATE_FINISH_OK = 93, /* Finish API succeeded but it is expected to return NULL (Since: v1.2.18) */ + VIR_ERR_AUTH_UNAVAILABLE = 94, /* authentication unavailable (Since: v1.3.3) */ + VIR_ERR_NO_SERVER = 95, /* Server was not found (Since: v1.3.3) */ + VIR_ERR_NO_CLIENT = 96, /* Client was not found (Since: v1.3.5) */ VIR_ERR_AGENT_UNSYNCED = 97, /* guest agent replies with wrong id - to guest-sync command (DEPRECATED) */ - VIR_ERR_LIBSSH = 98, /* error in libssh transport driver */ - VIR_ERR_DEVICE_MISSING = 99, /* fail to find the desired device */ - VIR_ERR_INVALID_NWFILTER_BINDING = 100, /* invalid nwfilter binding */ - VIR_ERR_NO_NWFILTER_BINDING = 101, /* no nwfilter binding */ - VIR_ERR_INVALID_DOMAIN_CHECKPOINT = 102, /* invalid domain checkpoint */ - VIR_ERR_NO_DOMAIN_CHECKPOINT = 103, /* domain checkpoint not found */ - VIR_ERR_NO_DOMAIN_BACKUP = 104, /* domain backup job id not found */ - VIR_ERR_INVALID_NETWORK_PORT = 105, /* invalid network port object */ - VIR_ERR_NETWORK_PORT_EXIST = 106, /* the network port already exist */ - VIR_ERR_NO_NETWORK_PORT = 107, /* network port not found */ - VIR_ERR_NO_HOSTNAME = 108, /* no domain's hostname found */ - VIR_ERR_CHECKPOINT_INCONSISTENT = 109, /* checkpoint can't be used */ - VIR_ERR_MULTIPLE_DOMAINS = 110, /* more than one matching domain found */ + to guest-sync command (DEPRECATED) (Since: v2.3.0) */ + VIR_ERR_LIBSSH = 98, /* error in libssh transport driver (Since: v2.5.0) */ + VIR_ERR_DEVICE_MISSING = 99, /* fail to find the desired device (Since: v4.1.0) */ + VIR_ERR_INVALID_NWFILTER_BINDING = 100, /* invalid nwfilter binding (Since: v4.5.0) */ + VIR_ERR_NO_NWFILTER_BINDING = 101, /* no nwfilter binding (Since: v4.5.0) */ + VIR_ERR_INVALID_DOMAIN_CHECKPOINT = 102, /* invalid domain checkpoint (Since: v5.2.0) */ + VIR_ERR_NO_DOMAIN_CHECKPOINT = 103, /* domain checkpoint not found (Since: v5.2.0) */ + VIR_ERR_NO_DOMAIN_BACKUP = 104, /* domain backup job id not found (Since: v5.2.0) */ + VIR_ERR_INVALID_NETWORK_PORT = 105, /* invalid network port object (Since: v5.5.0) */ + VIR_ERR_NETWORK_PORT_EXIST = 106, /* the network port already exist (Since: v5.5.0) */ + VIR_ERR_NO_NETWORK_PORT = 107, /* network port not found (Since: v5.5.0) */ + VIR_ERR_NO_HOSTNAME = 108, /* no domain's hostname found (Since: v6.1.0) */ + VIR_ERR_CHECKPOINT_INCONSISTENT = 109, /* checkpoint can't be used (Since: v6.10.0) */ + VIR_ERR_MULTIPLE_DOMAINS = 110, /* more than one matching domain found (Since: v7.1.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_ERR_NUMBER_LAST + VIR_ERR_NUMBER_LAST /* (Since: v5.0.0) */ # endif } virErrorNumber; -- 2.35.1

Either create or append to existing docstring, the version (git tag) that a given macro was introduced in the format: Since: v1.2.3 Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- include/libvirt/libvirt-admin.h | 60 +++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/include/libvirt/libvirt-admin.h b/include/libvirt/libvirt-admin.h index f65886f20d..defca505f8 100644 --- a/include/libvirt/libvirt-admin.h +++ b/include/libvirt/libvirt-admin.h @@ -132,6 +132,9 @@ virAdmServerPtr virAdmConnectLookupServer(virAdmConnectPtr conn, * VIR_THREADPOOL_WORKERS_MIN: * Macro for the threadpool minWorkers limit: represents the bottom limit to * number of active workers in threadpool, as VIR_TYPED_PARAM_UINT. + * + * Since: v1.3.4 + * */ # define VIR_THREADPOOL_WORKERS_MIN "minWorkers" @@ -142,6 +145,9 @@ virAdmServerPtr virAdmConnectLookupServer(virAdmConnectPtr conn, * number of active workers in threadpool, as VIR_TYPED_PARAM_UINT. * The value of this limit has to be greater than VIR_THREADPOOL_WORKERS_MIN * at all times. + * + * Since: v1.3.4 + * */ # define VIR_THREADPOOL_WORKERS_MAX "maxWorkers" @@ -150,6 +156,9 @@ virAdmServerPtr virAdmConnectLookupServer(virAdmConnectPtr conn, * VIR_THREADPOOL_WORKERS_PRIORITY: * Macro for the threadpool nPrioWorkers attribute: represents the current number * of active priority workers in threadpool, as VIR_TYPED_PARAM_UINT. + * + * Since: v1.3.4 + * */ # define VIR_THREADPOOL_WORKERS_PRIORITY "prioWorkers" @@ -161,6 +170,9 @@ virAdmServerPtr virAdmConnectLookupServer(virAdmConnectPtr conn, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.4 + * */ # define VIR_THREADPOOL_WORKERS_FREE "freeWorkers" @@ -172,6 +184,9 @@ virAdmServerPtr virAdmConnectLookupServer(virAdmConnectPtr conn, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.4 + * */ # define VIR_THREADPOOL_WORKERS_CURRENT "nWorkers" @@ -183,6 +198,9 @@ virAdmServerPtr virAdmConnectLookupServer(virAdmConnectPtr conn, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.4 + * */ # define VIR_THREADPOOL_JOB_QUEUE_DEPTH "jobQueueDepth" @@ -233,6 +251,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_READONLY "readonly" @@ -244,6 +265,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_SOCKET_ADDR "sock_addr" @@ -255,6 +279,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_SASL_USER_NAME "sasl_user_name" @@ -267,6 +294,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_X509_DISTINGUISHED_NAME "tls_x509_dname" @@ -279,6 +309,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_UNIX_USER_ID "unix_user_id" @@ -291,6 +324,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_UNIX_USER_NAME "unix_user_name" @@ -303,6 +339,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_UNIX_GROUP_ID "unix_group_id" @@ -315,6 +354,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_UNIX_GROUP_NAME "unix_group_name" @@ -327,6 +369,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_UNIX_PROCESS_ID "unix_process_id" @@ -339,6 +384,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_SELINUX_CONTEXT "selinux_context" @@ -356,6 +404,9 @@ int virAdmClientClose(virAdmClientPtr client, unsigned int flags); * VIR_SERVER_CLIENTS_MAX: * Macro for per-server nclients_max limit: represents the upper limit to * number of clients connected to the server, as uint. + * + * Since: v1.3.5 + * */ # define VIR_SERVER_CLIENTS_MAX "nclients_max" @@ -367,6 +418,9 @@ int virAdmClientClose(virAdmClientPtr client, unsigned int flags); * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_SERVER_CLIENTS_CURRENT "nclients" @@ -376,6 +430,9 @@ int virAdmClientClose(virAdmClientPtr client, unsigned int flags); * Macro for per-server nclients_unauth_max limit: represents the upper limit * to number of clients connected to the server, but not authenticated yet, * as VIR_TYPED_PARAM_UINT. + * + * Since: v1.3.5 + * */ # define VIR_SERVER_CLIENTS_UNAUTH_MAX "nclients_unauth_max" @@ -388,6 +445,9 @@ int virAdmClientClose(virAdmClientPtr client, unsigned int flags); * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_SERVER_CLIENTS_UNAUTH_CURRENT "nclients_unauth" -- 2.35.1

Either create or append to existing docstring, the version (git tag) that a given typedef was introduced in the format: Since: v1.2.3 Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- include/libvirt/libvirt-qemu.h | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/include/libvirt/libvirt-qemu.h b/include/libvirt/libvirt-qemu.h index a2569a9fbd..9697b54158 100644 --- a/include/libvirt/libvirt-qemu.h +++ b/include/libvirt/libvirt-qemu.h @@ -30,6 +30,12 @@ extern "C" { # endif +/** + * virDomainQemuMonitorCommandFlags: + * + * Since: v0.8.8 + * + */ typedef enum { VIR_DOMAIN_QEMU_MONITOR_COMMAND_DEFAULT = 0, /* (Since: v0.8.8) */ VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP = (1 << 0), /* cmd is in HMP (Since: v0.8.8) */ @@ -50,6 +56,12 @@ virDomainPtr virDomainQemuAttach(virConnectPtr domain, unsigned int pid_value, unsigned int flags); +/** + * virDomainQemuAgentCommandTimeoutValues: + * + * Since: v0.10.0 + * + */ typedef enum { VIR_DOMAIN_QEMU_AGENT_COMMAND_MIN = VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK, /* (Since: v0.10.0) */ VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK = VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK, /* (Since: v0.10.0) */ @@ -84,6 +96,12 @@ typedef void (*virConnectDomainQemuMonitorEventCallback)(virConnectPtr conn, void *opaque); +/** + * virConnectDomainQemuMonitorEventRegisterFlags: + * + * Since: v1.2.3 + * + */ typedef enum { /* Event filter is a regex rather than a literal string (Since: v1.2.3) */ VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_REGEX = (1 << 0), -- 2.35.1

Either create or append to existing docstring, the version (git tag) that a given typedef was introduced in the format: Since: v1.2.3 Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- include/libvirt/libvirt-admin.h | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/include/libvirt/libvirt-admin.h b/include/libvirt/libvirt-admin.h index defca505f8..c73cf6e7da 100644 --- a/include/libvirt/libvirt-admin.h +++ b/include/libvirt/libvirt-admin.h @@ -37,6 +37,9 @@ extern "C" { * * a virAdmConnect is a private structure representing a connection to * libvirt daemon. + * + * Since: v1.2.17 + * */ typedef struct _virAdmConnect virAdmConnect; @@ -45,6 +48,9 @@ typedef struct _virAdmConnect virAdmConnect; * * a virAdmServer is a private structure and client-side representation of * a remote server object + * + * Since: v1.3.2 + * */ typedef struct _virAdmServer virAdmServer; @@ -53,6 +59,9 @@ typedef struct _virAdmServer virAdmServer; * * a virAdmClient is a private structure and client-side representation of * a remote server's client object (as server sees clients connected to it) + * + * Since: v1.3.5 + * */ typedef struct _virAdmClient virAdmClient; @@ -62,6 +71,9 @@ typedef struct _virAdmClient virAdmClient; * a virAdmConnectPtr is pointer to a virAdmConnect private structure, * this is the type used to reference a connection to the daemon * in the API. + * + * Since: v1.2.17 + * */ typedef virAdmConnect *virAdmConnectPtr; @@ -71,6 +83,9 @@ typedef virAdmConnect *virAdmConnectPtr; * a virAdmServerPtr is a pointer to a virAdmServer structure, * this is the type used to reference client-side representation of a * remote server object throughout all the APIs. + * + * Since: v1.3.2 + * */ typedef virAdmServer *virAdmServerPtr; @@ -80,6 +95,9 @@ typedef virAdmServer *virAdmServerPtr; * a virAdmClientPtr is a pointer to a virAdmClient structure, * this is the type used to reference client-side representation of a * client object throughout all the APIs. + * + * Since: v1.3.5 + * */ typedef virAdmClient *virAdmClientPtr; @@ -222,6 +240,12 @@ long long virAdmClientGetTimestamp(virAdmClientPtr client); int virAdmClientGetTransport(virAdmClientPtr client); int virAdmClientFree(virAdmClientPtr client); +/** + * virClientTransport: + * + * Since: v1.3.5 + * + */ typedef enum { VIR_CLIENT_TRANS_UNIX = 0, /* connection via UNIX socket (Since: v1.3.5) */ VIR_CLIENT_TRANS_TCP, /* connection via unencrypted TCP socket (Since: v1.3.5) */ -- 2.35.1

On Wed, Apr 20, 2022 at 09:08:02PM +0200, Victor Toso wrote: I see that Peter is going really hard with these reviews, so while I intended to look at the series before the end of the week he's probably going to be done with it way before then so I better speak up now :) The vertical whitespace is inconsistent: two different styles can be seen here, and I've also spotted instances of * ... * * Since: v... */ elsewhere. My own preference would be to adopt this last style everywhere, but I would be okay with having a single empty line after version information. Either way, it needs to be applied consistently. -- Andrea Bolognani / Red Hat / Virtualization

On Wed, Apr 20, 2022 at 21:08:05 +0200, Victor Toso wrote: [...] Per Daniels reply, all of these were made available only in libvirt-2.0.0 thus at the date the symbol was published, so also the Since tag should say so, even when the code was added previously. The logic should be that the Since tag for function should be MAX_VERSION(version_of_symbol, version_when_code_was_actually_added) Thus if code was added previously but exported later, it makes no sense to state it worked in the older version. Similarly if symbol is exported mistakenly in a prior version but added later it simply won't work with the older version. Thus for the admin commands we have both situations, here it's so that the code was added first and exposed later. The other case is virAdmServerUpdateTlsFiles which was mistakenly added to the LIBVIRT_2.0.0 symbol but really added in libvirt-6.2.

This commit is similar to "docs: Fix generated documentation of virConnectListAllNodeDeviceFlags", check it out for more info. Using git diff --word-diff to show the fixed output xml (redacted). <enum name='VIR_STORAGE_VOL_GET_PHYSICAL' ... [-type='virStorageVolInfoFlags'/>-] {+type='virStorageVolInfoFlags' version='3.0.0' info='Return the physical size in allocation'/>+} ... <enum name='VIR_STORAGE_VOL_USE_ALLOCATION' ... type='virStorageVolInfoFlags' [-info='Return the physical size in allocation'/>-] {+version='3.0.0'/>+} Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- include/libvirt/libvirt-storage.h | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/include/libvirt/libvirt-storage.h b/include/libvirt/libvirt-storage.h index 434454f455..8b57b1f2e8 100644 --- a/include/libvirt/libvirt-storage.h +++ b/include/libvirt/libvirt-storage.h @@ -248,11 +248,8 @@ typedef enum { * */ typedef enum { - VIR_STORAGE_VOL_USE_ALLOCATION = 0, - - /* Return the physical size in allocation */ - VIR_STORAGE_VOL_GET_PHYSICAL = 1 << 0, - + VIR_STORAGE_VOL_USE_ALLOCATION = 0, /* (Since: v3.0.0) */ + VIR_STORAGE_VOL_GET_PHYSICAL = 1 << 0, /* Return the physical size in allocation (Since: v3.0.0) */ } virStorageVolInfoFlags; /** -- 2.35.1

This commit is similar to "docs: Fix generated documentation of virConnectListAllNodeDeviceFlags", check it out for more info. Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- include/libvirt/libvirt-storage.h | 49 +++++++++++++++---------------- 1 file changed, 24 insertions(+), 25 deletions(-) diff --git a/include/libvirt/libvirt-storage.h b/include/libvirt/libvirt-storage.h index 8b57b1f2e8..e4980ae95f 100644 --- a/include/libvirt/libvirt-storage.h +++ b/include/libvirt/libvirt-storage.h @@ -317,34 +317,33 @@ int virConnectListDefinedStoragePools(virConnectPtr conn, * Note that these flags come in groups; if all bits from a group are 0, * then that group is not used to filter results. * - * Since: v1.0.0 + * Since: v0.10.2 * */ typedef enum { - VIR_CONNECT_LIST_STORAGE_POOLS_INACTIVE = 1 << 0, - VIR_CONNECT_LIST_STORAGE_POOLS_ACTIVE = 1 << 1, - - VIR_CONNECT_LIST_STORAGE_POOLS_PERSISTENT = 1 << 2, - VIR_CONNECT_LIST_STORAGE_POOLS_TRANSIENT = 1 << 3, - - VIR_CONNECT_LIST_STORAGE_POOLS_AUTOSTART = 1 << 4, - VIR_CONNECT_LIST_STORAGE_POOLS_NO_AUTOSTART = 1 << 5, - - /* List pools by type */ - VIR_CONNECT_LIST_STORAGE_POOLS_DIR = 1 << 6, - VIR_CONNECT_LIST_STORAGE_POOLS_FS = 1 << 7, - VIR_CONNECT_LIST_STORAGE_POOLS_NETFS = 1 << 8, - VIR_CONNECT_LIST_STORAGE_POOLS_LOGICAL = 1 << 9, - VIR_CONNECT_LIST_STORAGE_POOLS_DISK = 1 << 10, - VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI = 1 << 11, - VIR_CONNECT_LIST_STORAGE_POOLS_SCSI = 1 << 12, - VIR_CONNECT_LIST_STORAGE_POOLS_MPATH = 1 << 13, - VIR_CONNECT_LIST_STORAGE_POOLS_RBD = 1 << 14, - VIR_CONNECT_LIST_STORAGE_POOLS_SHEEPDOG = 1 << 15, - VIR_CONNECT_LIST_STORAGE_POOLS_GLUSTER = 1 << 16, - VIR_CONNECT_LIST_STORAGE_POOLS_ZFS = 1 << 17, - VIR_CONNECT_LIST_STORAGE_POOLS_VSTORAGE = 1 << 18, - VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI_DIRECT = 1 << 19, + VIR_CONNECT_LIST_STORAGE_POOLS_INACTIVE = 1 << 0, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_STORAGE_POOLS_ACTIVE = 1 << 1, /* (Since: v0.10.2) */ + + VIR_CONNECT_LIST_STORAGE_POOLS_PERSISTENT = 1 << 2, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_STORAGE_POOLS_TRANSIENT = 1 << 3, /* (Since: v0.10.2) */ + + VIR_CONNECT_LIST_STORAGE_POOLS_AUTOSTART = 1 << 4, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_STORAGE_POOLS_NO_AUTOSTART = 1 << 5, /* (Since: v0.10.2) */ + + VIR_CONNECT_LIST_STORAGE_POOLS_DIR = 1 << 6, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_STORAGE_POOLS_FS = 1 << 7, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_STORAGE_POOLS_NETFS = 1 << 8, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_STORAGE_POOLS_LOGICAL = 1 << 9, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_STORAGE_POOLS_DISK = 1 << 10, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI = 1 << 11, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_STORAGE_POOLS_SCSI = 1 << 12, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_STORAGE_POOLS_MPATH = 1 << 13, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_STORAGE_POOLS_RBD = 1 << 14, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_STORAGE_POOLS_SHEEPDOG = 1 << 15, /* (Since: v0.10.2) */ + VIR_CONNECT_LIST_STORAGE_POOLS_GLUSTER = 1 << 16, /* (Since: v1.2.1) */ + VIR_CONNECT_LIST_STORAGE_POOLS_ZFS = 1 << 17, /* (Since: v1.2.8) */ + VIR_CONNECT_LIST_STORAGE_POOLS_VSTORAGE = 1 << 18, /* (Since: v3.1.0) */ + VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI_DIRECT = 1 << 19, /* (Since: v5.6.0) */ } virConnectListAllStoragePoolsFlags; int virConnectListAllStoragePools(virConnectPtr conn, -- 2.35.1

This commit is similar to "docs: Fix generated documentation of virConnectListAllNodeDeviceFlags", check it out for more info. Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- include/libvirt/libvirt-domain.h | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h index 9199cc9ad3..27a680a907 100644 --- a/include/libvirt/libvirt-domain.h +++ b/include/libvirt/libvirt-domain.h @@ -2758,18 +2758,18 @@ int virDomainGetVcpus (virDomainPtr domain, /** * virDomainDeviceModifyFlags: * - * Since: v1.0.0 + * These flags may be bitwise-OR'd in. + * + * Since: v0.7.7 * */ typedef enum { - /* See virDomainModificationImpact for these flags. (Since: v1.0.0) */ - VIR_DOMAIN_DEVICE_MODIFY_CURRENT = VIR_DOMAIN_AFFECT_CURRENT, - VIR_DOMAIN_DEVICE_MODIFY_LIVE = VIR_DOMAIN_AFFECT_LIVE, - VIR_DOMAIN_DEVICE_MODIFY_CONFIG = VIR_DOMAIN_AFFECT_CONFIG, + VIR_DOMAIN_DEVICE_MODIFY_CURRENT = VIR_DOMAIN_AFFECT_CURRENT, /* See virDomainModificationImpact (Since: v0.7.7) */ + VIR_DOMAIN_DEVICE_MODIFY_LIVE = VIR_DOMAIN_AFFECT_LIVE, /* (Since: v0.7.7) */ + VIR_DOMAIN_DEVICE_MODIFY_CONFIG = VIR_DOMAIN_AFFECT_CONFIG, /* (Since: v0.7.7) */ - /* Additionally, these flags may be bitwise-OR'd in. (Since: v1.0.0) */ VIR_DOMAIN_DEVICE_MODIFY_FORCE = (1 << 2), /* Forcibly modify device - (ex. force eject a cdrom) */ + (ex. force eject a cdrom) (Since: v0.8.6) */ } virDomainDeviceModifyFlags; int virDomainAttachDevice(virDomainPtr domain, const char *xml); -- 2.35.1

On Thu, Apr 21, 2022 at 15:51:25 +0200, Peter Krempa wrote: I'm unsure how to get about this. Either squash this to the appropriate commit or perhaps remove the comments breaking stuff before and then just apply the numbers along in the patch doing everything else.

This commit is similar to "docs: Fix generated documentation of virConnectListAllNodeDeviceFlags", check it out for more info. Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- include/libvirt/libvirt-domain.h | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h index 27a680a907..67cbc0d08e 100644 --- a/include/libvirt/libvirt-domain.h +++ b/include/libvirt/libvirt-domain.h @@ -1958,18 +1958,17 @@ int virDomainGetMemoryParameters(virDomainPtr domain, * virDomainMemoryModFlags: * * Memory size modification flags. + * These flags may be bitwise-OR'd in. * - * Since: v1.0.0 + * Since: v0.9.0 * */ typedef enum { - /* See virDomainModificationImpact for these flags. (Since: v1.0.0) */ - VIR_DOMAIN_MEM_CURRENT = VIR_DOMAIN_AFFECT_CURRENT, - VIR_DOMAIN_MEM_LIVE = VIR_DOMAIN_AFFECT_LIVE, - VIR_DOMAIN_MEM_CONFIG = VIR_DOMAIN_AFFECT_CONFIG, + VIR_DOMAIN_MEM_CURRENT = VIR_DOMAIN_AFFECT_CURRENT, /* See virDomainModificationImpact (Since: v0.9.1) */ + VIR_DOMAIN_MEM_LIVE = VIR_DOMAIN_AFFECT_LIVE, /* See virDomainModificationImpact (Since: v0.9.0) */ + VIR_DOMAIN_MEM_CONFIG = VIR_DOMAIN_AFFECT_CONFIG, /* See virDomainModificationImpact (Since: v0.9.0) */ - /* Additionally, these flags may be bitwise-OR'd in. (Since: v1.0.0) */ - VIR_DOMAIN_MEM_MAXIMUM = (1 << 2), /* affect Max rather than current */ + VIR_DOMAIN_MEM_MAXIMUM = (1 << 2), /* affect Max rather than current (Since: v0.9.1) */ } virDomainMemoryModFlags; -- 2.35.1

This commit is similar to "docs: Fix generated documentation of virConnectListAllNodeDeviceFlags", check it out for more info. Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- include/libvirt/libvirt-domain.h | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h index 67cbc0d08e..689a17a223 100644 --- a/include/libvirt/libvirt-domain.h +++ b/include/libvirt/libvirt-domain.h @@ -2491,20 +2491,19 @@ typedef virVcpuInfo *virVcpuInfoPtr; * virDomainVcpuFlags: * * Flags for controlling virtual CPU hot-plugging. + * These flags may be bitwise-OR'd in. * - * Since: v1.0.0 + * Since: v0.8.5 * */ typedef enum { - /* See virDomainModificationImpact for these flags. (Since: v1.0.0) */ - VIR_DOMAIN_VCPU_CURRENT = VIR_DOMAIN_AFFECT_CURRENT, - VIR_DOMAIN_VCPU_LIVE = VIR_DOMAIN_AFFECT_LIVE, - VIR_DOMAIN_VCPU_CONFIG = VIR_DOMAIN_AFFECT_CONFIG, - - /* Additionally, these flags may be bitwise-OR'd in. (Since: v1.0.0) */ - VIR_DOMAIN_VCPU_MAXIMUM = (1 << 2), /* Max rather than current count (Since: v1.1.0) */ - VIR_DOMAIN_VCPU_GUEST = (1 << 3), /* Modify state of the cpu in the guest (Since: v2.4.0) */ - VIR_DOMAIN_VCPU_HOTPLUGGABLE = (1 << 4), /* Make vcpus added hot(un)pluggable */ + VIR_DOMAIN_VCPU_CURRENT = VIR_DOMAIN_AFFECT_CURRENT, /* See virDomainModificationImpact (Since: v0.9.4) */ + VIR_DOMAIN_VCPU_LIVE = VIR_DOMAIN_AFFECT_LIVE, /* See virDomainModificationImpact (Since: v0.8.5) */ + VIR_DOMAIN_VCPU_CONFIG = VIR_DOMAIN_AFFECT_CONFIG, /* See virDomainModificationImpact (Since: v0.8.5) */ + + VIR_DOMAIN_VCPU_MAXIMUM = (1 << 2), /* Max rather than current count (Since: v0.8.5) */ + VIR_DOMAIN_VCPU_GUEST = (1 << 3), /* Modify state of the cpu in the guest (Since: v1.1.0) */ + VIR_DOMAIN_VCPU_HOTPLUGGABLE = (1 << 4), /* Make vcpus added hot(un)pluggable (Since: v2.4.0) */ } virDomainVcpuFlags; int virDomainSetVcpus (virDomainPtr domain, -- 2.35.1

Removed the TODO as we can rely to the serialize_typedef() the job to report missing comments. Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- scripts/apibuild.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/scripts/apibuild.py b/scripts/apibuild.py index 19e897b1ba..ddc2fff7af 100755 --- a/scripts/apibuild.py +++ b/scripts/apibuild.py @@ -1145,6 +1145,12 @@ class CParser: def parseTypedef(self, token): if token is None: return None + + # With typedef enum types, we can have comments parsed before the + # enum themselves. The parsing of enum values does clear the + # self.comment variable. So we store it here for later. + typedef_comment = self.comment + token = self.parseType(token) if token is None: self.error("parsing typedef") @@ -1168,7 +1174,7 @@ class CParser: "struct", type) base_type = "struct " + name else: - # TODO report missing or misformatted comments + self.comment = typedef_comment info = self.parseTypeComment(name, 1) self.index_add(name, self.filename, not self.is_header, "typedef", type, info) -- 2.35.1

This patch adds 'version' parameter to the generated XML API for macros It'll require, for new additions, to add a comment with the version that the macro was added. An example bellow of code diff and the change in the generated XML. Note that the Since tag is removed from the comment as there is a proper field for it in the XML. Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- scripts/apibuild.py | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/scripts/apibuild.py b/scripts/apibuild.py index 24ca98bd1c..b77eea0624 100755 --- a/scripts/apibuild.py +++ b/scripts/apibuild.py @@ -2267,11 +2267,15 @@ class docBuilder: output.write(" string='%s'" % strValue) else: output.write(" raw='%s'" % escape(rawValue)) + + (since, comment) = self.retrieve_comment_tags(name, desc) + if len(since) > 0: + output.write(" version='%s'" % escape(since)) output.write(">\n") - if desc is not None and desc != "": - output.write(" <info><![CDATA[%s]]></info>\n" % (desc)) - self.indexString(name, desc) + if comment is not None and comment != "": + output.write(" <info><![CDATA[%s]]></info>\n" % (comment)) + self.indexString(name, comment) for arg in args: (name, desc) = arg if desc is not None and desc != "": -- 2.35.1

On Wed, Apr 20, 2022 at 21:08:16 +0200, Victor Toso wrote: Let's review the outliers and then the script which generated the rest: We've discussed this one. Your script seems to have picked a stable release which we did at some point. The v1.0.6 where the symbol is exported is correct. This would be also the only outlier which has a 4 digit version string. So the Since tag needs to be fixed and this removed. This is an unfortunate side-effect of grepping in the repository rather than looking for actual code. 'virNodeDeviceCreate' was indeed mentioned in a comment in the version you've added here, but was in fact implemented at the time it was actually exported. This entry needs to be removed and the Since tag fixed. All of the above should be removed and the Since tag should say v2.0.0 to match the symbol as that's the first point at which we've exported these. This one is needed as it's a mistake in the symbol export. This is a mistake in our repo. The 'v0.4.5' tag is missing but the function was added and exported in time of v0.4.5. Remove this entry and fix the since tag. Same as above. So in this case the code was added indeed post v0.4.2 release but the symbol was exported in the previous one, although it happened prior to v0.4.3 was released, but our repo is missing the tag. So correctly both should be 0.4.3. Not sure what happened here, but v0.10.2 what the script detects in the symbol seems to be correct. Now for these you should follow again when the symbol was exported, many of these functions are mentioned in TODO first and implemented later. As noted previously the Since tag should be the maximum version of following two: 1) when the symbol was exported 2) when it was implemented. In the end I expect this list to be only contain: 'virDomainSetBlockThreshold' 'virAdmServerUpdateTlsFiles' 'virDomainBlockPeek' 'virDomainMemoryPeek'

So we can use for comments that are being hold in helper variables. Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- scripts/apibuild.py | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/scripts/apibuild.py b/scripts/apibuild.py index ec10931151..151eba37e6 100755 --- a/scripts/apibuild.py +++ b/scripts/apibuild.py @@ -789,15 +789,18 @@ class CParser: line = line.replace('*', '', 1) return line - def cleanupComment(self): - if not isinstance(self.comment, str): - return - # remove the leading * on multi-line comments - lines = self.comment.splitlines(True) + def cleanup_code_comment(self, comment: str) -> str: + if not isinstance(self.comment, str) or comment == "": + return "" + + lines = comment.splitlines(True) com = "" for line in lines: com = com + self.strip_lead_star(line) - self.comment = com.strip() + return com.strip() + + def cleanupComment(self): + self.comment = self.cleanup_code_comment(self.comment) def parseComment(self, token): com = token[1] -- 2.35.1

A throw away script to validate that the generated XML has the correct versions. It checks if $keyword is present in $git_tag and also in the $next_git_tag but not in the $previous_git_tag. Takes almost a minute to run, in my computer. | python3 ./scripts/version-quest.py -i ./include/ -d ./build/docs/ | # libvirt has 2101 symbols | # libvirt-qemu has 19 symbols | # libvirt-lxc has 4 symbols | # libvirt-admin has 63 symbols | # Total of 2187 symbols checked Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- scripts/version-quest.py | 190 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 scripts/version-quest.py diff --git a/scripts/version-quest.py b/scripts/version-quest.py new file mode 100644 index 0000000000..01e5d28c59 --- /dev/null +++ b/scripts/version-quest.py @@ -0,0 +1,190 @@ +#!/usr/bin/env python3 +# +# This is a simple utitly script to help check version of exported +# types in XML built with scripts/apibuild.py +# +# See Copyright for the status of this software. +# +# victortoso(a)redhat.com +# + +import os +import re +import argparse + +tags = [] +includedir = "" +xmldir = "" +next_release = "v8.3.0" + +allowlist = { + 'virDomainSetBlockThreshold': '3.2.0', + 'virGetLastErrorMessage': '1.0.5.2', + 'virNodeDeviceCreate': '0.5.0', + 'virAdmClientClose': '1.3.5', + 'virAdmClientFree': '1.3.5', + 'virAdmClientGetID': '1.3.5', + 'virAdmClientGetInfo': '1.3.5', + 'virAdmClientGetTimestamp': '1.3.5', + 'virAdmClientGetTransport': '1.3.5', + 'virAdmConnectClose': '1.2.17', + 'virAdmConnectGetLibVersion': '1.3.1', + 'virAdmConnectGetURI': '1.3.1', + 'virAdmConnectIsAlive': '1.3.1', + 'virAdmConnectListServers': '1.3.2', + 'virAdmConnectLookupServer': '1.3.3', + 'virAdmConnectOpen': '1.2.17', + 'virAdmConnectRef': '1.2.17', + 'virAdmConnectRegisterCloseCallback': '1.3.1', + 'virAdmConnectUnregisterCloseCallback': '1.3.1', + 'virAdmGetVersion': '1.3.0', + 'virAdmServerFree': '1.3.2', + 'virAdmServerGetClientLimits': '1.3.5', + 'virAdmServerGetName': '1.3.2', + 'virAdmServerGetThreadPoolParameters': '1.3.4', + 'virAdmServerListClients': '1.3.5', + 'virAdmServerLookupClient': '1.3.5', + 'virAdmServerSetClientLimits': '1.3.5', + 'virAdmServerSetThreadPoolParameters': '1.3.4', + 'virAdmServerUpdateTlsFiles': '6.2.0', + 'virConnectFindStoragePoolSources': '0.4.6', + 'virConnectNumOfDefinedDomains': '0.1.6', + 'virConnectOpenAuth': '0.4.1', + 'virDomainBlockPeek': '0.4.4', + 'virDomainMemoryPeek': '0.4.4', + 'virNetworkUpdate': '1.0.0', + 'virConnectClose': '0.0.1', + 'virConnectGetType': '0.0.1', + 'virConnectGetVersion': '0.0.1', + 'virConnectListDomains': '0.0.1', + 'virConnectNumOfDomains': '0.0.1', + 'virConnectOpen': '0.0.1', + 'virConnectOpenReadOnly': '0.0.1', + 'virDomainCreateLinux': '0.0.1', + 'virDomainDestroy': '0.0.1', + 'virDomainFree': '0.0.1', + 'virDomainGetID': '0.0.1', + 'virDomainGetInfo': '0.0.1', + 'virDomainGetMaxMemory': '0.0.1', + 'virDomainGetName': '0.0.1', + 'virDomainGetOSType': '0.0.1', + 'virDomainGetXMLDesc': '0.0.1', + 'virDomainLookupByID': '0.0.1', + 'virDomainLookupByName': '0.0.1', + 'virDomainRestore': '0.0.2', + 'virDomainResume': '0.0.1', + 'virDomainSave': '0.0.2', + 'virDomainSetMaxMemory': '0.0.1', + 'virDomainShutdown': '0.0.1', + 'virDomainSuspend': '0.0.1', + 'virGetVersion': '0.0.1', +} + + +def get_symbols(xmlpath: str): + symbols = [] + expression = "<(.*?) name='(.*?)'.*version='(.*?)'" + with open(xmlpath) as file: + for line in file: + r = re.search(expression, line) + if r is not None: + symbols.append(r.groups()) + + return symbols + + +def find_version(symbol, start_version): + index = start_version == "" and -1 or tags.index(start_version) + for i in range(index + 1, len(tags)): + if git_check_symbol(symbol, tags[i]): + return tags[i] + + assert False + + +def get_tags_array() -> list[str]: + # We will be looking symbols at released tags. Only vx.y.z are + # interesting to us. + k = os.popen("git tag --list 'v*' | grep -v 'rc' | sort -V") + alltags = k.read().split() + return alltags + + +def git_check_symbol(symbol, version, full=False) -> bool: + path = full and "" or includedir + s = os.system(f"git grep -rqw {symbol} {version} {path}") + return os.waitstatus_to_exitcode(s) == 0 + + +def check_symbol(symbol, xml_version) -> (bool, str): + # For functions that were released with wrong sym version + if symbol in allowlist: + docversion = f"v{allowlist[symbol]}" + if docversion == xml_version: + return (False, f"{symbol} allowlist versions match: {xml_version}") + + if not git_check_symbol(symbol, docversion, True): + version = find_version(symbol, docversion) + return (False, f"{symbol} allowlist {docversion} => {version}") + + return (True, "") + + # Too recent, just skip. + if xml_version == next_release: + return (True, "") + + if xml_version not in tags: + return (False, f"{symbol}'s {xml_version} does not exist in git tags") + + index = tags.index(xml_version) + + if not git_check_symbol(symbol, tags[index]): + return (False, f"{symbol} does not exist in version {xml_version}") + + # Added in the first release. Seems fine. + if index == 0: + return (True, "") + + # Ooops. Symbol was found in the previous release too. + if git_check_symbol(symbol, tags[index - 1]): + version = find_version(symbol, "") + return (False, f"{symbol} {tags[index]} => real: {version}") + + # Added in the last tag, nothing else to do. + if index == len(tags) - 1: + return (True, "") + + # Ooops. Symbol was not found in the next release. + if not git_check_symbol(symbol, tags[index + 1]): + return (False, f"{symbol} in {tags[index]} but not {tags[index + 1]}") + + return (True, "") + + +if __name__ == "__main__": + parser = argparse.ArgumentParser(description="Quest: Versions!") + parser.add_argument("-d", "--xmldir", type=str, + help="Directory of libvirt-.*.xml APIs") + parser.add_argument("-i", "--includedir", type=str, + help="Include directory of libvirt") + + args = parser.parse_args() + includedir = args.includedir + xmldir = args.xmldir + tags = get_tags_array() + + counter = {} + xmlfiles = ["libvirt", "libvirt-qemu", "libvirt-lxc", "libvirt-admin"] + for xml in xmlfiles: + symbols = get_symbols(f"{xmldir}/{xml}-api.xml") + counter[xml] = len(symbols) + for (symbol_type, symbol_name, symbol_version) in symbols: + ok, errmsg = check_symbol(symbol_name, f"v{symbol_version}") + if not ok: + print(f"{xml}: {symbol_type}: Failed: {errmsg}") + + total = 0 + for xml in counter.keys(): + total += counter[xml] + print(f"# {xml} has {counter[xml]} symbols") + print(f"# Total of {total} symbols checked") -- 2.35.1