Imported Upstream version 1.9.1upstream/1.9.1upstream

Change-Id: I8ccc371679c730299ebe8068ed5af0ae033c4f7d
Signed-off-by: Cheoleun Moon <chleun.moon@samsung.com>

1 files changed, 69 insertions, 45 deletions

diff --git a/pcap_get_selectable_fd.3pcap b/pcap_get_selectable_fd.3pcap
index 6ae06a1..7f43db3 100644
--- a/pcap_get_selectable_fd.3pcap
+++ b/pcap_get_selectable_fd.3pcap
@@ -17,7 +17,7 @@
 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 .\"
-.TH PCAP_GET_SELECTABLE_FD 3PCAP "22 July 2011"
+.TH PCAP_GET_SELECTABLE_FD 3PCAP "25 July 2018"
 .SH NAME
 pcap_get_selectable_fd \- get a file descriptor on which a select() can
 be done for a live capture
@@ -36,23 +36,50 @@ 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(2) ,
+.BR poll(2) ,
+.BR epoll_wait(2) ,
+.BR kevent() ,
+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
-.B pcap_create()
+a descriptor exists, or
+.BR PCAP_ERROR ,
+if no such descriptor exists.
+.PP
+Some network devices opened with
+.B pcap_create(3PCAP)
 and
-.BR pcap_activate() ,
+.BR pcap_activate(3PCAP) ,
 or with
-.BR pcap_open_live() ,
-do not support
-.B select()
+.BR pcap_open_live(3PCAP) ,
+do not support those calls (for example, regular network devices on
+FreeBSD 4.3 and 4.4, and Endace DAG devices), so
+.B PCAP_ERROR
+is returned for
+those devices.  In that case, those calls must be given a timeout less
+than or equal to the timeout returned by
+.B pcap_get_required_select_timeout(3PCAP)
+for the device for which
+.B pcap_get_selectable_fd()
+returned
+.BR PCAP_ERROR ,
+the device must be put in non-blocking mode with a call to
+.BR \%pcap_setnonblock(3PCAP) ,
+and an attempt must always be made to read packets from the device
+when the call returns.  If
+.B \%pcap_get_required_select_timeout()
+returns
+.BR NULL ,
+it is not possible to wait for packets to arrive on the device in an
+event loop.
+.PP
+Note that a device on which a read can be done without blocking may,
+on some platforms, not have any packets to read if the packet buffer
+timeout has expired.  A call to
+.B pcap_dispatch(3PCAP)
 or
-.B poll()
-(for example, regular network devices on FreeBSD 4.3 and 4.4, and Endace
-DAG devices), so \-1 is returned for those devices.
+.B pcap_next_ex(3PCAP)
+will return 0 in this case, but will not block.
 .PP
 Note that in:
 .IP
@@ -64,64 +91,61 @@ OpenBSD prior to OpenBSD 2.4;
 .IP
 Mac OS X prior to Mac OS X 10.7;
 .PP
-.B select()
+.BR select() ,
+.BR poll() ,
 and
-.B poll()
+.B kevent()
 do not work correctly on BPF devices;
 .B pcap_get_selectable_fd()
 will return a file descriptor on most of those versions (the exceptions
 being FreeBSD 4.3 and 4.4), but a simple
-.B select()
-or
-.B poll()
-will not indicate that the descriptor is readable until a full buffer's
-worth of packets is received, even if the read timeout expires before
-then.  To work around this, an application that uses
-.B select()
+.BR select() ,
+.BR poll() ,
 or
-.B poll()
-to wait for packets to arrive must put the
+.B kevent()
+call will not indicate that the descriptor is readable until a full
+buffer's worth of packets is received, even if the packet timeout
+expires before then.  To work around this, code that uses
+those calls to wait for packets to arrive must put the
 .B pcap_t
-in non-blocking mode, and must arrange that the
-.B select()
-or
-.B poll()
-have a timeout less than or equal to the read timeout,
+in non-blocking mode, and must arrange that the call
+have a timeout less than or equal to the packet buffer timeout,
 and must try to read packets after that timeout expires, regardless of
-whether
-.B select()
-or
-.B poll()
-indicated that the file descriptor for the
+whether the call indicated that the file descriptor for the
 .B pcap_t
 is ready to be read or not.  (That workaround will not work in FreeBSD
-4.3 and later; however, in FreeBSD 4.6 and later,
-.B select()
-and
-.B poll()
+4.3 and later; however, in FreeBSD 4.6 and later, those calls
 work correctly on BPF devices, so the workaround isn't necessary,
 although it does no harm.)
 .PP
 Note also that
 .B poll()
+and
+.B kevent()
 doesn't work on character special files, including BPF devices, in Mac
 OS X 10.4 and 10.5, so, while
 .B select()
 can be used on the descriptor returned by
 .BR pcap_get_selectable_fd() ,
 .B poll()
-cannot be used on it those versions of Mac OS X.  Kqueues also don't
-work on that descriptor.
+and
+.B kevent()
+cannot be used on it those versions of Mac OS X.
 .BR poll() ,
-but not kqueues, work on that descriptor in Mac OS X releases prior to
+but not
+.BR kevent() ,
+works on that descriptor in Mac OS X releases prior to
 10.4;
 .B poll()
-and kqueues work on that descriptor in Mac OS X 10.6 and later.
+and
+.B kevent()
+work on that descriptor in Mac OS X 10.6 and later.
 .PP
 .B pcap_get_selectable_fd()
 is not available on Windows.
 .SH RETURN VALUE
-A selectable file descriptor is returned if one exists; otherwise, \-1
+A selectable file descriptor is returned if one exists; otherwise,
+.B PCAP_ERROR
 is returned.
 .SH SEE ALSO
-pcap(3PCAP), select(2), poll(2)
+pcap(3PCAP), kqueue(2)