[PATCH v2] libxl: document the memory ownership of some functions

[Dario Faggioli <raistlin@linux.it>]

Specifying they allocate dynamic memory that needs to be explicitly freed.

Signed-off-by: Dario Faggioli <dario.faggioli@citrix.com>
---
Changes from v1:
 * Functions are gathered together under a unique comment describing
   them all.
 * nr_THING output parameter renamed nr_THING_out.

diff --git a/tools/libxl/libxl.c b/tools/libxl/libxl.c
--- a/tools/libxl/libxl.c
+++ b/tools/libxl/libxl.c
@@ -508,7 +508,7 @@ static void xcinfo2xlinfo(const xc_domai
     xlinfo->cpupool = xcinfo->cpupool;
 }
 
-libxl_dominfo * libxl_list_domain(libxl_ctx *ctx, int *nb_domain)
+libxl_dominfo * libxl_list_domain(libxl_ctx *ctx, int *nb_domain_out)
 {
     libxl_dominfo *ptr;
     int i, ret;
@@ -531,7 +531,7 @@ libxl_dominfo * libxl_list_domain(libxl_
     for (i = 0; i < ret; i++) {
         xcinfo2xlinfo(&info[i], &ptr[i]);
     }
-    *nb_domain = ret;
+    *nb_domain_out = ret;
     return ptr;
 }
 
@@ -589,7 +589,7 @@ int libxl_cpupool_info(libxl_ctx *ctx,
     return rc;
 }
 
-libxl_cpupoolinfo * libxl_list_cpupool(libxl_ctx *ctx, int *nb_pool)
+libxl_cpupoolinfo * libxl_list_cpupool(libxl_ctx *ctx, int *nb_pool_out)
 {
     GC_INIT(ctx);
     libxl_cpupoolinfo info, *ptr, *tmp;
@@ -613,14 +613,15 @@ libxl_cpupoolinfo * libxl_list_cpupool(l
         poolid = info.poolid + 1;
     }
 
-    *nb_pool = i;
+    *nb_pool_out = i;
 out:
     GC_FREE;
     return ptr;
 }
 
-/* this API call only list VM running on this host. a VM can be an aggregate of multiple domains. */
-libxl_vminfo * libxl_list_vm(libxl_ctx *ctx, int *nb_vm)
+/* this API call only list VM running on this host. A VM can
+ * be an aggregate of multiple domains. */
+libxl_vminfo * libxl_list_vm(libxl_ctx *ctx, int *nb_vm_out)
 {
     libxl_vminfo *ptr;
     int index, i, ret;
@@ -644,7 +645,7 @@ libxl_vminfo * libxl_list_vm(libxl_ctx *
 
         index++;
     }
-    *nb_vm = index;
+    *nb_vm_out = index;
     return ptr;
 }
 
@@ -3161,7 +3162,7 @@ int libxl_get_physinfo(libxl_ctx *ctx, l
     return 0;
 }
 
-libxl_cputopology *libxl_get_cpu_topology(libxl_ctx *ctx, int *nr)
+libxl_cputopology *libxl_get_cpu_topology(libxl_ctx *ctx, int *nb_cpu_out)
 {
     xc_topologyinfo_t tinfo;
     DECLARE_HYPERCALL_BUFFER(xc_cpu_to_core_t, coremap);
@@ -3219,7 +3220,7 @@ fail:
     xc_hypercall_buffer_free(ctx->xch, nodemap);
 
     if (ret)
-        *nr = max_cpus;
+        *nb_cpu_out = max_cpus;
     return ret;
 }
 
@@ -3270,7 +3271,7 @@ const libxl_version_info* libxl_get_vers
 }
 
 libxl_vcpuinfo *libxl_list_vcpu(libxl_ctx *ctx, uint32_t domid,
-                                       int *nb_vcpu, int *nrcpus)
+                                       int *nb_vcpu, int *nr_vcpus_out)
 {
     libxl_vcpuinfo *ptr, *ret;
     xc_domaininfo_t domaininfo;
@@ -3280,7 +3281,7 @@ libxl_vcpuinfo *libxl_list_vcpu(libxl_ct
         LIBXL__LOG_ERRNO(ctx, LIBXL__LOG_ERROR, "getting infolist");
         return NULL;
     }
-    *nrcpus = libxl_get_max_cpus(ctx);
+    *nr_vcpus_out = libxl_get_max_cpus(ctx);
     ret = ptr = calloc(domaininfo.max_vcpu_id + 1, sizeof (libxl_vcpuinfo));
     if (!ptr) {
         return NULL;
diff --git a/tools/libxl/libxl.h b/tools/libxl/libxl.h
--- a/tools/libxl/libxl.h
+++ b/tools/libxl/libxl.h
@@ -585,12 +585,28 @@ int libxl_primary_console_get_tty(libxl_
 /* May be called with info_r == NULL to check for domain's existance */
 int libxl_domain_info(libxl_ctx*, libxl_dominfo *info_r,
                       uint32_t domid);
-libxl_dominfo * libxl_list_domain(libxl_ctx*, int *nb_domain);
-void libxl_dominfo_list_free(libxl_dominfo *list, int nr);
-libxl_cpupoolinfo * libxl_list_cpupool(libxl_ctx*, int *nb_pool);
-void libxl_cpupoolinfo_list_free(libxl_cpupoolinfo *list, int nr);
-libxl_vminfo * libxl_list_vm(libxl_ctx *ctx, int *nb_vm);
-void libxl_vminfo_list_free(libxl_vminfo *list, int nr);
+
+/* These functions each return (on success) an array of elements,
+ * and the length via the int* out parameter.  These arrays and
+ * their contents come from malloc, and must be freed with the
+ * corresponding libxl_THING_list_free function.
+ */
+libxl_dominfo * libxl_list_domain(libxl_ctx*, int *nb_domain_out);
+void libxl_dominfo_list_free(libxl_dominfo *list, int nb_domain);
+
+libxl_cpupoolinfo * libxl_list_cpupool(libxl_ctx*, int *nb_pool_out);
+void libxl_cpupoolinfo_list_free(libxl_cpupoolinfo *list, int nb_pool);
+
+libxl_vminfo * libxl_list_vm(libxl_ctx *ctx, int *nb_vm_out);
+void libxl_vminfo_list_free(libxl_vminfo *list, int nb_vm);
+
+#define LIBXL_CPUTOPOLOGY_INVALID_ENTRY (~(uint32_t)0)
+libxl_cputopology *libxl_get_cpu_topology(libxl_ctx *ctx, int *nb_cpu_out);
+void libxl_cputopology_list_free(libxl_cputopology *, int nb_cpu);
+
+libxl_vcpuinfo *libxl_list_vcpu(libxl_ctx *ctx, uint32_t domid,
+                                int *nb_vcpu, int *nr_vcpus_out);
+void libxl_vcpuinfo_list_free(libxl_vcpuinfo *, int nr_vcpus);
 
 /*
  * Devices
@@ -766,12 +782,6 @@ int libxl_userdata_retrieve(libxl_ctx *c
    */
 
 int libxl_get_physinfo(libxl_ctx *ctx, libxl_physinfo *physinfo);
-#define LIBXL_CPUTOPOLOGY_INVALID_ENTRY (~(uint32_t)0)
-libxl_cputopology *libxl_get_cpu_topology(libxl_ctx *ctx, int *nr);
-void libxl_cputopology_list_free(libxl_cputopology *, int nr);
-libxl_vcpuinfo *libxl_list_vcpu(libxl_ctx *ctx, uint32_t domid,
-                                       int *nb_vcpu, int *nrcpus);
-void libxl_vcpuinfo_list_free(libxl_vcpuinfo *, int nr);
 int libxl_set_vcpuaffinity(libxl_ctx *ctx, uint32_t domid, uint32_t vcpuid,
                            libxl_cpumap *cpumap);
 int libxl_set_vcpuaffinity_all(libxl_ctx *ctx, uint32_t domid,