| blob | 0eaf6e5e598c4fe807e90e686d902acd3944b89a |
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 .\"
20 .TH PCAP_LOOP 3PCAP "18 October 2014"
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
45 .B pcap_loop()
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'',
50 .B pcap_breakloop()
51 is called, or an error occurs.
52 It does
53 .B not
54 return when live read timeouts occur.
55 A value of \-1 or 0 for
56 .I cnt
57 is equivalent to infinity, so that packets are processed until another
58 ending condition occurs.
59 .PP
60 .B pcap_dispatch()
61 processes packets from a live capture or ``savefile'' until
62 .I cnt
63 packets are processed, the end of the current bufferful of packets is
64 reached when doing a live capture, the end of the ``savefile'' is
65 reached when reading from a ``savefile'',
66 .B pcap_breakloop()
67 is called, or an error occurs.
68 Thus, when doing a live capture,
69 .I cnt
70 is the maximum number of packets to process before returning, but is not
71 a minimum number; when reading a live capture, only one
72 bufferful of packets is read at a time, so fewer than
73 .I cnt
74 packets may be processed. A value of \-1 or 0 for
75 .I cnt
76 causes all the packets received in one buffer to be processed when
77 reading a live capture, and causes all the packets in the file to be
78 processed when reading a ``savefile''.
79 .PP
80 Note that, when doing a live capture on some platforms, if the read
81 timeout expires when there are no packets available,
82 .B pcap_dispatch()
83 will return 0, even when not in non-blocking mode, as there are no
84 packets to process. Applications should be prepared for this to happen,
85 but must not rely on it happening.
86 .PP
87 .ft B
88 (In older versions of libpcap, the behavior when
89 \fIcnt\fP
90 was 0 was undefined; different platforms and devices behaved
91 differently, so code that must work with older versions of libpcap
92 should use \-1, not 0, as the value of
93 \fIcnt\fP.)
94 .ft R
95 .PP
96 .I callback
97 specifies a
98 .I pcap_handler
99 routine to be called with three arguments:
100 a
101 .I u_char
102 pointer which is passed in the
103 .I user
104 argument to
105 .B pcap_loop()
106 or
107 .BR pcap_dispatch() ,
108 a
109 .I const struct pcap_pkthdr
110 pointer pointing to the packet time stamp and lengths, and a
111 .I const u_char
112 pointer to the first
113 .B caplen
114 (as given in the
115 .I struct pcap_pkthdr
116 a pointer to which is passed to the callback routine)
117 bytes of data from the packet. The
118 .I struct pcap_pkthdr
119 and the packet data are not to be freed by the callback routine, and are
120 not guaranteed to be valid after the callback routine returns; if the
121 code needs them to be valid after the callback, it must make a copy of
122 them.
123 .PP
124 The bytes of data from the packet begin with a link-layer header. The
125 format of the link-layer header is indicated by the return value of the
126 .B pcap_datalink()
127 routine when handed the
128 .B pcap_t
129 value also passed to
130 .B pcap_loop()
131 or
132 .BR pcap_dispatch() .
133 .I http://www.tcpdump.org/linktypes.html
134 lists the values
135 .B pcap_datalink()
136 can return and describes the packet formats that
137 correspond to those values. The value it returns will be valid for all
138 packets received unless and until
139 .B pcap_set_datalink()
140 is called; after a successful call to
141 .BR pcap_set_datalink() ,
142 all subsequent packets will have a link-layer header of the type
143 specified by the link-layer header type value passed to
144 .BR pcap_set_datalink() .
145 .PP
146 Do
147 .B NOT
148 assume that the packets for a given capture or ``savefile`` will have
149 any given link-layer header type, such as
150 .B DLT_EN10MB
151 for Ethernet. For example, the "any" device on Linux will have a
152 link-layer header type of
153 .B DLT_LINUX_SLL
154 even if all devices on the system at the time the "any" device is opened
155 have some other data link type, such as
156 .B DLT_EN10MB
157 for Ethernet.
158 .SH RETURN VALUE
159 .B pcap_loop()
160 returns 0 if
161 .I cnt
162 is exhausted or if, when reading from a ``savefile'', no more packets
163 are available. It returns \-1 if an error occurs or \-2 if the loop
164 terminated due to a call to
165 .B pcap_breakloop()
166 before any packets were processed.
167 It does
168 .B not
169 return when live read timeouts occur; instead, it attempts to read more
170 packets.
171 .PP
172 .B pcap_dispatch()
173 returns the number of packets processed on success; this can be 0 if no
174 packets were read from a live capture (if, for example, they were
175 discarded because they didn't pass the packet filter, or if, on
176 platforms that support a read timeout that starts before any packets
177 arrive, the timeout expires before any packets arrive, or if the file
178 descriptor for the capture device is in non-blocking mode and no packets
179 were available to be read) or if no more packets are available in a
180 ``savefile.'' It returns \-1 if an error occurs or \-2 if the loop
181 terminated due to a call to
182 .B pcap_breakloop()
183 before any packets were processed.
184 .ft B
185 If your application uses pcap_breakloop(),
186 make sure that you explicitly check for \-1 and \-2, rather than just
187 checking for a return value < 0.
188 .ft R
189 .PP
190 If \-1 is returned,
191 .B pcap_geterr()
192 or
193 .B pcap_perror()
194 may be called with
195 .I p
196 as an argument to fetch or display the error text.
197 .SH SEE ALSO
198 pcap(3PCAP), pcap_geterr(3PCAP), pcap_breakloop(3PCAP),
199 pcap_datalink(3PCAP)