[libvirt] [PATCH v3 1/8] libvirt: Update headers for doc

John Ferlan jferlan at redhat.com
Tue Feb 26 14:18:48 UTC 2013


Update the function prototypes to include a message about the client needing
to free() returned name fields.  Fix the all domains example flags values.

v3->v2 diff:
Separted this out to it's own patch.
---
 src/libvirt.c | 21 ++++++++++-----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/src/libvirt.c b/src/libvirt.c
index 934997a..8447c0e 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -8304,19 +8304,18 @@ error:
  * VIR_CONNECT_LIST_DOMAINS_NO_SNAPSHOT, for filtering based on whether
  * a domain has snapshots.
  *
- * Returns the number of domains found or -1 and sets domains to NULL in case
- * of error.  On success, the array stored into @doms is guaranteed to have an
+ * Returns the number of domains found or -1 and sets domains to NULL in case of
+ * error.  On success, the array stored into @domains is guaranteed to 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 virDomainFree()
- * on each array element, then calling free() on @doms.
+ * on each array element, then calling free() on @domains.
  *
  * Example of usage:
  * virDomainPtr *domains;
- * virDomainPtr dom;
  * int i;
  * int ret;
- * unsigned int flags = VIR_CONNECT_LIST_RUNNING |
- *                      VIR_CONNECT_LIST_PERSISTENT;
+ * unsigned int flags = VIR_CONNECT_LIST_DOMAINS_RUNNING |
+ *                      VIR_CONNECT_LIST_DOMAINS_PERSISTENT;
  *
  * ret = virConnectListAllDomains(conn, &domains, flags);
  * if (ret < 0)
@@ -10226,7 +10225,7 @@ error:
  * this command is inherently racy; a network can be started between a call
  * to virConnectNumOfNetworks() and this call; you are only guaranteed that
  * all currently active networks were listed if the return is less than
- * @maxnames.
+ * @maxnames. The client must call free() on each returned name.
  */
 int
 virConnectListNetworks(virConnectPtr conn, char **const names, int maxnames)
@@ -11208,7 +11207,7 @@ error:
  * this command is inherently racy; a interface can be started between a call
  * to virConnectNumOfInterfaces() and this call; you are only guaranteed that
  * all currently active interfaces were listed if the return is less than
- * @maxnames.
+ * @maxnames. The client must call free() on each returned name.
  */
 int
 virConnectListInterfaces(virConnectPtr conn, char **const names, int maxnames)
@@ -12076,7 +12075,7 @@ error:
  * this command is inherently racy; a pool can be started between a call to
  * virConnectNumOfStoragePools() and this call; you are only guaranteed
  * that all currently active pools were listed if the return is less than
- * @maxnames.
+ * @maxnames. The client must call free() on each returned name.
  */
 int
 virConnectListStoragePools(virConnectPtr conn,
@@ -18440,7 +18439,7 @@ error:
  * the results, see virDomainListAllSnapshots().
  *
  * Returns the number of domain snapshots found or -1 in case of error.
- * The caller is responsible for freeing each member of the array.
+ * The caller is responsible to call free() for each member of the array.
  */
 int
 virDomainSnapshotListNames(virDomainPtr domain, char **names, int nameslen,
@@ -18689,7 +18688,7 @@ error:
  * the results, see virDomainSnapshotListAllChildren().
  *
  * Returns the number of domain snapshots found or -1 in case of error.
- * The caller is responsible for freeing each member of the array.
+ * The caller is responsible to call free() for each member of the array.
  */
 int
 virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot,
-- 
1.7.11.7




More information about the libvir-list mailing list