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

Backward Compatibility

This function became available in libpcap release 0.8.1. In releases prior to libpcap 1.10.0, pcap_breakloop() will not wake up a blocked thread on any platform.

Description

pcap_breakloop() sets a flag that will force pcap_dispatch(3PCAP) or pcap_loop(3PCAP) 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. If the loop is currently blocked waiting for packets to arrive, pcap_breakloop() will also, on some platforms, wake up the thread that is blocked. In this version of libpcap, the only platforms on which a wakeup is caused by pcap_breakloop() are Linux and Windows, and the wakeup will only be caused when capturing on network interfaces; it will not be caused on other operating systems, and will not be caused on any OS when capturing on other types of devices. This routine is safe to use inside a signal handler on UNIX or a console control handler on Windows, or in a thread other than the one in which the loop is running, as it merely sets a flag that is checked within the loop and, on some platforms, performs a signal-safe and thread-safe API call. 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. NotethatifyouarecatchingsignalsonUNIXsystemsthatsupportrestartingsystemcallsafterasignal,andcallingpcap_breakloop()inthesignalhandler,youmustspecify,whencatchingthosesignals,thatsystemcallsshouldNOTberestartedbythatsignal.Otherwise,ifthesignalinterruptedacallreadingpacketsinalivecapture,whenyoursignalhandlerreturnsaftercallingpcap_breakloop(),thecallwillberestarted,andtheloopwillnotterminateuntilmorepacketsarriveandthecallcompletes.Notealsothat,inamulti-threadedapplication,ifonethreadisblockedinpcap_dispatch(),pcap_loop(),pcap_next(3PCAP),orpcap_next_ex(3PCAP),acalltopcap_breakloop()inadifferentthreadwillonlyunblockthatthreadontheplatformsandcapturedeviceslistedabove. If a non-zero packet buffer timeout is set on the pcap_t, and you are capturing on a network interface, the thread will be unblocked with the timeout expires. This is not guaranteed to happen unless at least one packet has arrived; the only platforms on which it happens are macOS, the BSDs, Solaris 11, AIX, Tru64 UNIX, and Windows. If you want to ensure that the loop will eventually be unblocked on any other platforms, or unblocked when capturing on a device other than a network interface, 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 or thread signalling in systems that support POSIX threads. Notethatifpcap_breakloop()unblocksthethreadcapturingpackets,andyouarerunningonaplatformthatsupportspacketbuffering,theremaybepacketsinthebufferthatarrivedbeforepcap_breakloop()werecalledbutthatweren'tyetprovidedtolibpcap,thosepacketswillnothavebeenprocessedbypcap_dispatch()orpcap_loop().Ifpcap_breakloop()wascalledinordertoterminatethecaptureprocess,then,inordertoprocessthosepackets,youwouldhavetocallpcap_dispatch()onetimeinordertoprocessthelastbatchofpackets.Thismayblockuntilthepacketbuffertimeoutexpires,soanon-zeropacketbuffertimeoutmustbeused. 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 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 subsequent call will return PCAP_ERROR_BREAK and clear the flag.