API: Add libusb_free_pollfds() function

This patch adds a new API call to ensure that the same memory
allocator is used to both allocate and free the list of libusb_pollfd
structures. It is an incorrect assumption that the user's free() will
use the same memory allocator that libusb uses internally.

Signed-off-by: Chris Dickens <christopher.a.dickens@gmail.com>

4 files changed, 26 insertions, 4 deletions

diff --git a/libusb/io.c b/libusb/io.c
index 255eab0..2937ad9 100644
--- a/libusb/io.c
+++ b/libusb/io.c
@@ -2643,8 +2643,8 @@ void usbi_remove_pollfd(struct libusb_context *ctx, int fd)
  * Retrieve a list of file descriptors that should be polled by your main loop
  * as libusb event sources.
  *
- * The returned list is NULL-terminated and should be freed with free() when
- * done. The actual list contents must not be touched.
+ * The returned list is NULL-terminated and should be freed with libusb_free_pollfds()
+ * when done. The actual list contents must not be touched.
  *
  * As file descriptors are a Unix-specific concept, this function is not
  * available on Windows and will always return NULL.
@@ -2684,6 +2684,25 @@ out:
 #endif
 }
 
+/** \ingroup poll
+ * Free a list of libusb_pollfd structures. This should be called for all
+ * pollfd lists allocated with libusb_get_pollfds().
+ *
+ * Since version 1.0.20, \ref LIBUSB_API_VERSION >= 0x01000104
+ *
+ * It is legal to call this function with a NULL pollfd list. In this case,
+ * the function will simply return safely.
+ *
+ * \param pollfds the list of libusb_pollfd structures to free
+ */
+void API_EXPORTED libusb_free_pollfds(const struct libusb_pollfd **pollfds)
+{
+	if (!pollfds)
+		return;
+
+	free((void *)pollfds);
+}
+
 /* Backends may call this from handle_events to report disconnection of a
  * device. This function ensures transfers get cancelled appropriately.
  * Callers of this function must hold the events_lock.
diff --git a/libusb/libusb-1.0.def b/libusb/libusb-1.0.def
index d45cfc5..cbcf3e9 100644
--- a/libusb/libusb-1.0.def
+++ b/libusb/libusb-1.0.def
@@ -80,6 +80,8 @@ EXPORTS
   libusb_get_parent@4 = libusb_get_parent
   libusb_get_pollfds
   libusb_get_pollfds@4 = libusb_get_pollfds
+  libusb_free_pollfds
+  libusb_free_pollfds@4 = libusb_free_pollfds
   libusb_get_port_number
   libusb_get_port_number@4 = libusb_get_port_number
   libusb_get_port_numbers
diff --git a/libusb/libusb.h b/libusb/libusb.h
index 9cfdc99..513945f 100644
--- a/libusb/libusb.h
+++ b/libusb/libusb.h
@@ -141,7 +141,7 @@ typedef unsigned __int32  uint32_t;
  * Internally, LIBUSB_API_VERSION is defined as follows:
  * (libusb major << 24) | (libusb minor << 16) | (16 bit incremental)
  */
-#define LIBUSB_API_VERSION 0x01000103
+#define LIBUSB_API_VERSION 0x01000104
 
 /* The following is kept for compatibility, but will be deprecated in the future */
 #define LIBUSBX_API_VERSION LIBUSB_API_VERSION
@@ -1857,6 +1857,7 @@ typedef void (LIBUSB_CALL *libusb_pollfd_removed_cb)(int fd, void *user_data);
 
 const struct libusb_pollfd ** LIBUSB_CALL libusb_get_pollfds(
 	libusb_context *ctx);
+void LIBUSB_CALL libusb_free_pollfds(const struct libusb_pollfd **pollfds);
 void LIBUSB_CALL libusb_set_pollfd_notifiers(libusb_context *ctx,
 	libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb,
 	void *user_data);
diff --git a/libusb/version_nano.h b/libusb/version_nano.h
index f865dc3..cf35d90 100644
--- a/libusb/version_nano.h
+++ b/libusb/version_nano.h
@@ -1 +1 @@
-#define LIBUSB_NANO 10990
+#define LIBUSB_NANO 10991