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(3PCAP)  is  called,  or  an
24       error  occurs.   It  does  not  return when live packet buffer timeouts
25       occur.  A value of -1 or 0 for cnt is equivalent to infinity,  so  that
26       packets are 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       callback specifies a pcap_handler routine to be called with three argu‐
47       ments: a u_char pointer  which  is  passed  in  the  user  argument  to
48       pcap_loop()  or  pcap_dispatch(),  a  const  struct pcap_pkthdr pointer
49       pointing to the packet time stamp  and  lengths,  and  a  const  u_char
50       pointer  to  the  first  caplen  (as  given in the struct pcap_pkthdr a
51       pointer to which is passed to the callback routine) bytes of data  from
52       the  packet.   The struct pcap_pkthdr and the packet data are not to be
53       freed by the callback routine, and are not guaranteed to be valid after
54       the  callback routine returns; if the code needs them to be valid after
55       the callback, it must make a copy of them.
56
57       The bytes of data from the packet begin with a link-layer header.   The
58       format of the link-layer header is indicated by the return value of the
59       pcap_datalink(3PCAP) routine when handed the pcap_t value  also  passed
60       to   pcap_loop()   or  pcap_dispatch().   https://www.tcpdump.org/link
61       types.html lists the values pcap_datalink() can  return  and  describes
62       the  packet  formats  that  correspond  to  those values.  The value it
63       returns will be  valid  for  all  packets  received  unless  and  until
64       pcap_set_datalink(3PCAP)   is   called;  after  a  successful  call  to
65       pcap_set_datalink(), all subsequent  packets  will  have  a  link-layer
66       header of the type specified by the link-layer header type value passed
67       to pcap_set_datalink().
68
69       Do NOT assume that the packets for a given capture or ``savefile`` will
70       have any given link-layer header type, such as DLT_EN10MB for Ethernet.
71       For example, the "any" device on Linux will have  a  link-layer  header
72       type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the sys‐
73       tem at the time the "any" device is opened have some  other  data  link
74       type, such as DLT_EN10MB for Ethernet.
75

RETURN VALUE

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

BACKWARD COMPATIBILITY

102       In libpcap versions before 1.5.0, the behavior when cnt was 0 was unde‐
103       fined; different platforms and devices  behaved  differently,  so  code
104       that  must work with these versions of libpcap should use -1, not 0, as
105       the value of cnt.
106

SEE ALSO

108       pcap(3PCAP)
109
110
111
112                                22 August 2020                PCAP_LOOP(3PCAP)
Impressum