1PCAP_LOOP(3PCAP)                                              PCAP_LOOP(3PCAP)
2
3
4

NAME

6       pcap_loop, pcap_dispatch - process packets from a live capture or save‐
7       file
8

SYNOPSIS

10       #include <pcap/pcap.h>
11
12       typedef void (*pcap_handler)(u_char *user, const struct pcap_pkthdr *h,
13                                   const u_char *bytes);
14
15       int pcap_loop(pcap_t *p, int cnt,
16               pcap_handler callback, u_char *user);
17       int pcap_dispatch(pcap_t *p, int cnt,
18               pcap_handler callback, u_char *user);
19

DESCRIPTION

21       pcap_loop() processes packets from a live capture or ``savefile'' until
22       cnt  packets are processed, the end of the ``savefile'' is reached when
23       reading from a ``savefile'', pcap_breakloop() is called,  or  an  error
24       occurs.   It does not return when live read timeouts occur.  A value of
25       -1 or 0 for cnt is equivalent to infinity, so  that  packets  are  pro‐
26       cessed until another ending condition occurs.
27
28       pcap_dispatch()  processes  packets from a live capture or ``savefile''
29       until cnt packets are processed, the end of the  current  bufferful  of
30       packets  is  reached  when doing a live capture, the end of the ``save‐
31       file'' is reached when reading from a ``savefile'', pcap_breakloop() is
32       called,  or  an  error occurs.  Thus, when doing a live capture, cnt is
33       the maximum number of packets to process before returning, but is not a
34       minimum  number;  when  reading  a  live capture, only one bufferful of
35       packets is read at a time, so fewer than cnt packets may be  processed.
36       A  value of -1 or 0 for cnt causes all the packets received in one buf‐
37       fer to be processed when reading a live capture,  and  causes  all  the
38       packets in the file to be processed when reading a ``savefile''.
39
40       (In  older  versions  of libpcap, the behavior when cnt was 0 was unde‐
41       fined; different platforms and devices  behaved  differently,  so  code
42       that  must work with older versions of libpcap should use -1, nor 0, as
43       the value of cnt.)
44
45       callback specifies a pcap_handler routine to be called with three argu‐
46       ments:  a  u_char  pointer  which  is  passed  in  the user argument to
47       pcap_loop() or pcap_dispatch(),  a  const  struct  pcap_pkthdr  pointer
48       pointing  to  the  packet  time  stamp  and lengths, and a const u_char
49       pointer to the first caplen (as  given  in  the  struct  pcap_pkthdr  a
50       pointer  to which is passed to the callback routine) bytes of data from
51       the packet.
52

RETURN VALUE

54       pcap_loop() returns 0 if cnt is exhausted, -1 if an error occurs, or -2
55       if  the  loop  terminated  due to a call to pcap_breakloop() before any
56       packets were processed.  It does not return  when  live  read  timeouts
57       occur; instead, it attempts to read more packets.
58
59       pcap_dispatch()  returns  the  number  of packets processed on success;
60       this can be 0 if no packets were read from  a  live  capture  (if,  for
61       example,  they  were discarded because they didn't pass the packet fil‐
62       ter, or if, on platforms that support a read timeout that starts before
63       any  packets  arrive, the timeout expires before any packets arrive, or
64       if the file descriptor for the capture device is in  non-blocking  mode
65       and  no  packets  were  available to be read) or if no more packets are
66       available in a ``savefile.''  It returns -1 if an error occurs or -2 if
67       the  loop terminated due to a call to pcap_breakloop() before any pack‐
68       ets were processed.  If your application  uses  pcap_breakloop(),  make
69       sure that you explicitly check for -1 and -2, rather than just checking
70       for a return value < 0.
71
72       If -1 is returned, pcap_geterr() or pcap_perror() may be called with  p
73       as an argument to fetch or display the error text.
74

SEE ALSO

76       pcap(3PCAP), pcap_geterr(3PCAP), pcap_breakloop(3PCAP)
77
78
79
80                               24 December 2008               PCAP_LOOP(3PCAP)
Impressum