PCAP_ACTIVATE(3)

✨ NAME ✨

pcap_activate — activate a capture handle 🎬

ok so real quick, bestie: this whole page lives in the Library Functions Manual, section 3. that's the vibe. let's get into it 💅

---

🌸 SYNOPSIS 🌸

#include <pcap/pcap.h>

int pcap_activate(pcap_t *p);

---

🦋 DESCRIPTION 🦋

So like. pcap_activate() is the function you call to activate a packet capture handle — as in, make it actually go look at packets on the network. 👀✨

And here's the key thing: the options you already set on the handle? yeah, those are in effect when it activates. everything you queued up beforehand, that's what you're getting. no take-backs, no surprises. periodt. 🎀

---

🔥 RETURN VALUE 🔥

ok this is the part where you gotta pay attention, because the return value has three whole moods:

• 0 → slay, success, no warnings, immaculate. ✨
• a non-zero positive value → success with warnings. it worked, but it's got notes. 💀
• a negative value → error. not it. 😭

And a non-zero return value tells you which warning or error condition happened, so you can actually figure out what's going on.

🎀 the possible warning values (positive, remember!)

• PCAP_WARNING_PROMISC_NOTSUP — you asked for promiscuous mode, but the capture source doesn't support promiscuous mode. it said no. 🙈
• PCAP_WARNING_TSTAMP_TYPE_NOTSUP — the time stamp type you specified in a previous pcap_set_tstamp_type(3) call isn't supported by the capture source (and the time stamp type is left as the default).
• PCAP_WARNING — some other warning condition occurred. in that case you can call pcap_geterr(3) or pcap_perror(3) with p as an argument to fetch or display a message describing the warning condition. 🫶

💀 the possible error values (negative, oof)

• PCAP_ERROR_ACTIVATED — the handle has already been activated. girl it's already on. 😭
• PCAP_ERROR_NO_SUCH_DEVICE — the capture source specified when the handle was created doesn't exist. ghosted. 👻
• PCAP_ERROR_PERM_DENIED — the process doesn't have permission to open the capture source.
• PCAP_ERROR_PROMISC_PERM_DENIED — the process has permission to open the capture source, but doesn't have permission to put it into promiscuous mode. so close yet so far. 💔
• PCAP_ERROR_RFMON_NOTSUP — monitor mode was specified but the capture source doesn't support monitor mode.
• PCAP_ERROR_IFACE_NOT_UP — the capture source device is not up. get it together bestie. 🧚
• PCAP_ERROR_CAPTURE_NOTSUP — packet capture is not supported on the capture source.
• PCAP_ERROR — another error occurred. pcap_geterr() or pcap_perror() may be called with p as an argument to fetch or display a message describing the error.

💡 extra detail drop: if PCAP_WARNING_PROMISC_NOTSUP, PCAP_ERROR_NO_SUCH_DEVICE, PCAP_ERROR_PERM_DENIED, or PCAP_ERROR_CAPTURE_NOTSUP is returned, pcap_geterr() or pcap_perror() may be called with p as an argument to fetch or display a message giving additional details about the problem — which might be useful for debugging the problem if it's unexpected. 🔍

---

🌈 future-proofing, iykyk

Additional warning and error codes may be added in the future. so your program should check for positive, negative, and zero return codes, and treat all positive return codes as warnings and all negative return codes as errors. don't hardcode the specific ones, that's not the move. 👑

Also: pcap_statustostr(3) can be called, with a warning or error code as an argument, to fetch a message describing the warning or error code. very handy, 10/10. ⭐

---

⚠️ important cleanup note

If pcap_activate() fails, the pcap_t * is not closed and freed. you gotta close it yourself using pcap_close(3). don't leave it hanging, that's rude and also a leak. 💅

---

🫶 SEE ALSO 🫶

• pcap(3)

---

and that's the whole page, bestie — go forth and activate responsibly 🦋💖

signing off from PCAP_ACTIVATE(3) in the Library Functions Manual, dated 3 June 2024 ✨🎀