Be more emphatic that a read timeout may cause no packets to be read.

Note, in more places, that if you call pcap_dispatch() on a pcap_t for
which there's a read timeout, it might return 0 if the read timeout
expires and there are no packets to be read - but that this behavior is
not guaranteed (so write your code to be able to handle it if it does
happen but not to depend on it happening).

Note also that a select()/poll()/etc. on the selectable descriptor for
the pcap_t might report the descriptor as readable if the read timeout
expires, even if there are no packets available to read - but that it
might not (so write your code to be able to handle it if it does happen
but not to depend on it happening).

Also, note that pcap_t's start out blocking, so they don't think that a
0 return from pcap_dispatch() means it's non-blocking and that they need
to call pcap_setnonblock() to put it in blocking mode.

1 files changed, 13 insertions, 4 deletions

diff --git a/pcap.3pcap.in b/pcap.3pcap.in
index f5a7e0ca..85a2f5b3 100644
--- a/pcap.3pcap.in
+++ b/pcap.3pcap.in
@@ -580,7 +580,9 @@ for packets to become available.  On some, but
 all, platforms, if a read timeout was specified, the wait will terminate
 after the read timeout expires; applications should be prepared for
 this, as it happens on some platforms, but should not rely on it, as it
-does not happen on other platforms.
+does not happen on other platforms.  Note that the wait might, or might
+not, terminate even if no packets are available; applications should be
+prepared for this to happen, but must not rely on it happening.
 .PP
 A handle can be put into ``non-blocking mode'', so that those routines
 will, rather than blocking, return an indication that no packets are
@@ -596,8 +598,8 @@ Non-blocking mode is often combined with routines such as
 .BR select (2)
 or
 .BR poll (2)
-or other routines a platform offers to wait for the availability of data
-on any of a set of descriptors.  To obtain, for a handle, a descriptor
+or other routines a platform offers to wait for any of a set of
+descriptors to be ready to read.  To obtain, for a handle, a descriptor
 that can be used in those routines, call
 .BR pcap_get_selectable_fd ().
 Not all handles have such a descriptor available;
@@ -606,7 +608,14 @@ will return \-1 if no such descriptor exists.  In addition, for various
 reasons, one or more of those routines will not work properly with the
 descriptor; the documentation for
 .BR pcap_get_selectable_fd ()
-gives details.
+gives details.  Note that, just as an attempt to read packets from a
+.B pcap_t
+may not return any packets if the read timeout expires, a
+.BR select (),
+.BR poll (),
+or other such call may, if the read timeout expires, indicate that a
+descriptor is ready to read even if there are no packets available to
+read.
 .TP
 .B Routines
 .RS