1 .\" @(#) $Header: /tcpdump/master/libpcap/pcap.3pcap.in,v 1.1 2008-10-21 07:33:01 guy Exp $
3 .\" Copyright (c) 1994, 1996, 1997
4 .\" The Regents of the University of California. All rights reserved.
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.
22 .TH PCAP 3PCAP "4 April 2008"
24 pcap \- Packet Capture library
28 #include <pcap/pcap.h>
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
44 set the appropriate options on the handle, and then activate it with
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 (),
52 .BR pcap_freealldevs ().
54 will return the first device on that list that is not a ``loopback``
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
62 referring to a file already opened for reading, call
63 .BR pcap_fopen_offline ().
65 In order to get a ``fake''
67 for use in routines that require a
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 ().
74 .BR pcap_open_offline (),
75 .BR pcap_fopen_offline (),
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
86 The options that can be set on a capture handle include
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
99 than the size of a packet that is captured, only the first
101 bytes of that packet will be captured and provided as packet data.
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.
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
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.
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.
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.
128 Promiscuous mode is set with
129 .BR pcap_set_promisc ().
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.
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.
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.
149 Monitor mode is set with
150 .BR pcap_set_rfmon (),
152 .BR pcap_can_set_rfmon ()
153 can be used to determine whether an adapter can be put into monitor
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.
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.
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.
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.
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
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.
193 The read timeout is set with
194 .BR pcap_set_timeout ().
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.
206 The buffer size is set with
207 .BR pcap_set_buffer_size ().
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.
216 The time stamp type is set with
217 .BR pcap_set_tstamp_type ().
219 Reading packets from a network interface may require that you have
222 .B Under SunOS 3.x or 4.x with NIT or BPF:
223 You must have read access to
228 .B Under Solaris with DLPI:
229 You must have read/write access to the network pseudo device, e.g.
231 On at least some versions of Solaris, however, this is not sufficient to
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.
241 In newer versions of Solaris, you must have been given the
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
252 .B Under HP-UX with DLPI:
253 You must be root or the application capturing packets must be installed
256 .B Under IRIX with snoop:
257 You must be root or the application capturing packets must be installed
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
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
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
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.
287 .B Under BSD (this includes Mac OS X):
288 You must have read access to
290 on systems that don't have a cloning BPF device, or to
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.
300 Reading a saved packet file doesn't require special privileges.
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
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.
316 opened for a ``savefile'', call
322 .BR pcap_create (3PCAP)
327 .BR pcap_activate (3PCAP)
332 .BR pcap_findalldevs (3PCAP)
333 get a list of devices that can be opened for a live capture
335 .BR pcap_freealldevs (3PCAP)
338 .BR pcap_lookupdev (3PCAP)
339 get first non-loopback device on that list
341 .BR pcap_open_offline (3PCAP)
344 for a ``savefile'', given a pathname
346 .BR pcap_fopen_offline (3PCAP)
349 for a ``savefile'', given a
352 .BR pcap_open_dead (3PCAP)
356 .BR pcap_close (3PCAP)
360 .BR pcap_set_snaplen (3PCAP)
361 set the snapshot length for a not-yet-activated
365 .BR pcap_snapshot (3PCAP)
366 get the snapshot length for a
369 .BR pcap_set_promisc (3PCAP)
370 set promiscuous mode for a not-yet-activated
374 .BR pcap_set_rfmon (3PCAP)
375 set monitor mode for a not-yet-activated
379 .BR pcap_can_set_rfmon (3PCAP)
380 determine whether monitor mode can be set for a
384 .BR pcap_set_timeout (3PCAP)
385 set read timeout for a not-yet-activated
389 .BR pcap_set_buffer_size (3PCAP)
390 set buffer size for a not-yet-activated
394 .BR pcap_set_tstamp_type (3PCAP)
395 set time stamp type for a not-yet-activated
399 .BR pcap_list_tstamp_types (3PCAP)
400 get list of available time stamp types for a not-yet-activated
404 .BR pcap_free_tstamp_types (3PCAP)
405 free list of available time stamp types
407 .BR pcap_tstamp_type_val_to_name (3PCAP)
408 get name for a time stamp type
410 .BR pcap_tstamp_type_val_to_description (3PCAP)
411 get description for a time stamp type
413 .BR pcap_tstamp_name_to_val (3PCAP)
414 get time stamp type corresponding to a name
416 .BR pcap_datalink (3PCAP)
417 get link-layer header type for a
420 .BR pcap_file (3PCAP)
425 opened for a ``savefile''
427 .BR pcap_is_swapped (3PCAP)
428 determine whether a ``savefile'' being read came from a machine with the
431 .BR pcap_major_version (3PCAP)
434 .BR pcap_minor_version (3PCAP)
435 get the major and minor version of the file format version for a
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 ()
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.
456 .BR pcap_list_datalinks (3PCAP)
457 get a list of link-layer header types for a device
459 .BR pcap_free_datalinks (3PCAP)
460 free list of link-layer header types
462 .BR pcap_set_datalink (3PCAP)
463 set link-layer header type for a device
465 .BR pcap_datalink_val_to_name (3PCAP)
466 get name for a link-layer header type
468 .BR pcap_datalink_val_to_description (3PCAP)
469 get description for a link-layer header type
471 .BR pcap_datalink_name_to_val (3PCAP)
472 get link-layer header type corresponding to a name
475 Packets are read with
479 which process one or more packets, calling a callback routine for each
484 which return the next packet.
489 is supplied a pointer to a
490 .IR "struct pcap_pkthdr" ,
491 which includes the following members:
497 containing the time when the packet was captured
502 giving the number of bytes of the packet that are available from the
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).
514 supplies that pointer through a pointer argument.
516 is passed an argument that points to a
517 .I struct pcap_pkthdr
518 structure, and fills it in.
520 The callback is also supplied a
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
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.
538 returns that pointer;
540 supplies that pointer through a pointer argument.
547 .BR pcap_breakloop ().
549 By default, when reading packets from an interface opened for a live
551 .BR pcap_dispatch (),
555 will, if no packets are currently available to be read, block waiting
556 for packets to become available. On some, but
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.
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
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.
573 Non-blocking mode is often combined with routines such as
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 ()
592 .BR pcap_dispatch (3PCAP)
593 read a bufferful of packets from a
595 open for a live capture or the full set of packets from a
597 open for a ``savefile''
599 .BR pcap_loop (3PCAP)
602 until an interrupt or error occurs
604 .BR pcap_next (3PCAP)
605 read the next packet from a
607 without an indication whether an error occurred
609 .BR pcap_next_ex (3PCAP)
610 read the next packet from a
612 with an error indication on an error
614 .BR pcap_breakloop (3PCAP)
615 prematurely terminate the loop in
620 .BR pcap_setnonblock (3PCAP)
621 set or clear non-blocking mode on a
624 .BR pcap_getnonblock (3PCAP)
625 get the state of non-blocking mode for a
628 .BR pcap_get_selectable_fd (3PCAP)
629 attempt to get a descriptor for a
631 that can be used in calls such as
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.
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
648 and the resulting program can be made a filter for a handle with
649 .BR pcap_setfilter ().
652 can be freed with a call to
653 .BR pcap_freecode ().
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
660 A compiled filter can also be applied directly to a packet that has been
662 .BR pcap_offline_filter ().
667 .BR pcap_compile (3PCAP)
668 compile filter expression to a pseudo-machine-language code program
670 .BR pcap_freecode (3PCAP)
671 free a filter program
673 .BR pcap_setfilter (3PCAP)
677 .BR pcap_lookupnet (3PCAP)
678 get network address and network mask for a capture device
680 .BR pcap_offline_filter (3PCAP)
681 apply a filter program to a packet
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
688 .BR pcap_setdirection ().
693 .BR pcap_setdirection (3PCAP)
694 specify whether to capture incoming packets, outgoing packets, or both
696 .SS Capture statistics
697 To get statistics about packets received and dropped in a live capture,
704 .BR pcap_stats (3PCAP)
705 get capture statistics
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
716 referring to a file already opened for writing, call
717 .BR pcap_dump_fopen ().
718 They each return pointers to a
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.
726 .BR pcap_dump_close ().
731 .BR pcap_dump_open (3PCAP)
734 for a ``savefile``, given a pathname
736 .BR pcap_dump_fopen (3PCAP)
739 for a ``savefile``, given a
742 .BR pcap_dump_close (3PCAP)
746 .BR pcap_dump_file (3PCAP)
751 opened for a ``savefile''
754 To write a packet to a
760 may be buffered, rather than being immediately written to the
761 ``savefile''. Closing the
763 will cause all buffered-but-not-yet-written packets to be written to the
765 To force all packets written to the
767 and not yet written to the ``savefile'' because they're buffered by the
769 to be written to the ``savefile'', without closing the
772 .BR pcap_dump_flush ().
777 .BR pcap_dump (3PCAP)
781 .BR pcap_dump_flush (3PCAP)
782 flush buffered packets written to a
786 .BR pcap_dump_ftell (3PCAP)
787 get current file position for a
790 .SS Injecting packets
791 If you have the required privileges, you can inject packets onto a
794 for a live capture, using
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.)
804 .BR pcap_inject (3PCAP)
807 .BR pcap_sendpacket (3PCAP)
812 Some routines return error or warning status codes; to convert them to a
814 .BR pcap_statustostr ().
819 .BR pcap_statustostr (3PCAP)
820 get a string for an error or warning status code
822 .SS Getting library version information
823 To get a string giving version information about libpcap, call
824 .BR pcap_library_version ().
829 .BR pcap_library_version (3PCAP)
830 get library version string
832 .SH BACKWARDS COMPATIBILITY
834 In versions of libpcap prior to 1.0, the
836 header file was not in a
838 directory on most platforms; if you are writing an application that must
839 work on versions of libpcap prior to 1.0, include
843 for you, rather than including
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
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
857 .BR pcap_activate (),
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.
863 autoconf(1), tcpdump(1), tcpslice(1), pcap-filter(@MAN_MISC_INFO@), pfconfig(8),
866 The original authors of libpcap are:
870 Steven McCanne, all of the
871 Lawrence Berkeley National Laboratory, University of California, Berkeley, CA.
873 The current version is available from "The Tcpdump Group"'s Web site at
876 .I http://www.tcpdump.org/
879 Please send problems, bugs, questions, desirable enhancements, etc. to:
882 tcpdump-workers@lists.tcpdump.org
projects / dragonfly.git / blob