800 lines
21 KiB
Groff
800 lines
21 KiB
Groff
.\" @(#) $Header: /tcpdump/master/libpcap/pcap.3,v 1.31 2001/12/29 21:57:07 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.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_list_datalinks(pcap_t *p, int **dlt_buf);
|
|
int pcap_set_datalink(pcap_t *p, int dlt);
|
|
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 pointer to the
|
|
.I pcap_pkthdr
|
|
struct (which precede the actual network headers and data),
|
|
and a
|
|
.I 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).
|
|
.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 netmask of the local net.
|
|
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_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
|
|
.RE
|
|
.PP
|
|
.B pcap_list_datalinks()
|
|
is used to get a list of the supported data link types of the interface
|
|
associated with the pcap descriptor.
|
|
.B pcap_list_datalinks()
|
|
allocates an array to hold the list and sets
|
|
.IR *dlt_buf .
|
|
The caller is responsible for freeing the array.
|
|
.B \-1
|
|
is returned on failure;
|
|
otherwise, the number of data link types in the array is returned.
|
|
.PP
|
|
.B pcap_set_datalink()
|
|
is used to set the current data link type of the pcap descriptor
|
|
to the type specified by
|
|
.IR dlt .
|
|
.B \-1
|
|
is returned on failure.
|
|
.PP
|
|
.B pcap_datalink_name_to_val()
|
|
translates a data link type name, which is a
|
|
.B DLT_
|
|
name with the
|
|
.B DLT_
|
|
removed, to the corresponding data link type value. The translation
|
|
is case-insensitive.
|
|
is used to set the current data link type of the pcap descriptor
|
|
NULL is returned on failure.
|
|
.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
|