pcap.3

用来监视网络通信数据的源代码和应用程序,方便网络程序底层开发.

.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_PFLOG
OpenBSD pflog; the link layer header contains, in order:
.RS 10
.LP
a 1-byte header length, in host byte order;
.LP
a 4-byte PF_ value, in host byte order;
.LP
a 2-byte action code, in network byte order, which is one of:
.RS 5
.TP 5
0
passed
.TP 5
1
dropped
.TP 5
2
scrubbed
.RE
.LP
a 2-byte reason code, in network byte order, which is one of:
.RS 5
.TP 5
0
match
.TP 5
1
bad offset
.TP 5
2
fragment
.TP 5
3
short
.TP 5
4
normalize
.TP 5
5
memory
.RE
.LP
a 16-character interface name;
.LP
a 16-character ruleset name (only meaningful if subrule is set);
.LP
a 4-byte rule number, in network byte order;
.LP
a 4-byte subrule number, in network byte order;
.LP
a 1-byte direction, in network byte order, which is one of:
.RS 5
.TP 5
0
incoming or outgoing
.TP 5
1
incoming
.TP 5
2
outgoing
.RE
.RE
.TP 5
.B DLT_PRISM_HEADER
Prism monitor mode information followed by an 802.11 header.
.TP 5
.B DLT_IP_OVER_FC
RFC 2625 IP-over-Fibre Channel, with the link-layer header being the
Network_Header as described in that RFC.
.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
.TP 5
.B DLT_IEEE802_11_RADIO
link-layer information followed by an 802.11 header - see
http://www.shaftnet.org/~pizza/software/capturefrm.txt for a description
of the link-layer information.
.TP 5
.B DLT_ARCNET_LINUX
ARCNET, with no exception frames, reassembled packets rather than raw
frames, and an extra 16-bit offset field between the destination host
and type bytes.
.TP 5
.B DLT_LINUX_IRDA
Linux-IrDA packets, with a
.B DLT_LINUX_SLL
header followed by the IrLAP 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.  
.B \-1
is returned on failure.
.PP
.B pcap_datalink_val_to_name()
translates a data link type value to the corresponding data link type
name.  NULL is returned on failure.
.PP
.B pcap_datalink_val_to_description()
translates a data link type value to a short description of that data
link type.  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 file format of the savefile;
.B pcap_minor_version()
returns the minor number of the file format of the savefile.  The
version number is stored in the header of 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_get_selectable_fd()
returns, on UNIX, a file descriptor number for a file descriptor on
which one can
do a
.B select()
or
.B poll()
to wait for it to be possible to read packets without blocking, if such
a descriptor exists, or \-1, if no such descriptor exists.  Some network
devices opened with
.B pcap_open_live()
do not support
.B select()
or
.B poll()
(for example, regular network devices on FreeBSD 4.3 and 4.4, and Endace
DAG devices), so \-1 is returned for those devices.
.PP
Note that on most versions of most BSDs (including Mac OS X)
.B select()
and
.B poll()
do not work correctly on BPF devices;
.B pcap_get_selectable_fd()
will return a file descriptor on most of those versions (the exceptions
being FreeBSD 4.3 and 4.4), a simple
.B select()
or
.B poll()
will not return even after a timeout specified in
.B pcap_open_live()
expires.  To work around this, an application that uses
.B select()
or
.B poll()
to wait for packets to arrive must put the
.B pcap_t
in non-blocking mode, and must arrange that the
.B select()
or
.B poll()
have a timeout less than or equal to the timeout specified in
.BR pcap_open_live() ,
and must try to read packets after that timeout expires, regardless of
whether
.B select()
or
.B poll()
indicated that the file descriptor for the
.B pcap_t
is ready to be read or not.  (That workaround will not work in FreeBSD
4.3 and later; however, in FreeBSD 4.6 and later,
.B select()
and
.B poll()
work correctly on BPF devices, so the workaround isn't necessary,
although it does no harm.)
.PP
.B pcap_get_selectable_fd()
is not available on Windows.
.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_lib_version()
returns a pointer to a string giving information about the version of
the libpcap library being used; note that it contains more information
than just a version number.
.PP
.B pcap_close()
closes the files associated with
.I p
and deallocates resources.
.PP
.B pcap_dump_file()
returns the standard I/O stream of the ``savefile'' opened by
.BR pcap_dump_open().
.PP
.B pcap_dump_flush()
flushes the output buffer to the ``savefile,'' so that any packets
written with
.B pcap_dump()
but not yet written to the ``savefile'' will be written.
.B \-1
is returned on error, 0 on success.
.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
[e-mail]
.RE
.LP
Please send source code contributions, etc. to:
.LP
.RS
[e-mail]
.RE