PCAP_LOOP(3PCAP) PCAP_LOOP(3PCAP)

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(3PCAP) is
called, or an error occurs. It does not return when live packet
buffer 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''.

Note that, when doing a live capture on some platforms, if the read
timeout expires when there are no packets available, pcap_dispatch()
will return 0, even when not in non-blocking mode, as there are no
packets to process. Applications should be prepared for this to
happen, but must not rely on it happening.

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(3PCAP) routine when handed the pcap_t value also
passed to pcap_loop() or pcap_dispatch().
https://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(3PCAP) 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 or DLT_LINUX_SLL2 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
PCAP_ERROR_BREAK if the loop terminated due to a call to
pcap_breakloop() before any packets were processed,
PCAP_ERROR_NOT_ACTIVATED if called on a capture handle that has been
created but not activated, or PCAP_ERROR if another error occurs. It
does not return when live packet buffer 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 packet buffer 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
PCAP_ERROR_BREAK if the loop terminated due to a call to
pcap_breakloop() before any packets were processed,
PCAP_ERROR_NOT_ACTIVATED if called on a capture handle that has been
created but not activated, or PCAP_ERROR if another error occurs. If
your application uses pcap_breakloop(), make sure that you explicitly
check for PCAP_ERROR and PCAP_ERROR_BREAK, rather than just checking
for a return value < 0.

If PCAP_ERROR is returned, pcap_geterr(3PCAP) or pcap_perror(3PCAP)
may be called with p as an argument to fetch or display the error
text.

BACKWARD COMPATIBILITY

In libpcap versions before 1.5.0, the behavior when cnt was 0 was
undefined; different platforms and devices behaved differently, so
code that must work with these versions of libpcap should use -1, not
0, as the value of cnt.

SEE ALSO

pcap(3PCAP)

5 March 2022 PCAP_LOOP(3PCAP)