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

FreeBSD Manual Pages

  
 
  

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

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

SYNOPSIS
       #include	<pcap/pcap.h>

       void pcap_breakloop(pcap_t *);

DESCRIPTION
       pcap_breakloop()	 sets  a  flag	that  will  force  pcap_dispatch()  or
       pcap_loop() to return rather than looping; they will return the	number
       of  packets  that  have been processed so far, or -2 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-
       pletes.

       Note also that, in a  multi-threaded  application,  if  one  thread  is
       blocked	  in	pcap_dispatch(),    pcap_loop(),    pcap_next(),    or
       pcap_next_ex(), 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 -2 is	returned from pcap_dispatch()  or  pcap_loop(),	 the  flag  is
       cleared,	 so a subsequent call will resume reading packets.  If a posi-
       tive number is returned,	the flag is not	cleared, so a subsequent  call
       will return -2 and clear	the flag.

SEE ALSO
       pcap(3),	pcap_loop(3), pcap_next_ex(3)

				 8 March 2015		     PCAP_BREAKLOOP(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pcap_breakloop&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help