bionic (3) pcap_breakloop.3pcap.gz

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()  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

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

                                                  8 March 2015                             PCAP_BREAKLOOP(3PCAP)