1PCAP_LOOP(3PCAP) PCAP_LOOP(3PCAP)
2
6 pcap_loop, pcap_dispatch - process packets from a live capture or save‐
7 file
8
10 #include <pcap/pcap.h>
11 typedef void (*pcap_handler)(u_char *user, const struct pcap_pkthdr *h,
13 const u_char *bytes);
14 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
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 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 (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, not 0, as
43 the value of cnt.)
44 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. The struct pcap_pkthdr and the packet data are not to be
52 freed by the callback routine, and are not guaranteed to be valid after
53 the callback routine returns; if the code needs them to be valid after
54 the callback, it must make a copy of them.
55 The bytes of data from the packet begin with a link-layer header. The
57 format of the link-layer header is indicated by the return value of the
58 pcap_datalink() routine when handed the pcap_t value also passed to
59 pcap_loop() or pcap_dispatch(). http://www.tcpdump.org/linktypes.html
60 lists the values pcap_datalink() can return and describes the packet
61 formats that correspond to those values. The value it returns will be
62 valid for all packets received unless and until pcap_set_datalink() is
63 called; after a successful call to pcap_set_datalink(), all subsequent
64 packets will have a link-layer header of the type specified by the
65 link-layer header type value passed to pcap_set_datalink().
66 Do NOT assume that the packets for a given capture or ``savefile`` will
68 have any given link-layer header type, such as DLT_EN10MB for Ethernet.
69 For example, the "any" device on Linux will have a link-layer header
70 type of DLT_LINUX_SLL even if all devices on the system at the time the
71 "any" device is opened have some other data link type, such as
72 DLT_EN10MB for Ethernet.
73
75 pcap_loop() returns 0 if cnt is exhausted or if, when reading from a
76 ``savefile'', no more packets are available. It returns -1 if an error
77 occurs or -2 if the loop terminated due to a call to pcap_breakloop()
78 before any packets were processed. It does not return when live read
79 timeouts occur; instead, it attempts to read more packets.
80 pcap_dispatch() returns the number of packets processed on success;
82 this can be 0 if no packets were read from a live capture (if, for
83 example, they were discarded because they didn't pass the packet fil‐
84 ter, or if, on platforms that support a read timeout that starts before
85 any packets arrive, the timeout expires before any packets arrive, or
86 if the file descriptor for the capture device is in non-blocking mode
87 and no packets were available to be read) or if no more packets are
88 available in a ``savefile.'' It returns -1 if an error occurs or -2 if
89 the loop terminated due to a call to pcap_breakloop() before any pack‐
90 ets were processed. If your application uses pcap_breakloop(), make
91 sure that you explicitly check for -1 and -2, rather than just checking
92 for a return value < 0.
93 If -1 is returned, pcap_geterr() or pcap_perror() may be called with p
95 as an argument to fetch or display the error text.
96
98 pcap(3PCAP), pcap_geterr(3PCAP), pcap_breakloop(3PCAP),
99 pcap_datalink(3PCAP)
100 24 December 2008 PCAP_LOOP(3PCAP)