1 .\" @(#) $Header: /tcpdump/master/libpcap/Attic/pcap.3,v 1.49 2003-10-10 00:27:45 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 3 "3 January 2001"
24 pcap \- Packet Capture library
33 char errbuf[PCAP_ERRBUF_SIZE];
37 pcap_t *pcap_open_live(const char *device, int snaplen,
39 int promisc, int to_ms, char *errbuf)
40 pcap_t *pcap_open_dead(int linktype, int snaplen)
41 pcap_t *pcap_open_offline(const char *fname, char *errbuf)
42 pcap_dumper_t *pcap_dump_open(pcap_t *p, const char *fname)
46 int pcap_setnonblock(pcap_t *p, int nonblock, char *errbuf);
47 int pcap_getnonblock(pcap_t *p, char *errbuf);
51 int pcap_findalldevs(pcap_if_t **alldevsp, char *errbuf)
52 void pcap_freealldevs(pcap_if_t *alldevs)
53 char *pcap_lookupdev(char *errbuf)
54 int pcap_lookupnet(const char *device, bpf_u_int32 *netp,
56 bpf_u_int32 *maskp, char *errbuf)
60 int pcap_dispatch(pcap_t *p, int cnt,
62 pcap_handler callback, u_char *user)
63 int pcap_loop(pcap_t *p, int cnt,
65 pcap_handler callback, u_char *user)
66 void pcap_dump(u_char *user, struct pcap_pkthdr *h,
72 int pcap_compile(pcap_t *p, struct bpf_program *fp,
74 char *str, int optimize, bpf_u_int32 netmask)
75 int pcap_setfilter(pcap_t *p, struct bpf_program *fp)
76 void pcap_freecode(struct bpf_program *);
80 const u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h)
81 int pcap_next_ex(pcap_t *p, struct pcap_pkthdr **pkt_header,
83 const u_char **pkt_data)
87 int pcap_datalink(pcap_t *p)
88 int pcap_list_datalinks(pcap_t *p, int **dlt_buf);
89 int pcap_set_datalink(pcap_t *p, int dlt);
90 int pcap_datalink_name_to_val(const char *name);
91 const char *pcap_datalink_val_to_name(int dlt);
92 int pcap_snapshot(pcap_t *p)
93 int pcap_is_swapped(pcap_t *p)
94 int pcap_major_version(pcap_t *p)
95 int pcap_minor_version(pcap_t *p)
96 int pcap_stats(pcap_t *p, struct pcap_stat *ps)
97 FILE *pcap_file(pcap_t *p)
98 int pcap_fileno(pcap_t *p)
99 void pcap_perror(pcap_t *p, char *prefix)
100 char *pcap_geterr(pcap_t *p)
101 char *pcap_strerror(int error)
102 const char *pcap_lib_version(void)
106 void pcap_close(pcap_t *p)
107 int pcap_dump_flush(pcap_dumper_t *p)
108 void pcap_dump_close(pcap_dumper_t *p)
112 The Packet Capture library
113 provides a high level interface to packet capture systems. All packets
114 on the network, even those destined for other hosts, are accessible
115 through this mechanism.
121 .BR pcap_open_live() ,
122 .BR pcap_open_dead() ,
123 .BR pcap_open_offline() ,
124 .BR pcap_setnonblock() ,
125 .BR pcap_getnonblock() ,
126 .BR pcap_findalldevs() ,
127 .BR pcap_lookupdev() ,
130 is assumed to be able to hold at least
135 is used to obtain a packet capture descriptor to look
136 at packets on the network.
138 is a string that specifies the network device to open; on Linux systems
139 with 2.2 or later kernels, a
143 can be used to capture packets from all interfaces.
145 specifies the maximum number of bytes to capture. If this value is less
146 than the size of a packet that is captured, only the first
148 bytes of that packet will be captured and provided as packet data. A
149 value of 65535 should be sufficient, on most if not all networks, to
150 capture all the data available from the packet.
152 specifies if the interface is to be put into promiscuous mode.
153 (Note that even if this parameter is false, the interface
154 could well be in promiscuous mode for some other reason.) For now, this
155 doesn't work on the "any" device; if an argument of "any" or NULL is
160 specifies the read timeout in milliseconds. The read timeout is used to
161 arrange that the read not necessarily return immediately when a packet
162 is seen, but that it wait for some amount of time to allow more packets
163 to arrive and to read multiple packets from the OS kernel in one
164 operation. Not all platforms support a read timeout; on platforms that
165 don't, the read timeout is ignored. A zero value for
167 on platforms that support a read timeout,
168 will cause a read to wait forever to allow enough packets to
169 arrive, with no timeout.
171 is used to return error or warning text. It will be set to error text when
176 may also be set to warning text when
178 succeds; to detect this case the caller should store a zero-length string in
182 and display the warning to the user if
184 is no longer a zero-length string.
187 is used for creating a
189 structure to use when calling the other functions in libpcap. It is
190 typically used when just using libpcap for compiling BPF code.
192 .B pcap_open_offline()
193 is called to open a ``savefile'' for reading.
195 specifies the name of the file to open. The file has
196 the same format as those used by
200 The name "-" in a synonym for
203 is used to return error text and is only set when
204 .B pcap_open_offline()
209 is called to open a ``savefile'' for writing. The name "-" in a synonym
213 is returned on failure.
217 struct as returned by
218 .B pcap_open_offline()
220 .BR pcap_open_live() .
222 specifies the name of the file to open.
227 can be used to get the error text.
229 .B pcap_setnonblock()
230 puts a capture descriptor, opened with
231 .BR pcap_open_live() ,
232 into ``non-blocking'' mode, or takes it out of ``non-blocking'' mode,
233 depending on whether the
235 argument is non-zero or zero. It has no effect on ``savefiles''.
236 If there is an error, \-1 is returned and
238 is filled in with an appropriate error message; otherwise, 0 is
241 ``non-blocking'' mode, an attempt to read from the capture descriptor
244 will, if no packets are currently available to be read, return 0
245 immediately rather than blocking waiting for packets to arrive.
249 will not work in ``non-blocking'' mode.
251 .B pcap_getnonblock()
252 returns the current ``non-blocking'' state of the capture descriptor; it
253 always returns 0 on ``savefiles''.
254 If there is an error, \-1 is returned and
256 is filled in with an appropriate error message.
258 .B pcap_findalldevs()
259 constructs a list of network devices that can be opened with
260 .BR pcap_open_live() .
261 (Note that there may be network devices that cannot be opened with
265 .BR pcap_findalldevs() ,
266 because, for example, that process might not have sufficient privileges
267 to open them for capturing; if so, those devices will not appear on the
270 is set to point to the first element of the list; each element of the
273 and has the following members:
279 a pointer to the next element in the list;
281 for the last element of the list
284 a pointer to a string giving a name for the device to pass to
290 a pointer to a string giving a human-readable description of the device
293 a pointer to the first element of a list of addresses for the interface
300 set if the interface is a loopback interface
304 Each element of the list of addresses is of type
306 and has the following members:
312 a pointer to the next element in the list;
314 for the last element of the list
319 containing an address
326 that contains the netmask corresponding to the address pointed to by
334 that contains the broadcast address corresponding to the address pointed
337 may be null if the interface doesn't support broadcasts
344 that contains the destination address corresponding to the address pointed
347 may be null if the interface isn't a point-to-point interface
351 is returned on failure, in which case
353 is filled in with an appropriate error message;
355 is returned on success.
357 .B pcap_freealldevs()
358 is used to free a list allocated by
359 .BR pcap_findalldevs() .
362 returns a pointer to a network device suitable for use with
365 .BR pcap_lookupnet() .
366 If there is an error,
370 is filled in with an appropriate error message.
373 is used to determine the network number and mask
374 associated with the network device
383 A return of \-1 indicates an error in which case
385 is filled in with an appropriate error message.
388 is used to collect and process packets.
390 specifies the maximum number of packets to process before returning.
391 This is not a minimum number; when reading a live capture, only one
392 bufferful of packets is read at a time, so fewer than
394 packets may be processed. A
396 of \-1 processes all the packets received in one buffer when reading a
397 live capture, or all the packets in the file when reading a
400 specifies a routine to be called with three arguments:
403 pointer which is passed in from
404 .BR pcap_dispatch() ,
406 .I const struct pcap_pkthdr
407 pointer to a structure with the following members:
413 containing the time when the packet was captured
418 giving the number of bytes of the packet that are available from the
424 giving the length of the packet, in bytes (which might be more than the
425 number of bytes available from the capture, if the length of the packet
426 is larger than the maximum number of bytes to capture)
434 .I struct pcap_pkthdr
435 a pointer to which is passed to the callback routine)
436 bytes of data from the packet (which won't necessarily be the entire
437 packet; to capture the entire packet, you will have to provide a value
442 that is sufficiently large to get all of the packet's data - a value of
443 65535 should be sufficient on most if not all networks).
445 The number of packets read is returned.
446 0 is returned if no packets were read from a live capture (if, for
447 example, they were discarded because they didn't pass the packet filter,
448 or if, on platforms that support a read timeout that starts before any
449 packets arrive, the timeout expires before any packets arrive, or if the
450 file descriptor for the capture device is in non-blocking mode and no
451 packets were available to be read) or if no more packets are available
452 in a ``savefile.'' A return of \-1 indicates
453 an error in which case
457 may be used to display the error text.
460 when reading a live capture,
462 will not necessarily return when the read times out; on some platforms,
463 the read timeout isn't supported, and, on other platforms, the timer
464 doesn't start until at least one packet arrives. This means that the
467 be used in, for example, an interactive application, to allow the packet
468 capture loop to ``poll'' for user input periodically, as there's no
471 will return after the timeout expires.
476 except it keeps reading packets until
478 packets are processed or an error occurs.
481 return when live read timeouts occur.
482 Rather, specifying a non-zero read timeout to
486 allows the reception and processing of any packets that arrive when the
492 to loop forever (or at least until an error occurs). A negative number
493 is returned on an error; 0 is returned if
498 reads the next packet (by calling
504 pointer to the data in that packet. (The
506 struct for that packet is not supplied.)
508 is returned if an error occured, or if no packets were read from a live
509 capture (if, for example, they were discarded because they didn't pass
510 the packet filter, or if, on platforms that support a read timeout that
511 starts before any packets arrive, the timeout expires before any packets
512 arrive, or if the file descriptor for the capture device is in
513 non-blocking mode and no packets were available to be read), or if no
514 more packets are available in a ``savefile.'' Unfortunately, there is
515 no way to determine whether an error occured or not.
518 reads the next packet and returns a success/failure indication:
522 the packet was read without problems
525 packets are being read from a live capture, and the timeout expired
528 an error occurred while reading the packet
531 packets are being read from a ``savefile'', and there are no more
532 packets to read from the savefile.
535 If the packet was read without problems, the pointer pointed to by the
537 argument is set to point to the
539 struct for the packet, and the
540 pointer pointed to by the
542 argument is set to point to the data in the packet.
545 outputs a packet to the ``savefile'' opened with
546 .BR pcap_dump_open() .
547 Note that its calling arguments are suitable for use with
551 If called directly, the
556 .BR pcap_dump_open() .
559 is used to compile the string
561 into a filter program.
565 struct and is filled in by
568 controls whether optimization on the resulting code is performed.
570 specifies the IPv4 netmask of the network on which packets are being
571 captured; it is used only when checking for IPv4 broadcast addresses in
572 the filter program. If the netmask of the network on which packets are
573 being captured isn't known to the program, or if packets are being
574 captured on the Linux "any" pseudo-interface that can capture on more
575 than one network, a value of 0 can be supplied; tests for IPv4 broadcast
576 addreses won't be done correctly, but all other tests in the filter
577 program will be OK. A return of \-1 indicates an error in which case
579 may be used to display the error text.
581 .B pcap_compile_nopcap()
584 except that instead of passing a pcap structure, one passes the
585 snaplen and linktype explicitly. It is intended to be used for
586 compiling filters for direct BPF usage, without necessarily having
589 A return of \-1 indicates an error; the error text is unavailable.
590 .RB ( pcap_compile_nopcap()
592 .BR pcap_open_dead() ,
596 the latter three routines can be used directly in order to get the error
597 text for a compilation error.)
601 is used to specify a filter program.
605 struct, usually the result of a call to
608 is returned on failure, in which case
610 may be used to display the error text;
612 is returned on success.
615 is used to free up allocated memory pointed to by a
619 when that BPF program is no longer needed, for example after it
620 has been made the filter program for a pcap structure by a call to
621 .BR pcap_setfilter() .
624 returns the link layer type; link layer types it can return include:
629 BSD loopback encapsulation; the link layer header is a 4-byte field, in
631 byte order, containing a PF_ value from
633 for the network-layer protocol of the packet
635 Note that ``host byte order'' is the byte order of the machine on which
636 the packets are captured, and the PF_ values are for the OS of the
637 machine on which the packets are captured; if a live capture is being
638 done, ``host byte order'' is the byte order of the machine capturing the
639 packets, and the PF_ values are those of the OS of the machine capturing
640 the packets, but if a ``savefile'' is being read, the byte order and PF_
643 necessarily those of the machine reading the capture file.
646 Ethernet (10Mb, 100Mb, 1000Mb, and up)
649 IEEE 802.5 Token Ring
655 SLIP; the link layer header contains, in order:
658 a 1-byte flag, which is 0 for packets received by the machine and 1 for
659 packets sent by the machine;
661 a 1-byte field, the upper 4 bits of which indicate the type of packet,
666 an unmodified IP datagram (TYPE_IP);
669 an uncompressed-TCP IP datagram (UNCOMPRESSED_TCP), with that byte being
670 the first byte of the raw IP header on the wire, containing the
671 connection number in the protocol field;
674 a compressed-TCP IP datagram (COMPRESSED_TCP), with that byte being the
675 first byte of the compressed TCP/IP datagram header;
678 for UNCOMPRESSED_TCP, the rest of the modified IP header, and for
679 COMPRESSED_TCP, the compressed TCP/IP datagram header;
683 for a total of 16 bytes; the uncompressed IP datagram follows the header
687 PPP; if the first 2 bytes are 0xff and 0x03, it's PPP in HDLC-like
688 framing, with the PPP header following those two bytes, otherwise it's
689 PPP without framing, and the packet begins with the PPP header
695 RFC 1483 LLC/SNAP-encapsulated ATM; the packet begins with an IEEE 802.2
699 raw IP; the packet begins with an IP header
702 PPP in HDLC-like framing, as per RFC 1662, or Cisco PPP with HDLC
703 framing, as per section 4.3.1 of RFC 1547; the first byte will be 0xFF
704 for PPP in HDLC-like framing, and will be 0x0F or 0x8F for Cisco PPP
708 PPPoE; the packet begins with a PPPoE header, as per RFC 2516
711 Cisco PPP with HDLC framing, as per section 4.3.1 of RFC 1547
714 IEEE 802.11 wireless LAN
720 OpenBSD loopback encapsulation; the link layer header is a 4-byte field, in
722 byte order, containing a PF_ value from OpenBSD's
724 for the network-layer protocol of the packet
726 Note that, if a ``savefile'' is being read, those PF_ values are
728 necessarily those of the machine reading the capture file.
731 Linux "cooked" capture encapsulation; the link layer header contains, in
735 a 2-byte "packet type", in network byte order, which is one of:
739 packet was sent to us by somebody else
742 packet was broadcast by somebody else
745 packet was multicast, but not broadcast, by somebody else
748 packet was sent by somebody else to somebody else
751 packet was sent by us
754 a 2-byte field, in network byte order, containing a Linux ARPHRD_ value
755 for the link layer device type;
757 a 2-byte field, in network byte order, containing the length of the
758 link layer address of the sender of the packet (which could be 0);
760 an 8-byte field containing that number of bytes of the link layer header
761 (if there are more than 8 bytes, only the first 8 are present);
763 a 2-byte field containing an Ethernet protocol type, in network byte
764 order, or containing 1 for Novell 802.3 frames without an 802.2 LLC
765 header or 4 for frames beginning with an 802.2 LLC header.
769 Apple LocalTalk; the packet begins with an AppleTalk LLAP header
772 SunATM devices; the link layer header contains, in order:
775 a 1-byte flag field, containing a direction flag in the uppermost bit,
776 which is set for packets transmitted by the machine and clear for
777 packets received by the machine, and a 4-byte traffic type in the
778 low-order 4 bits, which is one of:
788 LLC-encapsulated traffic
805 a 2-byte VCI field, in network byte order.
809 RFC 2625 IP-over-Fibre Channel, with the link-layer header being the
810 Network_Header as described in that RFC.
813 .B pcap_list_datalinks()
814 is used to get a list of the supported data link types of the interface
815 associated with the pcap descriptor.
816 .B pcap_list_datalinks()
817 allocates an array to hold the list and sets
819 The caller is responsible for freeing the array.
821 is returned on failure;
822 otherwise, the number of data link types in the array is returned.
824 .B pcap_set_datalink()
825 is used to set the current data link type of the pcap descriptor
826 to the type specified by
829 is returned on failure.
831 .B pcap_datalink_name_to_val()
832 translates a data link type name, which is a
836 removed, to the corresponding data link type value. The translation
838 is used to set the current data link type of the pcap descriptor
839 NULL is returned on failure.
841 .B pcap_datalink_val_to_name()
842 translates a data link type value to the corresponding data link type
845 is returned on failure.
848 returns the snapshot length specified when
853 returns true if the current ``savefile'' uses a different byte order
854 than the current system.
856 .B pcap_major_version()
857 returns the major number of the file format of the savefile;
858 .B pcap_minor_version()
859 returns the minor number of the file format of the savefile. The
860 version number is stored in the header of the savefile.
863 returns the standard I/O stream of the ``savefile,'' if a ``savefile''
865 .BR pcap_open_offline() ,
866 or NULL, if a network device was opened with
867 .BR pcap_open_live() .
870 returns 0 and fills in a
872 struct. The values represent packet statistics from the start of the
873 run to the time of the call. If there is an error or the underlying
874 packet capture doesn't support packet statistics, \-1 is returned and
875 the error text can be obtained with
880 is supported only on live captures, not on ``savefiles''; no statistics
881 are stored in ``savefiles'', so no statistics are available when reading
885 returns the file descriptor number from which captured packets are read,
886 if a network device was opened with
887 .BR pcap_open_live() ,
888 or \-1, if a ``savefile'' was opened with
889 .BR pcap_open_offline() .
892 prints the text of the last pcap library error on
898 returns the error text pertaining to the last pcap library error.
900 the pointer it returns will no longer point to a valid error message
903 passed to it is closed; you must use or copy the string before closing
912 .B pcap_lib_version()
913 returns a pointer to a string giving information about the version of
914 the libpcap library being used; note that it contains more information
915 than just a version number.
918 closes the files associated with
920 and deallocates resources.
923 flushes the output buffer to the ``savefile,'' so that any packets
926 but not yet written to the ``savefile'' will be written.
928 is returned on error, 0 on success.
931 closes the ``savefile.''
934 tcpdump(1), tcpslice(1)
936 The original authors are:
940 Steven McCanne, all of the
941 Lawrence Berkeley National Laboratory, University of California, Berkeley, CA.
943 The current version is available from "The Tcpdump Group"'s Web site at
946 .I http://www.tcpdump.org/
949 Please send problems, bugs, questions, desirable enhancements, etc. to:
952 tcpdump-workers@tcpdump.org
955 Please send source code contributions, etc. to:
projects / libpcap / blob