PCAP_BREAKLOOP(3PCAP)PCAP_BREAKLOOP(3PCAP)NAMEpcap_breakloop - force a pcap_dispatch() or pcap_loop() call to return
SYNOPSIS
#include <pcap/pcap.h>
void pcap_breakloop(pcap_t *);
DESCRIPTIONpcap_breakloop() sets a flag that will force pcap_dispatch() or
pcap_loop() to return rather than looping; they will return the number
of packets that have been processed so far, or -2 if no packets have
been processed so far.
This routine is safe to use inside a signal handler on UNIX or a con‐
sole control handler on Windows, as it merely sets a flag that is
checked within the loop.
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 com‐
pletes.
Note also that, in a multi-threaded application, if one thread is
blocked in pcap_dispatch(), pcap_loop(), pcap_next(), or
pcap_next_ex(), a call to pcap_breakloop() in a different thread will
not unblock that thread; 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 in systems that support
POSIX threads.
Note that pcap_next() and pcap_next_ex() will, on some platforms, loop
reading packets from the OS; that loop will not necessarily be termi‐
nated 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 -2 is returned from pcap_dispatch() or pcap_loop(), the flag is
cleared, so a subsequent call will resume reading packets. If a posi‐
tive number is returned, the flag is not cleared, so a subsequent call
will return -2 and clear the flag.
SEE ALSOpcap(3PCAP), pcap_loop(3PCAP), pcap_next_ex(3PCAP)ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌────────────────────┬─────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├────────────────────┼─────────────────────────┤
│Availability │ system/library/libpcap │
├────────────────────┼─────────────────────────┤
│Interface Stability │ Uncommitted │
└────────────────────┴─────────────────────────┘
NOTES
Source for libpcap is available at http://opensolaris.org and at
http://www.tcpdump.org. Documentation is available at
file:///usr/share/man, and http://www.tcpdump.org.
5 April 2008 PCAP_BREAKLOOP(3PCAP)
