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(3PCAP) or pcap_loop(3PCAP) to
       return rather than looping; they  will  return  the  number  of  packets  that  have  been
       processed  so  far,  or PCAP_ERROR_BREAK if no packets have been processed so far.  If the
       loop is currently blocked waiting for packets to arrive, pcap_breakloop()  will  also,  on
       some  platforms, wake up the thread that is blocked.  In this version of libpcap, the only
       platforms on which a wakeup is caused by pcap_breakloop() are Linux and Windows,  and  the
       wakeup  will only be caused when capturing on network interfaces; it will not be caused on
       other operating systems, and will not be caused on any OS when capturing on other types of
       devices.

       This  routine  is safe to use inside a signal handler on UNIX or a console control handler
       on Windows, or in a thread other than the one in which the loop is running, as  it  merely
       sets a flag that is checked within the loop and, on some platforms, performs a signal-safe
       and thread-safe API call.

       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(3PCAP),  or  pcap_next_ex(3PCAP),  a  call  to
       pcap_breakloop() in a different thread will only unblock that thread on the platforms  and
       capture devices listed above.

       If  a  non-zero  packet  buffer  timeout  is set on the pcap_t, and you are capturing on a
       network interface, the thread will be unblocked with the timeout  expires.   This  is  not
       guaranteed  to  happen unless at least one packet has arrived; the only platforms on which
       it happens are macOS, the BSDs, Solaris 11, AIX, Tru64 UNIX, and Windows.

       If you want to ensure that the loop will eventually be unblocked on any  other  platforms,
       or  unblocked  when capturing on a device other than a network interface, 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 or thread signalling in systems
       that support POSIX threads.

       Note that if pcap_breakloop() unblocks the thread capturing packets, and you  are  running
       on  a  platform  that  supports  packet buffering, there may be packets in the buffer that
       arrived before pcap_breakloop() were called but that  weren't  yet  provided  to  libpcap,
       those  packets  will  not  have  been  processed  by  pcap_dispatch()  or pcap_loop().  If
       pcap_breakloop() was called in order to terminate the capture process, then, in  order  to
       process those packets, you would have to call pcap_dispatch() one time in order to process
       the last batch of packets.  This may block until the packet buffer timeout expires,  so  a
       non-zero packet buffer timeout must be used.

       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 PCAP_ERROR_BREAK 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 PCAP_ERROR_BREAK and clear the flag.

BACKWARD COMPATIBILITY

       This function became available in libpcap release 0.8.1.

       In releases prior to libpcap 1.10.0, pcap_breakloop() will not wake up a blocked thread on
       any platform.

SEE ALSO

       pcap(3PCAP)

                                         8 December 2022                    PCAP_BREAKLOOP(3PCAP)