Docs: Clarify that libusb_handle_events_timeout() tv param can't be NULL

The example code and API doc for libusb_handle_events_timeout() could be
interpreted as it being OK to pass a NULL pointer for the tv argument (I
interpreted it like that when I first started coding for libusb).

This patch changes the docs to make it clear that one must always supply
a tv struct to libusb_handle_events_timeout.

Signed-off-by: Hans de Goede <hdegoede@redhat.com>

diff --git a/libusb/io.c b/libusb/io.c
index 19454c6..35f9e2a 100644 (file)
--- a/libusb/io.c
+++ b/libusb/io.c
@@ -621,9 +621,9 @@ while (user has not requested application exit) {
        poll(on libusb file descriptors plus any other event sources of interest,
                using a timeout no larger than the value libusb just suggested)
        if (poll() indicated activity on libusb file descriptors)
        poll(on libusb file descriptors plus any other event sources of interest,
                using a timeout no larger than the value libusb just suggested)
        if (poll() indicated activity on libusb file descriptors)

-               libusb_handle_events_timeout(ctx, 0);
+               libusb_handle_events_timeout(ctx, &zero_tv);

        if (time has elapsed to or beyond the libusb timeout)
        if (time has elapsed to or beyond the libusb timeout)

-               libusb_handle_events_timeout(ctx, 0);
+               libusb_handle_events_timeout(ctx, &zero_tv);

        // handle events from other sources here
 }
 
        // handle events from other sources here
 }
 


@@ -656,7 +656,7 @@ while (user has not requested application exit) {
        poll(on libusb file descriptors plus any other event sources of interest,
                using any timeout that you like)
        if (poll() indicated activity on libusb file descriptors)
        poll(on libusb file descriptors plus any other event sources of interest,
                using any timeout that you like)
        if (poll() indicated activity on libusb file descriptors)

-               libusb_handle_events_timeout(ctx, 0);
+               libusb_handle_events_timeout(ctx, &zero_tv);

        // handle events from other sources here
 }
 
        // handle events from other sources here
 }
 


@@ -741,7 +741,7 @@ void myfunc() {
        while (!completed) {
                poll(libusb file descriptors, 120*1000);
                if (poll indicates activity)
        while (!completed) {
                poll(libusb file descriptors, 120*1000);
                if (poll indicates activity)

-                       libusb_handle_events_timeout(ctx, 0);
+                       libusb_handle_events_timeout(ctx, &zero_tv);

        }
        printf("completed!");
        // other code here
        }
        printf("completed!");
        // other code here


@@ -840,7 +840,7 @@ void myfunc() {
        while (!completed) {
                poll(libusb file descriptors, 120*1000);
                if (poll indicates activity)
        while (!completed) {
                poll(libusb file descriptors, 120*1000);
                if (poll indicates activity)

-                       libusb_handle_events_timeout(ctx, 0);
+                       libusb_handle_events_timeout(ctx, &zero_tv);

        }
        libusb_unlock_events(ctx);
 \endcode
        }
        libusb_unlock_events(ctx);
 \endcode


@@ -1988,8 +1988,8 @@ static int get_next_timeout(libusb_context *ctx, struct timeval *tv,
  * of a specific transfer.
  *
  * \param ctx the context to operate on, or NULL for the default context
  * of a specific transfer.
  *
  * \param ctx the context to operate on, or NULL for the default context

- * \param tv the maximum time to block waiting for events, or zero for
- * non-blocking mode
+ * \param tv the maximum time to block waiting for events, or an all zero
+ * timeval struct for non-blocking mode

  * \param completed pointer to completion integer to check, or NULL
  * \returns 0 on success, or a LIBUSB_ERROR code on failure
  * \see \ref mtasync
  * \param completed pointer to completion integer to check, or NULL
  * \returns 0 on success, or a LIBUSB_ERROR code on failure
  * \see \ref mtasync


@@ -2059,8 +2059,8 @@ already_done:
  * libusb_handle_events_timeout_completed() to avoid race conditions.
  *
  * \param ctx the context to operate on, or NULL for the default context
  * libusb_handle_events_timeout_completed() to avoid race conditions.
  *
  * \param ctx the context to operate on, or NULL for the default context

- * \param tv the maximum time to block waiting for events, or zero for
- * non-blocking mode
+ * \param tv the maximum time to block waiting for events, or an all zero
+ * timeval struct for non-blocking mode

  * \returns 0 on success, or a LIBUSB_ERROR code on failure
  */
 int API_EXPORTED libusb_handle_events_timeout(libusb_context *ctx,
  * \returns 0 on success, or a LIBUSB_ERROR code on failure
  */
 int API_EXPORTED libusb_handle_events_timeout(libusb_context *ctx,