Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PCAP_BREAKLOOP(3)	   Library Functions Manual	     PCAP_BREAKLOOP(3)

       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(3) or
       pcap_loop(3) 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.

       This routine is safe to use inside a signal handler on UNIX or  a  con-
       sole  control  handler  on  Windows,  as	 it merely sets	a flag that is
       checked within the loop.

       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 re-
       turns after calling pcap_breakloop(), the call will be  restarted,  and
       the loop	will not terminate until more packets arrive and the call com-

       Note also that, in a  multi-threaded  application,  if  one  thread  is
       blocked	  in	pcap_dispatch(),    pcap_loop(),    pcap_next(3),   or
       pcap_next_ex(3),	a call to pcap_breakloop() in a	different thread  will
       not  unblock  that thread.  You will need to use	whatever mechanism the
       OS provides for breaking	a thread out of	blocking calls in order	to un-
       block  the  thread, such	as thread cancellation or thread signalling in
       systems that support POSIX threads, or  SetEvent()  on  the  result  of
       pcap_getevent()	on a pcap_t on which the thread	is blocked on Windows.
       Asynchronous procedure calls will not work  on  Windows,	 as  a	thread
       blocked on a pcap_t will	not be in an alertable state.

       Note  that pcap_next() and pcap_next_ex() will, on some platforms, loop
       reading packets from the	OS; that loop will not necessarily  be	termi-
       nated  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	subse-
       quent call will return PCAP_ERROR_BREAK and clear the flag.


				 25 July 2018		     PCAP_BREAKLOOP(3)


Want to link to this manual page? Use this URL:

home | help