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 packet buffer timeouts occur.  A
25       value of -1 or 0 for cnt is equivalent to infinity, so that packets are
26       processed 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       Note  that,  when  doing  a live capture on some platforms, if the read
41       timeout expires when there are no  packets  available,  pcap_dispatch()
42       will  return  0,  even  when  not in non-blocking mode, as there are no
43       packets to process.  Applications should be prepared for this  to  hap‐
44       pen, but must not rely on it happening.
45
46       (In  older  versions  of libpcap, the behavior when cnt was 0 was unde‐
47       fined; different platforms and devices  behaved  differently,  so  code
48       that  must work with older versions of libpcap should use -1, not 0, as
49       the value of cnt.)
50
51       callback specifies a pcap_handler routine to be called with three argu‐
52       ments:  a  u_char  pointer  which  is  passed  in  the user argument to
53       pcap_loop() or pcap_dispatch(),  a  const  struct  pcap_pkthdr  pointer
54       pointing  to  the  packet  time  stamp  and lengths, and a const u_char
55       pointer to the first caplen (as  given  in  the  struct  pcap_pkthdr  a
56       pointer  to which is passed to the callback routine) bytes of data from
57       the packet.  The struct pcap_pkthdr and the packet data are not  to  be
58       freed by the callback routine, and are not guaranteed to be valid after
59       the callback routine returns; if the code needs them to be valid  after
60       the callback, it must make a copy of them.
61
62       The  bytes of data from the packet begin with a link-layer header.  The
63       format of the link-layer header is indicated by the return value of the
64       pcap_datalink()  routine  when  handed  the pcap_t value also passed to
65       pcap_loop() or pcap_dispatch().  https://www.tcpdump.org/linktypes.html
66       lists  the  values  pcap_datalink() can return and describes the packet
67       formats that correspond to those values.  The value it returns will  be
68       valid  for all packets received unless and until pcap_set_datalink() is
69       called; after a successful call to pcap_set_datalink(), all  subsequent
70       packets  will  have  a  link-layer  header of the type specified by the
71       link-layer header type value passed to pcap_set_datalink().
72
73       Do NOT assume that the packets for a given capture or ``savefile`` will
74       have any given link-layer header type, such as DLT_EN10MB for Ethernet.
75       For example, the "any" device on Linux will have  a  link-layer  header
76       type of DLT_LINUX_SLL even if all devices on the system at the time the
77       "any" device is  opened  have  some  other  data  link  type,  such  as
78       DLT_EN10MB for Ethernet.
79

RETURN VALUE

81       pcap_loop()  returns  0  if cnt is exhausted or if, when reading from a
82       ``savefile'', no more packets are available.  It returns -1 if an error
83       occurs  or  -2 if the loop terminated due to a call to pcap_breakloop()
84       before any packets were processed.  It does not return when live packet
85       buffer timeouts occur; instead, it attempts to read more packets.
86
87       pcap_dispatch()  returns  the  number  of packets processed on success;
88       this can be 0 if no packets were read from  a  live  capture  (if,  for
89       example,  they  were discarded because they didn't pass the packet fil‐
90       ter, or if, on platforms that support  a  packet  buffer  timeout  that
91       starts  before any packets arrive, the timeout expires before any pack‐
92       ets arrive, or if the file descriptor for the capture device is in non-
93       blocking  mode  and no packets were available to be read) or if no more
94       packets are available in a ``savefile.'' It  returns  -1  if  an  error
95       occurs  or  -2 if the loop terminated due to a call to pcap_breakloop()
96       before  any  packets  were  processed.   If   your   application   uses
97       pcap_breakloop(),  make  sure  that you explicitly check for -1 and -2,
98       rather than just checking for a return value < 0.
99
100       If -1 is returned, pcap_geterr() or pcap_perror() may be called with  p
101       as an argument to fetch or display the error text.
102

SEE ALSO

104       pcap(3PCAP),         pcap_geterr(3PCAP),         pcap_breakloop(3PCAP),
105       pcap_datalink(3PCAP)
106
107
108
109                                20 January 2017               PCAP_LOOP(3PCAP)
Impressum