PCAP_BREAKLOOP(3PCAP)

🌸 NAME 🌸

okay bestie, welcome to the PCAP_BREAKLOOP(3PCAP) manual page — aka the tea on pcap_breakloop 💅

• pcap_breakloop — force a pcap_dispatch() or pcap_loop() call to return.

---

✨ SYNOPSIS ✨

#include <pcap/pcap.h>

void pcap_breakloop(pcap_t *);

---

💖 DESCRIPTION 💖

okay so pcap_breakloop() sets a flag that will force pcap_dispatch(3PCAP) or pcap_loop(3PCAP) to return rather than looping. They will return the number of packets that have been processed so far, or PCAP_ERROR_BREAK if no packets have been processed so far. If the loop is currently blocked waiting for packets to arrive, pcap_breakloop() will also, on some platforms, wake up the thread that is blocked. In this version of libpcap, the only platforms on which a wakeup is caused by pcap_breakloop() are Linux and Windows, and the wakeup will only be caused when capturing on network interfaces; it will not be caused on other operating systems, and will not be caused on any OS when capturing on other types of devices. 🫶

This routine is safe to use inside a signal handler on UNIX or a console control handler on Windows, or in a thread other than the one in which the loop is running, as it merely sets a flag that is checked within the loop and, on some platforms, performs a signal-safe and thread-safe API call. No cap. ✨

The flag is checked in loops reading packets from the OS — a signal by itself will not necessarily terminate those loops — as well as in loops processing a set of packets returned by the OS. Note that if you are catching signals on UNIX systems that support restarting system calls after a signal, and calling pcap_breakloop() in the signal handler, you must specify, when catching those signals, that system calls should NOT be restarted by that signal. Otherwise, if the signal interrupted a call reading packets in a live capture, when your signal handler returns after calling pcap_breakloop(), the call will be restarted, and the loop will not terminate until more packets arrive and the call completes. 😭

Note also that, in a multi-threaded application, if one thread is blocked in pcap_dispatch(3PCAP), pcap_loop(3PCAP), pcap_next(3PCAP), or pcap_next_ex(3PCAP), a call to pcap_breakloop() in a different thread will only unblock that thread on the platforms and capture devices listed above. 🧵

If a non-zero packet buffer timeout is set on the pcap_t, and you are capturing on a network interface, the thread will be unblocked when the timeout expires. This is not guaranteed to happen unless at least one packet has arrived; the only platforms on which it happens are macOS, the BSDs, Solaris 11, AIX, Tru64 UNIX, and Windows. ⏰

If you want to ensure that the loop will eventually be unblocked on any other platforms, or unblocked when capturing on a device other than a network interface, you will need to use whatever mechanism the OS provides for breaking a thread out of blocking calls in order to unblock the thread, such as thread cancellation or thread signalling in systems that support POSIX threads. 🧚

Note that if pcap_breakloop() unblocks the thread capturing packets, and you are running on a platform that supports packet buffering, there may be packets in the buffer that arrived before pcap_breakloop() was called but that weren't yet provided to libpcap, those packets will not have been processed by pcap_dispatch() or pcap_loop(). If pcap_breakloop() was called in order to terminate the capture process, then, in order to process those packets, you would have to call pcap_dispatch() one time in order to process the last batch of packets. This may block until the packet buffer timeout expires, so a non-zero packet buffer timeout must be used. 🙈

Note that pcap_next() and pcap_next_ex() will, on some platforms, loop reading packets from the OS; that loop will not necessarily be terminated by a signal, so pcap_breakloop() should be used to terminate packet processing even if pcap_next() or pcap_next_ex() is being used. 👑

pcap_breakloop() does not guarantee that no further packets will be processed by pcap_dispatch() or pcap_loop() after it is called; at most one more packet might be processed. 💀

If PCAP_ERROR_BREAK is returned from pcap_dispatch() or pcap_loop(), the flag is cleared, so a subsequent call will resume reading packets. If a positive number is returned, the flag is not cleared, so a subsequent call will return PCAP_ERROR_BREAK and clear the flag. 🎀

---

🦋 BACKWARD COMPATIBILITY 🦋

This function became available in libpcap release 0.8.1.

In releases prior to libpcap 1.10.0, pcap_breakloop() will not wake up a blocked thread on any platform. periodt. 💅

---

🌈 SEE ALSO 🌈

• pcap(3PCAP)

---

okay that's the whole page, bestie 🫶 this one is dated 8 December 2022 and filed under PCAP_BREAKLOOP(3PCAP) — libpcap manual realness, slay 💖✨