1PCAP_GET_SELECTABLE_FD(3PCAP)                    PCAP_GET_SELECTABLE_FD(3PCAP)
2
3
4

NAME

6       pcap_get_selectable_fd  - get a file descriptor on which a select() can
7       be done for a live capture
8

SYNOPSIS

10       #include <pcap/pcap.h>
11
12       int pcap_get_selectable_fd(pcap_t *p);
13

DESCRIPTION

15       pcap_get_selectable_fd() returns, on UNIX, a file descriptor number for
16       a   file   descriptor  on  which  one  can  do  a  select(2),  poll(2),
17       epoll_wait(2), kevent(), or other such call to wait for it to be possi‐
18       ble  to  read packets without blocking, if such a descriptor exists, or
19       PCAP_ERROR, if no such descriptor exists.
20
21       Some network devices  opened  with  pcap_create(3PCAP)  and  pcap_acti‐
22       vate(3PCAP),  or with pcap_open_live(3PCAP), do not support those calls
23       (for example, regular network devices  on  FreeBSD  4.3  and  4.4,  and
24       Endace  DAG  devices), so PCAP_ERROR is returned for those devices.  In
25       that case, those calls must be given a timeout less than  or  equal  to
26       the timeout returned by pcap_get_required_select_timeout(3PCAP) for the
27       device for  which  pcap_get_selectable_fd()  returned  PCAP_ERROR,  the
28       device   must   be   put   in   non-blocking   mode   with  a  call  to
29       pcap_setnonblock(3PCAP), and an attempt must always  be  made  to  read
30       packets    from    the    device    when    the   call   returns.    If
31       pcap_get_required_select_timeout() returns NULL, it is not possible  to
32       wait for packets to arrive on the device in an event loop.
33
34       Note that a device on which a read can be done without blocking may, on
35       some platforms, not have any packets to read if the packet buffer time‐
36       out has expired.  A call to pcap_dispatch(3PCAP) or pcap_next_ex(3PCAP)
37       will return 0 in this case, but will not block.
38
39       Note that in:
40
41              FreeBSD prior to FreeBSD 4.6;
42
43              NetBSD prior to NetBSD 3.0;
44
45              OpenBSD prior to OpenBSD 2.4;
46
47              Mac OS X prior to Mac OS X 10.7;
48
49       select(), poll(), and kevent() do not work correctly  on  BPF  devices;
50       pcap_get_selectable_fd() will return a file descriptor on most of those
51       versions (the exceptions being FreeBSD  4.3  and  4.4),  but  a  simple
52       select(),  poll(), or kevent() call will not indicate that the descrip‐
53       tor is readable until a full buffer's worth  of  packets  is  received,
54       even  if  the packet timeout expires before then.  To work around this,
55       code that uses those calls to wait for packets to arrive must  put  the
56       pcap_t  in  non-blocking  mode,  and  must arrange that the call have a
57       timeout less than or equal to the packet buffer timeout, and  must  try
58       to  read  packets after that timeout expires, regardless of whether the
59       call indicated that the file descriptor for the pcap_t is ready  to  be
60       read  or not.  (That workaround will not work in FreeBSD 4.3 and later;
61       however, in FreeBSD 4.6 and later, those calls work  correctly  on  BPF
62       devices, so the workaround isn't necessary, although it does no harm.)
63
64       Note  also  that  poll() and kevent() doesn't work on character special
65       files, including BPF devices, in Mac OS X  10.4  and  10.5,  so,  while
66       select()    can    be    used    on    the   descriptor   returned   by
67       pcap_get_selectable_fd(), poll() and kevent()  cannot  be  used  on  it
68       those  versions  of  Mac OS X.  poll(), but not kevent(), works on that
69       descriptor in Mac OS X releases prior to 10.4; poll() and kevent() work
70       on that descriptor in Mac OS X 10.6 and later.
71
72       pcap_get_selectable_fd() is not available on Windows.
73

RETURN VALUE

75       A  selectable  file  descriptor  is  returned if one exists; otherwise,
76       PCAP_ERROR is returned.
77

SEE ALSO

79       pcap(3PCAP), kqueue(2)
80
81
82
83                                 25 July 2018    PCAP_GET_SELECTABLE_FD(3PCAP)
Impressum