External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-22 05:35:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

docstring: function: libvirt: Add 'Since version' metadata

Browse Source 
Either create or append to existing docstring, the version (git tag)
that a given function was introduced in the format:

    Since: v1.2.3

Signed-off-by: Victor Toso <victortoso@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
This commit is contained in:
Victor Toso 2022-04-22 21:23:36 +02:00 committed by Andrea Bolognani
parent 032724b9c4
commit c628bce03b
23 changed files with 1083 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
include/libvirt/libvirt-domain.h
View File

@ -3950,6 +3950,8 @@ typedef enum {
* A callback function to be registered, and called when a domain event occurs
*
* Returns 0 (the return value is currently ignored)
*
* Since: v0.5.0
*/
typedef int (*virConnectDomainEventCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -4496,6 +4498,8 @@ typedef enum {
* have a customization with extra parameters, often with @opaque being
* passed in a different parameter position; use VIR_DOMAIN_EVENT_CALLBACK()
* when registering an appropriate handler.
*
* Since: v0.8.0
*/
typedef void (*virConnectDomainEventGenericCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -4510,6 +4514,8 @@ typedef void (*virConnectDomainEventGenericCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_RTC_CHANGE with virConnectDomainEventRegisterAny()
*
* Since: v0.8.0
*/
typedef void (*virConnectDomainEventRTCChangeCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -4547,6 +4553,7 @@ typedef enum {
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_WATCHDOG with virConnectDomainEventRegisterAny()
*
* Since: v0.8.0
*/
typedef void (*virConnectDomainEventWatchdogCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -4582,6 +4589,8 @@ typedef enum {
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_IO_ERROR with virConnectDomainEventRegisterAny()
*
* Since: v0.8.0
*/
typedef void (*virConnectDomainEventIOErrorCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -4609,6 +4618,7 @@ typedef void (*virConnectDomainEventIOErrorCallback)(virConnectPtr conn,
* Otherwise, @reason will be "", although future strings may be added
* if determination of other error types becomes possible.
*
* Since: v0.8.1
*/
typedef void (*virConnectDomainEventIOErrorReasonCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -4752,6 +4762,8 @@ typedef virDomainEventGraphicsSubject *virDomainEventGraphicsSubjectPtr;
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_GRAPHICS with virConnectDomainEventRegisterAny()
*
* Since: v0.8.0
*/
typedef void (*virConnectDomainEventGraphicsCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -4804,6 +4816,8 @@ typedef enum {
* was registered using the newer type of VIR_DOMAIN_EVENT_ID_BLOCK_JOB_2,
* then @disk will contain the device target shorthand (the <target
* dev='...'/> sub-element, such as "vda").
*
* Since: v0.9.4
*/
typedef void (*virConnectDomainEventBlockJobCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -4857,6 +4871,8 @@ typedef enum {
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_DISK_CHANGE with virConnectDomainEventRegisterAny()
*
* Since: v0.9.7
*/
typedef void (*virConnectDomainEventDiskChangeCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -4894,6 +4910,8 @@ typedef enum {
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_TRAY_CHANGE with virConnectDomainEventRegisterAny()
*
* Since: v0.9.11
*/
typedef void (*virConnectDomainEventTrayChangeCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -4913,6 +4931,8 @@ typedef void (*virConnectDomainEventTrayChangeCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_PMWAKEUP with virConnectDomainEventRegisterAny()
*
* Since: v0.9.11
*/
typedef void (*virConnectDomainEventPMWakeupCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -4931,6 +4951,8 @@ typedef void (*virConnectDomainEventPMWakeupCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_PMSUSPEND with virConnectDomainEventRegisterAny()
*
* Since: v0.9.11
*/
typedef void (*virConnectDomainEventPMSuspendCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -4947,6 +4969,8 @@ typedef void (*virConnectDomainEventPMSuspendCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_BALLOON_CHANGE with virConnectDomainEventRegisterAny()
*
* Since: v0.10.0
*/
typedef void (*virConnectDomainEventBalloonChangeCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -4965,6 +4989,8 @@ typedef void (*virConnectDomainEventBalloonChangeCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_PMSUSPEND_DISK with virConnectDomainEventRegisterAny()
*
* Since: v1.0.0
*/
typedef void (*virConnectDomainEventPMSuspendDiskCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -4982,6 +5008,8 @@ typedef void (*virConnectDomainEventPMSuspendDiskCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_DEVICE_REMOVED with virConnectDomainEventRegisterAny()
*
* Since: v1.1.1
*/
typedef void (*virConnectDomainEventDeviceRemovedCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -4999,6 +5027,8 @@ typedef void (*virConnectDomainEventDeviceRemovedCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_DEVICE_ADDED with virConnectDomainEventRegisterAny()
*
* Since: v1.2.15
*/
typedef void (*virConnectDomainEventDeviceAddedCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -5018,6 +5048,8 @@ typedef void (*virConnectDomainEventDeviceAddedCallback)(virConnectPtr conn,
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_DEVICE_REMOVAL_FAILED with
* virConnectDomainEventRegisterAny().
*
* Since: v1.3.4
*/
typedef void (*virConnectDomainEventDeviceRemovalFailedCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -5036,6 +5068,8 @@ typedef void (*virConnectDomainEventDeviceRemovalFailedCallback)(virConnectPtr c
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_METADATA_CHANGE with virConnectDomainEventRegisterAny().
*
* Since: v3.0.0
*/
typedef void (*virConnectDomainEventMetadataChangeCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -5059,6 +5093,8 @@ typedef void (*virConnectDomainEventMetadataChangeCallback)(virConnectPtr conn,
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_MIGRATION_ITERATION with
* virConnectDomainEventRegisterAny().
*
* Since: v1.3.2
*/
typedef void (*virConnectDomainEventMigrationIterationCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -5083,6 +5119,8 @@ typedef void (*virConnectDomainEventMigrationIterationCallback)(virConnectPtr co
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_JOB_COMPLETED with
* virConnectDomainEventRegisterAny().
*
* Since: v1.3.3
*/
typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -5448,6 +5486,8 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_TUNABLE with virConnectDomainEventRegisterAny()
*
* Since: v1.2.9
*/
typedef void (*virConnectDomainEventTunableCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -5498,6 +5538,8 @@ typedef enum {
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_AGENT_LIFECYCLE with virConnectDomainEventRegisterAny()
*
* Since: v1.2.11
*/
typedef void (*virConnectDomainEventAgentLifecycleCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -5527,6 +5569,8 @@ typedef void (*virConnectDomainEventAgentLifecycleCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD with virConnectDomainEventRegisterAny()
*
* Since: v3.2.0
*/
typedef void (*virConnectDomainEventBlockThresholdCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -5552,6 +5596,8 @@ typedef void (*virConnectDomainEventBlockThresholdCallback)(virConnectPtr conn,
*
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_MEMORY_FAILURE with virConnectDomainEventRegisterAny()
*
* Since: v6.9.0
*/
typedef void (*virConnectDomainEventMemoryFailureCallback)(virConnectPtr conn,
virDomainPtr dom,
@ -5576,6 +5622,8 @@ typedef void (*virConnectDomainEventMemoryFailureCallback)(virConnectPtr conn,
* The callback signature to use when registering for an event of type
* VIR_DOMAIN_EVENT_ID_MEMORY_DEVICE_SIZE_CHANGE with
* virConnectDomainEventRegisterAny().
*
* Since: v7.9.0
*/
typedef void (*virConnectDomainEventMemoryDeviceSizeChangeCallback)(virConnectPtr conn,
virDomainPtr dom,

16
include/libvirt/libvirt-event.h
View File

@ -54,6 +54,8 @@ typedef enum {
*
* Callback for receiving file handle events. The callback will
* be invoked once for each event which is pending.
*
* Since: v0.5.0
*/
typedef void (*virEventHandleCallback)(int watch, int fd, int events, void *opaque);
@ -81,6 +83,8 @@ typedef void (*virEventHandleCallback)(int watch, int fd, int events, void *opaq
*
* Returns -1 if the file handle cannot be registered, otherwise a handle
* watch number to be used for updating and unregistering for events
*
* Since: v0.5.0
*/
typedef int (*virEventAddHandleFunc)(int fd, int event,
virEventHandleCallback cb,
@ -94,6 +98,8 @@ typedef int (*virEventAddHandleFunc)(int fd, int event,
*
* Part of the EventImpl, this user-provided callback is notified when
* events to listen on change
*
* Since: v0.5.0
*/
typedef void (*virEventUpdateHandleFunc)(int watch, int event);
@ -109,6 +115,8 @@ typedef void (*virEventUpdateHandleFunc)(int watch, int event);
* function call, when it is safe to release the user data.
*
* Returns -1 if the file handle was not registered, 0 upon success
*
* Since: v0.5.0
*/
typedef int (*virEventRemoveHandleFunc)(int watch);
@ -119,6 +127,8 @@ typedef int (*virEventRemoveHandleFunc)(int watch);
* @opaque: user data registered with handle
*
* callback for receiving timer events
*
* Since: v0.5.0
*/
typedef void (*virEventTimeoutCallback)(int timer, void *opaque);
@ -137,6 +147,8 @@ typedef void (*virEventTimeoutCallback)(int timer, void *opaque);
* this purpose.
*
* Returns a timer value
*
* Since: v0.5.0
*/
typedef int (*virEventAddTimeoutFunc)(int timeout,
virEventTimeoutCallback cb,
@ -150,6 +162,8 @@ typedef int (*virEventAddTimeoutFunc)(int timeout,
*
* Part of the EventImpl, this user-defined callback updates an
* event timeout.
*
* Since: v0.5.0
*/
typedef void (*virEventUpdateTimeoutFunc)(int timer, int timeout);
@ -164,6 +178,8 @@ typedef void (*virEventUpdateTimeoutFunc)(int timer, int timeout);
* function call, when it is safe to release the user data.
*
* Returns 0 on success, -1 on failure
*
* Since: v0.5.0
*/
typedef int (*virEventRemoveTimeoutFunc)(int timer);

4
include/libvirt/libvirt-host.h
View File

@ -650,6 +650,8 @@ typedef virConnectCredential *virConnectCredentialPtr;
* If an interaction cannot be filled, fill in NULL and 0.
*
* Returns 0 if all interactions were filled, or -1 upon error
*
* Since: v0.4.1
*/
typedef int (*virConnectAuthCallbackPtr)(virConnectCredentialPtr cred,
unsigned int ncred,
@ -841,6 +843,8 @@ int virConnectSetKeepAlive(virConnectPtr conn,
*
* A callback function to be registered, and called when the connection
* is closed.
*
* Since: v0.10.0
*/
typedef void (*virConnectCloseFunc)(virConnectPtr conn,
int reason,

4
include/libvirt/libvirt-network.h
View File

@ -300,6 +300,8 @@ typedef enum {
*
* The callback signature to use when registering for an event of type
* VIR_NETWORK_EVENT_ID_LIFECYCLE with virConnectNetworkEventRegisterAny()
*
* Since: v1.2.1
*/
typedef void (*virConnectNetworkEventLifecycleCallback)(virConnectPtr conn,
virNetworkPtr net,
@ -398,6 +400,8 @@ int virNetworkGetDHCPLeases(virNetworkPtr network,
* have a customization with extra parameters, often with @opaque being
* passed in a different parameter position; use VIR_NETWORK_EVENT_CALLBACK()
* when registering an appropriate handler.
*
* Since: v1.2.1
*/
typedef void (*virConnectNetworkEventGenericCallback)(virConnectPtr conn,
virNetworkPtr net,

4
include/libvirt/libvirt-nodedev.h
View File

@ -202,6 +202,8 @@ typedef enum {
* have a customization with extra parameters, often with @opaque being
* passed in a different parameter position; use
* VIR_NODE_DEVICE_EVENT_CALLBACK() when registering an appropriate handler.
*
* Since: v2.2.0
*/
typedef void (*virConnectNodeDeviceEventGenericCallback)(virConnectPtr conn,
virNodeDevicePtr dev,
@ -251,6 +253,8 @@ typedef enum {
* The callback signature to use when registering for an event of type
* VIR_NODE_DEVICE_EVENT_ID_LIFECYCLE with
* virConnectNodeDeviceEventRegisterAny()
*
* Since: v2.2.0
*/
typedef void (*virConnectNodeDeviceEventLifecycleCallback)(virConnectPtr conn,
virNodeDevicePtr dev,

4
include/libvirt/libvirt-secret.h
View File

@ -182,6 +182,8 @@ typedef enum {
* have a customization with extra parameters, often with @opaque being
* passed in a different parameter position; use
* VIR_SECRET_EVENT_CALLBACK() when registering an appropriate handler.
*
* Since: v3.0.0
*/
typedef void (*virConnectSecretEventGenericCallback)(virConnectPtr conn,
virSecretPtr secret,
@ -229,6 +231,8 @@ typedef enum {
* The callback signature to use when registering for an event of type
* VIR_SECRET_EVENT_ID_LIFECYCLE with
* virConnectSecretEventRegisterAny()
*
* Since: v3.0.0
*/
typedef void (*virConnectSecretEventLifecycleCallback)(virConnectPtr conn,
virSecretPtr secret,

4
include/libvirt/libvirt-storage.h
View File

@ -559,6 +559,8 @@ typedef enum {
* have a customization with extra parameters, often with @opaque being
* passed in a different parameter position; use
* VIR_STORAGE_POOL_EVENT_CALLBACK() when registering an appropriate handler.
*
* Since: v2.0.0
*/
typedef void (*virConnectStoragePoolEventGenericCallback)(virConnectPtr conn,
virStoragePoolPtr pool,
@ -610,6 +612,8 @@ typedef enum {
* The callback signature to use when registering for an event of type
* VIR_STORAGE_POOL_EVENT_ID_LIFECYCLE with
* virConnectStoragePoolEventRegisterAny()
*
* Since: v2.0.0
*/
typedef void (*virConnectStoragePoolEventLifecycleCallback)(virConnectPtr conn,
virStoragePoolPtr pool,

12
include/libvirt/libvirt-stream.h
View File

@ -98,6 +98,8 @@ int virStreamRecvHole(virStreamPtr,
*
* Returns the number of bytes filled, 0 upon end
* of file, or -1 upon error
*
* Since: v0.7.2
*/
typedef int (*virStreamSourceFunc)(virStreamPtr st,
char *data,
@ -136,6 +138,8 @@ int virStreamSendAll(virStreamPtr st,
*
* Returns 0 on success,
* -1 upon error
*
* Since: v3.4.0
*/
typedef int (*virStreamSourceHoleFunc)(virStreamPtr st,
int *inData,
@ -162,6 +166,8 @@ typedef int (*virStreamSourceHoleFunc)(virStreamPtr st,
*
* Returns 0 on success,
* -1 upon error.
*
* Since: v3.4.0
*/
typedef int (*virStreamSourceSkipFunc)(virStreamPtr st,
long long length,
@ -199,6 +205,8 @@ int virStreamSparseSendAll(virStreamPtr st,
*
* Returns the number of bytes consumed or -1 upon
* error
*
* Since: v0.7.2
*/
typedef int (*virStreamSinkFunc)(virStreamPtr st,
const char *data,
@ -229,6 +237,8 @@ int virStreamRecvAll(virStreamPtr st,
*
* Returns 0 on success,
* -1 upon error
*
* Since: v3.4.0
*/
typedef int (*virStreamSinkHoleFunc)(virStreamPtr st,
long long length,
@ -261,6 +271,8 @@ typedef enum {
*
* Callback for receiving stream events. The callback will
* be invoked once for each event which is pending.
*
* Since: v0.7.2
*/
typedef void (*virStreamEventCallback)(virStreamPtr stream, int events, void *opaque);

2
include/libvirt/virterror.h
View File

@ -360,6 +360,8 @@ typedef enum {
* @error: the error being raised.
*
* Signature of a function to use when there is an error raised by the library.
*
* Since: v0.1.0
*/
typedef void (*virErrorFunc) (void *userData, virErrorPtr error);

24
src/libvirt-domain-checkpoint.c
View File

@ -35,6 +35,8 @@ VIR_LOG_INIT("libvirt.domain-checkpoint");
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* as its lifetime will be the same as the checkpoint object.
*
* Since: v5.6.0
*/
const char *
virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint)
@ -58,6 +60,8 @@ virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint)
* call.
*
* Returns the domain or NULL.
*
* Since: v5.6.0
*/
virDomainPtr
virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint)
@ -81,6 +85,8 @@ virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint)
* call.
*
* Returns the connection or NULL.
*
* Since: v5.6.0
*/
virConnectPtr
virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint)
@ -138,6 +144,8 @@ virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint)
*
* Returns an (opaque) new virDomainCheckpointPtr on success or NULL
* on failure.
*
* Since: v5.6.0
*/
virDomainCheckpointPtr
virDomainCheckpointCreateXML(virDomainPtr domain,
@ -207,6 +215,8 @@ virDomainCheckpointCreateXML(virDomainPtr domain,
*
* Returns a 0 terminated UTF-8 encoded XML instance or NULL in case
* of error. The caller must free() the returned value.
*
* Since: v5.6.0
*/
char *
virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint,
@ -281,6 +291,8 @@ virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint,
* included in the return count, to make iteration easier. The caller is
* responsible for calling virDomainCheckpointFree() on each array element,
* then calling free() on @checkpoints.
*
* Since: v5.6.0
*/
int
virDomainListAllCheckpoints(virDomainPtr domain,
@ -348,6 +360,8 @@ virDomainListAllCheckpoints(virDomainPtr domain,
* in the return count, to make iteration easier. The caller is responsible
* for calling virDomainCheckpointFree() on each array element, then calling
* free() on @children.
*
* Since: v5.6.0
*/
int
virDomainCheckpointListAllChildren(virDomainCheckpointPtr checkpoint,
@ -394,6 +408,8 @@ virDomainCheckpointListAllChildren(virDomainCheckpointPtr checkpoint,
* Returns a domain checkpoint object or NULL in case of failure. If the
* domain checkpoint cannot be found, then the VIR_ERR_NO_DOMAIN_CHECKPOINT
* error is raised.
*
* Since: v5.6.0
*/
virDomainCheckpointPtr
virDomainCheckpointLookupByName(virDomainPtr domain,
@ -440,6 +456,8 @@ virDomainCheckpointLookupByName(virDomainPtr domain,
* Returns a domain checkpoint object or NULL in case of failure. If the
* given checkpoint is a root (no parent), then the VIR_ERR_NO_DOMAIN_CHECKPOINT
* error is raised.
*
* Since: v5.6.0
*/
virDomainCheckpointPtr
virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint,
@ -493,6 +511,8 @@ virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint,
* silently ignored.
*
* Returns 0 on success, -1 on error.
*
* Since: v5.6.0
*/
int
virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint,
@ -543,6 +563,8 @@ virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint,
* increment the reference count.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v5.6.0
*/
int
virDomainCheckpointRef(virDomainCheckpointPtr checkpoint)
@ -566,6 +588,8 @@ virDomainCheckpointRef(virDomainCheckpointPtr checkpoint)
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v5.6.0
*/
int
virDomainCheckpointFree(virDomainCheckpointPtr checkpoint)

42
src/libvirt-domain-snapshot.c
View File

@ -35,6 +35,8 @@ VIR_LOG_INIT("libvirt.domain-snapshot");
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* as its lifetime will be the same as the snapshot object.
*
* Since: v0.9.5
*/
const char *
virDomainSnapshotGetName(virDomainSnapshotPtr snapshot)
@ -58,6 +60,8 @@ virDomainSnapshotGetName(virDomainSnapshotPtr snapshot)
* call.
*
* Returns the domain or NULL.
*
* Since: v0.9.5
*/
virDomainPtr
virDomainSnapshotGetDomain(virDomainSnapshotPtr snapshot)
@ -81,6 +85,8 @@ virDomainSnapshotGetDomain(virDomainSnapshotPtr snapshot)
* call.
*
* Returns the connection or NULL.
*
* Since: v0.9.5
*/
virConnectPtr
virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
@ -213,6 +219,8 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
*
* Returns an (opaque) new virDomainSnapshotPtr on success or NULL on
* failure.
*
* Since: v0.8.0
*/
virDomainSnapshotPtr
virDomainSnapshotCreateXML(virDomainPtr domain,
@ -271,6 +279,8 @@ virDomainSnapshotCreateXML(virDomainPtr domain,
*
* Returns a 0 terminated UTF-8 encoded XML instance or NULL in case
* of error. The caller must free() the returned value.
*
* Since: v0.8.0
*/
char *
virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot,
@ -324,6 +334,8 @@ virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot,
* virDomainListAllSnapshots().
*
* Returns the number of domain snapshots found or -1 in case of error.
*
* Since: v0.8.0
*/
int
virDomainSnapshotNum(virDomainPtr domain, unsigned int flags)
@ -388,6 +400,8 @@ virDomainSnapshotNum(virDomainPtr domain, unsigned int flags)
*
* Returns the number of domain snapshots found or -1 in case of error.
* The caller is responsible to call free() for each member of the array.
*
* Since: v0.8.0
*/
int
virDomainSnapshotListNames(virDomainPtr domain, char **names, int nameslen,
@ -476,6 +490,8 @@ virDomainSnapshotListNames(virDomainPtr domain, char **names, int nameslen,
* in the return count, to make iteration easier. The caller is responsible
* for calling virDomainSnapshotFree() on each array element, then calling
* free() on @snaps.
*
* Since: v0.9.13
*/
int
virDomainListAllSnapshots(virDomainPtr domain, virDomainSnapshotPtr **snaps,
@ -525,6 +541,8 @@ virDomainListAllSnapshots(virDomainPtr domain, virDomainSnapshotPtr **snaps,
* virDomainSnapshotListAllChildren().
*
* Returns the number of domain snapshots found or -1 in case of error.
*
* Since: v0.9.7
*/
int
virDomainSnapshotNumChildren(virDomainSnapshotPtr snapshot, unsigned int flags)
@ -591,6 +609,8 @@ virDomainSnapshotNumChildren(virDomainSnapshotPtr snapshot, unsigned int flags)
*
* Returns the number of domain snapshots found or -1 in case of error.
* The caller is responsible to call free() for each member of the array.
*
* Since: v0.9.7
*/
int
virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot,
@ -662,6 +682,8 @@ virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot,
* in the return count, to make iteration easier. The caller is responsible
* for calling virDomainSnapshotFree() on each array element, then calling
* free() on @snaps.
*
* Since: v0.9.13
*/
int
virDomainSnapshotListAllChildren(virDomainSnapshotPtr snapshot,
@ -706,6 +728,8 @@ virDomainSnapshotListAllChildren(virDomainSnapshotPtr snapshot,
* Returns a domain snapshot object or NULL in case of failure. If the
* domain snapshot cannot be found, then the VIR_ERR_NO_DOMAIN_SNAPSHOT
* error is raised.
*
* Since: v0.8.0
*/
virDomainSnapshotPtr
virDomainSnapshotLookupByName(virDomainPtr domain,
@ -746,6 +770,8 @@ virDomainSnapshotLookupByName(virDomainPtr domain,
* Determine if the domain has a current snapshot.
*
* Returns 1 if such snapshot exists, 0 if it doesn't, -1 on error.
*
* Since: v0.8.0
*/
int
virDomainHasCurrentSnapshot(virDomainPtr domain, unsigned int flags)
@ -786,6 +812,8 @@ virDomainHasCurrentSnapshot(virDomainPtr domain, unsigned int flags)
* Returns a domain snapshot object or NULL in case of failure. If the
* current domain snapshot cannot be found, then the VIR_ERR_NO_DOMAIN_SNAPSHOT
* error is raised.
*
* Since: v0.8.0
*/
virDomainSnapshotPtr
virDomainSnapshotCurrent(virDomainPtr domain,
@ -828,6 +856,8 @@ virDomainSnapshotCurrent(virDomainPtr domain,
* Returns a domain snapshot object or NULL in case of failure. If the
* given snapshot is a root (no parent), then the VIR_ERR_NO_DOMAIN_SNAPSHOT
* error is raised.
*
* Since: v0.9.7
*/
virDomainSnapshotPtr
virDomainSnapshotGetParent(virDomainSnapshotPtr snapshot,
@ -866,6 +896,8 @@ virDomainSnapshotGetParent(virDomainSnapshotPtr snapshot,
* also virDomainHasCurrentSnapshot().
*
* Returns 1 if current, 0 if not current, or -1 on error.
*
* Since: v0.9.13
*/
int
virDomainSnapshotIsCurrent(virDomainSnapshotPtr snapshot,
@ -905,6 +937,8 @@ virDomainSnapshotIsCurrent(virDomainSnapshotPtr snapshot,
*
* Returns 1 if the snapshot has metadata, 0 if the snapshot exists without
* help from libvirt, or -1 on error.
*
* Since: v0.9.13
*/
int
virDomainSnapshotHasMetadata(virDomainSnapshotPtr snapshot,
@ -984,6 +1018,8 @@ virDomainSnapshotHasMetadata(virDomainSnapshotPtr snapshot,
* NVRAM from the pristine template.
*
* Returns 0 if the creation is successful, -1 on error.
*
* Since: v0.8.0
*/
int
virDomainRevertToSnapshot(virDomainSnapshotPtr snapshot,
@ -1041,6 +1077,8 @@ virDomainRevertToSnapshot(virDomainSnapshotPtr snapshot,
*
* Returns 0 if the selected snapshot(s) were successfully deleted,
* -1 on error.
*
* Since: v0.8.0
*/
int
virDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
@ -1091,6 +1129,8 @@ virDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
* increment the reference count.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v0.9.13
*/
int
virDomainSnapshotRef(virDomainSnapshotPtr snapshot)
@ -1114,6 +1154,8 @@ virDomainSnapshotRef(virDomainSnapshotPtr snapshot)
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v0.8.0
*/
int
virDomainSnapshotFree(virDomainSnapshotPtr snapshot)

371
src/libvirt-domain.c
View File

File diff suppressed because it is too large Load Diff

68
src/libvirt-host.c
View File

@ -47,6 +47,8 @@ VIR_LOG_INIT("libvirt.host");
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure
*
* Since: v0.6.0
*/
int
virConnectRef(virConnectPtr conn)
@ -85,6 +87,8 @@ virConnectRef(virConnectPtr conn)
* on a connection if the application is not trustworthy.
*
* Returns: 0 if the identity change was accepted, -1 on error
*
* Since: v5.8.0
*/
int
virConnectSetIdentity(virConnectPtr conn,
@ -149,6 +153,8 @@ virConnectSupportsFeature(virConnectPtr conn, int feature)
* hypervisor, use virConnectGetCapabilities().
*
* Returns NULL in case of error, a static zero terminated string otherwise.
*
* Since: v0.0.3
*/
const char *
virConnectGetType(virConnectPtr conn)
@ -180,6 +186,8 @@ virConnectGetType(virConnectPtr conn)
* Returns -1 in case of error, 0 otherwise. if the version can't be
* extracted by lack of capacities returns 0 and @hvVer is 0, otherwise
* @hvVer value is major * 1,000,000 + minor * 1,000 + release
*
* Since: v0.0.3
*/
int
virConnectGetVersion(virConnectPtr conn, unsigned long *hvVer)
@ -216,6 +224,8 @@ virConnectGetVersion(virConnectPtr conn, unsigned long *hvVer)
*
* Returns -1 in case of failure, 0 otherwise, and values for @libVer have
* the format major * 1,000,000 + minor * 1,000 + release.
*
* Since: v0.7.3
*/
int
virConnectGetLibVersion(virConnectPtr conn, unsigned long *libVer)
@ -256,6 +266,8 @@ virConnectGetLibVersion(virConnectPtr conn, unsigned long *libVer)
*
* Returns the hostname which must be freed by the caller, or
* NULL if there was an error.
*
* Since: v0.3.0
*/
char *
virConnectGetHostname(virConnectPtr conn)
@ -295,6 +307,8 @@ virConnectGetHostname(virConnectPtr conn)
*
* Returns the URI string which must be freed by the caller, or
* NULL if there was an error.
*
* Since: v0.3.0
*/
char *
virConnectGetURI(virConnectPtr conn)
@ -329,6 +343,8 @@ virConnectGetURI(virConnectPtr conn)
*
* Returns the XML string which must be freed by the caller, or
* NULL if there was an error.
*
* Since: v0.8.8
*/
char *
virConnectGetSysinfo(virConnectPtr conn, unsigned int flags)
@ -367,6 +383,8 @@ virConnectGetSysinfo(virConnectPtr conn, unsigned int flags)
* for "<vcpu max='...'>" in its output instead.
*
* Returns the maximum of virtual CPU or -1 in case of error.
*
* Since: v0.2.1
*/
int
virConnectGetMaxVcpus(virConnectPtr conn,
@ -416,6 +434,8 @@ virConnectGetMaxVcpus(virConnectPtr conn,
* in a more accurate representation.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v0.1.0
*/
int
virNodeGetInfo(virConnectPtr conn, virNodeInfoPtr info)
@ -452,6 +472,8 @@ virNodeGetInfo(virConnectPtr conn, virNodeInfoPtr info)
* Returns NULL in case of error, or an XML string
* defining the capabilities.
* The client must free the returned string after use.
*
* Since: v0.2.1
*/
char *
virConnectGetCapabilities(virConnectPtr conn)
@ -532,6 +554,8 @@ virConnectGetCapabilities(virConnectPtr conn)
* represents all CPUs on the server.
*
* Returns -1 in case of error, 0 in case of success.
*
* Since: v0.9.3
*/
int
virNodeGetCPUStats(virConnectPtr conn,
@ -619,6 +643,8 @@ virNodeGetCPUStats(virConnectPtr conn,
* The cached memory usage.(KB)
*
* Returns -1 in case of error, 0 in case of success.
*
* Since: v0.9.3
*/
int
virNodeGetMemoryStats(virConnectPtr conn,
@ -666,6 +692,8 @@ virNodeGetMemoryStats(virConnectPtr conn,
* function the returned value is in bytes. Divide by 1024 as necessary.
*
* Returns the available free memory in bytes or 0 in case of error
*
* Since: v0.3.3
*/
unsigned long long
virNodeGetFreeMemory(virConnectPtr conn)
@ -712,6 +740,8 @@ virNodeGetFreeMemory(virConnectPtr conn)
* Returns 0 on success (i.e., the node will be suspended after a short
* delay), -1 on failure (the operation is not supported, or an attempted
* suspend is already underway).
*
* Since: v0.9.8
*/
int
virNodeSuspendForDuration(virConnectPtr conn,
@ -765,6 +795,8 @@ virNodeSuspendForDuration(virConnectPtr conn,
* example.
*
* Returns 0 in case of success, and -1 in case of failure.
*
* Since: v0.10.2
*/
int
virNodeGetMemoryParameters(virConnectPtr conn,
@ -829,6 +861,8 @@ virNodeGetMemoryParameters(virConnectPtr conn,
* This function may require privileged access to the hypervisor.
*
* Returns 0 in case of success, -1 in case of failure.
*
* Since: v0.10.2
*/
int
virNodeSetMemoryParameters(virConnectPtr conn,
@ -877,6 +911,8 @@ virNodeSetMemoryParameters(virConnectPtr conn,
* string if the driver has not activated a security model.
*
* Returns 0 in case of success, -1 in case of failure
*
* Since: v0.6.1
*/
int
virNodeGetSecurityModel(virConnectPtr conn, virSecurityModelPtr secmodel)
@ -920,6 +956,8 @@ virNodeGetSecurityModel(virConnectPtr conn, virSecurityModelPtr secmodel)
* whichever is smaller.
*
* Returns the number of entries filled in freeMems, or -1 in case of error.
*
* Since: v0.3.3
*/
int
virNodeGetCellsFreeMemory(virConnectPtr conn, unsigned long long *freeMems,
@ -958,6 +996,8 @@ virNodeGetCellsFreeMemory(virConnectPtr conn, unsigned long long *freeMems,
* Determine if the connection to the hypervisor is encrypted
*
* Returns 1 if encrypted, 0 if not encrypted, -1 on error
*
* Since: v0.7.3
*/
int
virConnectIsEncrypted(virConnectPtr conn)
@ -993,6 +1033,8 @@ virConnectIsEncrypted(virConnectPtr conn)
* to eavesdropping (eg a UNIX domain socket, or pipe)
*
* Returns 1 if secure, 0 if not secure, -1 on error
*
* Since: v0.7.3
*/
int
virConnectIsSecure(virConnectPtr conn)
@ -1035,6 +1077,8 @@ virConnectIsSecure(virConnectPtr conn)
* (instead of VIR_CPU_COMPARE_INCOMPATIBLE) and the error will use the
* VIR_ERR_CPU_INCOMPATIBLE code with a message providing more details about
* the incompatibility.
*
* Since: v0.7.5
*/
int
virConnectCompareCPU(virConnectPtr conn,
@ -1091,6 +1135,8 @@ virConnectCompareCPU(virConnectPtr conn,
* VIR_CPU_COMPARE_INCOMPATIBLE) and the error will use the
* VIR_ERR_CPU_INCOMPATIBLE code with a message providing more details about
* the incompatibility.
*
* Since: v4.4.0
*/
int
virConnectCompareHypervisorCPU(virConnectPtr conn,
@ -1153,6 +1199,8 @@ virConnectCompareHypervisorCPU(virConnectPtr conn,
*
* Returns -1 on error, number of elements in @models on success (0 means
* libvirt accepts any CPU model).
*
* Since: v1.1.3
*/
int
virConnectGetCPUModelNames(virConnectPtr conn, const char *arch, char ***models,
@ -1209,6 +1257,8 @@ virConnectGetCPUModelNames(virConnectPtr conn, const char *arch, char ***models,
* CPU will not include features that block migration.
*
* Returns XML description of the computed CPU (caller frees) or NULL on error.
*
* Since: v0.7.7
*/
char *
virConnectBaselineCPU(virConnectPtr conn,
@ -1278,6 +1328,8 @@ virConnectBaselineCPU(virConnectPtr conn,
* CPU will not include features that block migration.
*
* Returns XML description of the computed CPU (caller frees) or NULL on error.
*
* Since: v4.4.0
*/
char *
virConnectBaselineHypervisorCPU(virConnectPtr conn,
@ -1351,6 +1403,8 @@ virConnectBaselineHypervisorCPU(virConnectPtr conn,
*
* Returns -1 on error, 0 on success, 1 when remote party doesn't support
* keepalive messages.
*
* Since: v0.9.8
*/
int
virConnectSetKeepAlive(virConnectPtr conn,
@ -1388,6 +1442,8 @@ virConnectSetKeepAlive(virConnectPtr conn,
* over a channel (TCP or UNIX socket) which is not closed.
*
* Returns 1 if alive, 0 if dead, -1 on error
*
* Since: v0.9.8
*/
int
virConnectIsAlive(virConnectPtr conn)
@ -1434,6 +1490,8 @@ virConnectIsAlive(virConnectPtr conn)
* context.
*
* Returns 0 on success, -1 on error
*
* Since: v0.10.0
*/
int
virConnectRegisterCloseCallback(virConnectPtr conn,
@ -1471,6 +1529,8 @@ virConnectRegisterCloseCallback(virConnectPtr conn,
* registration, it will be invoked
*
* Returns 0 on success, -1 on error
*
* Since: v0.10.0
*/
int
virConnectUnregisterCloseCallback(virConnectPtr conn,
@ -1513,6 +1573,8 @@ virConnectUnregisterCloseCallback(virConnectPtr conn,
*
* Returns number of CPUs present on the host node,
* or -1 if there was an error.
*
* Since: v1.0.0
*/
int
virNodeGetCPUMap(virConnectPtr conn,
@ -1599,6 +1661,8 @@ virNodeGetCPUMap(virConnectPtr conn,
* Page size=1073741824 count=0 bytes=0
*
* Returns: the number of entries filled in @counts or -1 in case of error.
*
* Since: v1.2.6
*/
int
virNodeGetFreePages(virConnectPtr conn,
@ -1669,6 +1733,8 @@ virNodeGetFreePages(virConnectPtr conn,
*
* Returns: the number of nodes successfully adjusted or -1 in
* case of an error.
*
* Since: v1.2.9
*/
int
virNodeAllocPages(virConnectPtr conn,
@ -1722,6 +1788,8 @@ virNodeAllocPages(virConnectPtr conn,
* responsible for freeing @params.
*
* Returns 0 in case of success, and -1 in case of failure.
*
* Since: v4.5.0
*/
int
virNodeGetSEVInfo(virConnectPtr conn,

42
src/libvirt-interface.c
View File

@ -36,6 +36,8 @@ VIR_LOG_INIT("libvirt.interface");
* call.
*
* Returns the virConnectPtr or NULL in case of failure.
*
* Since: v0.6.4
*/
virConnectPtr
virInterfaceGetConnect(virInterfacePtr iface)
@ -76,6 +78,8 @@ virInterfaceGetConnect(virInterfacePtr iface)
* extra allocated element set to NULL but not included in the return count,
* to make iteration easier. The caller is responsible for calling
* virStorageInterfaceFree() on each array element, then calling free() on @ifaces.
*
* Since: v0.10.2
*/
int
virConnectListAllInterfaces(virConnectPtr conn,
@ -115,6 +119,8 @@ virConnectListAllInterfaces(virConnectPtr conn,
* Provides the number of active interfaces on the physical host.
*
* Returns the number of active interfaces found or -1 in case of error
*
* Since: v0.6.4
*/
int
virConnectNumOfInterfaces(virConnectPtr conn)
@ -158,6 +164,8 @@ virConnectNumOfInterfaces(virConnectPtr conn)
* to virConnectNumOfInterfaces() and this call; you are only guaranteed that
* all currently active interfaces were listed if the return is less than
* @maxnames. The client must call free() on each returned name.
*
* Since: v0.6.4
*/
int
virConnectListInterfaces(virConnectPtr conn, char **const names, int maxnames)
@ -193,6 +201,8 @@ virConnectListInterfaces(virConnectPtr conn, char **const names, int maxnames)
* Provides the number of defined (inactive) interfaces on the physical host.
*
* Returns the number of defined interface found or -1 in case of error
*
* Since: v0.7.0
*/
int
virConnectNumOfDefinedInterfaces(virConnectPtr conn)
@ -236,6 +246,8 @@ virConnectNumOfDefinedInterfaces(virConnectPtr conn)
* a call to virConnectNumOfDefinedInterfaces() and this call; you are only
* guaranteed that all currently defined interfaces were listed if the return
* is less than @maxnames. The client must call free() on each returned name.
*
* Since: v0.7.0
*/
int
virConnectListDefinedInterfaces(virConnectPtr conn,
@ -278,6 +290,8 @@ virConnectListDefinedInterfaces(virConnectPtr conn,
*
* Returns a new interface object or NULL in case of failure. If the
* interface cannot be found, then VIR_ERR_NO_INTERFACE error is raised.
*
* Since: v0.6.4
*/
virInterfacePtr
virInterfaceLookupByName(virConnectPtr conn, const char *name)
@ -317,6 +331,8 @@ virInterfaceLookupByName(virConnectPtr conn, const char *name)
*
* Returns a new interface object or NULL in case of failure. If the
* interface cannot be found, then VIR_ERR_NO_INTERFACE error is raised.
*
* Since: v0.6.4
*/
virInterfacePtr
virInterfaceLookupByMACString(virConnectPtr conn, const char *macstr)
@ -352,6 +368,8 @@ virInterfaceLookupByMACString(virConnectPtr conn, const char *macstr)
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* its lifetime will be the same as the interface object.
*
* Since: v0.6.4
*/
const char *
virInterfaceGetName(virInterfacePtr iface)
@ -376,6 +394,8 @@ virInterfaceGetName(virInterfacePtr iface)
* Returns a pointer to the MAC address (in null-terminated ASCII
* format) or NULL, the string need not be deallocated its lifetime
* will be the same as the interface object.
*
* Since: v0.6.4
*/
const char *
virInterfaceGetMACString(virInterfacePtr iface)
@ -407,6 +427,8 @@ virInterfaceGetMACString(virInterfacePtr iface)
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case
* of error. The caller must free() the returned value.
*
* Since: v0.6.4
*/
char *
virInterfaceGetXMLDesc(virInterfacePtr iface, unsigned int flags)
@ -458,6 +480,8 @@ virInterfaceGetXMLDesc(virInterfacePtr iface, unsigned int flags)
* interface object is no longer needed.
*
* Returns NULL in case of error, a pointer to the interface otherwise
*
* Since: v0.6.4
*/
virInterfacePtr
virInterfaceDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
@ -504,6 +528,8 @@ virInterfaceDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
* during the next reboot of the system running libvirtd.
*
* Returns 0 in case of success, -1 in case of error
*
* Since: v0.6.4
*/
int
virInterfaceUndefine(virInterfacePtr iface)
@ -547,6 +573,8 @@ virInterfaceUndefine(virInterfacePtr iface)
* undefined) if virInterfaceChangeRollback() is called.
*
* Returns 0 in case of success, -1 in case of error
*
* Since: v0.6.4
*/
int
virInterfaceCreate(virInterfacePtr iface, unsigned int flags)
@ -594,6 +622,8 @@ virInterfaceCreate(virInterfacePtr iface, unsigned int flags)
* interface definition will also bring the interface back up.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v0.6.4
*/
int
virInterfaceDestroy(virInterfacePtr iface, unsigned int flags)
@ -640,6 +670,8 @@ virInterfaceDestroy(virInterfacePtr iface, unsigned int flags)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
*
* Since: v0.6.4
*/
int
virInterfaceRef(virInterfacePtr iface)
@ -663,6 +695,8 @@ virInterfaceRef(virInterfacePtr iface)
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v0.6.4
*/
int
virInterfaceFree(virInterfacePtr iface)
@ -694,6 +728,8 @@ virInterfaceFree(virInterfacePtr iface)
* VIR_ERR_INVALID_OPERATION will be logged.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v0.9.2
*/
int
virInterfaceChangeBegin(virConnectPtr conn, unsigned int flags)
@ -734,6 +770,8 @@ virInterfaceChangeBegin(virConnectPtr conn, unsigned int flags)
* will be logged.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v0.9.2
*/
int
virInterfaceChangeCommit(virConnectPtr conn, unsigned int flags)
@ -774,6 +812,8 @@ virInterfaceChangeCommit(virConnectPtr conn, unsigned int flags)
* will be logged.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v0.9.2
*/
int
virInterfaceChangeRollback(virConnectPtr conn, unsigned int flags)
@ -809,6 +849,8 @@ virInterfaceChangeRollback(virConnectPtr conn, unsigned int flags)
* Determine if the interface is currently running
*
* Returns 1 if running, 0 if inactive, -1 on error
*
* Since: v0.7.3
*/
int
virInterfaceIsActive(virInterfacePtr iface)

89
src/libvirt-network.c
View File

@ -38,6 +38,8 @@ VIR_LOG_INIT("libvirt.network");
* call.
*
* Returns the virConnectPtr or NULL in case of failure.
*
* Since: v0.3.0
*/
virConnectPtr
virNetworkGetConnect(virNetworkPtr net)
@ -86,6 +88,8 @@ virNetworkGetConnect(virNetworkPtr net)
* extra allocated element set to NULL but not included in the return count,
* to make iteration easier. The caller is responsible for calling
* virNetworkFree() on each array element, then calling free() on @nets.
*
* Since: v0.10.2
*/
int
virConnectListAllNetworks(virConnectPtr conn,
@ -125,6 +129,8 @@ virConnectListAllNetworks(virConnectPtr conn,
* Provides the number of active networks.
*
* Returns the number of network found or -1 in case of error
*
* Since: v0.2.0
*/
int
virConnectNumOfNetworks(virConnectPtr conn)
@ -167,6 +173,8 @@ virConnectNumOfNetworks(virConnectPtr conn)
* to virConnectNumOfNetworks() and this call; you are only guaranteed that
* all currently active networks were listed if the return is less than
* @maxnames. The client must call free() on each returned name.
*
* Since: v0.2.0
*/
int
virConnectListNetworks(virConnectPtr conn, char **const names, int maxnames)
@ -202,6 +210,8 @@ virConnectListNetworks(virConnectPtr conn, char **const names, int maxnames)
* Provides the number of inactive networks.
*
* Returns the number of networks found or -1 in case of error
*
* Since: v0.2.0
*/
int
virConnectNumOfDefinedNetworks(virConnectPtr conn)
@ -244,6 +254,8 @@ virConnectNumOfDefinedNetworks(virConnectPtr conn)
* a call to virConnectNumOfDefinedNetworks() and this call; you are only
* guaranteed that all currently defined networks were listed if the return
* is less than @maxnames. The client must call free() on each returned name.
*
* Since: v0.2.0
*/
int
virConnectListDefinedNetworks(virConnectPtr conn, char **const names,
@ -285,6 +297,8 @@ virConnectListDefinedNetworks(virConnectPtr conn, char **const names,
*
* Returns a new network object or NULL in case of failure. If the
* network cannot be found, then VIR_ERR_NO_NETWORK error is raised.
*
* Since: v0.2.0
*/
virNetworkPtr
virNetworkLookupByName(virConnectPtr conn, const char *name)
@ -324,6 +338,8 @@ virNetworkLookupByName(virConnectPtr conn, const char *name)
*
* Returns a new network object or NULL in case of failure. If the
* network cannot be found, then VIR_ERR_NO_NETWORK error is raised.
*
* Since: v0.2.0
*/
virNetworkPtr
virNetworkLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
@ -360,6 +376,8 @@ virNetworkLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
*
* Returns a new network object or NULL in case of failure. If the
* network cannot be found, then VIR_ERR_NO_NETWORK error is raised.
*
* Since: v0.2.0
*/
virNetworkPtr
virNetworkLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
@ -399,6 +417,8 @@ virNetworkLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
* network object is no longer needed.
*
* Returns a new network object or NULL in case of failure
*
* Since: v0.2.0
*/
virNetworkPtr
virNetworkCreateXML(virConnectPtr conn, const char *xmlDesc)
@ -440,6 +460,8 @@ virNetworkCreateXML(virConnectPtr conn, const char *xmlDesc)
* network object is no longer needed.
*
* Returns a new network object or NULL in case of failure
*
* Since: v7.8.0
*/
virNetworkPtr
virNetworkCreateXMLFlags(virConnectPtr conn, const char *xmlDesc, unsigned int flags)
@ -480,6 +502,8 @@ virNetworkCreateXMLFlags(virConnectPtr conn, const char *xmlDesc, unsigned int f
* network object is no longer needed.
*
* Returns NULL in case of error, a pointer to the network otherwise
*
* Since: v0.2.0
*/
virNetworkPtr
virNetworkDefineXML(virConnectPtr conn, const char *xml)
@ -521,6 +545,8 @@ virNetworkDefineXML(virConnectPtr conn, const char *xml)
* network object is no longer needed.
*
* Returns NULL in case of error, a pointer to the network otherwise
*
* Since: v7.7.0
*/
virNetworkPtr
virNetworkDefineXMLFlags(virConnectPtr conn, const char *xml, unsigned int flags)
@ -556,6 +582,8 @@ virNetworkDefineXMLFlags(virConnectPtr conn, const char *xml, unsigned int flags
* Undefine a network but does not stop it if it is running
*
* Returns 0 in case of success, -1 in case of error
*
* Since: v0.2.0
*/
int
virNetworkUndefine(virNetworkPtr network)
@ -604,6 +632,8 @@ virNetworkUndefine(virNetworkPtr network)
* running state, its persistent configuration, or both.
*
* Returns 0 in case of success, -1 in case of error
*
* Since: v0.10.2
*/
int
virNetworkUpdate(virNetworkPtr network,
@ -670,6 +700,8 @@ virNetworkUpdate(virNetworkPtr network,
* moves from the defined to the running networks pools.
*
* Returns 0 in case of success, -1 in case of error
*
* Since: v0.2.0
*/
int
virNetworkCreate(virNetworkPtr network)
@ -710,6 +742,8 @@ virNetworkCreate(virNetworkPtr network)
* This function may require privileged access
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v0.2.0
*/
int
virNetworkDestroy(virNetworkPtr network)
@ -748,6 +782,8 @@ virNetworkDestroy(virNetworkPtr network)
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v0.2.0
*/
int
virNetworkFree(virNetworkPtr network)
@ -779,6 +815,8 @@ virNetworkFree(virNetworkPtr network)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
*
* Since: v0.6.0
*/
int
virNetworkRef(virNetworkPtr network)
@ -802,6 +840,8 @@ virNetworkRef(virNetworkPtr network)
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* its lifetime will be the same as the network object.
*
* Since: v0.2.0
*/
const char *
virNetworkGetName(virNetworkPtr network)
@ -824,6 +864,8 @@ virNetworkGetName(virNetworkPtr network)
* Get the UUID for a network
*
* Returns -1 in case of error, 0 in case of success
*
* Since: v0.2.0
*/
int
virNetworkGetUUID(virNetworkPtr network, unsigned char *uuid)
@ -854,6 +896,8 @@ virNetworkGetUUID(virNetworkPtr network, unsigned char *uuid)
* UUID see RFC4122.
*
* Returns -1 in case of error, 0 in case of success
*
* Since: v0.2.0
*/
int
virNetworkGetUUIDString(virNetworkPtr network, char *buf)
@ -889,6 +933,8 @@ virNetworkGetUUIDString(virNetworkPtr network, char *buf)
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case
* of error. The caller must free() the returned value.
*
* Since: v0.2.0
*/
char *
virNetworkGetXMLDesc(virNetworkPtr network, unsigned int flags)
@ -926,6 +972,8 @@ virNetworkGetXMLDesc(virNetworkPtr network, unsigned int flags)
*
* Returns a 0 terminated interface name, or NULL in case of
* error. The caller must free() the returned value.
*
* Since: v0.2.0
*/
char *
virNetworkGetBridgeName(virNetworkPtr network)
@ -964,6 +1012,8 @@ virNetworkGetBridgeName(virNetworkPtr network)
* machine boots.
*
* Returns -1 in case of error, 0 in case of success
*
* Since: v0.2.1
*/
int
virNetworkGetAutostart(virNetworkPtr network,
@ -1004,6 +1054,8 @@ virNetworkGetAutostart(virNetworkPtr network,
* when the host machine boots.
*
* Returns -1 in case of error, 0 in case of success
*
* Since: v0.2.1
*/
int
virNetworkSetAutostart(virNetworkPtr network,
@ -1042,6 +1094,8 @@ virNetworkSetAutostart(virNetworkPtr network,
* Determine if the network is currently running
*
* Returns 1 if running, 0 if inactive, -1 on error
*
* Since: v0.7.3
*/
int
virNetworkIsActive(virNetworkPtr net)
@ -1075,6 +1129,8 @@ virNetworkIsActive(virNetworkPtr net)
* which means it will still exist after shutting down
*
* Returns 1 if persistent, 0 if transient, -1 on error
*
* Since: v0.7.3
*/
int
virNetworkIsPersistent(virNetworkPtr net)
@ -1134,6 +1190,8 @@ virNetworkIsPersistent(virNetworkPtr net)
* be passed to the virConnectNetworkEventDeregisterAny() method.
*
* Returns a callback identifier on success, -1 on failure.
*
* Since: v1.2.1
*/
int
virConnectNetworkEventRegisterAny(virConnectPtr conn,
@ -1195,6 +1253,8 @@ virConnectNetworkEventRegisterAny(virConnectPtr conn,
* value obtained from a previous virConnectNetworkEventRegisterAny() method.
*
* Returns 0 on success, -1 on failure
*
* Since: v1.2.1
*/
int
virConnectNetworkEventDeregisterAny(virConnectPtr conn,
@ -1297,6 +1357,7 @@ virConnectNetworkEventDeregisterAny(virConnectPtr conn,
* Returns the number of leases found or -1 and sets @leases to NULL in
* case of error.
*
* Since: v1.2.6
*/
int
virNetworkGetDHCPLeases(virNetworkPtr network,
@ -1338,6 +1399,8 @@ virNetworkGetDHCPLeases(virNetworkPtr network,
* @lease: pointer to a leases object
*
* Frees all the memory occupied by @lease.
*
* Since: v1.2.6
*/
void
virNetworkDHCPLeaseFree(virNetworkDHCPLeasePtr lease)
@ -1366,6 +1429,8 @@ virNetworkDHCPLeaseFree(virNetworkDHCPLeasePtr lease)
*
* Returns a new network port object or NULL in case of failure. If the
* network port cannot be found, then VIR_ERR_NO_NETWORK_PORT error is raised.
*
* Since: v5.5.0
*/
virNetworkPortPtr
virNetworkPortLookupByUUID(virNetworkPtr net,
@ -1403,6 +1468,8 @@ virNetworkPortLookupByUUID(virNetworkPtr net,
*
* Returns a new network port object or NULL in case of failure. If the
* network port cannot be found, then VIR_ERR_NO_NETWORK_PORT error is raised.
*
* Since: v5.5.0
*/
virNetworkPortPtr
virNetworkPortLookupByUUIDString(virNetworkPtr net,
@ -1443,6 +1510,8 @@ virNetworkPortLookupByUUIDString(virNetworkPtr net,
* includes bandwidth parameters.
*
* Returns -1 in case of error, 0 in case of success.
*
* Since: v5.5.0
*/
int
virNetworkPortSetParameters(virNetworkPortPtr port,
@ -1491,6 +1560,8 @@ virNetworkPortSetParameters(virNetworkPortPtr port,
* on success.
*
* Returns -1 in case of error, 0 in case of success.
*
* Since: v5.5.0
*/
int
virNetworkPortGetParameters(virNetworkPortPtr port,
@ -1535,6 +1606,8 @@ virNetworkPortGetParameters(virNetworkPortPtr port,
* network port object is no longer needed.
*
* Returns a new network port object or NULL in case of failure
*
* Since: v5.5.0
*/
virNetworkPortPtr
virNetworkPortCreateXML(virNetworkPtr net,
@ -1573,6 +1646,8 @@ virNetworkPortCreateXML(virNetworkPtr net,
* call.
*
* Returns the virNetworkPtr or NULL in case of failure.
*
* Since: v5.5.0
*/
virNetworkPtr
virNetworkPortGetNetwork(virNetworkPortPtr port)
@ -1597,6 +1672,8 @@ virNetworkPortGetNetwork(virNetworkPortPtr port)
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
* the caller must free() the returned value.
*
* Since: v5.5.0
*/
char *
virNetworkPortGetXMLDesc(virNetworkPortPtr port,
@ -1634,6 +1711,8 @@ virNetworkPortGetXMLDesc(virNetworkPortPtr port,
* Get the UUID for a network port
*
* Returns -1 in case of error, 0 in case of success
*
* Since: v5.5.0
*/
int
virNetworkPortGetUUID(virNetworkPortPtr port,
@ -1665,6 +1744,8 @@ virNetworkPortGetUUID(virNetworkPortPtr port,
* UUID see RFC4122.
*
* Returns -1 in case of error, 0 in case of success
*
* Since: v5.5.0
*/
int
virNetworkPortGetUUIDString(virNetworkPortPtr port,
@ -1697,6 +1778,8 @@ virNetworkPortGetUUIDString(virNetworkPortPtr port,
* port.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v5.5.0
*/
int
virNetworkPortDelete(virNetworkPortPtr port,
@ -1745,6 +1828,8 @@ virNetworkPortDelete(virNetworkPortPtr port,
* in the return count, to make iteration easier. The caller is responsible
* for calling virNetworkPortFree() on each array element, then calling
* free() on @ports.
*
* Since: v5.5.0
*/
int
virNetworkListAllPorts(virNetworkPtr network,
@ -1782,6 +1867,8 @@ virNetworkListAllPorts(virNetworkPtr network,
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v5.5.0
*/
int
virNetworkPortFree(virNetworkPortPtr port)
@ -1813,6 +1900,8 @@ virNetworkPortFree(virNetworkPortPtr port)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
*
* Since: v5.5.0
*/
int
virNetworkPortRef(virNetworkPortPtr port)

54
src/libvirt-nodedev.c
View File

@ -40,6 +40,8 @@ VIR_LOG_INIT("libvirt.nodedev");
* will be restricted to devices with the specified capability
*
* Returns the number of node devices or -1 in case of error
*
* Since: v0.5.0
*/
int
virNodeNumOfDevices(virConnectPtr conn, const char *cap, unsigned int flags)
@ -86,6 +88,8 @@ virNodeNumOfDevices(virConnectPtr conn, const char *cap, unsigned int flags)
* count, to make iteration easier. The caller is responsible for calling
* virNodeDeviceFree() on each array element, then calling free() on
* @devices.
*
* Since: v0.10.2
*/
int
virConnectListAllNodeDevices(virConnectPtr conn,
@ -135,6 +139,8 @@ virConnectListAllNodeDevices(virConnectPtr conn,
* will be restricted to devices with the specified capability
*
* Returns the number of node devices found or -1 in case of error
*
* Since: v0.5.0
*/
int
virNodeListDevices(virConnectPtr conn,
@ -178,6 +184,8 @@ virNodeListDevices(virConnectPtr conn,
* node device object is no longer needed.
*
* Returns a virNodeDevicePtr if found, NULL otherwise.
*
* Since: v0.5.0
*/
virNodeDevicePtr
virNodeDeviceLookupByName(virConnectPtr conn, const char *name)
@ -218,6 +226,8 @@ virNodeDeviceLookupByName(virConnectPtr conn, const char *name)
* node device object is no longer needed.
*
* Returns a virNodeDevicePtr if found, NULL otherwise.
*
* Since: v1.0.3
*/
virNodeDevicePtr
virNodeDeviceLookupSCSIHostByWWN(virConnectPtr conn,
@ -260,6 +270,8 @@ virNodeDeviceLookupSCSIHostByWWN(virConnectPtr conn,
* the device.
*
* Returns the XML document, or NULL on error
*
* Since: v0.5.0
*/
char *
virNodeDeviceGetXMLDesc(virNodeDevicePtr dev, unsigned int flags)
@ -293,6 +305,8 @@ virNodeDeviceGetXMLDesc(virNodeDevicePtr dev, unsigned int flags)
* Just return the device name
*
* Returns the device name or NULL in case of error
*
* Since: v0.5.0
*/
const char *
virNodeDeviceGetName(virNodeDevicePtr dev)
@ -315,6 +329,8 @@ virNodeDeviceGetName(virNodeDevicePtr dev)
*
* Returns the name of the device's parent, or NULL if an
* error occurred or when the device has no parent.
*
* Since: v0.5.0
*/
const char *
virNodeDeviceGetParent(virNodeDevicePtr dev)
@ -346,6 +362,8 @@ virNodeDeviceGetParent(virNodeDevicePtr dev)
*
* Returns the number of capabilities supported by the device or -1
* in case of error.
*
* Since: v0.5.0
*/
int
virNodeDeviceNumOfCaps(virNodeDevicePtr dev)
@ -382,6 +400,8 @@ virNodeDeviceNumOfCaps(virNodeDevicePtr dev)
*
* Returns the number of capability names listed in @names or -1
* in case of error.
*
* Since: v0.5.0
*/
int
virNodeDeviceListCaps(virNodeDevicePtr dev,
@ -421,6 +441,8 @@ virNodeDeviceListCaps(virNodeDevicePtr dev,
* this was the last reference.
*
* Returns the 0 for success, -1 for error.
*
* Since: v0.5.0
*/
int
virNodeDeviceFree(virNodeDevicePtr dev)
@ -452,6 +474,8 @@ virNodeDeviceFree(virNodeDevicePtr dev)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
*
* Since: v0.6.0
*/
int
virNodeDeviceRef(virNodeDevicePtr dev)
@ -490,6 +514,8 @@ virNodeDeviceRef(virNodeDevicePtr dev)
* API should be used instead.
*
* Returns 0 in case of success, -1 in case of failure.
*
* Since: v0.6.1
*/
int
virNodeDeviceDettach(virNodeDevicePtr dev)
@ -543,6 +569,8 @@ virNodeDeviceDettach(virNodeDevicePtr dev)
* to the node using the virNodeDeviceReAttach() method.
*
* Returns 0 in case of success, -1 in case of failure.
*
* Since: v1.0.5
*/
int
virNodeDeviceDetachFlags(virNodeDevicePtr dev,
@ -588,6 +616,8 @@ virNodeDeviceDetachFlags(virNodeDevicePtr dev,
* If the device is currently in use by a guest, this method may fail.
*
* Returns 0 in case of success, -1 in case of failure.
*
* Since: v0.6.1
*/
int
virNodeDeviceReAttach(virNodeDevicePtr dev)
@ -631,6 +661,8 @@ virNodeDeviceReAttach(virNodeDevicePtr dev)
* this function may fail.
*
* Returns 0 in case of success, -1 in case of failure.
*
* Since: v0.6.1
*/
int
virNodeDeviceReset(virNodeDevicePtr dev)
@ -671,6 +703,8 @@ virNodeDeviceReset(virNodeDevicePtr dev)
* node device object is no longer needed.
*
* Returns a node device object if successful, NULL in case of failure
*
* Since: v0.6.3
*/
virNodeDevicePtr
virNodeDeviceCreateXML(virConnectPtr conn,
@ -710,6 +744,8 @@ virNodeDeviceCreateXML(virConnectPtr conn,
* may require privileged access.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v0.6.3
*/
int
virNodeDeviceDestroy(virNodeDevicePtr dev)
@ -750,6 +786,8 @@ virNodeDeviceDestroy(virNodeDevicePtr dev)
* node device object is no longer needed.
*
* Returns a node device object if successful, NULL in case of failure
*
* Since: v7.3.0
*/
virNodeDevicePtr
virNodeDeviceDefineXML(virConnectPtr conn,
@ -789,6 +827,8 @@ virNodeDeviceDefineXML(virConnectPtr conn,
* operating system. This function may require privileged access.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v7.3.0
*/
int
virNodeDeviceUndefine(virNodeDevicePtr dev,
@ -826,6 +866,8 @@ virNodeDeviceUndefine(virNodeDevicePtr dev,
* Start a defined node device:
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v7.3.0
*/
int
virNodeDeviceCreate(virNodeDevicePtr dev,
@ -889,6 +931,8 @@ virNodeDeviceCreate(virNodeDevicePtr dev,
* be passed to the virConnectNodeDeviceEventDeregisterAny() method.
*
* Returns a callback identifier on success, -1 on failure.
*
* Since: v2.2.0
*/
int
virConnectNodeDeviceEventRegisterAny(virConnectPtr conn,
@ -953,6 +997,8 @@ virConnectNodeDeviceEventRegisterAny(virConnectPtr conn,
* value obtained from a previous virConnectNodeDeviceEventRegisterAny() method.
*
* Returns 0 on success, -1 on failure.
*
* Since: v2.2.0
*/
int
virConnectNodeDeviceEventDeregisterAny(virConnectPtr conn,
@ -990,6 +1036,8 @@ virConnectNodeDeviceEventDeregisterAny(virConnectPtr conn,
* boots or the parent device becomes available.
*
* Returns -1 in case of error, 0 in case of success
*
* Since: v7.8.0
*/
int
virNodeDeviceSetAutostart(virNodeDevicePtr dev,
@ -1029,6 +1077,8 @@ virNodeDeviceSetAutostart(virNodeDevicePtr dev,
* becomes available.
*
* Returns -1 in case of error, 0 in case of success
*
* Since: v7.8.0
*/
int
virNodeDeviceGetAutostart(virNodeDevicePtr dev,
@ -1065,6 +1115,8 @@ virNodeDeviceGetAutostart(virNodeDevicePtr dev,
* which means it will still exist after shutting down
*
* Returns 1 if persistent, 0 if transient, -1 on error
*
* Since: v7.8.0
*/
int
virNodeDeviceIsPersistent(virNodeDevicePtr dev)
@ -1098,6 +1150,8 @@ virNodeDeviceIsPersistent(virNodeDevicePtr dev)
* Determine if the node device is currently active
*
* Returns 1 if active, 0 if inactive, -1 on error
*
* Since: v7.8.0
*/
int virNodeDeviceIsActive(virNodeDevicePtr dev)
{

48
src/libvirt-nwfilter.c
View File

@ -35,6 +35,8 @@ VIR_LOG_INIT("libvirt.nwfilter");
* Provides the number of nwfilters.
*
* Returns the number of nwfilters found or -1 in case of error
*
* Since: v0.8.0
*/
int
virConnectNumOfNWFilters(virConnectPtr conn)
@ -77,6 +79,8 @@ virConnectNumOfNWFilters(virConnectPtr conn)
* have an extra allocated element set to NULL but not included in the return count,
* to make iteration easier. The caller is responsible for calling
* virNWFilterFree() on each array element, then calling free() on @filters.
*
* Since: v0.10.2
*/
int
virConnectListAllNWFilters(virConnectPtr conn,
@ -121,6 +125,8 @@ virConnectListAllNWFilters(virConnectPtr conn,
* virConnectListAllNWFilters().
*
* Returns the number of network filters found or -1 in case of error
*
* Since: v0.8.0
*/
int
virConnectListNWFilters(virConnectPtr conn, char **const names, int maxnames)
@ -161,6 +167,8 @@ virConnectListNWFilters(virConnectPtr conn, char **const names, int maxnames)
*
* Returns a new nwfilter object or NULL in case of failure. If the
* network filter cannot be found, then VIR_ERR_NO_NWFILTER error is raised.
*
* Since: v0.8.0
*/
virNWFilterPtr
virNWFilterLookupByName(virConnectPtr conn, const char *name)
@ -200,6 +208,8 @@ virNWFilterLookupByName(virConnectPtr conn, const char *name)
*
* Returns a new nwfilter object or NULL in case of failure. If the
* nwfdilter cannot be found, then VIR_ERR_NO_NWFILTER error is raised.
*
* Since: v0.8.0
*/
virNWFilterPtr
virNWFilterLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
@ -239,6 +249,8 @@ virNWFilterLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
*
* Returns a new nwfilter object or NULL in case of failure. If the
* nwfilter cannot be found, then VIR_ERR_NO_NWFILTER error is raised.
*
* Since: v0.8.0
*/
virNWFilterPtr
virNWFilterLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
@ -274,6 +286,8 @@ virNWFilterLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v0.8.0
*/
int
virNWFilterFree(virNWFilterPtr nwfilter)
@ -297,6 +311,8 @@ virNWFilterFree(virNWFilterPtr nwfilter)
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* its lifetime will be the same as the nwfilter object.
*
* Since: v0.8.0
*/
const char *
virNWFilterGetName(virNWFilterPtr nwfilter)
@ -319,6 +335,8 @@ virNWFilterGetName(virNWFilterPtr nwfilter)
* Get the UUID for a network filter
*
* Returns -1 in case of error, 0 in case of success
*
* Since: v0.8.0
*/
int
virNWFilterGetUUID(virNWFilterPtr nwfilter, unsigned char *uuid)
@ -349,6 +367,8 @@ virNWFilterGetUUID(virNWFilterPtr nwfilter, unsigned char *uuid)
* UUID see RFC4122.
*
* Returns -1 in case of error, 0 in case of success
*
* Since: v0.8.0
*/
int
virNWFilterGetUUIDString(virNWFilterPtr nwfilter, char *buf)
@ -381,6 +401,8 @@ virNWFilterGetUUIDString(virNWFilterPtr nwfilter, char *buf)
* nwfilter object is no longer needed.
*
* Returns a new nwfilter object or NULL in case of failure
*
* Since: v0.8.0
*/
virNWFilterPtr
virNWFilterDefineXML(virConnectPtr conn, const char *xmlDesc)
@ -422,6 +444,8 @@ virNWFilterDefineXML(virConnectPtr conn, const char *xmlDesc)
* nwfilter object is no longer needed.
*
* Returns a new nwfilter object or NULL in case of failure
*
* Since: v7.7.0
*/
virNWFilterPtr
virNWFilterDefineXMLFlags(virConnectPtr conn, const char *xmlDesc, unsigned int flags)
@ -459,6 +483,8 @@ virNWFilterDefineXMLFlags(virConnectPtr conn, const char *xmlDesc, unsigned int
* associated virNWFilterPtr object.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v0.8.0
*/
int
virNWFilterUndefine(virNWFilterPtr nwfilter)
@ -499,6 +525,8 @@ virNWFilterUndefine(virNWFilterPtr nwfilter)
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case
* of error. The caller must free() the returned value.
*
* Since: v0.8.0
*/
char *
virNWFilterGetXMLDesc(virNWFilterPtr nwfilter, unsigned int flags)
@ -543,6 +571,8 @@ virNWFilterGetXMLDesc(virNWFilterPtr nwfilter, unsigned int flags)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
*
* Since: v0.8.0
*/
int
virNWFilterRef(virNWFilterPtr nwfilter)
@ -574,6 +604,8 @@ virNWFilterRef(virNWFilterPtr nwfilter)
* have an extra allocated element set to NULL but not included in the return count,
* to make iteration easier. The caller is responsible for calling
* virNWFilterFree() on each array element, then calling free() on @filters.
*
* Since: v4.5.0
*/
int
virConnectListAllNWFilterBindings(virConnectPtr conn,
@ -620,6 +652,8 @@ virConnectListAllNWFilterBindings(virConnectPtr conn,
* Returns a new binding object or NULL in case of failure. If the
* network filter cannot be found, then VIR_ERR_NO_NWFILTER_BINDING
* error is raised.
*
* Since: v4.5.0
*/
virNWFilterBindingPtr
virNWFilterBindingLookupByPortDev(virConnectPtr conn, const char *portdev)
@ -655,6 +689,8 @@ virNWFilterBindingLookupByPortDev(virConnectPtr conn, const char *portdev)
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v4.5.0
*/
int
virNWFilterBindingFree(virNWFilterBindingPtr binding)
@ -678,6 +714,8 @@ virNWFilterBindingFree(virNWFilterBindingPtr binding)
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* its lifetime will be the same as the binding object.
*
* Since: v4.5.0
*/
const char *
virNWFilterBindingGetPortDev(virNWFilterBindingPtr binding)
@ -700,6 +738,8 @@ virNWFilterBindingGetPortDev(virNWFilterBindingPtr binding)
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* its lifetime will be the same as the binding object.
*
* Since: v4.5.0
*/
const char *
virNWFilterBindingGetFilterName(virNWFilterBindingPtr binding)
@ -734,6 +774,8 @@ virNWFilterBindingGetFilterName(virNWFilterBindingPtr binding)
* binding object is no longer needed.
*
* Returns a new binding object or NULL in case of failure
*
* Since: v4.5.0
*/
virNWFilterBindingPtr
virNWFilterBindingCreateXML(virConnectPtr conn, const char *xml, unsigned int flags)
@ -775,6 +817,8 @@ virNWFilterBindingCreateXML(virConnectPtr conn, const char *xml, unsigned int fl
* would be accomplished by using virNWFilterBindingCreateXML.
*
* Returns 0 in case of success and -1 in case of failure.
*
* Since: v4.5.0
*/
int
virNWFilterBindingDelete(virNWFilterBindingPtr binding)
@ -815,6 +859,8 @@ virNWFilterBindingDelete(virNWFilterBindingPtr binding)
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case
* of error. The caller must free() the returned value.
*
* Since: v4.5.0
*/
char *
virNWFilterBindingGetXMLDesc(virNWFilterBindingPtr binding, unsigned int flags)
@ -859,6 +905,8 @@ virNWFilterBindingGetXMLDesc(virNWFilterBindingPtr binding, unsigned int flags)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
*
* Since: v4.5.0
*/
int
virNWFilterBindingRef(virNWFilterBindingPtr binding)

40
src/libvirt-secret.c
View File

@ -35,6 +35,8 @@ VIR_LOG_INIT("libvirt.secret");
* counter on the connection is not increased by this call.
*
* Returns the virConnectPtr or NULL in case of failure.
*
* Since: v0.7.1
*/
virConnectPtr
virSecretGetConnect(virSecretPtr secret)
@ -56,6 +58,8 @@ virSecretGetConnect(virSecretPtr secret)
* Fetch number of currently defined secrets.
*
* Returns the number currently defined secrets.
*
* Since: v0.7.1
*/
int
virConnectNumOfSecrets(virConnectPtr conn)
@ -116,6 +120,8 @@ virConnectNumOfSecrets(virConnectPtr conn)
* have an extra allocated element set to NULL but not included in the return count,
* to make iteration easier. The caller is responsible for calling
* virSecretFree() on each array element, then calling free() on @secrets.
*
* Since: v0.10.2
*/
int
virConnectListAllSecrets(virConnectPtr conn,
@ -160,6 +166,8 @@ virConnectListAllSecrets(virConnectPtr conn,
* virConnectListAllSecrets().
*
* Returns the number of UUIDs provided in the array, or -1 on failure.
*
* Since: v0.7.1
*/
int
virConnectListSecrets(virConnectPtr conn, char **uuids, int maxuuids)
@ -202,6 +210,8 @@ virConnectListSecrets(virConnectPtr conn, char **uuids, int maxuuids)
*
* Returns a new secret object or NULL in case of failure. If the
* secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
*
* Since: v0.7.1
*/
virSecretPtr
virSecretLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
@ -243,6 +253,8 @@ virSecretLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
*
* Returns a new secret object or NULL in case of failure. If the
* secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
*
* Since: v0.7.1
*/
virSecretPtr
virSecretLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
@ -285,6 +297,8 @@ virSecretLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
*
* Returns a new secret object or NULL in case of failure. If the
* secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
*
* Since: v0.7.1
*/
virSecretPtr
virSecretLookupByUsage(virConnectPtr conn,
@ -332,6 +346,8 @@ virSecretLookupByUsage(virConnectPtr conn,
* secret object is no longer needed.
*
* Returns a secret on success, NULL on failure.
*
* Since: v0.7.1
*/
virSecretPtr
virSecretDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
@ -370,6 +386,8 @@ virSecretDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
*
* Returns 0 on success with the uuid buffer being filled, or
* -1 upon failure.
*
* Since: v0.7.1
*/
int
virSecretGetUUID(virSecretPtr secret, unsigned char *uuid)
@ -400,6 +418,8 @@ virSecretGetUUID(virSecretPtr secret, unsigned char *uuid)
* UUID see RFC4122.
*
* Returns -1 in case of error, 0 in case of success
*
* Since: v0.7.1
*/
int
virSecretGetUUIDString(virSecretPtr secret, char *buf)
@ -432,6 +452,8 @@ virSecretGetUUIDString(virSecretPtr secret, char *buf)
*
* Returns a positive integer identifying the type of object,
* or -1 upon error.
*
* Since: v0.7.1
*/
int
virSecretGetUsageType(virSecretPtr secret)
@ -461,6 +483,8 @@ virSecretGetUsageType(virSecretPtr secret)
*
* Returns a string identifying the object using the secret,
* or NULL upon error
*
* Since: v0.7.1
*/
const char *
virSecretGetUsageID(virSecretPtr secret)
@ -484,6 +508,8 @@ virSecretGetUsageID(virSecretPtr secret)
*
* Returns the XML document on success, NULL on failure. The caller must
* free() the XML.
*
* Since: v0.7.1
*/
char *
virSecretGetXMLDesc(virSecretPtr secret, unsigned int flags)
@ -524,6 +550,8 @@ virSecretGetXMLDesc(virSecretPtr secret, unsigned int flags)
* Sets the value of a secret.
*
* Returns 0 on success, -1 on failure.
*
* Since: v0.7.1
*/
int
virSecretSetValue(virSecretPtr secret, const unsigned char *value,
@ -569,6 +597,8 @@ virSecretSetValue(virSecretPtr secret, const unsigned char *value,
*
* Returns the secret value on success, NULL on failure. The caller must
* free() the secret value.
*
* Since: v0.7.1
*/
unsigned char *
virSecretGetValue(virSecretPtr secret, size_t *value_size, unsigned int flags)
@ -610,6 +640,8 @@ virSecretGetValue(virSecretPtr secret, size_t *value_size, unsigned int flags)
* virSecretPtr object.
*
* Returns 0 on success, -1 on failure.
*
* Since: v0.7.1
*/
int
virSecretUndefine(virSecretPtr secret)
@ -657,6 +689,8 @@ virSecretUndefine(virSecretPtr secret)
* increment the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
*
* Since: v0.7.1
*/
int
virSecretRef(virSecretPtr secret)
@ -679,6 +713,8 @@ virSecretRef(virSecretPtr secret)
* Release the secret handle. The underlying secret continues to exist.
*
* Returns 0 on success, or -1 on error
*
* Since: v0.7.1
*/
int
virSecretFree(virSecretPtr secret)
@ -728,6 +764,8 @@ virSecretFree(virSecretPtr secret)
* be passed to the virConnectSecretEventDeregisterAny() method.
*
* Returns a callback identifier on success, -1 on failure.
*
* Since: v3.0.0
*/
int
virConnectSecretEventRegisterAny(virConnectPtr conn,
@ -794,6 +832,8 @@ virConnectSecretEventRegisterAny(virConnectPtr conn,
* value obtained from a previous virConnectSecretEventRegisterAny() method.
*
* Returns 0 on success, -1 on failure.
*
* Since: v3.0.0
*/
int
virConnectSecretEventDeregisterAny(virConnectPtr conn,

114
src/libvirt-storage.c
View File

@ -37,6 +37,8 @@ VIR_LOG_INIT("libvirt.storage");
* call.
*
* Returns the virConnectPtr or NULL in case of failure.
*
* Since: v0.4.1
*/
virConnectPtr
virStoragePoolGetConnect(virStoragePoolPtr pool)
@ -104,6 +106,8 @@ virStoragePoolGetConnect(virStoragePoolPtr pool)
* in the return count, to make iteration easier. The caller is responsible
* for calling virStoragePoolFree() on each array element, then calling
* free() on @pools.
*
* Since: v0.10.2
*/
int
virConnectListAllStoragePools(virConnectPtr conn,
@ -143,6 +147,8 @@ virConnectListAllStoragePools(virConnectPtr conn,
* Provides the number of active storage pools
*
* Returns the number of pools found, or -1 on error
*
* Since: v0.4.1
*/
int
virConnectNumOfStoragePools(virConnectPtr conn)
@ -187,6 +193,8 @@ virConnectNumOfStoragePools(virConnectPtr conn)
* virConnectNumOfStoragePools() and this call; you are only guaranteed
* that all currently active pools were listed if the return is less than
* @maxnames. The client must call free() on each returned name.
*
* Since: v0.4.1
*/
int
virConnectListStoragePools(virConnectPtr conn,
@ -224,6 +232,8 @@ virConnectListStoragePools(virConnectPtr conn,
* Provides the number of inactive storage pools
*
* Returns the number of pools found, or -1 on error
*
* Since: v0.4.1
*/
int
virConnectNumOfDefinedStoragePools(virConnectPtr conn)
@ -268,6 +278,8 @@ virConnectNumOfDefinedStoragePools(virConnectPtr conn)
* a call to virConnectNumOfDefinedStoragePools() and this call; you are only
* guaranteed that all currently defined pools were listed if the return
* is less than @maxnames. The client must call free() on each returned name.
*
* Since: v0.4.1
*/
int
virConnectListDefinedStoragePools(virConnectPtr conn,
@ -318,6 +330,8 @@ virConnectListDefinedStoragePools(virConnectPtr conn,
* Returns an xml document consisting of a SourceList element
* containing a source document appropriate to the given pool
* type for each discovered source.
*
* Since: v0.4.5
*/
char *
virConnectFindStoragePoolSources(virConnectPtr conn,
@ -361,6 +375,8 @@ virConnectFindStoragePoolSources(virConnectPtr conn,
* storage pool object is no longer needed.
*
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
*
* Since: v0.4.1
*/
virStoragePoolPtr
virStoragePoolLookupByName(virConnectPtr conn,
@ -400,6 +416,8 @@ virStoragePoolLookupByName(virConnectPtr conn,
* storage pool object is no longer needed.
*
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
*
* Since: v0.4.1
*/
virStoragePoolPtr
virStoragePoolLookupByUUID(virConnectPtr conn,
@ -439,6 +457,8 @@ virStoragePoolLookupByUUID(virConnectPtr conn,
* storage pool object is no longer needed.
*
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
*
* Since: v0.4.1
*/
virStoragePoolPtr
virStoragePoolLookupByUUIDString(virConnectPtr conn,
@ -477,6 +497,8 @@ virStoragePoolLookupByUUIDString(virConnectPtr conn,
* storage pool object is no longer needed.
*
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
*
* Since: v0.4.1
*/
virStoragePoolPtr
virStoragePoolLookupByVolume(virStorageVolPtr vol)
@ -516,6 +538,8 @@ virStoragePoolLookupByVolume(virStorageVolPtr vol)
* storage pool object is no longer needed.
*
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
*
* Since: v4.1.0
*/
virStoragePoolPtr
virStoragePoolLookupByTargetPath(virConnectPtr conn,
@ -557,6 +581,8 @@ virStoragePoolLookupByTargetPath(virConnectPtr conn,
* storage pool object is no longer needed.
*
* Returns a virStoragePoolPtr object, or NULL if creation failed
*
* Since: v0.4.1
*/
virStoragePoolPtr
virStoragePoolCreateXML(virConnectPtr conn,
@ -600,6 +626,8 @@ virStoragePoolCreateXML(virConnectPtr conn,
* storage pool object is no longer needed.
*
* Returns a virStoragePoolPtr object, or NULL if creation failed
*
* Since: v0.4.1
*/
virStoragePoolPtr
virStoragePoolDefineXML(virConnectPtr conn,
@ -641,6 +669,8 @@ virStoragePoolDefineXML(virConnectPtr conn,
* Build the underlying storage pool
*
* Returns 0 on success, or -1 upon failure
*
* Since: v0.4.1
*/
int
virStoragePoolBuild(virStoragePoolPtr pool,
@ -679,6 +709,8 @@ virStoragePoolBuild(virStoragePoolPtr pool,
* Undefine an inactive storage pool
*
* Returns 0 on success, -1 on failure
*
* Since: v0.4.1
*/
int
virStoragePoolUndefine(virStoragePoolPtr pool)
@ -717,6 +749,8 @@ virStoragePoolUndefine(virStoragePoolPtr pool)
* Starts an inactive storage pool
*
* Returns 0 on success, or -1 if it could not be started
*
* Since: v0.4.1
*/
int
virStoragePoolCreate(virStoragePoolPtr pool,
@ -759,6 +793,8 @@ virStoragePoolCreate(virStoragePoolPtr pool,
* the associated virStoragePoolPtr object.
*
* Returns 0 on success, or -1 if it could not be destroyed
*
* Since: v0.4.1
*/
int
virStoragePoolDestroy(virStoragePoolPtr pool)
@ -799,6 +835,8 @@ virStoragePoolDestroy(virStoragePoolPtr pool)
* itself is not free'd.
*
* Returns 0 on success, or -1 if it could not be obliterate
*
* Since: v0.4.1
*/
int
virStoragePoolDelete(virStoragePoolPtr pool,
@ -838,6 +876,8 @@ virStoragePoolDelete(virStoragePoolPtr pool,
* it. Does not change the state of the pool on the host.
*
* Returns 0 on success, or -1 if it could not be free'd.
*
* Since: v0.4.1
*/
int
virStoragePoolFree(virStoragePoolPtr pool)
@ -870,6 +910,8 @@ virStoragePoolFree(virStoragePoolPtr pool)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
*
* Since: v0.6.0
*/
int
virStoragePoolRef(virStoragePoolPtr pool)
@ -895,6 +937,8 @@ virStoragePoolRef(virStoragePoolPtr pool)
* new devices at the OS layer
*
* Returns 0 if the volume list was refreshed, -1 on failure
*
* Since: v0.4.1
*/
int
virStoragePoolRefresh(virStoragePoolPtr pool,
@ -933,6 +977,8 @@ virStoragePoolRefresh(virStoragePoolPtr pool,
* Fetch the locally unique name of the storage pool
*
* Returns the name of the pool, or NULL on error
*
* Since: v0.4.1
*/
const char*
virStoragePoolGetName(virStoragePoolPtr pool)
@ -955,6 +1001,8 @@ virStoragePoolGetName(virStoragePoolPtr pool)
* Fetch the globally unique ID of the storage pool
*
* Returns 0 on success, or -1 on error;
*
* Since: v0.4.1
*/
int
virStoragePoolGetUUID(virStoragePoolPtr pool,
@ -985,6 +1033,8 @@ virStoragePoolGetUUID(virStoragePoolPtr pool,
* Fetch the globally unique ID of the storage pool as a string
*
* Returns 0 on success, or -1 on error;
*
* Since: v0.4.1
*/
int
virStoragePoolGetUUIDString(virStoragePoolPtr pool,
@ -1015,6 +1065,8 @@ virStoragePoolGetUUIDString(virStoragePoolPtr pool,
* such as free space / usage summary
*
* Returns 0 on success, or -1 on failure.
*
* Since: v0.4.1
*/
int
virStoragePoolGetInfo(virStoragePoolPtr pool,
@ -1059,6 +1111,8 @@ virStoragePoolGetInfo(virStoragePoolPtr pool,
* into the virStoragePoolCreateXML method.
*
* Returns a XML document (caller frees), or NULL on error
*
* Since: v0.4.1
*/
char *
virStoragePoolGetXMLDesc(virStoragePoolPtr pool,
@ -1097,6 +1151,8 @@ virStoragePoolGetXMLDesc(virStoragePoolPtr pool,
* whether the pool is automatically started at boot time
*
* Returns 0 on success, -1 on failure
*
* Since: v0.4.1
*/
int
virStoragePoolGetAutostart(virStoragePoolPtr pool,
@ -1137,6 +1193,8 @@ virStoragePoolGetAutostart(virStoragePoolPtr pool,
* when the host machine boots.
*
* Returns 0 on success, -1 on failure
*
* Since: v0.4.1
*/
int
virStoragePoolSetAutostart(virStoragePoolPtr pool,
@ -1185,6 +1243,8 @@ virStoragePoolSetAutostart(virStoragePoolPtr pool,
* in the return count, to make iteration easier. The caller is responsible
* for calling virStorageVolFree() on each array element, then calling
* free() on @vols.
*
* Since: v0.10.2
*/
int
virStoragePoolListAllVolumes(virStoragePoolPtr pool,
@ -1221,6 +1281,8 @@ virStoragePoolListAllVolumes(virStoragePoolPtr pool,
* Fetch the number of storage volumes within a pool
*
* Returns the number of storage pools, or -1 on failure
*
* Since: v0.4.1
*/
int
virStoragePoolNumOfVolumes(virStoragePoolPtr pool)
@ -1260,6 +1322,8 @@ virStoragePoolNumOfVolumes(virStoragePoolPtr pool)
* virStoragePoolListAllVolumes().
*
* Returns the number of names fetched, or -1 on error
*
* Since: v0.4.1
*/
int
virStoragePoolListVolumes(virStoragePoolPtr pool,
@ -1299,6 +1363,8 @@ virStoragePoolListVolumes(virStoragePoolPtr pool,
* call.
*
* Returns the virConnectPtr or NULL in case of failure.
*
* Since: v0.4.1
*/
virConnectPtr
virStorageVolGetConnect(virStorageVolPtr vol)
@ -1325,6 +1391,8 @@ virStorageVolGetConnect(virStorageVolPtr vol)
* storage volume object is no longer needed.
*
* Returns a storage volume, or NULL if not found / error
*
* Since: v0.4.1
*/
virStorageVolPtr
virStorageVolLookupByName(virStoragePoolPtr pool,
@ -1365,6 +1433,8 @@ virStorageVolLookupByName(virStoragePoolPtr pool,
* storage volume object is no longer needed.
*
* Returns a storage volume, or NULL if not found / error
*
* Since: v0.4.1
*/
virStorageVolPtr
virStorageVolLookupByKey(virConnectPtr conn,
@ -1405,6 +1475,8 @@ virStorageVolLookupByKey(virConnectPtr conn,
* storage volume object is no longer needed.
*
* Returns a storage volume, or NULL if not found / error
*
* Since: v0.4.1
*/
virStorageVolPtr
virStorageVolLookupByPath(virConnectPtr conn,
@ -1441,6 +1513,8 @@ virStorageVolLookupByPath(virConnectPtr conn,
* within the scope of a pool
*
* Returns the volume name, or NULL on error
*
* Since: v0.4.1
*/
const char*
virStorageVolGetName(virStorageVolPtr vol)
@ -1464,6 +1538,8 @@ virStorageVolGetName(virStorageVolPtr vol)
* key no matter what host it is accessed from
*
* Returns the volume key, or NULL on error
*
* Since: v0.4.1
*/
const char*
virStorageVolGetKey(virStorageVolPtr vol)
@ -1497,6 +1573,8 @@ virStorageVolGetKey(virStorageVolPtr vol)
* storage volume object is no longer needed.
*
* Returns the storage volume, or NULL on error
*
* Since: v0.4.1
*/
virStorageVolPtr
virStorageVolCreateXML(virStoragePoolPtr pool,
@ -1548,6 +1626,8 @@ virStorageVolCreateXML(virStoragePoolPtr pool,
* storage volume object is no longer needed.
*
* Returns the storage volume, or NULL on error
*
* Since: v0.6.4
*/
virStorageVolPtr
virStorageVolCreateXMLFrom(virStoragePoolPtr pool,
@ -1612,6 +1692,8 @@ virStorageVolCreateXMLFrom(virStoragePoolPtr pool,
* another active stream is writing to the storage volume.
*
* Returns 0, or -1 upon error.
*
* Since: v0.9.0
*/
int
virStorageVolDownload(virStorageVolPtr vol,
@ -1695,6 +1777,8 @@ virStorageVolDownload(virStorageVolPtr vol,
* capacity, and allocation.
*
* Returns 0, or -1 upon error.
*
* Since: v0.9.0
*/
int
virStorageVolUpload(virStorageVolPtr vol,
@ -1748,6 +1832,8 @@ virStorageVolUpload(virStorageVolPtr vol,
* Delete the storage volume from the pool
*
* Returns 0 on success, or -1 on error
*
* Since: v0.4.1
*/
int
virStorageVolDelete(virStorageVolPtr vol,
@ -1797,6 +1883,8 @@ virStorageVolDelete(virStorageVolPtr vol,
* network file systems are known to be problematic.
*
* Returns 0 on success, or -1 on error
*
* Since: v0.8.0
*/
int
virStorageVolWipe(virStorageVolPtr vol,
@ -1843,6 +1931,8 @@ virStorageVolWipe(virStorageVolPtr vol,
* problematic.
*
* Returns 0 on success, or -1 on error.
*
* Since: v0.9.10
*/
int
virStorageVolWipePattern(virStorageVolPtr vol,
@ -1883,6 +1973,8 @@ virStorageVolWipePattern(virStorageVolPtr vol,
* storage volume continues to exist.
*
* Returns 0 on success, or -1 on error
*
* Since: v0.4.1
*/
int
virStorageVolFree(virStorageVolPtr vol)
@ -1914,6 +2006,8 @@ virStorageVolFree(virStorageVolPtr vol)
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
*
* Since: v0.6.0
*/
int
virStorageVolRef(virStorageVolPtr vol)
@ -1938,6 +2032,8 @@ virStorageVolRef(virStorageVolPtr vol)
* volume such as its current allocation
*
* Returns 0 on success, or -1 on failure
*
* Since: v0.4.1
*/
int
virStorageVolGetInfo(virStorageVolPtr vol,
@ -1988,6 +2084,8 @@ virStorageVolGetInfo(virStorageVolPtr vol,
* as is the case with qcow2 files.
*
* Returns 0 on success, or -1 on failure
*
* Since: v3.0.0
*/
int
virStorageVolGetInfoFlags(virStorageVolPtr vol,
@ -2032,6 +2130,8 @@ virStorageVolGetInfoFlags(virStorageVolPtr vol,
* the storage volume
*
* Returns the XML document, or NULL on error
*
* Since: v0.4.1
*/
char *
virStorageVolGetXMLDesc(virStorageVolPtr vol,
@ -2073,6 +2173,8 @@ virStorageVolGetXMLDesc(virStorageVolPtr vol,
*
* Returns the storage volume path, or NULL on error. The
* caller must free() the returned path after use.
*
* Since: v0.4.1
*/
char *
virStorageVolGetPath(virStorageVolPtr vol)
@ -2134,6 +2236,8 @@ virStorageVolGetPath(virStorageVolPtr vol)
* than the current size.
*
* Returns 0 on success, or -1 on error.
*
* Since: v0.9.10
*/
int
virStorageVolResize(virStorageVolPtr vol,
@ -2183,6 +2287,8 @@ virStorageVolResize(virStorageVolPtr vol,
* Determine if the storage pool is currently running
*
* Returns 1 if running, 0 if inactive, -1 on error
*
* Since: v0.7.3
*/
int
virStoragePoolIsActive(virStoragePoolPtr pool)
@ -2216,6 +2322,8 @@ virStoragePoolIsActive(virStoragePoolPtr pool)
* which means it will still exist after shutting down
*
* Returns 1 if persistent, 0 if transient, -1 on error
*
* Since: v0.7.3
*/
int
virStoragePoolIsPersistent(virStoragePoolPtr pool)
@ -2274,6 +2382,8 @@ virStoragePoolIsPersistent(virStoragePoolPtr pool)
* be passed to the virConnectStoragePoolEventDeregisterAny() method.
*
* Returns a callback identifier on success, -1 on failure.
*
* Since: v2.0.0
*/
int
virConnectStoragePoolEventRegisterAny(virConnectPtr conn,
@ -2337,6 +2447,8 @@ virConnectStoragePoolEventRegisterAny(virConnectPtr conn,
* value obtained from a previous virConnectStoragePoolEventRegisterAny() method.
*
* Returns 0 on success, -1 on failure
*
* Since: v2.0.0
*/
int
virConnectStoragePoolEventDeregisterAny(virConnectPtr conn,
@ -2376,6 +2488,8 @@ virConnectStoragePoolEventDeregisterAny(virConnectPtr conn,
* are supported along with the file/disk formats for each pool.
*
* Returns NULL in case of error or an XML string defining the capabilities.
*
* Since: v5.2.0
*/
char *
virConnectGetStoragePoolCapabilities(virConnectPtr conn,

34
src/libvirt-stream.c
View File

@ -52,6 +52,8 @@ VIR_LOG_INIT("libvirt.stream");
* VIR_STREAM_NONBLOCK for flags, otherwise pass 0.
*
* Returns the new stream, or NULL upon error
*
* Since: v0.7.2
*/
virStreamPtr
virStreamNew(virConnectPtr conn,
@ -85,6 +87,8 @@ virStreamNew(virConnectPtr conn,
* the caller no longer needs the reference to this object.
*
* Returns 0 in case of success, -1 in case of failure
*
* Since: v0.7.2
*/
int
virStreamRef(virStreamPtr stream)
@ -163,6 +167,8 @@ virStreamRef(virStreamPtr stream)
*
* Returns -2 if the outgoing transmit buffers are full &
* the stream is marked as non-blocking.
*
* Since: v0.7.2
*/
int
virStreamSend(virStreamPtr stream,
@ -258,6 +264,8 @@ virStreamSend(virStreamPtr stream,
*
* Returns -2 if there is no data pending to be read & the
* stream is marked as non-blocking.
*
* Since: v0.7.2
*/
int
virStreamRecv(virStreamPtr stream,
@ -345,6 +353,8 @@ virStreamRecv(virStreamPtr stream,
*
* Returns -3 if there is a hole in stream and caller requested
* to stop at a hole.
*
* Since: v3.4.0
*/
int
virStreamRecvFlags(virStreamPtr stream,
@ -412,6 +422,8 @@ virStreamRecvFlags(virStreamPtr stream,
*
* Returns 0 on success,
* -1 error
*
* Since: v3.4.0
*/
int
virStreamSendHole(virStreamPtr stream,
@ -455,6 +467,8 @@ virStreamSendHole(virStreamPtr stream,
*
* Returns 0 on success,
* -1 on error or when there's currently no hole in the stream
*
* Since: v3.4.0
*/
int
virStreamRecvHole(virStreamPtr stream,
@ -577,6 +591,8 @@ virStreamInData(virStreamPtr stream,
* Returns -1 upon any error, with virStreamAbort() already
* having been called, so the caller need only call
* virStreamFree().
*
* Since: v0.7.2
*/
int
virStreamSendAll(virStreamPtr stream,
@ -706,6 +722,8 @@ virStreamSendAll(virStreamPtr stream,
* Returns -1 upon any error, with virStreamAbort() already
* having been called, so the caller need only call
* virStreamFree().
*
* Since: v3.4.0
*/
int virStreamSparseSendAll(virStreamPtr stream,
virStreamSourceFunc handler,
@ -845,6 +863,8 @@ int virStreamSparseSendAll(virStreamPtr stream,
* Returns -1 upon any error, with virStreamAbort() already
* having been called, so the caller need only call
* virStreamFree()
*
* Since: v0.7.2
*/
int
virStreamRecvAll(virStreamPtr stream,
@ -958,6 +978,8 @@ virStreamRecvAll(virStreamPtr stream,
*
* Returns -1 upon any error, with virStreamAbort() already
* having been called, so the caller need only call virStreamFree().
*
* Since: v3.4.0
*/
int
virStreamSparseRecvAll(virStreamPtr stream,
@ -1051,6 +1073,8 @@ virStreamSparseRecvAll(virStreamPtr stream,
* to integrate into an event loop
*
* Returns 0 on success, -1 upon error
*
* Since: v0.7.2
*/
int
virStreamEventAddCallback(virStreamPtr stream,
@ -1094,6 +1118,8 @@ virStreamEventAddCallback(virStreamPtr stream,
* is guaranteed to succeed if a callback is already registered
*
* Returns 0 on success, -1 if no callback is registered
*
* Since: v0.7.2
*/
int
virStreamEventUpdateCallback(virStreamPtr stream,
@ -1129,6 +1155,8 @@ virStreamEventUpdateCallback(virStreamPtr stream,
* Remove an event callback from the stream
*
* Returns 0 on success, -1 on error
*
* Since: v0.7.2
*/
int
virStreamEventRemoveCallback(virStreamPtr stream)
@ -1173,6 +1201,8 @@ virStreamEventRemoveCallback(virStreamPtr stream)
* beforehand.
*
* Returns 0 on success, -1 upon error
*
* Since: v0.7.2
*/
int
virStreamFinish(virStreamPtr stream)
@ -1215,6 +1245,8 @@ virStreamFinish(virStreamPtr stream)
* beforehand.
*
* Returns 0 on success, -1 upon error
*
* Since: v0.7.2
*/
int
virStreamAbort(virStreamPtr stream)
@ -1259,6 +1291,8 @@ virStreamAbort(virStreamPtr stream)
* the virStreamAbort function should be called first.
*
* Returns 0 upon success, or -1 on error
*
* Since: v0.7.2
*/
int
virStreamFree(virStreamPtr stream)

12
src/libvirt.c
View File

@ -296,6 +296,8 @@ virGlobalInit(void)
* connection attempt.
*
* Returns 0 in case of success, -1 in case of error
*
* Since: v0.1.0
*/
int
virInitialize(void)
@ -797,6 +799,8 @@ virStateStop(void)
*
* Returns -1 in case of failure, 0 otherwise, and values for @libVer and
* @typeVer have the format major * 1,000,000 + minor * 1,000 + release.
*
* Since: v0.0.3
*/
int
virGetVersion(unsigned long *libVer, const char *type G_GNUC_UNUSED,
@ -1185,6 +1189,8 @@ virConnectOpenInternal(const char *name,
* is no longer needed.
*
* Returns a pointer to the hypervisor connection or NULL in case of error
*
* Since: v0.0.3
*/
virConnectPtr
virConnectOpen(const char *name)
@ -1218,6 +1224,8 @@ virConnectOpen(const char *name)
* URIs are documented at https://libvirt.org/uri.html
*
* Returns a pointer to the hypervisor connection or NULL in case of error
*
* Since: v0.0.3
*/
virConnectPtr
virConnectOpenReadOnly(const char *name)
@ -1252,6 +1260,8 @@ virConnectOpenReadOnly(const char *name)
* URIs are documented at https://libvirt.org/uri.html
*
* Returns a pointer to the hypervisor connection or NULL in case of error
*
* Since: v0.4.0
*/
virConnectPtr
virConnectOpenAuth(const char *name,
@ -1300,6 +1310,8 @@ virConnectOpenAuth(const char *name,
* value if some other object still has a temporary reference to the
* connection, but the application should not try to further use a
* connection after the virConnectClose that matches the initial open.
*
* Since: v0.0.3
*/
int
virConnectClose(virConnectPtr conn)

30
src/util/virerror.c
View File

@ -254,6 +254,8 @@ virLastErrorObject(void)
* threads can safely access this concurrently.
*
* Returns a pointer to the last error or NULL if none occurred.
*
* Since: v0.1.0
*/
virErrorPtr
virGetLastError(void)
@ -271,6 +273,8 @@ virGetLastError(void)
* Get the most recent error code (enum virErrorNumber).
*
* Returns the most recent error code, or VIR_ERR_OK if none is set.
*
* Since: v4.5.0
*/
int
virGetLastErrorCode(void)
@ -289,6 +293,8 @@ virGetLastErrorCode(void)
*
* Returns a numerical value of the most recent error's origin, or VIR_FROM_NONE
* if none is set.
*
* Since: v4.5.0
*/
int
virGetLastErrorDomain(void)
@ -307,6 +313,8 @@ virGetLastErrorDomain(void)
*
* Returns the most recent error message string in this
* thread, or a generic message if none is set
*
* Since: v1.0.6
*/
const char *
virGetLastErrorMessage(void)
@ -361,6 +369,8 @@ virSetError(virErrorPtr newerr)
* One will need to free the result with virResetError()
*
* Returns error code or -1 in case of parameter error.
*
* Since: v0.1.0
*/
int
virCopyLastError(virErrorPtr to)
@ -392,6 +402,8 @@ virCopyLastError(virErrorPtr to)
* Returns a pointer to the copied error or NULL if allocation failed.
* It is the caller's responsibility to free the error with
* virFreeError().
*
* Since: v0.6.1
*/
virErrorPtr
virSaveLastError(void)
@ -455,6 +467,8 @@ virErrorRestore(virErrorPtr *savederr)
* @err: pointer to the virError to clean up
*
* Reset the error being pointed to
*
* Since: v0.1.0
*/
void
virResetError(virErrorPtr err)
@ -473,6 +487,8 @@ virResetError(virErrorPtr err)
* @err: error to free
*
* Resets and frees the given error.
*
* Since: v0.6.1
*/
void
virFreeError(virErrorPtr err)
@ -489,6 +505,8 @@ virFreeError(virErrorPtr err)
* The error object is kept in thread local storage, so separate
* threads can safely access this concurrently, only resetting
* their own error object.
*
* Since: v0.1.0
*/
void
virResetLastError(void)
@ -519,6 +537,8 @@ virResetLastError(void)
* remains for backwards compatibility.
*
* Returns a pointer to the last error or NULL if none occurred.
*
* Since: v0.1.0
*/
virErrorPtr
virConnGetLastError(virConnectPtr conn)
@ -553,6 +573,8 @@ virConnGetLastError(virConnectPtr conn)
*
* Returns 0 if no error was found and the error code otherwise and -1 in case
* of parameter error.
*
* Since: v0.1.0
*/
int
virConnCopyLastError(virConnectPtr conn, virErrorPtr to)
@ -579,6 +601,8 @@ virConnCopyLastError(virConnectPtr conn, virErrorPtr to)
* threads can safely access this concurrently.
*
* Reset the last error caught on that connection
*
* Since: v0.1.0
*/
void
virConnResetLastError(virConnectPtr conn)
@ -598,6 +622,8 @@ virConnResetLastError(virConnectPtr conn)
* Set a library global error handling function, if @handler is NULL,
* it will reset to default printing on stderr. The error raised there
* are those for which no handler at the connection level could caught.
*
* Since: v0.1.0
*/
void
virSetErrorFunc(void *userData, virErrorFunc handler)
@ -615,6 +641,8 @@ virSetErrorFunc(void *userData, virErrorFunc handler)
* Set a connection error handling function, if @handler is NULL
* it will reset to default which is to pass error back to the global
* library handler.
*
* Since: v0.1.0
*/
void
virConnSetErrorFunc(virConnectPtr conn, void *userData,
@ -633,6 +661,8 @@ virConnSetErrorFunc(virConnectPtr conn, void *userData,
* @err: pointer to the error.
*
* Default routine reporting an error to stderr.
*
* Since: v0.1.0
*/
void
virDefaultErrorFunc(virErrorPtr err)

18
src/util/virevent.c
View File

@ -69,6 +69,8 @@ static virEventRemoveTimeoutFunc removeTimeoutImpl;
*
* Returns -1 if the file handle cannot be registered, otherwise a handle
* watch number to be used for updating and unregistering for events.
*
* Since: v0.9.3
*/
int
virEventAddHandle(int fd,
@ -94,6 +96,8 @@ virEventAddHandle(int fd,
* virEventRegisterImpl() or virEventRegisterDefaultImpl().
*
* Will not fail if fd exists.
*
* Since: v0.9.3
*/
void
virEventUpdateHandle(int watch, int events)
@ -112,6 +116,8 @@ virEventUpdateHandle(int watch, int events)
* virEventRegisterImpl() or virEventRegisterDefaultImpl().
*
* Returns -1 if the file handle was not registered, 0 upon success.
*
* Since: v0.9.3
*/
int
virEventRemoveHandle(int watch)
@ -139,6 +145,8 @@ virEventRemoveHandle(int watch)
*
* Returns -1 if the timer cannot be registered, a positive
* integer timer id upon success.
*
* Since: v0.9.3
*/
int
virEventAddTimeout(int timeout,
@ -166,6 +174,8 @@ virEventAddTimeout(int timeout,
* to zero will cause it to fire on every event loop iteration.
*
* Will not fail if timer exists.
*
* Since: v0.9.3
*/
void
virEventUpdateTimeout(int timer, int timeout)
@ -184,6 +194,8 @@ virEventUpdateTimeout(int timer, int timeout)
* virEventRegisterImpl() or virEventRegisterDefaultImpl().
*
* Returns -1 if the timer was not registered, 0 upon success.
*
* Since: v0.9.3
*/
int
virEventRemoveTimeout(int timer)
@ -232,6 +244,8 @@ virEventRemoveTimeout(int timer)
* virConnectClose on all open connections, so it is not safe
* to stop running the event loop immediately after closing
* the connection.
*
* Since: v0.5.0
*/
void virEventRegisterImpl(virEventAddHandleFunc addHandle,
virEventUpdateHandleFunc updateHandle,
@ -300,6 +314,8 @@ int virEventRequireImpl(void)
* virEventAddHandle() or virConnectDomainEventRegisterAny().
*
* Returns 0 on success, -1 on failure.
*
* Since: v0.9.0
*/
int virEventRegisterDefaultImpl(void)
{
@ -335,6 +351,8 @@ int virEventRegisterDefaultImpl(void)
* }
*
* Returns 0 on success, -1 on failure.
*
* Since: v0.9.0
*/
int virEventRunDefaultImpl(void)
{