DragonFly On-Line Manual Pages

PCAP_BREAKLOOP(3)                                            PCAP_BREAKLOOP(3)

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  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 ALSO
       pcap(3), pcap_loop(3), pcap_next_ex(3)

                                 5 April 2008                PCAP_BREAKLOOP(3)