1 |
.\" @(#) $Header: /tcpdump/master/libpcap/pcap.3pcap.in,v 1.1 2008-10-21 07:33:01 guy Exp $ |
2 |
.\" |
3 |
.\" Copyright (c) 1994, 1996, 1997 |
4 |
.\" The Regents of the University of California. All rights reserved. |
5 |
.\" |
6 |
.\" Redistribution and use in source and binary forms, with or without |
7 |
.\" modification, are permitted provided that: (1) source code distributions |
8 |
.\" retain the above copyright notice and this paragraph in its entirety, (2) |
9 |
.\" distributions including binary code include the above copyright notice and |
10 |
.\" this paragraph in its entirety in the documentation or other materials |
11 |
.\" provided with the distribution, and (3) all advertising materials mentioning |
12 |
.\" features or use of this software display the following acknowledgement: |
13 |
.\" ``This product includes software developed by the University of California, |
14 |
.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of |
15 |
.\" the University nor the names of its contributors may be used to endorse |
16 |
.\" or promote products derived from this software without specific prior |
17 |
.\" written permission. |
18 |
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED |
19 |
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF |
20 |
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
21 |
.\" |
22 |
.TH PCAP 3PCAP "4 April 2008" |
23 |
.SH NAME |
24 |
pcap \- Packet Capture library |
25 |
.SH SYNOPSIS |
26 |
.nf |
27 |
.ft B |
28 |
#include <pcap/pcap.h> |
29 |
.LP |
30 |
.ft B |
31 |
.ft |
32 |
.fi |
33 |
.SH DESCRIPTION |
34 |
The Packet Capture library |
35 |
provides a high level interface to packet capture systems. All packets |
36 |
on the network, even those destined for other hosts, are accessible |
37 |
through this mechanism. |
38 |
It also supports saving captured packets to a ``savefile'', and reading |
39 |
packets from a ``savefile''. |
40 |
.SS Opening a capture handle for reading |
41 |
To open a handle for a live capture, given the name of the network or |
42 |
other interface on which the capture should be done, call |
43 |
.BR pcap_create (), |
44 |
set the appropriate options on the handle, and then activate it with |
45 |
.BR pcap_activate (). |
46 |
.PP |
47 |
To obtain a list of devices that can be opened for a live capture, call |
48 |
.BR pcap_findalldevs (); |
49 |
to free the list returned by |
50 |
.BR pcap_findalldevs (), |
51 |
call |
52 |
.BR pcap_freealldevs (). |
53 |
.BR pcap_lookupdev () |
54 |
will return the first device on that list that is not a ``loopback`` |
55 |
network interface. |
56 |
.PP |
57 |
To open a handle for a ``savefile'' from which to read packets, given the |
58 |
pathname of the ``savefile'', call |
59 |
.BR pcap_open_offline (); |
60 |
to set up a handle for a ``savefile'', given a |
61 |
.B "FILE\ *" |
62 |
referring to a file already opened for reading, call |
63 |
.BR pcap_fopen_offline (). |
64 |
.PP |
65 |
In order to get a ``fake'' |
66 |
.B pcap_t |
67 |
for use in routines that require a |
68 |
.B pcap_t |
69 |
as an argument, such as routines to open a ``savefile'' for writing and |
70 |
to compile a filter expression, call |
71 |
.BR pcap_open_dead (). |
72 |
.PP |
73 |
.BR pcap_create (), |
74 |
.BR pcap_open_offline (), |
75 |
.BR pcap_fopen_offline (), |
76 |
and |
77 |
.BR pcap_open_dead () |
78 |
return a pointer to a |
79 |
.BR pcap_t , |
80 |
which is the handle used for reading packets from the capture stream or |
81 |
the ``savefile'', and for finding out information about the capture |
82 |
stream or ``savefile''. |
83 |
To close a handle, use |
84 |
.BR pcap_close (). |
85 |
.PP |
86 |
The options that can be set on a capture handle include |
87 |
.IP "snapshot length" |
88 |
If, when capturing, you capture the entire contents of the packet, that |
89 |
requires more CPU time to copy the packet to your application, more disk |
90 |
and possibly network bandwidth to write the packet data to a file, and |
91 |
more disk space to save the packet. If you don't need the entire |
92 |
contents of the packet - for example, if you are only interested in the |
93 |
TCP headers of packets - you can set the "snapshot length" for the |
94 |
capture to an appropriate value. If the snapshot length is set to |
95 |
.IR snaplen , |
96 |
and |
97 |
.I snaplen |
98 |
is less |
99 |
than the size of a packet that is captured, only the first |
100 |
.I snaplen |
101 |
bytes of that packet will be captured and provided as packet data. |
102 |
.IP |
103 |
A snapshot length of 65535 should be sufficient, on most if not all |
104 |
networks, to capture all the data available from the packet. |
105 |
.IP |
106 |
The snapshot length is set with |
107 |
.BR pcap_set_snaplen (). |
108 |
.IP "promiscuous mode" |
109 |
On broadcast LANs such as Ethernet, if the network isn't switched, or if |
110 |
the adapter is connected to a "mirror port" on a switch to which all |
111 |
packets passing through the switch are sent, a network adapter receives |
112 |
all packets on the LAN, including unicast or multicast packets not sent |
113 |
to a network address that the network adapter isn't configured to |
114 |
recognize. |
115 |
.IP |
116 |
Normally, the adapter will discard those packets; however, many network |
117 |
adapters support "promiscuous mode", which is a mode in which all |
118 |
packets, even if they are not sent to an address that the adapter |
119 |
recognizes, are provided to the host. This is useful for passively |
120 |
capturing traffic between two or more other hosts for analysis. |
121 |
.IP |
122 |
Note that even if an application does not set promiscuous mode, the |
123 |
adapter could well be in promiscuous mode for some other reason. |
124 |
.IP |
125 |
For now, this doesn't work on the "any" device; if an argument of "any" |
126 |
or NULL is supplied, the setting of promiscuous mode is ignored. |
127 |
.IP |
128 |
Promiscuous mode is set with |
129 |
.BR pcap_set_promisc (). |
130 |
.IP "monitor mode" |
131 |
On IEEE 802.11 wireless LANs, even if an adapter is in promiscuous mode, |
132 |
it will supply to the host only frames for the network with which it's |
133 |
associated. It might also supply only data frames, not management or |
134 |
control frames, and might not provide the 802.11 header or radio |
135 |
information pseudo-header for those frames. |
136 |
.IP |
137 |
In "monitor mode", sometimes also called "rfmon mode" (for "Radio |
138 |
Frequency MONitor"), the adapter will supply all frames that it |
139 |
receives, with 802.11 headers, and might supply a pseudo-header with |
140 |
radio information about the frame as well. |
141 |
.IP |
142 |
Note that in monitor mode the adapter might disassociate from the |
143 |
network with which it's associated, so that you will not be able to use |
144 |
any wireless networks with that adapter. This could prevent accessing |
145 |
files on a network server, or resolving host names or network addresses, |
146 |
if you are capturing in monitor mode and are not connected to another |
147 |
network with another adapter. |
148 |
.IP |
149 |
Monitor mode is set with |
150 |
.BR pcap_set_rfmon (), |
151 |
and |
152 |
.BR pcap_can_set_rfmon () |
153 |
can be used to determine whether an adapter can be put into monitor |
154 |
mode. |
155 |
.IP "read timeout" |
156 |
If, when capturing, packets are delivered as soon as they arrive, the |
157 |
application capturing the packets will be woken up for each packet as it |
158 |
arrives, and might have to make one or more calls to the operating |
159 |
system to fetch each packet. |
160 |
.IP |
161 |
If, instead, packets are not delivered as soon as they arrive, but are |
162 |
delivered after a short delay (called a "read timeout"), more than one |
163 |
packet can be accumulated before the packets are delivered, so that a |
164 |
single wakeup would be done for multiple packets, and each set of calls |
165 |
made to the operating system would supply multiple packets, rather than |
166 |
a single packet. This reduces the per-packet CPU overhead if packets |
167 |
are arriving at a high rate, increasing the number of packets per second |
168 |
that can be captured. |
169 |
.IP |
170 |
The read timeout is required so that an application won't wait for the |
171 |
operating system's capture buffer to fill up before packets are |
172 |
delivered; if packets are arriving slowly, that wait could take an |
173 |
arbitrarily long period of time. |
174 |
.IP |
175 |
Not all platforms support a read timeout; on platforms that |
176 |
don't, the read timeout is ignored. A zero value for the timeout, |
177 |
on platforms that support a read timeout, |
178 |
will cause a read to wait forever to allow enough packets to |
179 |
arrive, with no timeout. |
180 |
.IP |
181 |
.BR NOTE : |
182 |
the read timeout cannot be used to cause calls that read |
183 |
packets to return within a limited period of time, because, on some |
184 |
platforms, the read timeout isn't supported, and, on other platforms, |
185 |
the timer doesn't start until at least one packet arrives. This means |
186 |
that the read timeout should |
187 |
.B NOT |
188 |
be used, for example, in an interactive application to allow the packet |
189 |
capture loop to ``poll'' for user input periodically, as there's no |
190 |
guarantee that a call reading packets will return after the timeout |
191 |
expires even if no packets have arrived. |
192 |
.IP |
193 |
The read timeout is set with |
194 |
.BR pcap_set_timeout (). |
195 |
.IP "buffer size" |
196 |
Packets that arrive for a capture are stored in a buffer, so that they |
197 |
do not have to be read by the application as soon as they arrive. On |
198 |
some platforms, the buffer's size can be set; a size that's too small |
199 |
could mean that, if too many packets are being captured and the snapshot |
200 |
length doesn't limit the amount of data that's buffered, packets could |
201 |
be dropped if the buffer fills up before the application can read |
202 |
packets from it, while a size that's too large could use more |
203 |
non-pageable operating system memory than is necessary to prevent |
204 |
packets from being dropped. |
205 |
.IP |
206 |
The buffer size is set with |
207 |
.BR pcap_set_buffer_size (). |
208 |
.IP "timestamp type" |
209 |
On some platforms, the time stamp given to packets on live captures can |
210 |
come from different sources that can have different resolutions or that |
211 |
can have different relationships to the time values for the current time |
212 |
supplied by routines on the native operating system. See |
213 |
.BR pcap-tstamp (@MAN_MISC_INFO@) |
214 |
for a list of time stamp types. |
215 |
.IP |
216 |
The time stamp type is set with |
217 |
.BR pcap_set_tstamp_type (). |
218 |
.PP |
219 |
Reading packets from a network interface may require that you have |
220 |
special privileges: |
221 |
.TP |
222 |
.B Under SunOS 3.x or 4.x with NIT or BPF: |
223 |
You must have read access to |
224 |
.I /dev/nit |
225 |
or |
226 |
.IR /dev/bpf* . |
227 |
.TP |
228 |
.B Under Solaris with DLPI: |
229 |
You must have read/write access to the network pseudo device, e.g. |
230 |
.IR /dev/le . |
231 |
On at least some versions of Solaris, however, this is not sufficient to |
232 |
allow |
233 |
.I tcpdump |
234 |
to capture in promiscuous mode; on those versions of Solaris, you must |
235 |
be root, or the application capturing packets |
236 |
must be installed setuid to root, in order to capture in promiscuous |
237 |
mode. Note that, on many (perhaps all) interfaces, if you don't capture |
238 |
in promiscuous mode, you will not see any outgoing packets, so a capture |
239 |
not done in promiscuous mode may not be very useful. |
240 |
.IP |
241 |
In newer versions of Solaris, you must have been given the |
242 |
.B net_rawaccess |
243 |
privilege; this is both necessary and sufficient to give you access to the |
244 |
network pseudo-device - there is no need to change the privileges on |
245 |
that device. A user can be given that privilege by, for example, adding |
246 |
that privilege to the user's |
247 |
.B defaultpriv |
248 |
key with the |
249 |
.B usermod (1M) |
250 |
command. |
251 |
.TP |
252 |
.B Under HP-UX with DLPI: |
253 |
You must be root or the application capturing packets must be installed |
254 |
setuid to root. |
255 |
.TP |
256 |
.B Under IRIX with snoop: |
257 |
You must be root or the application capturing packets must be installed |
258 |
setuid to root. |
259 |
.TP |
260 |
.B Under Linux: |
261 |
You must be root or the application capturing packets must be installed |
262 |
setuid to root (unless your distribution has a kernel |
263 |
that supports capability bits such as CAP_NET_RAW and code to allow |
264 |
those capability bits to be given to particular accounts and to cause |
265 |
those bits to be set on a user's initial processes when they log in, in |
266 |
which case you must have CAP_NET_RAW in order to capture and |
267 |
CAP_NET_ADMIN to enumerate network devices with, for example, the |
268 |
.B \-D |
269 |
flag). |
270 |
.TP |
271 |
.B Under ULTRIX and Digital UNIX/Tru64 UNIX: |
272 |
Any user may capture network traffic. |
273 |
However, no user (not even the super-user) can capture in promiscuous |
274 |
mode on an interface unless the super-user has enabled promiscuous-mode |
275 |
operation on that interface using |
276 |
.IR pfconfig (8), |
277 |
and no user (not even the super-user) can capture unicast traffic |
278 |
received by or sent by the machine on an interface unless the super-user |
279 |
has enabled copy-all-mode operation on that interface using |
280 |
.IR pfconfig , |
281 |
so |
282 |
.I useful |
283 |
packet capture on an interface probably requires that either |
284 |
promiscuous-mode or copy-all-mode operation, or both modes of |
285 |
operation, be enabled on that interface. |
286 |
.TP |
287 |
.B Under BSD (this includes Mac OS X): |
288 |
You must have read access to |
289 |
.I /dev/bpf* |
290 |
on systems that don't have a cloning BPF device, or to |
291 |
.I /dev/bpf |
292 |
on systems that do. |
293 |
On BSDs with a devfs (this includes Mac OS X), this might involve more |
294 |
than just having somebody with super-user access setting the ownership |
295 |
or permissions on the BPF devices - it might involve configuring devfs |
296 |
to set the ownership or permissions every time the system is booted, |
297 |
if the system even supports that; if it doesn't support that, you might |
298 |
have to find some other way to make that happen at boot time. |
299 |
.PP |
300 |
Reading a saved packet file doesn't require special privileges. |
301 |
.PP |
302 |
The packets read from the handle may include a ``pseudo-header'' |
303 |
containing various forms of packet meta-data, and probably includes a |
304 |
link-layer header whose contents can differ for different network |
305 |
interfaces. To determine the format of the packets supplied by the |
306 |
handle, call |
307 |
.BR pcap_datalink (); |
308 |
.I http://www.tcpdump.org/linktypes.html |
309 |
lists the values it returns and describes the packet formats that |
310 |
correspond to those values. |
311 |
.PP |
312 |
To obtain the |
313 |
.B "FILE\ *" |
314 |
corresponding to a |
315 |
.B pcap_t |
316 |
opened for a ``savefile'', call |
317 |
.BR pcap_file (). |
318 |
.TP |
319 |
.B Routines |
320 |
.RS |
321 |
.TP |
322 |
.BR pcap_create (3PCAP) |
323 |
get a |
324 |
.B pcap_t |
325 |
for live capture |
326 |
.TP |
327 |
.BR pcap_activate (3PCAP) |
328 |
activate a |
329 |
.B pcap_t |
330 |
for live capture |
331 |
.TP |
332 |
.BR pcap_findalldevs (3PCAP) |
333 |
get a list of devices that can be opened for a live capture |
334 |
.TP |
335 |
.BR pcap_freealldevs (3PCAP) |
336 |
free list of devices |
337 |
.TP |
338 |
.BR pcap_lookupdev (3PCAP) |
339 |
get first non-loopback device on that list |
340 |
.TP |
341 |
.BR pcap_open_offline (3PCAP) |
342 |
open a |
343 |
.B pcap_t |
344 |
for a ``savefile'', given a pathname |
345 |
.TP |
346 |
.BR pcap_fopen_offline (3PCAP) |
347 |
open a |
348 |
.B pcap_t |
349 |
for a ``savefile'', given a |
350 |
.B "FILE\ *" |
351 |
.TP |
352 |
.BR pcap_open_dead (3PCAP) |
353 |
create a ``fake'' |
354 |
.B pcap_t |
355 |
.TP |
356 |
.BR pcap_close (3PCAP) |
357 |
close a |
358 |
.B pcap_t |
359 |
.TP |
360 |
.BR pcap_set_snaplen (3PCAP) |
361 |
set the snapshot length for a not-yet-activated |
362 |
.B pcap_t |
363 |
for live capture |
364 |
.TP |
365 |
.BR pcap_snapshot (3PCAP) |
366 |
get the snapshot length for a |
367 |
.B pcap_t |
368 |
.TP |
369 |
.BR pcap_set_promisc (3PCAP) |
370 |
set promiscuous mode for a not-yet-activated |
371 |
.B pcap_t |
372 |
for live capture |
373 |
.TP |
374 |
.BR pcap_set_rfmon (3PCAP) |
375 |
set monitor mode for a not-yet-activated |
376 |
.B pcap_t |
377 |
for live capture |
378 |
.TP |
379 |
.BR pcap_can_set_rfmon (3PCAP) |
380 |
determine whether monitor mode can be set for a |
381 |
.B pcap_t |
382 |
for live capture |
383 |
.TP |
384 |
.BR pcap_set_timeout (3PCAP) |
385 |
set read timeout for a not-yet-activated |
386 |
.B pcap_t |
387 |
for live capture |
388 |
.TP |
389 |
.BR pcap_set_buffer_size (3PCAP) |
390 |
set buffer size for a not-yet-activated |
391 |
.B pcap_t |
392 |
for live capture |
393 |
.TP |
394 |
.BR pcap_set_tstamp_type (3PCAP) |
395 |
set time stamp type for a not-yet-activated |
396 |
.B pcap_t |
397 |
for live capture |
398 |
.TP |
399 |
.BR pcap_list_tstamp_types (3PCAP) |
400 |
get list of available time stamp types for a not-yet-activated |
401 |
.B pcap_t |
402 |
for live capture |
403 |
.TP |
404 |
.BR pcap_free_tstamp_types (3PCAP) |
405 |
free list of available time stamp types |
406 |
.TP |
407 |
.BR pcap_tstamp_type_val_to_name (3PCAP) |
408 |
get name for a time stamp type |
409 |
.TP |
410 |
.BR pcap_tstamp_type_val_to_description (3PCAP) |
411 |
get description for a time stamp type |
412 |
.TP |
413 |
.BR pcap_tstamp_name_to_val (3PCAP) |
414 |
get time stamp type corresponding to a name |
415 |
.TP |
416 |
.BR pcap_datalink (3PCAP) |
417 |
get link-layer header type for a |
418 |
.B pcap_t |
419 |
.TP |
420 |
.BR pcap_file (3PCAP) |
421 |
get the |
422 |
.B "FILE\ *" |
423 |
for a |
424 |
.B pcap_t |
425 |
opened for a ``savefile'' |
426 |
.TP |
427 |
.BR pcap_is_swapped (3PCAP) |
428 |
determine whether a ``savefile'' being read came from a machine with the |
429 |
opposite byte order |
430 |
.TP |
431 |
.BR pcap_major_version (3PCAP) |
432 |
.PD 0 |
433 |
.TP |
434 |
.BR pcap_minor_version (3PCAP) |
435 |
get the major and minor version of the file format version for a |
436 |
``savefile'' |
437 |
.PD |
438 |
.RE |
439 |
.SS Selecting a link-layer header type for a live capture |
440 |
Some devices may provide more than one link-layer header type. To |
441 |
obtain a list of all link-layer header types provided by a device, call |
442 |
.BR pcap_list_datalinks () |
443 |
on an activated |
444 |
.B pcap_t |
445 |
for the device. |
446 |
To free a list of link-layer header types, call |
447 |
.BR pcap_free_datalinks (). |
448 |
To set the link-layer header type for a device, call |
449 |
.BR pcap_set_datalink (). |
450 |
This should be done after the device has been activated but before any |
451 |
packets are read and before any filters are compiled or installed. |
452 |
.TP |
453 |
.B Routines |
454 |
.RS |
455 |
.TP |
456 |
.BR pcap_list_datalinks (3PCAP) |
457 |
get a list of link-layer header types for a device |
458 |
.TP |
459 |
.BR pcap_free_datalinks (3PCAP) |
460 |
free list of link-layer header types |
461 |
.TP |
462 |
.BR pcap_set_datalink (3PCAP) |
463 |
set link-layer header type for a device |
464 |
.TP |
465 |
.BR pcap_datalink_val_to_name (3PCAP) |
466 |
get name for a link-layer header type |
467 |
.TP |
468 |
.BR pcap_datalink_val_to_description (3PCAP) |
469 |
get description for a link-layer header type |
470 |
.TP |
471 |
.BR pcap_datalink_name_to_val (3PCAP) |
472 |
get link-layer header type corresponding to a name |
473 |
.RE |
474 |
.SS Reading packets |
475 |
Packets are read with |
476 |
.BR pcap_dispatch () |
477 |
or |
478 |
.BR pcap_loop (), |
479 |
which process one or more packets, calling a callback routine for each |
480 |
packet, or with |
481 |
.BR pcap_next () |
482 |
or |
483 |
.BR pcap_next_ex (), |
484 |
which return the next packet. |
485 |
The callback for |
486 |
.BR pcap_dispatch () |
487 |
and |
488 |
.BR pcap_loop () |
489 |
is supplied a pointer to a |
490 |
.IR "struct pcap_pkthdr" , |
491 |
which includes the following members: |
492 |
.RS |
493 |
.TP |
494 |
.B ts |
495 |
a |
496 |
.I struct timeval |
497 |
containing the time when the packet was captured |
498 |
.TP |
499 |
.B caplen |
500 |
a |
501 |
.I bpf_u_int32 |
502 |
giving the number of bytes of the packet that are available from the |
503 |
capture |
504 |
.TP |
505 |
.B len |
506 |
a |
507 |
.I bpf_u_int32 |
508 |
giving the length of the packet, in bytes (which might be more than the |
509 |
number of bytes available from the capture, if the length of the packet |
510 |
is larger than the maximum number of bytes to capture). |
511 |
.RE |
512 |
.PP |
513 |
.BR pcap_next_ex () |
514 |
supplies that pointer through a pointer argument. |
515 |
.BR pcap_next () |
516 |
is passed an argument that points to a |
517 |
.I struct pcap_pkthdr |
518 |
structure, and fills it in. |
519 |
.PP |
520 |
The callback is also supplied a |
521 |
.I const u_char |
522 |
pointer to the first |
523 |
.B caplen |
524 |
(as given in the |
525 |
.I struct pcap_pkthdr |
526 |
a pointer to which is passed to the callback routine) |
527 |
bytes of data from the packet. This won't necessarily be the entire |
528 |
packet; to capture the entire packet, you will have to provide a value |
529 |
for |
530 |
.I snaplen |
531 |
in your call to |
532 |
.BR pcap_set_snaplen () |
533 |
that is sufficiently large to get all of the packet's data - a value of |
534 |
65535 should be sufficient on most if not all networks). When reading |
535 |
from a ``savefile'', the snapshot length specified when the capture was |
536 |
performed will limit the amount of packet data available. |
537 |
.BR pcap_next () |
538 |
returns that pointer; |
539 |
.BR pcap_next_ex () |
540 |
supplies that pointer through a pointer argument. |
541 |
.PP |
542 |
To force the loop in |
543 |
.BR pcap_dispatch () |
544 |
or |
545 |
.BR pcap_loop () |
546 |
to terminate, call |
547 |
.BR pcap_breakloop (). |
548 |
.PP |
549 |
By default, when reading packets from an interface opened for a live |
550 |
capture, |
551 |
.BR pcap_dispatch (), |
552 |
.BR pcap_next (), |
553 |
and |
554 |
.BR pcap_next_ex () |
555 |
will, if no packets are currently available to be read, block waiting |
556 |
for packets to become available. On some, but |
557 |
.I not |
558 |
all, platforms, if a read timeout was specified, the wait will terminate |
559 |
after the read timeout expires; applications should be prepared for |
560 |
this, as it happens on some platforms, but should not rely on it, as it |
561 |
does not happen on other platforms. |
562 |
.PP |
563 |
A handle can be put into ``non-blocking mode'', so that those routines |
564 |
will, rather than blocking, return an indication that no packets are |
565 |
available to read. Call |
566 |
.BR pcap_setnonblock () |
567 |
to put a handle into non-blocking mode or to take it out of non-blocking |
568 |
mode; call |
569 |
.BR pcap_getnonblock () |
570 |
to determine whether a handle is in non-blocking mode. Note that |
571 |
non-blocking mode does not work correctly in Mac OS X 10.6. |
572 |
.PP |
573 |
Non-blocking mode is often combined with routines such as |
574 |
.BR select (2) |
575 |
or |
576 |
.BR poll (2) |
577 |
or other routines a platform offers to wait for the availability of data |
578 |
on any of a set of descriptors. To obtain, for a handle, a descriptor |
579 |
that can be used in those routines, call |
580 |
.BR pcap_get_selectable_fd (). |
581 |
Not all handles have such a descriptor available; |
582 |
.BR pcap_get_selectable_fd () |
583 |
will return \-1 if no such descriptor exists. In addition, for various |
584 |
reasons, one or more of those routines will not work properly with the |
585 |
descriptor; the documentation for |
586 |
.BR pcap_get_selectable_fd () |
587 |
gives details. |
588 |
.TP |
589 |
.B Routines |
590 |
.RS |
591 |
.TP |
592 |
.BR pcap_dispatch (3PCAP) |
593 |
read a bufferful of packets from a |
594 |
.B pcap_t |
595 |
open for a live capture or the full set of packets from a |
596 |
.B pcap_t |
597 |
open for a ``savefile'' |
598 |
.TP |
599 |
.BR pcap_loop (3PCAP) |
600 |
read packets from a |
601 |
.B pcap_t |
602 |
until an interrupt or error occurs |
603 |
.TP |
604 |
.BR pcap_next (3PCAP) |
605 |
read the next packet from a |
606 |
.B pcap_t |
607 |
without an indication whether an error occurred |
608 |
.TP |
609 |
.BR pcap_next_ex (3PCAP) |
610 |
read the next packet from a |
611 |
.B pcap_t |
612 |
with an error indication on an error |
613 |
.TP |
614 |
.BR pcap_breakloop (3PCAP) |
615 |
prematurely terminate the loop in |
616 |
.BR pcap_dispatch () |
617 |
or |
618 |
.BR pcap_loop () |
619 |
.TP |
620 |
.BR pcap_setnonblock (3PCAP) |
621 |
set or clear non-blocking mode on a |
622 |
.B pcap_t |
623 |
.TP |
624 |
.BR pcap_getnonblock (3PCAP) |
625 |
get the state of non-blocking mode for a |
626 |
.B pcap_t |
627 |
.TP |
628 |
.BR pcap_get_selectable_fd (3PCAP) |
629 |
attempt to get a descriptor for a |
630 |
.B pcap_t |
631 |
that can be used in calls such as |
632 |
.BR select (2) |
633 |
and |
634 |
.BR poll (2) |
635 |
.RE |
636 |
.SS Filters |
637 |
In order to cause only certain packets to be returned when reading |
638 |
packets, a filter can be set on a handle. For a live capture, the |
639 |
filtering will be performed in kernel mode, if possible, to avoid |
640 |
copying ``uninteresting'' packets from the kernel to user mode. |
641 |
.PP |
642 |
A filter can be specified as a text string; the syntax and semantics of |
643 |
the string are as described by |
644 |
.BR pcap-filter (@MAN_MISC_INFO@). |
645 |
A filter string is compiled into a program in a pseudo-machine-language |
646 |
by |
647 |
.BR pcap_compile () |
648 |
and the resulting program can be made a filter for a handle with |
649 |
.BR pcap_setfilter (). |
650 |
The result of |
651 |
.BR pcap_compile () |
652 |
can be freed with a call to |
653 |
.BR pcap_freecode (). |
654 |
.BR pcap_compile () |
655 |
may require a network mask for certain expressions in the filter string; |
656 |
.BR pcap_lookupnet () |
657 |
can be used to find the network address and network mask for a given |
658 |
capture device. |
659 |
.PP |
660 |
A compiled filter can also be applied directly to a packet that has been |
661 |
read using |
662 |
.BR pcap_offline_filter (). |
663 |
.TP |
664 |
.B Routines |
665 |
.RS |
666 |
.TP |
667 |
.BR pcap_compile (3PCAP) |
668 |
compile filter expression to a pseudo-machine-language code program |
669 |
.TP |
670 |
.BR pcap_freecode (3PCAP) |
671 |
free a filter program |
672 |
.TP |
673 |
.BR pcap_setfilter (3PCAP) |
674 |
set filter for a |
675 |
.B pcap_t |
676 |
.TP |
677 |
.BR pcap_lookupnet (3PCAP) |
678 |
get network address and network mask for a capture device |
679 |
.TP |
680 |
.BR pcap_offline_filter (3PCAP) |
681 |
apply a filter program to a packet |
682 |
.RE |
683 |
.SS Incoming and outgoing packets |
684 |
By default, libpcap will attempt to capture both packets sent by the |
685 |
machine and packets received by the machine. To limit it to capturing |
686 |
only packets received by the machine or, if possible, only packets sent |
687 |
by the machine, call |
688 |
.BR pcap_setdirection (). |
689 |
.TP |
690 |
.BR Routines |
691 |
.RS |
692 |
.TP |
693 |
.BR pcap_setdirection (3PCAP) |
694 |
specify whether to capture incoming packets, outgoing packets, or both |
695 |
.RE |
696 |
.SS Capture statistics |
697 |
To get statistics about packets received and dropped in a live capture, |
698 |
call |
699 |
.BR pcap_stats (). |
700 |
.TP |
701 |
.B Routines |
702 |
.RS |
703 |
.TP |
704 |
.BR pcap_stats (3PCAP) |
705 |
get capture statistics |
706 |
.RE |
707 |
.SS Opening a handle for writing captured packets |
708 |
To open a ``savefile`` to which to write packets, given the pathname the |
709 |
``savefile'' should have, call |
710 |
.BR pcap_dump_open (). |
711 |
To open a ``savefile`` to which to write packets, given the pathname the |
712 |
``savefile'' should have, call |
713 |
.BR pcap_dump_open (); |
714 |
to set up a handle for a ``savefile'', given a |
715 |
.B "FILE\ *" |
716 |
referring to a file already opened for writing, call |
717 |
.BR pcap_dump_fopen (). |
718 |
They each return pointers to a |
719 |
.BR pcap_dumper_t , |
720 |
which is the handle used for writing packets to the ``savefile''. If it |
721 |
succeeds, it will have created the file if it doesn't exist and |
722 |
truncated the file if it does exist. |
723 |
To close a |
724 |
.BR pcap_dumper_t , |
725 |
call |
726 |
.BR pcap_dump_close (). |
727 |
.TP |
728 |
.B Routines |
729 |
.RS |
730 |
.TP |
731 |
.BR pcap_dump_open (3PCAP) |
732 |
open a |
733 |
.B pcap_dumper_t |
734 |
for a ``savefile``, given a pathname |
735 |
.TP |
736 |
.BR pcap_dump_fopen (3PCAP) |
737 |
open a |
738 |
.B pcap_dumper_t |
739 |
for a ``savefile``, given a |
740 |
.B "FILE\ *" |
741 |
.TP |
742 |
.BR pcap_dump_close (3PCAP) |
743 |
close a |
744 |
.B pcap_dumper_t |
745 |
.TP |
746 |
.BR pcap_dump_file (3PCAP) |
747 |
get the |
748 |
.B "FILE\ *" |
749 |
for a |
750 |
.B pcap_dumper_t |
751 |
opened for a ``savefile'' |
752 |
.RE |
753 |
.SS Writing packets |
754 |
To write a packet to a |
755 |
.BR pcap_dumper_t , |
756 |
call |
757 |
.BR pcap_dump (). |
758 |
Packets written with |
759 |
.BR pcap_dump () |
760 |
may be buffered, rather than being immediately written to the |
761 |
``savefile''. Closing the |
762 |
.B pcap_dumper_t |
763 |
will cause all buffered-but-not-yet-written packets to be written to the |
764 |
``savefile''. |
765 |
To force all packets written to the |
766 |
.BR pcap_dumper_t , |
767 |
and not yet written to the ``savefile'' because they're buffered by the |
768 |
.BR pcap_dumper_t , |
769 |
to be written to the ``savefile'', without closing the |
770 |
.BR pcap_dumper_t , |
771 |
call |
772 |
.BR pcap_dump_flush (). |
773 |
.TP |
774 |
.B Routines |
775 |
.RS |
776 |
.TP |
777 |
.BR pcap_dump (3PCAP) |
778 |
write packet to a |
779 |
.B pcap_dumper_t |
780 |
.TP |
781 |
.BR pcap_dump_flush (3PCAP) |
782 |
flush buffered packets written to a |
783 |
.B pcap_dumper_t |
784 |
to the ``savefile'' |
785 |
.TP |
786 |
.BR pcap_dump_ftell (3PCAP) |
787 |
get current file position for a |
788 |
.B pcap_dumper_t |
789 |
.RE |
790 |
.SS Injecting packets |
791 |
If you have the required privileges, you can inject packets onto a |
792 |
network with a |
793 |
.B pcap_t |
794 |
for a live capture, using |
795 |
.BR pcap_inject () |
796 |
or |
797 |
.BR pcap_sendpacket (). |
798 |
(The two routines exist for compatibility with both OpenBSD and WinPcap; |
799 |
they perform the same function, but have different return values.) |
800 |
.TP |
801 |
.B Routines |
802 |
.RS |
803 |
.TP |
804 |
.BR pcap_inject (3PCAP) |
805 |
.PD 0 |
806 |
.TP |
807 |
.BR pcap_sendpacket (3PCAP) |
808 |
transmit a packet |
809 |
.PD |
810 |
.RE |
811 |
.SS Reporting errors |
812 |
Some routines return error or warning status codes; to convert them to a |
813 |
string, use |
814 |
.BR pcap_statustostr (). |
815 |
.TP |
816 |
.B Routines |
817 |
.RS |
818 |
.TP |
819 |
.BR pcap_statustostr (3PCAP) |
820 |
get a string for an error or warning status code |
821 |
.RE |
822 |
.SS Getting library version information |
823 |
To get a string giving version information about libpcap, call |
824 |
.BR pcap_library_version (). |
825 |
.TP |
826 |
.B Routines |
827 |
.RS |
828 |
.TP |
829 |
.BR pcap_library_version (3PCAP) |
830 |
get library version string |
831 |
.RE |
832 |
.SH BACKWARDS COMPATIBILITY |
833 |
.PP |
834 |
In versions of libpcap prior to 1.0, the |
835 |
.B pcap.h |
836 |
header file was not in a |
837 |
.B pcap |
838 |
directory on most platforms; if you are writing an application that must |
839 |
work on versions of libpcap prior to 1.0, include |
840 |
.BR <pcap.h> , |
841 |
which will include |
842 |
.B <pcap/pcap.h> |
843 |
for you, rather than including |
844 |
.BR <pcap/pcap.h> . |
845 |
.PP |
846 |
.BR pcap_create () |
847 |
and |
848 |
.BR pcap_activate () |
849 |
were not available in versions of libpcap prior to 1.0; if you are |
850 |
writing an application that must work on versions of libpcap prior to |
851 |
1.0, either use |
852 |
.BR pcap_open_live () |
853 |
to get a handle for a live capture or, if you want to be able to use the |
854 |
additional capabilities offered by using |
855 |
.BR pcap_create () |
856 |
and |
857 |
.BR pcap_activate (), |
858 |
use an |
859 |
.BR autoconf (1) |
860 |
script or some other configuration script to check whether the libpcap |
861 |
1.0 APIs are available and use them only if they are. |
862 |
.SH SEE ALSO |
863 |
autoconf(1), tcpdump(1), tcpslice(1), pcap-filter(@MAN_MISC_INFO@), pfconfig(8), |
864 |
usermod(1M) |
865 |
.SH AUTHORS |
866 |
The original authors of libpcap are: |
867 |
.LP |
868 |
Van Jacobson, |
869 |
Craig Leres and |
870 |
Steven McCanne, all of the |
871 |
Lawrence Berkeley National Laboratory, University of California, Berkeley, CA. |
872 |
.LP |
873 |
The current version is available from "The Tcpdump Group"'s Web site at |
874 |
.LP |
875 |
.RS |
876 |
.I http://www.tcpdump.org/ |
877 |
.RE |
878 |
.SH BUGS |
879 |
Please send problems, bugs, questions, desirable enhancements, etc. to: |
880 |
.LP |
881 |
.RS |
882 |
tcpdump-workers@lists.tcpdump.org |
883 |
.RE |