1PCAP_GET_REQUIRED_SELECT_TIMEOUT(3PCAP)PCAP_GET_REQUIRED_SELECT_TIMEOUT(3PCAP)
2
3
4

NAME

6       pcap_get_required_select_timeout  - get a timeout to be used when doing
7       select() for a live capture
8

SYNOPSIS

10       #include <pcap/pcap.h>
11
12       const struct timeval *pcap_get_required_select_timeout(pcap_t *p);
13

DESCRIPTION

15       pcap_get_required_select_timeout() returns, on UNIX,  a  pointer  to  a
16       struct  timeval  containing  a  value  that must be used as the minimum
17       timeout in select(2), poll(2), epoll_wait(2), and kevent(2)  calls,  or
18       NULL  if there is no such timeout.  If a non-NULL value is returned, it
19       must be used regardless of  whether  pcap_get_selectable_fd(3PCAP)  re‐
20       turns  -1  for  any  descriptor  on  which  those calls are being done.
21       pcap_get_required_select_timeout() should be called for all pcap_ts be‐
22       fore  a  call  to  select(), poll(), epoll_wait(), or kevent(), and any
23       timeouts used for those calls should be updated  as  appropriate  given
24       the new value of the timeout.
25
26       For  kevent(), one EVFILT_TIMER filter per selectable descriptor can be
27       used, rather than using the timeout argument to kevent();  if  the  EV‐
28       FILT_TIMER  event  for  a  particular  selectable descriptor signals an
29       event, pcap_dispatch(3PCAP) should  be  called  for  the  corresponding
30       pcap_t.
31
32       On  Linux  systems  with timerfd_create(2), one timer object created by
33       timerfd_create() per selectable descriptor can be used, rather than us‐
34       ing  the  timeout  argument  to epoll_wait(); if the timer object for a
35       particular selectable descriptor signals an event, pcap_dispatch(3PCAP)
36       should be called for the corresponding pcap_t.
37
38       Otherwise,  a timeout value no larger than the smallest of all timeouts
39       returned by pcap_get_required_select_timeout() for devices  from  which
40       packets  will be captured and any other timeouts to be used in the call
41       should be used as the timeout for the call, and, when the call returns,
42       pcap_dispatch(3PCAP)  should be called for all pcap_ts for which a non-
43       NULL timeout was returned, regardless of whether it's indicated as hav‐
44       ing anything to read from it or not.
45
46       All  devices  with  a non-NULL timeout must be put in non-blocking mode
47       with pcap_setnonblock(3PCAP).
48
49       Note that a device on which a read can be done without blocking may, on
50       some platforms, not have any packets to read if the packet buffer time‐
51       out has expired.  A call to pcap_dispatch() or pcap_next_ex(3PCAP) will
52       return 0 in this case, but will not block.
53
54       pcap_get_required_select_timeout() is not available on Windows.
55

RETURN VALUE

57       A  pointer  to a struct timeval is returned if the timeout is required;
58       otherwise NULL is returned.
59

BACKWARD COMPATIBILITY

61       This function became available in libpcap release 1.9.0.   In  previous
62       releases,  select(),  poll(),  epoll_wait(),  and kevent() could not be
63       used for devices that don't provide a selectable  file  descriptor  (in
64       other  words,  on  any capture source for that pcap_get_selectable_fd()
65       returns -1).
66
67       In libpcap release 1.10.0 and later, the timeout value can change  from
68       call  to call, so pcap_get_required_select_timeout() must be called be‐
69       fore each call to select(), poll(), epoll_wait(), or kevent(), and  the
70       new  value  must be used to calculate timeouts for the call.  Code that
71       does that will also work with libpcap 1.9.x  releases,  so  code  using
72       pcap_get_required_select_timeout()  should  be  changed  to call it for
73       each call to select(), poll(), epoll_wait(), or kevent()  even  if  the
74       code must also work with libpcap 1.9.x.
75

SEE ALSO

77       pcap(3PCAP),    pcap_get_selectable_fd(3PCAP),    select(2),   poll(2),
78       epoll_wait(2), kqueue(2)
79
80
81
82                                29 JanuaPrCyAP2_0G2E0T_REQUIRED_SELECT_TIMEOUT(3PCAP)
Impressum