Commit | Line | Data |
---|---|---|
de0d3203 PA |
1 | .\" Copyright (c) 1994, 1996, 1997 |
2 | .\" The Regents of the University of California. All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that: (1) source code distributions | |
6 | .\" retain the above copyright notice and this paragraph in its entirety, (2) | |
7 | .\" distributions including binary code include the above copyright notice and | |
8 | .\" this paragraph in its entirety in the documentation or other materials | |
9 | .\" provided with the distribution, and (3) all advertising materials mentioning | |
10 | .\" features or use of this software display the following acknowledgement: | |
11 | .\" ``This product includes software developed by the University of California, | |
12 | .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of | |
13 | .\" the University nor the names of its contributors may be used to endorse | |
14 | .\" or promote products derived from this software without specific prior | |
15 | .\" written permission. | |
16 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED | |
17 | .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF | |
18 | .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. | |
19 | .\" | |
ea16f64e | 20 | .TH PCAP_LOOP 3PCAP "22 August 2020" |
de0d3203 PA |
21 | .SH NAME |
22 | pcap_loop, pcap_dispatch \- process packets from a live capture or savefile | |
23 | .SH SYNOPSIS | |
24 | .nf | |
25 | .ft B | |
26 | #include <pcap/pcap.h> | |
27 | .ft | |
28 | .LP | |
29 | .ft B | |
30 | typedef void (*pcap_handler)(u_char *user, const struct pcap_pkthdr *h, | |
31 | .ti +8 | |
32 | const u_char *bytes); | |
33 | .ft | |
34 | .LP | |
35 | .ft B | |
36 | int pcap_loop(pcap_t *p, int cnt, | |
37 | .ti +8 | |
38 | pcap_handler callback, u_char *user); | |
39 | int pcap_dispatch(pcap_t *p, int cnt, | |
40 | .ti +8 | |
41 | pcap_handler callback, u_char *user); | |
42 | .ft | |
43 | .fi | |
44 | .SH DESCRIPTION | |
ea16f64e | 45 | .BR pcap_loop () |
de0d3203 PA |
46 | processes packets from a live capture or ``savefile'' until |
47 | .I cnt | |
48 | packets are processed, the end of the ``savefile'' is | |
49 | reached when reading from a ``savefile'', | |
ea16f64e | 50 | .BR pcap_breakloop (3PCAP) |
de0d3203 PA |
51 | is called, or an error occurs. |
52 | It does | |
53 | .B not | |
3a289941 | 54 | return when live packet buffer timeouts occur. |
ea16f64e AHJ |
55 | A value of |
56 | .B \-1 | |
57 | or | |
58 | .B 0 | |
59 | for | |
de0d3203 PA |
60 | .I cnt |
61 | is equivalent to infinity, so that packets are processed until another | |
62 | ending condition occurs. | |
63 | .PP | |
ea16f64e | 64 | .BR pcap_dispatch () |
de0d3203 PA |
65 | processes packets from a live capture or ``savefile'' until |
66 | .I cnt | |
67 | packets are processed, the end of the current bufferful of packets is | |
68 | reached when doing a live capture, the end of the ``savefile'' is | |
69 | reached when reading from a ``savefile'', | |
ea16f64e | 70 | .BR pcap_breakloop () |
de0d3203 PA |
71 | is called, or an error occurs. |
72 | Thus, when doing a live capture, | |
73 | .I cnt | |
74 | is the maximum number of packets to process before returning, but is not | |
75 | a minimum number; when reading a live capture, only one | |
76 | bufferful of packets is read at a time, so fewer than | |
77 | .I cnt | |
ea16f64e AHJ |
78 | packets may be processed. A value of |
79 | .B \-1 | |
80 | or | |
81 | .B 0 | |
82 | for | |
de0d3203 PA |
83 | .I cnt |
84 | causes all the packets received in one buffer to be processed when | |
85 | reading a live capture, and causes all the packets in the file to be | |
86 | processed when reading a ``savefile''. | |
87 | .PP | |
97a9217a AHJ |
88 | Note that, when doing a live capture on some platforms, if the read |
89 | timeout expires when there are no packets available, | |
ea16f64e | 90 | .BR pcap_dispatch () |
97a9217a AHJ |
91 | will return 0, even when not in non-blocking mode, as there are no |
92 | packets to process. Applications should be prepared for this to happen, | |
93 | but must not rely on it happening. | |
94 | .PP | |
de0d3203 | 95 | .I callback |
a85e14b0 PA |
96 | specifies a |
97 | .I pcap_handler | |
98 | routine to be called with three arguments: | |
de0d3203 PA |
99 | a |
100 | .I u_char | |
101 | pointer which is passed in the | |
102 | .I user | |
103 | argument to | |
ea16f64e | 104 | .BR pcap_loop () |
de0d3203 | 105 | or |
ea16f64e | 106 | .BR pcap_dispatch (), |
de0d3203 PA |
107 | a |
108 | .I const struct pcap_pkthdr | |
109 | pointer pointing to the packet time stamp and lengths, and a | |
110 | .I const u_char | |
111 | pointer to the first | |
112 | .B caplen | |
113 | (as given in the | |
114 | .I struct pcap_pkthdr | |
115 | a pointer to which is passed to the callback routine) | |
a85e14b0 PA |
116 | bytes of data from the packet. The |
117 | .I struct pcap_pkthdr | |
118 | and the packet data are not to be freed by the callback routine, and are | |
119 | not guaranteed to be valid after the callback routine returns; if the | |
120 | code needs them to be valid after the callback, it must make a copy of | |
121 | them. | |
97a9217a AHJ |
122 | .PP |
123 | The bytes of data from the packet begin with a link-layer header. The | |
124 | format of the link-layer header is indicated by the return value of the | |
ea16f64e | 125 | .BR pcap_datalink (3PCAP) |
97a9217a AHJ |
126 | routine when handed the |
127 | .B pcap_t | |
128 | value also passed to | |
ea16f64e | 129 | .BR pcap_loop () |
97a9217a | 130 | or |
ea16f64e | 131 | .BR pcap_dispatch (). |
3a289941 | 132 | .I https://www.tcpdump.org/linktypes.html |
97a9217a | 133 | lists the values |
ea16f64e | 134 | .BR pcap_datalink () |
97a9217a AHJ |
135 | can return and describes the packet formats that |
136 | correspond to those values. The value it returns will be valid for all | |
137 | packets received unless and until | |
ea16f64e | 138 | .BR pcap_set_datalink (3PCAP) |
97a9217a | 139 | is called; after a successful call to |
ea16f64e | 140 | .BR pcap_set_datalink (), |
97a9217a AHJ |
141 | all subsequent packets will have a link-layer header of the type |
142 | specified by the link-layer header type value passed to | |
ea16f64e | 143 | .BR pcap_set_datalink (). |
97a9217a AHJ |
144 | .PP |
145 | Do | |
146 | .B NOT | |
147 | assume that the packets for a given capture or ``savefile`` will have | |
148 | any given link-layer header type, such as | |
149 | .B DLT_EN10MB | |
150 | for Ethernet. For example, the "any" device on Linux will have a | |
151 | link-layer header type of | |
152 | .B DLT_LINUX_SLL | |
ea16f64e AHJ |
153 | or |
154 | .B DLT_LINUX_SLL2 | |
97a9217a AHJ |
155 | even if all devices on the system at the time the "any" device is opened |
156 | have some other data link type, such as | |
157 | .B DLT_EN10MB | |
158 | for Ethernet. | |
de0d3203 | 159 | .SH RETURN VALUE |
ea16f64e AHJ |
160 | .BR pcap_loop () |
161 | returns | |
162 | .B 0 | |
163 | if | |
de0d3203 | 164 | .I cnt |
0e381983 | 165 | is exhausted or if, when reading from a ``savefile'', no more packets |
3a289941 AL |
166 | are available. It returns |
167 | .B PCAP_ERROR | |
168 | if an error occurs or | |
169 | .B PCAP_ERROR_BREAK | |
170 | if the loop terminated due to a call to | |
ea16f64e | 171 | .BR pcap_breakloop () |
de0d3203 PA |
172 | before any packets were processed. |
173 | It does | |
174 | .B not | |
3a289941 AL |
175 | return when live packet buffer timeouts occur; instead, it attempts to |
176 | read more packets. | |
de0d3203 | 177 | .PP |
ea16f64e | 178 | .BR pcap_dispatch () |
de0d3203 PA |
179 | returns the number of packets processed on success; this can be 0 if no |
180 | packets were read from a live capture (if, for example, they were | |
181 | discarded because they didn't pass the packet filter, or if, on | |
3a289941 AL |
182 | platforms that support a packet buffer timeout that starts before any |
183 | packets arrive, the timeout expires before any packets arrive, or if the | |
184 | file descriptor for the capture device is in non-blocking mode and no | |
185 | packets were available to be read) or if no more packets are available | |
186 | in a ``savefile.'' It returns | |
187 | .B PCAP_ERROR | |
188 | if an error occurs or | |
189 | .B PCAP_ERROR_BREAK | |
190 | if the loop terminated due to a call to | |
ea16f64e | 191 | .BR pcap_breakloop () |
de0d3203 PA |
192 | before any packets were processed. |
193 | .ft B | |
194 | If your application uses pcap_breakloop(), | |
3a289941 AL |
195 | make sure that you explicitly check for PCAP_ERROR and PCAP_ERROR_BREAK, |
196 | rather than just checking for a return value < 0. | |
de0d3203 PA |
197 | .ft R |
198 | .PP | |
3a289941 AL |
199 | If |
200 | .B PCAP_ERROR | |
201 | is returned, | |
ea16f64e | 202 | .BR pcap_geterr (3PCAP) |
de0d3203 | 203 | or |
ea16f64e | 204 | .BR pcap_perror (3PCAP) |
de0d3203 PA |
205 | may be called with |
206 | .I p | |
207 | as an argument to fetch or display the error text. | |
ea16f64e AHJ |
208 | .SH BACKWARD COMPATIBILITY |
209 | .PP | |
210 | In libpcap versions before 1.5.0, the behavior when | |
211 | .I cnt | |
212 | was | |
213 | .B 0 | |
214 | was undefined; different platforms and devices behaved differently, | |
215 | so code that must work with these versions of libpcap should use | |
216 | .BR \-1 , | |
217 | not | |
218 | .BR 0 , | |
219 | as the value of | |
220 | .IR cnt . | |
de0d3203 | 221 | .SH SEE ALSO |
ea16f64e | 222 | .BR pcap (3PCAP) |