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, 7 insertions, 0 deletions

diff --git a/pcap_loop.3pcap b/pcap_loop.3pcap
index d18dc06c..011d85c7 100644
--- a/pcap_loop.3pcap
+++ b/pcap_loop.3pcap
@@ -77,6 +77,13 @@ causes all the packets received in one buffer to be processed when
 reading a live capture, and causes all the packets in the file to be
 processed when reading a ``savefile''.
 .PP
+Note that, when doing a live capture on some platforms, if the read
+timeout expires when there are no packets available,
+.B pcap_dispatch()
+will return 0, even when not in non-blocking mode, as there are no
+packets to process.  Applications should be prepared for this to happen,
+but must not rely on it happening.
+.PP
 .ft B
 (In older versions of libpcap, the behavior when
 \fIcnt\fP