1 .\" @(#) $Header: /tcpdump/master/libpcap/Attic/pcap.3,v 1.33 2002-07-11 08:12:34 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.
138 specifies if the interface is to be put into promiscuous mode.
139 (Note that even if this parameter is false, the interface
140 could well be in promiscuous mode for some other reason.) For now, this
141 doesn't work on the "any" device; if an argument of "any" or NULL is
146 specifies the read timeout in milliseconds. The read timeout is used to
147 arrange that the read not necessarily return immediately when a packet
148 is seen, but that it wait for some amount of time to allow more packets
149 to arrive and to read multiple packets from the OS kernel in one
150 operation. Not all platforms support a read timeout; on platforms that
151 don't, the read timeout is ignored.
153 is used to return error or warning text. It will be set to error text when
158 may also be set to warning text when
160 succeds; to detect this case the caller should store a zero-length string in
164 and display the warning to the user if
166 is no longer a zero-length string.
169 is used for creating a
171 structure to use when calling the other functions in libpcap. It is
172 typically used when just using libpcap for compiling BPF code.
174 .B pcap_open_offline()
175 is called to open a ``savefile'' for reading.
177 specifies the name of the file to open. The file has
178 the same format as those used by
182 The name "-" in a synonym for
185 is used to return error text and is only set when
186 .B pcap_open_offline()
191 is called to open a ``savefile'' for writing. The name "-" in a synonym
195 is returned on failure.
199 struct as returned by
200 .B pcap_open_offline()
202 .BR pcap_open_live() .
204 specifies the name of the file to open.
209 can be used to get the error text.
211 .B pcap_setnonblock()
212 puts a capture descriptor, opened with
213 .BR pcap_open_live() ,
214 into ``non-blocking'' mode, or takes it out of ``non-blocking'' mode,
215 depending on whether the
217 argument is non-zero or zero. It has no effect on ``savefiles''.
218 If there is an error, \-1 is returned and
220 is filled in with an appropriate error message; otherwise, 0 is
223 ``non-blocking'' mode, an attempt to read from the capture descriptor
226 will, if no packets are currently available to be read, return 0
227 immediately rather than blocking waiting for packets to arrive.
231 will not work in ``non-blocking'' mode.
233 .B pcap_getnonblock()
234 returns the current ``non-blocking'' state of the capture descriptor; it
235 always returns 0 on ``savefiles''.
236 If there is an error, \-1 is returned and
238 is filled in with an appropriate error message.
240 .B pcap_findalldevs()
241 constructs a list of network devices that can be opened with
242 .BR pcap_open_live() .
243 (Note that there may be network devices that cannot be opened with
247 .BR pcap_findalldevs() ,
248 because, for example, that process might not have sufficient privileges
249 to open them for capturing; if so, those devices will not appear on the
252 is set to point to the first element of the list; each element of the
255 and has the following members:
261 a pointer to the next element in the list;
263 for the last element of the list
266 a pointer to a string giving a name for the device to pass to
272 a pointer to a string giving a human-readable description of the device
275 a pointer to the first element of a list of addresses for the interface
282 set if the interface is a loopback interface
286 Each element of the list of addresses is of type
288 and has the following members:
294 a pointer to the next element in the list;
296 for the last element of the list
301 containing an address
308 that contains the netmask corresponding to the address pointed to by
316 that contains the broadcast address corresponding to the address pointed
319 may be null if the interface doesn't support broadcasts
326 that contains the destination address corresponding to the address pointed
329 may be null if the interface isn't a point-to-point interface
332 .B pcap_freealldevs()
333 is used to free a list allocated by
334 .BR pcap_findalldevs() .
337 returns a pointer to a network device suitable for use with
340 .BR pcap_lookupnet() .
341 If there is an error,
345 is filled in with an appropriate error message.
348 is used to determine the network number and mask
349 associated with the network device
358 A return of \-1 indicates an error in which case
360 is filled in with an appropriate error message.
363 is used to collect and process packets.
365 specifies the maximum number of packets to process before returning.
366 This is not a minimum number; when reading a live capture, only one
367 bufferful of packets is read at a time, so fewer than
369 packets may be processed. A
371 of \-1 processes all the packets received in one buffer when reading a
372 live capture, or all the packets in the file when reading a
375 specifies a routine to be called with three arguments:
378 pointer which is passed in from
379 .BR pcap_dispatch() ,
381 .I const struct pcap_pkthdr
382 pointer to a structure with the following members:
388 containing the time when the packet was captured
393 giving the number of bytes of the packet that are available from the
399 giving the length of the packet, in bytes (which might be more than the
400 number of bytes available from the capture, if the length of the packet
401 is larger than the maximum number of bytes to capture)
406 pointer to the packet data.
408 The number of packets read is returned.
409 0 is returned if no packets were read from a live capture (if, for
410 example, they were discarded because they didn't pass the packet filter,
411 or if, on platforms that support a read timeout that starts before any
412 packets arrive, the timeout expires before any packets arrive, or if the
413 file descriptor for the capture device is in non-blocking mode and no
414 packets were available to be read) or if no more packets are available
415 in a ``savefile.'' A return of \-1 indicates
416 an error in which case
420 may be used to display the error text.
423 when reading a live capture,
425 will not necessarily return when the read times out; on some platforms,
426 the read timeout isn't supported, and, on other platforms, the timer
427 doesn't start until at least one packet arrives. This means that the
430 be used in, for example, an interactive application, to allow the packet
431 capture loop to ``poll'' for user input periodically, as there's no
434 will return after the timeout expires.
439 except it keeps reading packets until
441 packets are processed or an error occurs.
444 return when live read timeouts occur.
445 Rather, specifying a non-zero read timeout to
449 allows the reception and processing of any packets that arrive when the
455 to loop forever (or at least until an error occurs). A negative number
456 is returned on an error; 0 is returned if
461 reads the next packet (by calling
467 pointer to the data in that packet. (The
469 struct for that packet is not supplied.)
472 outputs a packet to the ``savefile'' opened with
473 .BR pcap_dump_open() .
474 Note that its calling arguments are suitable for use with
478 If called directly, the
483 .BR pcap_dump_open() .
486 is used to compile the string
488 into a filter program.
492 struct and is filled in by
495 controls whether optimization on the resulting code is performed.
497 specifies the netmask of the local net.
498 A return of \-1 indicates an error in which case
500 may be used to display the error text.
502 .B pcap_compile_nopcap()
505 except that instead of passing a pcap structure, one passes the
506 snaplen and linktype explicitly. It is intended to be used for
507 compiling filters for direct BPF usage, without necessarily having
510 A return of \-1 indicates an error; the error text is unavailable.
511 .RB ( pcap_compile_nopcap()
513 .BR pcap_open_dead() ,
517 the latter three routines can be used directly in order to get the error
518 text for a compilation error.)
522 is used to specify a filter program.
526 struct, usually the result of a call to
529 is returned on failure, in which case
531 may be used to display the error text;
533 is returned on success.
536 is used to free up allocated memory pointed to by a
540 when that BPF program is no longer needed, for example after it
541 has been made the filter program for a pcap structure by a call to
542 .BR pcap_setfilter() .
545 returns the link layer type; link layer types it can return include:
550 BSD loopback encapsulation; the link layer header is a 4-byte field, in
552 byte order, containing a PF_ value from
554 for the network-layer protocol of the packet
556 Note that ``host byte order'' is the byte order of the machine on which
557 the packets are captured, and the PF_ values are for the OS of the
558 machine on which the packets are captured; if a live capture is being
559 done, ``host byte order'' is the byte order of the machine capturing the
560 packets, and the PF_ values are those of the OS of the machine capturing
561 the packets, but if a ``savefile'' is being read, the byte order and PF_
564 necessarily those of the machine reading the capture file.
567 Ethernet (10Mb, 100Mb, 1000Mb, and up)
570 IEEE 802.5 Token Ring
576 SLIP; the link layer header contains, in order:
579 a 1-byte flag, which is 0 for packets received by the machine and 1 for
580 packets sent by the machine;
582 a 1-byte field, the upper 4 bits of which indicate the type of packet,
587 an unmodified IP datagram (TYPE_IP);
590 an uncompressed-TCP IP datagram (UNCOMPRESSED_TCP), with that byte being
591 the first byte of the raw IP header on the wire, containing the
592 connection number in the protocol field;
595 a compressed-TCP IP datagram (COMPRESSED_TCP), with that byte being the
596 first byte of the compressed TCP/IP datagram header;
599 for UNCOMPRESSED_TCP, the rest of the modified IP header, and for
600 COMPRESSED_TCP, the compressed TCP/IP datagram header;
604 for a total of 16 bytes; the uncompressed IP datagram follows the header
608 PPP; if the first 2 bytes are 0xff and 0x03, it's PPP in HDLC-like
609 framing, with the PPP header following those two bytes, otherwise it's
610 PPP without framing, and the packet begins with the PPP header
616 RFC 1483 LLC/SNAP-encapsulated ATM; the packet begins with an IEEE 802.2
620 raw IP; the packet begins with an IP header
623 PPP in HDLC-like framing, as per RFC 1662, or Cisco PPP with HDLC
624 framing, as per section 4.3.1 of RFC 1547; the first byte will be 0xFF
625 for PPP in HDLC-like framing, and will be 0x0F or 0x8F for Cisco PPP
629 PPPoE; the packet begins with a PPPoE header, as per RFC 2516
632 Cisco PPP with HDLC framing, as per section 4.3.1 of RFC 1547
635 IEEE 802.11 wireless LAN
641 OpenBSD loopback encapsulation; the link layer header is a 4-byte field, in
643 byte order, containing a PF_ value from OpenBSD's
645 for the network-layer protocol of the packet
647 Note that, if a ``savefile'' is being read, those PF_ values are
649 necessarily those of the machine reading the capture file.
652 Linux "cooked" capture encapsulation; the link layer header contains, in
656 a 2-byte "packet type", in network byte order, which is one of:
660 packet was sent to us by somebody else
663 packet was broadcast by somebody else
666 packet was multicast, but not broadcast, by somebody else
669 packet was sent by somebody else to somebody else
672 packet was sent by us
675 a 2-byte field, in network byte order, containing a Linux ARPHRD_ value
676 for the link layer device type;
678 a 2-byte field, in network byte order, containing the length of the
679 link layer address of the sender of the packet (which could be 0);
681 an 8-byte field containing that number of bytes of the link layer header
682 (if there are more than 8 bytes, only the first 8 are present);
684 a 2-byte field containing an Ethernet protocol type, in network byte
685 order, or containing 1 for Novell 802.3 frames without an 802.2 LLC
686 header or 4 for frames beginning with an 802.2 LLC header.
690 Apple LocalTalk; the packet begins with an AppleTalk LLAP header
694 returns the snapshot length specified when
699 returns true if the current ``savefile'' uses a different byte order
700 than the current system.
702 .B pcap_major_version()
703 returns the major number of the version of the pcap used to write the
706 .B pcap_minor_version()
707 returns the minor number of the version of the pcap used to write the
711 returns the standard I/O stream of the ``savefile,'' if a ``savefile''
713 .BR pcap_open_offline() ,
714 or NULL, if a network device was opened with
715 .BR pcap_open_live() .
718 returns 0 and fills in a
720 struct. The values represent packet statistics from the start of the
721 run to the time of the call. If there is an error or the underlying
722 packet capture doesn't support packet statistics, \-1 is returned and
723 the error text can be obtained with
728 is supported only on live captures, not on ``savefiles''; no statistics
729 are stored in ``savefiles'', so no statistics are available when reading
733 returns the file descriptor number from which captured packets are read,
734 if a network device was opened with
735 .BR pcap_open_live() ,
736 or \-1, if a ``savefile'' was opened with
737 .BR pcap_open_offline() .
740 prints the text of the last pcap library error on
746 returns the error text pertaining to the last pcap library error.
748 the pointer it returns will no longer point to a valid error message
751 passed to it is closed; you must use or copy the string before closing
761 closes the files associated with
763 and deallocates resources.
766 closes the ``savefile.''
769 tcpdump(1), tcpslice(1)
771 The original authors are:
775 Steven McCanne, all of the
776 Lawrence Berkeley National Laboratory, University of California, Berkeley, CA.
778 The current version is available from "The Tcpdump Group"'s Web site at
781 .I http://www.tcpdump.org/
784 Please send problems, bugs, questions, desirable enhancements, etc. to:
787 tcpdump-workers@tcpdump.org
790 Please send source code contributions, etc. to:
projects / libpcap / blob