[libvirt] [PATCH] util: add note about event file descriptors on Windows
When using GNULIB with Winsock, libvirt will never see the normal HANDLE
objects, instead GNULIB guarantees that libvirt gets a C runtime file
descriptor. The GNULIB poll impl also expects to get C runtime file
descriptors rather than HANDLE objects. Document this behaviour so that
it is clear to applications providing event loop implementations if they
need Windows portability.
Signed-off-by: Daniel P. Berrangé <berrange(a)redhat.com>
---
include/libvirt/libvirt-event.h | 4 ++++
src/util/virevent.c | 7 +++++++
2 files changed, 11 insertions(+)
diff --git a/include/libvirt/libvirt-event.h b/include/libvirt/libvirt-event.h
index 734dbdcbc1..facdc3a3ec 100644
--- a/include/libvirt/libvirt-event.h
+++ b/include/libvirt/libvirt-event.h
@@ -67,6 +67,10 @@ typedef void (*virEventHandleCallback)(int watch, int fd, int events,
void *opaq
* listen for specific events. The same file handle can be registered
* multiple times provided the requested event sets are non-overlapping
*
+ * @fd will always be a C runtime file descriptor. On Windows
+ * the _get_osfhandle() method can be used if a HANDLE is required
+ * instead.
+ *
* If the opaque user data requires free'ing when the handle
* is unregistered, then a 2nd callback can be supplied for
* this purpose. This callback needs to be invoked from a clean stack.
diff --git a/src/util/virevent.c b/src/util/virevent.c
index f6c797724e..fd5d8f5bf1 100644
--- a/src/util/virevent.c
+++ b/src/util/virevent.c
@@ -60,6 +60,13 @@ static virEventRemoveTimeoutFunc removeTimeoutImpl;
* requires that an event loop has previously been registered with
* virEventRegisterImpl() or virEventRegisterDefaultImpl().
*
+ * @fd must always always be a C runtime file descriptor. On Windows
+ * if the caller only has a HANDLE, the _open_osfhandle() method can
+ * be used to open an associated C runtime file descriptor for use
+ * with this API. After opening a runtime file descriptor, CloseHandle()
+ * must not be used, instead close() will close the runtime file
+ * descriptor and its original associated HANDLE.
+ *
* Returns -1 if the file handle cannot be registered, otherwise a handle
* watch number to be used for updating and unregistering for events.
*/
--
2.21.0