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, 9 insertions, 3 deletions

diff --git a/pcap_get_selectable_fd.3pcap b/pcap_get_selectable_fd.3pcap
index 6ae06a1b..6640577e 100644
--- a/pcap_get_selectable_fd.3pcap
+++ b/pcap_get_selectable_fd.3pcap
@@ -36,9 +36,9 @@ int pcap_get_selectable_fd(pcap_t *p);
 returns, on UNIX, a file descriptor number for a file descriptor on
 which one can
 do a
-.B select()
-or
-.B poll()
+.BR select() ,
+.BR poll() ,
+or other such call
 to wait for it to be possible to read packets without blocking, if such
 a descriptor exists, or \-1, if no such descriptor exists.  Some network
 devices opened with
@@ -54,6 +54,12 @@ or
 (for example, regular network devices on FreeBSD 4.3 and 4.4, and Endace
 DAG devices), so \-1 is returned for those devices.
 .PP
+Note that a descriptor on which a read can be done without blocking may,
+on some platforms, not have any packets to read if the read timeout has
+expired.  A call to
+.B pcap_dispatch()
+will return 0 in this case, but will not block.
+.PP
 Note that in:
 .IP
 FreeBSD prior to FreeBSD 4.6;