PCAP_OPEN_LIVE(3PCAP)

💖 PCAP_OPEN_LIVE 💖

okay so bestie, you're about to meet pcap_open_live — she's from the 3PCAP manual family (libpcap's finest, fr fr) and she's literally the main character of "open a device for capturing" ✨

🌸 SYNOPSIS 🌸

like, here's the exact spell you gotta cast, no cap:

#include <pcap/pcap.h>

char errbuf[PCAP_ERRBUF_SIZE];

pcap_t *pcap_open_live(const char *device, int snaplen,
    int promisc, int to_ms, char *errbuf);

ok but notice the char errbuf[PCAP_ERRBUF_SIZE]; sitting up there all independent — that's not a typo, that's just her vibe 🎀

🦋 DESCRIPTION 🦋

So pcap_open_live() is the function you call to get yourself a packet capture handle so you can go look at packets on the network. She's giving gatekeeper-to-the-packets energy and honestly? obsessed. 👑

device is a string that tells her which network device to open. And here's the slay: on all supported Linux systems, plus recent versions of macOS and Solaris, you can pass "any" or NULL as the device argument and she'll capture packets from all network interfaces at once. Iconic behavior honestly. 🫶

but bestie, hear me — NULL is not the same thing as "all available capture devices" the way pcap_findalldevs(3PCAP) sees them. That list can also include D-Bus, USB, etc. Different list, different vibe. Don't conflate them or you will be confused and sad 😭

snaplen is the snapshot length she sets on the handle. If you don't want your packet data truncated at the end, a value of 262144 should be sufficient for most devices — but plot twist: D-Bus devices require a value of 128MB (128*1024*1024). yes really, that's not a typo, D-Bus is just Like That 💀

promisc decides whether the interface gets put into promiscuous mode. If promisc is non-zero, promiscuous mode will be set. Otherwise it will not be set. Simple as that, no notes. ✨

to_ms is the packet buffer timeout — give her a non-negative value, expressed in milliseconds. (For the full explanation of what the packet buffer timeout even means, go read pcap(3PCAP) — she explains it way better than I could rn.)

errbuf is a buffer large enough to hold at least PCAP_ERRBUF_SIZE chars. Make it big enough, please, she needs the room 🥺

⭐ RETURN VALUE ⭐

• On success, pcap_open_live() returns a pcap_t * — yay, handle acquired, go capture things 🔥
• On failure, she returns NULL. And when that happens, errbuf gets filled in with an appropriate error message. So check it, bestie, don't just ignore her 💅

🚨 IMPORTANT PLOT POINT 🚨 errbuf may also be set to warning text when pcap_open_live() succeeds. Not just on failure! Sneaky. So to actually detect that case, the caller should store a zero-length string in errbuf before calling pcap_open_live(), and then display the warning to the user if errbuf is no longer a zero-length string. That's the whole trick and it's lowkey genius ngl.

🌈 SEE ALSO 🌈

• pcap_create(3PCAP)
• pcap_activate(3PCAP)

and that's the whole page, bestie!! this one's dated 4 March 2024, straight from the PCAP_OPEN_LIVE(3PCAP) manual page in the libpcap docs — go forth and capture responsibly, mwah 💋🧚‍♀️🍓