From 644373ce08ceeb3c9abb1949b25931842009ec34 Mon Sep 17 00:00:00 2001 From: Guy Harris Date: Sat, 18 Oct 2014 01:12:14 -0700 Subject: 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. --- pcap.3pcap.in | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) (limited to 'pcap.3pcap.in') 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 -- cgit v1.2.1