[libvirt] [PATCH] Document the need to free vir*Ptr objects per-function

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