1PCAP_BREAKLOOP(3PCAP)                                    PCAP_BREAKLOOP(3PCAP)
2
3
4

NAME

6       pcap_breakloop - force a pcap_dispatch() or pcap_loop() call to return
7

SYNOPSIS

9       #include <pcap/pcap.h>
10
11       void pcap_breakloop(pcap_t *);
12

DESCRIPTION

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
26       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
32       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
44       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
50       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
56       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
63       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
74       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
79       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
83       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

BACKWARD COMPATIBILITY

89       This function became available in libpcap release 0.8.1.
90
91       In  releases prior to libpcap 1.10.0, pcap_breakloop() will not wake up
92       a blocked thread on any platform.
93

SEE ALSO

95       pcap(3PCAP)
96
97
98
99                                8 December 2022          PCAP_BREAKLOOP(3PCAP)
Impressum