1PCAP(3PCAP) PCAP(3PCAP)
2
6 pcap - Packet Capture library
7
9 #include <pcap/pcap.h>
10
12 The Packet Capture library provides a high level interface to packet
13 capture systems. All packets on the network, even those destined for
14 other hosts, are accessible through this mechanism. It also supports
15 saving captured packets to a ``savefile'', and reading packets from a
16 ``savefile''.
17 To open a handle for a live capture, call pcap_create(), set the appro‐
19 priate options on the handle, and then activate it with pcap_acti‐
20 vate(). To open a handle for a ``savefile'' with captured packets,
21 call pcap_open_offline(). Both pcap_create() and pcap_open_offline()
22 return a pointer to a pcap_t, which is the handle used for reading
23 packets from the capture stream or the ``savefile'', and for finding
24 out information about the capture stream or ``savefile''.
25 The options that can be set on a capture handle include
27 snapshot length
29 If, when capturing, you capture the entire contents of the
30 packet, that requires more CPU time to copy the packet to your
31 application, more disk and possibly network bandwidth to write
32 the packet data to a file, and more disk space to save the
33 packet. If you don't need the entire contents of the packet -
34 for example, if you are only interested in the TCP headers of
35 packets - you can set the "snapshot length" for the capture to
36 an appropriate value. If the snapshot length is set to snaplen,
37 and snaplen is less than the size of a packet that is captured,
38 only the first snaplen bytes of that packet will be captured and
39 provided as packet data.
40 A snapshot length of 65535 should be sufficient, on most if not
42 all networks, to capture all the data available from the packet.
43 The snapshot length is set with pcap_set_snaplen().
45 promiscuous mode
47 On broadcast LANs such as Ethernet, if the network isn't
48 switched, or if the adapter is connected to a "mirror port" on a
49 switch to which all packets passing through the switch are sent,
50 a network adapter receives all packets on the LAN, including
51 unicast or multicast packets not sent to a network address that
52 the network adapter isn't configured to recognize.
53 Normally, the adapter will discard those packets; however, many
55 network adapters support "promiscuous mode", which is a mode in
56 which all packets, even if they are not sent to an address that
57 the adapter recognizes, are provided to the host. This is use‐
58 ful for passively capturing traffic between two or more other
59 hosts for analysis.
60 Note that even if an application does not set promiscuous mode,
62 the adapter could well be in promiscuous mode for some other
63 reason.
64 For now, this doesn't work on the "any" device; if an argument
66 of "any" or NULL is supplied, the setting of promiscuous mode is
67 ignored.
68 Promiscuous mode is set with pcap_set_promisc().
70 monitor mode
72 On IEEE 802.11 wireless LANs, even if an adapter is in promiscu‐
73 ous mode, it will supply to the host only frames for the network
74 with which it's associated. It might also supply only data
75 frames, not management or control frames, and might not provide
76 the 802.11 header or radio information pseudo-header for those
77 frames.
78 In "monitor mode", sometimes also called "rfmon mode" (for
80 "Radio Frequency MONitor"), the adapter will supply all frames
81 that it receives, with 802.11 headers, and might supply a
82 pseudo-header with radio information about the frame as well.
83 Note that in monitor mode the adapter might disassociate from
85 the network with which it's associated, so that you will not be
86 able to use any wireless networks with that adapter. This could
87 prevent accessing files on a network server, or resolving host
88 names or network addresses, if you are capturing in monitor mode
89 and are not connected to another network with another adapter.
90 Monitor mode is set with pcap_set_rfmon(), and
92 pcap_can_set_rfmon() can be used to determine whether an adapter
93 can be put into monitor mode.
94 read timeout
96 If, when capturing, packets are delivered as soon as they
97 arrive, the application capturing the packets will be woken up
98 for each packet as it arrives, and might have to make one or
99 more calls to the operating system to fetch each packet.
100 If, instead, packets are not delivered as soon as they arrive,
102 but are delivered after a short delay (called a "read timeout"),
103 more than one packet can be accumulated before the packets are
104 delivered, so that a single wakeup would be done for multiple
105 packets, and each set of calls made to the operating system
106 would supply multiple packets, rather than a single packet.
107 This reduces the per-packet CPU overhead if packets are arriving
108 at a high rate, increasing the number of packets per second that
109 can be captured.
110 The read timeout is required so that an application won't wait
112 for the operating system's capture buffer to fill up before
113 packets are delivered; if packets are arriving slowly, that wait
114 could take an arbitrarily long period of time.
115 Not all platforms support a read timeout; on platforms that
117 don't, the read timeout is ignored. A zero value for the time‐
118 out, on platforms that support a read timeout, will cause a read
119 to wait forever to allow enough packets to arrive, with no time‐
120 out.
121 NOTE: the read timeout cannot be used to cause calls that read
123 packets to return within a limited period of time, because, on
124 some platforms, the read timeout isn't supported, and, on other
125 platforms, the timer doesn't start until at least one packet
126 arrives. This means that the read timeout should NOT be used,
127 for example, in an interactive application to allow the packet
128 capture loop to ``poll'' for user input periodically, as there's
129 no guarantee that a call reading packets will return after the
130 timeout expires even if no packets have arrived.
131 The read timeout is set with pcap_set_timeout().
133 buffer size
135 Packets that arrive for a capture are stored in a buffer, so
136 that they do not have to be read by the application as soon as
137 they arrive. On some platforms, the buffer's size can be set; a
138 size that's too small could mean that, if too many packets are
139 being captured and the snapshot length doesn't limit the amount
140 of data that's buffered, packets could be dropped if the buffer
141 fills up before the application can read packets from it, while
142 a size that's too large could use more non-pageable operating
143 system memory than is necessary to prevent packets from being
144 dropped.
145 The buffer size is set with pcap_set_buffer_size().
147 Reading packets from a network interface may require that you have spe‐
149 cial privileges:
150 Under SunOS 3.x or 4.x with NIT or BPF:
152 You must have read access to /dev/nit or /dev/bpf*.
153 Under Solaris with DLPI:
155 You must have read/write access to the network pseudo device,
156 e.g. /dev/le. On at least some versions of Solaris, however,
157 this is not sufficient to allow tcpdump to capture in promiscu‐
158 ous mode; on those versions of Solaris, you must be root, or the
159 application capturing packets must be installed setuid to root,
160 in order to capture in promiscuous mode. Note that, on many
161 (perhaps all) interfaces, if you don't capture in promiscuous
162 mode, you will not see any outgoing packets, so a capture not
163 done in promiscuous mode may not be very useful.
164 In newer versions of Solaris, you must have been given the
166 net_rawaccess privilege; this is both necessary and sufficient
167 to give you access to the network pseudo-device - there is no
168 need to change the privileges on that device. A user can be
169 given that privilege by, for example, adding that privilege to
170 the user's defaultpriv key with the usermod (1M) command.
171 Under HP-UX with DLPI:
173 You must be root or the application capturing packets must be
174 installed setuid to root.
175 Under IRIX with snoop:
177 You must be root or the application capturing packets must be
178 installed setuid to root.
179 Under Linux:
181 You must be root or the application capturing packets must be
182 installed setuid to root (unless your distribution has a kernel
183 that supports capability bits such as CAP_NET_RAW and code to
184 allow those capability bits to be given to particular accounts
185 and to cause those bits to be set on a user's initial processes
186 when they log in, in which case you must have CAP_NET_RAW in
187 order to capture and CAP_NET_ADMIN to enumerate network devices
188 with, for example, the -D flag).
189 Under ULTRIX and Digital UNIX/Tru64 UNIX:
191 Any user may capture network traffic. However, no user (not
192 even the super-user) can capture in promiscuous mode on an
193 interface unless the super-user has enabled promiscuous-mode
194 operation on that interface using pfconfig(8), and no user (not
195 even the super-user) can capture unicast traffic received by or
196 sent by the machine on an interface unless the super-user has
197 enabled copy-all-mode operation on that interface using pfcon‐
198 fig, so useful packet capture on an interface probably requires
199 that either promiscuous-mode or copy-all-mode operation, or both
200 modes of operation, be enabled on that interface.
201 Under BSD (this includes Mac OS X):
203 You must have read access to /dev/bpf* on systems that don't
204 have a cloning BPF device, or to /dev/bpf on systems that do.
205 On BSDs with a devfs (this includes Mac OS X), this might
206 involve more than just having somebody with super-user access
207 setting the ownership or permissions on the BPF devices - it
208 might involve configuring devfs to set the ownership or permis‐
209 sions every time the system is booted, if the system even sup‐
210 ports that; if it doesn't support that, you might have to find
211 some other way to make that happen at boot time.
212 Reading a saved packet file doesn't require special privileges.
214 To open a ``savefile`` to which to write packets, call
216 pcap_dump_open(). It returns a pointer to a pcap_dumper_t, which is
217 the handle used for writing packets to the ``savefile''.
218 Packets are read with pcap_dispatch() or pcap_loop(), which process one
220 or more packets, calling a callback routine for each packet, or with
221 pcap_next() or pcap_next_ex(), which return the next packet. The call‐
222 back for pcap_dispatch() and pcap_loop() is supplied a pointer to a
223 struct pcap_pkthdr, which includes the following members:
224 ts a struct timeval containing the time when the packet was
226 captured
227 caplen a bpf_u_int32 giving the number of bytes of the packet
229 that are available from the capture
230 len a bpf_u_int32 giving the length of the packet, in bytes
232 (which might be more than the number of bytes available
233 from the capture, if the length of the packet is larger
234 than the maximum number of bytes to capture).
235 pcap_next_ex() supplies that pointer through a pointer argument.
237 pcap_next() is passed an argument that points to a struct pcap_pkthdr
238 structure, and fills it in.
239 The callback is also supplied a const u_char pointer to the first
241 caplen (as given in the struct pcap_pkthdr a pointer to which is passed
242 to the callback routine) bytes of data from the packet. This won't
243 necessarily be the entire packet; to capture the entire packet, you
244 will have to provide a value for snaplen in your call to
245 pcap_open_live() that is sufficiently large to get all of the packet's
246 data - a value of 65535 should be sufficient on most if not all net‐
247 works). When reading from a ``savefile'', the snapshot length speci‐
248 fied when the capture was performed will limit the amount of packet
249 data available. pcap_next() returns that pointer; pcap_next_ex() sup‐
250 plies that pointer through a pointer argument.
251
253 In versions of libpcap prior to 1.0, the pcap.h header file was not in
254 a pcap directory on most platforms; if you are writing an application
255 that must work on versions of libpcap prior to 1.0, include <pcap.h>,
256 which will include <pcap/pcap.h> for you, rather than including
257 <pcap/pcap.h>.
258 pcap_create() and pcap_activate() were not available in versions of
260 libpcap prior to 1.0; if you are writing an application that must work
261 on versions of libpcap prior to 1.0, either use pcap_open_live() to get
262 a handle for a live capture or, if you want to be able to use the addi‐
263 tional capabilities offered by using pcap_create() and pcap_activate(),
264 use an autoconf(1) script or some other configuration script to check
265 whether the libpcap 1.0 APIs are available and use them only if they
266 are.
267
269 autoconf(1), tcpdump(8), tcpslice(8), pcap-filter(7), pfconfig(8),
270 usermod(1M)
271
273 The original authors of libpcap are:
274 Van Jacobson, Craig Leres and Steven McCanne, all of the Lawrence
276 Berkeley National Laboratory, University of California, Berkeley, CA.
277 The current version is available from "The Tcpdump Group"'s Web site at
279 http://www.tcpdump.org/
281
283 Please send problems, bugs, questions, desirable enhancements, etc. to:
284 tcpdump-workers@lists.tcpdump.org
286 4 April 2008 PCAP(3PCAP)