PCAP_GET_REQUIRED_SELECT_TIMEOUT(3PCAP)

💖 PCAP_GET_REQUIRED_SELECT_TIMEOUT 💖

okay bestie, welcome to the 3PCAP section of the libpcap manual — this one is called pcap_get_required_select_timeout and it's lowkey the save of the day when you're doing select() on a live capture. sit down, hydrate, let's go ✨

---

🌸 NAME 🌸

pcap_get_required_select_timeout — get a timeout to be used when doing select() for a live capture 🫶

---

🎀 SYNOPSIS 🎀

#include <pcap/pcap.h>

const struct timeval *pcap_get_required_select_timeout(pcap_t *p);

that's it, that's the whole incantation, no cap 💅

---

🦋 DESCRIPTION 🦋

so. pcap_get_required_select_timeout() returns — on UNIX — a pointer to a struct timeval holding a value that must be used as the minimum timeout in select(2), poll(2), epoll_wait(2), and kevent(2) calls. or it returns NULL if there is no such timeout. that's the whole vibe check: pointer = you have a required timeout, NULL = you don't 💀

and listen — if a non-NULL value comes back, you must use it regardless of whether pcap_get_selectable_fd(3PCAP) returns -1 for any descriptor on which those calls are being done. like, even if the fd situation looks cursed, the timeout still applies. periodt 👑

the way this works: pcap_get_required_select_timeout() should be called for all pcap_ts before a call to select(), poll(), epoll_wait(), or kevent(), and any timeouts used for those calls should be updated as appropriate given the new value of the timeout. fresh value, fresh timeout, every single time 🧚

---

💜 the fancy alternatives, iykyk 💜

for kevent(), you can use one EVFILT_TIMER filter per selectable descriptor rather than using the timeout argument to kevent(). if the EVFILT_TIMER event for a particular selectable descriptor signals an event, pcap_dispatch(3PCAP) should be called for the corresponding pcap_t. cute, right? 🌈

on Linux systems with timerfd_create(2), you can use one timer object created by timerfd_create() per selectable descriptor rather than using the timeout argument to epoll_wait(). if the timer object for a particular selectable descriptor signals an event, pcap_dispatch(3PCAP) should be called for the corresponding pcap_t. Linux girlies stay winning 🐧✨

---

🌸 otherwise (the classic route) 🌸

otherwise, a timeout value no larger than the smallest of all timeouts returned by pcap_get_required_select_timeout() for devices from which packets will be captured, and any other timeouts to be used in the call, should be used as the timeout for the call. smallest wins, it's giving "the group can only move as fast as the slowest bestie" 🫶

and when the call returns, pcap_dispatch(3PCAP) should be called for all pcap_ts for which a non-NULL timeout was returned — regardless of whether it's indicated as having anything to read from it or not. yes, even the quiet ones. even the ones ghosting you 🙈

---

⚠️ important caveat bestie, do not skip this one: all devices with a non-NULL timeout must be put in non-blocking mode with pcap_setnonblock(3PCAP). no exceptions, it's the law 💅

also, a lil note: 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 pcap_dispatch() or pcap_next_ex(3PCAP) will return 0 in this case, but will not block. so if you get a 0, don't panic — it's not an error, it's just the vibe 😭

and the sad one: pcap_get_required_select_timeout() is not available on Windows. windows besties we love you but this one's not for you 💔

---

⭐ RETURN VALUE ⭐

• a pointer to a struct timeval is returned if the timeout is required
• otherwise NULL is returned

short, sweet, iconic 🎀

---

🔥 BACKWARD COMPATIBILITY 🔥

this function became available in libpcap release 1.9.0. in previous releases, select(), poll(), epoll_wait(), and kevent() could not be used for devices that don't provide a selectable file descriptor — in other words, on any capture source for which pcap_get_selectable_fd() returns -1. rough out here for the ancestors 😔

in libpcap release 1.10.0 and later, the timeout value can change from call to call, so pcap_get_required_select_timeout() must be called before each call to select(), poll(), epoll_wait(), or kevent(), and the new value must be used to calculate timeouts for the call. no caching, no "I remembered it from last time", none of that 💀

and here's the slay part: code that does that will also work with libpcap 1.9.x releases. so code using pcap_get_required_select_timeout() should be changed to call it for each call to select(), poll(), epoll_wait(), or kevent() even if the code must also work with libpcap 1.9.x. one pattern, all the versions, we love a future-proof queen 👑

---

🌈 SEE ALSO 🌈

• pcap(3PCAP)
• pcap_get_selectable_fd(3PCAP)
• select(2)
• poll(2)
• epoll_wait(2)
• kqueue(2)

go read them, they're all connected, it's a whole ecosystem bestie 🦋

---

mwah 💋 that's the page! this one's from the 3PCAP manual, dated 29 Janua — yeah our copy got clipped mid-word, the rest of the date is out there living its life 😭 — signing off, go put your devices in non-blocking mode, love u, bye 🎀✨💖