1 .\" @(#) $Header: /tcpdump/master/libpcap/Attic/pcap.3,v 1.39 2002-10-18 08:46:15 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(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(char *fname, char *errbuf)
42 pcap_dumper_t *pcap_dump_open(pcap_t *p, 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 *)
53 char *pcap_lookupdev(char *errbuf)
54 int pcap_lookupnet(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 u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h)
84 int pcap_datalink(pcap_t *p)
85 int pcap_snapshot(pcap_t *p)
86 int pcap_is_swapped(pcap_t *p)
87 int pcap_major_version(pcap_t *p)
88 int pcap_minor_version(pcap_t *p)
89 int pcap_stats(pcap_t *p, struct pcap_stat *ps)
90 FILE *pcap_file(pcap_t *p)
91 int pcap_fileno(pcap_t *p)
92 void pcap_perror(pcap_t *p, char *prefix)
93 char *pcap_geterr(pcap_t *p)
94 char *pcap_strerror(int error)
98 void pcap_close(pcap_t *p)
99 void pcap_dump_close(pcap_dumper_t *p)
103 The Packet Capture library
104 provides a high level interface to packet capture systems. All packets
105 on the network, even those destined for other hosts, are accessible
106 through this mechanism.
112 .BR pcap_open_live() ,
113 .BR pcap_open_dead() ,
114 .BR pcap_open_offline() ,
115 .BR pcap_setnonblock() ,
116 .BR pcap_getnonblock() ,
117 .BR pcap_findalldevs() ,
118 .BR pcap_lookupdev() ,
121 is assumed to be able to hold at least
126 is used to obtain a packet capture descriptor to look
127 at packets on the network.
129 is a string that specifies the network device to open; on Linux systems
130 with 2.2 or later kernels, a
134 can be used to capture packets from all interfaces.
136 specifies the maximum number of bytes to capture. If this value is less
137 than the size of a packet that is captured, only the first
139 bytes of that packet will be captured and provided as packet data. A
140 value of 65535 should be sufficient, on most if not all networks, to
141 capture all the data available from the packet.
143 specifies if the interface is to be put into promiscuous mode.
144 (Note that even if this parameter is false, the interface
145 could well be in promiscuous mode for some other reason.) For now, this
146 doesn't work on the "any" device; if an argument of "any" or NULL is
151 specifies the read timeout in milliseconds. The read timeout is used to
152 arrange that the read not necessarily return immediately when a packet
153 is seen, but that it wait for some amount of time to allow more packets
154 to arrive and to read multiple packets from the OS kernel in one
155 operation. Not all platforms support a read timeout; on platforms that
156 don't, the read timeout is ignored. A zero value for
158 on platforms that support a read timeout,
159 will cause a read to wait forever to allow enough packets to
160 arrive, with no timeout.
162 is used to return error or warning text. It will be set to error text when
167 may also be set to warning text when
169 succeds; to detect this case the caller should store a zero-length string in
173 and display the warning to the user if
175 is no longer a zero-length string.
178 is used for creating a
180 structure to use when calling the other functions in libpcap. It is
181 typically used when just using libpcap for compiling BPF code.
183 .B pcap_open_offline()
184 is called to open a ``savefile'' for reading.
186 specifies the name of the file to open. The file has
187 the same format as those used by
191 The name "-" in a synonym for
194 is used to return error text and is only set when
195 .B pcap_open_offline()
200 is called to open a ``savefile'' for writing. The name "-" in a synonym
204 is returned on failure.
208 struct as returned by
209 .B pcap_open_offline()
211 .BR pcap_open_live() .
213 specifies the name of the file to open.
218 can be used to get the error text.
220 .B pcap_setnonblock()
221 puts a capture descriptor, opened with
222 .BR pcap_open_live() ,
223 into ``non-blocking'' mode, or takes it out of ``non-blocking'' mode,
224 depending on whether the
226 argument is non-zero or zero. It has no effect on ``savefiles''.
227 If there is an error, \-1 is returned and
229 is filled in with an appropriate error message; otherwise, 0 is
232 ``non-blocking'' mode, an attempt to read from the capture descriptor
235 will, if no packets are currently available to be read, return 0
236 immediately rather than blocking waiting for packets to arrive.
240 will not work in ``non-blocking'' mode.
242 .B pcap_getnonblock()
243 returns the current ``non-blocking'' state of the capture descriptor; it
244 always returns 0 on ``savefiles''.
245 If there is an error, \-1 is returned and
247 is filled in with an appropriate error message.
249 .B pcap_findalldevs()
250 constructs a list of network devices that can be opened with
251 .BR pcap_open_live() .
252 (Note that there may be network devices that cannot be opened with
256 .BR pcap_findalldevs() ,
257 because, for example, that process might not have sufficient privileges
258 to open them for capturing; if so, those devices will not appear on the
261 is set to point to the first element of the list; each element of the
264 and has the following members:
270 a pointer to the next element in the list;
272 for the last element of the list
275 a pointer to a string giving a name for the device to pass to
281 a pointer to a string giving a human-readable description of the device
284 a pointer to the first element of a list of addresses for the interface
291 set if the interface is a loopback interface
295 Each element of the list of addresses is of type
297 and has the following members:
303 a pointer to the next element in the list;
305 for the last element of the list
310 containing an address
317 that contains the netmask corresponding to the address pointed to by
325 that contains the broadcast address corresponding to the address pointed
328 may be null if the interface doesn't support broadcasts
335 that contains the destination address corresponding to the address pointed
338 may be null if the interface isn't a point-to-point interface
341 .B pcap_freealldevs()
342 is used to free a list allocated by
343 .BR pcap_findalldevs() .
346 returns a pointer to a network device suitable for use with
349 .BR pcap_lookupnet() .
350 If there is an error,
354 is filled in with an appropriate error message.
357 is used to determine the network number and mask
358 associated with the network device
367 A return of \-1 indicates an error in which case
369 is filled in with an appropriate error message.
372 is used to collect and process packets.
374 specifies the maximum number of packets to process before returning.
375 This is not a minimum number; when reading a live capture, only one
376 bufferful of packets is read at a time, so fewer than
378 packets may be processed. A
380 of \-1 processes all the packets received in one buffer when reading a
381 live capture, or all the packets in the file when reading a
384 specifies a routine to be called with three arguments:
387 pointer which is passed in from
388 .BR pcap_dispatch() ,
390 .I const struct pcap_pkthdr
391 pointer to a structure with the following members:
397 containing the time when the packet was captured
402 giving the number of bytes of the packet that are available from the
408 giving the length of the packet, in bytes (which might be more than the
409 number of bytes available from the capture, if the length of the packet
410 is larger than the maximum number of bytes to capture)
418 .I struct pcap_pkthdr
419 a pointer to which is passed to the callback routine)
420 bytes of data from the packet (which won't necessarily be the entire
421 packet; to capture the entire packet, you will have to provide a value
426 that is sufficiently large to get all of the packet's data - a value of
427 65535 should be sufficient on most if not all networks).
429 The number of packets read is returned.
430 0 is returned if no packets were read from a live capture (if, for
431 example, they were discarded because they didn't pass the packet filter,
432 or if, on platforms that support a read timeout that starts before any
433 packets arrive, the timeout expires before any packets arrive, or if the
434 file descriptor for the capture device is in non-blocking mode and no
435 packets were available to be read) or if no more packets are available
436 in a ``savefile.'' A return of \-1 indicates
437 an error in which case
441 may be used to display the error text.
444 when reading a live capture,
446 will not necessarily return when the read times out; on some platforms,
447 the read timeout isn't supported, and, on other platforms, the timer
448 doesn't start until at least one packet arrives. This means that the
451 be used in, for example, an interactive application, to allow the packet
452 capture loop to ``poll'' for user input periodically, as there's no
455 will return after the timeout expires.
460 except it keeps reading packets until
462 packets are processed or an error occurs.
465 return when live read timeouts occur.
466 Rather, specifying a non-zero read timeout to
470 allows the reception and processing of any packets that arrive when the
476 to loop forever (or at least until an error occurs). A negative number
477 is returned on an error; 0 is returned if
482 reads the next packet (by calling
488 pointer to the data in that packet. (The
490 struct for that packet is not supplied.)
493 outputs a packet to the ``savefile'' opened with
494 .BR pcap_dump_open() .
495 Note that its calling arguments are suitable for use with
499 If called directly, the
504 .BR pcap_dump_open() .
507 is used to compile the string
509 into a filter program.
513 struct and is filled in by
516 controls whether optimization on the resulting code is performed.
518 specifies the IPv4 netmask of the network on which packets are being
519 captured; it is used only when checking for IPv4 broadcast addresses in
520 the filter program. If the netmask of the network on which packets are
521 being captured isn't known to the program, or if packets are being
522 captured on the Linux "any" pseudo-interface that can capture on more
523 than one network, a value of 0 can be supplied; tests for IPv4 broadcast
524 addreses won't be done correctly, but all other tests in the filter
525 program will be OK. A return of \-1 indicates an error in which case
527 may be used to display the error text.
529 .B pcap_compile_nopcap()
532 except that instead of passing a pcap structure, one passes the
533 snaplen and linktype explicitly. It is intended to be used for
534 compiling filters for direct BPF usage, without necessarily having
537 A return of \-1 indicates an error; the error text is unavailable.
538 .RB ( pcap_compile_nopcap()
540 .BR pcap_open_dead() ,
544 the latter three routines can be used directly in order to get the error
545 text for a compilation error.)
549 is used to specify a filter program.
553 struct, usually the result of a call to
556 is returned on failure, in which case
558 may be used to display the error text;
560 is returned on success.
563 is used to free up allocated memory pointed to by a
567 when that BPF program is no longer needed, for example after it
568 has been made the filter program for a pcap structure by a call to
569 .BR pcap_setfilter() .
572 returns the link layer type; link layer types it can return include:
577 BSD loopback encapsulation; the link layer header is a 4-byte field, in
579 byte order, containing a PF_ value from
581 for the network-layer protocol of the packet
583 Note that ``host byte order'' is the byte order of the machine on which
584 the packets are captured, and the PF_ values are for the OS of the
585 machine on which the packets are captured; if a live capture is being
586 done, ``host byte order'' is the byte order of the machine capturing the
587 packets, and the PF_ values are those of the OS of the machine capturing
588 the packets, but if a ``savefile'' is being read, the byte order and PF_
591 necessarily those of the machine reading the capture file.
594 Ethernet (10Mb, 100Mb, 1000Mb, and up)
597 IEEE 802.5 Token Ring
603 SLIP; the link layer header contains, in order:
606 a 1-byte flag, which is 0 for packets received by the machine and 1 for
607 packets sent by the machine;
609 a 1-byte field, the upper 4 bits of which indicate the type of packet,
614 an unmodified IP datagram (TYPE_IP);
617 an uncompressed-TCP IP datagram (UNCOMPRESSED_TCP), with that byte being
618 the first byte of the raw IP header on the wire, containing the
619 connection number in the protocol field;
622 a compressed-TCP IP datagram (COMPRESSED_TCP), with that byte being the
623 first byte of the compressed TCP/IP datagram header;
626 for UNCOMPRESSED_TCP, the rest of the modified IP header, and for
627 COMPRESSED_TCP, the compressed TCP/IP datagram header;
631 for a total of 16 bytes; the uncompressed IP datagram follows the header
635 PPP; if the first 2 bytes are 0xff and 0x03, it's PPP in HDLC-like
636 framing, with the PPP header following those two bytes, otherwise it's
637 PPP without framing, and the packet begins with the PPP header
643 RFC 1483 LLC/SNAP-encapsulated ATM; the packet begins with an IEEE 802.2
647 raw IP; the packet begins with an IP header
650 PPP in HDLC-like framing, as per RFC 1662, or Cisco PPP with HDLC
651 framing, as per section 4.3.1 of RFC 1547; the first byte will be 0xFF
652 for PPP in HDLC-like framing, and will be 0x0F or 0x8F for Cisco PPP
656 PPPoE; the packet begins with a PPPoE header, as per RFC 2516
659 Cisco PPP with HDLC framing, as per section 4.3.1 of RFC 1547
662 IEEE 802.11 wireless LAN
668 OpenBSD loopback encapsulation; the link layer header is a 4-byte field, in
670 byte order, containing a PF_ value from OpenBSD's
672 for the network-layer protocol of the packet
674 Note that, if a ``savefile'' is being read, those PF_ values are
676 necessarily those of the machine reading the capture file.
679 Linux "cooked" capture encapsulation; the link layer header contains, in
683 a 2-byte "packet type", in network byte order, which is one of:
687 packet was sent to us by somebody else
690 packet was broadcast by somebody else
693 packet was multicast, but not broadcast, by somebody else
696 packet was sent by somebody else to somebody else
699 packet was sent by us
702 a 2-byte field, in network byte order, containing a Linux ARPHRD_ value
703 for the link layer device type;
705 a 2-byte field, in network byte order, containing the length of the
706 link layer address of the sender of the packet (which could be 0);
708 an 8-byte field containing that number of bytes of the link layer header
709 (if there are more than 8 bytes, only the first 8 are present);
711 a 2-byte field containing an Ethernet protocol type, in network byte
712 order, or containing 1 for Novell 802.3 frames without an 802.2 LLC
713 header or 4 for frames beginning with an 802.2 LLC header.
717 Apple LocalTalk; the packet begins with an AppleTalk LLAP header
720 SunATM devices; the link layer header contains, in order:
723 a 1-byte flag field, containing a direction flag in the uppermost bit,
724 which is set for packets transmitted by the machine and clear for
725 packets received by the machine, and a 4-byte traffic type in the
726 low-order 4 bits, which is one of:
736 LLC-encapsulated traffic
753 a 2-byte VCI field, in network byte order.
757 RFC 2625 IP-over-Fibre Channel, with the link-layer header being the
758 Network_Header as described in that RFC.
761 returns the snapshot length specified when
766 returns true if the current ``savefile'' uses a different byte order
767 than the current system.
769 .B pcap_major_version()
770 returns the major number of the version of the pcap used to write the
773 .B pcap_minor_version()
774 returns the minor number of the version of the pcap used to write the
778 returns the standard I/O stream of the ``savefile,'' if a ``savefile''
780 .BR pcap_open_offline() ,
781 or NULL, if a network device was opened with
782 .BR pcap_open_live() .
785 returns 0 and fills in a
787 struct. The values represent packet statistics from the start of the
788 run to the time of the call. If there is an error or the underlying
789 packet capture doesn't support packet statistics, \-1 is returned and
790 the error text can be obtained with
795 is supported only on live captures, not on ``savefiles''; no statistics
796 are stored in ``savefiles'', so no statistics are available when reading
800 returns the file descriptor number from which captured packets are read,
801 if a network device was opened with
802 .BR pcap_open_live() ,
803 or \-1, if a ``savefile'' was opened with
804 .BR pcap_open_offline() .
807 prints the text of the last pcap library error on
813 returns the error text pertaining to the last pcap library error.
815 the pointer it returns will no longer point to a valid error message
818 passed to it is closed; you must use or copy the string before closing
828 closes the files associated with
830 and deallocates resources.
833 closes the ``savefile.''
836 tcpdump(1), tcpslice(1)
838 The original authors are:
842 Steven McCanne, all of the
843 Lawrence Berkeley National Laboratory, University of California, Berkeley, CA.
845 The current version is available from "The Tcpdump Group"'s Web site at
848 .I http://www.tcpdump.org/
851 Please send problems, bugs, questions, desirable enhancements, etc. to:
854 tcpdump-workers@tcpdump.org
857 Please send source code contributions, etc. to:
projects / libpcap / blob