FreeBSD Manual Pages
PCAP_BREAKLOOP(3) Library Functions Manual 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. 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 re- turns 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 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 un- block the thread, such as thread cancellation or thread signalling in systems that support POSIX threads, or SetEvent() on the result of pcap_getevent() on a pcap_t on which the thread is blocked on Windows. Asynchronous procedure calls will not work on Windows, as a thread blocked on a pcap_t will not be in an alertable state. 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. SEE ALSO pcap(3) 25 July 2018 PCAP_BREAKLOOP(3)
NAME | SYNOPSIS | DESCRIPTION | SEE ALSO
Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pcap_breakloop&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>