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)

                                           5 April 2008                     PCAP_BREAKLOOP(3PCAP)