1PCAP_BREAKLOOP(3PCAP) PCAP_BREAKLOOP(3PCAP)
2
6 pcap_breakloop - force a pcap_dispatch() or pcap_loop() call to return
7
9 #include <pcap/pcap.h>
10 void pcap_breakloop(pcap_t *);
12
14 pcap_breakloop() sets a flag that will force pcap_dispatch(3PCAP) or
15 pcap_loop(3PCAP) to return rather than looping; they will return the
16 number of packets that have been processed so far, or PCAP_ERROR_BREAK
17 if no packets have been processed so far. If the loop is currently
18 blocked waiting for packets to arrive, pcap_breakloop() will also, on
19 some platforms, wake up the thread that is blocked. In this version of
20 libpcap, the only platforms on which a wakeup is caused by pcap_break‐
21 loop() are Linux and Windows, and the wakeup will only be caused when
22 capturing on network interfaces; it will not be caused on other operat‐
23 ing systems, and will not be caused on any OS when capturing on other
24 types of devices.
25 This routine is safe to use inside a signal handler on UNIX or a con‐
27 sole control handler on Windows, or in a thread other than the one in
28 which the loop is running, as it merely sets a flag that is checked
29 within the loop and, on some platforms, performs a signal-safe and
30 thread-safe API call.
31 The flag is checked in loops reading packets from the OS - a signal by
33 itself will not necessarily terminate those loops - as well as in loops
34 processing a set of packets returned by the OS. Note that if you are
35 catching signals on UNIX systems that support restarting system calls
36 after a signal, and calling pcap_breakloop() in the signal handler, you
37 must specify, when catching those signals, that system calls should NOT
38 be restarted by that signal. Otherwise, if the signal interrupted a
39 call reading packets in a live capture, when your signal handler re‐
40 turns after calling pcap_breakloop(), the call will be restarted, and
41 the loop will not terminate until more packets arrive and the call com‐
42 pletes.
43 Note also that, in a multi-threaded application, if one thread is
45 blocked in pcap_dispatch(), pcap_loop(), pcap_next(3PCAP), or
46 pcap_next_ex(3PCAP), a call to pcap_breakloop() in a different thread
47 will only unblock that thread on the platforms and capture devices
48 listed above.
49 If a non-zero packet buffer timeout is set on the pcap_t, and you are
51 capturing on a network interface, the thread will be unblocked with the
52 timeout expires. This is not guaranteed to happen unless at least one
53 packet has arrived; the only platforms on which it happens are macOS,
54 the BSDs, Solaris 11, AIX, Tru64 UNIX, and Windows.
55 If you want to ensure that the loop will eventually be unblocked on any
57 other platforms, or unblocked when capturing on a device other than a
58 network interface, you will need to use whatever mechanism the OS pro‐
59 vides for breaking a thread out of blocking calls in order to unblock
60 the thread, such as thread cancellation or thread signalling in systems
61 that support POSIX threads.
62 Note that if pcap_breakloop() unblocks the thread capturing packets,
64 and you are running on a platform that supports packet buffering, there
65 may be packets in the buffer that arrived before pcap_breakloop() were
66 called but that weren't yet provided to libpcap, those packets will not
67 have been processed by pcap_dispatch() or pcap_loop(). If pcap_break‐
68 loop() was called in order to terminate the capture process, then, in
69 order to process those packets, you would have to call pcap_dispatch()
70 one time in order to process the last batch of packets. This may block
71 until the packet buffer timeout expires, so a non-zero packet buffer
72 timeout must be used.
73 Note that pcap_next() and pcap_next_ex() will, on some platforms, loop
75 reading packets from the OS; that loop will not necessarily be termi‐
76 nated by a signal, so pcap_breakloop() should be used to terminate
77 packet processing even if pcap_next() or pcap_next_ex() is being used.
78 pcap_breakloop() does not guarantee that no further packets will be
80 processed by pcap_dispatch() or pcap_loop() after it is called; at most
81 one more packet might be processed.
82 If PCAP_ERROR_BREAK is returned from pcap_dispatch() or pcap_loop(),
84 the flag is cleared, so a subsequent call will resume reading packets.
85 If a positive number is returned, the flag is not cleared, so a subse‐
86 quent call will return PCAP_ERROR_BREAK and clear the flag.
87
89 This function became available in libpcap release 0.8.1.
90 In releases prior to libpcap 1.10.0, pcap_breakloop() will not wake up
92 a blocked thread on any platform.
93
95 pcap(3PCAP)
96 8 December 2022 PCAP_BREAKLOOP(3PCAP)