NAME¶
bpf
—
Berkeley Packet Filter
SYNOPSIS¶
#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);
DESCRIPTION¶
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.
RETURN VALUES¶
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.
EVENT HANDLERS¶
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.
SEE ALSO¶
tcpdump(1),
bpf(4),
EVENTHANDLER(9)
HISTORY¶
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.
AUTHORS¶
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.