diff options
| -rw-r--r-- | pcap.3pcap.in | 17 | ||||
| -rw-r--r-- | pcap_get_selectable_fd.3pcap | 12 | ||||
| -rw-r--r-- | pcap_loop.3pcap | 7 | ||||
| -rw-r--r-- | pcap_setnonblock.3pcap | 8 |
4 files changed, 37 insertions, 7 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 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; 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 diff --git a/pcap_setnonblock.3pcap b/pcap_setnonblock.3pcap index 37b22031..a99ea076 100644 --- 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. +.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 |