JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 1 | .\" @(#) $Header: /tcpdump/master/libpcap/pcap_get_selectable_fd.3pcap,v 1.3 2008-04-06 02:53:22 guy Exp $ |
| 2 | .\" |
| 3 | .\" Copyright (c) 1994, 1996, 1997 |
| 4 | .\" The Regents of the University of California. All rights reserved. |
| 5 | .\" |
| 6 | .\" Redistribution and use in source and binary forms, with or without |
| 7 | .\" modification, are permitted provided that: (1) source code distributions |
| 8 | .\" retain the above copyright notice and this paragraph in its entirety, (2) |
| 9 | .\" distributions including binary code include the above copyright notice and |
| 10 | .\" this paragraph in its entirety in the documentation or other materials |
| 11 | .\" provided with the distribution, and (3) all advertising materials mentioning |
| 12 | .\" features or use of this software display the following acknowledgement: |
| 13 | .\" ``This product includes software developed by the University of California, |
| 14 | .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of |
| 15 | .\" the University nor the names of its contributors may be used to endorse |
| 16 | .\" or promote products derived from this software without specific prior |
| 17 | .\" written permission. |
| 18 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED |
| 19 | .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF |
| 20 | .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
| 21 | .\" |
| 22 | .TH PCAP_GET_SELECTABLE_FD 3PCAP "5 April 2008" |
| 23 | .SH NAME |
| 24 | pcap_get_selectable_fd \- get a file descriptor on which a select() can |
| 25 | be done for a live capture |
| 26 | .SH SYNOPSIS |
| 27 | .nf |
| 28 | .ft B |
| 29 | #include <pcap/pcap.h> |
| 30 | .ft |
| 31 | .LP |
| 32 | .ft B |
| 33 | int pcap_get_selectable_fd(pcap_t *p); |
| 34 | .ft |
| 35 | .fi |
| 36 | .SH DESCRIPTION |
| 37 | .B pcap_get_selectable_fd() |
| 38 | returns, on UNIX, a file descriptor number for a file descriptor on |
| 39 | which one can |
| 40 | do a |
| 41 | .B select() |
| 42 | or |
| 43 | .B poll() |
| 44 | to wait for it to be possible to read packets without blocking, if such |
| 45 | a descriptor exists, or \-1, if no such descriptor exists. Some network |
| 46 | devices opened with |
| 47 | .B pcap_create() |
| 48 | and |
| 49 | .BR pcap_activate() , |
| 50 | or with |
| 51 | .BR pcap_open_live() , |
| 52 | do not support |
| 53 | .B select() |
| 54 | or |
| 55 | .B poll() |
| 56 | (for example, regular network devices on FreeBSD 4.3 and 4.4, and Endace |
| 57 | DAG devices), so \-1 is returned for those devices. |
| 58 | .PP |
| 59 | Note that in: |
| 60 | .IP |
| 61 | FreeBSD prior to FreeBSD 4.6; |
| 62 | .IP |
| 63 | NetBSD prior to NetBSD 3.0; |
| 64 | .IP |
| 65 | OpenBSD prior to OpenBSD 2.4; |
| 66 | .IP |
| 67 | Mac OS X prior to Mac OS X 10.7; |
| 68 | .PP |
| 69 | .B select() |
| 70 | and |
| 71 | .B poll() |
| 72 | do not work correctly on BPF devices; |
| 73 | .B pcap_get_selectable_fd() |
| 74 | will return a file descriptor on most of those versions (the exceptions |
| 75 | being FreeBSD 4.3 and 4.4), but a simple |
| 76 | .B select() |
| 77 | or |
| 78 | .B poll() |
| 79 | will not indicate that the descriptor is readable until a full buffer's |
| 80 | worth of packets is received, even if the read timeout expires before |
| 81 | then. To work around this, an application that uses |
| 82 | .B select() |
| 83 | or |
| 84 | .B poll() |
| 85 | to wait for packets to arrive must put the |
| 86 | .B pcap_t |
| 87 | in non-blocking mode, and must arrange that the |
| 88 | .B select() |
| 89 | or |
| 90 | .B poll() |
| 91 | have a timeout less than or equal to the read timeout, |
| 92 | and must try to read packets after that timeout expires, regardless of |
| 93 | whether |
| 94 | .B select() |
| 95 | or |
| 96 | .B poll() |
| 97 | indicated that the file descriptor for the |
| 98 | .B pcap_t |
| 99 | is ready to be read or not. (That workaround will not work in FreeBSD |
| 100 | 4.3 and later; however, in FreeBSD 4.6 and later, |
| 101 | .B select() |
| 102 | and |
| 103 | .B poll() |
| 104 | work correctly on BPF devices, so the workaround isn't necessary, |
| 105 | although it does no harm.) |
| 106 | .PP |
| 107 | Note also that |
| 108 | .B poll() |
| 109 | doesn't work on character special files, including BPF devices, in Mac |
| 110 | OS X 10.4 and 10.5, so, while |
| 111 | .B select() |
| 112 | can be used on the descriptor returned by |
| 113 | .BR pcap_get_selectable_fd() , |
| 114 | .B poll() |
| 115 | cannot be used on it those versions of Mac OS X. Kqueues also don't |
| 116 | work on that descriptor. |
| 117 | .BR poll() , |
| 118 | but not kqueues, work on that descriptor in Mac OS X releases prior to |
| 119 | 10.4; |
| 120 | .B poll() |
| 121 | and kqueues work on that descriptor in Mac OS X 10.6 and later. |
| 122 | .PP |
| 123 | .B pcap_get_selectable_fd() |
| 124 | is not available on Windows. |
| 125 | .SH RETURN VALUE |
| 126 | A selectable file descriptor is returned if one exists; otherwise, \-1 |
| 127 | is returned. |
| 128 | .SH SEE ALSO |
| 129 | pcap(3PCAP), select(2), poll(2) |