| .\" @(#) $Header: /tcpdump/master/libpcap/Attic/pcap.3,v 1.35 2002-09-06 21:14:46 guy Exp $ |
| .\" |
| .\" Copyright (c) 1994, 1996, 1997 |
| .\" The Regents of the University of California. All rights reserved. |
| .\" |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that: (1) source code distributions |
| .\" retain the above copyright notice and this paragraph in its entirety, (2) |
| .\" distributions including binary code include the above copyright notice and |
| .\" this paragraph in its entirety in the documentation or other materials |
| .\" provided with the distribution, and (3) all advertising materials mentioning |
| .\" features or use of this software display the following acknowledgement: |
| .\" ``This product includes software developed by the University of California, |
| .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of |
| .\" the University nor the names of its contributors may be used to endorse |
| .\" or promote products derived from this software without specific prior |
| .\" written permission. |
| .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED |
| .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF |
| .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
| .\" |
| .TH PCAP 3 "3 January 2001" |
| .SH NAME |
| pcap \- Packet Capture library |
| .SH SYNOPSIS |
| .nf |
| .ft B |
| #include <pcap.h> |
| .ft |
| .LP |
| .nf |
| .ft B |
| char errbuf[PCAP_ERRBUF_SIZE]; |
| .ft |
| .LP |
| .ft B |
| pcap_t *pcap_open_live(char *device, int snaplen, |
| .ti +8 |
| int promisc, int to_ms, char *errbuf) |
| pcap_t *pcap_open_dead(int linktype, int snaplen) |
| pcap_t *pcap_open_offline(char *fname, char *errbuf) |
| pcap_dumper_t *pcap_dump_open(pcap_t *p, char *fname) |
| .ft |
| .LP |
| .ft B |
| int pcap_setnonblock(pcap_t *p, int nonblock, char *errbuf); |
| int pcap_getnonblock(pcap_t *p, char *errbuf); |
| .ft |
| .LP |
| .ft B |
| int pcap_findalldevs(pcap_if_t **alldevsp, char *errbuf) |
| void pcap_freealldevs(pcap_if_t *) |
| char *pcap_lookupdev(char *errbuf) |
| int pcap_lookupnet(char *device, bpf_u_int32 *netp, |
| .ti +8 |
| bpf_u_int32 *maskp, char *errbuf) |
| .ft |
| .LP |
| .ft B |
| int pcap_dispatch(pcap_t *p, int cnt, |
| .ti +8 |
| pcap_handler callback, u_char *user) |
| int pcap_loop(pcap_t *p, int cnt, |
| .ti +8 |
| pcap_handler callback, u_char *user) |
| void pcap_dump(u_char *user, struct pcap_pkthdr *h, |
| .ti +8 |
| u_char *sp) |
| .ft |
| .LP |
| .ft B |
| int pcap_compile(pcap_t *p, struct bpf_program *fp, |
| .ti +8 |
| char *str, int optimize, bpf_u_int32 netmask) |
| int pcap_setfilter(pcap_t *p, struct bpf_program *fp) |
| void pcap_freecode(struct bpf_program *); |
| .ft |
| .LP |
| .ft B |
| u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h) |
| .ft |
| .LP |
| .ft B |
| int pcap_datalink(pcap_t *p) |
| int pcap_snapshot(pcap_t *p) |
| int pcap_is_swapped(pcap_t *p) |
| int pcap_major_version(pcap_t *p) |
| int pcap_minor_version(pcap_t *p) |
| int pcap_stats(pcap_t *p, struct pcap_stat *ps) |
| FILE *pcap_file(pcap_t *p) |
| int pcap_fileno(pcap_t *p) |
| void pcap_perror(pcap_t *p, char *prefix) |
| char *pcap_geterr(pcap_t *p) |
| char *pcap_strerror(int error) |
| .ft |
| .LP |
| .ft B |
| void pcap_close(pcap_t *p) |
| void pcap_dump_close(pcap_dumper_t *p) |
| .ft |
| .fi |
| .SH DESCRIPTION |
| The Packet Capture library |
| provides a high level interface to packet capture systems. All packets |
| on the network, even those destined for other hosts, are accessible |
| through this mechanism. |
| .PP |
| .SH ROUTINES |
| NOTE: |
| .I errbuf |
| in |
| .BR pcap_open_live() , |
| .BR pcap_open_dead() , |
| .BR pcap_open_offline() , |
| .BR pcap_setnonblock() , |
| .BR pcap_getnonblock() , |
| .BR pcap_findalldevs() , |
| .BR pcap_lookupdev() , |
| and |
| .B pcap_lookupnet() |
| is assumed to be able to hold at least |
| .B PCAP_ERRBUF_SIZE |
| chars. |
| .PP |
| .B pcap_open_live() |
| is used to obtain a packet capture descriptor to look |
| at packets on the network. |
| .I device |
| is a string that specifies the network device to open; on Linux systems |
| with 2.2 or later kernels, a |
| .I device |
| argument of "any" or |
| .B NULL |
| can be used to capture packets from all interfaces. |
| .I snaplen |
| specifies the maximum number of bytes to capture. |
| .I promisc |
| specifies if the interface is to be put into promiscuous mode. |
| (Note that even if this parameter is false, the interface |
| could well be in promiscuous mode for some other reason.) For now, this |
| doesn't work on the "any" device; if an argument of "any" or NULL is |
| supplied, the |
| .I promisc |
| flag is ignored. |
| .I to_ms |
| specifies the read timeout in milliseconds. The read timeout is used to |
| arrange that the read not necessarily return immediately when a packet |
| is seen, but that it wait for some amount of time to allow more packets |
| to arrive and to read multiple packets from the OS kernel in one |
| operation. Not all platforms support a read timeout; on platforms that |
| don't, the read timeout is ignored. |
| .I errbuf |
| is used to return error or warning text. It will be set to error text when |
| .B pcap_open_live() |
| fails and returns |
| .BR NULL . |
| .I errbuf |
| may also be set to warning text when |
| .B pcap_open_live() |
| succeds; to detect this case the caller should store a zero-length string in |
| .I errbuf |
| before calling |
| .B pcap_open_live() |
| and display the warning to the user if |
| .I errbuf |
| is no longer a zero-length string. |
| .PP |
| .B pcap_open_dead() |
| is used for creating a |
| .B pcap_t |
| structure to use when calling the other functions in libpcap. It is |
| typically used when just using libpcap for compiling BPF code. |
| .PP |
| .B pcap_open_offline() |
| is called to open a ``savefile'' for reading. |
| .I fname |
| specifies the name of the file to open. The file has |
| the same format as those used by |
| .B tcpdump(1) |
| and |
| .BR tcpslice(1) . |
| The name "-" in a synonym for |
| .BR stdin . |
| .I errbuf |
| is used to return error text and is only set when |
| .B pcap_open_offline() |
| fails and returns |
| .BR NULL . |
| .PP |
| .B pcap_dump_open() |
| is called to open a ``savefile'' for writing. The name "-" in a synonym |
| for |
| .BR stdout . |
| .B NULL |
| is returned on failure. |
| .I p |
| is a |
| .I pcap |
| struct as returned by |
| .B pcap_open_offline() |
| or |
| .BR pcap_open_live() . |
| .I fname |
| specifies the name of the file to open. |
| If |
| .B NULL |
| is returned, |
| .B pcap_geterr() |
| can be used to get the error text. |
| .PP |
| .B pcap_setnonblock() |
| puts a capture descriptor, opened with |
| .BR pcap_open_live() , |
| into ``non-blocking'' mode, or takes it out of ``non-blocking'' mode, |
| depending on whether the |
| .I nonblock |
| argument is non-zero or zero. It has no effect on ``savefiles''. |
| If there is an error, \-1 is returned and |
| .I errbuf |
| is filled in with an appropriate error message; otherwise, 0 is |
| returned. |
| In |
| ``non-blocking'' mode, an attempt to read from the capture descriptor |
| with |
| .B pcap_dispatch() |
| will, if no packets are currently available to be read, return 0 |
| immediately rather than blocking waiting for packets to arrive. |
| .B pcap_loop() |
| and |
| .B pcap_next() |
| will not work in ``non-blocking'' mode. |
| .PP |
| .B pcap_getnonblock() |
| returns the current ``non-blocking'' state of the capture descriptor; it |
| always returns 0 on ``savefiles''. |
| If there is an error, \-1 is returned and |
| .I errbuf |
| is filled in with an appropriate error message. |
| .PP |
| .B pcap_findalldevs() |
| constructs a list of network devices that can be opened with |
| .BR pcap_open_live() . |
| (Note that there may be network devices that cannot be opened with |
| .BR pcap_open_live() |
| by the |
| process calling |
| .BR pcap_findalldevs() , |
| because, for example, that process might not have sufficient privileges |
| to open them for capturing; if so, those devices will not appear on the |
| list.) |
| .I alldevsp |
| is set to point to the first element of the list; each element of the |
| list is of type |
| .BR pcap_if_t , |
| and has the following members: |
| .RS |
| .TP |
| .B next |
| if not |
| .BR NULL , |
| a pointer to the next element in the list; |
| .B NULL |
| for the last element of the list |
| .TP |
| .B name |
| a pointer to a string giving a name for the device to pass to |
| .B pcap_open_live() |
| .TP |
| .B description |
| if not |
| .BR NULL , |
| a pointer to a string giving a human-readable description of the device |
| .TP |
| .B addresses |
| a pointer to the first element of a list of addresses for the interface |
| .TP |
| .B flags |
| interface flags: |
| .RS |
| .TP |
| .B PCAP_IF_LOOPBACK |
| set if the interface is a loopback interface |
| .RE |
| .RE |
| .PP |
| Each element of the list of addresses is of type |
| .BR pcap_addr_t , |
| and has the following members: |
| .RS |
| .TP |
| .B next |
| if not |
| .BR NULL , |
| a pointer to the next element in the list; |
| .B NULL |
| for the last element of the list |
| .TP |
| .B addr |
| a pointer to a |
| .B "struct sockaddr" |
| containing an address |
| .TP |
| .B netmask |
| if not |
| .BR NULL , |
| a pointer to a |
| .B "struct sockaddr" |
| that contains the netmask corresponding to the address pointed to by |
| .B addr |
| .TP |
| .B broadaddr |
| if not |
| .BR NULL , |
| a pointer to a |
| .B "struct sockaddr" |
| that contains the broadcast address corresponding to the address pointed |
| to by |
| .BR addr ; |
| may be null if the interface doesn't support broadcasts |
| .TP |
| .B dstaddr |
| if not |
| .BR NULL , |
| a pointer to a |
| .B "struct sockaddr" |
| that contains the destination address corresponding to the address pointed |
| to by |
| .BR addr ; |
| may be null if the interface isn't a point-to-point interface |
| .RE |
| .PP |
| .B pcap_freealldevs() |
| is used to free a list allocated by |
| .BR pcap_findalldevs() . |
| .PP |
| .B pcap_lookupdev() |
| returns a pointer to a network device suitable for use with |
| .B pcap_open_live() |
| and |
| .BR pcap_lookupnet() . |
| If there is an error, |
| .B NULL |
| is returned and |
| .I errbuf |
| is filled in with an appropriate error message. |
| .PP |
| .B pcap_lookupnet() |
| is used to determine the network number and mask |
| associated with the network device |
| .BR device . |
| Both |
| .I netp |
| and |
| .I maskp |
| are |
| .I bpf_u_int32 |
| pointers. |
| A return of \-1 indicates an error in which case |
| .I errbuf |
| is filled in with an appropriate error message. |
| .PP |
| .B pcap_dispatch() |
| is used to collect and process packets. |
| .I cnt |
| specifies the maximum number of packets to process before returning. |
| This is not a minimum number; when reading a live capture, only one |
| bufferful of packets is read at a time, so fewer than |
| .I cnt |
| packets may be processed. A |
| .I cnt |
| of \-1 processes all the packets received in one buffer when reading a |
| live capture, or all the packets in the file when reading a |
| ``savefile''. |
| .I callback |
| specifies a routine to be called with three arguments: |
| a |
| .I u_char |
| pointer which is passed in from |
| .BR pcap_dispatch() , |
| a |
| .I const struct pcap_pkthdr |
| pointer to a structure with the following members: |
| .RS |
| .TP |
| .B ts |
| a |
| .I struct timeval |
| containing the time when the packet was captured |
| .TP |
| .B caplen |
| a |
| .I bpf_u_int32 |
| giving the number of bytes of the packet that are available from the |
| capture |
| .TP |
| .B len |
| a |
| .I bpf_u_int32 |
| giving the length of the packet, in bytes (which might be more than the |
| number of bytes available from the capture, if the length of the packet |
| is larger than the maximum number of bytes to capture) |
| .RE |
| .PP |
| and a |
| .I const u_char |
| pointer to the packet data. |
| .PP |
| The number of packets read is returned. |
| 0 is returned if no packets were read from a live capture (if, for |
| example, they were discarded because they didn't pass the packet filter, |
| or if, on platforms that support a read timeout that starts before any |
| packets arrive, the timeout expires before any packets arrive, or if the |
| file descriptor for the capture device is in non-blocking mode and no |
| packets were available to be read) or if no more packets are available |
| in a ``savefile.'' A return of \-1 indicates |
| an error in which case |
| .B pcap_perror() |
| or |
| .B pcap_geterr() |
| may be used to display the error text. |
| .PP |
| .BR NOTE : |
| when reading a live capture, |
| .B pcap_dispatch() |
| will not necessarily return when the read times out; on some platforms, |
| the read timeout isn't supported, and, on other platforms, the timer |
| doesn't start until at least one packet arrives. This means that the |
| read timeout should |
| .B NOT |
| be used in, for example, an interactive application, to allow the packet |
| capture loop to ``poll'' for user input periodically, as there's no |
| guarantee that |
| .B pcap_dispatch() |
| will return after the timeout expires. |
| .PP |
| .B pcap_loop() |
| is similar to |
| .B pcap_dispatch() |
| except it keeps reading packets until |
| .I cnt |
| packets are processed or an error occurs. |
| It does |
| .B not |
| return when live read timeouts occur. |
| Rather, specifying a non-zero read timeout to |
| .B pcap_open_live() |
| and then calling |
| .B pcap_dispatch() |
| allows the reception and processing of any packets that arrive when the |
| timeout occurs. |
| A negative |
| .I cnt |
| causes |
| .B pcap_loop() |
| to loop forever (or at least until an error occurs). A negative number |
| is returned on an error; 0 is returned if |
| .I cnt |
| is exhausted. |
| .PP |
| .B pcap_next() |
| reads the next packet (by calling |
| .B pcap_dispatch() |
| with a |
| .I cnt |
| of 1) and returns a |
| .I u_char |
| pointer to the data in that packet. (The |
| .I pcap_pkthdr |
| struct for that packet is not supplied.) |
| .PP |
| .B pcap_dump() |
| outputs a packet to the ``savefile'' opened with |
| .BR pcap_dump_open() . |
| Note that its calling arguments are suitable for use with |
| .B pcap_dispatch() |
| or |
| .BR pcap_loop() . |
| If called directly, the |
| .I user |
| parameter is of type |
| .I pcap_dumper_t |
| as returned by |
| .BR pcap_dump_open() . |
| .PP |
| .B pcap_compile() |
| is used to compile the string |
| .I str |
| into a filter program. |
| .I program |
| is a pointer to a |
| .I bpf_program |
| struct and is filled in by |
| .BR pcap_compile() . |
| .I optimize |
| controls whether optimization on the resulting code is performed. |
| .I netmask |
| specifies the IPv4 netmask of the network on which packets are being |
| captured; it is used only when checking for IPv4 broadcast addresses in |
| the filter program. If the netmask of the network on which packets are |
| being captured isn't known to the program, or if packets are being |
| captured on the Linux "any" pseudo-interface that can capture on more |
| than one network, a value of 0 can be supplied; tests for IPv4 broadcast |
| addreses won't be done correctly, but all other tests in the filter |
| program will be OK. A return of \-1 indicates an error in which case |
| .BR pcap_geterr() |
| may be used to display the error text. |
| .PP |
| .B pcap_compile_nopcap() |
| is similar to |
| .B pcap_compile() |
| except that instead of passing a pcap structure, one passes the |
| snaplen and linktype explicitly. It is intended to be used for |
| compiling filters for direct BPF usage, without necessarily having |
| called |
| .BR pcap_open() . |
| A return of \-1 indicates an error; the error text is unavailable. |
| .RB ( pcap_compile_nopcap() |
| is a wrapper around |
| .BR pcap_open_dead() , |
| .BR pcap_compile() , |
| and |
| .BR pcap_close() ; |
| the latter three routines can be used directly in order to get the error |
| text for a compilation error.) |
| .B |
| .PP |
| .B pcap_setfilter() |
| is used to specify a filter program. |
| .I fp |
| is a pointer to a |
| .I bpf_program |
| struct, usually the result of a call to |
| .BR pcap_compile() . |
| .B \-1 |
| is returned on failure, in which case |
| .BR pcap_geterr() |
| may be used to display the error text; |
| .B 0 |
| is returned on success. |
| .PP |
| .B pcap_freecode() |
| is used to free up allocated memory pointed to by a |
| .I bpf_program |
| struct generated by |
| .B pcap_compile() |
| when that BPF program is no longer needed, for example after it |
| has been made the filter program for a pcap structure by a call to |
| .BR pcap_setfilter() . |
| .PP |
| .B pcap_datalink() |
| returns the link layer type; link layer types it can return include: |
| .PP |
| .RS 5 |
| .TP 5 |
| .B DLT_NULL |
| BSD loopback encapsulation; the link layer header is a 4-byte field, in |
| .I host |
| byte order, containing a PF_ value from |
| .B socket.h |
| for the network-layer protocol of the packet |
| .IP |
| Note that ``host byte order'' is the byte order of the machine on which |
| the packets are captured, and the PF_ values are for the OS of the |
| machine on which the packets are captured; if a live capture is being |
| done, ``host byte order'' is the byte order of the machine capturing the |
| packets, and the PF_ values are those of the OS of the machine capturing |
| the packets, but if a ``savefile'' is being read, the byte order and PF_ |
| values are |
| .I not |
| necessarily those of the machine reading the capture file. |
| .TP 5 |
| .B DLT_EN10MB |
| Ethernet (10Mb, 100Mb, 1000Mb, and up) |
| .TP 5 |
| .B DLT_IEEE802 |
| IEEE 802.5 Token Ring |
| .TP 5 |
| .B DLT_ARCNET |
| ARCNET |
| .TP 5 |
| .B DLT_SLIP |
| SLIP; the link layer header contains, in order: |
| .RS 10 |
| .LP |
| a 1-byte flag, which is 0 for packets received by the machine and 1 for |
| packets sent by the machine; |
| .LP |
| a 1-byte field, the upper 4 bits of which indicate the type of packet, |
| as per RFC 1144: |
| .RS 5 |
| .TP 5 |
| 0x40 |
| an unmodified IP datagram (TYPE_IP); |
| .TP 5 |
| 0x70 |
| an uncompressed-TCP IP datagram (UNCOMPRESSED_TCP), with that byte being |
| the first byte of the raw IP header on the wire, containing the |
| connection number in the protocol field; |
| .TP 5 |
| 0x80 |
| a compressed-TCP IP datagram (COMPRESSED_TCP), with that byte being the |
| first byte of the compressed TCP/IP datagram header; |
| .RE |
| .LP |
| for UNCOMPRESSED_TCP, the rest of the modified IP header, and for |
| COMPRESSED_TCP, the compressed TCP/IP datagram header; |
| .RE |
| .RS 5 |
| .LP |
| for a total of 16 bytes; the uncompressed IP datagram follows the header |
| .RE |
| .TP 5 |
| .B DLT_PPP |
| PPP; if the first 2 bytes are 0xff and 0x03, it's PPP in HDLC-like |
| framing, with the PPP header following those two bytes, otherwise it's |
| PPP without framing, and the packet begins with the PPP header |
| .TP 5 |
| .B DLT_FDDI |
| FDDI |
| .TP 5 |
| .B DLT_ATM_RFC1483 |
| RFC 1483 LLC/SNAP-encapsulated ATM; the packet begins with an IEEE 802.2 |
| LLC header |
| .TP 5 |
| .B DLT_RAW |
| raw IP; the packet begins with an IP header |
| .TP 5 |
| .B DLT_PPP_SERIAL |
| PPP in HDLC-like framing, as per RFC 1662, or Cisco PPP with HDLC |
| framing, as per section 4.3.1 of RFC 1547; the first byte will be 0xFF |
| for PPP in HDLC-like framing, and will be 0x0F or 0x8F for Cisco PPP |
| with HDLC framing |
| .TP 5 |
| .B DLT_PPP_ETHER |
| PPPoE; the packet begins with a PPPoE header, as per RFC 2516 |
| .TP 5 |
| .B DLT_C_HDLC |
| Cisco PPP with HDLC framing, as per section 4.3.1 of RFC 1547 |
| .TP 5 |
| .B DLT_IEEE802_11 |
| IEEE 802.11 wireless LAN |
| .TP 5 |
| .B DLT_FRELAY |
| Frame Relay |
| .TP 5 |
| .B DLT_LOOP |
| OpenBSD loopback encapsulation; the link layer header is a 4-byte field, in |
| .I network |
| byte order, containing a PF_ value from OpenBSD's |
| .B socket.h |
| for the network-layer protocol of the packet |
| .IP |
| Note that, if a ``savefile'' is being read, those PF_ values are |
| .I not |
| necessarily those of the machine reading the capture file. |
| .TP 5 |
| .B DLT_LINUX_SLL |
| Linux "cooked" capture encapsulation; the link layer header contains, in |
| order: |
| .RS 10 |
| .LP |
| a 2-byte "packet type", in network byte order, which is one of: |
| .RS 5 |
| .TP 5 |
| 0 |
| packet was sent to us by somebody else |
| .TP 5 |
| 1 |
| packet was broadcast by somebody else |
| .TP 5 |
| 2 |
| packet was multicast, but not broadcast, by somebody else |
| .TP 5 |
| 3 |
| packet was sent by somebody else to somebody else |
| .TP 5 |
| 4 |
| packet was sent by us |
| .RE |
| .LP |
| a 2-byte field, in network byte order, containing a Linux ARPHRD_ value |
| for the link layer device type; |
| .LP |
| a 2-byte field, in network byte order, containing the length of the |
| link layer address of the sender of the packet (which could be 0); |
| .LP |
| an 8-byte field containing that number of bytes of the link layer header |
| (if there are more than 8 bytes, only the first 8 are present); |
| .LP |
| a 2-byte field containing an Ethernet protocol type, in network byte |
| order, or containing 1 for Novell 802.3 frames without an 802.2 LLC |
| header or 4 for frames beginning with an 802.2 LLC header. |
| .RE |
| .TP 5 |
| .B DLT_LTALK |
| Apple LocalTalk; the packet begins with an AppleTalk LLAP header |
| .TP 5 |
| .B DLT_SUNATM |
| SunATM devices; the link layer header contains, in order: |
| .RS 10 |
| .LP |
| a 1-byte flag field, containing a direction flag in the uppermost bit, |
| which is set for packets transmitted by the machine and clear for |
| packets received by the machine, and a 4-byte traffic type in the |
| low-order 4 bits, which is one of: |
| .RS 5 |
| .TP 5 |
| 0 |
| raw traffic |
| .TP 5 |
| 1 |
| LANE traffic |
| .TP 5 |
| 2 |
| LLC-encapsulated traffic |
| .TP 5 |
| 3 |
| MARS traffic |
| .TP 5 |
| 4 |
| IFMP traffic |
| .TP 5 |
| 5 |
| ILMI traffic |
| .TP 5 |
| 6 |
| Q.2931 traffic |
| .RE |
| .LP |
| a 1-byte VPI value; |
| .LP |
| a 2-byte VCI field, in network byte order. |
| .RE |
| .PP |
| .B pcap_snapshot() |
| returns the snapshot length specified when |
| .B pcap_open_live |
| was called. |
| .PP |
| .B pcap_is_swapped() |
| returns true if the current ``savefile'' uses a different byte order |
| than the current system. |
| .PP |
| .B pcap_major_version() |
| returns the major number of the version of the pcap used to write the |
| savefile. |
| .PP |
| .B pcap_minor_version() |
| returns the minor number of the version of the pcap used to write the |
| savefile. |
| .PP |
| .B pcap_file() |
| returns the standard I/O stream of the ``savefile,'' if a ``savefile'' |
| was opened with |
| .BR pcap_open_offline() , |
| or NULL, if a network device was opened with |
| .BR pcap_open_live() . |
| .PP |
| .B pcap_stats() |
| returns 0 and fills in a |
| .B pcap_stat |
| struct. The values represent packet statistics from the start of the |
| run to the time of the call. If there is an error or the underlying |
| packet capture doesn't support packet statistics, \-1 is returned and |
| the error text can be obtained with |
| .B pcap_perror() |
| or |
| .BR pcap_geterr() . |
| .B pcap_stats() |
| is supported only on live captures, not on ``savefiles''; no statistics |
| are stored in ``savefiles'', so no statistics are available when reading |
| from a ``savefile''. |
| .PP |
| .B pcap_fileno() |
| returns the file descriptor number from which captured packets are read, |
| if a network device was opened with |
| .BR pcap_open_live() , |
| or \-1, if a ``savefile'' was opened with |
| .BR pcap_open_offline() . |
| .PP |
| .B pcap_perror() |
| prints the text of the last pcap library error on |
| .BR stderr , |
| prefixed by |
| .IR prefix . |
| .PP |
| .B pcap_geterr() |
| returns the error text pertaining to the last pcap library error. |
| .BR NOTE : |
| the pointer it returns will no longer point to a valid error message |
| string after the |
| .B pcap_t |
| passed to it is closed; you must use or copy the string before closing |
| the |
| .BR pcap_t . |
| .PP |
| .B pcap_strerror() |
| is provided in case |
| .BR strerror (1) |
| isn't available. |
| .PP |
| .B pcap_close() |
| closes the files associated with |
| .I p |
| and deallocates resources. |
| .PP |
| .B pcap_dump_close() |
| closes the ``savefile.'' |
| .PP |
| .SH SEE ALSO |
| tcpdump(1), tcpslice(1) |
| .SH AUTHORS |
| The original authors are: |
| .LP |
| Van Jacobson, |
| Craig Leres and |
| Steven McCanne, all of the |
| Lawrence Berkeley National Laboratory, University of California, Berkeley, CA. |
| .LP |
| The current version is available from "The Tcpdump Group"'s Web site at |
| .LP |
| .RS |
| .I http://www.tcpdump.org/ |
| .RE |
| .SH BUGS |
| Please send problems, bugs, questions, desirable enhancements, etc. to: |
| .LP |
| .RS |
| tcpdump-workers@tcpdump.org |
| .RE |
| .LP |
| Please send source code contributions, etc. to: |
| .LP |
| .RS |
| patches@tcpdump.org |
| .RE |