[PATCH v2 11/34] docs: generated: functions: libvirt: append 'Since version' metadata

Signed-off-by: Victor Toso <victortoso(a)redhat.com&gt; --- 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 | 554 +++++++++++++++++++++++++++++- src/libvirt-host.c | 102 ++++++ src/libvirt-interface.c | 63 ++++ src/libvirt-network.c | 123 +++++++ src/libvirt-nodedev.c | 81 +++++ src/libvirt-nwfilter.c | 63 ++++ src/libvirt-secret.c | 60 ++++ src/libvirt-storage.c | 168 +++++++++ src/libvirt-stream.c | 51 +++ src/libvirt.c | 18 + src/util/virerror.c | 45 +++ src/util/virevent.c | 27 ++ 23 files changed, 1603 insertions(+), 1 deletion(-) diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h index 912ed26a56..8d04a0b989 100644 --- a/include/libvirt/libvirt-domain.h +++ b/include/libvirt/libvirt-domain.h @@ -4126,6 +4126,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: v1.0.0 + * */ typedef int (*virConnectDomainEventCallback)(virConnectPtr conn, virDomainPtr dom, @@ -4712,6 +4715,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: v1.0.0 + * */ typedef void (*virConnectDomainEventGenericCallback)(virConnectPtr conn, virDomainPtr dom, @@ -4726,6 +4732,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: v1.0.0 + * */ typedef void (*virConnectDomainEventRTCChangeCallback)(virConnectPtr conn, virDomainPtr dom, @@ -4764,6 +4773,9 @@ typedef enum { * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_WATCHDOG with virConnectDomainEventRegisterAny() * + * Since: v1.0.0 + * + * */ typedef void (*virConnectDomainEventWatchdogCallback)(virConnectPtr conn, virDomainPtr dom, @@ -4800,6 +4812,9 @@ typedef enum { * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_IO_ERROR with virConnectDomainEventRegisterAny() + * + * Since: v1.0.0 + * */ typedef void (*virConnectDomainEventIOErrorCallback)(virConnectPtr conn, virDomainPtr dom, @@ -4827,6 +4842,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: v1.0.0 + * + * */ typedef void (*virConnectDomainEventIOErrorReasonCallback)(virConnectPtr conn, virDomainPtr dom, @@ -4980,6 +4998,9 @@ typedef virDomainEventGraphicsSubject *virDomainEventGraphicsSubjectPtr; * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_GRAPHICS with virConnectDomainEventRegisterAny() + * + * Since: v1.0.0 + * */ typedef void (*virConnectDomainEventGraphicsCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5033,6 +5054,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: v1.0.0 + * */ typedef void (*virConnectDomainEventBlockJobCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5087,6 +5111,9 @@ typedef enum { * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_DISK_CHANGE with virConnectDomainEventRegisterAny() + * + * Since: v1.0.0 + * */ typedef void (*virConnectDomainEventDiskChangeCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5125,6 +5152,9 @@ typedef enum { * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_TRAY_CHANGE with virConnectDomainEventRegisterAny() + * + * Since: v1.0.0 + * */ typedef void (*virConnectDomainEventTrayChangeCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5144,6 +5174,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: v1.0.0 + * */ typedef void (*virConnectDomainEventPMWakeupCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5162,6 +5195,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: v1.0.0 + * */ typedef void (*virConnectDomainEventPMSuspendCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5178,6 +5214,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: v1.0.0 + * */ typedef void (*virConnectDomainEventBalloonChangeCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5196,6 +5235,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, @@ -5213,6 +5255,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, @@ -5230,6 +5275,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, @@ -5249,6 +5297,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, @@ -5267,6 +5318,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, @@ -5290,6 +5344,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, @@ -5314,6 +5371,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, @@ -5712,6 +5772,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, @@ -5764,6 +5827,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, @@ -5793,6 +5859,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, @@ -5818,6 +5887,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, @@ -5842,6 +5914,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 a5c73dda2a..078439f3d6 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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.0 + * */ typedef int (*virEventRemoveTimeoutFunc)(int timer); diff --git a/include/libvirt/libvirt-host.h b/include/libvirt/libvirt-host.h index a11bfb5f95..d366cc903e 100644 --- a/include/libvirt/libvirt-host.h +++ b/include/libvirt/libvirt-host.h @@ -700,6 +700,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: v1.0.0 + * */ typedef int (*virConnectAuthCallbackPtr)(virConnectCredentialPtr cred, unsigned int ncred, @@ -901,6 +904,9 @@ int virConnectSetKeepAlive(virConnectPtr conn, * * A callback function to be registered, and called when the connection * is closed. + * + * Since: v1.0.0 + * */ typedef void (*virConnectCloseFunc)(virConnectPtr conn, int reason, diff --git a/include/libvirt/libvirt-network.h b/include/libvirt/libvirt-network.h index ab8b34ae1c..0457771fb7 100644 --- a/include/libvirt/libvirt-network.h +++ b/include/libvirt/libvirt-network.h @@ -296,6 +296,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, @@ -390,6 +393,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 a19821bb75..4d05237cbe 100644 --- a/include/libvirt/libvirt-nodedev.h +++ b/include/libvirt/libvirt-nodedev.h @@ -207,6 +207,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, @@ -257,6 +260,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 9f4f60dcaa..1f0fc41c0c 100644 --- a/include/libvirt/libvirt-secret.h +++ b/include/libvirt/libvirt-secret.h @@ -173,6 +173,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, @@ -221,6 +224,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 c86b1439b6..8f0352237c 100644 --- a/include/libvirt/libvirt-storage.h +++ b/include/libvirt/libvirt-storage.h @@ -536,6 +536,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, @@ -588,6 +591,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 5feb66ac35..1850b06684 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ typedef void (*virStreamEventCallback)(virStreamPtr stream, int events, void *opaque); diff --git a/include/libvirt/virterror.h b/include/libvirt/virterror.h index 4feaffd1e3..76b20e410c 100644 --- a/include/libvirt/virterror.h +++ b/include/libvirt/virterror.h @@ -359,6 +359,9 @@ typedef enum { * @error: the error being raised. * * Signature of a function to use when there is an error raised by the library. + * + * Since: v1.0.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..f91111e283 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: v1.0.0 + * */ const char * virDomainSnapshotGetName(virDomainSnapshotPtr snapshot) @@ -58,6 +61,9 @@ virDomainSnapshotGetName(virDomainSnapshotPtr snapshot) * call. * * Returns the domain or NULL. + * + * Since: v1.0.0 + * */ virDomainPtr virDomainSnapshotGetDomain(virDomainSnapshotPtr snapshot) @@ -81,6 +87,9 @@ virDomainSnapshotGetDomain(virDomainSnapshotPtr snapshot) * call. * * Returns the connection or NULL. + * + * Since: v1.0.0 + * */ virConnectPtr virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot) @@ -213,6 +222,9 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot) * * Returns an (opaque) new virDomainSnapshotPtr on success or NULL on * failure. + * + * Since: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.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: v1.0.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: v1.0.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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.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: v1.0.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: v1.0.0 + * */ 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: v1.0.0 + * */ int virDomainSnapshotFree(virDomainSnapshotPtr snapshot) diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index cbd7902d2d..b9c0a65cfa 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: v1.0.0 + * */ 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: v1.0.0 + * */ int virConnectNumOfDomains(virConnectPtr conn) @@ -115,6 +121,9 @@ virConnectNumOfDomains(virConnectPtr conn) * call. * * Returns the virConnectPtr or NULL in case of failure. + * + * Since: v1.0.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: v1.0.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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ virDomainPtr virDomainLookupByUUID(virConnectPtr conn, const unsigned char *uuid) @@ -422,6 +446,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: v1.0.0 + * */ virDomainPtr virDomainLookupByName(virConnectPtr conn, const char *name) @@ -472,6 +499,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: v1.0.0 + * */ int virDomainDestroy(virDomainPtr domain) @@ -537,6 +567,9 @@ virDomainDestroy(virDomainPtr domain) * * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainDestroyFlags(virDomainPtr domain, @@ -577,6 +610,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: v1.0.0 + * */ int virDomainFree(virDomainPtr domain) @@ -608,6 +644,9 @@ virDomainFree(virDomainPtr domain) * the reference count. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainRef(virDomainPtr domain) @@ -636,6 +675,9 @@ virDomainRef(virDomainPtr domain) * special state like VIR_DOMAIN_PMSUSPENDED. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainSuspend(virDomainPtr domain) @@ -678,6 +720,9 @@ virDomainSuspend(virDomainPtr domain) * special state like VIR_DOMAIN_PMSUSPENDED. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainResume(virDomainPtr domain) @@ -734,6 +779,9 @@ virDomainResume(virDomainPtr domain) * * Returns: 0 on success, * -1 on failure. + * + * Since: v1.0.0 + * */ int virDomainPMSuspendForDuration(virDomainPtr dom, @@ -781,6 +829,9 @@ virDomainPMSuspendForDuration(virDomainPtr dom, * * Returns: 0 on success, * -1 on failure. + * + * Since: v1.0.0 + * */ int virDomainPMWakeup(virDomainPtr dom, @@ -828,6 +879,9 @@ virDomainPMWakeup(virDomainPtr dom, * and virDomainSaveImageDefineXML(). * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainSave(virDomainPtr domain, const char *to) @@ -910,6 +964,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: v1.0.0 + * */ int virDomainSaveFlags(virDomainPtr domain, const char *to, @@ -970,6 +1027,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: v1.0.0 + * */ int virDomainRestore(virConnectPtr conn, const char *from) @@ -1042,6 +1102,9 @@ virDomainRestore(virConnectPtr conn, const char *from) * pristine template. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainRestoreFlags(virConnectPtr conn, const char *from, const char *dxml, @@ -1104,6 +1167,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: v1.0.0 + * */ char * virDomainSaveImageGetXMLDesc(virConnectPtr conn, const char *file, @@ -1172,6 +1238,9 @@ virDomainSaveImageGetXMLDesc(virConnectPtr conn, const char *file, * exclusive. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainSaveImageDefineXML(virConnectPtr conn, const char *file, @@ -1246,6 +1315,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: v1.0.0 + * */ int virDomainCoreDump(virDomainPtr domain, const char *to, unsigned int flags) @@ -1322,6 +1394,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 +1476,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: v1.0.0 + * */ char * virDomainScreenshot(virDomainPtr domain, @@ -1460,6 +1538,9 @@ virDomainScreenshot(virDomainPtr domain, * be deleted when the domain quits. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainShutdown(virDomainPtr domain) @@ -1520,6 +1601,9 @@ virDomainShutdown(virDomainPtr domain) * must have <channel> configured. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainShutdownFlags(virDomainPtr domain, unsigned int flags) @@ -1578,6 +1662,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: v1.0.0 + * */ int virDomainReboot(virDomainPtr domain, unsigned int flags) @@ -1622,6 +1709,9 @@ virDomainReboot(virDomainPtr domain, unsigned int flags) * guest OS shutdown. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainReset(virDomainPtr domain, unsigned int flags) @@ -1661,6 +1751,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: v1.0.0 + * */ const char * virDomainGetName(virDomainPtr domain) @@ -1683,6 +1776,9 @@ virDomainGetName(virDomainPtr domain) * Get the UUID for a domain * * Returns -1 in case of error, 0 in case of success + * + * Since: v1.0.0 + * */ int virDomainGetUUID(virDomainPtr domain, unsigned char *uuid) @@ -1713,6 +1809,9 @@ virDomainGetUUID(virDomainPtr domain, unsigned char *uuid) * UUID see RFC4122. * * Returns -1 in case of error, 0 in case of success + * + * Since: v1.0.0 + * */ int virDomainGetUUIDString(virDomainPtr domain, char *buf) @@ -1740,6 +1839,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: v1.0.0 + * */ unsigned int virDomainGetID(virDomainPtr domain) @@ -1762,6 +1864,9 @@ virDomainGetID(virDomainPtr domain) * * Returns the new string or NULL in case of error, the string must be * freed by the caller. + * + * Since: v1.0.0 + * */ char * virDomainGetOSType(virDomainPtr domain) @@ -1801,6 +1906,9 @@ virDomainGetOSType(virDomainPtr domain) * * Returns the memory size in kibibytes (blocks of 1024 bytes), or 0 in * case of error. + * + * Since: v1.0.0 + * */ unsigned long virDomainGetMaxMemory(virDomainPtr domain) @@ -1850,6 +1958,9 @@ virDomainGetMaxMemory(virDomainPtr domain) * virDomainSetMemoryFlags(). * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainSetMaxMemory(virDomainPtr domain, unsigned long memory) @@ -1903,6 +2014,9 @@ virDomainSetMaxMemory(virDomainPtr domain, unsigned long memory) * virDomainSetMemoryFlags(). * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainSetMemory(virDomainPtr domain, unsigned long memory) @@ -1965,6 +2079,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: v1.0.0 + * */ int virDomainSetMemoryFlags(virDomainPtr domain, unsigned long memory, @@ -2025,6 +2142,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 +2195,9 @@ virDomainSetMemoryStatsPeriod(virDomainPtr domain, int period, * VIR_DOMAIN_MEMORY_PARAM_UNLIMITED. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v1.0.0 + * */ int virDomainSetMemoryParameters(virDomainPtr domain, @@ -2149,6 +2272,9 @@ virDomainSetMemoryParameters(virDomainPtr domain, * expects the caller to allocate the @params. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v1.0.0 + * */ int virDomainGetMemoryParameters(virDomainPtr domain, @@ -2216,6 +2342,9 @@ virDomainGetMemoryParameters(virDomainPtr domain, * Changing persistent configuration does not pose such limitations. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v1.0.0 + * */ int virDomainSetNumaParameters(virDomainPtr domain, @@ -2281,6 +2410,9 @@ virDomainSetNumaParameters(virDomainPtr domain, * expects the caller to allocate the @params. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v1.0.0 + * */ int virDomainGetNumaParameters(virDomainPtr domain, @@ -2338,6 +2470,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: v1.0.0 + * */ int virDomainSetBlkioParameters(virDomainPtr domain, @@ -2403,6 +2538,9 @@ virDomainSetBlkioParameters(virDomainPtr domain, * expects the caller to allocate the @params. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v1.0.0 + * */ int virDomainGetBlkioParameters(virDomainPtr domain, @@ -2461,6 +2599,9 @@ virDomainGetBlkioParameters(virDomainPtr domain, * can be extracted. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainGetInfo(virDomainPtr domain, virDomainInfoPtr info) @@ -2507,6 +2648,9 @@ virDomainGetInfo(virDomainPtr domain, virDomainInfoPtr info) * which led to the state. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainGetState(virDomainPtr domain, @@ -2550,6 +2694,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: v1.0.0 + * */ int virDomainGetControlInfo(virDomainPtr domain, @@ -2611,6 +2758,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: v1.0.0 + * */ char * virDomainGetXMLDesc(virDomainPtr domain, unsigned int flags) @@ -2660,6 +2810,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: v1.0.0 + * */ char * virConnectDomainXMLFromNative(virConnectPtr conn, @@ -2710,6 +2863,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: v1.0.0 + * */ char * virConnectDomainXMLToNative(virConnectPtr conn, @@ -3563,6 +3719,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: v1.0.0 + * */ virDomainPtr virDomainMigrate(virDomainPtr domain, @@ -3759,6 +3918,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: v1.0.0 + * */ virDomainPtr virDomainMigrate2(virDomainPtr domain, @@ -3968,6 +4130,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 +4421,9 @@ int virDomainMigrateUnmanagedCheckCompat(virDomainPtr domain, * corresponds to VIR_MIGRATE_PARAM_URI of virDomainMigrateToURI3. * * Returns 0 if the migration succeeded, -1 upon error. + * + * Since: v1.0.0 + * */ int virDomainMigrateToURI(virDomainPtr domain, @@ -4332,6 +4500,9 @@ virDomainMigrateToURI(virDomainPtr domain, * virDomainMigrateToURI3. * * Returns 0 if the migration succeeded, -1 upon error. + * + * Since: v1.0.0 + * */ int virDomainMigrateToURI2(virDomainPtr domain, @@ -4412,6 +4583,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 +5455,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: v1.0.0 + * */ char * virDomainGetSchedulerType(virDomainPtr domain, int *nparams) @@ -5329,6 +5506,9 @@ virDomainGetSchedulerType(virDomainPtr domain, int *nparams) * virDomainGetSchedulerParametersFlags(). * * Returns -1 in case of error, 0 in case of success. + * + * Since: v1.0.0 + * */ int virDomainGetSchedulerParameters(virDomainPtr domain, @@ -5394,6 +5574,9 @@ virDomainGetSchedulerParameters(virDomainPtr domain, * } * * Returns -1 in case of error, 0 in case of success. + * + * Since: v1.0.0 + * */ int virDomainGetSchedulerParametersFlags(virDomainPtr domain, @@ -5458,6 +5641,9 @@ virDomainGetSchedulerParametersFlags(virDomainPtr domain, * virDomainSetSchedulerParametersFlags. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v1.0.0 + * */ int virDomainSetSchedulerParameters(virDomainPtr domain, @@ -5512,6 +5698,9 @@ virDomainSetSchedulerParameters(virDomainPtr domain, * flags are supported. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v1.0.0 + * */ int virDomainSetSchedulerParametersFlags(virDomainPtr domain, @@ -5583,6 +5772,9 @@ virDomainSetSchedulerParametersFlags(virDomainPtr domain, * that particular statistic. * * Returns: 0 in case of success or -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainBlockStats(virDomainPtr dom, const char *disk, @@ -5660,6 +5852,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: v1.0.0 + * */ int virDomainBlockStatsFlags(virDomainPtr dom, @@ -5729,6 +5924,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: v1.0.0 + * */ int virDomainInterfaceStats(virDomainPtr dom, const char *device, @@ -5789,6 +5987,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: v1.0.0 + * */ int virDomainSetInterfaceParameters(virDomainPtr domain, @@ -5857,6 +6058,9 @@ virDomainSetInterfaceParameters(virDomainPtr domain, * expects the caller to allocate the @params. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v1.0.0 + * */ int virDomainGetInterfaceParameters(virDomainPtr domain, @@ -5947,6 +6151,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: v1.0.0 + * */ int virDomainMemoryStats(virDomainPtr dom, virDomainMemoryStatPtr stats, @@ -6026,6 +6233,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: v1.0.0 + * */ int virDomainBlockPeek(virDomainPtr dom, @@ -6095,6 +6305,9 @@ virDomainBlockPeek(virDomainPtr dom, * hypervisor. * * Returns: 0 in case of success or -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainBlockResize(virDomainPtr dom, @@ -6163,6 +6376,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: v1.0.0 + * */ int virDomainMemoryPeek(virDomainPtr dom, @@ -6299,6 +6515,9 @@ virDomainMemoryPeek(virDomainPtr dom, * ... * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainGetBlockInfo(virDomainPtr domain, const char *disk, @@ -6349,6 +6568,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: v1.0.0 + * */ virDomainPtr virDomainDefineXML(virConnectPtr conn, const char *xml) @@ -6392,6 +6614,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 +6660,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: v1.0.0 + * */ int virDomainUndefine(virDomainPtr domain) @@ -6504,6 +6732,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: v1.0.0 + * */ int virDomainUndefineFlags(virDomainPtr domain, @@ -6543,6 +6774,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: v1.0.0 + * */ int virConnectNumOfDefinedDomains(virConnectPtr conn) @@ -6586,6 +6820,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: v1.0.0 + * */ int virConnectListDefinedDomains(virConnectPtr conn, char **const names, @@ -6685,6 +6922,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: v1.0.0 + * */ int virConnectListAllDomains(virConnectPtr conn, @@ -6726,6 +6966,9 @@ virConnectListAllDomains(virConnectPtr conn, * control, see virDomainCreateWithFlags(). * * Returns 0 in case of success, -1 in case of error + * + * Since: v1.0.0 + * */ int virDomainCreate(virDomainPtr domain) @@ -6794,6 +7037,9 @@ virDomainCreate(virDomainPtr domain) * pristine template. * * Returns 0 in case of success, -1 in case of error + * + * Since: v1.0.0 + * */ int virDomainCreateWithFlags(virDomainPtr domain, unsigned int flags) @@ -6870,6 +7116,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 +7176,9 @@ virDomainCreateWithFiles(virDomainPtr domain, unsigned int nfiles, * machine boots. * * Returns -1 in case of error, 0 in case of success + * + * Since: v1.0.0 + * */ int virDomainGetAutostart(virDomainPtr domain, @@ -6968,6 +7220,9 @@ virDomainGetAutostart(virDomainPtr domain, * when the host machine boots. * * Returns -1 in case of error, 0 in case of success + * + * Since: v1.0.0 + * */ int virDomainSetAutostart(virDomainPtr domain, @@ -7008,6 +7263,9 @@ virDomainSetAutostart(virDomainPtr domain, * Send NMI to the guest * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainInjectNMI(virDomainPtr domain, unsigned int flags) @@ -7050,6 +7308,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: v1.0.0 + * */ int virDomainSendKey(virDomainPtr domain, @@ -7135,6 +7396,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 +7456,9 @@ virDomainSendProcessSignal(virDomainPtr domain, * use virDomainSetVcpusFlags(). * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainSetVcpus(virDomainPtr domain, unsigned int nvcpus) @@ -7263,6 +7530,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: v1.0.0 + * */ int virDomainSetVcpusFlags(virDomainPtr domain, unsigned int nvcpus, @@ -7332,6 +7602,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: v1.0.0 + * */ int virDomainGetVcpusFlags(virDomainPtr domain, unsigned int flags) @@ -7388,6 +7661,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: v1.0.0 + * */ int virDomainPinVcpu(virDomainPtr domain, unsigned int vcpu, @@ -7455,6 +7731,9 @@ virDomainPinVcpu(virDomainPtr domain, unsigned int vcpu, * * Returns 0 in case of success, -1 in case of failure. * + * Since: v1.0.0 + * + * */ int virDomainPinVcpuFlags(virDomainPtr domain, unsigned int vcpu, @@ -7513,6 +7792,9 @@ virDomainPinVcpuFlags(virDomainPtr domain, unsigned int vcpu, * * Returns the number of virtual CPUs in case of success, * -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainGetVcpuPinInfo(virDomainPtr domain, int ncpumaps, @@ -7590,6 +7872,9 @@ virDomainGetVcpuPinInfo(virDomainPtr domain, int ncpumaps, * * Returns 0 in case of success, -1 in case of failure. * + * Since: v1.0.0 + * + * */ int virDomainPinEmulator(virDomainPtr domain, unsigned char *cpumap, @@ -7645,6 +7930,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: v1.0.0 + * */ int virDomainGetEmulatorPinInfo(virDomainPtr domain, unsigned char *cpumap, @@ -7710,6 +7998,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: v1.0.0 + * */ int virDomainGetVcpus(virDomainPtr domain, virVcpuInfoPtr info, int maxinfo, @@ -7769,6 +8060,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: v1.0.0 + * */ int virDomainGetMaxVcpus(virDomainPtr domain) @@ -7813,6 +8107,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 +8149,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 +8195,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 +8262,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 +8324,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 +8388,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 +8444,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: v1.0.0 + * */ int virDomainGetSecurityLabel(virDomainPtr domain, virSecurityLabelPtr seclabel) @@ -8174,6 +8489,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: v1.0.0 + * */ int virDomainGetSecurityLabelList(virDomainPtr domain, @@ -8236,6 +8554,9 @@ virDomainGetSecurityLabelList(virDomainPtr domain, * or both will be modified. * * Returns 0 on success, -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainSetMetadata(virDomainPtr domain, @@ -8321,6 +8642,9 @@ virDomainSetMetadata(virDomainPtr domain, * * Returns the metadata string on success (caller must free), * or NULL in case of failure. + * + * Since: v1.0.0 + * */ char * virDomainGetMetadata(virDomainPtr domain, @@ -8388,6 +8712,9 @@ virDomainGetMetadata(virDomainPtr domain, * persistent domain definition. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainAttachDevice(virDomainPtr domain, const char *xml) @@ -8447,6 +8774,9 @@ virDomainAttachDevice(virDomainPtr domain, const char *xml) * persistent domain definition. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainAttachDeviceFlags(virDomainPtr domain, @@ -8491,6 +8821,9 @@ virDomainAttachDeviceFlags(virDomainPtr domain, * See virDomainDetachDeviceFlags() for more details. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainDetachDevice(virDomainPtr domain, const char *xml) @@ -8573,6 +8906,9 @@ virDomainDetachDevice(virDomainPtr domain, const char *xml) * may lead to unexpected results. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainDetachDeviceFlags(virDomainPtr domain, @@ -8637,6 +8973,9 @@ virDomainDetachDeviceFlags(virDomainPtr domain, * domain XML with only the disk path changed. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainUpdateDeviceFlags(virDomainPtr domain, @@ -8691,6 +9030,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 +9093,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: v1.0.0 + * */ int virConnectDomainEventRegister(virConnectPtr conn, @@ -8794,6 +9139,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: v1.0.0 + * */ int virConnectDomainEventDeregister(virConnectPtr conn, @@ -8828,6 +9176,9 @@ virConnectDomainEventDeregister(virConnectPtr conn, * Determine if the domain is currently running * * Returns 1 if running, 0 if inactive, -1 on error + * + * Since: v1.0.0 + * */ int virDomainIsActive(virDomainPtr dom) @@ -8861,6 +9212,9 @@ virDomainIsActive(virDomainPtr dom) * which means it will still exist after shutting down * * Returns 1 if persistent, 0 if transient, -1 on error + * + * Since: v1.0.0 + * */ int virDomainIsPersistent(virDomainPtr dom) @@ -8901,6 +9255,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 +9291,9 @@ virDomainRename(virDomainPtr dom, * Determine if the domain has been updated. * * Returns 1 if updated, 0 if not, -1 on error + * + * Since: v1.0.0 + * */ int virDomainIsUpdated(virDomainPtr dom) @@ -8971,6 +9331,9 @@ virDomainIsUpdated(virDomainPtr dom) * to virDomainGetJobStats(). * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainGetJobInfo(virDomainPtr domain, virDomainJobInfoPtr info) @@ -9035,6 +9398,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 +9453,9 @@ virDomainGetJobStats(virDomainPtr domain, * for more details). * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virDomainAbortJob(virDomainPtr domain) @@ -9129,6 +9498,9 @@ virDomainAbortJob(virDomainPtr domain) * being live-migrated as a reaction to migration progress. * * Returns 0 in case of success, -1 otherwise. + * + * Since: v1.0.0 + * */ int virDomainMigrateSetMaxDowntime(virDomainPtr domain, @@ -9170,6 +9542,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 +9585,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 +9632,9 @@ virDomainMigrateGetCompressionCache(virDomainPtr domain, * virDomainGetJobStats. * * Returns 0 in case of success, -1 otherwise. + * + * Since: v1.0.3 + * */ int virDomainMigrateSetCompressionCache(virDomainPtr domain, @@ -9298,6 +9679,9 @@ virDomainMigrateSetCompressionCache(virDomainPtr domain, * phase of the migration. * * Returns 0 in case of success, -1 otherwise. + * + * Since: v1.0.0 + * */ int virDomainMigrateSetMaxSpeed(virDomainPtr domain, @@ -9341,6 +9725,9 @@ virDomainMigrateSetMaxSpeed(virDomainPtr domain, * migration. * * Returns 0 in case of success, -1 otherwise. + * + * Since: v1.0.0 + * */ int virDomainMigrateGetMaxSpeed(virDomainPtr domain, @@ -9434,6 +9821,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 +9887,9 @@ virDomainMigrateStartPostCopy(virDomainPtr domain, * be passed to the virConnectDomainEventDeregisterAny() method. * * Returns a callback identifier on success, -1 on failure. + * + * Since: v1.0.0 + * */ int virConnectDomainEventRegisterAny(virConnectPtr conn, @@ -9555,7 +9948,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: v1.0.0 + * */ int virConnectDomainEventDeregisterAny(virConnectPtr conn, int callbackID) @@ -9610,6 +10006,9 @@ virConnectDomainEventDeregisterAny(virConnectPtr conn, * flags are mutually exclusive. * * Returns 0 in case of success or -1 in case of failure + * + * Since: v1.0.0 + * */ int virDomainManagedSave(virDomainPtr dom, unsigned int flags) @@ -9657,6 +10056,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: v1.0.0 + * */ int virDomainHasManagedSaveImage(virDomainPtr dom, unsigned int flags) @@ -9695,6 +10097,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: v1.0.0 + * */ int virDomainManagedSaveRemove(virDomainPtr dom, unsigned int flags) @@ -9741,6 +10146,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 +10207,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 +10275,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: v1.0.0 + * */ int virDomainOpenConsole(virDomainPtr dom, @@ -9928,6 +10342,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 +10402,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 +10455,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 +10541,9 @@ int virDomainSetPerfEvents(virDomainPtr domain, * beginning of the first phase. * * Returns -1 in case of failure, 0 when successful. + * + * Since: v1.0.0 + * */ int virDomainBlockJobAbort(virDomainPtr dom, const char *disk, @@ -10195,6 +10621,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: v1.0.0 + * */ int virDomainGetBlockJobInfo(virDomainPtr dom, const char *disk, @@ -10258,6 +10687,9 @@ virDomainGetBlockJobInfo(virDomainPtr dom, const char *disk, * elements within //domain/devices/disk. * * Returns -1 in case of failure, 0 when successful. + * + * Since: v1.0.0 + * */ int virDomainBlockJobSetSpeed(virDomainPtr dom, const char *disk, @@ -10332,6 +10764,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: v1.0.0 + * */ int virDomainBlockPull(virDomainPtr dom, const char *disk, @@ -10476,6 +10911,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: v1.0.0 + * */ int virDomainBlockRebase(virDomainPtr dom, const char *disk, @@ -10606,6 +11044,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 +11193,9 @@ virDomainBlockCopy(virDomainPtr dom, const char *disk, * virDomainGetBlockJobInfo(). * * Returns 0 if the operation has started, -1 on failure. + * + * Since: v1.0.0 + * */ int virDomainBlockCommit(virDomainPtr dom, const char *disk, @@ -10811,6 +11255,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: v1.0.0 + * */ int virDomainOpenGraphics(virDomainPtr dom, @@ -10891,6 +11338,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 +11402,9 @@ virDomainOpenGraphicsFD(virDomainPtr dom, * within //domain/devices/disk. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v1.0.0 + * */ int virDomainSetBlockIoTune(virDomainPtr dom, @@ -11027,6 +11480,9 @@ virDomainSetBlockIoTune(virDomainPtr dom, * unless @nparams is 0 on input. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v1.0.0 + * */ int virDomainGetBlockIoTune(virDomainPtr dom, @@ -11156,6 +11612,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: v1.0.0 + * */ int virDomainGetCPUStats(virDomainPtr domain, @@ -11256,6 +11715,9 @@ virDomainGetCPUStats(virDomainPtr domain, * * Returns number of disks with errors filled in the @errors array or -1 on * error. + * + * Since: v1.0.0 + * */ int virDomainGetDiskErrors(virDomainPtr dom, @@ -11301,6 +11763,9 @@ virDomainGetDiskErrors(virDomainPtr dom, * * Returns the hostname which must be freed by the caller, or * NULL if there was an error. + * + * Since: v1.0.0 + * */ char * virDomainGetHostname(virDomainPtr domain, unsigned int flags) @@ -11350,6 +11815,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 +11862,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 +11908,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 +11956,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 +12009,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 +12058,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 +12111,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 +12520,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 +12602,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 +12672,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 +12707,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 +12745,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 +12840,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 +12884,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 +12930,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 +12991,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 +13043,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 +13198,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 +13275,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 +13327,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 +13385,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 +13454,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 +13514,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 +13613,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 +13666,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 +13718,9 @@ virDomainBackupGetXMLDesc(virDomainPtr domain, * * Returns: number of keys stored in @keys, * -1 otherwise. + * + * Since: v6.10.0 + * */ int virDomainAuthorizedSSHKeysGet(virDomainPtr domain, @@ -13246,6 +13789,9 @@ virDomainAuthorizedSSHKeysGet(virDomainPtr domain, * * Returns: 0 on success, * -1 otherwise. + * + * Since: v6.10.0 + * */ int virDomainAuthorizedSSHKeysSet(virDomainPtr domain, @@ -13314,6 +13860,9 @@ virDomainAuthorizedSSHKeysSet(virDomainPtr domain, * * Returns: number of messages stored in @msgs, * -1 otherwise. + * + * Since: v7.1.0 + * */ int virDomainGetMessages(virDomainPtr domain, @@ -13356,6 +13905,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..acdc489ae3 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: v1.0.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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.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: v1.0.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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ int virConnectIsAlive(virConnectPtr conn) @@ -1434,6 +1518,9 @@ virConnectIsAlive(virConnectPtr conn) * context. * * Returns 0 on success, -1 on error + * + * Since: v1.0.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: v1.0.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..240530fc13 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.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: v1.0.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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ int virInterfaceIsActive(virInterfacePtr iface) diff --git a/src/libvirt-network.c b/src/libvirt-network.c index 883dd40f6b..eae005e91f 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: v1.0.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: v1.0.0 + * */ 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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.0 + * */ virNetworkPtr virNetworkCreateXML(virConnectPtr conn, const char *xmlDesc) @@ -480,6 +510,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: v1.0.0 + * */ virNetworkPtr virNetworkDefineXML(virConnectPtr conn, const char *xml) @@ -556,6 +589,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: v1.0.0 + * */ int virNetworkUndefine(virNetworkPtr network) @@ -670,6 +706,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: v1.0.0 + * */ int virNetworkCreate(virNetworkPtr network) @@ -710,6 +749,9 @@ virNetworkCreate(virNetworkPtr network) * This function may require privileged access * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.0 + * */ int virNetworkDestroy(virNetworkPtr network) @@ -748,6 +790,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: v1.0.0 + * */ int virNetworkFree(virNetworkPtr network) @@ -779,6 +824,9 @@ virNetworkFree(virNetworkPtr network) * the reference count. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.0.0 + * */ int virNetworkRef(virNetworkPtr network) @@ -802,6 +850,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: v1.0.0 + * */ const char * virNetworkGetName(virNetworkPtr network) @@ -824,6 +875,9 @@ virNetworkGetName(virNetworkPtr network) * Get the UUID for a network * * Returns -1 in case of error, 0 in case of success + * + * Since: v1.0.0 + * */ int virNetworkGetUUID(virNetworkPtr network, unsigned char *uuid) @@ -854,6 +908,9 @@ virNetworkGetUUID(virNetworkPtr network, unsigned char *uuid) * UUID see RFC4122. * * Returns -1 in case of error, 0 in case of success + * + * Since: v1.0.0 + * */ int virNetworkGetUUIDString(virNetworkPtr network, char *buf) @@ -889,6 +946,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: v1.0.0 + * */ char * virNetworkGetXMLDesc(virNetworkPtr network, unsigned int flags) @@ -926,6 +986,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: v1.0.0 + * */ char * virNetworkGetBridgeName(virNetworkPtr network) @@ -964,6 +1027,9 @@ virNetworkGetBridgeName(virNetworkPtr network) * machine boots. * * Returns -1 in case of error, 0 in case of success + * + * Since: v1.0.0 + * */ int virNetworkGetAutostart(virNetworkPtr network, @@ -1004,6 +1070,9 @@ virNetworkGetAutostart(virNetworkPtr network, * when the host machine boots. * * Returns -1 in case of error, 0 in case of success + * + * Since: v1.0.0 + * */ int virNetworkSetAutostart(virNetworkPtr network, @@ -1042,6 +1111,9 @@ virNetworkSetAutostart(virNetworkPtr network, * Determine if the network is currently running * * Returns 1 if running, 0 if inactive, -1 on error + * + * Since: v1.0.0 + * */ int virNetworkIsActive(virNetworkPtr net) @@ -1075,6 +1147,9 @@ virNetworkIsActive(virNetworkPtr net) * which means it will still exist after shutting down * * Returns 1 if persistent, 0 if transient, -1 on error + * + * Since: v1.0.0 + * */ int virNetworkIsPersistent(virNetworkPtr net) @@ -1134,6 +1209,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 +1273,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 +1378,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 +1422,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 +1453,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 +1493,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 +1536,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 +1587,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 +1634,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 +1675,9 @@ virNetworkPortCreateXML(virNetworkPtr net, * call. * * Returns the virNetworkPtr or NULL in case of failure. + * + * Since: v5.5.0 + * */ virNetworkPtr virNetworkPortGetNetwork(virNetworkPortPtr port) @@ -1597,6 +1702,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 +1742,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, @@ -1697,6 +1808,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 +1859,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 +1899,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 +1933,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..b069e32433 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: v1.0.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: v1.0.0 + * */ 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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v7.3.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..1204d2fdbe 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: v1.0.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: v1.0.0 + * */ 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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.0 + * */ virNWFilterPtr virNWFilterDefineXML(virConnectPtr conn, const char *xmlDesc) @@ -459,6 +492,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: v1.0.0 + * */ int virNWFilterUndefine(virNWFilterPtr nwfilter) @@ -499,6 +535,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: v1.0.0 + * */ char * virNWFilterGetXMLDesc(virNWFilterPtr nwfilter, unsigned int flags) @@ -543,6 +582,9 @@ virNWFilterGetXMLDesc(virNWFilterPtr nwfilter, unsigned int flags) * the reference count. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.0.0 + * */ int virNWFilterRef(virNWFilterPtr nwfilter) @@ -620,6 +662,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 +700,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 +726,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 +751,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 +788,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 +832,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) @@ -859,6 +919,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..67909f890f 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: v1.0.0 + * */ virConnectPtr virSecretGetConnect(virSecretPtr secret) @@ -56,6 +59,9 @@ virSecretGetConnect(virSecretPtr secret) * Fetch number of currently defined secrets. * * Returns the number currently defined secrets. + * + * Since: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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..33b7ff8c39 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ virStoragePoolPtr virStoragePoolLookupByUUID(virConnectPtr conn, @@ -477,6 +504,9 @@ virStoragePoolLookupByUUIDString(virConnectPtr conn, * storage pool object is no longer needed. * * Returns a virStoragePoolPtr object, or NULL if no matching pool is found + * + * Since: v1.0.0 + * */ virStoragePoolPtr virStoragePoolLookupByVolume(virStorageVolPtr vol) @@ -516,6 +546,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 +590,9 @@ virStoragePoolLookupByTargetPath(virConnectPtr conn, * storage pool object is no longer needed. * * Returns a virStoragePoolPtr object, or NULL if creation failed + * + * Since: v1.0.0 + * */ virStoragePoolPtr virStoragePoolCreateXML(virConnectPtr conn, @@ -600,6 +636,9 @@ virStoragePoolCreateXML(virConnectPtr conn, * storage pool object is no longer needed. * * Returns a virStoragePoolPtr object, or NULL if creation failed + * + * Since: v1.0.0 + * */ virStoragePoolPtr virStoragePoolDefineXML(virConnectPtr conn, @@ -641,6 +680,9 @@ virStoragePoolDefineXML(virConnectPtr conn, * Build the underlying storage pool * * Returns 0 on success, or -1 upon failure + * + * Since: v1.0.0 + * */ int virStoragePoolBuild(virStoragePoolPtr pool, @@ -679,6 +721,9 @@ virStoragePoolBuild(virStoragePoolPtr pool, * Undefine an inactive storage pool * * Returns 0 on success, -1 on failure + * + * Since: v1.0.0 + * */ int virStoragePoolUndefine(virStoragePoolPtr pool) @@ -717,6 +762,9 @@ virStoragePoolUndefine(virStoragePoolPtr pool) * Starts an inactive storage pool * * Returns 0 on success, or -1 if it could not be started + * + * Since: v1.0.0 + * */ int virStoragePoolCreate(virStoragePoolPtr pool, @@ -759,6 +807,9 @@ virStoragePoolCreate(virStoragePoolPtr pool, * the associated virStoragePoolPtr object. * * Returns 0 on success, or -1 if it could not be destroyed + * + * Since: v1.0.0 + * */ int virStoragePoolDestroy(virStoragePoolPtr pool) @@ -799,6 +850,9 @@ virStoragePoolDestroy(virStoragePoolPtr pool) * itself is not free'd. * * Returns 0 on success, or -1 if it could not be obliterate + * + * Since: v1.0.0 + * */ int virStoragePoolDelete(virStoragePoolPtr pool, @@ -838,6 +892,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: v1.0.0 + * */ int virStoragePoolFree(virStoragePoolPtr pool) @@ -870,6 +927,9 @@ virStoragePoolFree(virStoragePoolPtr pool) * the reference count. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.0.0 + * */ int virStoragePoolRef(virStoragePoolPtr pool) @@ -895,6 +955,9 @@ virStoragePoolRef(virStoragePoolPtr pool) * new devices at the OS layer * * Returns 0 if the volume list was refreshed, -1 on failure + * + * Since: v1.0.0 + * */ int virStoragePoolRefresh(virStoragePoolPtr pool, @@ -933,6 +996,9 @@ virStoragePoolRefresh(virStoragePoolPtr pool, * Fetch the locally unique name of the storage pool * * Returns the name of the pool, or NULL on error + * + * Since: v1.0.0 + * */ const char* virStoragePoolGetName(virStoragePoolPtr pool) @@ -955,6 +1021,9 @@ virStoragePoolGetName(virStoragePoolPtr pool) * Fetch the globally unique ID of the storage pool * * Returns 0 on success, or -1 on error; + * + * Since: v1.0.0 + * */ int virStoragePoolGetUUID(virStoragePoolPtr pool, @@ -985,6 +1054,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: v1.0.0 + * */ int virStoragePoolGetUUIDString(virStoragePoolPtr pool, @@ -1015,6 +1087,9 @@ virStoragePoolGetUUIDString(virStoragePoolPtr pool, * such as free space / usage summary * * Returns 0 on success, or -1 on failure. + * + * Since: v1.0.0 + * */ int virStoragePoolGetInfo(virStoragePoolPtr pool, @@ -1059,6 +1134,9 @@ virStoragePoolGetInfo(virStoragePoolPtr pool, * into the virStoragePoolCreateXML method. * * Returns a XML document (caller frees), or NULL on error + * + * Since: v1.0.0 + * */ char * virStoragePoolGetXMLDesc(virStoragePoolPtr pool, @@ -1097,6 +1175,9 @@ virStoragePoolGetXMLDesc(virStoragePoolPtr pool, * whether the pool is automatically started at boot time * * Returns 0 on success, -1 on failure + * + * Since: v1.0.0 + * */ int virStoragePoolGetAutostart(virStoragePoolPtr pool, @@ -1137,6 +1218,9 @@ virStoragePoolGetAutostart(virStoragePoolPtr pool, * when the host machine boots. * * Returns 0 on success, -1 on failure + * + * Since: v1.0.0 + * */ int virStoragePoolSetAutostart(virStoragePoolPtr pool, @@ -1185,6 +1269,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: v1.0.0 + * */ int virStoragePoolListAllVolumes(virStoragePoolPtr pool, @@ -1221,6 +1308,9 @@ virStoragePoolListAllVolumes(virStoragePoolPtr pool, * Fetch the number of storage volumes within a pool * * Returns the number of storage pools, or -1 on failure + * + * Since: v1.0.0 + * */ int virStoragePoolNumOfVolumes(virStoragePoolPtr pool) @@ -1260,6 +1350,9 @@ virStoragePoolNumOfVolumes(virStoragePoolPtr pool) * virStoragePoolListAllVolumes(). * * Returns the number of names fetched, or -1 on error + * + * Since: v1.0.0 + * */ int virStoragePoolListVolumes(virStoragePoolPtr pool, @@ -1299,6 +1392,9 @@ virStoragePoolListVolumes(virStoragePoolPtr pool, * call. * * Returns the virConnectPtr or NULL in case of failure. + * + * Since: v1.0.0 + * */ virConnectPtr virStorageVolGetConnect(virStorageVolPtr vol) @@ -1325,6 +1421,9 @@ virStorageVolGetConnect(virStorageVolPtr vol) * storage volume object is no longer needed. * * Returns a storage volume, or NULL if not found / error + * + * Since: v1.0.0 + * */ virStorageVolPtr virStorageVolLookupByName(virStoragePoolPtr pool, @@ -1365,6 +1464,9 @@ virStorageVolLookupByName(virStoragePoolPtr pool, * storage volume object is no longer needed. * * Returns a storage volume, or NULL if not found / error + * + * Since: v1.0.0 + * */ virStorageVolPtr virStorageVolLookupByKey(virConnectPtr conn, @@ -1405,6 +1507,9 @@ virStorageVolLookupByKey(virConnectPtr conn, * storage volume object is no longer needed. * * Returns a storage volume, or NULL if not found / error + * + * Since: v1.0.0 + * */ virStorageVolPtr virStorageVolLookupByPath(virConnectPtr conn, @@ -1441,6 +1546,9 @@ virStorageVolLookupByPath(virConnectPtr conn, * within the scope of a pool * * Returns the volume name, or NULL on error + * + * Since: v1.0.0 + * */ const char* virStorageVolGetName(virStorageVolPtr vol) @@ -1464,6 +1572,9 @@ virStorageVolGetName(virStorageVolPtr vol) * key no matter what host it is accessed from * * Returns the volume key, or NULL on error + * + * Since: v1.0.0 + * */ const char* virStorageVolGetKey(virStorageVolPtr vol) @@ -1497,6 +1608,9 @@ virStorageVolGetKey(virStorageVolPtr vol) * storage volume object is no longer needed. * * Returns the storage volume, or NULL on error + * + * Since: v1.0.0 + * */ virStorageVolPtr virStorageVolCreateXML(virStoragePoolPtr pool, @@ -1548,6 +1662,9 @@ virStorageVolCreateXML(virStoragePoolPtr pool, * storage volume object is no longer needed. * * Returns the storage volume, or NULL on error + * + * Since: v1.0.0 + * */ virStorageVolPtr virStorageVolCreateXMLFrom(virStoragePoolPtr pool, @@ -1612,6 +1729,9 @@ virStorageVolCreateXMLFrom(virStoragePoolPtr pool, * another active stream is writing to the storage volume. * * Returns 0, or -1 upon error. + * + * Since: v1.0.0 + * */ int virStorageVolDownload(virStorageVolPtr vol, @@ -1695,6 +1815,9 @@ virStorageVolDownload(virStorageVolPtr vol, * capacity, and allocation. * * Returns 0, or -1 upon error. + * + * Since: v1.0.0 + * */ int virStorageVolUpload(virStorageVolPtr vol, @@ -1748,6 +1871,9 @@ virStorageVolUpload(virStorageVolPtr vol, * Delete the storage volume from the pool * * Returns 0 on success, or -1 on error + * + * Since: v1.0.0 + * */ int virStorageVolDelete(virStorageVolPtr vol, @@ -1797,6 +1923,9 @@ virStorageVolDelete(virStorageVolPtr vol, * network file systems are known to be problematic. * * Returns 0 on success, or -1 on error + * + * Since: v1.0.0 + * */ int virStorageVolWipe(virStorageVolPtr vol, @@ -1843,6 +1972,9 @@ virStorageVolWipe(virStorageVolPtr vol, * problematic. * * Returns 0 on success, or -1 on error. + * + * Since: v1.0.0 + * */ int virStorageVolWipePattern(virStorageVolPtr vol, @@ -1883,6 +2015,9 @@ virStorageVolWipePattern(virStorageVolPtr vol, * storage volume continues to exist. * * Returns 0 on success, or -1 on error + * + * Since: v1.0.0 + * */ int virStorageVolFree(virStorageVolPtr vol) @@ -1914,6 +2049,9 @@ virStorageVolFree(virStorageVolPtr vol) * the reference count. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.0.0 + * */ int virStorageVolRef(virStorageVolPtr vol) @@ -1938,6 +2076,9 @@ virStorageVolRef(virStorageVolPtr vol) * volume such as its current allocation * * Returns 0 on success, or -1 on failure + * + * Since: v1.0.0 + * */ int virStorageVolGetInfo(virStorageVolPtr vol, @@ -1988,6 +2129,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 +2176,9 @@ virStorageVolGetInfoFlags(virStorageVolPtr vol, * the storage volume * * Returns the XML document, or NULL on error + * + * Since: v1.0.0 + * */ char * virStorageVolGetXMLDesc(virStorageVolPtr vol, @@ -2073,6 +2220,9 @@ virStorageVolGetXMLDesc(virStorageVolPtr vol, * * Returns the storage volume path, or NULL on error. The * caller must free() the returned path after use. + * + * Since: v1.0.0 + * */ char * virStorageVolGetPath(virStorageVolPtr vol) @@ -2134,6 +2284,9 @@ virStorageVolGetPath(virStorageVolPtr vol) * than the current size. * * Returns 0 on success, or -1 on error. + * + * Since: v1.0.0 + * */ int virStorageVolResize(virStorageVolPtr vol, @@ -2183,6 +2336,9 @@ virStorageVolResize(virStorageVolPtr vol, * Determine if the storage pool is currently running * * Returns 1 if running, 0 if inactive, -1 on error + * + * Since: v1.0.0 + * */ int virStoragePoolIsActive(virStoragePoolPtr pool) @@ -2216,6 +2372,9 @@ virStoragePoolIsActive(virStoragePoolPtr pool) * which means it will still exist after shutting down * * Returns 1 if persistent, 0 if transient, -1 on error + * + * Since: v1.0.0 + * */ int virStoragePoolIsPersistent(virStoragePoolPtr pool) @@ -2274,6 +2433,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 +2499,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 +2541,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..a3779ef1c7 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ int virStreamEventRemoveCallback(virStreamPtr stream) @@ -1173,6 +1215,9 @@ virStreamEventRemoveCallback(virStreamPtr stream) * beforehand. * * Returns 0 on success, -1 upon error + * + * Since: v1.0.0 + * */ int virStreamFinish(virStreamPtr stream) @@ -1215,6 +1260,9 @@ virStreamFinish(virStreamPtr stream) * beforehand. * * Returns 0 on success, -1 upon error + * + * Since: v1.0.0 + * */ 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: v1.0.0 + * */ int virStreamFree(virStreamPtr stream) diff --git a/src/libvirt.c b/src/libvirt.c index 6cda75d1ca..a2c6360489 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: v1.0.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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ int virConnectClose(virConnectPtr conn) diff --git a/src/util/virerror.c b/src/util/virerror.c index e864a50fba..5687c2aaa3 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: v1.0.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.6 + * */ 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: v1.0.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: v1.0.0 + * */ 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: v1.0.0 + * */ void virResetError(virErrorPtr err) @@ -473,6 +494,9 @@ virResetError(virErrorPtr err) * @err: error to free * * Resets and frees the given error. + * + * Since: v1.0.0 + * */ 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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.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: v1.0.0 + * */ void virDefaultErrorFunc(virErrorPtr err) diff --git a/src/util/virevent.c b/src/util/virevent.c index f6eb806faf..9fe751abb2 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: v1.0.0 + * */ int virEventAddHandle(int fd, @@ -94,6 +97,9 @@ virEventAddHandle(int fd, * virEventRegisterImpl() or virEventRegisterDefaultImpl(). * * Will not fail if fd exists. + * + * Since: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.0 + * */ 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: v1.0.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: v1.0.0 + * */ int virEventRegisterDefaultImpl(void) { @@ -335,6 +359,9 @@ int virEventRegisterDefaultImpl(void) * } * * Returns 0 on success, -1 on failure. + * + * Since: v1.0.0 + * */ int virEventRunDefaultImpl(void) { -- 2.35.1