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() 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)

                                                                 24 December 2008                                                 PCAP_LOOP(3PCAP)