[PATCH v4 11/19] docstring: function: libvirt: Add 'Since version' metadata
Victor Toso
victortoso at redhat.com
Fri Apr 22 19:23:36 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 | 48 ++++
include/libvirt/libvirt-event.h | 16 ++
include/libvirt/libvirt-host.h | 4 +
include/libvirt/libvirt-network.h | 4 +
include/libvirt/libvirt-nodedev.h | 4 +
include/libvirt/libvirt-secret.h | 4 +
include/libvirt/libvirt-storage.h | 4 +
include/libvirt/libvirt-stream.h | 12 +
include/libvirt/virterror.h | 2 +
src/libvirt-domain-checkpoint.c | 24 ++
src/libvirt-domain-snapshot.c | 42 ++++
src/libvirt-domain.c | 371 +++++++++++++++++++++++++++++-
src/libvirt-host.c | 68 ++++++
src/libvirt-interface.c | 42 ++++
src/libvirt-network.c | 89 +++++++
src/libvirt-nodedev.c | 54 +++++
src/libvirt-nwfilter.c | 48 ++++
src/libvirt-secret.c | 40 ++++
src/libvirt-storage.c | 114 +++++++++
src/libvirt-stream.c | 34 +++
src/libvirt.c | 12 +
src/util/virerror.c | 30 +++
src/util/virevent.c | 18 ++
23 files changed, 1083 insertions(+), 1 deletion(-)
diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index 5e165f60ed..bba37dfbcf 100644
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -3980,6 +3980,8 @@ 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,
@@ -4526,6 +4528,8 @@ 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,
@@ -4540,6 +4544,8 @@ 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,
@@ -4577,6 +4583,7 @@ 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,
@@ -4612,6 +4619,8 @@ 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,
@@ -4639,6 +4648,7 @@ 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,
@@ -4782,6 +4792,8 @@ 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,
@@ -4834,6 +4846,8 @@ 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,
@@ -4887,6 +4901,8 @@ 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,
@@ -4924,6 +4940,8 @@ 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,
@@ -4943,6 +4961,8 @@ 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,
@@ -4961,6 +4981,8 @@ 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,
@@ -4977,6 +4999,8 @@ 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,
@@ -4995,6 +5019,8 @@ 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,
@@ -5012,6 +5038,8 @@ 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,
@@ -5029,6 +5057,8 @@ 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,
@@ -5048,6 +5078,8 @@ 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,
@@ -5066,6 +5098,8 @@ 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,
@@ -5089,6 +5123,8 @@ 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,
@@ -5113,6 +5149,8 @@ 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,
@@ -5478,6 +5516,8 @@ 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,
@@ -5528,6 +5568,8 @@ 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,
@@ -5557,6 +5599,8 @@ 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,
@@ -5582,6 +5626,8 @@ 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,
@@ -5606,6 +5652,8 @@ 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 89dea437c0..cc517044c6 100644
--- a/include/libvirt/libvirt-event.h
+++ b/include/libvirt/libvirt-event.h
@@ -54,6 +54,8 @@ 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);
@@ -81,6 +83,8 @@ 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,
@@ -94,6 +98,8 @@ 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);
@@ -109,6 +115,8 @@ 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);
@@ -119,6 +127,8 @@ 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);
@@ -137,6 +147,8 @@ typedef void (*virEventTimeoutCallback)(int timer, void *opaque);
* this purpose.
*
* Returns a timer value
+ *
+ * Since: v0.5.0
*/
typedef int (*virEventAddTimeoutFunc)(int timeout,
virEventTimeoutCallback cb,
@@ -150,6 +162,8 @@ 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);
@@ -164,6 +178,8 @@ 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 aa4d2a583f..b5cf8a4a4a 100644
--- a/include/libvirt/libvirt-host.h
+++ b/include/libvirt/libvirt-host.h
@@ -650,6 +650,8 @@ 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,
@@ -841,6 +843,8 @@ 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 39a38f0c3f..0a9f0ecb0d 100644
--- a/include/libvirt/libvirt-network.h
+++ b/include/libvirt/libvirt-network.h
@@ -300,6 +300,8 @@ 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,
@@ -398,6 +400,8 @@ 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 7d4dbd58b9..455bc2ce57 100644
--- a/include/libvirt/libvirt-nodedev.h
+++ b/include/libvirt/libvirt-nodedev.h
@@ -202,6 +202,8 @@ 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,
@@ -251,6 +253,8 @@ 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 537b5595b4..a71c3e7eba 100644
--- a/include/libvirt/libvirt-secret.h
+++ b/include/libvirt/libvirt-secret.h
@@ -182,6 +182,8 @@ 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,
@@ -229,6 +231,8 @@ 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 8f62b6f87a..30e3dc25c5 100644
--- a/include/libvirt/libvirt-storage.h
+++ b/include/libvirt/libvirt-storage.h
@@ -559,6 +559,8 @@ 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,
@@ -610,6 +612,8 @@ 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 a44612cd88..6b82711244 100644
--- a/include/libvirt/libvirt-stream.h
+++ b/include/libvirt/libvirt-stream.h
@@ -98,6 +98,8 @@ 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,
@@ -136,6 +138,8 @@ int virStreamSendAll(virStreamPtr st,
*
* Returns 0 on success,
* -1 upon error
+ *
+ * Since: v3.4.0
*/
typedef int (*virStreamSourceHoleFunc)(virStreamPtr st,
int *inData,
@@ -162,6 +166,8 @@ typedef int (*virStreamSourceHoleFunc)(virStreamPtr st,
*
* Returns 0 on success,
* -1 upon error.
+ *
+ * Since: v3.4.0
*/
typedef int (*virStreamSourceSkipFunc)(virStreamPtr st,
long long length,
@@ -199,6 +205,8 @@ 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,
@@ -229,6 +237,8 @@ int virStreamRecvAll(virStreamPtr st,
*
* Returns 0 on success,
* -1 upon error
+ *
+ * Since: v3.4.0
*/
typedef int (*virStreamSinkHoleFunc)(virStreamPtr st,
long long length,
@@ -261,6 +271,8 @@ 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 c4bcdf88bf..4e6dfaa3f4 100644
--- a/include/libvirt/virterror.h
+++ b/include/libvirt/virterror.h
@@ -360,6 +360,8 @@ 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..a92404a56f 100644
--- a/src/libvirt-domain-checkpoint.c
+++ b/src/libvirt-domain-checkpoint.c
@@ -35,6 +35,8 @@ 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 +60,8 @@ virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint)
* call.
*
* Returns the domain or NULL.
+ *
+ * Since: v5.6.0
*/
virDomainPtr
virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint)
@@ -81,6 +85,8 @@ virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint)
* call.
*
* Returns the connection or NULL.
+ *
+ * Since: v5.6.0
*/
virConnectPtr
virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint)
@@ -138,6 +144,8 @@ virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint)
*
* Returns an (opaque) new virDomainCheckpointPtr on success or NULL
* on failure.
+ *
+ * Since: v5.6.0
*/
virDomainCheckpointPtr
virDomainCheckpointCreateXML(virDomainPtr domain,
@@ -207,6 +215,8 @@ 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 +291,8 @@ 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 +360,8 @@ 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 +408,8 @@ 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 +456,8 @@ 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 +511,8 @@ virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint,
* silently ignored.
*
* Returns 0 on success, -1 on error.
+ *
+ * Since: v5.6.0
*/
int
virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint,
@@ -543,6 +563,8 @@ 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 +588,8 @@ 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..021f6f599d 100644
--- a/src/libvirt-domain-snapshot.c
+++ b/src/libvirt-domain-snapshot.c
@@ -35,6 +35,8 @@ 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 +60,8 @@ virDomainSnapshotGetName(virDomainSnapshotPtr snapshot)
* call.
*
* Returns the domain or NULL.
+ *
+ * Since: v0.9.5
*/
virDomainPtr
virDomainSnapshotGetDomain(virDomainSnapshotPtr snapshot)
@@ -81,6 +85,8 @@ virDomainSnapshotGetDomain(virDomainSnapshotPtr snapshot)
* call.
*
* Returns the connection or NULL.
+ *
+ * Since: v0.9.5
*/
virConnectPtr
virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
@@ -213,6 +219,8 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
*
* Returns an (opaque) new virDomainSnapshotPtr on success or NULL on
* failure.
+ *
+ * Since: v0.8.0
*/
virDomainSnapshotPtr
virDomainSnapshotCreateXML(virDomainPtr domain,
@@ -271,6 +279,8 @@ 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 +334,8 @@ 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 +400,8 @@ 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 +490,8 @@ 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 +541,8 @@ 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 +609,8 @@ 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 +682,8 @@ 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 +728,8 @@ 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 +770,8 @@ 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 +812,8 @@ 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 +856,8 @@ 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 +896,8 @@ 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 +937,8 @@ 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 +1018,8 @@ 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 +1077,8 @@ 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 +1129,8 @@ 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 +1154,8 @@ 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..e27d611882 100644
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -49,6 +49,8 @@ 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.3
*/
int
virConnectListDomains(virConnectPtr conn, int *ids, int maxids)
@@ -82,6 +84,8 @@ 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.3
*/
int
virConnectNumOfDomains(virConnectPtr conn)
@@ -115,6 +119,8 @@ virConnectNumOfDomains(virConnectPtr conn)
* call.
*
* Returns the virConnectPtr or NULL in case of failure.
+ *
+ * Since: v0.3.0
*/
virConnectPtr
virDomainGetConnect(virDomainPtr dom)
@@ -162,6 +168,8 @@ 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 +236,8 @@ 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 +294,8 @@ 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.3
*/
virDomainPtr
virDomainCreateLinux(virConnectPtr conn, const char *xmlDesc,
@@ -307,6 +319,8 @@ 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.3
*/
virDomainPtr
virDomainLookupByID(virConnectPtr conn, int id)
@@ -346,6 +360,8 @@ 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 +401,8 @@ 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 +440,8 @@ 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.3
*/
virDomainPtr
virDomainLookupByName(virConnectPtr conn, const char *name)
@@ -472,6 +492,8 @@ 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.3
*/
int
virDomainDestroy(virDomainPtr domain)
@@ -537,6 +559,8 @@ 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 +601,8 @@ 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.3
*/
int
virDomainFree(virDomainPtr domain)
@@ -608,6 +634,8 @@ 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 +664,8 @@ virDomainRef(virDomainPtr domain)
* special state like VIR_DOMAIN_PMSUSPENDED.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.0.3
*/
int
virDomainSuspend(virDomainPtr domain)
@@ -678,6 +708,8 @@ virDomainSuspend(virDomainPtr domain)
* special state like VIR_DOMAIN_PMSUSPENDED.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.0.3
*/
int
virDomainResume(virDomainPtr domain)
@@ -734,6 +766,8 @@ virDomainResume(virDomainPtr domain)
*
* Returns: 0 on success,
* -1 on failure.
+ *
+ * Since: v0.9.10
*/
int
virDomainPMSuspendForDuration(virDomainPtr dom,
@@ -781,6 +815,8 @@ virDomainPMSuspendForDuration(virDomainPtr dom,
*
* Returns: 0 on success,
* -1 on failure.
+ *
+ * Since: v0.9.11
*/
int
virDomainPMWakeup(virDomainPtr dom,
@@ -828,6 +864,8 @@ virDomainPMWakeup(virDomainPtr dom,
* and virDomainSaveImageDefineXML().
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.0.3
*/
int
virDomainSave(virDomainPtr domain, const char *to)
@@ -910,6 +948,8 @@ 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 +1010,8 @@ 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.3
*/
int
virDomainRestore(virConnectPtr conn, const char *from)
@@ -1042,6 +1084,8 @@ 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 +1148,8 @@ 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 +1218,8 @@ 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 +1294,8 @@ 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 +1372,8 @@ 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 +1453,8 @@ 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 +1514,8 @@ virDomainScreenshot(virDomainPtr domain,
* be deleted when the domain quits.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.0.3
*/
int
virDomainShutdown(virDomainPtr domain)
@@ -1520,6 +1576,8 @@ 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 +1636,8 @@ 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 +1682,8 @@ 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 +1723,8 @@ 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.3
*/
const char *
virDomainGetName(virDomainPtr domain)
@@ -1683,6 +1747,8 @@ 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 +1779,8 @@ 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 +1808,8 @@ 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.3
*/
unsigned int
virDomainGetID(virDomainPtr domain)
@@ -1762,6 +1832,8 @@ virDomainGetID(virDomainPtr domain)
*
* Returns the new string or NULL in case of error, the string must be
* freed by the caller.
+ *
+ * Since: v0.0.3
*/
char *
virDomainGetOSType(virDomainPtr domain)
@@ -1801,6 +1873,8 @@ virDomainGetOSType(virDomainPtr domain)
*
* Returns the memory size in kibibytes (blocks of 1024 bytes), or 0 in
* case of error.
+ *
+ * Since: v0.0.3
*/
unsigned long
virDomainGetMaxMemory(virDomainPtr domain)
@@ -1850,6 +1924,8 @@ virDomainGetMaxMemory(virDomainPtr domain)
* virDomainSetMemoryFlags().
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.0.3
*/
int
virDomainSetMaxMemory(virDomainPtr domain, unsigned long memory)
@@ -1903,6 +1979,8 @@ 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 +2043,8 @@ 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 +2105,8 @@ 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 +2157,8 @@ 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 +2233,8 @@ 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 +2302,8 @@ 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 +2369,8 @@ 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 +2428,8 @@ 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 +2495,8 @@ 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 +2555,8 @@ virDomainGetBlkioParameters(virDomainPtr domain,
* can be extracted.
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v0.0.3
*/
int
virDomainGetInfo(virDomainPtr domain, virDomainInfoPtr info)
@@ -2507,6 +2603,8 @@ 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 +2648,8 @@ 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 +2711,8 @@ 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.3
*/
char *
virDomainGetXMLDesc(virDomainPtr domain, unsigned int flags)
@@ -2660,6 +2762,8 @@ 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 +2814,8 @@ 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 +3669,8 @@ 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 +3867,8 @@ 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 +4078,8 @@ 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 +4368,8 @@ 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 +4446,8 @@ virDomainMigrateToURI(virDomainPtr domain,
* virDomainMigrateToURI3.
*
* Returns 0 if the migration succeeded, -1 upon error.
+ *
+ * Since: v0.9.2
*/
int
virDomainMigrateToURI2(virDomainPtr domain,
@@ -4412,6 +4528,8 @@ 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 +5399,8 @@ 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 +5449,8 @@ 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 +5516,8 @@ virDomainGetSchedulerParameters(virDomainPtr domain,
* }
*
* Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: v0.9.2
*/
int
virDomainGetSchedulerParametersFlags(virDomainPtr domain,
@@ -5458,6 +5582,8 @@ 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 +5638,8 @@ 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 +5711,8 @@ 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 +5790,8 @@ 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 +5861,8 @@ 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 +5923,8 @@ 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 +5993,8 @@ 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 +6085,8 @@ 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 +6166,8 @@ 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.3
*/
int
virDomainBlockPeek(virDomainPtr dom,
@@ -6095,6 +6237,8 @@ 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 +6307,8 @@ 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.3
*/
int
virDomainMemoryPeek(virDomainPtr dom,
@@ -6299,6 +6445,8 @@ 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 +6497,8 @@ 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 +6542,8 @@ 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 +6587,8 @@ 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 +6658,8 @@ 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 +6699,8 @@ 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.5
*/
int
virConnectNumOfDefinedDomains(virConnectPtr conn)
@@ -6586,6 +6744,8 @@ 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 +6845,8 @@ 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 +6888,8 @@ 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 +6958,8 @@ 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 +7036,8 @@ 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 +7095,8 @@ 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 +7138,8 @@ 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 +7180,8 @@ 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 +7224,8 @@ 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 +7311,8 @@ 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 +7370,8 @@ 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 +7443,8 @@ 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 +7514,8 @@ 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 +7572,8 @@ 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 +7641,7 @@ 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 +7700,8 @@ 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 +7779,7 @@ 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 +7835,8 @@ 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 +7902,8 @@ 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 +7963,8 @@ 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 +8009,8 @@ 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 +8050,8 @@ 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 +8095,8 @@ 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 +8161,8 @@ 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 +8222,8 @@ 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 +8285,8 @@ 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 +8340,8 @@ 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 +8384,8 @@ 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 +8448,8 @@ 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 +8535,8 @@ 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 +8604,8 @@ 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 +8665,8 @@ 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 +8711,8 @@ 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 +8795,8 @@ 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 +8861,8 @@ 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 +8917,8 @@ 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 +8979,8 @@ 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 +9024,8 @@ 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 +9060,8 @@ 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 +9095,8 @@ 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 +9137,8 @@ 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 +9172,8 @@ 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 +9211,8 @@ 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 +9277,8 @@ 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 +9331,8 @@ 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 +9375,8 @@ 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 +9418,8 @@ 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 +9460,8 @@ 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 +9506,8 @@ virDomainMigrateGetCompressionCache(virDomainPtr domain,
* virDomainGetJobStats.
*
* Returns 0 in case of success, -1 otherwise.
+ *
+ * Since: v1.0.3
*/
int
virDomainMigrateSetCompressionCache(virDomainPtr domain,
@@ -9298,6 +9552,8 @@ 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 +9597,8 @@ virDomainMigrateSetMaxSpeed(virDomainPtr domain,
* migration.
*
* Returns 0 in case of success, -1 otherwise.
+ *
+ * Since: v0.9.5
*/
int
virDomainMigrateGetMaxSpeed(virDomainPtr domain,
@@ -9434,6 +9692,8 @@ 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 +9757,8 @@ 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 +9817,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 +9875,8 @@ 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 +9924,8 @@ 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 +9964,8 @@ 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 +10012,8 @@ 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 +10072,8 @@ 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 +10139,8 @@ 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 +10205,8 @@ 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 +10264,8 @@ 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 +10316,8 @@ 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 +10401,8 @@ 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 +10480,8 @@ 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 +10545,8 @@ 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 +10621,8 @@ 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 +10767,8 @@ 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 +10899,8 @@ 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 +11047,8 @@ 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 +11108,8 @@ 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 +11190,8 @@ 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 +11253,8 @@ 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 +11330,8 @@ 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 +11461,8 @@ 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 +11563,8 @@ 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 +11610,8 @@ 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 +11661,8 @@ 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 +11707,8 @@ 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 +11752,8 @@ 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 +11799,8 @@ 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 +11851,8 @@ 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 +11899,8 @@ 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 +11951,8 @@ 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 +12359,8 @@ 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 +12440,8 @@ 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 +12509,8 @@ 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 +12543,8 @@ 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 +12580,8 @@ 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 +12674,8 @@ 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 +12717,8 @@ 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 +12762,8 @@ 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 +12822,8 @@ 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 +12873,8 @@ 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 +13027,8 @@ 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 +13103,8 @@ 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 +13154,8 @@ 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 +13211,8 @@ 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 +13279,8 @@ 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 +13338,8 @@ 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 +13436,8 @@ 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 +13488,8 @@ 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 +13539,8 @@ virDomainBackupGetXMLDesc(virDomainPtr domain,
*
* Returns: number of keys stored in @keys,
* -1 otherwise.
+ *
+ * Since: v6.10.0
*/
int
virDomainAuthorizedSSHKeysGet(virDomainPtr domain,
@@ -13246,6 +13609,8 @@ virDomainAuthorizedSSHKeysGet(virDomainPtr domain,
*
* Returns: 0 on success,
* -1 otherwise.
+ *
+ * Since: v6.10.0
*/
int
virDomainAuthorizedSSHKeysSet(virDomainPtr domain,
@@ -13314,6 +13679,8 @@ virDomainAuthorizedSSHKeysSet(virDomainPtr domain,
*
* Returns: number of messages stored in @msgs,
* -1 otherwise.
+ *
+ * Since: v7.1.0
*/
int
virDomainGetMessages(virDomainPtr domain,
@@ -13356,6 +13723,8 @@ 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..7e7545d447 100644
--- a/src/libvirt-host.c
+++ b/src/libvirt-host.c
@@ -47,6 +47,8 @@ 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 +87,8 @@ 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 +153,8 @@ virConnectSupportsFeature(virConnectPtr conn, int feature)
* hypervisor, use virConnectGetCapabilities().
*
* Returns NULL in case of error, a static zero terminated string otherwise.
+ *
+ * Since: v0.0.3
*/
const char *
virConnectGetType(virConnectPtr conn)
@@ -180,6 +186,8 @@ 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.3
*/
int
virConnectGetVersion(virConnectPtr conn, unsigned long *hvVer)
@@ -216,6 +224,8 @@ 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 +266,8 @@ 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 +307,8 @@ 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 +343,8 @@ 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 +383,8 @@ 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 +434,8 @@ 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 +472,8 @@ 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 +554,8 @@ 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 +643,8 @@ 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 +692,8 @@ 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 +740,8 @@ 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 +795,8 @@ 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 +861,8 @@ 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 +911,8 @@ 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 +956,8 @@ 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 +996,8 @@ 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 +1033,8 @@ 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 +1077,8 @@ 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 +1135,8 @@ 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 +1199,8 @@ 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 +1257,8 @@ 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 +1328,8 @@ 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 +1403,8 @@ 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 +1442,8 @@ 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 +1490,8 @@ virConnectIsAlive(virConnectPtr conn)
* context.
*
* Returns 0 on success, -1 on error
+ *
+ * Since: v0.10.0
*/
int
virConnectRegisterCloseCallback(virConnectPtr conn,
@@ -1471,6 +1529,8 @@ 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 +1573,8 @@ 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 +1661,8 @@ 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 +1733,8 @@ 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 +1788,8 @@ 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..b1194fd803 100644
--- a/src/libvirt-interface.c
+++ b/src/libvirt-interface.c
@@ -36,6 +36,8 @@ 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 +78,8 @@ 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 +119,8 @@ 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 +164,8 @@ 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 +201,8 @@ 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 +246,8 @@ 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 +290,8 @@ 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 +331,8 @@ 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 +368,8 @@ 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 +394,8 @@ 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 +427,8 @@ 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 +480,8 @@ 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 +528,8 @@ 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 +573,8 @@ 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 +622,8 @@ 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 +670,8 @@ 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 +695,8 @@ 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 +728,8 @@ 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 +770,8 @@ 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 +812,8 @@ 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 +849,8 @@ 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..0d1524ce34 100644
--- a/src/libvirt-network.c
+++ b/src/libvirt-network.c
@@ -38,6 +38,8 @@ 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 +88,8 @@ 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 +129,8 @@ 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 +173,8 @@ 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 +210,8 @@ 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 +254,8 @@ 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 +297,8 @@ 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 +338,8 @@ 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 +376,8 @@ 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 +417,8 @@ 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 +460,8 @@ 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 +502,8 @@ 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 +545,8 @@ 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 +582,8 @@ 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 +632,8 @@ virNetworkUndefine(virNetworkPtr network)
* running state, its persistent configuration, or both.
*
* Returns 0 in case of success, -1 in case of error
+ *
+ * Since: v0.10.2
*/
int
virNetworkUpdate(virNetworkPtr network,
@@ -670,6 +700,8 @@ 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 +742,8 @@ 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 +782,8 @@ 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 +815,8 @@ 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 +840,8 @@ 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 +864,8 @@ 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 +896,8 @@ 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 +933,8 @@ 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 +972,8 @@ 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 +1012,8 @@ 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 +1054,8 @@ 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 +1094,8 @@ 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 +1129,8 @@ 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 +1190,8 @@ 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 +1253,8 @@ 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 +1357,7 @@ 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 +1399,8 @@ 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 +1429,8 @@ 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 +1468,8 @@ 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 +1510,8 @@ 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 +1560,8 @@ 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 +1606,8 @@ 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 +1646,8 @@ virNetworkPortCreateXML(virNetworkPtr net,
* call.
*
* Returns the virNetworkPtr or NULL in case of failure.
+ *
+ * Since: v5.5.0
*/
virNetworkPtr
virNetworkPortGetNetwork(virNetworkPortPtr port)
@@ -1597,6 +1672,8 @@ 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 +1711,8 @@ 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 +1744,8 @@ 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 +1778,8 @@ 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 +1828,8 @@ 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 +1867,8 @@ 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 +1900,8 @@ 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..1caf3c8479 100644
--- a/src/libvirt-nodedev.c
+++ b/src/libvirt-nodedev.c
@@ -40,6 +40,8 @@ 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 +88,8 @@ 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 +139,8 @@ 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 +184,8 @@ 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 +226,8 @@ 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 +270,8 @@ 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 +305,8 @@ 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 +329,8 @@ 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 +362,8 @@ 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 +400,8 @@ 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 +441,8 @@ 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 +474,8 @@ 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 +514,8 @@ 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 +569,8 @@ 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 +616,8 @@ 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 +661,8 @@ 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 +703,8 @@ 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 +744,8 @@ 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 +786,8 @@ 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 +827,8 @@ 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 +866,8 @@ virNodeDeviceUndefine(virNodeDevicePtr dev,
* Start a defined node device:
*
* Returns 0 in case of success and -1 in case of failure.
+ *
+ * Since: v7.3.0
*/
int
virNodeDeviceCreate(virNodeDevicePtr dev,
@@ -889,6 +931,8 @@ 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 +997,8 @@ 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 +1036,8 @@ 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 +1077,8 @@ 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 +1115,8 @@ 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 +1150,8 @@ 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..bac50e89a3 100644
--- a/src/libvirt-nwfilter.c
+++ b/src/libvirt-nwfilter.c
@@ -35,6 +35,8 @@ 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 +79,8 @@ 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 +125,8 @@ 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 +167,8 @@ 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 +208,8 @@ 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 +249,8 @@ 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 +286,8 @@ 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 +311,8 @@ 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 +335,8 @@ 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 +367,8 @@ 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 +401,8 @@ 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 +444,8 @@ 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 +483,8 @@ 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 +525,8 @@ 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 +571,8 @@ 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 +604,8 @@ 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 +652,8 @@ 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 +689,8 @@ 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 +714,8 @@ 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 +738,8 @@ 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 +774,8 @@ 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 +817,8 @@ 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 +859,8 @@ 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 +905,8 @@ 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..ccf47a8f07 100644
--- a/src/libvirt-secret.c
+++ b/src/libvirt-secret.c
@@ -35,6 +35,8 @@ 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 +58,8 @@ 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 +120,8 @@ 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 +166,8 @@ 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 +210,8 @@ 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 +253,8 @@ 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 +297,8 @@ 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 +346,8 @@ 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 +386,8 @@ 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 +418,8 @@ 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 +452,8 @@ 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 +483,8 @@ 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 +508,8 @@ 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 +550,8 @@ 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 +597,8 @@ 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 +640,8 @@ 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 +689,8 @@ 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 +713,8 @@ 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 +764,8 @@ 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 +832,8 @@ 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..a31a18dbe9 100644
--- a/src/libvirt-storage.c
+++ b/src/libvirt-storage.c
@@ -37,6 +37,8 @@ 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 +106,8 @@ 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 +147,8 @@ 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 +193,8 @@ 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 +232,8 @@ 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 +278,8 @@ 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 +330,8 @@ 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.5
*/
char *
virConnectFindStoragePoolSources(virConnectPtr conn,
@@ -361,6 +375,8 @@ 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 +416,8 @@ 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 +457,8 @@ 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 +497,8 @@ 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 +538,8 @@ 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 +581,8 @@ 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 +626,8 @@ 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 +669,8 @@ 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 +709,8 @@ 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 +749,8 @@ 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 +793,8 @@ 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 +835,8 @@ 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 +876,8 @@ 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 +910,8 @@ 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 +937,8 @@ 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 +977,8 @@ 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 +1001,8 @@ 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 +1033,8 @@ 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 +1065,8 @@ 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 +1111,8 @@ 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 +1151,8 @@ 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 +1193,8 @@ 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 +1243,8 @@ 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 +1281,8 @@ 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 +1322,8 @@ virStoragePoolNumOfVolumes(virStoragePoolPtr pool)
* virStoragePoolListAllVolumes().
*
* Returns the number of names fetched, or -1 on error
+ *
+ * Since: v0.4.1
*/
int
virStoragePoolListVolumes(virStoragePoolPtr pool,
@@ -1299,6 +1363,8 @@ virStoragePoolListVolumes(virStoragePoolPtr pool,
* call.
*
* Returns the virConnectPtr or NULL in case of failure.
+ *
+ * Since: v0.4.1
*/
virConnectPtr
virStorageVolGetConnect(virStorageVolPtr vol)
@@ -1325,6 +1391,8 @@ 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 +1433,8 @@ 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 +1475,8 @@ 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 +1513,8 @@ 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 +1538,8 @@ 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 +1573,8 @@ 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 +1626,8 @@ 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 +1692,8 @@ 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 +1777,8 @@ virStorageVolDownload(virStorageVolPtr vol,
* capacity, and allocation.
*
* Returns 0, or -1 upon error.
+ *
+ * Since: v0.9.0
*/
int
virStorageVolUpload(virStorageVolPtr vol,
@@ -1748,6 +1832,8 @@ 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 +1883,8 @@ 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 +1931,8 @@ virStorageVolWipe(virStorageVolPtr vol,
* problematic.
*
* Returns 0 on success, or -1 on error.
+ *
+ * Since: v0.9.10
*/
int
virStorageVolWipePattern(virStorageVolPtr vol,
@@ -1883,6 +1973,8 @@ 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 +2006,8 @@ 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 +2032,8 @@ 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 +2084,8 @@ 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 +2130,8 @@ virStorageVolGetInfoFlags(virStorageVolPtr vol,
* the storage volume
*
* Returns the XML document, or NULL on error
+ *
+ * Since: v0.4.1
*/
char *
virStorageVolGetXMLDesc(virStorageVolPtr vol,
@@ -2073,6 +2173,8 @@ 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 +2236,8 @@ 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 +2287,8 @@ 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 +2322,8 @@ 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 +2382,8 @@ 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 +2447,8 @@ 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 +2488,8 @@ 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..2bc9535eb1 100644
--- a/src/libvirt-stream.c
+++ b/src/libvirt-stream.c
@@ -52,6 +52,8 @@ 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 +87,8 @@ 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 +167,8 @@ 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 +264,8 @@ 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 +353,8 @@ 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 +422,8 @@ virStreamRecvFlags(virStreamPtr stream,
*
* Returns 0 on success,
* -1 error
+ *
+ * Since: v3.4.0
*/
int
virStreamSendHole(virStreamPtr stream,
@@ -455,6 +467,8 @@ 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 +591,8 @@ 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 +722,8 @@ 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 +863,8 @@ 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 +978,8 @@ 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 +1073,8 @@ 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 +1118,8 @@ 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 +1155,8 @@ 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 +1201,8 @@ virStreamEventRemoveCallback(virStreamPtr stream)
* beforehand.
*
* Returns 0 on success, -1 upon error
+ *
+ * Since: v0.7.2
*/
int
virStreamFinish(virStreamPtr stream)
@@ -1215,6 +1245,8 @@ virStreamFinish(virStreamPtr stream)
* beforehand.
*
* Returns 0 on success, -1 upon error
+ *
+ * Since: v0.7.2
*/
int
virStreamAbort(virStreamPtr stream)
@@ -1259,6 +1291,8 @@ 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..ec685355b1 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -296,6 +296,8 @@ virGlobalInit(void)
* connection attempt.
*
* Returns 0 in case of success, -1 in case of error
+ *
+ * Since: v0.1.0
*/
int
virInitialize(void)
@@ -797,6 +799,8 @@ 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.3
*/
int
virGetVersion(unsigned long *libVer, const char *type G_GNUC_UNUSED,
@@ -1185,6 +1189,8 @@ virConnectOpenInternal(const char *name,
* is no longer needed.
*
* Returns a pointer to the hypervisor connection or NULL in case of error
+ *
+ * Since: v0.0.3
*/
virConnectPtr
virConnectOpen(const char *name)
@@ -1218,6 +1224,8 @@ 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.3
*/
virConnectPtr
virConnectOpenReadOnly(const char *name)
@@ -1252,6 +1260,8 @@ 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.0
*/
virConnectPtr
virConnectOpenAuth(const char *name,
@@ -1300,6 +1310,8 @@ 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.3
*/
int
virConnectClose(virConnectPtr conn)
diff --git a/src/util/virerror.c b/src/util/virerror.c
index e864a50fba..ea320ebbf1 100644
--- a/src/util/virerror.c
+++ b/src/util/virerror.c
@@ -254,6 +254,8 @@ 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 +273,8 @@ 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 +293,8 @@ 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 +313,8 @@ virGetLastErrorDomain(void)
*
* Returns the most recent error message string in this
* thread, or a generic message if none is set
+ *
+ * Since: v1.0.6
*/
const char *
virGetLastErrorMessage(void)
@@ -361,6 +369,8 @@ 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 +402,8 @@ 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 +467,8 @@ 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 +487,8 @@ virResetError(virErrorPtr err)
* @err: error to free
*
* Resets and frees the given error.
+ *
+ * Since: v0.6.1
*/
void
virFreeError(virErrorPtr err)
@@ -489,6 +505,8 @@ 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 +537,8 @@ 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 +573,8 @@ 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 +601,8 @@ 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 +622,8 @@ 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 +641,8 @@ 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 +661,8 @@ 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..6add093216 100644
--- a/src/util/virevent.c
+++ b/src/util/virevent.c
@@ -69,6 +69,8 @@ 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 +96,8 @@ virEventAddHandle(int fd,
* virEventRegisterImpl() or virEventRegisterDefaultImpl().
*
* Will not fail if fd exists.
+ *
+ * Since: v0.9.3
*/
void
virEventUpdateHandle(int watch, int events)
@@ -112,6 +116,8 @@ 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 +145,8 @@ 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 +174,8 @@ 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 +194,8 @@ 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 +244,8 @@ 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 +314,8 @@ int virEventRequireImpl(void)
* virEventAddHandle() or virConnectDomainEventRegisterAny().
*
* Returns 0 on success, -1 on failure.
+ *
+ * Since: v0.9.0
*/
int virEventRegisterDefaultImpl(void)
{
@@ -335,6 +351,8 @@ 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