pcap_breakloop(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
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(3) or
       pcap_loop(3) 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_break-
       loop() are Linux and Windows, and the wakeup will only be  caused  when
       capturing on network interfaces; it will not be caused on other operat-
       ing 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 con-
       sole 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 com-
       pletes.

       Note  also  that,  in  a  multi-threaded  application, if one thread is
       blocked   in    pcap_dispatch(),    pcap_loop(),    pcap_next(3),    or
       pcap_next_ex(3),  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 pro-
       vides 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_break-
       loop()  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  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  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 subse-
       quent 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(3)



                                8 December 2022              PCAP_BREAKLOOP(3)