PCAP_BREAKLOOP(3PCAP) PCAP_BREAKLOOP(3PCAP)

NAME

pcap_breakloop - force a pcap_dispatch() or pcap_loop() call to
return

SYNOPSIS

#include <pcap/pcap.h>

void pcap_breakloop(pcap_t *);

DESCRIPTION

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.

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(), pcap_loop(), 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 with
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() were 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.

SEE ALSO

pcap(3PCAP)

8 December 2022 PCAP_BREAKLOOP(3PCAP)