Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PCAP_GET_SELECTABLE_FD(3)  Library Functions Manual  PCAP_GET_SELECTABLE_FD(3)

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

SYNOPSIS
       #include	<pcap/pcap.h>

       int pcap_get_selectable_fd(pcap_t *p);

DESCRIPTION
       pcap_get_selectable_fd()	returns, on UNIX, a file descriptor number for
       a file descriptor on which one can do a select(), poll(), epoll_wait(),
       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	pcap_create() and pcap_activate(),  or
       with pcap_open_live(), do not support those calls (for example, regular
       network devices on FreeBSD 4.3 and 4.4, and Endace DAG devices),	so  -1
       is returned for those devices.  In that case, those calls must be given
       a timeout less than or equal to the timeout  returned  by  pcap_get_re-
       quired_select_timeout()	 for   the   device   for  which  pcap_get_se-
       lectable_fd() returned -1, the device must be put in non-blocking  mode
       with  a	call to	pcap_setnonblock(), and	an attempt must	always be made
       to read packets from the	device when the	call returns.  If pcap_get_re-
       quired_select_timeout()	returns	 NULL,	it is not possible to wait for
       packets to arrive on the	device in an event loop.

       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 time-
       out has expired.	 A call	to pcap_dispatch() or pcap_next_ex() will  re-
       turn 0 in this case, but	will not block.

       Note that in:

	      FreeBSD prior to FreeBSD 4.6;

	      NetBSD prior to NetBSD 3.0;

	      OpenBSD prior to OpenBSD 2.4;

	      Mac OS X prior to	Mac OS X 10.7;

       select(),  poll(),  and	kevent() do not	work correctly on BPF devices;
       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 se-
       lect(), poll(), or 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 pcap_t 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 pack-
       ets after that timeout expires, regardless of whether  the  call	 indi-
       cated  that  the	 file descriptor for the 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, those calls work correctly on BPF devices, so
       the workaround isn't necessary, although	it does	no harm.)

       Note also that poll() and kevent() doesn't work	on  character  special
       files,  including BPF devices, in Mac OS	X 10.4 and 10.5, so, while se-
       lect()  can  be	used  on  the  descriptor  returned  by	  pcap_get_se-
       lectable_fd(),  poll() and kevent() cannot be used on it	those versions
       of Mac OS X.  poll(), but not kevent(), works on	that descriptor	in Mac
       OS  X releases prior to 10.4; poll() and	kevent() work on that descrip-
       tor in Mac OS X 10.6 and	later.

       pcap_get_selectable_fd()	is not available on Windows.

RETURN VALUE
       A selectable file descriptor is returned	if one exists;	otherwise,  -1
       is returned.

SEE ALSO
       pcap(3),	 pcap_get_required_select_timeout(3), pcap_setnonblock(3), se-
       lect(2),	poll(2), epoll_wait(2),	kqueue(2)

				20 January 2017	     PCAP_GET_SELECTABLE_FD(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pcap_get_selectable_fd&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help