Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 1 | .\" Copyright (c) 1994, 1996, 1997 |
| 2 | .\" The Regents of the University of California. All rights reserved. |
| 3 | .\" |
| 4 | .\" Redistribution and use in source and binary forms, with or without |
| 5 | .\" modification, are permitted provided that: (1) source code distributions |
| 6 | .\" retain the above copyright notice and this paragraph in its entirety, (2) |
| 7 | .\" distributions including binary code include the above copyright notice and |
| 8 | .\" this paragraph in its entirety in the documentation or other materials |
| 9 | .\" provided with the distribution, and (3) all advertising materials mentioning |
| 10 | .\" features or use of this software display the following acknowledgement: |
| 11 | .\" ``This product includes software developed by the University of California, |
| 12 | .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of |
| 13 | .\" the University nor the names of its contributors may be used to endorse |
| 14 | .\" or promote products derived from this software without specific prior |
| 15 | .\" written permission. |
| 16 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED |
| 17 | .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF |
| 18 | .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
| 19 | .\" |
Haibo Huang | ee759ce | 2021-01-05 21:34:29 -0800 | [diff] [blame] | 20 | .TH PCAP_GET_REQUIRED_SELECT_TIMEOUT 3PCAP "29 January 2020" |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 21 | .SH NAME |
Haibo Huang | ee759ce | 2021-01-05 21:34:29 -0800 | [diff] [blame] | 22 | pcap_get_required_select_timeout \- get a timeout to be used when doing |
| 23 | select() for a live capture |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 24 | .SH SYNOPSIS |
| 25 | .nf |
| 26 | .ft B |
| 27 | #include <pcap/pcap.h> |
| 28 | .ft |
| 29 | .LP |
| 30 | .ft B |
Haibo Huang | ee759ce | 2021-01-05 21:34:29 -0800 | [diff] [blame] | 31 | const struct timeval *pcap_get_required_select_timeout(pcap_t *p); |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 32 | .ft |
| 33 | .fi |
| 34 | .SH DESCRIPTION |
Haibo Huang | ee759ce | 2021-01-05 21:34:29 -0800 | [diff] [blame] | 35 | .BR pcap_get_required_select_timeout () |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 36 | returns, on UNIX, a pointer to a |
| 37 | .B struct timeval |
| 38 | containing a value that must be used as the minimum timeout in |
Haibo Huang | ee759ce | 2021-01-05 21:34:29 -0800 | [diff] [blame] | 39 | .BR select (2), |
| 40 | .BR poll (2), |
| 41 | .BR epoll_wait (2), |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 42 | and |
Haibo Huang | ee759ce | 2021-01-05 21:34:29 -0800 | [diff] [blame] | 43 | .BR kevent (2) |
| 44 | calls, or |
| 45 | .B NULL |
| 46 | if there is no such timeout. |
| 47 | If a |
| 48 | .RB non- NULL |
| 49 | value is returned, it must be used regardless of whether |
| 50 | .BR pcap_get_selectable_fd (3PCAP) |
Haibo Huang | 4ccd683 | 2020-04-23 18:03:48 -0700 | [diff] [blame] | 51 | returns |
Haibo Huang | ee759ce | 2021-01-05 21:34:29 -0800 | [diff] [blame] | 52 | .B \-1 |
| 53 | for any descriptor on which those calls are being done. |
| 54 | .BR pcap_get_required_select_timeout () |
| 55 | should be called for all |
| 56 | .BR pcap_t s |
| 57 | before a call to |
| 58 | .BR select (), |
| 59 | .BR poll (), |
| 60 | .BR epoll_wait (), |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 61 | or |
Haibo Huang | ee759ce | 2021-01-05 21:34:29 -0800 | [diff] [blame] | 62 | .BR kevent (), |
| 63 | and any timeouts used for those calls should be updated as appropriate |
| 64 | given the new value of the timeout. |
| 65 | .PP |
| 66 | For |
| 67 | .BR kevent (), |
| 68 | one |
| 69 | .B EVFILT_TIMER |
| 70 | filter per selectable descriptor can be used, rather than using the |
| 71 | timeout argument to |
| 72 | .BR kevent (); |
| 73 | if the |
| 74 | .B EVFILT_TIMER |
| 75 | event for a particular selectable descriptor signals an event, |
| 76 | .BR pcap_dispatch (3PCAP) |
| 77 | should be called for the corresponding |
| 78 | .BR pcap_t . |
| 79 | .PP |
| 80 | On Linux systems with |
| 81 | .BR timerfd_create (2), |
| 82 | one timer object created by |
| 83 | .BR timerfd_create () |
| 84 | per selectable descriptor can be used, rather than using the timeout |
| 85 | argument to |
| 86 | .BR epoll_wait (); |
| 87 | if the |
| 88 | timer object for a particular selectable descriptor signals an event, |
| 89 | .BR pcap_dispatch (3PCAP) |
| 90 | should be called for the corresponding |
| 91 | .BR pcap_t . |
| 92 | .PP |
| 93 | Otherwise, a timeout value no larger than |
| 94 | the smallest of all timeouts returned by |
| 95 | .BR \%pcap_get_required_select_timeout () |
| 96 | for devices from which packets will be captured and any other timeouts |
| 97 | to be used in the call should be used as the timeout for the call, and, |
| 98 | when the call returns, |
| 99 | .BR pcap_dispatch (3PCAP) |
| 100 | should be called for all |
| 101 | .BR pcap_t s |
| 102 | for which a |
| 103 | .RB non- NULL |
| 104 | timeout was returned, regardless of whether it's indicated as having |
| 105 | anything to read from it or not. |
| 106 | .PP |
| 107 | All devices with a |
| 108 | .RB non- NULL |
| 109 | timeout must be put in non-blocking mode with |
| 110 | .BR pcap_setnonblock (3PCAP). |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 111 | .PP |
| 112 | Note that a device on which a read can be done without blocking may, |
| 113 | on some platforms, not have any packets to read if the packet buffer |
| 114 | timeout has expired. A call to |
Haibo Huang | ee759ce | 2021-01-05 21:34:29 -0800 | [diff] [blame] | 115 | .BR pcap_dispatch () |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 116 | or |
Haibo Huang | ee759ce | 2021-01-05 21:34:29 -0800 | [diff] [blame] | 117 | .BR pcap_next_ex (3PCAP) |
| 118 | will return |
| 119 | .B 0 |
| 120 | in this case, but will not block. |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 121 | .PP |
Haibo Huang | ee759ce | 2021-01-05 21:34:29 -0800 | [diff] [blame] | 122 | .BR pcap_get_required_select_timeout () |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 123 | is not available on Windows. |
| 124 | .SH RETURN VALUE |
| 125 | A pointer to a |
| 126 | .B struct timeval |
| 127 | is returned if the timeout is required; otherwise |
| 128 | .B NULL |
| 129 | is returned. |
Haibo Huang | 4ccd683 | 2020-04-23 18:03:48 -0700 | [diff] [blame] | 130 | .SH BACKWARD COMPATIBILITY |
| 131 | This function became available in libpcap release 1.9.0. In previous |
| 132 | releases, |
Haibo Huang | ee759ce | 2021-01-05 21:34:29 -0800 | [diff] [blame] | 133 | .BR select (), |
| 134 | .BR poll (), |
| 135 | .BR epoll_wait (), |
Haibo Huang | 4ccd683 | 2020-04-23 18:03:48 -0700 | [diff] [blame] | 136 | and |
Haibo Huang | ee759ce | 2021-01-05 21:34:29 -0800 | [diff] [blame] | 137 | .BR kevent () |
Haibo Huang | 4ccd683 | 2020-04-23 18:03:48 -0700 | [diff] [blame] | 138 | cannot be used on any capture source for which |
Haibo Huang | ee759ce | 2021-01-05 21:34:29 -0800 | [diff] [blame] | 139 | .BR pcap_get_selectable_fd () |
| 140 | returns |
| 141 | .BR \-1 . |
| 142 | .PP |
| 143 | In libpcap release 1.10.0 and later, the timeout value can change from |
| 144 | call to call, so |
| 145 | .BR pcap_get_required_select_timeout () |
| 146 | must be called before each call to |
| 147 | .BR select (), |
| 148 | .BR poll (), |
| 149 | .BR epoll_wait (), |
| 150 | or |
| 151 | .BR kevent (), |
| 152 | and the new value must be used to calculate timeouts for the call. Code |
| 153 | that does that will also work with libpcap 1.9.x releases, so code |
| 154 | using |
| 155 | .BR pcap_get_required_select_timeout () |
| 156 | should be changed to call it for each call to |
| 157 | .BR select (), |
| 158 | .BR poll (), |
| 159 | .BR epoll_wait (), |
| 160 | or |
| 161 | .BR kevent () |
| 162 | even if the code must also work with libpcap 1.9.x. |
| 163 | .SH BACKWARD COMPATIBILITY |
| 164 | This function became available in libpcap release 1.9.0. In previous |
| 165 | releases, |
| 166 | .BR select (), |
| 167 | .BR poll (), |
| 168 | .BR epoll_wait (), |
| 169 | and |
| 170 | .BR kevent () |
| 171 | could not be used for devices that don't provide a selectable file |
| 172 | descriptor. |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 173 | .SH SEE ALSO |
Haibo Huang | ee759ce | 2021-01-05 21:34:29 -0800 | [diff] [blame] | 174 | .BR pcap (3PCAP), |
| 175 | .BR pcap_get_selectable_fd (3PCAP), |
| 176 | .BR select (2), |
| 177 | .BR poll (2), |
| 178 | .BR epoll_wait (2), |
| 179 | .BR kqueue (2) |