PCAP_SETNONBLOCK(3)

💅 pcap_setnonblock / pcap_getnonblock 💅

okay bestie, this is the PCAP_SETNONBLOCK(3) page from the Library Functions Manual, and it’s literally all about flipping non-blocking mode on and off for a capture device. no cap, it’s giving very niche but very useful. 🦋

---

✨ NAME ✨

pcap_setnonblock, pcap_getnonblock — set or get the state of non-blocking mode on a capture device 💖

---

🌸 SYNOPSIS 🌸

#include <pcap/pcap.h>

char errbuf[PCAP_ERRBUF_SIZE];

int pcap_setnonblock(pcap_t *p, int nonblock, char *errbuf);
int pcap_getnonblock(pcap_t *p, char *errbuf);

---

🎀 DESCRIPTION 🎀

pcap_setnonblock() puts a capture handle into “non-blocking” mode, or takes it out of “non-blocking” mode, depending on whether the nonblock argument is non-zero or zero. It has no effect on “savefiles”. 🫶

errbuf is a buffer large enough to hold at least PCAP_ERRBUF_SIZE chars. yes, bestie, make sure it’s big enough — we’re not trying to be messy. 💅

In “non-blocking” mode, an attempt to read from the capture descriptor with pcap_dispatch(3) and pcap_next_ex(3) will, if no packets are currently available to be read, return 0 immediately rather than blocking waiting for packets to arrive. ✨

heads up: pcap_loop(3) will loop forever, consuming CPU time when no packets are currently available; pcap_dispatch() should be used instead. not it spinning like a fidget spinner 😭

pcap_next(3) will return NULL if there are no packets currently available to read; this is indistinguishable from an error, so pcap_next_ex() should be used instead. fr fr, don’t get caught out by that one. 💀

When first activated with pcap_activate(3) or opened with pcap_open_live(3), a capture handle is not in “non-blocking mode”; a call to pcap_setnonblock() is required in order to put it into “non-blocking” mode. so yeah, it starts off blocking — you gotta do the little mode switch yourself. 🦋

---

👑 RETURN VALUE 👑

pcap_setnonblock() returns 0 on success, PCAP_ERROR_NOT_ACTIVATED if called on a capture handle that has been created but not activated, and PCAP_ERROR for other errors. 💖

pcap_getnonblock() returns the current “non-blocking” state of the capture descriptor on success; it always returns 0 on “savefiles”. It returns PCAP_ERROR_NOT_ACTIVATED if called on a capture handle that has been created but not activated, and PCAP_ERROR for other errors. 🌈

If PCAP_ERROR is returned, errbuf is filled in with an appropriate error message. so check the errbuf, bestie, it’s literally there to help. 🫶

---

🔥 SEE ALSO 🔥

• pcap(3)
• pcap_next_ex(3)
• pcap_geterr(3)

---

xoxo, your fav manpage — from the Library Functions Manual, dated 30 November 2023 💖🎀✨