| BPF(9) | Kernel Developer's Manual | BPF(9) |
bpf — Berkeley
Packet Filter
#include
<net/bpf.h>
void
bpfattach(struct
ifnet *ifp, u_int
dlt, u_int
hdrlen);
void
bpfattach2(struct ifnet *ifp,
u_int dlt, u_int hdrlen,
struct bpf_if **driverp);
void
bpfdetach(struct
ifnet *ifp);
void
bpf_tap(struct
ifnet *ifp, u_char
*pkt, u_int
*pktlen);
void
bpf_mtap(struct
ifnet *ifp, struct mbuf
*m);
void
bpf_mtap2(struct
bpf_if *bp, void
*data, u_int dlen,
struct mbuf *m);
u_int
bpf_filter(const struct bpf_insn *pc
, u_char *pkt, u_int
wirelen, u_int buflen);
int
bpf_validate(const
struct bpf_insn *fcode,
int flen);
The Berkeley Packet Filter provides a raw interface, that is
protocol independent, to data link layers. It allows all packets on the
network, even those destined for other hosts, to be passed from a network
interface to user programs. Each program may specify a filter, in the form
of a bpf filter machine program. The
bpf(4) manual page describes the interface used by user
programs. This manual page describes the functions used by interfaces to
pass packets to bpf and the functions for testing
and running bpf filter machine programs.
The
bpfattach()
function attaches a network interface to bpf. The
ifp argument is a pointer to the structure that
defines the interface to be attached to an interface. The
dlt argument is the data link-layer type:
DLT_NULL (no link-layer encapsulation),
DLT_EN10MB (Ethernet),
DLT_IEEE802_11 (802.11 wireless networks), etc. The
rest of the link layer types can be found in
<net/bpf.h>. The
hdrlen argument is the fixed size of the link header;
variable length headers are not yet supported. The
bpf system will hold a pointer to
ifp->if_bpf. This variable will set to a
non-NULL value when bpf
requires packets from this interface to be tapped using the functions
below.
The
bpfattach2()
function allows multiple bpf instances to be
attached to a single interface, by registering an explicit
if_bpf rather than using
ifp->if_bpf. It is then possible to run
tcpdump(1) on the interface for any data link-layer types
attached.
The
bpfdetach()
function detaches a bpf instance from an interface,
specified by ifp. The
bpfdetach() function should be called once for each
bpf instance attached.
The
bpf_tap()
function is used by an interface to pass the packet to
bpf. The packet data (including link-header),
pointed to by pkt, is of length
pktlen, which must be a contiguous buffer. The
ifp argument is a pointer to the structure that
defines the interface to be tapped. The packet is parsed by each processes
filter, and if accepted, it is buffered for the process to read.
The
bpf_mtap()
function is like bpf_tap() except that it is used to
tap packets that are in an mbuf chain,
m. The ifp argument is a pointer
to the structure that defines the interface to be tapped. Like
bpf_tap(), bpf_mtap()
requires a link-header for whatever data link layer type is specified. Note
that bpf only reads from the
mbuf chain, it does not free it or keep a pointer to
it. This means that an mbuf containing the link-header
can be prepended to the chain if necessary. A cleaner interface to achieve
this is provided by bpf_mtap2().
The
bpf_mtap2()
function allows the user to pass a link-header data,
of length dlen, independent of the
mbuf m, containing the packet.
This simplifies the passing of some link-headers.
The
bpf_filter()
function executes the filter program starting at pc on
the packet pkt. The wirelen
argument is the length of the original packet and
buflen is the amount of data present. The
buflen value of 0 is special; it indicates that the
pkt is actually a pointer to an mbuf chain
(struct mbuf *).
The
bpf_validate()
function checks that the filter code fcode, of length
flen, is valid.
The bpf_filter() function returns -1 (cast
to an unsigned integer) if there is no filter. Otherwise, it returns the
result of the filter program.
The bpf_validate() function returns 0 when
the program is not a valid filter program.
bpf invokes
bpf_track EVENTHANDLER(9) event each
time listener attaches to or detaches from an interface. Pointer to
(struct ifnet *) is passed as the first argument,
interface dlt follows. Last argument indicates
listener is attached (1) or detached (0). Note that handler is invoked with
bpf global lock held, which implies restriction on
sleeping and calling bpf subsystem inside
EVENTHANDLER(9) dispatcher. Note that handler is not
called for write-only listeners.
The Enet packet filter was created in 1980 by Mike Accetta and Rick Rashid at Carnegie-Mellon University. Jeffrey Mogul, at Stanford, ported the code to BSD and continued its development from 1983 on. Since then, it has evolved into the Ultrix Packet Filter at DEC, a STREAMS NIT module under SunOS 4.1, and BPF.
Steven McCanne, of Lawrence Berkeley Laboratory, implemented BPF in Summer 1990. Much of the design is due to Van Jacobson. This manpage was written by Orla McGann.
| May 11, 2012 | Debian |