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.

diff --git a/pcap.3pcap.in b/pcap.3pcap.in
index f5a7e0ca217ad738d60f66fec34629acc8a2dec9..85a2f5b3a581679e8d049c8580dce9a56255e05b 100644 (file)
--- 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
 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
 .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)
 .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;
 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 ()
 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
 .TP
 .B Routines
 .RS

diff --git a/pcap_get_selectable_fd.3pcap b/pcap_get_selectable_fd.3pcap
index 6ae06a1bc429172109fcee47115f265ddc419780..6640577eaabd0fe0e6b802b86a6560d478fa1dd8 100644 (file)
--- 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
 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
 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
 (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;
 Note that in:
 .IP
 FreeBSD prior to FreeBSD 4.6;

diff --git a/pcap_loop.3pcap b/pcap_loop.3pcap
index d18dc06c28b8c11159d21e9906d03ca22202df42..011d85c72587305e39f4ddf44b6e625ffb87123e 100644 (file)
--- 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
 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
 .ft B
 (In older versions of libpcap, the behavior when
 \fIcnt\fP

diff --git a/pcap_setnonblock.3pcap b/pcap_setnonblock.3pcap
index 37b22031d451a4afc171c3daadef95598bbafe16..a99ea076ed9cce221980ac27cc381f04de97068d 100644 (file)
--- a/pcap_setnonblock.3pcap
+++ b/pcap_setnonblock.3pcap
@@ -57,6 +57,14 @@ immediately rather than blocking waiting for packets to arrive.
 and
 .B pcap_next()
 will not work in ``non-blocking'' mode.
 and
 .B pcap_next()
 will not work in ``non-blocking'' mode.

+.PP
+When first activated with
+.B pcap_activate()
+or opened with
+.B pcap_open_live() ,
+a capture handle is not in ``non-blocking mode''; a call to
+.B pcap_setnonblock()
+is required in order to put it into ``non-blocking'' mode.

 .SH RETURN VALUE
 .B pcap_getnonblock()
 returns the current ``non-blocking'' state of the capture descriptor; it
 .SH RETURN VALUE
 .B pcap_getnonblock()
 returns the current ``non-blocking'' state of the capture descriptor; it