diff options
Diffstat (limited to 'contrib/libpcap/pcap_get_selectable_fd.3pcap')
-rw-r--r-- | contrib/libpcap/pcap_get_selectable_fd.3pcap | 77 |
1 files changed, 39 insertions, 38 deletions
diff --git a/contrib/libpcap/pcap_get_selectable_fd.3pcap b/contrib/libpcap/pcap_get_selectable_fd.3pcap index 7f43db398e61..ed333038a0a1 100644 --- a/contrib/libpcap/pcap_get_selectable_fd.3pcap +++ b/contrib/libpcap/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 "25 July 2018" +.TH PCAP_GET_SELECTABLE_FD 3PCAP "29 January 2020" .SH NAME pcap_get_selectable_fd \- get a file descriptor on which a select() can be done for a live capture @@ -32,42 +32,42 @@ int pcap_get_selectable_fd(pcap_t *p); .ft .fi .SH DESCRIPTION -.B pcap_get_selectable_fd() +.BR pcap_get_selectable_fd () returns, on UNIX, a file descriptor number for a file descriptor on which one can do a -.BR select(2) , -.BR poll(2) , -.BR epoll_wait(2) , -.BR kevent() , +.BR select (2), +.BR poll (2), +.BR epoll_wait (2), +.BR kevent (2), or other such call to wait for it to be possible to read packets without blocking, if such a descriptor exists, or -.BR PCAP_ERROR , +.BR \-1 , if no such descriptor exists. .PP Some network devices opened with -.B pcap_create(3PCAP) +.BR pcap_create (3PCAP) and -.BR pcap_activate(3PCAP) , +.BR pcap_activate (3PCAP), or with -.BR pcap_open_live(3PCAP) , +.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 +.B \-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 -.B pcap_get_required_select_timeout(3PCAP) +.BR pcap_get_required_select_timeout (3PCAP) for the device for which -.B pcap_get_selectable_fd() +.BR pcap_get_selectable_fd () returned -.BR PCAP_ERROR , +.BR \-1 , the device must be put in non-blocking mode with a call to -.BR \%pcap_setnonblock(3PCAP) , +.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() +.BR \%pcap_get_required_select_timeout () returns .BR NULL , it is not possible to wait for packets to arrive on the device in an @@ -76,9 +76,9 @@ 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 timeout has expired. A call to -.B pcap_dispatch(3PCAP) +.BR pcap_dispatch (3PCAP) or -.B pcap_next_ex(3PCAP) +.BR pcap_next_ex (3PCAP) will return 0 in this case, but will not block. .PP Note that in: @@ -91,18 +91,18 @@ OpenBSD prior to OpenBSD 2.4; .IP Mac OS X prior to Mac OS X 10.7; .PP -.BR select() , -.BR poll() , +.BR select (), +.BR poll (), and -.B kevent() +.BR kevent () do not work correctly on BPF devices; -.B pcap_get_selectable_fd() +.BR 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 -.BR select() , -.BR poll() , +.BR select (), +.BR poll (), or -.B kevent() +.BR 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 @@ -119,33 +119,34 @@ work correctly on BPF devices, so the workaround isn't necessary, although it does no harm.) .PP Note also that -.B poll() +.BR poll () and -.B kevent() +.BR kevent () doesn't work on character special files, including BPF devices, in Mac OS X 10.4 and 10.5, so, while -.B select() +.BR select () can be used on the descriptor returned by -.BR pcap_get_selectable_fd() , -.B poll() +.BR pcap_get_selectable_fd (), +.BR poll () and -.B kevent() +.BR kevent () cannot be used on it those versions of Mac OS X. -.BR poll() , +.BR poll (), but not -.BR kevent() , +.BR kevent (), works on that descriptor in Mac OS X releases prior to 10.4; -.B poll() +.BR poll () and -.B kevent() +.BR kevent () work on that descriptor in Mac OS X 10.6 and later. .PP -.B pcap_get_selectable_fd() +.BR pcap_get_selectable_fd () is not available on Windows. .SH RETURN VALUE A selectable file descriptor is returned if one exists; otherwise, -.B PCAP_ERROR +.B \-1 is returned. .SH SEE ALSO -pcap(3PCAP), kqueue(2) +.BR pcap (3PCAP), +.BR kqueue (2) |