pcap_loop, pcap_dispatch - process packets from a live capture or save- file
#include <pcap/pcap.h> typedef void (*pcap_handler)(u_char *user, const struct pcap_pkthdr *h, const u_char *bytes); pcap_loop(3) *p, int cnt, pcap_handler callback, u_char *user); int pcap_dispatch(pcap_t *p, int cnt, pcap_handler callback, u_char *user);
pcap_loop(3) processes packets from a live capture or ``savefile'' until cnt packets are processed, the end of the ``savefile'' is reached when reading from a ``savefile'', pcap_breakloop() is called, or an error occurs. It does not return when live read timeouts occur. A value of -1 or 0 for cnt is equivalent to infinity, so that packets are pro- cessed until another ending condition occurs. pcap_dispatch() processes packets from a live capture or ``savefile'' until cnt packets are processed, the end of the current bufferful of packets is reached when doing a live capture, the end of the ``save- file'' is reached when reading from a ``savefile'', pcap_breakloop() is called, or an error occurs. Thus, when doing a live capture, cnt is the maximum number of packets to process before returning, but is not a minimum number; when reading a live capture, only one bufferful of packets is read at a time, so fewer than cnt packets may be processed. A value of -1 or 0 for cnt causes all the packets received in one buffer to be processed when reading a live capture, and causes all the packets in the file to be processed when reading a ``savefile''. (In older versions of libpcap, the behavior when cnt was 0 was unde- fined; different platforms and devices behaved differently, so code that must work with older versions of libpcap should use -1, not 0, as the value of cnt.) callback specifies a pcap_handler routine to be called with three argu- ments: a u_char pointer which is passed in the user argument to pcap_loop(3) or pcap_dispatch(), a const struct pcap_pkthdr pointer pointing to the packet time stamp and lengths, and a const u_char pointer to the first caplen (as given in the struct pcap_pkthdr a pointer to which is passed to the callback routine) bytes of data from the packet. The struct pcap_pkthdr and the packet data are not to be freed by the callback routine, and are not guaranteed to be valid after the callback routine returns; if the code needs them to be valid after the callback, it must make a copy of them.
pcap_loop(3) returns 0 if cnt is exhausted or if, when reading from a ``savefile'', no more packets are available. It returns -1 if an error occurs or -2 if the loop terminated due to a call to pcap_breakloop() before any packets were processed. It does not return when live read timeouts occur; instead, it attempts to read more packets. pcap_dispatch() returns the number of packets processed on success; this can be 0 if no packets were read from a live capture (if, for example, they were discarded because they didn't pass the packet fil- ter, or if, on platforms that support a read timeout that starts before any packets arrive, the timeout expires before any packets arrive, or if the file descriptor for the capture device is in non-blocking mode and no packets were available to be read) or if no more packets are available in a ``savefile.'' It returns -1 if an error occurs or -2 if the loop terminated due to a call to pcap_breakloop() before any pack- ets were processed. If your application uses pcap_breakloop(), make sure that you explicitly check for -1 and -2, rather than just checking for a return value < 0. If -1 is returned, pcap_geterr() or pcap_perror() may be called with p as an argument to fetch or display the error text.
pcap(3), pcap_geterr(3), pcap_breakloop(3) 24 December 2008 pcap_loop(3)
libpcap 1.4.0 - Generated Sat Jun 1 18:32:50 CDT 2013