PCAP_BREAKLOOP(3PCAP)                                  PCAP_BREAKLOOP(3PCAP)

NAME         top

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

SYNOPSIS         top

       #include <pcap/pcap.h>

       void pcap_breakloop(pcap_t *);

DESCRIPTION         top

       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.

SEE ALSO         top

       pcap(3PCAP), pcap_loop(3PCAP), pcap_next_ex(3PCAP)

COLOPHON         top

       This page is part of the libpcap (packet capture library) project.
       Information about the project can be found at 
       ⟨⟩.  If you have a bug report for this manual
       page, see ⟨⟩.  This page was obtained
       from the project's upstream Git repository 
       ⟨⟩ on 2017-09-15.  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

                                8 March 2015           PCAP_BREAKLOOP(3PCAP)