From: Hans de Goede <hdegoede@redhat.com>
Date: Wed, 14 Sep 2011 08:53:48 +0000 (+0200)
Subject: Docs: Clarify that libusb_handle_events_timeout() tv param can't be NULL
X-Git-Tag: upstream/1.0.21~777
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=9ad3643391a7fc6ce97aa77ffaf97d244fd9e613;p=platform%2Fupstream%2Flibusb.git

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
--- 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)
-		libusb_handle_events_timeout(ctx, 0);
+		libusb_handle_events_timeout(ctx, &zero_tv);
 	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
 }
 
@@ -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)
-		libusb_handle_events_timeout(ctx, 0);
+		libusb_handle_events_timeout(ctx, &zero_tv);
 	// handle events from other sources here
 }
 
@@ -741,7 +741,7 @@ void myfunc() {
 	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
@@ -840,7 +840,7 @@ void myfunc() {
 	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
@@ -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
- * \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
@@ -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
- * \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,