NAME¶
pcap_loop, pcap_dispatch - process packets from a live capture or savefile
SYNOPSIS¶
#include <pcap/pcap.h>
typedef void (*pcap_handler)(u_char *user, const struct pcap_pkthdr *h,
const u_char *bytes);
int pcap_loop(pcap_t *p, int cnt,
pcap_handler callback, u_char *user);
int pcap_dispatch(pcap_t *p, int cnt,
pcap_handler callback, u_char *user);
DESCRIPTION¶
pcap_loop() 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 processed
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 ``savefile'' 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 undefined;
different platforms and devices behaved differently, so code that must work
with older versions of libpcap should use -1, nor 0, as the value of
cnt.)
callback specifies a
pcap_handler routine to be called with three
arguments: a
u_char pointer which is passed in the
user argument
to
pcap_loop() 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.
RETURN VALUE¶
pcap_loop() returns 0 if
cnt is exhausted, -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 filter, 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 packets 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.
SEE ALSO¶
pcap(3PCAP), pcap_geterr(3PCAP), pcap_breakloop(3PCAP)