[PATCH v3 13/30] docstring: function: libvirt: Add 'Since version' metadata
Victor Toso
victortoso at redhat.com
Wed Apr 20 19:08:02 UTC 2022
Either create or append to existing docstring, the version (git tag)
that a given function was introduced in the format:
Since: v1.2.3
Signed-off-by: Victor Toso <victortoso at redhat.com>
---
include/libvirt/libvirt-domain.h | 75 ++++
include/libvirt/libvirt-event.h | 24 ++
include/libvirt/libvirt-host.h | 6 +
include/libvirt/libvirt-network.h | 6 +
include/libvirt/libvirt-nodedev.h | 6 +
include/libvirt/libvirt-secret.h | 6 +
include/libvirt/libvirt-storage.h | 6 +
include/libvirt/libvirt-stream.h | 18 +
include/libvirt/virterror.h | 3 +
src/libvirt-domain-checkpoint.c | 36 ++
src/libvirt-domain-snapshot.c | 63 ++++
src/libvirt-domain.c | 557 +++++++++++++++++++++++++++++-
src/libvirt-host.c | 102 ++++++
src/libvirt-interface.c | 63 ++++
src/libvirt-network.c | 135 ++++++++
src/libvirt-nodedev.c | 81 +++++
src/libvirt-nwfilter.c | 72 ++++
src/libvirt-secret.c | 60 ++++
src/libvirt-storage.c | 171 +++++++++
src/libvirt-stream.c | 51 +++
src/libvirt.c | 18 +
src/util/virerror.c | 45 +++
src/util/virevent.c | 27 ++
23 files changed, 1630 insertions(+), 1 deletion(-)
diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index 5654a50c7e..9199cc9ad3 100644
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -4215,6 +4215,9 @@ typedef enum {
* A callback function to be registered, and called when a domain event occurs
*
* Returns 0 (the return value is currently ignored)
+ *
+ * Since: v0.5.0
+ *
*/
typedef int (*virConnectDomainEventCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -4801,6 +4804,9 @@ typedef enum {
* have a customization with extra parameters, often with @opaque being
* passed in a different parameter position; use VIR_DOMAIN_EVENT_CALLBACK()
* when registering an appropriate handler.
+ *
+ * Since: v0.8.0
+ *
*/
typedef void (*virConnectDomainEventGenericCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -4815,6 +4821,9 @@ typedef void (*virConnectDomainEventGenericCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_RTC_CHANGE with virConnectDomainEventRegisterAny()
+ *
+ * Since: v0.8.0
+ *
*/
typedef void (*virConnectDomainEventRTCChangeCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -4853,6 +4862,9 @@ typedef enum {
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_WATCHDOG with virConnectDomainEventRegisterAny()
*
+ * Since: v0.8.0
+ *
+ *
*/
typedef void (*virConnectDomainEventWatchdogCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -4889,6 +4901,9 @@ typedef enum {
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_IO_ERROR with virConnectDomainEventRegisterAny()
+ *
+ * Since: v0.8.0
+ *
*/
typedef void (*virConnectDomainEventIOErrorCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -4916,6 +4931,9 @@ typedef void (*virConnectDomainEventIOErrorCallback)(virConnectPtr conn,
* Otherwise, @reason will be "", although future strings may be added
* if determination of other error types becomes possible.
*
+ * Since: v0.8.1
+ *
+ *
*/
typedef void (*virConnectDomainEventIOErrorReasonCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5069,6 +5087,9 @@ typedef virDomainEventGraphicsSubject *virDomainEventGraphicsSubjectPtr;
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_GRAPHICS with virConnectDomainEventRegisterAny()
+ *
+ * Since: v0.8.0
+ *
*/
typedef void (*virConnectDomainEventGraphicsCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5122,6 +5143,9 @@ typedef enum {
* was registered using the newer type of VIR_DOMAIN_EVENT_ID_BLOCK_JOB_2,
* then @disk will contain the device target shorthand (the <target
* dev='...'/> sub-element, such as "vda").
+ *
+ * Since: v0.9.4
+ *
*/
typedef void (*virConnectDomainEventBlockJobCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5176,6 +5200,9 @@ typedef enum {
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_DISK_CHANGE with virConnectDomainEventRegisterAny()
+ *
+ * Since: v0.9.7
+ *
*/
typedef void (*virConnectDomainEventDiskChangeCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5214,6 +5241,9 @@ typedef enum {
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_TRAY_CHANGE with virConnectDomainEventRegisterAny()
+ *
+ * Since: v0.9.11
+ *
*/
typedef void (*virConnectDomainEventTrayChangeCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5233,6 +5263,9 @@ typedef void (*virConnectDomainEventTrayChangeCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_PMWAKEUP with virConnectDomainEventRegisterAny()
+ *
+ * Since: v0.9.11
+ *
*/
typedef void (*virConnectDomainEventPMWakeupCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5251,6 +5284,9 @@ typedef void (*virConnectDomainEventPMWakeupCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_PMSUSPEND with virConnectDomainEventRegisterAny()
+ *
+ * Since: v0.9.11
+ *
*/
typedef void (*virConnectDomainEventPMSuspendCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5267,6 +5303,9 @@ typedef void (*virConnectDomainEventPMSuspendCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_BALLOON_CHANGE with virConnectDomainEventRegisterAny()
+ *
+ * Since: v0.10.0
+ *
*/
typedef void (*virConnectDomainEventBalloonChangeCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5285,6 +5324,9 @@ typedef void (*virConnectDomainEventBalloonChangeCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_PMSUSPEND_DISK with virConnectDomainEventRegisterAny()
+ *
+ * Since: v1.0.0
+ *
*/
typedef void (*virConnectDomainEventPMSuspendDiskCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5302,6 +5344,9 @@ typedef void (*virConnectDomainEventPMSuspendDiskCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_DEVICE_REMOVED with virConnectDomainEventRegisterAny()
+ *
+ * Since: v1.1.1
+ *
*/
typedef void (*virConnectDomainEventDeviceRemovedCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5319,6 +5364,9 @@ typedef void (*virConnectDomainEventDeviceRemovedCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_DEVICE_ADDED with virConnectDomainEventRegisterAny()
+ *
+ * Since: v1.2.15
+ *
*/
typedef void (*virConnectDomainEventDeviceAddedCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5338,6 +5386,9 @@ typedef void (*virConnectDomainEventDeviceAddedCallback)(virConnectPtr conn,
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_DEVICE_REMOVAL_FAILED with
* virConnectDomainEventRegisterAny().
+ *
+ * Since: v1.3.4
+ *
*/
typedef void (*virConnectDomainEventDeviceRemovalFailedCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5356,6 +5407,9 @@ typedef void (*virConnectDomainEventDeviceRemovalFailedCallback)(virConnectPtr c
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_METADATA_CHANGE with virConnectDomainEventRegisterAny().
+ *
+ * Since: v3.0.0
+ *
*/
typedef void (*virConnectDomainEventMetadataChangeCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5379,6 +5433,9 @@ typedef void (*virConnectDomainEventMetadataChangeCallback)(virConnectPtr conn,
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_MIGRATION_ITERATION with
* virConnectDomainEventRegisterAny().
+ *
+ * Since: v1.3.2
+ *
*/
typedef void (*virConnectDomainEventMigrationIterationCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5403,6 +5460,9 @@ typedef void (*virConnectDomainEventMigrationIterationCallback)(virConnectPtr co
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_JOB_COMPLETED with
* virConnectDomainEventRegisterAny().
+ *
+ * Since: v1.3.3
+ *
*/
typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5801,6 +5861,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_TUNABLE with virConnectDomainEventRegisterAny()
+ *
+ * Since: v1.2.9
+ *
*/
typedef void (*virConnectDomainEventTunableCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5853,6 +5916,9 @@ typedef enum {
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_AGENT_LIFECYCLE with virConnectDomainEventRegisterAny()
+ *
+ * Since: v1.2.11
+ *
*/
typedef void (*virConnectDomainEventAgentLifecycleCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5882,6 +5948,9 @@ typedef void (*virConnectDomainEventAgentLifecycleCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD with virConnectDomainEventRegisterAny()
+ *
+ * Since: v3.2.0
+ *
*/
typedef void (*virConnectDomainEventBlockThresholdCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5907,6 +5976,9 @@ typedef void (*virConnectDomainEventBlockThresholdCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_MEMORY_FAILURE with virConnectDomainEventRegisterAny()
+ *
+ * Since: v6.9.0
+ *
*/
typedef void (*virConnectDomainEventMemoryFailureCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -5931,6 +6003,9 @@ typedef void (*virConnectDomainEventMemoryFailureCallback)(virConnectPtr conn,
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_MEMORY_DEVICE_SIZE_CHANGE with
* virConnectDomainEventRegisterAny().
+ *
+ * Since: v7.9.0
+ *
*/
typedef void (*virConnectDomainEventMemoryDeviceSizeChangeCallback)(virConnectPtr conn,
virDomainPtr dom,
diff --git a/include/libvirt/libvirt-event.h b/include/libvirt/libvirt-event.h
index fe2234913f..7a6483fb8d 100644
--- a/include/libvirt/libvirt-event.h
+++ b/include/libvirt/libvirt-event.h
@@ -55,6 +55,9 @@ typedef enum {
*
* Callback for receiving file handle events. The callback will
* be invoked once for each event which is pending.
+ *
+ * Since: v0.5.0
+ *
*/
typedef void (*virEventHandleCallback)(int watch, int fd, int events, void *opaque);
@@ -82,6 +85,9 @@ typedef void (*virEventHandleCallback)(int watch, int fd, int events, void *opaq
*
* Returns -1 if the file handle cannot be registered, otherwise a handle
* watch number to be used for updating and unregistering for events
+ *
+ * Since: v0.5.0
+ *
*/
typedef int (*virEventAddHandleFunc)(int fd, int event,
virEventHandleCallback cb,
@@ -95,6 +101,9 @@ typedef int (*virEventAddHandleFunc)(int fd, int event,
*
* Part of the EventImpl, this user-provided callback is notified when
* events to listen on change
+ *
+ * Since: v0.5.0
+ *
*/
typedef void (*virEventUpdateHandleFunc)(int watch, int event);
@@ -110,6 +119,9 @@ typedef void (*virEventUpdateHandleFunc)(int watch, int event);
* function call, when it is safe to release the user data.
*
* Returns -1 if the file handle was not registered, 0 upon success
+ *
+ * Since: v0.5.0
+ *
*/
typedef int (*virEventRemoveHandleFunc)(int watch);
@@ -120,6 +132,9 @@ typedef int (*virEventRemoveHandleFunc)(int watch);
* @opaque: user data registered with handle
*
* callback for receiving timer events
+ *
+ * Since: v0.5.0
+ *
*/
typedef void (*virEventTimeoutCallback)(int timer, void *opaque);
@@ -138,6 +153,9 @@ typedef void (*virEventTimeoutCallback)(int timer, void *opaque);
* this purpose.
*
* Returns a timer value
+ *
+ * Since: v0.5.0
+ *
*/
typedef int (*virEventAddTimeoutFunc)(int timeout,
virEventTimeoutCallback cb,
@@ -151,6 +169,9 @@ typedef int (*virEventAddTimeoutFunc)(int timeout,
*
* Part of the EventImpl, this user-defined callback updates an
* event timeout.
+ *
+ * Since: v0.5.0
+ *
*/
typedef void (*virEventUpdateTimeoutFunc)(int timer, int timeout);
@@ -165,6 +186,9 @@ typedef void (*virEventUpdateTimeoutFunc)(int timer, int timeout);
* function call, when it is safe to release the user data.
*
* Returns 0 on success, -1 on failure
+ *
+ * Since: v0.5.0
+ *
*/
typedef int (*virEventRemoveTimeoutFunc)(int timer);
diff --git a/include/libvirt/libvirt-host.h b/include/libvirt/libvirt-host.h
index 1996ea87c9..7c0f487708 100644
--- a/include/libvirt/libvirt-host.h
+++ b/include/libvirt/libvirt-host.h
@@ -705,6 +705,9 @@ typedef virConnectCredential *virConnectCredentialPtr;
* If an interaction cannot be filled, fill in NULL and 0.
*
* Returns 0 if all interactions were filled, or -1 upon error
+ *
+ * Since: v0.4.1
+ *
*/
typedef int (*virConnectAuthCallbackPtr)(virConnectCredentialPtr cred,
unsigned int ncred,
@@ -912,6 +915,9 @@ int virConnectSetKeepAlive(virConnectPtr conn,
*
* A callback function to be registered, and called when the connection
* is closed.
+ *
+ * Since: v0.10.0
+ *
*/
typedef void (*virConnectCloseFunc)(virConnectPtr conn,
int reason,
diff --git a/include/libvirt/libvirt-network.h b/include/libvirt/libvirt-network.h
index d735611437..6957b60ef1 100644
--- a/include/libvirt/libvirt-network.h
+++ b/include/libvirt/libvirt-network.h
@@ -312,6 +312,9 @@ typedef enum {
*
* The callback signature to use when registering for an event of type
* VIR_NETWORK_EVENT_ID_LIFECYCLE with virConnectNetworkEventRegisterAny()
+ *
+ * Since: v1.2.1
+ *
*/
typedef void (*virConnectNetworkEventLifecycleCallback)(virConnectPtr conn,
virNetworkPtr net,
@@ -415,6 +418,9 @@ int virNetworkGetDHCPLeases(virNetworkPtr network,
* have a customization with extra parameters, often with @opaque being
* passed in a different parameter position; use VIR_NETWORK_EVENT_CALLBACK()
* when registering an appropriate handler.
+ *
+ * Since: v1.2.1
+ *
*/
typedef void (*virConnectNetworkEventGenericCallback)(virConnectPtr conn,
virNetworkPtr net,
diff --git a/include/libvirt/libvirt-nodedev.h b/include/libvirt/libvirt-nodedev.h
index 1bec57fca4..12ea115514 100644
--- a/include/libvirt/libvirt-nodedev.h
+++ b/include/libvirt/libvirt-nodedev.h
@@ -209,6 +209,9 @@ typedef enum {
* have a customization with extra parameters, often with @opaque being
* passed in a different parameter position; use
* VIR_NODE_DEVICE_EVENT_CALLBACK() when registering an appropriate handler.
+ *
+ * Since: v2.2.0
+ *
*/
typedef void (*virConnectNodeDeviceEventGenericCallback)(virConnectPtr conn,
virNodeDevicePtr dev,
@@ -259,6 +262,9 @@ typedef enum {
* The callback signature to use when registering for an event of type
* VIR_NODE_DEVICE_EVENT_ID_LIFECYCLE with
* virConnectNodeDeviceEventRegisterAny()
+ *
+ * Since: v2.2.0
+ *
*/
typedef void (*virConnectNodeDeviceEventLifecycleCallback)(virConnectPtr conn,
virNodeDevicePtr dev,
diff --git a/include/libvirt/libvirt-secret.h b/include/libvirt/libvirt-secret.h
index 92fd03f726..e0023f551b 100644
--- a/include/libvirt/libvirt-secret.h
+++ b/include/libvirt/libvirt-secret.h
@@ -189,6 +189,9 @@ typedef enum {
* have a customization with extra parameters, often with @opaque being
* passed in a different parameter position; use
* VIR_SECRET_EVENT_CALLBACK() when registering an appropriate handler.
+ *
+ * Since: v3.0.0
+ *
*/
typedef void (*virConnectSecretEventGenericCallback)(virConnectPtr conn,
virSecretPtr secret,
@@ -237,6 +240,9 @@ typedef enum {
* The callback signature to use when registering for an event of type
* VIR_SECRET_EVENT_ID_LIFECYCLE with
* virConnectSecretEventRegisterAny()
+ *
+ * Since: v3.0.0
+ *
*/
typedef void (*virConnectSecretEventLifecycleCallback)(virConnectPtr conn,
virSecretPtr secret,
diff --git a/include/libvirt/libvirt-storage.h b/include/libvirt/libvirt-storage.h
index 0b27d5d99f..434454f455 100644
--- a/include/libvirt/libvirt-storage.h
+++ b/include/libvirt/libvirt-storage.h
@@ -588,6 +588,9 @@ typedef enum {
* have a customization with extra parameters, often with @opaque being
* passed in a different parameter position; use
* VIR_STORAGE_POOL_EVENT_CALLBACK() when registering an appropriate handler.
+ *
+ * Since: v2.0.0
+ *
*/
typedef void (*virConnectStoragePoolEventGenericCallback)(virConnectPtr conn,
virStoragePoolPtr pool,
@@ -640,6 +643,9 @@ typedef enum {
* The callback signature to use when registering for an event of type
* VIR_STORAGE_POOL_EVENT_ID_LIFECYCLE with
* virConnectStoragePoolEventRegisterAny()
+ *
+ * Since: v2.0.0
+ *
*/
typedef void (*virConnectStoragePoolEventLifecycleCallback)(virConnectPtr conn,
virStoragePoolPtr pool,
diff --git a/include/libvirt/libvirt-stream.h b/include/libvirt/libvirt-stream.h
index caf6779cd6..06f771b40b 100644
--- a/include/libvirt/libvirt-stream.h
+++ b/include/libvirt/libvirt-stream.h
@@ -100,6 +100,9 @@ int virStreamRecvHole(virStreamPtr,
*
* Returns the number of bytes filled, 0 upon end
* of file, or -1 upon error
+ *
+ * Since: v0.7.2
+ *
*/
typedef int (*virStreamSourceFunc)(virStreamPtr st,
char *data,
@@ -138,6 +141,9 @@ int virStreamSendAll(virStreamPtr st,
*
* Returns 0 on success,
* -1 upon error
+ *
+ * Since: v3.4.0
+ *
*/
typedef int (*virStreamSourceHoleFunc)(virStreamPtr st,
int *inData,
@@ -164,6 +170,9 @@ typedef int (*virStreamSourceHoleFunc)(virStreamPtr st,
*
* Returns 0 on success,
* -1 upon error.
+ *
+ * Since: v3.4.0
+ *
*/
typedef int (*virStreamSourceSkipFunc)(virStreamPtr st,
long long length,
@@ -201,6 +210,9 @@ int virStreamSparseSendAll(virStreamPtr st,
*
* Returns the number of bytes consumed or -1 upon
* error
+ *
+ * Since: v0.7.2
+ *
*/
typedef int (*virStreamSinkFunc)(virStreamPtr st,
const char *data,
@@ -231,6 +243,9 @@ int virStreamRecvAll(virStreamPtr st,
*
* Returns 0 on success,
* -1 upon error
+ *
+ * Since: v3.4.0
+ *
*/
typedef int (*virStreamSinkHoleFunc)(virStreamPtr st,
long long length,
@@ -264,6 +279,9 @@ typedef enum {
*
* Callback for receiving stream events. The callback will
* be invoked once for each event which is pending.
+ *
+ * Since: v0.7.2
+ *
*/
typedef void (*virStreamEventCallback)(virStreamPtr stream, int events, void *opaque);
diff --git a/include/libvirt/virterror.h b/include/libvirt/virterror.h
index 6d15c12358..3ae95cb980 100644
--- a/include/libvirt/virterror.h
+++ b/include/libvirt/virterror.h
@@ -366,6 +366,9 @@ typedef enum {
* @error: the error being raised.
*
* Signature of a function to use when there is an error raised by the library.
+ *
+ * Since: v0.1.0
+ *
*/
typedef void (*virErrorFunc) (void *userData, virErrorPtr error);
diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c
index 58ee26857d..37a895e771 100644
--- a/src/libvirt-domain-checkpoint.c
+++ b/src/libvirt-domain-checkpoint.c
@@ -35,6 +35,9 @@ VIR_LOG_INIT("libvirt.domain-checkpoint");
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* as its lifetime will be the same as the checkpoint object.
+ *
+ * Since: v5.6.0
+ *
*/
const char *
virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint)
@@ -58,6 +61,9 @@ virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint)
* call.
*
* Returns the domain or NULL.
+ *
+ * Since: v5.6.0
+ *
*/
virDomainPtr
virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint)
@@ -81,6 +87,9 @@ virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint)
* call.
*
* Returns the connection or NULL.
+ *
+ * Since: v5.6.0
+ *
*/
virConnectPtr
virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint)
@@ -138,6 +147,9 @@ virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint)
*
* Returns an (opaque) new virDomainCheckpointPtr on success or NULL
* on failure.
+ *
+ * Since: v5.6.0
+ *
*/
virDomainCheckpointPtr
virDomainCheckpointCreateXML(virDomainPtr domain,
@@ -207,6 +219,9 @@ virDomainCheckpointCreateXML(virDomainPtr domain,
*
* Returns a 0 terminated UTF-8 encoded XML instance or NULL in case
* of error. The caller must free() the returned value.
+ *
+ * Since: v5.6.0
+ *
*/
char *
virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint,
@@ -281,6 +296,9 @@ virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint,
* included in the return count, to make iteration easier. The caller is
* responsible for calling virDomainCheckpointFree() on each array element,
* then calling free() on @checkpoints.
+ *
+ * Since: v5.6.0
+ *
*/
int
virDomainListAllCheckpoints(virDomainPtr domain,
@@ -348,6 +366,9 @@ virDomainListAllCheckpoints(virDomainPtr domain,
* in the return count, to make iteration easier. The caller is responsible
* for calling virDomainCheckpointFree() on each array element, then calling
* free() on @children.
+ *
+ * Since: v5.6.0
+ *
*/
int
virDomainCheckpointListAllChildren(virDomainCheckpointPtr checkpoint,
@@ -394,6 +415,9 @@ virDomainCheckpointListAllChildren(virDomainCheckpointPtr checkpoint,
* Returns a domain checkpoint object or NULL in case of failure. If the
* domain checkpoint cannot be found, then the VIR_ERR_NO_DOMAIN_CHECKPOINT
* error is raised.
+ *
+ * Since: v5.6.0
+ *
*/
virDomainCheckpointPtr
virDomainCheckpointLookupByName(virDomainPtr domain,
@@ -440,6 +464,9 @@ virDomainCheckpointLookupByName(virDomainPtr domain,
* Returns a domain checkpoint object or NULL in case of failure. If the
* given checkpoint is a root (no parent), then the VIR_ERR_NO_DOMAIN_CHECKPOINT
* error is raised.
+ *
+ * Since: v5.6.0
+ *
*/
virDomainCheckpointPtr
virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint,
@@ -493,6 +520,9 @@ virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint,
* silently ignored.
*
* Returns 0 on success, -1 on error.
+ *
+ * Since: v5.6.0
+ *
*/
int
virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint,
@@ -543,6 +573,9 @@ virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint,
* increment the reference count.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v5.6.0
+ *
*/
int
virDomainCheckpointRef(virDomainCheckpointPtr checkpoint)
@@ -566,6 +599,9 @@ virDomainCheckpointRef(virDomainCheckpointPtr checkpoint)
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v5.6.0
+ *
*/
int
virDomainCheckpointFree(virDomainCheckpointPtr checkpoint)
diff --git a/src/libvirt-domain-snapshot.c b/src/libvirt-domain-snapshot.c
index 69845918a2..f9fc1d4f2b 100644
--- a/src/libvirt-domain-snapshot.c
+++ b/src/libvirt-domain-snapshot.c
@@ -35,6 +35,9 @@ VIR_LOG_INIT("libvirt.domain-snapshot");
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* as its lifetime will be the same as the snapshot object.
+ *
+ * Since: v0.9.5
+ *
*/
const char *
virDomainSnapshotGetName(virDomainSnapshotPtr snapshot)
@@ -58,6 +61,9 @@ virDomainSnapshotGetName(virDomainSnapshotPtr snapshot)
* call.
*
* Returns the domain or NULL.
+ *
+ * Since: v0.9.5
+ *
*/
virDomainPtr
virDomainSnapshotGetDomain(virDomainSnapshotPtr snapshot)
@@ -81,6 +87,9 @@ virDomainSnapshotGetDomain(virDomainSnapshotPtr snapshot)
* call.
*
* Returns the connection or NULL.
+ *
+ * Since: v0.9.5
+ *
*/
virConnectPtr
virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
@@ -213,6 +222,9 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
*
* Returns an (opaque) new virDomainSnapshotPtr on success or NULL on
* failure.
+ *
+ * Since: v0.8.0
+ *
*/
virDomainSnapshotPtr
virDomainSnapshotCreateXML(virDomainPtr domain,
@@ -271,6 +283,9 @@ virDomainSnapshotCreateXML(virDomainPtr domain,
*
* Returns a 0 terminated UTF-8 encoded XML instance or NULL in case
* of error. The caller must free() the returned value.
+ *
+ * Since: v0.8.0
+ *
*/
char *
virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot,
@@ -324,6 +339,9 @@ virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot,
* virDomainListAllSnapshots().
*
* Returns the number of domain snapshots found or -1 in case of error.
+ *
+ * Since: v0.8.0
+ *
*/
int
virDomainSnapshotNum(virDomainPtr domain, unsigned int flags)
@@ -388,6 +406,9 @@ virDomainSnapshotNum(virDomainPtr domain, unsigned int flags)
*
* Returns the number of domain snapshots found or -1 in case of error.
* The caller is responsible to call free() for each member of the array.
+ *
+ * Since: v0.8.0
+ *
*/
int
virDomainSnapshotListNames(virDomainPtr domain, char **names, int nameslen,
@@ -476,6 +497,9 @@ virDomainSnapshotListNames(virDomainPtr domain, char **names, int nameslen,
* in the return count, to make iteration easier. The caller is responsible
* for calling virDomainSnapshotFree() on each array element, then calling
* free() on @snaps.
+ *
+ * Since: v0.9.13
+ *
*/
int
virDomainListAllSnapshots(virDomainPtr domain, virDomainSnapshotPtr **snaps,
@@ -525,6 +549,9 @@ virDomainListAllSnapshots(virDomainPtr domain, virDomainSnapshotPtr **snaps,
* virDomainSnapshotListAllChildren().
*
* Returns the number of domain snapshots found or -1 in case of error.
+ *
+ * Since: v0.9.7
+ *
*/
int
virDomainSnapshotNumChildren(virDomainSnapshotPtr snapshot, unsigned int flags)
@@ -591,6 +618,9 @@ virDomainSnapshotNumChildren(virDomainSnapshotPtr snapshot, unsigned int flags)
*
* Returns the number of domain snapshots found or -1 in case of error.
* The caller is responsible to call free() for each member of the array.
+ *
+ * Since: v0.9.7
+ *
*/
int
virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot,
@@ -662,6 +692,9 @@ virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot,
* in the return count, to make iteration easier. The caller is responsible
* for calling virDomainSnapshotFree() on each array element, then calling
* free() on @snaps.
+ *
+ * Since: v0.9.13
+ *
*/
int
virDomainSnapshotListAllChildren(virDomainSnapshotPtr snapshot,
@@ -706,6 +739,9 @@ virDomainSnapshotListAllChildren(virDomainSnapshotPtr snapshot,
* Returns a domain snapshot object or NULL in case of failure. If the
* domain snapshot cannot be found, then the VIR_ERR_NO_DOMAIN_SNAPSHOT
* error is raised.
+ *
+ * Since: v0.8.0
+ *
*/
virDomainSnapshotPtr
virDomainSnapshotLookupByName(virDomainPtr domain,
@@ -746,6 +782,9 @@ virDomainSnapshotLookupByName(virDomainPtr domain,
* Determine if the domain has a current snapshot.
*
* Returns 1 if such snapshot exists, 0 if it doesn't, -1 on error.
+ *
+ * Since: v0.8.0
+ *
*/
int
virDomainHasCurrentSnapshot(virDomainPtr domain, unsigned int flags)
@@ -786,6 +825,9 @@ virDomainHasCurrentSnapshot(virDomainPtr domain, unsigned int flags)
* Returns a domain snapshot object or NULL in case of failure. If the
* current domain snapshot cannot be found, then the VIR_ERR_NO_DOMAIN_SNAPSHOT
* error is raised.
+ *
+ * Since: v0.8.0
+ *
*/
virDomainSnapshotPtr
virDomainSnapshotCurrent(virDomainPtr domain,
@@ -828,6 +870,9 @@ virDomainSnapshotCurrent(virDomainPtr domain,
* Returns a domain snapshot object or NULL in case of failure. If the
* given snapshot is a root (no parent), then the VIR_ERR_NO_DOMAIN_SNAPSHOT
* error is raised.
+ *
+ * Since: v0.9.7
+ *
*/
virDomainSnapshotPtr
virDomainSnapshotGetParent(virDomainSnapshotPtr snapshot,
@@ -866,6 +911,9 @@ virDomainSnapshotGetParent(virDomainSnapshotPtr snapshot,
* also virDomainHasCurrentSnapshot().
*
* Returns 1 if current, 0 if not current, or -1 on error.
+ *
+ * Since: v0.9.13
+ *
*/
int
virDomainSnapshotIsCurrent(virDomainSnapshotPtr snapshot,
@@ -905,6 +953,9 @@ virDomainSnapshotIsCurrent(virDomainSnapshotPtr snapshot,
*
* Returns 1 if the snapshot has metadata, 0 if the snapshot exists without
* help from libvirt, or -1 on error.
+ *
+ * Since: v0.9.13
+ *
*/
int
virDomainSnapshotHasMetadata(virDomainSnapshotPtr snapshot,
@@ -984,6 +1035,9 @@ virDomainSnapshotHasMetadata(virDomainSnapshotPtr snapshot,
* NVRAM from the pristine template.
*
* Returns 0 if the creation is successful, -1 on error.
+ *
+ * Since: v0.8.0
+ *
*/
int
virDomainRevertToSnapshot(virDomainSnapshotPtr snapshot,
@@ -1041,6 +1095,9 @@ virDomainRevertToSnapshot(virDomainSnapshotPtr snapshot,
*
* Returns 0 if the selected snapshot(s) were successfully deleted,
* -1 on error.
+ *
+ * Since: v0.8.0
+ *
*/
int
virDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
@@ -1091,6 +1148,9 @@ virDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
* increment the reference count.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.9.13
+ *
*/
int
virDomainSnapshotRef(virDomainSnapshotPtr snapshot)
@@ -1114,6 +1174,9 @@ virDomainSnapshotRef(virDomainSnapshotPtr snapshot)
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.8.0
+ *
*/
int
virDomainSnapshotFree(virDomainSnapshotPtr snapshot)
diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index cbd7902d2d..cb7fa7471b 100644
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -49,6 +49,9 @@ VIR_LOG_INIT("libvirt.domain");
* call to virConnectNumOfDomains() and this call; you are only guaranteed
* that all currently active domains were listed if the return is less
* than @maxids.
+ *
+ * Since: v0.0.1
+ *
*/
int
virConnectListDomains(virConnectPtr conn, int *ids, int maxids)
@@ -82,6 +85,9 @@ virConnectListDomains(virConnectPtr conn, int *ids, int maxids)
* Provides the number of active domains.
*
* Returns the number of domain found or -1 in case of error
+ *
+ * Since: v0.0.1
+ *
*/
int
virConnectNumOfDomains(virConnectPtr conn)
@@ -115,6 +121,9 @@ virConnectNumOfDomains(virConnectPtr conn)
* call.
*
* Returns the virConnectPtr or NULL in case of failure.
+ *
+ * Since: v0.3.0
+ *
*/
virConnectPtr
virDomainGetConnect(virDomainPtr dom)
@@ -162,6 +171,9 @@ virDomainGetConnect(virDomainPtr dom)
* domain object is no longer needed.
*
* Returns a new domain object or NULL in case of failure
+ *
+ * Since: v0.5.0
+ *
*/
virDomainPtr
virDomainCreateXML(virConnectPtr conn, const char *xmlDesc,
@@ -228,6 +240,9 @@ virDomainCreateXML(virConnectPtr conn, const char *xmlDesc,
* domain object is no longer needed.
*
* Returns a new domain object or NULL in case of failure
+ *
+ * Since: v1.1.1
+ *
*/
virDomainPtr
virDomainCreateXMLWithFiles(virConnectPtr conn, const char *xmlDesc,
@@ -284,6 +299,9 @@ virDomainCreateXMLWithFiles(virConnectPtr conn, const char *xmlDesc,
* This existing name will be left indefinitely for API compatibility.
*
* Returns a new domain object or NULL in case of failure
+ *
+ * Since: v0.0.1
+ *
*/
virDomainPtr
virDomainCreateLinux(virConnectPtr conn, const char *xmlDesc,
@@ -307,6 +325,9 @@ virDomainCreateLinux(virConnectPtr conn, const char *xmlDesc,
*
* Returns a new domain object or NULL in case of failure. If the
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
+ *
+ * Since: v0.0.1
+ *
*/
virDomainPtr
virDomainLookupByID(virConnectPtr conn, int id)
@@ -346,6 +367,9 @@ virDomainLookupByID(virConnectPtr conn, int id)
*
* Returns a new domain object or NULL in case of failure. If the
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
+ *
+ * Since: v0.0.5
+ *
*/
virDomainPtr
virDomainLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
@@ -385,6 +409,9 @@ virDomainLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
*
* Returns a new domain object or NULL in case of failure. If the
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
+ *
+ * Since: v0.1.1
+ *
*/
virDomainPtr
virDomainLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
@@ -422,6 +449,9 @@ virDomainLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
*
* Returns a new domain object or NULL in case of failure. If the
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
+ *
+ * Since: v0.0.1
+ *
*/
virDomainPtr
virDomainLookupByName(virConnectPtr conn, const char *name)
@@ -472,6 +502,9 @@ virDomainLookupByName(virConnectPtr conn, const char *name)
* be deleted when the domain quits.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.0.1
+ *
*/
int
virDomainDestroy(virDomainPtr domain)
@@ -537,6 +570,9 @@ virDomainDestroy(virDomainPtr domain)
*
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.9.4
+ *
*/
int
virDomainDestroyFlags(virDomainPtr domain,
@@ -577,6 +613,9 @@ virDomainDestroyFlags(virDomainPtr domain,
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.0.1
+ *
*/
int
virDomainFree(virDomainPtr domain)
@@ -608,6 +647,9 @@ virDomainFree(virDomainPtr domain)
* the reference count.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.6.0
+ *
*/
int
virDomainRef(virDomainPtr domain)
@@ -636,6 +678,9 @@ virDomainRef(virDomainPtr domain)
* special state like VIR_DOMAIN_PMSUSPENDED.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.0.1
+ *
*/
int
virDomainSuspend(virDomainPtr domain)
@@ -678,6 +723,9 @@ virDomainSuspend(virDomainPtr domain)
* special state like VIR_DOMAIN_PMSUSPENDED.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.0.1
+ *
*/
int
virDomainResume(virDomainPtr domain)
@@ -734,6 +782,9 @@ virDomainResume(virDomainPtr domain)
*
* Returns: 0 on success,
* -1 on failure.
+ *
+ * Since: v0.9.10
+ *
*/
int
virDomainPMSuspendForDuration(virDomainPtr dom,
@@ -781,6 +832,9 @@ virDomainPMSuspendForDuration(virDomainPtr dom,
*
* Returns: 0 on success,
* -1 on failure.
+ *
+ * Since: v0.9.11
+ *
*/
int
virDomainPMWakeup(virDomainPtr dom,
@@ -828,6 +882,9 @@ virDomainPMWakeup(virDomainPtr dom,
* and virDomainSaveImageDefineXML().
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.0.2
+ *
*/
int
virDomainSave(virDomainPtr domain, const char *to)
@@ -910,6 +967,9 @@ virDomainSave(virDomainPtr domain, const char *to)
* to stop the block job first.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.9.4
+ *
*/
int
virDomainSaveFlags(virDomainPtr domain, const char *to,
@@ -970,6 +1030,9 @@ virDomainSaveFlags(virDomainPtr domain, const char *to,
* See virDomainRestoreFlags() for more control.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.0.2
+ *
*/
int
virDomainRestore(virConnectPtr conn, const char *from)
@@ -1042,6 +1105,9 @@ virDomainRestore(virConnectPtr conn, const char *from)
* pristine template.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.9.4
+ *
*/
int
virDomainRestoreFlags(virConnectPtr conn, const char *from, const char *dxml,
@@ -1104,6 +1170,9 @@ virDomainRestoreFlags(virConnectPtr conn, const char *from, const char *dxml,
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of
* error. The caller must free() the returned value.
+ *
+ * Since: v0.9.4
+ *
*/
char *
virDomainSaveImageGetXMLDesc(virConnectPtr conn, const char *file,
@@ -1172,6 +1241,9 @@ virDomainSaveImageGetXMLDesc(virConnectPtr conn, const char *file,
* exclusive.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.9.4
+ *
*/
int
virDomainSaveImageDefineXML(virConnectPtr conn, const char *file,
@@ -1246,6 +1318,9 @@ virDomainSaveImageDefineXML(virConnectPtr conn, const char *file,
* For more control over the output format, see virDomainCoreDumpWithFormat().
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.1.9
+ *
*/
int
virDomainCoreDump(virDomainPtr domain, const char *to, unsigned int flags)
@@ -1322,6 +1397,9 @@ virDomainCoreDump(virDomainPtr domain, const char *to, unsigned int flags)
* pressure on file system cache, but also risks slowing saves to NFS.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v1.2.3
+ *
*/
int
virDomainCoreDumpWithFormat(virDomainPtr domain, const char *to,
@@ -1401,6 +1479,9 @@ virDomainCoreDumpWithFormat(virDomainPtr domain, const char *to,
*
* Returns a string representing the mime-type of the image format, or
* NULL upon error. The caller must free() the returned value.
+ *
+ * Since: v0.9.2
+ *
*/
char *
virDomainScreenshot(virDomainPtr domain,
@@ -1460,6 +1541,9 @@ virDomainScreenshot(virDomainPtr domain,
* be deleted when the domain quits.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.0.1
+ *
*/
int
virDomainShutdown(virDomainPtr domain)
@@ -1520,6 +1604,9 @@ virDomainShutdown(virDomainPtr domain)
* must have <channel> configured.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.9.10
+ *
*/
int
virDomainShutdownFlags(virDomainPtr domain, unsigned int flags)
@@ -1578,6 +1665,9 @@ virDomainShutdownFlags(virDomainPtr domain, unsigned int flags)
* to a plain shutdown on the destination.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.1.0
+ *
*/
int
virDomainReboot(virDomainPtr domain, unsigned int flags)
@@ -1622,6 +1712,9 @@ virDomainReboot(virDomainPtr domain, unsigned int flags)
* guest OS shutdown.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.9.7
+ *
*/
int
virDomainReset(virDomainPtr domain, unsigned int flags)
@@ -1661,6 +1754,9 @@ virDomainReset(virDomainPtr domain, unsigned int flags)
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* its lifetime will be the same as the domain object.
+ *
+ * Since: v0.0.1
+ *
*/
const char *
virDomainGetName(virDomainPtr domain)
@@ -1683,6 +1779,9 @@ virDomainGetName(virDomainPtr domain)
* Get the UUID for a domain
*
* Returns -1 in case of error, 0 in case of success
+ *
+ * Since: v0.0.5
+ *
*/
int
virDomainGetUUID(virDomainPtr domain, unsigned char *uuid)
@@ -1713,6 +1812,9 @@ virDomainGetUUID(virDomainPtr domain, unsigned char *uuid)
* UUID see RFC4122.
*
* Returns -1 in case of error, 0 in case of success
+ *
+ * Since: v0.1.1
+ *
*/
int
virDomainGetUUIDString(virDomainPtr domain, char *buf)
@@ -1740,6 +1842,9 @@ virDomainGetUUIDString(virDomainPtr domain, char *buf)
* Get the hypervisor ID number for the domain
*
* Returns the domain ID number or (unsigned int) -1 in case of error
+ *
+ * Since: v0.0.1
+ *
*/
unsigned int
virDomainGetID(virDomainPtr domain)
@@ -1762,6 +1867,9 @@ virDomainGetID(virDomainPtr domain)
*
* Returns the new string or NULL in case of error, the string must be
* freed by the caller.
+ *
+ * Since: v0.0.1
+ *
*/
char *
virDomainGetOSType(virDomainPtr domain)
@@ -1801,6 +1909,9 @@ virDomainGetOSType(virDomainPtr domain)
*
* Returns the memory size in kibibytes (blocks of 1024 bytes), or 0 in
* case of error.
+ *
+ * Since: v0.0.1
+ *
*/
unsigned long
virDomainGetMaxMemory(virDomainPtr domain)
@@ -1850,6 +1961,9 @@ virDomainGetMaxMemory(virDomainPtr domain)
* virDomainSetMemoryFlags().
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.0.1
+ *
*/
int
virDomainSetMaxMemory(virDomainPtr domain, unsigned long memory)
@@ -1903,6 +2017,9 @@ virDomainSetMaxMemory(virDomainPtr domain, unsigned long memory)
* virDomainSetMemoryFlags().
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.1.1
+ *
*/
int
virDomainSetMemory(virDomainPtr domain, unsigned long memory)
@@ -1965,6 +2082,9 @@ virDomainSetMemory(virDomainPtr domain, unsigned long memory)
* Not all hypervisors can support all flag combinations.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.9.0
+ *
*/
int
virDomainSetMemoryFlags(virDomainPtr domain, unsigned long memory,
@@ -2025,6 +2145,9 @@ virDomainSetMemoryFlags(virDomainPtr domain, unsigned long memory,
* Not all hypervisors can support all flag combinations.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v1.1.1
+ *
*/
int
virDomainSetMemoryStatsPeriod(virDomainPtr domain, int period,
@@ -2075,6 +2198,9 @@ virDomainSetMemoryStatsPeriod(virDomainPtr domain, int period,
* VIR_DOMAIN_MEMORY_PARAM_UNLIMITED.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.8.5
+ *
*/
int
virDomainSetMemoryParameters(virDomainPtr domain,
@@ -2149,6 +2275,9 @@ virDomainSetMemoryParameters(virDomainPtr domain,
* expects the caller to allocate the @params.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.8.5
+ *
*/
int
virDomainGetMemoryParameters(virDomainPtr domain,
@@ -2216,6 +2345,9 @@ virDomainGetMemoryParameters(virDomainPtr domain,
* Changing persistent configuration does not pose such limitations.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.9.9
+ *
*/
int
virDomainSetNumaParameters(virDomainPtr domain,
@@ -2281,6 +2413,9 @@ virDomainSetNumaParameters(virDomainPtr domain,
* expects the caller to allocate the @params.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.9.9
+ *
*/
int
virDomainGetNumaParameters(virDomainPtr domain,
@@ -2338,6 +2473,9 @@ virDomainGetNumaParameters(virDomainPtr domain,
* This function may require privileged access to the hypervisor.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.9.0
+ *
*/
int
virDomainSetBlkioParameters(virDomainPtr domain,
@@ -2403,6 +2541,9 @@ virDomainSetBlkioParameters(virDomainPtr domain,
* expects the caller to allocate the @params.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.9.0
+ *
*/
int
virDomainGetBlkioParameters(virDomainPtr domain,
@@ -2461,6 +2602,9 @@ virDomainGetBlkioParameters(virDomainPtr domain,
* can be extracted.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.0.1
+ *
*/
int
virDomainGetInfo(virDomainPtr domain, virDomainInfoPtr info)
@@ -2507,6 +2651,9 @@ virDomainGetInfo(virDomainPtr domain, virDomainInfoPtr info)
* which led to the state.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.9.2
+ *
*/
int
virDomainGetState(virDomainPtr domain,
@@ -2550,6 +2697,9 @@ virDomainGetState(virDomainPtr domain,
* Extract details about current state of control interface to a domain.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.9.3
+ *
*/
int
virDomainGetControlInfo(virDomainPtr domain,
@@ -2611,6 +2761,9 @@ virDomainGetControlInfo(virDomainPtr domain,
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case
* of error. The caller must free() the returned value.
+ *
+ * Since: v0.0.1
+ *
*/
char *
virDomainGetXMLDesc(virDomainPtr domain, unsigned int flags)
@@ -2660,6 +2813,9 @@ virDomainGetXMLDesc(virDomainPtr domain, unsigned int flags)
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case
* of error. The caller must free() the returned value.
+ *
+ * Since: v0.6.4
+ *
*/
char *
virConnectDomainXMLFromNative(virConnectPtr conn,
@@ -2710,6 +2866,9 @@ virConnectDomainXMLFromNative(virConnectPtr conn,
*
* Returns a 0 terminated UTF-8 encoded native config datafile, or
* NULL in case of error. The caller must free() the returned value.
+ *
+ * Since: v0.6.4
+ *
*/
char *
virConnectDomainXMLToNative(virConnectPtr conn,
@@ -3563,6 +3722,9 @@ virDomainMigrateUnmanaged(virDomainPtr domain,
* Returns the new domain object if the migration was successful,
* or NULL in case of error. Note that the new domain object
* exists in the scope of the destination connection (dconn).
+ *
+ * Since: v0.3.2
+ *
*/
virDomainPtr
virDomainMigrate(virDomainPtr domain,
@@ -3759,6 +3921,9 @@ virDomainMigrate(virDomainPtr domain,
* Returns the new domain object if the migration was successful,
* or NULL in case of error. Note that the new domain object
* exists in the scope of the destination connection (dconn).
+ *
+ * Since: v0.9.2
+ *
*/
virDomainPtr
virDomainMigrate2(virDomainPtr domain,
@@ -3968,6 +4133,9 @@ virDomainMigrate2(virDomainPtr domain,
* Returns the new domain object if the migration was successful,
* or NULL in case of error. Note that the new domain object
* exists in the scope of the destination connection (dconn).
+ *
+ * Since: v1.1.0
+ *
*/
virDomainPtr
virDomainMigrate3(virDomainPtr domain,
@@ -4256,6 +4424,9 @@ int virDomainMigrateUnmanagedCheckCompat(virDomainPtr domain,
* corresponds to VIR_MIGRATE_PARAM_URI of virDomainMigrateToURI3.
*
* Returns 0 if the migration succeeded, -1 upon error.
+ *
+ * Since: v0.7.2
+ *
*/
int
virDomainMigrateToURI(virDomainPtr domain,
@@ -4332,6 +4503,9 @@ virDomainMigrateToURI(virDomainPtr domain,
* virDomainMigrateToURI3.
*
* Returns 0 if the migration succeeded, -1 upon error.
+ *
+ * Since: v0.9.2
+ *
*/
int
virDomainMigrateToURI2(virDomainPtr domain,
@@ -4412,6 +4586,9 @@ virDomainMigrateToURI2(virDomainPtr domain,
* different types of hypervisor.
*
* Returns 0 if the migration succeeded, -1 upon error.
+ *
+ * Since: v1.1.0
+ *
*/
int
virDomainMigrateToURI3(virDomainPtr domain,
@@ -5281,6 +5458,9 @@ virDomainMigrateConfirm3Params(virDomainPtr domain,
* Get the scheduler type and the number of scheduler parameters.
*
* Returns NULL in case of error. The caller must free the returned string.
+ *
+ * Since: v0.2.3
+ *
*/
char *
virDomainGetSchedulerType(virDomainPtr domain, int *nparams)
@@ -5329,6 +5509,9 @@ virDomainGetSchedulerType(virDomainPtr domain, int *nparams)
* virDomainGetSchedulerParametersFlags().
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.2.3
+ *
*/
int
virDomainGetSchedulerParameters(virDomainPtr domain,
@@ -5394,6 +5577,9 @@ virDomainGetSchedulerParameters(virDomainPtr domain,
* }
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.9.2
+ *
*/
int
virDomainGetSchedulerParametersFlags(virDomainPtr domain,
@@ -5458,6 +5644,9 @@ virDomainGetSchedulerParametersFlags(virDomainPtr domain,
* virDomainSetSchedulerParametersFlags.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.2.3
+ *
*/
int
virDomainSetSchedulerParameters(virDomainPtr domain,
@@ -5512,6 +5701,9 @@ virDomainSetSchedulerParameters(virDomainPtr domain,
* flags are supported.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.9.2
+ *
*/
int
virDomainSetSchedulerParametersFlags(virDomainPtr domain,
@@ -5583,6 +5775,9 @@ virDomainSetSchedulerParametersFlags(virDomainPtr domain,
* that particular statistic.
*
* Returns: 0 in case of success or -1 in case of failure.
+ *
+ * Since: v0.3.2
+ *
*/
int
virDomainBlockStats(virDomainPtr dom, const char *disk,
@@ -5660,6 +5855,9 @@ virDomainBlockStats(virDomainPtr dom, const char *disk,
* again. See virDomainGetMemoryParameters() for more details.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.9.5
+ *
*/
int
virDomainBlockStatsFlags(virDomainPtr dom,
@@ -5729,6 +5927,9 @@ virDomainBlockStatsFlags(virDomainPtr dom,
* The returned stats are from domain's point of view.
*
* Returns: 0 in case of success or -1 in case of failure.
+ *
+ * Since: v0.3.2
+ *
*/
int
virDomainInterfaceStats(virDomainPtr dom, const char *device,
@@ -5789,6 +5990,9 @@ virDomainInterfaceStats(virDomainPtr dom, const char *device,
* This function may require privileged access to the hypervisor.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.9.9
+ *
*/
int
virDomainSetInterfaceParameters(virDomainPtr domain,
@@ -5857,6 +6061,9 @@ virDomainSetInterfaceParameters(virDomainPtr domain,
* expects the caller to allocate the @params.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.9.9
+ *
*/
int
virDomainGetInterfaceParameters(virDomainPtr domain,
@@ -5947,6 +6154,9 @@ virDomainGetInterfaceParameters(virDomainPtr domain,
* The number of failed huge page allocations from inside the domain
*
* Returns: The number of stats provided or -1 in case of failure.
+ *
+ * Since: v0.7.5
+ *
*/
int
virDomainMemoryStats(virDomainPtr dom, virDomainMemoryStatPtr stats,
@@ -6026,6 +6236,9 @@ virDomainMemoryStats(virDomainPtr dom, virDomainMemoryStatPtr stats,
* Now large requests up to 16M byte are supported.
*
* Returns: 0 in case of success or -1 in case of failure.
+ *
+ * Since: v0.4.4
+ *
*/
int
virDomainBlockPeek(virDomainPtr dom,
@@ -6095,6 +6308,9 @@ virDomainBlockPeek(virDomainPtr dom,
* hypervisor.
*
* Returns: 0 in case of success or -1 in case of failure.
+ *
+ * Since: v0.9.8
+ *
*/
int
virDomainBlockResize(virDomainPtr dom,
@@ -6163,6 +6379,9 @@ virDomainBlockResize(virDomainPtr dom,
* Now large requests up to 16M byte are supported.
*
* Returns: 0 in case of success or -1 in case of failure.
+ *
+ * Since: v0.4.4
+ *
*/
int
virDomainMemoryPeek(virDomainPtr dom,
@@ -6299,6 +6518,9 @@ virDomainMemoryPeek(virDomainPtr dom,
* ...
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.8.1
+ *
*/
int
virDomainGetBlockInfo(virDomainPtr domain, const char *disk,
@@ -6349,6 +6571,9 @@ virDomainGetBlockInfo(virDomainPtr domain, const char *disk,
* domain object is no longer needed.
*
* Returns NULL in case of error, a pointer to the domain otherwise
+ *
+ * Since: v0.1.1
+ *
*/
virDomainPtr
virDomainDefineXML(virConnectPtr conn, const char *xml)
@@ -6392,6 +6617,9 @@ virDomainDefineXML(virConnectPtr conn, const char *xml)
* domain object is no longer needed.
*
* Returns NULL in case of error, a pointer to the domain otherwise
+ *
+ * Since: v1.2.12
+ *
*/
virDomainPtr
virDomainDefineXMLFlags(virConnectPtr conn, const char *xml, unsigned int flags)
@@ -6435,6 +6663,9 @@ virDomainDefineXMLFlags(virConnectPtr conn, const char *xml, unsigned int flags)
* will fail. See virDomainUndefineFlags() for more control.
*
* Returns 0 in case of success, -1 in case of error
+ *
+ * Since: v0.1.1
+ *
*/
int
virDomainUndefine(virDomainPtr domain)
@@ -6504,6 +6735,9 @@ virDomainUndefine(virDomainPtr domain)
* VIR_DOMAIN_UNDEFINE_NVRAM is specified to remove the nvram file.
*
* Returns 0 in case of success, -1 in case of error
+ *
+ * Since: v0.9.4
+ *
*/
int
virDomainUndefineFlags(virDomainPtr domain,
@@ -6543,6 +6777,9 @@ virDomainUndefineFlags(virDomainPtr domain,
* Provides the number of defined but inactive domains.
*
* Returns the number of domain found or -1 in case of error
+ *
+ * Since: v0.1.6
+ *
*/
int
virConnectNumOfDefinedDomains(virConnectPtr conn)
@@ -6586,6 +6823,9 @@ virConnectNumOfDefinedDomains(virConnectPtr conn)
* a call to virConnectNumOfDefinedDomains() and this call; you are only
* guaranteed that all currently defined domains were listed if the return
* is less than @maxids. The client must call free() on each returned name.
+ *
+ * Since: v0.1.1
+ *
*/
int
virConnectListDefinedDomains(virConnectPtr conn, char **const names,
@@ -6685,6 +6925,9 @@ virConnectListDefinedDomains(virConnectPtr conn, char **const names,
* extra allocated element set to NULL but not included in the return count, to
* make iteration easier. The caller is responsible for calling virDomainFree()
* on each array element, then calling free() on @domains.
+ *
+ * Since: v0.9.13
+ *
*/
int
virConnectListAllDomains(virConnectPtr conn,
@@ -6726,6 +6969,9 @@ virConnectListAllDomains(virConnectPtr conn,
* control, see virDomainCreateWithFlags().
*
* Returns 0 in case of success, -1 in case of error
+ *
+ * Since: v0.1.1
+ *
*/
int
virDomainCreate(virDomainPtr domain)
@@ -6794,6 +7040,9 @@ virDomainCreate(virDomainPtr domain)
* pristine template.
*
* Returns 0 in case of success, -1 in case of error
+ *
+ * Since: v0.8.2
+ *
*/
int
virDomainCreateWithFlags(virDomainPtr domain, unsigned int flags)
@@ -6870,6 +7119,9 @@ virDomainCreateWithFlags(virDomainPtr domain, unsigned int flags)
* pristine template.
*
* Returns 0 in case of success, -1 in case of error
+ *
+ * Since: v1.1.1
+ *
*/
int
virDomainCreateWithFiles(virDomainPtr domain, unsigned int nfiles,
@@ -6927,6 +7179,9 @@ virDomainCreateWithFiles(virDomainPtr domain, unsigned int nfiles,
* machine boots.
*
* Returns -1 in case of error, 0 in case of success
+ *
+ * Since: v0.2.1
+ *
*/
int
virDomainGetAutostart(virDomainPtr domain,
@@ -6968,6 +7223,9 @@ virDomainGetAutostart(virDomainPtr domain,
* when the host machine boots.
*
* Returns -1 in case of error, 0 in case of success
+ *
+ * Since: v0.2.1
+ *
*/
int
virDomainSetAutostart(virDomainPtr domain,
@@ -7008,6 +7266,9 @@ virDomainSetAutostart(virDomainPtr domain,
* Send NMI to the guest
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.9.2
+ *
*/
int
virDomainInjectNMI(virDomainPtr domain, unsigned int flags)
@@ -7050,6 +7311,9 @@ virDomainInjectNMI(virDomainPtr domain, unsigned int flags)
* Send key(s) to the guest.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.9.3
+ *
*/
int
virDomainSendKey(virDomainPtr domain,
@@ -7135,6 +7399,9 @@ virDomainSendKey(virDomainPtr domain,
* the container/guest.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v1.0.1
+ *
*/
int
virDomainSendProcessSignal(virDomainPtr domain,
@@ -7192,6 +7459,9 @@ virDomainSendProcessSignal(virDomainPtr domain,
* use virDomainSetVcpusFlags().
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.1.4
+ *
*/
int
virDomainSetVcpus(virDomainPtr domain, unsigned int nvcpus)
@@ -7263,6 +7533,9 @@ virDomainSetVcpus(virDomainPtr domain, unsigned int nvcpus)
* Not all hypervisors can support all flag combinations.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.8.5
+ *
*/
int
virDomainSetVcpusFlags(virDomainPtr domain, unsigned int nvcpus,
@@ -7332,6 +7605,9 @@ virDomainSetVcpusFlags(virDomainPtr domain, unsigned int nvcpus,
* on live domains. Guest agent may be needed for this flag to be available.
*
* Returns the number of vCPUs in case of success, -1 in case of failure.
+ *
+ * Since: v0.8.5
+ *
*/
int
virDomainGetVcpusFlags(virDomainPtr domain, unsigned int flags)
@@ -7388,6 +7664,9 @@ virDomainGetVcpusFlags(virDomainPtr domain, unsigned int flags)
* so can only be called on an active domain.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.1.4
+ *
*/
int
virDomainPinVcpu(virDomainPtr domain, unsigned int vcpu,
@@ -7455,6 +7734,9 @@ virDomainPinVcpu(virDomainPtr domain, unsigned int vcpu,
*
* Returns 0 in case of success, -1 in case of failure.
*
+ * Since: v0.9.3
+ *
+ *
*/
int
virDomainPinVcpuFlags(virDomainPtr domain, unsigned int vcpu,
@@ -7513,6 +7795,9 @@ virDomainPinVcpuFlags(virDomainPtr domain, unsigned int vcpu,
*
* Returns the number of virtual CPUs in case of success,
* -1 in case of failure.
+ *
+ * Since: v0.9.3
+ *
*/
int
virDomainGetVcpuPinInfo(virDomainPtr domain, int ncpumaps,
@@ -7590,6 +7875,9 @@ virDomainGetVcpuPinInfo(virDomainPtr domain, int ncpumaps,
*
* Returns 0 in case of success, -1 in case of failure.
*
+ * Since: v0.10.0
+ *
+ *
*/
int
virDomainPinEmulator(virDomainPtr domain, unsigned char *cpumap,
@@ -7645,6 +7933,9 @@ virDomainPinEmulator(virDomainPtr domain, unsigned char *cpumap,
* Returns 1 in case of success,
* 0 in case of no emulator threads are pined to pcpus,
* -1 in case of failure.
+ *
+ * Since: v0.10.0
+ *
*/
int
virDomainGetEmulatorPinInfo(virDomainPtr domain, unsigned char *cpumap,
@@ -7710,6 +8001,9 @@ virDomainGetEmulatorPinInfo(virDomainPtr domain, unsigned char *cpumap,
* an inactive domain.
*
* Returns the number of info filled in case of success, -1 in case of failure.
+ *
+ * Since: v0.1.4
+ *
*/
int
virDomainGetVcpus(virDomainPtr domain, virVcpuInfoPtr info, int maxinfo,
@@ -7769,6 +8063,9 @@ virDomainGetVcpus(virDomainPtr domain, virVcpuInfoPtr info, int maxinfo,
* guest was booted with. For more details, see virDomainGetVcpusFlags().
*
* Returns the maximum of virtual CPU or -1 in case of error.
+ *
+ * Since: v0.2.1
+ *
*/
int
virDomainGetMaxVcpus(virDomainPtr domain)
@@ -7813,6 +8110,9 @@ virDomainGetMaxVcpus(virDomainPtr domain)
* On success, the array of information is stored into @info. The caller is
* responsible for calling virDomainIOThreadInfoFree() on each array element,
* then calling free() on @info. On error, @info is set to NULL.
+ *
+ * Since: v1.2.14
+ *
*/
int
virDomainGetIOThreadInfo(virDomainPtr dom,
@@ -7852,6 +8152,9 @@ virDomainGetIOThreadInfo(virDomainPtr dom,
* @info: pointer to a virDomainIOThreadInfo object
*
* Frees the memory used by @info.
+ *
+ * Since: v1.2.14
+ *
*/
void
virDomainIOThreadInfoFree(virDomainIOThreadInfoPtr info)
@@ -7895,6 +8198,9 @@ virDomainIOThreadInfoFree(virDomainIOThreadInfoPtr info)
* See also virDomainGetIOThreadInfo for querying this information.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v1.2.14
+ *
*/
int
virDomainPinIOThread(virDomainPtr domain,
@@ -7959,6 +8265,9 @@ virDomainPinIOThread(virDomainPtr domain,
* just live or both live and persistent state is changed.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v1.2.15
+ *
*/
int
virDomainAddIOThread(virDomainPtr domain,
@@ -8018,6 +8327,9 @@ virDomainAddIOThread(virDomainPtr domain,
* just live or both live and persistent state is changed.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v1.2.15
+ *
*/
int
virDomainDelIOThread(virDomainPtr domain,
@@ -8079,6 +8391,9 @@ virDomainDelIOThread(virDomainPtr domain,
* This function requires privileged access to the hypervisor.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v4.10.0
+ *
*/
int
virDomainSetIOThreadParams(virDomainPtr domain,
@@ -8132,6 +8447,9 @@ virDomainSetIOThreadParams(virDomainPtr domain,
* string if the domain is not running under a security model.
*
* Returns 0 in case of success, -1 in case of failure
+ *
+ * Since: v0.6.1
+ *
*/
int
virDomainGetSecurityLabel(virDomainPtr domain, virSecurityLabelPtr seclabel)
@@ -8174,6 +8492,9 @@ virDomainGetSecurityLabel(virDomainPtr domain, virSecurityLabelPtr seclabel)
* string if the domain is not running under a security model.
*
* Returns number of elements in @seclabels on success, -1 in case of failure.
+ *
+ * Since: v0.10.0
+ *
*/
int
virDomainGetSecurityLabelList(virDomainPtr domain,
@@ -8236,6 +8557,9 @@ virDomainGetSecurityLabelList(virDomainPtr domain,
* or both will be modified.
*
* Returns 0 on success, -1 in case of failure.
+ *
+ * Since: v0.9.10
+ *
*/
int
virDomainSetMetadata(virDomainPtr domain,
@@ -8321,6 +8645,9 @@ virDomainSetMetadata(virDomainPtr domain,
*
* Returns the metadata string on success (caller must free),
* or NULL in case of failure.
+ *
+ * Since: v0.9.10
+ *
*/
char *
virDomainGetMetadata(virDomainPtr domain,
@@ -8388,6 +8715,9 @@ virDomainGetMetadata(virDomainPtr domain,
* persistent domain definition.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.1.9
+ *
*/
int
virDomainAttachDevice(virDomainPtr domain, const char *xml)
@@ -8447,6 +8777,9 @@ virDomainAttachDevice(virDomainPtr domain, const char *xml)
* persistent domain definition.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.7.7
+ *
*/
int
virDomainAttachDeviceFlags(virDomainPtr domain,
@@ -8491,6 +8824,9 @@ virDomainAttachDeviceFlags(virDomainPtr domain,
* See virDomainDetachDeviceFlags() for more details.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.1.9
+ *
*/
int
virDomainDetachDevice(virDomainPtr domain, const char *xml)
@@ -8573,6 +8909,9 @@ virDomainDetachDevice(virDomainPtr domain, const char *xml)
* may lead to unexpected results.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.7.7
+ *
*/
int
virDomainDetachDeviceFlags(virDomainPtr domain,
@@ -8637,6 +8976,9 @@ virDomainDetachDeviceFlags(virDomainPtr domain,
* domain XML with only the disk path changed.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.8.0
+ *
*/
int
virDomainUpdateDeviceFlags(virDomainPtr domain,
@@ -8691,6 +9033,9 @@ virDomainUpdateDeviceFlags(virDomainPtr domain,
* device removal.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v4.4.0
+ *
*/
int
virDomainDetachDeviceAlias(virDomainPtr domain,
@@ -8751,6 +9096,9 @@ virDomainDetachDeviceAlias(virDomainPtr domain,
* Returns 0 on success, -1 on failure. Older versions of some hypervisors
* sometimes returned a positive number on success, but without any reliable
* semantics on what that number represents.
+ *
+ * Since: v0.5.0
+ *
*/
int
virConnectDomainEventRegister(virConnectPtr conn,
@@ -8794,6 +9142,9 @@ virConnectDomainEventRegister(virConnectPtr conn,
* Returns 0 on success, -1 on failure. Older versions of some hypervisors
* sometimes returned a positive number on success, but without any reliable
* semantics on what that number represents.
+ *
+ * Since: v0.5.0
+ *
*/
int
virConnectDomainEventDeregister(virConnectPtr conn,
@@ -8828,6 +9179,9 @@ virConnectDomainEventDeregister(virConnectPtr conn,
* Determine if the domain is currently running
*
* Returns 1 if running, 0 if inactive, -1 on error
+ *
+ * Since: v0.7.3
+ *
*/
int
virDomainIsActive(virDomainPtr dom)
@@ -8861,6 +9215,9 @@ virDomainIsActive(virDomainPtr dom)
* which means it will still exist after shutting down
*
* Returns 1 if persistent, 0 if transient, -1 on error
+ *
+ * Since: v0.7.3
+ *
*/
int
virDomainIsPersistent(virDomainPtr dom)
@@ -8901,6 +9258,9 @@ virDomainIsPersistent(virDomainPtr dom)
* advised to change these after the rename was successful.
*
* Returns 0 if successfully renamed, -1 on error
+ *
+ * Since: v1.2.19
+ *
*/
int
virDomainRename(virDomainPtr dom,
@@ -8934,6 +9294,9 @@ virDomainRename(virDomainPtr dom,
* Determine if the domain has been updated.
*
* Returns 1 if updated, 0 if not, -1 on error
+ *
+ * Since: v0.8.6
+ *
*/
int
virDomainIsUpdated(virDomainPtr dom)
@@ -8971,6 +9334,9 @@ virDomainIsUpdated(virDomainPtr dom)
* to virDomainGetJobStats().
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.7.7
+ *
*/
int
virDomainGetJobInfo(virDomainPtr domain, virDomainJobInfoPtr info)
@@ -9035,6 +9401,9 @@ virDomainGetJobInfo(virDomainPtr domain, virDomainJobInfoPtr info)
* source host in case of a migration job).
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v1.0.3
+ *
*/
int
virDomainGetJobStats(virDomainPtr domain,
@@ -9087,6 +9456,9 @@ virDomainGetJobStats(virDomainPtr domain,
* for more details).
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.7.7
+ *
*/
int
virDomainAbortJob(virDomainPtr domain)
@@ -9129,6 +9501,9 @@ virDomainAbortJob(virDomainPtr domain)
* being live-migrated as a reaction to migration progress.
*
* Returns 0 in case of success, -1 otherwise.
+ *
+ * Since: v0.8.0
+ *
*/
int
virDomainMigrateSetMaxDowntime(virDomainPtr domain,
@@ -9170,6 +9545,9 @@ virDomainMigrateSetMaxDowntime(virDomainPtr domain,
* at the end of live migration.
*
* Returns 0 in case of success, -1 otherwise.
+ *
+ * Since: v3.7.0
+ *
*/
int
virDomainMigrateGetMaxDowntime(virDomainPtr domain,
@@ -9210,6 +9588,9 @@ virDomainMigrateGetMaxDowntime(virDomainPtr domain,
* transferred memory pages during live migration.
*
* Returns 0 in case of success, -1 otherwise.
+ *
+ * Since: v1.0.3
+ *
*/
int
virDomainMigrateGetCompressionCache(virDomainPtr domain,
@@ -9254,6 +9635,9 @@ virDomainMigrateGetCompressionCache(virDomainPtr domain,
* virDomainGetJobStats.
*
* Returns 0 in case of success, -1 otherwise.
+ *
+ * Since: v1.0.3
+ *
*/
int
virDomainMigrateSetCompressionCache(virDomainPtr domain,
@@ -9298,6 +9682,9 @@ virDomainMigrateSetCompressionCache(virDomainPtr domain,
* phase of the migration.
*
* Returns 0 in case of success, -1 otherwise.
+ *
+ * Since: v0.9.0
+ *
*/
int
virDomainMigrateSetMaxSpeed(virDomainPtr domain,
@@ -9341,6 +9728,9 @@ virDomainMigrateSetMaxSpeed(virDomainPtr domain,
* migration.
*
* Returns 0 in case of success, -1 otherwise.
+ *
+ * Since: v0.9.5
+ *
*/
int
virDomainMigrateGetMaxSpeed(virDomainPtr domain,
@@ -9434,6 +9824,9 @@ virDomainMigrateGetMaxSpeed(virDomainPtr domain,
* migration and there's no domain to run virDomainGetJobStats on).
*
* Returns 0 in case of success, -1 otherwise.
+ *
+ * Since: v1.3.3
+ *
*/
int
virDomainMigrateStartPostCopy(virDomainPtr domain,
@@ -9497,6 +9890,9 @@ virDomainMigrateStartPostCopy(virDomainPtr domain,
* be passed to the virConnectDomainEventDeregisterAny() method.
*
* Returns a callback identifier on success, -1 on failure.
+ *
+ * Since: v0.8.0
+ *
*/
int
virConnectDomainEventRegisterAny(virConnectPtr conn,
@@ -9555,7 +9951,10 @@ virConnectDomainEventRegisterAny(virConnectPtr conn,
*
* Returns 0 on success, -1 on failure. Older versions of some hypervisors
* sometimes returned a positive number on success, but without any reliable
- * semantics on what that number represents. */
+ * semantics on what that number represents.
+ *
+ * Since: v0.8.0
+ * */
int
virConnectDomainEventDeregisterAny(virConnectPtr conn,
int callbackID)
@@ -9610,6 +10009,9 @@ virConnectDomainEventDeregisterAny(virConnectPtr conn,
* flags are mutually exclusive.
*
* Returns 0 in case of success or -1 in case of failure
+ *
+ * Since: v0.8.0
+ *
*/
int
virDomainManagedSave(virDomainPtr dom, unsigned int flags)
@@ -9657,6 +10059,9 @@ virDomainManagedSave(virDomainPtr dom, unsigned int flags)
*
* Returns 0 if no image is present, 1 if an image is present, and
* -1 in case of error
+ *
+ * Since: v0.8.0
+ *
*/
int
virDomainHasManagedSaveImage(virDomainPtr dom, unsigned int flags)
@@ -9695,6 +10100,9 @@ virDomainHasManagedSaveImage(virDomainPtr dom, unsigned int flags)
* Remove any managed save image for this domain.
*
* Returns 0 in case of success, and -1 in case of error
+ *
+ * Since: v0.8.0
+ *
*/
int
virDomainManagedSaveRemove(virDomainPtr dom, unsigned int flags)
@@ -9741,6 +10149,9 @@ virDomainManagedSaveRemove(virDomainPtr dom, unsigned int flags)
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of
* error. The caller must free() the returned value.
+ *
+ * Since: v3.7.0
+ *
*/
char *
virDomainManagedSaveGetXMLDesc(virDomainPtr domain, unsigned int flags)
@@ -9799,6 +10210,9 @@ virDomainManagedSaveGetXMLDesc(virDomainPtr domain, unsigned int flags)
* exclusive.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v3.7.0
+ *
*/
int
virDomainManagedSaveDefineXML(virDomainPtr domain, const char *dxml,
@@ -9864,6 +10278,9 @@ virDomainManagedSaveDefineXML(virDomainPtr domain, const char *dxml,
* versions, it is up to the client to ensure mutual exclusion.
*
* Returns 0 if the console was opened, -1 on error
+ *
+ * Since: v0.8.6
+ *
*/
int
virDomainOpenConsole(virDomainPtr dom,
@@ -9928,6 +10345,9 @@ virDomainOpenConsole(virDomainPtr dom,
* other client prior to opening this channel.
*
* Returns 0 if the channel was opened, -1 on error
+ *
+ * Since: v1.0.2
+ *
*/
int
virDomainOpenChannel(virDomainPtr dom,
@@ -9985,6 +10405,9 @@ virDomainOpenChannel(virDomainPtr dom,
* Linux perf events are performance analyzing tool in Linux.
*
* Returns -1 in case of failure, 0 in case of success.
+ *
+ * Since: v1.3.3
+ *
*/
int virDomainGetPerfEvents(virDomainPtr domain,
virTypedParameterPtr *params,
@@ -10035,6 +10458,9 @@ int virDomainGetPerfEvents(virDomainPtr domain,
* Linux perf events are performance analyzing tool in Linux.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v1.3.3
+ *
*/
int virDomainSetPerfEvents(virDomainPtr domain,
virTypedParameterPtr params,
@@ -10118,6 +10544,9 @@ int virDomainSetPerfEvents(virDomainPtr domain,
* beginning of the first phase.
*
* Returns -1 in case of failure, 0 when successful.
+ *
+ * Since: v0.9.4
+ *
*/
int
virDomainBlockJobAbort(virDomainPtr dom, const char *disk,
@@ -10195,6 +10624,9 @@ virDomainBlockJobAbort(virDomainPtr dom, const char *disk,
* space required for the backup.
*
* Returns -1 in case of failure, 0 when nothing found, 1 when info was found.
+ *
+ * Since: v0.9.4
+ *
*/
int
virDomainGetBlockJobInfo(virDomainPtr dom, const char *disk,
@@ -10258,6 +10690,9 @@ virDomainGetBlockJobInfo(virDomainPtr dom, const char *disk,
* elements within //domain/devices/disk.
*
* Returns -1 in case of failure, 0 when successful.
+ *
+ * Since: v0.9.4
+ *
*/
int
virDomainBlockJobSetSpeed(virDomainPtr dom, const char *disk,
@@ -10332,6 +10767,9 @@ virDomainBlockJobSetSpeed(virDomainPtr dom, const char *disk,
* This is shorthand for virDomainBlockRebase() with a NULL base.
*
* Returns 0 if the operation has started, -1 on failure.
+ *
+ * Since: v0.9.4
+ *
*/
int
virDomainBlockPull(virDomainPtr dom, const char *disk,
@@ -10476,6 +10914,9 @@ virDomainBlockPull(virDomainPtr dom, const char *disk,
* to the source format or probed from the reused file.
*
* Returns 0 if the operation has started, -1 on failure.
+ *
+ * Since: v0.9.10
+ *
*/
int
virDomainBlockRebase(virDomainPtr dom, const char *disk,
@@ -10606,6 +11047,9 @@ virDomainBlockRebase(virDomainPtr dom, const char *disk,
* is not a local file, and the possibility of additional tuning parameters.
*
* Returns 0 if the operation has started, -1 on failure.
+ *
+ * Since: v1.2.8
+ *
*/
int
virDomainBlockCopy(virDomainPtr dom, const char *disk,
@@ -10752,6 +11196,9 @@ virDomainBlockCopy(virDomainPtr dom, const char *disk,
* virDomainGetBlockJobInfo().
*
* Returns 0 if the operation has started, -1 on failure.
+ *
+ * Since: v0.10.2
+ *
*/
int
virDomainBlockCommit(virDomainPtr dom, const char *disk,
@@ -10811,6 +11258,9 @@ virDomainBlockCommit(virDomainPtr dom, const char *disk,
* to use this method over a TCP connection will always fail
*
* Returns 0 on success, -1 on failure
+ *
+ * Since: v0.9.7
+ *
*/
int
virDomainOpenGraphics(virDomainPtr dom,
@@ -10891,6 +11341,9 @@ virDomainOpenGraphics(virDomainPtr dom,
* to use this method over a TCP connection will always fail.
*
* Returns an fd on success, -1 on failure
+ *
+ * Since: v1.2.8
+ *
*/
int
virDomainOpenGraphicsFD(virDomainPtr dom,
@@ -10952,6 +11405,9 @@ virDomainOpenGraphicsFD(virDomainPtr dom,
* within //domain/devices/disk.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.9.8
+ *
*/
int
virDomainSetBlockIoTune(virDomainPtr dom,
@@ -11027,6 +11483,9 @@ virDomainSetBlockIoTune(virDomainPtr dom,
* unless @nparams is 0 on input.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.9.8
+ *
*/
int
virDomainGetBlockIoTune(virDomainPtr dom,
@@ -11156,6 +11615,9 @@ virDomainGetBlockIoTune(virDomainPtr dom,
* skipped elements if @nparams is too large, and tail elements if
* @ncpus is too large). The caller is responsible for freeing any
* returned string parameters.
+ *
+ * Since: v0.9.10
+ *
*/
int
virDomainGetCPUStats(virDomainPtr domain,
@@ -11256,6 +11718,9 @@ virDomainGetCPUStats(virDomainPtr domain,
*
* Returns number of disks with errors filled in the @errors array or -1 on
* error.
+ *
+ * Since: v0.9.10
+ *
*/
int
virDomainGetDiskErrors(virDomainPtr dom,
@@ -11301,6 +11766,9 @@ virDomainGetDiskErrors(virDomainPtr dom,
*
* Returns the hostname which must be freed by the caller, or
* NULL if there was an error.
+ *
+ * Since: v0.10.0
+ *
*/
char *
virDomainGetHostname(virDomainPtr domain, unsigned int flags)
@@ -11350,6 +11818,9 @@ virDomainGetHostname(virDomainPtr domain, unsigned int flags)
* If @minimum is not zero, the command may fail.
*
* Returns 0 on success, -1 otherwise.
+ *
+ * Since: v1.0.1
+ *
*/
int
virDomainFSTrim(virDomainPtr dom,
@@ -11394,6 +11865,9 @@ virDomainFSTrim(virDomainPtr dom,
* support mountpoints argument), @mountpoints may need to be NULL.
*
* Returns the number of frozen filesystems on success, -1 otherwise.
+ *
+ * Since: v1.2.5
+ *
*/
int
virDomainFSFreeze(virDomainPtr dom,
@@ -11437,6 +11911,9 @@ virDomainFSFreeze(virDomainPtr dom,
* In some drivers (e.g. QEMU driver), @mountpoints may need to be NULL.
*
* Returns the number of thawed filesystems on success, -1 otherwise.
+ *
+ * Since: v1.2.5
+ *
*/
int
virDomainFSThaw(virDomainPtr dom,
@@ -11482,6 +11959,9 @@ virDomainFSThaw(virDomainPtr dom,
* be configured and running in order to run this API.
*
* Returns 0 on success, -1 otherwise.
+ *
+ * Since: v1.2.5
+ *
*/
int
virDomainGetTime(virDomainPtr dom,
@@ -11532,6 +12012,9 @@ virDomainGetTime(virDomainPtr dom,
* be configured and running in order to be able to run this API.
*
* Returns 0 on success, -1 otherwise.
+ *
+ * Since: v1.2.5
+ *
*/
int
virDomainSetTime(virDomainPtr dom,
@@ -11578,6 +12061,9 @@ virDomainSetTime(virDomainPtr dom,
* be configured and running in order to be able to run this API.
*
* Returns 0 on success, -1 otherwise.
+ *
+ * Since: v1.2.16
+ *
*/
int
virDomainSetUserPassword(virDomainPtr dom,
@@ -11628,6 +12114,9 @@ virDomainSetUserPassword(virDomainPtr dom,
*
* Returns NULL in case of error or an XML string
* defining the capabilities.
+ *
+ * Since: v1.2.7
+ *
*/
char *
virConnectGetDomainCapabilities(virConnectPtr conn,
@@ -12034,6 +12523,9 @@ virConnectGetDomainCapabilities(virConnectPtr conn,
* Returns the count of returned statistics structures on success, -1 on error.
* The requested data are returned in the @retStats parameter. The returned
* array should be freed by the caller. See virDomainStatsRecordListFree.
+ *
+ * Since: v1.2.8
+ *
*/
int
virConnectGetAllDomainStats(virConnectPtr conn,
@@ -12113,6 +12605,9 @@ virConnectGetAllDomainStats(virConnectPtr conn,
* array should be freed by the caller. See virDomainStatsRecordListFree.
* Note that the count of returned stats may be less than the domain count
* provided via @doms.
+ *
+ * Since: v1.2.8
+ *
*/
int
virDomainListGetStats(virDomainPtr *doms,
@@ -12180,6 +12675,9 @@ virDomainListGetStats(virDomainPtr *doms,
*
* Convenience function to free a list of domain stats returned by
* virDomainListGetStats and virConnectGetAllDomainStats.
+ *
+ * Since: v1.2.8
+ *
*/
void
virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats)
@@ -12212,6 +12710,9 @@ virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats)
* On success, the array of the information is stored into @info. The caller is
* responsible for calling virDomainFSInfoFree() on each array element, then
* calling free() on @info. On error, @info is set to NULL.
+ *
+ * Since: v1.2.11
+ *
*/
int
virDomainGetFSInfo(virDomainPtr dom,
@@ -12247,6 +12748,9 @@ virDomainGetFSInfo(virDomainPtr dom,
* @info: pointer to a FSInfo object
*
* Frees all the memory occupied by @info.
+ *
+ * Since: v1.2.11
+ *
*/
void
virDomainFSInfoFree(virDomainFSInfoPtr info)
@@ -12339,6 +12843,9 @@ virDomainFSInfoFree(virDomainFSInfoPtr info)
* free(ifaces);
*
* Returns the number of interfaces on success, -1 in case of error.
+ *
+ * Since: v1.2.14
+ *
*/
int
virDomainInterfaceAddresses(virDomainPtr dom,
@@ -12380,6 +12887,9 @@ virDomainInterfaceAddresses(virDomainPtr dom,
* Free the interface object. The data structure is
* freed and should not be used thereafter. If @iface
* is NULL, then this method has no effect.
+ *
+ * Since: v1.2.14
+ *
*/
void
virDomainInterfaceFree(virDomainInterfacePtr iface)
@@ -12423,6 +12933,9 @@ virDomainInterfaceFree(virDomainInterfacePtr iface)
* virTypedParamsFree to free memory returned in @params.
*
* Returns 0 on success, -1 on error.
+ *
+ * Since: v2.0.0
+ *
*/
int
virDomainGetGuestVcpus(virDomainPtr domain,
@@ -12481,6 +12994,9 @@ virDomainGetGuestVcpus(virDomainPtr domain,
* low-level features a S3 sleep.
*
* Returns 0 on success, -1 on error.
+ *
+ * Since: v2.0.0
+ *
*/
int
virDomainSetGuestVcpus(virDomainPtr domain,
@@ -12530,6 +13046,9 @@ virDomainSetGuestVcpus(virDomainPtr domain,
* Note that OSes and hypervisors may require vCPU 0 to stay online.
*
* Returns 0 on success, -1 on error.
+ *
+ * Since: v3.1.0
+ *
*/
int
virDomainSetVcpu(virDomainPtr domain,
@@ -12682,6 +13201,9 @@ virDomainSetVcpu(virDomainPtr domain,
* virTypedParamsFree to free memory returned in @params.
*
* Returns 0 on success, -1 on error.
+ *
+ * Since: v5.7.0
+ *
*/
int virDomainGetGuestInfo(virDomainPtr domain,
unsigned int types,
@@ -12756,6 +13278,9 @@ int virDomainGetGuestInfo(virDomainPtr domain,
* tools to grow it without the need for polling of the data.
*
* Returns 0 if the operation has started, -1 on failure.
+ *
+ * Since: v3.2.0
+ *
*/
int
virDomainSetBlockThreshold(virDomainPtr domain,
@@ -12805,6 +13330,9 @@ virDomainSetBlockThreshold(virDomainPtr domain,
* any action for running domain.
*
* Returns 0 on success, -1 on failure.
+ *
+ * Since: v3.9.0
+ *
*/
int virDomainSetLifecycleAction(virDomainPtr domain,
unsigned int type,
@@ -12860,6 +13388,9 @@ int virDomainSetLifecycleAction(virDomainPtr domain,
* return the launch measurement.
*
* Returns -1 in case of failure, 0 in case of success.
+ *
+ * Since: v4.5.0
+ *
*/
int virDomainGetLaunchSecurityInfo(virDomainPtr domain,
virTypedParameterPtr *params,
@@ -12926,6 +13457,9 @@ int virDomainGetLaunchSecurityInfo(virDomainPtr domain,
* launch security parameters.
*
* Returns -1 in case of failure, 0 in case of success.
+ *
+ * Since: v8.0.0
+ *
*/
int virDomainSetLaunchSecurityState(virDomainPtr domain,
virTypedParameterPtr params,
@@ -12983,6 +13517,9 @@ int virDomainSetLaunchSecurityState(virDomainPtr domain,
* positive value: wait for @timeout seconds
*
* Returns 0 on success, -1 on failure
+ *
+ * Since: v5.10.0
+ *
*/
int
virDomainAgentSetResponseTimeout(virDomainPtr domain,
@@ -13079,6 +13616,9 @@ virDomainAgentSetResponseTimeout(virDomainPtr domain,
* formats if checkpoints are not involved.
*
* Returns 0 on success or -1 on failure.
+ *
+ * Since: v6.0.0
+ *
*/
int
virDomainBackupBegin(virDomainPtr domain,
@@ -13129,6 +13669,9 @@ virDomainBackupBegin(virDomainPtr domain,
*
* Returns a NUL-terminated UTF-8 encoded XML instance or NULL in
* case of error. The caller must free() the returned value.
+ *
+ * Since: v6.0.0
+ *
*/
char *
virDomainBackupGetXMLDesc(virDomainPtr domain,
@@ -13178,6 +13721,9 @@ virDomainBackupGetXMLDesc(virDomainPtr domain,
*
* Returns: number of keys stored in @keys,
* -1 otherwise.
+ *
+ * Since: v6.10.0
+ *
*/
int
virDomainAuthorizedSSHKeysGet(virDomainPtr domain,
@@ -13246,6 +13792,9 @@ virDomainAuthorizedSSHKeysGet(virDomainPtr domain,
*
* Returns: 0 on success,
* -1 otherwise.
+ *
+ * Since: v6.10.0
+ *
*/
int
virDomainAuthorizedSSHKeysSet(virDomainPtr domain,
@@ -13314,6 +13863,9 @@ virDomainAuthorizedSSHKeysSet(virDomainPtr domain,
*
* Returns: number of messages stored in @msgs,
* -1 otherwise.
+ *
+ * Since: v7.1.0
+ *
*/
int
virDomainGetMessages(virDomainPtr domain,
@@ -13356,6 +13908,9 @@ virDomainGetMessages(virDomainPtr domain,
* virConnectGetAllDomainStats.
*
* Returns 0 in case of success, -1 otherwise.
+ *
+ * Since: v7.2.0
+ *
*/
int
virDomainStartDirtyRateCalc(virDomainPtr domain,
diff --git a/src/libvirt-host.c b/src/libvirt-host.c
index 8e680cb9f9..6ba2c9e0bd 100644
--- a/src/libvirt-host.c
+++ b/src/libvirt-host.c
@@ -47,6 +47,9 @@ VIR_LOG_INIT("libvirt.host");
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure
+ *
+ * Since: v0.6.0
+ *
*/
int
virConnectRef(virConnectPtr conn)
@@ -85,6 +88,9 @@ virConnectRef(virConnectPtr conn)
* on a connection if the application is not trustworthy.
*
* Returns: 0 if the identity change was accepted, -1 on error
+ *
+ * Since: v5.8.0
+ *
*/
int
virConnectSetIdentity(virConnectPtr conn,
@@ -149,6 +155,9 @@ virConnectSupportsFeature(virConnectPtr conn, int feature)
* hypervisor, use virConnectGetCapabilities().
*
* Returns NULL in case of error, a static zero terminated string otherwise.
+ *
+ * Since: v0.0.1
+ *
*/
const char *
virConnectGetType(virConnectPtr conn)
@@ -180,6 +189,9 @@ virConnectGetType(virConnectPtr conn)
* Returns -1 in case of error, 0 otherwise. if the version can't be
* extracted by lack of capacities returns 0 and @hvVer is 0, otherwise
* @hvVer value is major * 1,000,000 + minor * 1,000 + release
+ *
+ * Since: v0.0.1
+ *
*/
int
virConnectGetVersion(virConnectPtr conn, unsigned long *hvVer)
@@ -216,6 +228,9 @@ virConnectGetVersion(virConnectPtr conn, unsigned long *hvVer)
*
* Returns -1 in case of failure, 0 otherwise, and values for @libVer have
* the format major * 1,000,000 + minor * 1,000 + release.
+ *
+ * Since: v0.7.3
+ *
*/
int
virConnectGetLibVersion(virConnectPtr conn, unsigned long *libVer)
@@ -256,6 +271,9 @@ virConnectGetLibVersion(virConnectPtr conn, unsigned long *libVer)
*
* Returns the hostname which must be freed by the caller, or
* NULL if there was an error.
+ *
+ * Since: v0.3.0
+ *
*/
char *
virConnectGetHostname(virConnectPtr conn)
@@ -295,6 +313,9 @@ virConnectGetHostname(virConnectPtr conn)
*
* Returns the URI string which must be freed by the caller, or
* NULL if there was an error.
+ *
+ * Since: v0.3.0
+ *
*/
char *
virConnectGetURI(virConnectPtr conn)
@@ -329,6 +350,9 @@ virConnectGetURI(virConnectPtr conn)
*
* Returns the XML string which must be freed by the caller, or
* NULL if there was an error.
+ *
+ * Since: v0.8.8
+ *
*/
char *
virConnectGetSysinfo(virConnectPtr conn, unsigned int flags)
@@ -367,6 +391,9 @@ virConnectGetSysinfo(virConnectPtr conn, unsigned int flags)
* for "<vcpu max='...'>" in its output instead.
*
* Returns the maximum of virtual CPU or -1 in case of error.
+ *
+ * Since: v0.2.1
+ *
*/
int
virConnectGetMaxVcpus(virConnectPtr conn,
@@ -416,6 +443,9 @@ virConnectGetMaxVcpus(virConnectPtr conn,
* in a more accurate representation.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.1.0
+ *
*/
int
virNodeGetInfo(virConnectPtr conn, virNodeInfoPtr info)
@@ -452,6 +482,9 @@ virNodeGetInfo(virConnectPtr conn, virNodeInfoPtr info)
* Returns NULL in case of error, or an XML string
* defining the capabilities.
* The client must free the returned string after use.
+ *
+ * Since: v0.2.1
+ *
*/
char *
virConnectGetCapabilities(virConnectPtr conn)
@@ -532,6 +565,9 @@ virConnectGetCapabilities(virConnectPtr conn)
* represents all CPUs on the server.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.9.3
+ *
*/
int
virNodeGetCPUStats(virConnectPtr conn,
@@ -619,6 +655,9 @@ virNodeGetCPUStats(virConnectPtr conn,
* The cached memory usage.(KB)
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.9.3
+ *
*/
int
virNodeGetMemoryStats(virConnectPtr conn,
@@ -666,6 +705,9 @@ virNodeGetMemoryStats(virConnectPtr conn,
* function the returned value is in bytes. Divide by 1024 as necessary.
*
* Returns the available free memory in bytes or 0 in case of error
+ *
+ * Since: v0.3.3
+ *
*/
unsigned long long
virNodeGetFreeMemory(virConnectPtr conn)
@@ -712,6 +754,9 @@ virNodeGetFreeMemory(virConnectPtr conn)
* Returns 0 on success (i.e., the node will be suspended after a short
* delay), -1 on failure (the operation is not supported, or an attempted
* suspend is already underway).
+ *
+ * Since: v0.9.8
+ *
*/
int
virNodeSuspendForDuration(virConnectPtr conn,
@@ -765,6 +810,9 @@ virNodeSuspendForDuration(virConnectPtr conn,
* example.
*
* Returns 0 in case of success, and -1 in case of failure.
+ *
+ * Since: v0.10.2
+ *
*/
int
virNodeGetMemoryParameters(virConnectPtr conn,
@@ -829,6 +877,9 @@ virNodeGetMemoryParameters(virConnectPtr conn,
* This function may require privileged access to the hypervisor.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.10.2
+ *
*/
int
virNodeSetMemoryParameters(virConnectPtr conn,
@@ -877,6 +928,9 @@ virNodeSetMemoryParameters(virConnectPtr conn,
* string if the driver has not activated a security model.
*
* Returns 0 in case of success, -1 in case of failure
+ *
+ * Since: v0.6.1
+ *
*/
int
virNodeGetSecurityModel(virConnectPtr conn, virSecurityModelPtr secmodel)
@@ -920,6 +974,9 @@ virNodeGetSecurityModel(virConnectPtr conn, virSecurityModelPtr secmodel)
* whichever is smaller.
*
* Returns the number of entries filled in freeMems, or -1 in case of error.
+ *
+ * Since: v0.3.3
+ *
*/
int
virNodeGetCellsFreeMemory(virConnectPtr conn, unsigned long long *freeMems,
@@ -958,6 +1015,9 @@ virNodeGetCellsFreeMemory(virConnectPtr conn, unsigned long long *freeMems,
* Determine if the connection to the hypervisor is encrypted
*
* Returns 1 if encrypted, 0 if not encrypted, -1 on error
+ *
+ * Since: v0.7.3
+ *
*/
int
virConnectIsEncrypted(virConnectPtr conn)
@@ -993,6 +1053,9 @@ virConnectIsEncrypted(virConnectPtr conn)
* to eavesdropping (eg a UNIX domain socket, or pipe)
*
* Returns 1 if secure, 0 if not secure, -1 on error
+ *
+ * Since: v0.7.3
+ *
*/
int
virConnectIsSecure(virConnectPtr conn)
@@ -1035,6 +1098,9 @@ virConnectIsSecure(virConnectPtr conn)
* (instead of VIR_CPU_COMPARE_INCOMPATIBLE) and the error will use the
* VIR_ERR_CPU_INCOMPATIBLE code with a message providing more details about
* the incompatibility.
+ *
+ * Since: v0.7.5
+ *
*/
int
virConnectCompareCPU(virConnectPtr conn,
@@ -1091,6 +1157,9 @@ virConnectCompareCPU(virConnectPtr conn,
* VIR_CPU_COMPARE_INCOMPATIBLE) and the error will use the
* VIR_ERR_CPU_INCOMPATIBLE code with a message providing more details about
* the incompatibility.
+ *
+ * Since: v4.4.0
+ *
*/
int
virConnectCompareHypervisorCPU(virConnectPtr conn,
@@ -1153,6 +1222,9 @@ virConnectCompareHypervisorCPU(virConnectPtr conn,
*
* Returns -1 on error, number of elements in @models on success (0 means
* libvirt accepts any CPU model).
+ *
+ * Since: v1.1.3
+ *
*/
int
virConnectGetCPUModelNames(virConnectPtr conn, const char *arch, char ***models,
@@ -1209,6 +1281,9 @@ virConnectGetCPUModelNames(virConnectPtr conn, const char *arch, char ***models,
* CPU will not include features that block migration.
*
* Returns XML description of the computed CPU (caller frees) or NULL on error.
+ *
+ * Since: v0.7.7
+ *
*/
char *
virConnectBaselineCPU(virConnectPtr conn,
@@ -1278,6 +1353,9 @@ virConnectBaselineCPU(virConnectPtr conn,
* CPU will not include features that block migration.
*
* Returns XML description of the computed CPU (caller frees) or NULL on error.
+ *
+ * Since: v4.4.0
+ *
*/
char *
virConnectBaselineHypervisorCPU(virConnectPtr conn,
@@ -1351,6 +1429,9 @@ virConnectBaselineHypervisorCPU(virConnectPtr conn,
*
* Returns -1 on error, 0 on success, 1 when remote party doesn't support
* keepalive messages.
+ *
+ * Since: v0.9.8
+ *
*/
int
virConnectSetKeepAlive(virConnectPtr conn,
@@ -1388,6 +1469,9 @@ virConnectSetKeepAlive(virConnectPtr conn,
* over a channel (TCP or UNIX socket) which is not closed.
*
* Returns 1 if alive, 0 if dead, -1 on error
+ *
+ * Since: v0.9.8
+ *
*/
int
virConnectIsAlive(virConnectPtr conn)
@@ -1434,6 +1518,9 @@ virConnectIsAlive(virConnectPtr conn)
* context.
*
* Returns 0 on success, -1 on error
+ *
+ * Since: v0.10.0
+ *
*/
int
virConnectRegisterCloseCallback(virConnectPtr conn,
@@ -1471,6 +1558,9 @@ virConnectRegisterCloseCallback(virConnectPtr conn,
* registration, it will be invoked
*
* Returns 0 on success, -1 on error
+ *
+ * Since: v0.10.0
+ *
*/
int
virConnectUnregisterCloseCallback(virConnectPtr conn,
@@ -1513,6 +1603,9 @@ virConnectUnregisterCloseCallback(virConnectPtr conn,
*
* Returns number of CPUs present on the host node,
* or -1 if there was an error.
+ *
+ * Since: v1.0.0
+ *
*/
int
virNodeGetCPUMap(virConnectPtr conn,
@@ -1599,6 +1692,9 @@ virNodeGetCPUMap(virConnectPtr conn,
* Page size=1073741824 count=0 bytes=0
*
* Returns: the number of entries filled in @counts or -1 in case of error.
+ *
+ * Since: v1.2.6
+ *
*/
int
virNodeGetFreePages(virConnectPtr conn,
@@ -1669,6 +1765,9 @@ virNodeGetFreePages(virConnectPtr conn,
*
* Returns: the number of nodes successfully adjusted or -1 in
* case of an error.
+ *
+ * Since: v1.2.9
+ *
*/
int
virNodeAllocPages(virConnectPtr conn,
@@ -1722,6 +1821,9 @@ virNodeAllocPages(virConnectPtr conn,
* responsible for freeing @params.
*
* Returns 0 in case of success, and -1 in case of failure.
+ *
+ * Since: v4.5.0
+ *
*/
int
virNodeGetSEVInfo(virConnectPtr conn,
diff --git a/src/libvirt-interface.c b/src/libvirt-interface.c
index e4e8178ba9..67dcb76efb 100644
--- a/src/libvirt-interface.c
+++ b/src/libvirt-interface.c
@@ -36,6 +36,9 @@ VIR_LOG_INIT("libvirt.interface");
* call.
*
* Returns the virConnectPtr or NULL in case of failure.
+ *
+ * Since: v0.6.4
+ *
*/
virConnectPtr
virInterfaceGetConnect(virInterfacePtr iface)
@@ -76,6 +79,9 @@ virInterfaceGetConnect(virInterfacePtr iface)
* extra allocated element set to NULL but not included in the return count,
* to make iteration easier. The caller is responsible for calling
* virStorageInterfaceFree() on each array element, then calling free() on @ifaces.
+ *
+ * Since: v0.10.2
+ *
*/
int
virConnectListAllInterfaces(virConnectPtr conn,
@@ -115,6 +121,9 @@ virConnectListAllInterfaces(virConnectPtr conn,
* Provides the number of active interfaces on the physical host.
*
* Returns the number of active interfaces found or -1 in case of error
+ *
+ * Since: v0.6.4
+ *
*/
int
virConnectNumOfInterfaces(virConnectPtr conn)
@@ -158,6 +167,9 @@ virConnectNumOfInterfaces(virConnectPtr conn)
* to virConnectNumOfInterfaces() and this call; you are only guaranteed that
* all currently active interfaces were listed if the return is less than
* @maxnames. The client must call free() on each returned name.
+ *
+ * Since: v0.6.4
+ *
*/
int
virConnectListInterfaces(virConnectPtr conn, char **const names, int maxnames)
@@ -193,6 +205,9 @@ virConnectListInterfaces(virConnectPtr conn, char **const names, int maxnames)
* Provides the number of defined (inactive) interfaces on the physical host.
*
* Returns the number of defined interface found or -1 in case of error
+ *
+ * Since: v0.7.0
+ *
*/
int
virConnectNumOfDefinedInterfaces(virConnectPtr conn)
@@ -236,6 +251,9 @@ virConnectNumOfDefinedInterfaces(virConnectPtr conn)
* a call to virConnectNumOfDefinedInterfaces() and this call; you are only
* guaranteed that all currently defined interfaces were listed if the return
* is less than @maxnames. The client must call free() on each returned name.
+ *
+ * Since: v0.7.0
+ *
*/
int
virConnectListDefinedInterfaces(virConnectPtr conn,
@@ -278,6 +296,9 @@ virConnectListDefinedInterfaces(virConnectPtr conn,
*
* Returns a new interface object or NULL in case of failure. If the
* interface cannot be found, then VIR_ERR_NO_INTERFACE error is raised.
+ *
+ * Since: v0.6.4
+ *
*/
virInterfacePtr
virInterfaceLookupByName(virConnectPtr conn, const char *name)
@@ -317,6 +338,9 @@ virInterfaceLookupByName(virConnectPtr conn, const char *name)
*
* Returns a new interface object or NULL in case of failure. If the
* interface cannot be found, then VIR_ERR_NO_INTERFACE error is raised.
+ *
+ * Since: v0.6.4
+ *
*/
virInterfacePtr
virInterfaceLookupByMACString(virConnectPtr conn, const char *macstr)
@@ -352,6 +376,9 @@ virInterfaceLookupByMACString(virConnectPtr conn, const char *macstr)
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* its lifetime will be the same as the interface object.
+ *
+ * Since: v0.6.4
+ *
*/
const char *
virInterfaceGetName(virInterfacePtr iface)
@@ -376,6 +403,9 @@ virInterfaceGetName(virInterfacePtr iface)
* Returns a pointer to the MAC address (in null-terminated ASCII
* format) or NULL, the string need not be deallocated its lifetime
* will be the same as the interface object.
+ *
+ * Since: v0.6.4
+ *
*/
const char *
virInterfaceGetMACString(virInterfacePtr iface)
@@ -407,6 +437,9 @@ virInterfaceGetMACString(virInterfacePtr iface)
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case
* of error. The caller must free() the returned value.
+ *
+ * Since: v0.6.4
+ *
*/
char *
virInterfaceGetXMLDesc(virInterfacePtr iface, unsigned int flags)
@@ -458,6 +491,9 @@ virInterfaceGetXMLDesc(virInterfacePtr iface, unsigned int flags)
* interface object is no longer needed.
*
* Returns NULL in case of error, a pointer to the interface otherwise
+ *
+ * Since: v0.6.4
+ *
*/
virInterfacePtr
virInterfaceDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
@@ -504,6 +540,9 @@ virInterfaceDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
* during the next reboot of the system running libvirtd.
*
* Returns 0 in case of success, -1 in case of error
+ *
+ * Since: v0.6.4
+ *
*/
int
virInterfaceUndefine(virInterfacePtr iface)
@@ -547,6 +586,9 @@ virInterfaceUndefine(virInterfacePtr iface)
* undefined) if virInterfaceChangeRollback() is called.
*
* Returns 0 in case of success, -1 in case of error
+ *
+ * Since: v0.6.4
+ *
*/
int
virInterfaceCreate(virInterfacePtr iface, unsigned int flags)
@@ -594,6 +636,9 @@ virInterfaceCreate(virInterfacePtr iface, unsigned int flags)
* interface definition will also bring the interface back up.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.6.4
+ *
*/
int
virInterfaceDestroy(virInterfacePtr iface, unsigned int flags)
@@ -640,6 +685,9 @@ virInterfaceDestroy(virInterfacePtr iface, unsigned int flags)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.6.4
+ *
*/
int
virInterfaceRef(virInterfacePtr iface)
@@ -663,6 +711,9 @@ virInterfaceRef(virInterfacePtr iface)
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.6.4
+ *
*/
int
virInterfaceFree(virInterfacePtr iface)
@@ -694,6 +745,9 @@ virInterfaceFree(virInterfacePtr iface)
* VIR_ERR_INVALID_OPERATION will be logged.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.9.2
+ *
*/
int
virInterfaceChangeBegin(virConnectPtr conn, unsigned int flags)
@@ -734,6 +788,9 @@ virInterfaceChangeBegin(virConnectPtr conn, unsigned int flags)
* will be logged.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.9.2
+ *
*/
int
virInterfaceChangeCommit(virConnectPtr conn, unsigned int flags)
@@ -774,6 +831,9 @@ virInterfaceChangeCommit(virConnectPtr conn, unsigned int flags)
* will be logged.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.9.2
+ *
*/
int
virInterfaceChangeRollback(virConnectPtr conn, unsigned int flags)
@@ -809,6 +869,9 @@ virInterfaceChangeRollback(virConnectPtr conn, unsigned int flags)
* Determine if the interface is currently running
*
* Returns 1 if running, 0 if inactive, -1 on error
+ *
+ * Since: v0.7.3
+ *
*/
int
virInterfaceIsActive(virInterfacePtr iface)
diff --git a/src/libvirt-network.c b/src/libvirt-network.c
index 883dd40f6b..c3713dfad5 100644
--- a/src/libvirt-network.c
+++ b/src/libvirt-network.c
@@ -38,6 +38,9 @@ VIR_LOG_INIT("libvirt.network");
* call.
*
* Returns the virConnectPtr or NULL in case of failure.
+ *
+ * Since: v0.3.0
+ *
*/
virConnectPtr
virNetworkGetConnect(virNetworkPtr net)
@@ -86,6 +89,9 @@ virNetworkGetConnect(virNetworkPtr net)
* extra allocated element set to NULL but not included in the return count,
* to make iteration easier. The caller is responsible for calling
* virNetworkFree() on each array element, then calling free() on @nets.
+ *
+ * Since: v0.10.2
+ *
*/
int
virConnectListAllNetworks(virConnectPtr conn,
@@ -125,6 +131,9 @@ virConnectListAllNetworks(virConnectPtr conn,
* Provides the number of active networks.
*
* Returns the number of network found or -1 in case of error
+ *
+ * Since: v0.2.0
+ *
*/
int
virConnectNumOfNetworks(virConnectPtr conn)
@@ -167,6 +176,9 @@ virConnectNumOfNetworks(virConnectPtr conn)
* to virConnectNumOfNetworks() and this call; you are only guaranteed that
* all currently active networks were listed if the return is less than
* @maxnames. The client must call free() on each returned name.
+ *
+ * Since: v0.2.0
+ *
*/
int
virConnectListNetworks(virConnectPtr conn, char **const names, int maxnames)
@@ -202,6 +214,9 @@ virConnectListNetworks(virConnectPtr conn, char **const names, int maxnames)
* Provides the number of inactive networks.
*
* Returns the number of networks found or -1 in case of error
+ *
+ * Since: v0.2.0
+ *
*/
int
virConnectNumOfDefinedNetworks(virConnectPtr conn)
@@ -244,6 +259,9 @@ virConnectNumOfDefinedNetworks(virConnectPtr conn)
* a call to virConnectNumOfDefinedNetworks() and this call; you are only
* guaranteed that all currently defined networks were listed if the return
* is less than @maxnames. The client must call free() on each returned name.
+ *
+ * Since: v0.2.0
+ *
*/
int
virConnectListDefinedNetworks(virConnectPtr conn, char **const names,
@@ -285,6 +303,9 @@ virConnectListDefinedNetworks(virConnectPtr conn, char **const names,
*
* Returns a new network object or NULL in case of failure. If the
* network cannot be found, then VIR_ERR_NO_NETWORK error is raised.
+ *
+ * Since: v0.2.0
+ *
*/
virNetworkPtr
virNetworkLookupByName(virConnectPtr conn, const char *name)
@@ -324,6 +345,9 @@ virNetworkLookupByName(virConnectPtr conn, const char *name)
*
* Returns a new network object or NULL in case of failure. If the
* network cannot be found, then VIR_ERR_NO_NETWORK error is raised.
+ *
+ * Since: v0.2.0
+ *
*/
virNetworkPtr
virNetworkLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
@@ -360,6 +384,9 @@ virNetworkLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
*
* Returns a new network object or NULL in case of failure. If the
* network cannot be found, then VIR_ERR_NO_NETWORK error is raised.
+ *
+ * Since: v0.2.0
+ *
*/
virNetworkPtr
virNetworkLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
@@ -399,6 +426,9 @@ virNetworkLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
* network object is no longer needed.
*
* Returns a new network object or NULL in case of failure
+ *
+ * Since: v0.2.0
+ *
*/
virNetworkPtr
virNetworkCreateXML(virConnectPtr conn, const char *xmlDesc)
@@ -440,6 +470,9 @@ virNetworkCreateXML(virConnectPtr conn, const char *xmlDesc)
* network object is no longer needed.
*
* Returns a new network object or NULL in case of failure
+ *
+ * Since: v7.8.0
+ *
*/
virNetworkPtr
virNetworkCreateXMLFlags(virConnectPtr conn, const char *xmlDesc, unsigned int flags)
@@ -480,6 +513,9 @@ virNetworkCreateXMLFlags(virConnectPtr conn, const char *xmlDesc, unsigned int f
* network object is no longer needed.
*
* Returns NULL in case of error, a pointer to the network otherwise
+ *
+ * Since: v0.2.0
+ *
*/
virNetworkPtr
virNetworkDefineXML(virConnectPtr conn, const char *xml)
@@ -521,6 +557,9 @@ virNetworkDefineXML(virConnectPtr conn, const char *xml)
* network object is no longer needed.
*
* Returns NULL in case of error, a pointer to the network otherwise
+ *
+ * Since: v7.7.0
+ *
*/
virNetworkPtr
virNetworkDefineXMLFlags(virConnectPtr conn, const char *xml, unsigned int flags)
@@ -556,6 +595,9 @@ virNetworkDefineXMLFlags(virConnectPtr conn, const char *xml, unsigned int flags
* Undefine a network but does not stop it if it is running
*
* Returns 0 in case of success, -1 in case of error
+ *
+ * Since: v0.2.0
+ *
*/
int
virNetworkUndefine(virNetworkPtr network)
@@ -604,6 +646,9 @@ virNetworkUndefine(virNetworkPtr network)
* running state, its persistent configuration, or both.
*
* Returns 0 in case of success, -1 in case of error
+ *
+ * Since: v1.0.0
+ *
*/
int
virNetworkUpdate(virNetworkPtr network,
@@ -670,6 +715,9 @@ virNetworkUpdate(virNetworkPtr network,
* moves from the defined to the running networks pools.
*
* Returns 0 in case of success, -1 in case of error
+ *
+ * Since: v0.2.0
+ *
*/
int
virNetworkCreate(virNetworkPtr network)
@@ -710,6 +758,9 @@ virNetworkCreate(virNetworkPtr network)
* This function may require privileged access
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.2.0
+ *
*/
int
virNetworkDestroy(virNetworkPtr network)
@@ -748,6 +799,9 @@ virNetworkDestroy(virNetworkPtr network)
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.2.0
+ *
*/
int
virNetworkFree(virNetworkPtr network)
@@ -779,6 +833,9 @@ virNetworkFree(virNetworkPtr network)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.6.0
+ *
*/
int
virNetworkRef(virNetworkPtr network)
@@ -802,6 +859,9 @@ virNetworkRef(virNetworkPtr network)
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* its lifetime will be the same as the network object.
+ *
+ * Since: v0.2.0
+ *
*/
const char *
virNetworkGetName(virNetworkPtr network)
@@ -824,6 +884,9 @@ virNetworkGetName(virNetworkPtr network)
* Get the UUID for a network
*
* Returns -1 in case of error, 0 in case of success
+ *
+ * Since: v0.2.0
+ *
*/
int
virNetworkGetUUID(virNetworkPtr network, unsigned char *uuid)
@@ -854,6 +917,9 @@ virNetworkGetUUID(virNetworkPtr network, unsigned char *uuid)
* UUID see RFC4122.
*
* Returns -1 in case of error, 0 in case of success
+ *
+ * Since: v0.2.0
+ *
*/
int
virNetworkGetUUIDString(virNetworkPtr network, char *buf)
@@ -889,6 +955,9 @@ virNetworkGetUUIDString(virNetworkPtr network, char *buf)
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case
* of error. The caller must free() the returned value.
+ *
+ * Since: v0.2.0
+ *
*/
char *
virNetworkGetXMLDesc(virNetworkPtr network, unsigned int flags)
@@ -926,6 +995,9 @@ virNetworkGetXMLDesc(virNetworkPtr network, unsigned int flags)
*
* Returns a 0 terminated interface name, or NULL in case of
* error. The caller must free() the returned value.
+ *
+ * Since: v0.2.0
+ *
*/
char *
virNetworkGetBridgeName(virNetworkPtr network)
@@ -964,6 +1036,9 @@ virNetworkGetBridgeName(virNetworkPtr network)
* machine boots.
*
* Returns -1 in case of error, 0 in case of success
+ *
+ * Since: v0.2.1
+ *
*/
int
virNetworkGetAutostart(virNetworkPtr network,
@@ -1004,6 +1079,9 @@ virNetworkGetAutostart(virNetworkPtr network,
* when the host machine boots.
*
* Returns -1 in case of error, 0 in case of success
+ *
+ * Since: v0.2.1
+ *
*/
int
virNetworkSetAutostart(virNetworkPtr network,
@@ -1042,6 +1120,9 @@ virNetworkSetAutostart(virNetworkPtr network,
* Determine if the network is currently running
*
* Returns 1 if running, 0 if inactive, -1 on error
+ *
+ * Since: v0.7.3
+ *
*/
int
virNetworkIsActive(virNetworkPtr net)
@@ -1075,6 +1156,9 @@ virNetworkIsActive(virNetworkPtr net)
* which means it will still exist after shutting down
*
* Returns 1 if persistent, 0 if transient, -1 on error
+ *
+ * Since: v0.7.3
+ *
*/
int
virNetworkIsPersistent(virNetworkPtr net)
@@ -1134,6 +1218,9 @@ virNetworkIsPersistent(virNetworkPtr net)
* be passed to the virConnectNetworkEventDeregisterAny() method.
*
* Returns a callback identifier on success, -1 on failure.
+ *
+ * Since: v1.2.1
+ *
*/
int
virConnectNetworkEventRegisterAny(virConnectPtr conn,
@@ -1195,6 +1282,9 @@ virConnectNetworkEventRegisterAny(virConnectPtr conn,
* value obtained from a previous virConnectNetworkEventRegisterAny() method.
*
* Returns 0 on success, -1 on failure
+ *
+ * Since: v1.2.1
+ *
*/
int
virConnectNetworkEventDeregisterAny(virConnectPtr conn,
@@ -1297,6 +1387,9 @@ virConnectNetworkEventDeregisterAny(virConnectPtr conn,
* Returns the number of leases found or -1 and sets @leases to NULL in
* case of error.
*
+ * Since: v1.2.6
+ *
+ *
*/
int
virNetworkGetDHCPLeases(virNetworkPtr network,
@@ -1338,6 +1431,9 @@ virNetworkGetDHCPLeases(virNetworkPtr network,
* @lease: pointer to a leases object
*
* Frees all the memory occupied by @lease.
+ *
+ * Since: v1.2.6
+ *
*/
void
virNetworkDHCPLeaseFree(virNetworkDHCPLeasePtr lease)
@@ -1366,6 +1462,9 @@ virNetworkDHCPLeaseFree(virNetworkDHCPLeasePtr lease)
*
* Returns a new network port object or NULL in case of failure. If the
* network port cannot be found, then VIR_ERR_NO_NETWORK_PORT error is raised.
+ *
+ * Since: v5.5.0
+ *
*/
virNetworkPortPtr
virNetworkPortLookupByUUID(virNetworkPtr net,
@@ -1403,6 +1502,9 @@ virNetworkPortLookupByUUID(virNetworkPtr net,
*
* Returns a new network port object or NULL in case of failure. If the
* network port cannot be found, then VIR_ERR_NO_NETWORK_PORT error is raised.
+ *
+ * Since: v5.5.0
+ *
*/
virNetworkPortPtr
virNetworkPortLookupByUUIDString(virNetworkPtr net,
@@ -1443,6 +1545,9 @@ virNetworkPortLookupByUUIDString(virNetworkPtr net,
* includes bandwidth parameters.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v5.5.0
+ *
*/
int
virNetworkPortSetParameters(virNetworkPortPtr port,
@@ -1491,6 +1596,9 @@ virNetworkPortSetParameters(virNetworkPortPtr port,
* on success.
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v5.5.0
+ *
*/
int
virNetworkPortGetParameters(virNetworkPortPtr port,
@@ -1535,6 +1643,9 @@ virNetworkPortGetParameters(virNetworkPortPtr port,
* network port object is no longer needed.
*
* Returns a new network port object or NULL in case of failure
+ *
+ * Since: v5.5.0
+ *
*/
virNetworkPortPtr
virNetworkPortCreateXML(virNetworkPtr net,
@@ -1573,6 +1684,9 @@ virNetworkPortCreateXML(virNetworkPtr net,
* call.
*
* Returns the virNetworkPtr or NULL in case of failure.
+ *
+ * Since: v5.5.0
+ *
*/
virNetworkPtr
virNetworkPortGetNetwork(virNetworkPortPtr port)
@@ -1597,6 +1711,9 @@ virNetworkPortGetNetwork(virNetworkPortPtr port)
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
* the caller must free() the returned value.
+ *
+ * Since: v5.5.0
+ *
*/
char *
virNetworkPortGetXMLDesc(virNetworkPortPtr port,
@@ -1634,6 +1751,9 @@ virNetworkPortGetXMLDesc(virNetworkPortPtr port,
* Get the UUID for a network port
*
* Returns -1 in case of error, 0 in case of success
+ *
+ * Since: v5.5.0
+ *
*/
int
virNetworkPortGetUUID(virNetworkPortPtr port,
@@ -1665,6 +1785,9 @@ virNetworkPortGetUUID(virNetworkPortPtr port,
* UUID see RFC4122.
*
* Returns -1 in case of error, 0 in case of success
+ *
+ * Since: v5.5.0
+ *
*/
int
virNetworkPortGetUUIDString(virNetworkPortPtr port,
@@ -1697,6 +1820,9 @@ virNetworkPortGetUUIDString(virNetworkPortPtr port,
* port.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v5.5.0
+ *
*/
int
virNetworkPortDelete(virNetworkPortPtr port,
@@ -1745,6 +1871,9 @@ virNetworkPortDelete(virNetworkPortPtr port,
* in the return count, to make iteration easier. The caller is responsible
* for calling virNetworkPortFree() on each array element, then calling
* free() on @ports.
+ *
+ * Since: v5.5.0
+ *
*/
int
virNetworkListAllPorts(virNetworkPtr network,
@@ -1782,6 +1911,9 @@ virNetworkListAllPorts(virNetworkPtr network,
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v5.5.0
+ *
*/
int
virNetworkPortFree(virNetworkPortPtr port)
@@ -1813,6 +1945,9 @@ virNetworkPortFree(virNetworkPortPtr port)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v5.5.0
+ *
*/
int
virNetworkPortRef(virNetworkPortPtr port)
diff --git a/src/libvirt-nodedev.c b/src/libvirt-nodedev.c
index 3695b39270..3f23267b7a 100644
--- a/src/libvirt-nodedev.c
+++ b/src/libvirt-nodedev.c
@@ -40,6 +40,9 @@ VIR_LOG_INIT("libvirt.nodedev");
* will be restricted to devices with the specified capability
*
* Returns the number of node devices or -1 in case of error
+ *
+ * Since: v0.5.0
+ *
*/
int
virNodeNumOfDevices(virConnectPtr conn, const char *cap, unsigned int flags)
@@ -86,6 +89,9 @@ virNodeNumOfDevices(virConnectPtr conn, const char *cap, unsigned int flags)
* count, to make iteration easier. The caller is responsible for calling
* virNodeDeviceFree() on each array element, then calling free() on
* @devices.
+ *
+ * Since: v0.10.2
+ *
*/
int
virConnectListAllNodeDevices(virConnectPtr conn,
@@ -135,6 +141,9 @@ virConnectListAllNodeDevices(virConnectPtr conn,
* will be restricted to devices with the specified capability
*
* Returns the number of node devices found or -1 in case of error
+ *
+ * Since: v0.5.0
+ *
*/
int
virNodeListDevices(virConnectPtr conn,
@@ -178,6 +187,9 @@ virNodeListDevices(virConnectPtr conn,
* node device object is no longer needed.
*
* Returns a virNodeDevicePtr if found, NULL otherwise.
+ *
+ * Since: v0.5.0
+ *
*/
virNodeDevicePtr
virNodeDeviceLookupByName(virConnectPtr conn, const char *name)
@@ -218,6 +230,9 @@ virNodeDeviceLookupByName(virConnectPtr conn, const char *name)
* node device object is no longer needed.
*
* Returns a virNodeDevicePtr if found, NULL otherwise.
+ *
+ * Since: v1.0.3
+ *
*/
virNodeDevicePtr
virNodeDeviceLookupSCSIHostByWWN(virConnectPtr conn,
@@ -260,6 +275,9 @@ virNodeDeviceLookupSCSIHostByWWN(virConnectPtr conn,
* the device.
*
* Returns the XML document, or NULL on error
+ *
+ * Since: v0.5.0
+ *
*/
char *
virNodeDeviceGetXMLDesc(virNodeDevicePtr dev, unsigned int flags)
@@ -293,6 +311,9 @@ virNodeDeviceGetXMLDesc(virNodeDevicePtr dev, unsigned int flags)
* Just return the device name
*
* Returns the device name or NULL in case of error
+ *
+ * Since: v0.5.0
+ *
*/
const char *
virNodeDeviceGetName(virNodeDevicePtr dev)
@@ -315,6 +336,9 @@ virNodeDeviceGetName(virNodeDevicePtr dev)
*
* Returns the name of the device's parent, or NULL if an
* error occurred or when the device has no parent.
+ *
+ * Since: v0.5.0
+ *
*/
const char *
virNodeDeviceGetParent(virNodeDevicePtr dev)
@@ -346,6 +370,9 @@ virNodeDeviceGetParent(virNodeDevicePtr dev)
*
* Returns the number of capabilities supported by the device or -1
* in case of error.
+ *
+ * Since: v0.5.0
+ *
*/
int
virNodeDeviceNumOfCaps(virNodeDevicePtr dev)
@@ -382,6 +409,9 @@ virNodeDeviceNumOfCaps(virNodeDevicePtr dev)
*
* Returns the number of capability names listed in @names or -1
* in case of error.
+ *
+ * Since: v0.5.0
+ *
*/
int
virNodeDeviceListCaps(virNodeDevicePtr dev,
@@ -421,6 +451,9 @@ virNodeDeviceListCaps(virNodeDevicePtr dev,
* this was the last reference.
*
* Returns the 0 for success, -1 for error.
+ *
+ * Since: v0.5.0
+ *
*/
int
virNodeDeviceFree(virNodeDevicePtr dev)
@@ -452,6 +485,9 @@ virNodeDeviceFree(virNodeDevicePtr dev)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.6.0
+ *
*/
int
virNodeDeviceRef(virNodeDevicePtr dev)
@@ -490,6 +526,9 @@ virNodeDeviceRef(virNodeDevicePtr dev)
* API should be used instead.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.6.1
+ *
*/
int
virNodeDeviceDettach(virNodeDevicePtr dev)
@@ -543,6 +582,9 @@ virNodeDeviceDettach(virNodeDevicePtr dev)
* to the node using the virNodeDeviceReAttach() method.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v1.0.5
+ *
*/
int
virNodeDeviceDetachFlags(virNodeDevicePtr dev,
@@ -588,6 +630,9 @@ virNodeDeviceDetachFlags(virNodeDevicePtr dev,
* If the device is currently in use by a guest, this method may fail.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.6.1
+ *
*/
int
virNodeDeviceReAttach(virNodeDevicePtr dev)
@@ -631,6 +676,9 @@ virNodeDeviceReAttach(virNodeDevicePtr dev)
* this function may fail.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.6.1
+ *
*/
int
virNodeDeviceReset(virNodeDevicePtr dev)
@@ -671,6 +719,9 @@ virNodeDeviceReset(virNodeDevicePtr dev)
* node device object is no longer needed.
*
* Returns a node device object if successful, NULL in case of failure
+ *
+ * Since: v0.6.3
+ *
*/
virNodeDevicePtr
virNodeDeviceCreateXML(virConnectPtr conn,
@@ -710,6 +761,9 @@ virNodeDeviceCreateXML(virConnectPtr conn,
* may require privileged access.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.6.3
+ *
*/
int
virNodeDeviceDestroy(virNodeDevicePtr dev)
@@ -750,6 +804,9 @@ virNodeDeviceDestroy(virNodeDevicePtr dev)
* node device object is no longer needed.
*
* Returns a node device object if successful, NULL in case of failure
+ *
+ * Since: v7.3.0
+ *
*/
virNodeDevicePtr
virNodeDeviceDefineXML(virConnectPtr conn,
@@ -789,6 +846,9 @@ virNodeDeviceDefineXML(virConnectPtr conn,
* operating system. This function may require privileged access.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v7.3.0
+ *
*/
int
virNodeDeviceUndefine(virNodeDevicePtr dev,
@@ -826,6 +886,9 @@ virNodeDeviceUndefine(virNodeDevicePtr dev,
* Start a defined node device:
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.5.0
+ *
*/
int
virNodeDeviceCreate(virNodeDevicePtr dev,
@@ -889,6 +952,9 @@ virNodeDeviceCreate(virNodeDevicePtr dev,
* be passed to the virConnectNodeDeviceEventDeregisterAny() method.
*
* Returns a callback identifier on success, -1 on failure.
+ *
+ * Since: v2.2.0
+ *
*/
int
virConnectNodeDeviceEventRegisterAny(virConnectPtr conn,
@@ -953,6 +1019,9 @@ virConnectNodeDeviceEventRegisterAny(virConnectPtr conn,
* value obtained from a previous virConnectNodeDeviceEventRegisterAny() method.
*
* Returns 0 on success, -1 on failure.
+ *
+ * Since: v2.2.0
+ *
*/
int
virConnectNodeDeviceEventDeregisterAny(virConnectPtr conn,
@@ -990,6 +1059,9 @@ virConnectNodeDeviceEventDeregisterAny(virConnectPtr conn,
* boots or the parent device becomes available.
*
* Returns -1 in case of error, 0 in case of success
+ *
+ * Since: v7.8.0
+ *
*/
int
virNodeDeviceSetAutostart(virNodeDevicePtr dev,
@@ -1029,6 +1101,9 @@ virNodeDeviceSetAutostart(virNodeDevicePtr dev,
* becomes available.
*
* Returns -1 in case of error, 0 in case of success
+ *
+ * Since: v7.8.0
+ *
*/
int
virNodeDeviceGetAutostart(virNodeDevicePtr dev,
@@ -1065,6 +1140,9 @@ virNodeDeviceGetAutostart(virNodeDevicePtr dev,
* which means it will still exist after shutting down
*
* Returns 1 if persistent, 0 if transient, -1 on error
+ *
+ * Since: v7.8.0
+ *
*/
int
virNodeDeviceIsPersistent(virNodeDevicePtr dev)
@@ -1098,6 +1176,9 @@ virNodeDeviceIsPersistent(virNodeDevicePtr dev)
* Determine if the node device is currently active
*
* Returns 1 if active, 0 if inactive, -1 on error
+ *
+ * Since: v7.8.0
+ *
*/
int virNodeDeviceIsActive(virNodeDevicePtr dev)
{
diff --git a/src/libvirt-nwfilter.c b/src/libvirt-nwfilter.c
index 73b061152e..e3d4375bad 100644
--- a/src/libvirt-nwfilter.c
+++ b/src/libvirt-nwfilter.c
@@ -35,6 +35,9 @@ VIR_LOG_INIT("libvirt.nwfilter");
* Provides the number of nwfilters.
*
* Returns the number of nwfilters found or -1 in case of error
+ *
+ * Since: v0.8.0
+ *
*/
int
virConnectNumOfNWFilters(virConnectPtr conn)
@@ -77,6 +80,9 @@ virConnectNumOfNWFilters(virConnectPtr conn)
* have an extra allocated element set to NULL but not included in the return count,
* to make iteration easier. The caller is responsible for calling
* virNWFilterFree() on each array element, then calling free() on @filters.
+ *
+ * Since: v0.10.2
+ *
*/
int
virConnectListAllNWFilters(virConnectPtr conn,
@@ -121,6 +127,9 @@ virConnectListAllNWFilters(virConnectPtr conn,
* virConnectListAllNWFilters().
*
* Returns the number of network filters found or -1 in case of error
+ *
+ * Since: v0.8.0
+ *
*/
int
virConnectListNWFilters(virConnectPtr conn, char **const names, int maxnames)
@@ -161,6 +170,9 @@ virConnectListNWFilters(virConnectPtr conn, char **const names, int maxnames)
*
* Returns a new nwfilter object or NULL in case of failure. If the
* network filter cannot be found, then VIR_ERR_NO_NWFILTER error is raised.
+ *
+ * Since: v0.8.0
+ *
*/
virNWFilterPtr
virNWFilterLookupByName(virConnectPtr conn, const char *name)
@@ -200,6 +212,9 @@ virNWFilterLookupByName(virConnectPtr conn, const char *name)
*
* Returns a new nwfilter object or NULL in case of failure. If the
* nwfdilter cannot be found, then VIR_ERR_NO_NWFILTER error is raised.
+ *
+ * Since: v0.8.0
+ *
*/
virNWFilterPtr
virNWFilterLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
@@ -239,6 +254,9 @@ virNWFilterLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
*
* Returns a new nwfilter object or NULL in case of failure. If the
* nwfilter cannot be found, then VIR_ERR_NO_NWFILTER error is raised.
+ *
+ * Since: v0.8.0
+ *
*/
virNWFilterPtr
virNWFilterLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
@@ -274,6 +292,9 @@ virNWFilterLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.8.0
+ *
*/
int
virNWFilterFree(virNWFilterPtr nwfilter)
@@ -297,6 +318,9 @@ virNWFilterFree(virNWFilterPtr nwfilter)
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* its lifetime will be the same as the nwfilter object.
+ *
+ * Since: v0.8.0
+ *
*/
const char *
virNWFilterGetName(virNWFilterPtr nwfilter)
@@ -319,6 +343,9 @@ virNWFilterGetName(virNWFilterPtr nwfilter)
* Get the UUID for a network filter
*
* Returns -1 in case of error, 0 in case of success
+ *
+ * Since: v0.8.0
+ *
*/
int
virNWFilterGetUUID(virNWFilterPtr nwfilter, unsigned char *uuid)
@@ -349,6 +376,9 @@ virNWFilterGetUUID(virNWFilterPtr nwfilter, unsigned char *uuid)
* UUID see RFC4122.
*
* Returns -1 in case of error, 0 in case of success
+ *
+ * Since: v0.8.0
+ *
*/
int
virNWFilterGetUUIDString(virNWFilterPtr nwfilter, char *buf)
@@ -381,6 +411,9 @@ virNWFilterGetUUIDString(virNWFilterPtr nwfilter, char *buf)
* nwfilter object is no longer needed.
*
* Returns a new nwfilter object or NULL in case of failure
+ *
+ * Since: v0.8.0
+ *
*/
virNWFilterPtr
virNWFilterDefineXML(virConnectPtr conn, const char *xmlDesc)
@@ -422,6 +455,9 @@ virNWFilterDefineXML(virConnectPtr conn, const char *xmlDesc)
* nwfilter object is no longer needed.
*
* Returns a new nwfilter object or NULL in case of failure
+ *
+ * Since: v7.7.0
+ *
*/
virNWFilterPtr
virNWFilterDefineXMLFlags(virConnectPtr conn, const char *xmlDesc, unsigned int flags)
@@ -459,6 +495,9 @@ virNWFilterDefineXMLFlags(virConnectPtr conn, const char *xmlDesc, unsigned int
* associated virNWFilterPtr object.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.8.0
+ *
*/
int
virNWFilterUndefine(virNWFilterPtr nwfilter)
@@ -499,6 +538,9 @@ virNWFilterUndefine(virNWFilterPtr nwfilter)
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case
* of error. The caller must free() the returned value.
+ *
+ * Since: v0.8.0
+ *
*/
char *
virNWFilterGetXMLDesc(virNWFilterPtr nwfilter, unsigned int flags)
@@ -543,6 +585,9 @@ virNWFilterGetXMLDesc(virNWFilterPtr nwfilter, unsigned int flags)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.8.0
+ *
*/
int
virNWFilterRef(virNWFilterPtr nwfilter)
@@ -574,6 +619,9 @@ virNWFilterRef(virNWFilterPtr nwfilter)
* have an extra allocated element set to NULL but not included in the return count,
* to make iteration easier. The caller is responsible for calling
* virNWFilterFree() on each array element, then calling free() on @filters.
+ *
+ * Since: v4.5.0
+ *
*/
int
virConnectListAllNWFilterBindings(virConnectPtr conn,
@@ -620,6 +668,9 @@ virConnectListAllNWFilterBindings(virConnectPtr conn,
* Returns a new binding object or NULL in case of failure. If the
* network filter cannot be found, then VIR_ERR_NO_NWFILTER_BINDING
* error is raised.
+ *
+ * Since: v4.5.0
+ *
*/
virNWFilterBindingPtr
virNWFilterBindingLookupByPortDev(virConnectPtr conn, const char *portdev)
@@ -655,6 +706,9 @@ virNWFilterBindingLookupByPortDev(virConnectPtr conn, const char *portdev)
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v4.5.0
+ *
*/
int
virNWFilterBindingFree(virNWFilterBindingPtr binding)
@@ -678,6 +732,9 @@ virNWFilterBindingFree(virNWFilterBindingPtr binding)
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* its lifetime will be the same as the binding object.
+ *
+ * Since: v4.5.0
+ *
*/
const char *
virNWFilterBindingGetPortDev(virNWFilterBindingPtr binding)
@@ -700,6 +757,9 @@ virNWFilterBindingGetPortDev(virNWFilterBindingPtr binding)
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* its lifetime will be the same as the binding object.
+ *
+ * Since: v4.5.0
+ *
*/
const char *
virNWFilterBindingGetFilterName(virNWFilterBindingPtr binding)
@@ -734,6 +794,9 @@ virNWFilterBindingGetFilterName(virNWFilterBindingPtr binding)
* binding object is no longer needed.
*
* Returns a new binding object or NULL in case of failure
+ *
+ * Since: v4.5.0
+ *
*/
virNWFilterBindingPtr
virNWFilterBindingCreateXML(virConnectPtr conn, const char *xml, unsigned int flags)
@@ -775,6 +838,9 @@ virNWFilterBindingCreateXML(virConnectPtr conn, const char *xml, unsigned int fl
* would be accomplished by using virNWFilterBindingCreateXML.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v4.5.0
+ *
*/
int
virNWFilterBindingDelete(virNWFilterBindingPtr binding)
@@ -815,6 +881,9 @@ virNWFilterBindingDelete(virNWFilterBindingPtr binding)
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case
* of error. The caller must free() the returned value.
+ *
+ * Since: v4.5.0
+ *
*/
char *
virNWFilterBindingGetXMLDesc(virNWFilterBindingPtr binding, unsigned int flags)
@@ -859,6 +928,9 @@ virNWFilterBindingGetXMLDesc(virNWFilterBindingPtr binding, unsigned int flags)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v4.5.0
+ *
*/
int
virNWFilterBindingRef(virNWFilterBindingPtr binding)
diff --git a/src/libvirt-secret.c b/src/libvirt-secret.c
index d2a3a4bd9d..e0d14f6e4d 100644
--- a/src/libvirt-secret.c
+++ b/src/libvirt-secret.c
@@ -35,6 +35,9 @@ VIR_LOG_INIT("libvirt.secret");
* counter on the connection is not increased by this call.
*
* Returns the virConnectPtr or NULL in case of failure.
+ *
+ * Since: v0.7.1
+ *
*/
virConnectPtr
virSecretGetConnect(virSecretPtr secret)
@@ -56,6 +59,9 @@ virSecretGetConnect(virSecretPtr secret)
* Fetch number of currently defined secrets.
*
* Returns the number currently defined secrets.
+ *
+ * Since: v0.7.1
+ *
*/
int
virConnectNumOfSecrets(virConnectPtr conn)
@@ -116,6 +122,9 @@ virConnectNumOfSecrets(virConnectPtr conn)
* have an extra allocated element set to NULL but not included in the return count,
* to make iteration easier. The caller is responsible for calling
* virSecretFree() on each array element, then calling free() on @secrets.
+ *
+ * Since: v0.10.2
+ *
*/
int
virConnectListAllSecrets(virConnectPtr conn,
@@ -160,6 +169,9 @@ virConnectListAllSecrets(virConnectPtr conn,
* virConnectListAllSecrets().
*
* Returns the number of UUIDs provided in the array, or -1 on failure.
+ *
+ * Since: v0.7.1
+ *
*/
int
virConnectListSecrets(virConnectPtr conn, char **uuids, int maxuuids)
@@ -202,6 +214,9 @@ virConnectListSecrets(virConnectPtr conn, char **uuids, int maxuuids)
*
* Returns a new secret object or NULL in case of failure. If the
* secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
+ *
+ * Since: v0.7.1
+ *
*/
virSecretPtr
virSecretLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
@@ -243,6 +258,9 @@ virSecretLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
*
* Returns a new secret object or NULL in case of failure. If the
* secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
+ *
+ * Since: v0.7.1
+ *
*/
virSecretPtr
virSecretLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
@@ -285,6 +303,9 @@ virSecretLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
*
* Returns a new secret object or NULL in case of failure. If the
* secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
+ *
+ * Since: v0.7.1
+ *
*/
virSecretPtr
virSecretLookupByUsage(virConnectPtr conn,
@@ -332,6 +353,9 @@ virSecretLookupByUsage(virConnectPtr conn,
* secret object is no longer needed.
*
* Returns a secret on success, NULL on failure.
+ *
+ * Since: v0.7.1
+ *
*/
virSecretPtr
virSecretDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
@@ -370,6 +394,9 @@ virSecretDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
*
* Returns 0 on success with the uuid buffer being filled, or
* -1 upon failure.
+ *
+ * Since: v0.7.1
+ *
*/
int
virSecretGetUUID(virSecretPtr secret, unsigned char *uuid)
@@ -400,6 +427,9 @@ virSecretGetUUID(virSecretPtr secret, unsigned char *uuid)
* UUID see RFC4122.
*
* Returns -1 in case of error, 0 in case of success
+ *
+ * Since: v0.7.1
+ *
*/
int
virSecretGetUUIDString(virSecretPtr secret, char *buf)
@@ -432,6 +462,9 @@ virSecretGetUUIDString(virSecretPtr secret, char *buf)
*
* Returns a positive integer identifying the type of object,
* or -1 upon error.
+ *
+ * Since: v0.7.1
+ *
*/
int
virSecretGetUsageType(virSecretPtr secret)
@@ -461,6 +494,9 @@ virSecretGetUsageType(virSecretPtr secret)
*
* Returns a string identifying the object using the secret,
* or NULL upon error
+ *
+ * Since: v0.7.1
+ *
*/
const char *
virSecretGetUsageID(virSecretPtr secret)
@@ -484,6 +520,9 @@ virSecretGetUsageID(virSecretPtr secret)
*
* Returns the XML document on success, NULL on failure. The caller must
* free() the XML.
+ *
+ * Since: v0.7.1
+ *
*/
char *
virSecretGetXMLDesc(virSecretPtr secret, unsigned int flags)
@@ -524,6 +563,9 @@ virSecretGetXMLDesc(virSecretPtr secret, unsigned int flags)
* Sets the value of a secret.
*
* Returns 0 on success, -1 on failure.
+ *
+ * Since: v0.7.1
+ *
*/
int
virSecretSetValue(virSecretPtr secret, const unsigned char *value,
@@ -569,6 +611,9 @@ virSecretSetValue(virSecretPtr secret, const unsigned char *value,
*
* Returns the secret value on success, NULL on failure. The caller must
* free() the secret value.
+ *
+ * Since: v0.7.1
+ *
*/
unsigned char *
virSecretGetValue(virSecretPtr secret, size_t *value_size, unsigned int flags)
@@ -610,6 +655,9 @@ virSecretGetValue(virSecretPtr secret, size_t *value_size, unsigned int flags)
* virSecretPtr object.
*
* Returns 0 on success, -1 on failure.
+ *
+ * Since: v0.7.1
+ *
*/
int
virSecretUndefine(virSecretPtr secret)
@@ -657,6 +705,9 @@ virSecretUndefine(virSecretPtr secret)
* increment the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.7.1
+ *
*/
int
virSecretRef(virSecretPtr secret)
@@ -679,6 +730,9 @@ virSecretRef(virSecretPtr secret)
* Release the secret handle. The underlying secret continues to exist.
*
* Returns 0 on success, or -1 on error
+ *
+ * Since: v0.7.1
+ *
*/
int
virSecretFree(virSecretPtr secret)
@@ -728,6 +782,9 @@ virSecretFree(virSecretPtr secret)
* be passed to the virConnectSecretEventDeregisterAny() method.
*
* Returns a callback identifier on success, -1 on failure.
+ *
+ * Since: v3.0.0
+ *
*/
int
virConnectSecretEventRegisterAny(virConnectPtr conn,
@@ -794,6 +851,9 @@ virConnectSecretEventRegisterAny(virConnectPtr conn,
* value obtained from a previous virConnectSecretEventRegisterAny() method.
*
* Returns 0 on success, -1 on failure.
+ *
+ * Since: v3.0.0
+ *
*/
int
virConnectSecretEventDeregisterAny(virConnectPtr conn,
diff --git a/src/libvirt-storage.c b/src/libvirt-storage.c
index cbc522b300..61d062f847 100644
--- a/src/libvirt-storage.c
+++ b/src/libvirt-storage.c
@@ -37,6 +37,9 @@ VIR_LOG_INIT("libvirt.storage");
* call.
*
* Returns the virConnectPtr or NULL in case of failure.
+ *
+ * Since: v0.4.1
+ *
*/
virConnectPtr
virStoragePoolGetConnect(virStoragePoolPtr pool)
@@ -104,6 +107,9 @@ virStoragePoolGetConnect(virStoragePoolPtr pool)
* in the return count, to make iteration easier. The caller is responsible
* for calling virStoragePoolFree() on each array element, then calling
* free() on @pools.
+ *
+ * Since: v0.10.2
+ *
*/
int
virConnectListAllStoragePools(virConnectPtr conn,
@@ -143,6 +149,9 @@ virConnectListAllStoragePools(virConnectPtr conn,
* Provides the number of active storage pools
*
* Returns the number of pools found, or -1 on error
+ *
+ * Since: v0.4.1
+ *
*/
int
virConnectNumOfStoragePools(virConnectPtr conn)
@@ -187,6 +196,9 @@ virConnectNumOfStoragePools(virConnectPtr conn)
* virConnectNumOfStoragePools() and this call; you are only guaranteed
* that all currently active pools were listed if the return is less than
* @maxnames. The client must call free() on each returned name.
+ *
+ * Since: v0.4.1
+ *
*/
int
virConnectListStoragePools(virConnectPtr conn,
@@ -224,6 +236,9 @@ virConnectListStoragePools(virConnectPtr conn,
* Provides the number of inactive storage pools
*
* Returns the number of pools found, or -1 on error
+ *
+ * Since: v0.4.1
+ *
*/
int
virConnectNumOfDefinedStoragePools(virConnectPtr conn)
@@ -268,6 +283,9 @@ virConnectNumOfDefinedStoragePools(virConnectPtr conn)
* a call to virConnectNumOfDefinedStoragePools() and this call; you are only
* guaranteed that all currently defined pools were listed if the return
* is less than @maxnames. The client must call free() on each returned name.
+ *
+ * Since: v0.4.1
+ *
*/
int
virConnectListDefinedStoragePools(virConnectPtr conn,
@@ -318,6 +336,9 @@ virConnectListDefinedStoragePools(virConnectPtr conn,
* Returns an xml document consisting of a SourceList element
* containing a source document appropriate to the given pool
* type for each discovered source.
+ *
+ * Since: v0.4.6
+ *
*/
char *
virConnectFindStoragePoolSources(virConnectPtr conn,
@@ -361,6 +382,9 @@ virConnectFindStoragePoolSources(virConnectPtr conn,
* storage pool object is no longer needed.
*
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
+ *
+ * Since: v0.4.1
+ *
*/
virStoragePoolPtr
virStoragePoolLookupByName(virConnectPtr conn,
@@ -400,6 +424,9 @@ virStoragePoolLookupByName(virConnectPtr conn,
* storage pool object is no longer needed.
*
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
+ *
+ * Since: v0.4.1
+ *
*/
virStoragePoolPtr
virStoragePoolLookupByUUID(virConnectPtr conn,
@@ -439,6 +466,9 @@ virStoragePoolLookupByUUID(virConnectPtr conn,
* storage pool object is no longer needed.
*
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
+ *
+ * Since: v0.4.1
+ *
*/
virStoragePoolPtr
virStoragePoolLookupByUUIDString(virConnectPtr conn,
@@ -477,6 +507,9 @@ virStoragePoolLookupByUUIDString(virConnectPtr conn,
* storage pool object is no longer needed.
*
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
+ *
+ * Since: v0.4.1
+ *
*/
virStoragePoolPtr
virStoragePoolLookupByVolume(virStorageVolPtr vol)
@@ -516,6 +549,9 @@ virStoragePoolLookupByVolume(virStorageVolPtr vol)
* storage pool object is no longer needed.
*
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
+ *
+ * Since: v4.1.0
+ *
*/
virStoragePoolPtr
virStoragePoolLookupByTargetPath(virConnectPtr conn,
@@ -557,6 +593,9 @@ virStoragePoolLookupByTargetPath(virConnectPtr conn,
* storage pool object is no longer needed.
*
* Returns a virStoragePoolPtr object, or NULL if creation failed
+ *
+ * Since: v0.4.1
+ *
*/
virStoragePoolPtr
virStoragePoolCreateXML(virConnectPtr conn,
@@ -600,6 +639,9 @@ virStoragePoolCreateXML(virConnectPtr conn,
* storage pool object is no longer needed.
*
* Returns a virStoragePoolPtr object, or NULL if creation failed
+ *
+ * Since: v0.4.1
+ *
*/
virStoragePoolPtr
virStoragePoolDefineXML(virConnectPtr conn,
@@ -641,6 +683,9 @@ virStoragePoolDefineXML(virConnectPtr conn,
* Build the underlying storage pool
*
* Returns 0 on success, or -1 upon failure
+ *
+ * Since: v0.4.1
+ *
*/
int
virStoragePoolBuild(virStoragePoolPtr pool,
@@ -679,6 +724,9 @@ virStoragePoolBuild(virStoragePoolPtr pool,
* Undefine an inactive storage pool
*
* Returns 0 on success, -1 on failure
+ *
+ * Since: v0.4.1
+ *
*/
int
virStoragePoolUndefine(virStoragePoolPtr pool)
@@ -717,6 +765,9 @@ virStoragePoolUndefine(virStoragePoolPtr pool)
* Starts an inactive storage pool
*
* Returns 0 on success, or -1 if it could not be started
+ *
+ * Since: v0.4.1
+ *
*/
int
virStoragePoolCreate(virStoragePoolPtr pool,
@@ -759,6 +810,9 @@ virStoragePoolCreate(virStoragePoolPtr pool,
* the associated virStoragePoolPtr object.
*
* Returns 0 on success, or -1 if it could not be destroyed
+ *
+ * Since: v0.4.1
+ *
*/
int
virStoragePoolDestroy(virStoragePoolPtr pool)
@@ -799,6 +853,9 @@ virStoragePoolDestroy(virStoragePoolPtr pool)
* itself is not free'd.
*
* Returns 0 on success, or -1 if it could not be obliterate
+ *
+ * Since: v0.4.1
+ *
*/
int
virStoragePoolDelete(virStoragePoolPtr pool,
@@ -838,6 +895,9 @@ virStoragePoolDelete(virStoragePoolPtr pool,
* it. Does not change the state of the pool on the host.
*
* Returns 0 on success, or -1 if it could not be free'd.
+ *
+ * Since: v0.4.1
+ *
*/
int
virStoragePoolFree(virStoragePoolPtr pool)
@@ -870,6 +930,9 @@ virStoragePoolFree(virStoragePoolPtr pool)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.6.0
+ *
*/
int
virStoragePoolRef(virStoragePoolPtr pool)
@@ -895,6 +958,9 @@ virStoragePoolRef(virStoragePoolPtr pool)
* new devices at the OS layer
*
* Returns 0 if the volume list was refreshed, -1 on failure
+ *
+ * Since: v0.4.1
+ *
*/
int
virStoragePoolRefresh(virStoragePoolPtr pool,
@@ -933,6 +999,9 @@ virStoragePoolRefresh(virStoragePoolPtr pool,
* Fetch the locally unique name of the storage pool
*
* Returns the name of the pool, or NULL on error
+ *
+ * Since: v0.4.1
+ *
*/
const char*
virStoragePoolGetName(virStoragePoolPtr pool)
@@ -955,6 +1024,9 @@ virStoragePoolGetName(virStoragePoolPtr pool)
* Fetch the globally unique ID of the storage pool
*
* Returns 0 on success, or -1 on error;
+ *
+ * Since: v0.4.1
+ *
*/
int
virStoragePoolGetUUID(virStoragePoolPtr pool,
@@ -985,6 +1057,9 @@ virStoragePoolGetUUID(virStoragePoolPtr pool,
* Fetch the globally unique ID of the storage pool as a string
*
* Returns 0 on success, or -1 on error;
+ *
+ * Since: v0.4.1
+ *
*/
int
virStoragePoolGetUUIDString(virStoragePoolPtr pool,
@@ -1015,6 +1090,9 @@ virStoragePoolGetUUIDString(virStoragePoolPtr pool,
* such as free space / usage summary
*
* Returns 0 on success, or -1 on failure.
+ *
+ * Since: v0.4.1
+ *
*/
int
virStoragePoolGetInfo(virStoragePoolPtr pool,
@@ -1059,6 +1137,9 @@ virStoragePoolGetInfo(virStoragePoolPtr pool,
* into the virStoragePoolCreateXML method.
*
* Returns a XML document (caller frees), or NULL on error
+ *
+ * Since: v0.4.1
+ *
*/
char *
virStoragePoolGetXMLDesc(virStoragePoolPtr pool,
@@ -1097,6 +1178,9 @@ virStoragePoolGetXMLDesc(virStoragePoolPtr pool,
* whether the pool is automatically started at boot time
*
* Returns 0 on success, -1 on failure
+ *
+ * Since: v0.4.1
+ *
*/
int
virStoragePoolGetAutostart(virStoragePoolPtr pool,
@@ -1137,6 +1221,9 @@ virStoragePoolGetAutostart(virStoragePoolPtr pool,
* when the host machine boots.
*
* Returns 0 on success, -1 on failure
+ *
+ * Since: v0.4.1
+ *
*/
int
virStoragePoolSetAutostart(virStoragePoolPtr pool,
@@ -1185,6 +1272,9 @@ virStoragePoolSetAutostart(virStoragePoolPtr pool,
* in the return count, to make iteration easier. The caller is responsible
* for calling virStorageVolFree() on each array element, then calling
* free() on @vols.
+ *
+ * Since: v0.10.2
+ *
*/
int
virStoragePoolListAllVolumes(virStoragePoolPtr pool,
@@ -1221,6 +1311,9 @@ virStoragePoolListAllVolumes(virStoragePoolPtr pool,
* Fetch the number of storage volumes within a pool
*
* Returns the number of storage pools, or -1 on failure
+ *
+ * Since: v0.4.1
+ *
*/
int
virStoragePoolNumOfVolumes(virStoragePoolPtr pool)
@@ -1260,6 +1353,9 @@ virStoragePoolNumOfVolumes(virStoragePoolPtr pool)
* virStoragePoolListAllVolumes().
*
* Returns the number of names fetched, or -1 on error
+ *
+ * Since: v0.4.1
+ *
*/
int
virStoragePoolListVolumes(virStoragePoolPtr pool,
@@ -1299,6 +1395,9 @@ virStoragePoolListVolumes(virStoragePoolPtr pool,
* call.
*
* Returns the virConnectPtr or NULL in case of failure.
+ *
+ * Since: v0.4.1
+ *
*/
virConnectPtr
virStorageVolGetConnect(virStorageVolPtr vol)
@@ -1325,6 +1424,9 @@ virStorageVolGetConnect(virStorageVolPtr vol)
* storage volume object is no longer needed.
*
* Returns a storage volume, or NULL if not found / error
+ *
+ * Since: v0.4.1
+ *
*/
virStorageVolPtr
virStorageVolLookupByName(virStoragePoolPtr pool,
@@ -1365,6 +1467,9 @@ virStorageVolLookupByName(virStoragePoolPtr pool,
* storage volume object is no longer needed.
*
* Returns a storage volume, or NULL if not found / error
+ *
+ * Since: v0.4.1
+ *
*/
virStorageVolPtr
virStorageVolLookupByKey(virConnectPtr conn,
@@ -1405,6 +1510,9 @@ virStorageVolLookupByKey(virConnectPtr conn,
* storage volume object is no longer needed.
*
* Returns a storage volume, or NULL if not found / error
+ *
+ * Since: v0.4.1
+ *
*/
virStorageVolPtr
virStorageVolLookupByPath(virConnectPtr conn,
@@ -1441,6 +1549,9 @@ virStorageVolLookupByPath(virConnectPtr conn,
* within the scope of a pool
*
* Returns the volume name, or NULL on error
+ *
+ * Since: v0.4.1
+ *
*/
const char*
virStorageVolGetName(virStorageVolPtr vol)
@@ -1464,6 +1575,9 @@ virStorageVolGetName(virStorageVolPtr vol)
* key no matter what host it is accessed from
*
* Returns the volume key, or NULL on error
+ *
+ * Since: v0.4.1
+ *
*/
const char*
virStorageVolGetKey(virStorageVolPtr vol)
@@ -1497,6 +1611,9 @@ virStorageVolGetKey(virStorageVolPtr vol)
* storage volume object is no longer needed.
*
* Returns the storage volume, or NULL on error
+ *
+ * Since: v0.4.1
+ *
*/
virStorageVolPtr
virStorageVolCreateXML(virStoragePoolPtr pool,
@@ -1548,6 +1665,9 @@ virStorageVolCreateXML(virStoragePoolPtr pool,
* storage volume object is no longer needed.
*
* Returns the storage volume, or NULL on error
+ *
+ * Since: v0.6.4
+ *
*/
virStorageVolPtr
virStorageVolCreateXMLFrom(virStoragePoolPtr pool,
@@ -1612,6 +1732,9 @@ virStorageVolCreateXMLFrom(virStoragePoolPtr pool,
* another active stream is writing to the storage volume.
*
* Returns 0, or -1 upon error.
+ *
+ * Since: v0.9.0
+ *
*/
int
virStorageVolDownload(virStorageVolPtr vol,
@@ -1695,6 +1818,9 @@ virStorageVolDownload(virStorageVolPtr vol,
* capacity, and allocation.
*
* Returns 0, or -1 upon error.
+ *
+ * Since: v0.9.0
+ *
*/
int
virStorageVolUpload(virStorageVolPtr vol,
@@ -1748,6 +1874,9 @@ virStorageVolUpload(virStorageVolPtr vol,
* Delete the storage volume from the pool
*
* Returns 0 on success, or -1 on error
+ *
+ * Since: v0.4.1
+ *
*/
int
virStorageVolDelete(virStorageVolPtr vol,
@@ -1797,6 +1926,9 @@ virStorageVolDelete(virStorageVolPtr vol,
* network file systems are known to be problematic.
*
* Returns 0 on success, or -1 on error
+ *
+ * Since: v0.8.0
+ *
*/
int
virStorageVolWipe(virStorageVolPtr vol,
@@ -1843,6 +1975,9 @@ virStorageVolWipe(virStorageVolPtr vol,
* problematic.
*
* Returns 0 on success, or -1 on error.
+ *
+ * Since: v0.9.10
+ *
*/
int
virStorageVolWipePattern(virStorageVolPtr vol,
@@ -1883,6 +2018,9 @@ virStorageVolWipePattern(virStorageVolPtr vol,
* storage volume continues to exist.
*
* Returns 0 on success, or -1 on error
+ *
+ * Since: v0.4.1
+ *
*/
int
virStorageVolFree(virStorageVolPtr vol)
@@ -1914,6 +2052,9 @@ virStorageVolFree(virStorageVolPtr vol)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
+ *
+ * Since: v0.6.0
+ *
*/
int
virStorageVolRef(virStorageVolPtr vol)
@@ -1938,6 +2079,9 @@ virStorageVolRef(virStorageVolPtr vol)
* volume such as its current allocation
*
* Returns 0 on success, or -1 on failure
+ *
+ * Since: v0.4.1
+ *
*/
int
virStorageVolGetInfo(virStorageVolPtr vol,
@@ -1988,6 +2132,9 @@ virStorageVolGetInfo(virStorageVolPtr vol,
* as is the case with qcow2 files.
*
* Returns 0 on success, or -1 on failure
+ *
+ * Since: v3.0.0
+ *
*/
int
virStorageVolGetInfoFlags(virStorageVolPtr vol,
@@ -2032,6 +2179,9 @@ virStorageVolGetInfoFlags(virStorageVolPtr vol,
* the storage volume
*
* Returns the XML document, or NULL on error
+ *
+ * Since: v0.4.1
+ *
*/
char *
virStorageVolGetXMLDesc(virStorageVolPtr vol,
@@ -2073,6 +2223,9 @@ virStorageVolGetXMLDesc(virStorageVolPtr vol,
*
* Returns the storage volume path, or NULL on error. The
* caller must free() the returned path after use.
+ *
+ * Since: v0.4.1
+ *
*/
char *
virStorageVolGetPath(virStorageVolPtr vol)
@@ -2134,6 +2287,9 @@ virStorageVolGetPath(virStorageVolPtr vol)
* than the current size.
*
* Returns 0 on success, or -1 on error.
+ *
+ * Since: v0.9.10
+ *
*/
int
virStorageVolResize(virStorageVolPtr vol,
@@ -2183,6 +2339,9 @@ virStorageVolResize(virStorageVolPtr vol,
* Determine if the storage pool is currently running
*
* Returns 1 if running, 0 if inactive, -1 on error
+ *
+ * Since: v0.7.3
+ *
*/
int
virStoragePoolIsActive(virStoragePoolPtr pool)
@@ -2216,6 +2375,9 @@ virStoragePoolIsActive(virStoragePoolPtr pool)
* which means it will still exist after shutting down
*
* Returns 1 if persistent, 0 if transient, -1 on error
+ *
+ * Since: v0.7.3
+ *
*/
int
virStoragePoolIsPersistent(virStoragePoolPtr pool)
@@ -2274,6 +2436,9 @@ virStoragePoolIsPersistent(virStoragePoolPtr pool)
* be passed to the virConnectStoragePoolEventDeregisterAny() method.
*
* Returns a callback identifier on success, -1 on failure.
+ *
+ * Since: v2.0.0
+ *
*/
int
virConnectStoragePoolEventRegisterAny(virConnectPtr conn,
@@ -2337,6 +2502,9 @@ virConnectStoragePoolEventRegisterAny(virConnectPtr conn,
* value obtained from a previous virConnectStoragePoolEventRegisterAny() method.
*
* Returns 0 on success, -1 on failure
+ *
+ * Since: v2.0.0
+ *
*/
int
virConnectStoragePoolEventDeregisterAny(virConnectPtr conn,
@@ -2376,6 +2544,9 @@ virConnectStoragePoolEventDeregisterAny(virConnectPtr conn,
* are supported along with the file/disk formats for each pool.
*
* Returns NULL in case of error or an XML string defining the capabilities.
+ *
+ * Since: v5.2.0
+ *
*/
char *
virConnectGetStoragePoolCapabilities(virConnectPtr conn,
diff --git a/src/libvirt-stream.c b/src/libvirt-stream.c
index 80dbc83a59..35beb67a10 100644
--- a/src/libvirt-stream.c
+++ b/src/libvirt-stream.c
@@ -52,6 +52,9 @@ VIR_LOG_INIT("libvirt.stream");
* VIR_STREAM_NONBLOCK for flags, otherwise pass 0.
*
* Returns the new stream, or NULL upon error
+ *
+ * Since: v0.7.2
+ *
*/
virStreamPtr
virStreamNew(virConnectPtr conn,
@@ -85,6 +88,9 @@ virStreamNew(virConnectPtr conn,
* the caller no longer needs the reference to this object.
*
* Returns 0 in case of success, -1 in case of failure
+ *
+ * Since: v0.7.2
+ *
*/
int
virStreamRef(virStreamPtr stream)
@@ -163,6 +169,9 @@ virStreamRef(virStreamPtr stream)
*
* Returns -2 if the outgoing transmit buffers are full &
* the stream is marked as non-blocking.
+ *
+ * Since: v0.7.2
+ *
*/
int
virStreamSend(virStreamPtr stream,
@@ -258,6 +267,9 @@ virStreamSend(virStreamPtr stream,
*
* Returns -2 if there is no data pending to be read & the
* stream is marked as non-blocking.
+ *
+ * Since: v0.7.2
+ *
*/
int
virStreamRecv(virStreamPtr stream,
@@ -345,6 +357,9 @@ virStreamRecv(virStreamPtr stream,
*
* Returns -3 if there is a hole in stream and caller requested
* to stop at a hole.
+ *
+ * Since: v3.4.0
+ *
*/
int
virStreamRecvFlags(virStreamPtr stream,
@@ -412,6 +427,9 @@ virStreamRecvFlags(virStreamPtr stream,
*
* Returns 0 on success,
* -1 error
+ *
+ * Since: v3.4.0
+ *
*/
int
virStreamSendHole(virStreamPtr stream,
@@ -455,6 +473,9 @@ virStreamSendHole(virStreamPtr stream,
*
* Returns 0 on success,
* -1 on error or when there's currently no hole in the stream
+ *
+ * Since: v3.4.0
+ *
*/
int
virStreamRecvHole(virStreamPtr stream,
@@ -577,6 +598,9 @@ virStreamInData(virStreamPtr stream,
* Returns -1 upon any error, with virStreamAbort() already
* having been called, so the caller need only call
* virStreamFree().
+ *
+ * Since: v0.7.2
+ *
*/
int
virStreamSendAll(virStreamPtr stream,
@@ -706,6 +730,9 @@ virStreamSendAll(virStreamPtr stream,
* Returns -1 upon any error, with virStreamAbort() already
* having been called, so the caller need only call
* virStreamFree().
+ *
+ * Since: v3.4.0
+ *
*/
int virStreamSparseSendAll(virStreamPtr stream,
virStreamSourceFunc handler,
@@ -845,6 +872,9 @@ int virStreamSparseSendAll(virStreamPtr stream,
* Returns -1 upon any error, with virStreamAbort() already
* having been called, so the caller need only call
* virStreamFree()
+ *
+ * Since: v0.7.2
+ *
*/
int
virStreamRecvAll(virStreamPtr stream,
@@ -958,6 +988,9 @@ virStreamRecvAll(virStreamPtr stream,
*
* Returns -1 upon any error, with virStreamAbort() already
* having been called, so the caller need only call virStreamFree().
+ *
+ * Since: v3.4.0
+ *
*/
int
virStreamSparseRecvAll(virStreamPtr stream,
@@ -1051,6 +1084,9 @@ virStreamSparseRecvAll(virStreamPtr stream,
* to integrate into an event loop
*
* Returns 0 on success, -1 upon error
+ *
+ * Since: v0.7.2
+ *
*/
int
virStreamEventAddCallback(virStreamPtr stream,
@@ -1094,6 +1130,9 @@ virStreamEventAddCallback(virStreamPtr stream,
* is guaranteed to succeed if a callback is already registered
*
* Returns 0 on success, -1 if no callback is registered
+ *
+ * Since: v0.7.2
+ *
*/
int
virStreamEventUpdateCallback(virStreamPtr stream,
@@ -1129,6 +1168,9 @@ virStreamEventUpdateCallback(virStreamPtr stream,
* Remove an event callback from the stream
*
* Returns 0 on success, -1 on error
+ *
+ * Since: v0.7.2
+ *
*/
int
virStreamEventRemoveCallback(virStreamPtr stream)
@@ -1173,6 +1215,9 @@ virStreamEventRemoveCallback(virStreamPtr stream)
* beforehand.
*
* Returns 0 on success, -1 upon error
+ *
+ * Since: v0.7.2
+ *
*/
int
virStreamFinish(virStreamPtr stream)
@@ -1215,6 +1260,9 @@ virStreamFinish(virStreamPtr stream)
* beforehand.
*
* Returns 0 on success, -1 upon error
+ *
+ * Since: v0.7.2
+ *
*/
int
virStreamAbort(virStreamPtr stream)
@@ -1259,6 +1307,9 @@ virStreamAbort(virStreamPtr stream)
* the virStreamAbort function should be called first.
*
* Returns 0 upon success, or -1 on error
+ *
+ * Since: v0.7.2
+ *
*/
int
virStreamFree(virStreamPtr stream)
diff --git a/src/libvirt.c b/src/libvirt.c
index 6cda75d1ca..0c8e787920 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -296,6 +296,9 @@ virGlobalInit(void)
* connection attempt.
*
* Returns 0 in case of success, -1 in case of error
+ *
+ * Since: v0.1.0
+ *
*/
int
virInitialize(void)
@@ -797,6 +800,9 @@ virStateStop(void)
*
* Returns -1 in case of failure, 0 otherwise, and values for @libVer and
* @typeVer have the format major * 1,000,000 + minor * 1,000 + release.
+ *
+ * Since: v0.0.1
+ *
*/
int
virGetVersion(unsigned long *libVer, const char *type G_GNUC_UNUSED,
@@ -1185,6 +1191,9 @@ virConnectOpenInternal(const char *name,
* is no longer needed.
*
* Returns a pointer to the hypervisor connection or NULL in case of error
+ *
+ * Since: v0.0.1
+ *
*/
virConnectPtr
virConnectOpen(const char *name)
@@ -1218,6 +1227,9 @@ virConnectOpen(const char *name)
* URIs are documented at https://libvirt.org/uri.html
*
* Returns a pointer to the hypervisor connection or NULL in case of error
+ *
+ * Since: v0.0.1
+ *
*/
virConnectPtr
virConnectOpenReadOnly(const char *name)
@@ -1252,6 +1264,9 @@ virConnectOpenReadOnly(const char *name)
* URIs are documented at https://libvirt.org/uri.html
*
* Returns a pointer to the hypervisor connection or NULL in case of error
+ *
+ * Since: v0.4.1
+ *
*/
virConnectPtr
virConnectOpenAuth(const char *name,
@@ -1300,6 +1315,9 @@ virConnectOpenAuth(const char *name,
* value if some other object still has a temporary reference to the
* connection, but the application should not try to further use a
* connection after the virConnectClose that matches the initial open.
+ *
+ * Since: v0.0.1
+ *
*/
int
virConnectClose(virConnectPtr conn)
diff --git a/src/util/virerror.c b/src/util/virerror.c
index e864a50fba..7d009d2298 100644
--- a/src/util/virerror.c
+++ b/src/util/virerror.c
@@ -254,6 +254,9 @@ virLastErrorObject(void)
* threads can safely access this concurrently.
*
* Returns a pointer to the last error or NULL if none occurred.
+ *
+ * Since: v0.1.0
+ *
*/
virErrorPtr
virGetLastError(void)
@@ -271,6 +274,9 @@ virGetLastError(void)
* Get the most recent error code (enum virErrorNumber).
*
* Returns the most recent error code, or VIR_ERR_OK if none is set.
+ *
+ * Since: v4.5.0
+ *
*/
int
virGetLastErrorCode(void)
@@ -289,6 +295,9 @@ virGetLastErrorCode(void)
*
* Returns a numerical value of the most recent error's origin, or VIR_FROM_NONE
* if none is set.
+ *
+ * Since: v4.5.0
+ *
*/
int
virGetLastErrorDomain(void)
@@ -307,6 +316,9 @@ virGetLastErrorDomain(void)
*
* Returns the most recent error message string in this
* thread, or a generic message if none is set
+ *
+ * Since: v1.0.5.2
+ *
*/
const char *
virGetLastErrorMessage(void)
@@ -361,6 +373,9 @@ virSetError(virErrorPtr newerr)
* One will need to free the result with virResetError()
*
* Returns error code or -1 in case of parameter error.
+ *
+ * Since: v0.1.0
+ *
*/
int
virCopyLastError(virErrorPtr to)
@@ -392,6 +407,9 @@ virCopyLastError(virErrorPtr to)
* Returns a pointer to the copied error or NULL if allocation failed.
* It is the caller's responsibility to free the error with
* virFreeError().
+ *
+ * Since: v0.6.1
+ *
*/
virErrorPtr
virSaveLastError(void)
@@ -455,6 +473,9 @@ virErrorRestore(virErrorPtr *savederr)
* @err: pointer to the virError to clean up
*
* Reset the error being pointed to
+ *
+ * Since: v0.1.0
+ *
*/
void
virResetError(virErrorPtr err)
@@ -473,6 +494,9 @@ virResetError(virErrorPtr err)
* @err: error to free
*
* Resets and frees the given error.
+ *
+ * Since: v0.6.1
+ *
*/
void
virFreeError(virErrorPtr err)
@@ -489,6 +513,9 @@ virFreeError(virErrorPtr err)
* The error object is kept in thread local storage, so separate
* threads can safely access this concurrently, only resetting
* their own error object.
+ *
+ * Since: v0.1.0
+ *
*/
void
virResetLastError(void)
@@ -519,6 +546,9 @@ virResetLastError(void)
* remains for backwards compatibility.
*
* Returns a pointer to the last error or NULL if none occurred.
+ *
+ * Since: v0.1.0
+ *
*/
virErrorPtr
virConnGetLastError(virConnectPtr conn)
@@ -553,6 +583,9 @@ virConnGetLastError(virConnectPtr conn)
*
* Returns 0 if no error was found and the error code otherwise and -1 in case
* of parameter error.
+ *
+ * Since: v0.1.0
+ *
*/
int
virConnCopyLastError(virConnectPtr conn, virErrorPtr to)
@@ -579,6 +612,9 @@ virConnCopyLastError(virConnectPtr conn, virErrorPtr to)
* threads can safely access this concurrently.
*
* Reset the last error caught on that connection
+ *
+ * Since: v0.1.0
+ *
*/
void
virConnResetLastError(virConnectPtr conn)
@@ -598,6 +634,9 @@ virConnResetLastError(virConnectPtr conn)
* Set a library global error handling function, if @handler is NULL,
* it will reset to default printing on stderr. The error raised there
* are those for which no handler at the connection level could caught.
+ *
+ * Since: v0.1.0
+ *
*/
void
virSetErrorFunc(void *userData, virErrorFunc handler)
@@ -615,6 +654,9 @@ virSetErrorFunc(void *userData, virErrorFunc handler)
* Set a connection error handling function, if @handler is NULL
* it will reset to default which is to pass error back to the global
* library handler.
+ *
+ * Since: v0.1.0
+ *
*/
void
virConnSetErrorFunc(virConnectPtr conn, void *userData,
@@ -633,6 +675,9 @@ virConnSetErrorFunc(virConnectPtr conn, void *userData,
* @err: pointer to the error.
*
* Default routine reporting an error to stderr.
+ *
+ * Since: v0.1.0
+ *
*/
void
virDefaultErrorFunc(virErrorPtr err)
diff --git a/src/util/virevent.c b/src/util/virevent.c
index f6eb806faf..6914901507 100644
--- a/src/util/virevent.c
+++ b/src/util/virevent.c
@@ -69,6 +69,9 @@ static virEventRemoveTimeoutFunc removeTimeoutImpl;
*
* Returns -1 if the file handle cannot be registered, otherwise a handle
* watch number to be used for updating and unregistering for events.
+ *
+ * Since: v0.9.3
+ *
*/
int
virEventAddHandle(int fd,
@@ -94,6 +97,9 @@ virEventAddHandle(int fd,
* virEventRegisterImpl() or virEventRegisterDefaultImpl().
*
* Will not fail if fd exists.
+ *
+ * Since: v0.9.3
+ *
*/
void
virEventUpdateHandle(int watch, int events)
@@ -112,6 +118,9 @@ virEventUpdateHandle(int watch, int events)
* virEventRegisterImpl() or virEventRegisterDefaultImpl().
*
* Returns -1 if the file handle was not registered, 0 upon success.
+ *
+ * Since: v0.9.3
+ *
*/
int
virEventRemoveHandle(int watch)
@@ -139,6 +148,9 @@ virEventRemoveHandle(int watch)
*
* Returns -1 if the timer cannot be registered, a positive
* integer timer id upon success.
+ *
+ * Since: v0.9.3
+ *
*/
int
virEventAddTimeout(int timeout,
@@ -166,6 +178,9 @@ virEventAddTimeout(int timeout,
* to zero will cause it to fire on every event loop iteration.
*
* Will not fail if timer exists.
+ *
+ * Since: v0.9.3
+ *
*/
void
virEventUpdateTimeout(int timer, int timeout)
@@ -184,6 +199,9 @@ virEventUpdateTimeout(int timer, int timeout)
* virEventRegisterImpl() or virEventRegisterDefaultImpl().
*
* Returns -1 if the timer was not registered, 0 upon success.
+ *
+ * Since: v0.9.3
+ *
*/
int
virEventRemoveTimeout(int timer)
@@ -232,6 +250,9 @@ virEventRemoveTimeout(int timer)
* virConnectClose on all open connections, so it is not safe
* to stop running the event loop immediately after closing
* the connection.
+ *
+ * Since: v0.5.0
+ *
*/
void virEventRegisterImpl(virEventAddHandleFunc addHandle,
virEventUpdateHandleFunc updateHandle,
@@ -300,6 +321,9 @@ int virEventRequireImpl(void)
* virEventAddHandle() or virConnectDomainEventRegisterAny().
*
* Returns 0 on success, -1 on failure.
+ *
+ * Since: v0.9.0
+ *
*/
int virEventRegisterDefaultImpl(void)
{
@@ -335,6 +359,9 @@ int virEventRegisterDefaultImpl(void)
* }
*
* Returns 0 on success, -1 on failure.
+ *
+ * Since: v0.9.0
+ *
*/
int virEventRunDefaultImpl(void)
{
--
2.35.1
More information about the libvir-list
mailing list