unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (NetBSD-6.1.5)
Page:
Section:
Apropos / Subsearch:
optional field

PCAP_BREAKLOOP(3)          Library Functions Manual          PCAP_BREAKLOOP(3)



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

SYNOPSIS
       #include <&lt;pcap/pcap.h>&gt;

       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
       console 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
       returns after calling pcap_breakloop(), the call will be restarted, and
       the loop will not terminate until more packets arrive and the call
       completes.

       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
       unblock the thread, such as thread cancellation in systems that support
       POSIX threads.

       Note that pcap_next() and pcap_next_ex() will, on some platforms, loop
       reading packets from the OS; that loop will not necessarily be
       terminated 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
       positive 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)



                                 5 April 2008                PCAP_BREAKLOOP(3)