# pcap_dispatch

## 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_.
    


* * *