1 .\" @(#) $Header: /tcpdump/master/libpcap/Attic/pcap.3,v 1.28 2001-12-09 05:10:02 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_findalldevs(pcap_if_t **alldevsp, char *errbuf)
47 void pcap_freealldevs(pcap_if_t *)
48 char *pcap_lookupdev(char *errbuf)
49 int pcap_lookupnet(char *device, bpf_u_int32 *netp,
51 bpf_u_int32 *maskp, char *errbuf)
55 int pcap_dispatch(pcap_t *p, int cnt,
57 pcap_handler callback, u_char *user)
58 int pcap_loop(pcap_t *p, int cnt,
60 pcap_handler callback, u_char *user)
61 void pcap_dump(u_char *user, struct pcap_pkthdr *h,
67 int pcap_compile(pcap_t *p, struct bpf_program *fp,
69 char *str, int optimize, bpf_u_int32 netmask)
70 int pcap_setfilter(pcap_t *p, struct bpf_program *fp)
71 void pcap_freecode(struct bpf_program *);
75 u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h)
79 int pcap_setnonblock(pcap_t *, int nonblock, char *errbuf);
80 int pcap_getnonblock(pcap_t *p, char *errbuf);
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.
114 .B pcap_open_offline(),
115 .B pcap_findalldevs(),
119 is assumed to be able to hold at least
124 is used to obtain a packet capture descriptor to look
125 at packets on the network.
127 is a string that specifies the network device to open; on Linux systems
128 with 2.2 or later kernels, a
132 can be used to capture packets from all interfaces.
134 specifies the maximum number of bytes to capture.
136 specifies if the interface is to be put into promiscuous mode.
137 (Note that even if this parameter is false, the interface
138 could well be in promiscuous mode for some other reason.) For now, this
139 doesn't work on the "any" device; if an argument of "any" or NULL is
144 specifies the read timeout in milliseconds. The read timeout is used to
145 arrange that the read not necessarily return immediately when a packet
146 is seen, but that it wait for some amount of time to allow more packets
147 to arrive and to read multiple packets from the OS kernel in one
148 operation. Not all platforms support a read timeout; on platforms that
149 don't, the read timeout is ignored.
151 is used to return error or warning text. It will be set to error text when
156 may also be set to warning text when
158 succeds; to detect this case the caller should store a zero-length string in
162 and display the warning to the user if
164 is no longer a zero-length string.
167 is used for creating a
169 structure to use when calling the other functions in libpcap. It is
170 typically used when just using libpcap for compiling BPF code.
172 .B pcap_open_offline()
173 is called to open a ``savefile'' for reading.
175 specifies the name of the file to open. The file has
176 the same format as those used by
180 The name "-" in a synonym for
183 is used to return error text and is only set when
184 .B pcap_open_offline()
189 is called to open a ``savefile'' for writing. The name "-" in a synonym
193 is returned on failure.
197 struct as returned by
198 .B pcap_open_offline()
200 .BR pcap_open_live() .
202 specifies the name of the file to open.
207 can be used to get the error text.
209 .B pcap_findalldevs()
210 constructs a list of network devices that can be opened with
211 .BR pcap_open_live() .
212 (Note that there may be network devices that cannot be opened with
216 .BR pcap_findalldevs() ,
217 because, for example, that process might not have sufficient privileges
218 to open them for capturing; if so, those devices will not appear on the
221 is set to point to the first element of the list; each element of the
224 and has the following members:
230 a pointer to the next element in the list;
232 for the last element of the list
235 a pointer to a string giving a name for the device to pass to
241 a pointer to a string giving a human-readable description of the device
244 a pointer to the first element of a list of addresses for the interface
251 set if the interface is a loopback interface
255 Each element of the list of addresses is of type
257 and has the following members:
263 a pointer to the next element in the list;
265 for the last element of the list
270 containing an address
277 that contains the netmask corresponding to the address pointed to by
285 that contains the broadcast address corresponding to the address pointed
288 may be null if the interface doesn't support broadcasts
295 that contains the destination address corresponding to the address pointed
298 may be null if the interface isn't a point-to-point interface
301 .B pcap_freealldevs()
302 is used to free a list allocated by
303 .BR pcap_findalldevs() .
306 returns a pointer to a network device suitable for use with
309 .BR pcap_lookupnet() .
310 If there is an error,
314 is filled in with an appropriate error message.
317 is used to determine the network number and mask
318 associated with the network device
327 A return of \-1 indicates an error in which case
329 is filled in with an appropriate error message.
332 is used to collect and process packets.
334 specifies the maximum number of packets to process before returning.
335 This is not a minimum number; when reading a live capture, only one
336 bufferful of packets is read at a time, so fewer than
338 packets may be processed. A
340 of \-1 processes all the packets received in one buffer when reading a
341 live capture, or all the packets in the file when reading a
344 specifies a routine to be called with three arguments:
347 pointer which is passed in from
348 .BR pcap_dispatch() ,
351 struct (which precede the actual network headers and data),
354 pointer to the packet data.
356 The number of packets read is returned.
357 0 is returned if no packets were read from a live capture (if, for
358 example, they were discarded because they didn't pass the packet filter,
359 or if, on platforms that support a read timeout that starts before any
360 packets arrive, the timeout expires before any packets arrive, or if the
361 file descriptor for the capture device is in non-blocking mode and no
362 packets were available to be read) or if no more packets are available
363 in a ``savefile.'' A return of \-1 indicates
364 an error in which case
368 may be used to display the error text.
371 when reading a live capture,
373 will not necessarily return when the read times out; on some platforms,
374 the read timeout isn't supported, and, on other platforms, the timer
375 doesn't start until at least one packet arrives. This means that the
378 be used in, for example, an interactive application, to allow the packet
379 capture loop to ``poll'' for user input periodically, as there's no
382 will return after the timeout expires.
387 except it keeps reading packets until
389 packets are processed or an error occurs.
392 return when live read timeouts occur.
393 Rather, specifying a non-zero read timeout to
397 allows the reception and processing of any packets that arrive when the
403 to loop forever (or at least until an error occurs).
406 reads the next packet (by calling
412 pointer to the data in that packet. (The
414 struct for that packet is not supplied.)
417 outputs a packet to the ``savefile'' opened with
418 .BR pcap_dump_open() .
419 Note that its calling arguments are suitable for use with
423 If called directly, the
428 .BR pcap_dump_open() .
431 is used to compile the string
433 into a filter program.
437 struct and is filled in by
440 controls whether optimization on the resulting code is performed.
442 specifies the netmask of the local net.
443 A return of \-1 indicates an error in which case
445 may be used to display the error text.
447 .B pcap_compile_nopcap()
450 except that instead of passing a pcap structure, one passes the
451 snaplen and linktype explicitly. It is intended to be used for
452 compiling filters for direct BPF usage, without necessarily having
455 A return of \-1 indicates an error; the error text is unavailable.
456 .RB ( pcap_compile_nopcap()
458 .BR pcap_open_dead() ,
462 the latter three routines can be used directly in order to get the error
463 text for a compilation error.)
467 is used to specify a filter program.
471 struct, usually the result of a call to
474 is returned on failure, in which case
476 may be used to display the error text;
478 is returned on success.
481 is used to free up allocated memory pointed to by a
485 when that BPF program is no longer needed, for example after it
486 has been made the filter program for a pcap structure by a call to
487 .BR pcap_setfilter() .
489 .B pcap_setnonblock()
490 puts a capture descriptor, opened with
491 .BR pcap_open_live() ,
492 into ``non-blocking'' mode, or takes it out of ``non-blocking'' mode,
493 depending on whether the
495 argument is non-zero or zero. It has no effect on ``savefiles''.
496 If there is an error, \-1 is returned and
498 is filled in with an appropriate error message.
500 ``non-blocking'' mode, an attempt to read from the capture descriptor
503 will, if no packets are currently available to be read, return 0
504 immediately rather than blocking waiting for packets to arrive.
508 will not work in ``non-blocking'' mode.
510 .B pcap_getnonblock()
511 returns the current ``non-blocking'' state of the capture descriptor; it
512 always returns 0 on ``savefiles''.
513 If there is an error, \-1 is returned and
515 is filled in with an appropriate error message.
518 returns the link layer type; link layer types it can return include:
523 BSD loopback encapsulation; the link layer header is a 4-byte field, in
525 byte order, containing a PF_ value from
527 for the network-layer protocol of the packet
529 Note that ``host byte order'' is the byte order of the machine on which
530 the packets are captured, and the PF_ values are for the OS of the
531 machine on which the packets are captured; if a live capture is being
532 done, ``host byte order'' is the byte order of the machine capturing the
533 packets, and the PF_ values are those of the OS of the machine capturing
534 the packets, but if a ``savefile'' is being read, the byte order and PF_
537 necessarily those of the machine reading the capture file.
540 Ethernet (10Mb, 100Mb, 1000Mb, and up)
543 IEEE 802.5 Token Ring
549 SLIP; the link layer header contains, in order:
552 a 1-byte flag, which is 0 for packets received by the machine and 1 for
553 packets sent by the machine;
555 a 1-byte field, the upper 4 bits of which indicate the type of packet,
560 an unmodified IP datagram (TYPE_IP);
563 an uncompressed-TCP IP datagram (UNCOMPRESSED_TCP), with that byte being
564 the first byte of the raw IP header on the wire, containing the
565 connection number in the protocol field;
568 a compressed-TCP IP datagram (COMPRESSED_TCP), with that byte being the
569 first byte of the compressed TCP/IP datagram header;
572 for UNCOMPRESSED_TCP, the rest of the modified IP header, and for
573 COMPRESSED_TCP, the compressed TCP/IP datagram header;
577 for a total of 16 bytes; the uncompressed IP datagram follows the header
581 PPP; if the first 2 bytes are 0xff and 0x03, it's PPP in HDLC-like
582 framing, with the PPP header following those two bytes, otherwise it's
583 PPP without framing, and the packet begins with the PPP header
589 RFC 1483 LLC/SNAP-encapsulated ATM; the packet begins with an IEEE 802.2
593 raw IP; the packet begins with an IP header
596 PPP in HDLC-like framing, as per RFC 1662, or Cisco PPP with HDLC
597 framing, as per section 4.3.1 of RFC 1547; the first byte will be 0xFF
598 for PPP in HDLC-like framing, and will be 0x0F or 0x8F for Cisco PPP
602 PPPoE; the packet begins with a PPPoE header, as per RFC 2516
605 Cisco PPP with HDLC framing, as per section 4.3.1 of RFC 1547
608 IEEE 802.11 wireless LAN
611 OpenBSD loopback encapsulation; the link layer header is a 4-byte field, in
613 byte order, containing a PF_ value from OpenBSD's
615 for the network-layer protocol of the packet
617 Note that, if a ``savefile'' is being read, those PF_ values are
619 necessarily those of the machine reading the capture file.
622 Linux "cooked" capture encapsulation; the link layer header contains, in
626 a 2-byte "packet type", in network byte order, which is one of:
630 packet was sent to us by somebody else
633 packet was broadcast by somebody else
636 packet was multicast, but not broadcast, by somebody else
639 packet was sent by somebody else to somebody else
642 packet was sent by us
645 a 2-byte field, in network byte order, containing a Linux ARPHRD_ value
646 for the link layer device type;
648 a 2-byte field, in network byte order, containing the length of the
649 link layer address of the sender of the packet (which could be 0);
651 an 8-byte field containing that number of bytes of the link layer header
652 (if there are more than 8 bytes, only the first 8 are present);
654 a 2-byte field containing an Ethernet protocol type, in network byte
655 order, or containing 1 for Novell 802.3 frames without an 802.2 LLC
656 header or 4 for frames beginning with an 802.2 LLC header.
660 Apple LocalTalk; the packet begins with an AppleTalk LLAP header
664 returns the snapshot length specified when
669 returns true if the current ``savefile'' uses a different byte order
670 than the current system.
672 .B pcap_major_version()
673 returns the major number of the version of the pcap used to write the
676 .B pcap_minor_version()
677 returns the minor number of the version of the pcap used to write the
681 returns the standard I/O stream of the ``savefile,'' if a ``savefile''
683 .BR pcap_open_offline() ,
684 or NULL, if a network device was opened with
685 .BR pcap_open_live() .
688 returns 0 and fills in a
690 struct. The values represent packet statistics from the start of the
691 run to the time of the call. If there is an error or the underlying
692 packet capture doesn't support packet statistics, \-1 is returned and
693 the error text can be obtained with
699 returns the file descriptor number from which captured packets are read,
700 if a network device was opened with
701 .BR pcap_open_live() ,
702 or \-1, if a ``savefile'' was opened with
703 .BR pcap_open_offline() .
706 prints the text of the last pcap library error on
712 returns the error text pertaining to the last pcap library error.
714 the pointer it returns will no longer point to a valid error message
717 passed to it is closed; you must use or copy the string before closing
727 closes the files associated with
729 and deallocates resources.
732 closes the ``savefile.''
735 tcpdump(1), tcpslice(1)
737 The original authors are:
741 Steven McCanne, all of the
742 Lawrence Berkeley National Laboratory, University of California, Berkeley, CA.
744 The current version is available from "The Tcpdump Group"'s Web site at
747 .I http://www.tcpdump.org/
750 Please send problems, bugs, questions, desirable enhancements, etc. to:
753 tcpdump-workers@tcpdump.org
756 Please send source code contributions, etc. to:
projects / libpcap / blob