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