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, not 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.
The bytes of data from the packet begin with a link-layer header. The format of
the link-layer header is indicated by the return value of the
pcap_datalink() routine when handed the
pcap_t value also passed
to
pcap_loop() or
pcap_dispatch().
http://www.tcpdump.org/linktypes.html lists the values
pcap_datalink() can return and describes the packet formats that
correspond to those values. The value it returns will be valid for all packets
received unless and until
pcap_set_datalink() is called; after a
successful call to
pcap_set_datalink(), all subsequent packets will
have a link-layer header of the type specified by the link-layer header type
value passed to
pcap_set_datalink().
Do
NOT assume that the packets for a given capture or ``savefile`` will
have any given link-layer header type, such as
DLT_EN10MB for Ethernet.
For example, the "any" device on Linux will have a link-layer header
type of
DLT_LINUX_SLL even if all devices on the system at the time the
"any" device is opened have some other data link type, such as
DLT_EN10MB for Ethernet.
RETURN VALUE¶
pcap_loop() 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 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),
pcap_datalink(3PCAP)