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)

                                         24 December 2008                        PCAP_LOOP(3PCAP)