manpagez: man (manual) pages & more
man pcap_loop(3)
Home | html | info | man
pcap_loop(3)                                              pcap_loop(3)




NAME

       pcap_loop, pcap_dispatch - process packets from a live capture or save-
       file


SYNOPSIS

       #include <pcap/pcap.h>

       typedef void (*pcap_handler)(u_char *user, const struct pcap_pkthdr *h,
                                   const u_char *bytes);

       pcap_loop(3) *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(3) 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  pro-
       cessed 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 ``save-
       file'' 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 unde-
       fined; 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 argu-
       ments:  a  u_char  pointer  which  is  passed  in  the user argument to
       pcap_loop(3) 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(3)  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 fil-
       ter, 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 pack-
       ets 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(3), pcap_geterr(3), pcap_breakloop(3)



                               24 December 2008               pcap_loop(3)

libpcap 1.4.0 - Generated Sat Jun 1 18:32:50 CDT 2013