|
HTML rendering created 2024-06-26 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | BACKWARD COMPATIBILITY | SEE ALSO | COLOPHON |
|
|
|
PCAP_BREAKLOOP(3PCAP) PCAP_BREAKLOOP(3PCAP)
pcap_breakloop - force a pcap_dispatch() or pcap_loop() call to
return
#include <pcap/pcap.h>
void pcap_breakloop(pcap_t *);
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, 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.
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.
pcap(3PCAP)
This page is part of the libpcap (packet capture library)
project. Information about the project can be found at
⟨http://www.tcpdump.org/⟩. If you have a bug report for this
manual page, see ⟨http://www.tcpdump.org/#patches⟩. This page
was obtained from the project's upstream Git repository
⟨https://github.com/the-tcpdump-group/libpcap.git⟩ on 2024-06-14.
(At that time, the date of the most recent commit that was found
in the repository was 2024-06-04.) If you discover any rendering
problems in this HTML version of the page, or you believe there
is a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
[email protected]
27 January 2024 PCAP_BREAKLOOP(3PCAP)
|
HTML rendering created 2024-06-26 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|