PCAP_SETNONBLOCK(3PCAP)

✨ PCAP_SETNONBLOCK ✨

okay bestie so this is a page from the 3PCAP manual and it's literally about flipping your capture handle's non-blocking switch on and off 💅 like a light switch but for packets, iykyk

🌸 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 💖

so pcap_setnonblock() is the main character here 👑 — it puts a capture handle into "non-blocking" mode, or takes it out of "non-blocking" mode, and honestly? it's all decided by whether the nonblock argument is non-zero or zero. non-zero = slay, we're non-blocking now. zero = okay we're back to blocking. periodt.

one thing though, bestie — it has no effect on "savefiles" 🫶 like, none. savefiles are not part of this conversation.

errbuf is a buffer large enough to hold at least PCAP_ERRBUF_SIZE chars. that's the whole vibe check on errbuf, ngl.

---

🌈 what non-blocking mode actually means 🌈

in "non-blocking" mode, if you try to read from the capture descriptor with pcap_dispatch(3PCAP) and pcap_next_ex(3PCAP) and there's no packets currently available to be read, it will return 0 immediately rather than blocking and waiting around for packets to arrive. it's giving no patience energy ✨ and honestly? iconic.

but like — the warnings, because there are warnings 🫶:

• pcap_loop(3PCAP) will loop forever, consuming CPU time when no packets are currently available. it just sits there. spinning. hot mess behavior fr fr 😭 so you should use pcap_dispatch() instead.
• pcap_next(3PCAP) will return NULL if there are no packets currently available to read. and that? that is indistinguishable from an error 💀 so please, for the love of everything, use pcap_next_ex() instead.

bestie. read those two again. pcap_loop() = CPU go brrr for nothing, and pcap_next() = can't tell the difference between "no packets" and "something went wrong." use the _ex versions, please, i'm begging 🙏

---

🧚 when you're non-blocking and when you're not 🧚

when a capture handle is first activated with pcap_activate(3PCAP) or opened with pcap_open_live(3PCAP), it is not in "non-blocking mode". nope! default is blocking, bestie. you need to actually call pcap_setnonblock() in order to put it into "non-blocking" mode. it doesn't just… happen. you have to want it 💅

---

🔥 RETURN VALUE 🔥

okay so here are the numbers, keep them in your notes app 📝

pcap_setnonblock():

• returns 0 on success ⭐
• returns PCAP_ERROR_NOT_ACTIVATED if it's called on a capture handle that has been created but not activated 🚫
• returns 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" (yes, always — savefiles stay unbothered) 🫶
• returns PCAP_ERROR_NOT_ACTIVATED if it's called on a capture handle that has been created but not activated 🚫
• returns PCAP_ERROR for other errors 💀

and if PCAP_ERROR gets returned, errbuf is filled in with an appropriate error message. so like, check errbuf. it's there for a reason, babe 🎀

fr fr: a handle that's created but not activated is a whole separate situation from a general error — that's why PCAP_ERROR_NOT_ACTIVATED exists as its own thing. don't lump them together 🙈

---

👑 SEE ALSO 👑

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

---

that's the whole page, bestie — you ate that 🍓

with love from the 3PCAP manual fam, dated 30 November 2023 💜 mwah 💋