|
NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | COLOPHON |
PCAP_BREAKLOOP(3PCAP) PCAP_BREAKLOOP(3PCAP)
pcap_breakloop - force a pcap_dispatch() or pcap_loop() call to
return
#include <pcap/pcap.h>
void pcap_breakloop(pcap_t *);
pcap_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
console 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 completes.
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
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 -2 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 -2 and clear the flag.
pcap(3PCAP), pcap_loop(3PCAP), pcap_next_ex(3PCAP)
This page is part of the libpcap (packet capture library) project.
Information about the project can be found at
⟨http://www.tcpdump.org/⟩. If you have a bug report for this manual
page, see ⟨http://www.tcpdump.org/#patches⟩. This page was obtained
from the project's upstream Git repository
⟨https://github.com/the-tcpdump-group/libpcap.git⟩ on 2017-07-05. If
you discover any rendering problems in this HTML version of the page,
or you believe there is a better or more up-to-date source for the
page, or you have corrections or improvements to the information in
this COLOPHON (which is not part of the original manual page), send a
mail to man-pages@man7.org
8 March 2015 PCAP_BREAKLOOP(3PCAP)