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
39       OS provides for breaking a thread out of blocking  calls  in  order  to
40       unblock the thread, such as thread cancellation or thread signalling in
41       systems that support POSIX threads, or  SetEvent()  on  the  result  of
42       pcap_getevent()  on a pcap_t on which the thread is blocked on Windows.
43       Asynchronous procedure calls will not work  on  Windows,  as  a  thread
44       blocked on a pcap_t will not be in an alertable state.
45
46       Note  that pcap_next() and pcap_next_ex() will, on some platforms, loop
47       reading packets from the OS; that loop will not necessarily  be  termi‐
48       nated  by  a  signal,  so  pcap_breakloop() should be used to terminate
49       packet processing even if pcap_next() or pcap_next_ex() is being used.
50
51       pcap_breakloop() does not guarantee that no  further  packets  will  be
52       processed by pcap_dispatch() or pcap_loop() after it is called; at most
53       one more packet might be processed.
54
55       If -2 is returned from pcap_dispatch()  or  pcap_loop(),  the  flag  is
56       cleared,  so a subsequent call will resume reading packets.  If a posi‐
57       tive number is returned, the flag is not cleared, so a subsequent  call
58       will return -2 and clear the flag.
59

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO