pcap_breakloop(3pcap)

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()  or
15       pcap_loop() to return rather than looping; they will return the  number
16       of  packets  that  have been processed so far, or -2 if no packets have
17       been processed so far.
18
19       This routine is safe to use inside a signal handler on UNIX or  a  con‐
20       sole  control  handler  on  Windows,  as  it merely sets a flag that is
21       checked within the loop.
22
23       The flag is checked in loops reading packets from the OS - a signal  by
24       itself will not necessarily terminate those loops - as well as in loops
25       processing a set of packets returned by the OS.  Note that if  you  are
26       catching  signals  on UNIX systems that support restarting system calls
27       after a signal, and calling pcap_breakloop() in the signal handler, you
28       must specify, when catching those signals, that system calls should NOT
29       be restarted by that signal.  Otherwise, if the  signal  interrupted  a
30       call  reading  packets  in  a  live  capture,  when your signal handler
31       returns after calling pcap_breakloop(), the call will be restarted, and
32       the loop will not terminate until more packets arrive and the call com‐
33       pletes.
34
35       Note also that, in a  multi-threaded  application,  if  one  thread  is
36       blocked    in    pcap_dispatch(),    pcap_loop(),    pcap_next(),    or
37       pcap_next_ex(), a call to pcap_breakloop() in a different  thread  will
38       not unblock that thread; you will need to use whatever mechanism the OS
39       provides for breaking a thread  out  of  blocking  calls  in  order  to
40       unblock the thread, such as thread cancellation in systems that support
41       POSIX threads.
42
43       Note that pcap_next() and pcap_next_ex() will, on some platforms,  loop
44       reading  packets  from the OS; that loop will not necessarily be termi‐
45       nated by a signal, so pcap_breakloop()  should  be  used  to  terminate
46       packet processing even if pcap_next() or pcap_next_ex() is being used.
47
48       pcap_breakloop()  does  not  guarantee  that no further packets will be
49       processed by pcap_dispatch() or pcap_loop() after it is called; at most
50       one more packet might be processed.
51
52       If  -2  is  returned  from  pcap_dispatch() or pcap_loop(), the flag is
53       cleared, so a subsequent call will resume reading packets.  If a  posi‐
54       tive  number is returned, the flag is not cleared, so a subsequent call
55       will return -2 and clear the flag.
56

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO