[libvirt] [PATCH] Document the need to free vir*Ptr objects per-function
Ján Tomko
jtomko at redhat.com
Tue Jul 8 16:00:34 UTC 2014
Another patch for
https://bugzilla.redhat.com/show_bug.cgi?id=994731
---
src/libvirt.c | 139 +++++++++++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 134 insertions(+), 5 deletions(-)
diff --git a/src/libvirt.c b/src/libvirt.c
index 316fdf0..8684298 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -1299,6 +1299,9 @@ do_open(const char *name,
*
* URIs are documented at http://libvirt.org/uri.html
*
+ * virConnectClose should be used to release the resources after the connection
+ * is no longer needed.
+ *
* Returns a pointer to the hypervisor connection or NULL in case of error
*/
virConnectPtr
@@ -1331,7 +1334,7 @@ virConnectOpen(const char *name)
* on the available methods to control the domains.
*
* See virConnectOpen for notes about environment variables which can
- * have an effect on opening drivers
+ * have an effect on opening drivers and freeing the connection resources
*
* URIs are documented at http://libvirt.org/uri.html
*
@@ -1369,7 +1372,7 @@ virConnectOpenReadOnly(const char *name)
* credentials via the callback
*
* See virConnectOpen for notes about environment variables which can
- * have an effect on opening drivers
+ * have an effect on opening drivers and freeing the connection resources
*
* URIs are documented at http://libvirt.org/uri.html
*
@@ -1875,6 +1878,9 @@ virDomainGetConnect(virDomainPtr dom)
* libvirtd daemon. Any domains marked for auto destroy will
* block attempts at migration, save-to-file, or snapshots.
*
+ * virDomainFree should be used to free the resources after the
+ * domain object is no longer needed.
+ *
* Returns a new domain object or NULL in case of failure
*/
virDomainPtr
@@ -1937,6 +1943,9 @@ virDomainCreateXML(virConnectPtr conn, const char *xmlDesc,
* libvirtd daemon. Any domains marked for auto destroy will
* block attempts at migration, save-to-file, or snapshots.
*
+ * virDomainFree should be used to free the resources after the
+ * domain object is no longer needed.
+ *
* Returns a new domain object or NULL in case of failure
*/
virDomainPtr
@@ -2000,6 +2009,9 @@ virDomainCreateLinux(virConnectPtr conn, const char *xmlDesc,
* Note that this won't work for inactive domains which have an ID of -1,
* in that case a lookup based on the Name or UUId need to be done instead.
*
+ * virDomainFree should be used to free the resources after the
+ * domain object is no longer needed.
+ *
* Returns a new domain object or NULL in case of failure. If the
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
*/
@@ -2036,6 +2048,9 @@ virDomainLookupByID(virConnectPtr conn, int id)
*
* Try to lookup a domain on the given hypervisor based on its UUID.
*
+ * virDomainFree should be used to free the resources after the
+ * domain object is no longer needed.
+ *
* Returns a new domain object or NULL in case of failure. If the
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
*/
@@ -2072,6 +2087,9 @@ virDomainLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
*
* Try to lookup a domain on the given hypervisor based on its UUID.
*
+ * virDomainFree should be used to free the resources after the
+ * domain object is no longer needed.
+ *
* Returns a new domain object or NULL in case of failure. If the
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
*/
@@ -2108,6 +2126,9 @@ virDomainLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
*
* Try to lookup a domain on the given hypervisor based on its name.
*
+ * virDomainFree should be used to free the resources after the
+ * domain object is no longer needed.
+ *
* Returns a new domain object or NULL in case of failure. If the
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
*/
@@ -5284,6 +5305,9 @@ virDomainMigrateDirect(virDomainPtr domain,
* different processors even with the same architecture, or between
* different types of hypervisor.
*
+ * virDomainFree should be used to free the resources after the
+ * returned domain object is no longer needed.
+ *
* Returns the new domain object if the migration was successful,
* or NULL in case of error. Note that the new domain object
* exists in the scope of the destination connection (dconn).
@@ -5509,6 +5533,9 @@ virDomainMigrate(virDomainPtr domain,
* @dname for that purpose). Domain name in @dxml must match the
* original domain name.
*
+ * virDomainFree should be used to free the resources after the
+ * returned domain object is no longer needed.
+ *
* Returns the new domain object if the migration was successful,
* or NULL in case of error. Note that the new domain object
* exists in the scope of the destination connection (dconn).
@@ -5680,6 +5707,9 @@ virDomainMigrate2(virDomainPtr domain,
* different processors even with the same architecture, or between
* different types of hypervisor.
*
+ * virDomainFree should be used to free the resources after the
+ * returned domain object is no longer needed.
+ *
* Returns the new domain object if the migration was successful,
* or NULL in case of error. Note that the new domain object
* exists in the scope of the destination connection (dconn).
@@ -7916,7 +7946,7 @@ virDomainBlockStats(virDomainPtr dom, const char *disk,
* @dom: pointer to domain object
* @disk: path to the block device, or device shorthand
* @params: pointer to block stats parameter object
- * (return value)
+ * (return value, allocated by the caller)
* @nparams: pointer to number of block stats; input and output
* @flags: bitwise-OR of virTypedParameterFlags
*
@@ -8631,6 +8661,9 @@ virDomainGetBlockInfo(virDomainPtr domain, const char *disk,
* domain being defined; in that case, use virDomainBlockJobAbort() to
* stop the block copy first.
*
+ * virDomainFree should be used to free the resources after the
+ * domain object is no longer needed.
+ *
* Returns NULL in case of error, a pointer to the domain otherwise
*/
virDomainPtr
@@ -10899,6 +10932,9 @@ virConnectListDefinedNetworks(virConnectPtr conn, char **const names,
*
* Try to lookup a network on the given hypervisor based on its name.
*
+ * virNetworkFree should be used to free the resources after the
+ * network object is no longer needed.
+ *
* 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.
*/
@@ -10935,6 +10971,9 @@ virNetworkLookupByName(virConnectPtr conn, const char *name)
*
* Try to lookup a network on the given hypervisor based on its UUID.
*
+ * virNetworkFree should be used to free the resources after the
+ * network object is no longer needed.
+ *
* 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.
*/
@@ -11008,6 +11047,9 @@ virNetworkLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
* Create and start a new virtual network, based on an XML description
* similar to the one returned by virNetworkGetXMLDesc()
*
+ * virNetworkFree should be used to free the resources after the
+ * network object is no longer needed.
+ *
* Returns a new network object or NULL in case of failure
*/
virNetworkPtr
@@ -11044,6 +11086,9 @@ virNetworkCreateXML(virConnectPtr conn, const char *xmlDesc)
*
* Define a network, but does not create it
*
+ * virNetworkFree should be used to free the resources after the
+ * network object is no longer needed.
+ *
* Returns NULL in case of error, a pointer to the network otherwise
*/
virNetworkPtr
@@ -11788,6 +11833,9 @@ virConnectListDefinedInterfaces(virConnectPtr conn,
*
* Try to lookup an interface on the given hypervisor based on its name.
*
+ * virInterfaceFree should be used to free the resources after the
+ * interface object is no longer needed.
+ *
* 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.
*/
@@ -11824,6 +11872,9 @@ virInterfaceLookupByName(virConnectPtr conn, const char *name)
*
* Try to lookup an interface on the given hypervisor based on its MAC.
*
+ * virInterfaceFree should be used to free the resources after the
+ * interface object is no longer needed.
+ *
* 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.
*/
@@ -11962,6 +12013,9 @@ virInterfaceGetXMLDesc(virInterfacePtr iface, unsigned int flags)
* automatically removed during the next reboot of the system running
* libvirtd.
*
+ * virInterfaceFree should be used to free the resources after the
+ * interface object is no longer needed.
+ *
* Returns NULL in case of error, a pointer to the interface otherwise
*/
virInterfacePtr
@@ -12634,6 +12688,9 @@ virConnectFindStoragePoolSources(virConnectPtr conn,
*
* Fetch a storage pool based on its unique name
*
+ * virStoragePoolFree should be used to free the resources after the
+ * storage pool object is no longer needed.
+ *
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
*/
virStoragePoolPtr
@@ -12670,6 +12727,9 @@ virStoragePoolLookupByName(virConnectPtr conn,
*
* Fetch a storage pool based on its globally unique id
*
+ * virStoragePoolFree should be used to free the resources after the
+ * storage pool object is no longer needed.
+ *
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
*/
virStoragePoolPtr
@@ -12706,6 +12766,9 @@ virStoragePoolLookupByUUID(virConnectPtr conn,
*
* Fetch a storage pool based on its globally unique id
*
+ * virStoragePoolFree should be used to free the resources after the
+ * storage pool object is no longer needed.
+ *
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
*/
virStoragePoolPtr
@@ -12741,6 +12804,9 @@ virStoragePoolLookupByUUIDString(virConnectPtr conn,
*
* Fetch a storage pool which contains a particular volume
*
+ * virStoragePoolFree should be used to free the resources after the
+ * storage pool object is no longer needed.
+ *
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
*/
virStoragePoolPtr
@@ -12778,6 +12844,9 @@ virStoragePoolLookupByVolume(virStorageVolPtr vol)
* pool is not persistent, so its definition will disappear
* when it is destroyed, or if the host is restarted
*
+ * virStoragePoolFree should be used to free the resources after the
+ * storage pool object is no longer needed.
+ *
* Returns a virStoragePoolPtr object, or NULL if creation failed
*/
virStoragePoolPtr
@@ -12818,6 +12887,9 @@ virStoragePoolCreateXML(virConnectPtr conn,
* Define a new inactive storage pool based on its XML description. The
* pool is persistent, until explicitly undefined.
*
+ * virStoragePoolFree should be used to free the resources after the
+ * storage pool object is no longer needed.
+ *
* Returns a virStoragePoolPtr object, or NULL if creation failed
*/
virStoragePoolPtr
@@ -13277,7 +13349,7 @@ virStoragePoolGetInfo(virStoragePoolPtr pool,
* storage pool. This is suitable for later feeding back
* into the virStoragePoolCreateXML method.
*
- * Returns a XML document, or NULL on error
+ * Returns a XML document (caller frees), or NULL on error
*/
char *
virStoragePoolGetXMLDesc(virStoragePoolPtr pool,
@@ -13542,6 +13614,9 @@ virStorageVolGetConnect(virStorageVolPtr vol)
* Fetch a pointer to a storage volume based on its name
* within a pool
*
+ * virStorageVolFree should be used to free the resources after the
+ * storage volume object is no longer needed.
+ *
* Returns a storage volume, or NULL if not found / error
*/
virStorageVolPtr
@@ -13579,6 +13654,9 @@ virStorageVolLookupByName(virStoragePoolPtr pool,
* Fetch a pointer to a storage volume based on its
* globally unique key
*
+ * virStorageVolFree should be used to free the resources after the
+ * storage volume object is no longer needed.
+ *
* Returns a storage volume, or NULL if not found / error
*/
virStorageVolPtr
@@ -13616,6 +13694,9 @@ virStorageVolLookupByKey(virConnectPtr conn,
* Fetch a pointer to a storage volume based on its
* locally (host) unique path
*
+ * virStorageVolFree should be used to free the resources after the
+ * storage volume object is no longer needed.
+ *
* Returns a storage volume, or NULL if not found / error
*/
virStorageVolPtr
@@ -13705,6 +13786,9 @@ virStorageVolGetKey(virStorageVolPtr vol)
* qcow2 image files which don't support full preallocation,
* by creating a sparse image file with metadata.
*
+ * virStorageVolFree should be used to free the resources after the
+ * storage volume object is no longer needed.
+ *
* Returns the storage volume, or NULL on error
*/
virStorageVolPtr
@@ -13753,6 +13837,9 @@ virStorageVolCreateXML(virStoragePoolPtr pool,
* qcow2 image files which don't support full preallocation,
* by creating a sparse image file with metadata.
*
+ * virStorageVolFree should be used to free the resources after the
+ * storage volume object is no longer needed.
+ *
* Returns the storage volume, or NULL on error
*/
virStorageVolPtr
@@ -14454,6 +14541,9 @@ virNodeListDevices(virConnectPtr conn,
*
* Lookup a node device by its name.
*
+ * virNodeDeviceFree should be used to free the resources after the
+ * node device object is no longer needed.
+ *
* Returns a virNodeDevicePtr if found, NULL otherwise.
*/
virNodeDevicePtr
@@ -14491,6 +14581,9 @@ virNodeDeviceLookupByName(virConnectPtr conn, const char *name)
*
* Lookup SCSI Host which is capable with 'fc_host' by its WWNN and WWPN.
*
+ * virNodeDeviceFree should be used to free the resources after the
+ * node device object is no longer needed.
+ *
* Returns a virNodeDevicePtr if found, NULL otherwise.
*/
virNodeDevicePtr
@@ -14941,6 +15034,9 @@ virNodeDeviceReset(virNodeDevicePtr dev)
* Create a new device on the VM host machine, for example, virtual
* HBAs created using vport_create.
*
+ * virNodeDeviceFree should be used to free the resources after the
+ * node device object is no longer needed.
+ *
* Returns a node device object if successful, NULL in case of failure
*/
virNodeDevicePtr
@@ -15280,6 +15376,9 @@ virConnectListSecrets(virConnectPtr conn, char **uuids, int maxuuids)
* Try to lookup a secret on the given hypervisor based on its UUID.
* Uses the 16 bytes of raw data to describe the UUID
*
+ * virSecretFree should be used to free the resources after the
+ * secret object is no longer needed.
+ *
* 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.
*/
@@ -15318,6 +15417,9 @@ virSecretLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
* Try to lookup a secret on the given hypervisor based on its UUID.
* Uses the printable string value to describe the UUID
*
+ * virSecretFree should be used to free the resources after the
+ * secret object is no longer needed.
+ *
* 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.
*/
@@ -15357,6 +15459,9 @@ virSecretLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
* The usageID is unique within the set of secrets sharing the
* same usageType value.
*
+ * virSecretFree should be used to free the resources after the
+ * secret object is no longer needed.
+ *
* 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.
*/
@@ -15402,6 +15507,9 @@ virSecretLookupByUsage(virConnectPtr conn,
* Otherwise, creates a new secret with an automatically chosen UUID, and
* initializes its attributes from xml.
*
+ * virSecretFree should be used to free the resources after the
+ * secret object is no longer needed.
+ *
* Returns a secret on success, NULL on failure.
*/
virSecretPtr
@@ -16793,6 +16901,9 @@ virConnectListNWFilters(virConnectPtr conn, char **const names, int maxnames)
*
* Try to lookup a network filter on the given hypervisor based on its name.
*
+ * virNWFilterFree should be used to free the resources after the
+ * nwfilter object is no longer needed.
+ *
* 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.
*/
@@ -16829,6 +16940,9 @@ virNWFilterLookupByName(virConnectPtr conn, const char *name)
*
* Try to lookup a network filter on the given hypervisor based on its UUID.
*
+ * virNWFilterFree should be used to free the resources after the
+ * nwfilter object is no longer needed.
+ *
* 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.
*/
@@ -16865,6 +16979,9 @@ virNWFilterLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
*
* Try to lookup an nwfilter on the given hypervisor based on its UUID.
*
+ * virNWFilterFree should be used to free the resources after the
+ * nwfilter object is no longer needed.
+ *
* 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.
*/
@@ -17005,6 +17122,9 @@ virNWFilterGetUUIDString(virNWFilterPtr nwfilter, char *buf)
* Define a new network filter, based on an XML description
* similar to the one returned by virNWFilterGetXMLDesc()
*
+ * virNWFilterFree should be used to free the resources after the
+ * nwfilter object is no longer needed.
+ *
* Returns a new nwfilter object or NULL in case of failure
*/
virNWFilterPtr
@@ -17348,7 +17468,7 @@ virConnectGetCPUModelNames(virConnectPtr conn, const char *arch, char ***models,
* without this flag features that are part of the CPU model will not be
* listed.
*
- * Returns XML description of the computed CPU or NULL on error.
+ * Returns XML description of the computed CPU (caller frees) or NULL on error.
*/
char *
virConnectBaselineCPU(virConnectPtr conn,
@@ -18297,6 +18417,9 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
* block copy operation; in that case, use virDomainBlockJobAbort()
* to stop the block copy first.
*
+ * virDomainSnapshotFree should be used to free the resources after the
+ * snapshot object is no longer needed.
+ *
* Returns an (opaque) virDomainSnapshotPtr on success, NULL on failure.
*/
virDomainSnapshotPtr
@@ -18966,6 +19089,9 @@ virDomainHasCurrentSnapshot(virDomainPtr domain, unsigned int flags)
*
* Get the current snapshot for a domain, if any.
*
+ * virDomainSnapshotFree should be used to free the resources after the
+ * snapshot object is no longer needed.
+ *
* 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.
@@ -19005,6 +19131,9 @@ virDomainSnapshotCurrent(virDomainPtr domain,
*
* Get the parent snapshot for @snapshot, if any.
*
+ * virDomainSnapshotFree should be used to free the resources after the
+ * snapshot object is no longer needed.
+ *
* 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.
--
1.8.5.5
More information about the libvir-list
mailing list