454 lines
12 KiB
Groff
454 lines
12 KiB
Groff
.\" @(#) $Header: /tcpdump/master/libpcap/pcap.3,v 1.17.2.1 2001/01/18 04:42:11 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
|
|
.ft B
|
|
pcap_t *pcap_open_live(char *device, int snaplen,
|
|
.ti +8
|
|
int promisc, int to_ms, char *ebuf)
|
|
pcap_t *pcap_open_dead(int linktype, int snaplen)
|
|
pcap_t *pcap_open_offline(char *fname, char *ebuf)
|
|
pcap_dumper_t *pcap_dump_open(pcap_t *p, char *fname)
|
|
.ft
|
|
.LP
|
|
.ft B
|
|
char errbuf[PCAP_ERRBUF_SIZE];
|
|
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
|
|
.B pcap_open_live(),
|
|
.B pcap_open_offline(),
|
|
.B 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 ebuf
|
|
is used to return error text and is only set when
|
|
.B pcap_open_live()
|
|
fails and returns
|
|
.BR NULL .
|
|
.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 ebuf
|
|
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_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()
|
|
returns a
|
|
.I u_char
|
|
pointer to the next packet.
|
|
.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() .
|
|
.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, e.g.
|
|
.BR DLT_EN10MB .
|
|
.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 name of the ``savefile.''
|
|
.PP
|
|
.B int 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 under lying
|
|
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() .
|
|
.PP
|
|
.B pcap_fileno()
|
|
returns the file descriptor number of the ``savefile.''
|
|
.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
|