1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
<table class="head">
<tr>
<td class="head-ltitle">BPF(9)</td>
<td class="head-vol">Kernel Developer's Manual</td>
<td class="head-rtitle">BPF(9)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">bpf</code> — <span class="Nd">Berkeley
Packet Filter</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">net/bpf.h</a>></code></p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">bpfattach</code>(<var class="Fa" style="white-space: nowrap;">struct
ifnet *ifp</var>, <var class="Fa" style="white-space: nowrap;">u_int
dlt</var>, <var class="Fa" style="white-space: nowrap;">u_int
hdrlen</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">bpfattach2</code>(<var class="Fa">struct ifnet *ifp</var>,
<var class="Fa">u_int dlt</var>, <var class="Fa">u_int hdrlen</var>,
<var class="Fa">struct bpf_if **driverp</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">bpfdetach</code>(<var class="Fa" style="white-space: nowrap;">struct
ifnet *ifp</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">bpf_tap</code>(<var class="Fa" style="white-space: nowrap;">struct
ifnet *ifp</var>, <var class="Fa" style="white-space: nowrap;">u_char
*pkt</var>, <var class="Fa" style="white-space: nowrap;">u_int
*pktlen</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">bpf_mtap</code>(<var class="Fa" style="white-space: nowrap;">struct
ifnet *ifp</var>, <var class="Fa" style="white-space: nowrap;">struct mbuf
*m</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">bpf_mtap2</code>(<var class="Fa" style="white-space: nowrap;">struct
bpf_if *bp</var>, <var class="Fa" style="white-space: nowrap;">void
*data</var>, <var class="Fa" style="white-space: nowrap;">u_int dlen</var>,
<var class="Fa" style="white-space: nowrap;">struct mbuf *m</var>);</p>
<p class="Pp"><var class="Ft">u_int</var>
<br/>
<code class="Fn">bpf_filter</code>(<var class="Fa">const struct bpf_insn *pc
</var>, <var class="Fa">u_char *pkt</var>, <var class="Fa">u_int
wirelen</var>, <var class="Fa">u_int buflen</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">bpf_validate</code>(<var class="Fa" style="white-space: nowrap;">const
struct bpf_insn *fcode</var>,
<var class="Fa" style="white-space: nowrap;">int flen</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">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 <code class="Nm">bpf</code> filter machine program. The
<a class="Xr">bpf(4)</a> manual page describes the interface used by user
programs. This manual page describes the functions used by interfaces to
pass packets to <code class="Nm">bpf</code> and the functions for testing
and running <code class="Nm">bpf</code> filter machine programs.</p>
<p class="Pp" id="bpfattach">The
<a class="permalink" href="#bpfattach"><code class="Fn">bpfattach</code></a>()
function attaches a network interface to <code class="Nm">bpf</code>. The
<var class="Fa">ifp</var> argument is a pointer to the structure that
defines the interface to be attached to an interface. The
<var class="Fa">dlt</var> argument is the data link-layer type:
<code class="Dv">DLT_NULL</code> (no link-layer encapsulation),
<code class="Dv">DLT_EN10MB</code> (Ethernet),
<code class="Dv">DLT_IEEE802_11</code> (802.11 wireless networks), etc. The
rest of the link layer types can be found in
<code class="In"><<a class="In">net/bpf.h</a>></code>. The
<var class="Fa">hdrlen</var> argument is the fixed size of the link header;
variable length headers are not yet supported. The
<code class="Nm">bpf</code> system will hold a pointer to
<var class="Fa">ifp->if_bpf</var>. This variable will set to a
non-<code class="Dv">NULL</code> value when <code class="Nm">bpf</code>
requires packets from this interface to be tapped using the functions
below.</p>
<p class="Pp" id="bpfattach2">The
<a class="permalink" href="#bpfattach2"><code class="Fn">bpfattach2</code></a>()
function allows multiple <code class="Nm">bpf</code> instances to be
attached to a single interface, by registering an explicit
<var class="Fa">if_bpf</var> rather than using
<var class="Fa">ifp->if_bpf</var>. It is then possible to run
<a class="Xr">tcpdump(1)</a> on the interface for any data link-layer types
attached.</p>
<p class="Pp" id="bpfdetach">The
<a class="permalink" href="#bpfdetach"><code class="Fn">bpfdetach</code></a>()
function detaches a <code class="Nm">bpf</code> instance from an interface,
specified by <var class="Fa">ifp</var>. The
<code class="Fn">bpfdetach</code>() function should be called once for each
<code class="Nm">bpf</code> instance attached.</p>
<p class="Pp" id="bpf_tap">The
<a class="permalink" href="#bpf_tap"><code class="Fn">bpf_tap</code></a>()
function is used by an interface to pass the packet to
<code class="Nm">bpf</code>. The packet data (including link-header),
pointed to by <var class="Fa">pkt</var>, is of length
<var class="Fa">pktlen</var>, which must be a contiguous buffer. The
<var class="Fa">ifp</var> 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.</p>
<p class="Pp" id="bpf_mtap">The
<a class="permalink" href="#bpf_mtap"><code class="Fn">bpf_mtap</code></a>()
function is like <code class="Fn">bpf_tap</code>() except that it is used to
tap packets that are in an <var class="Vt">mbuf</var> chain,
<var class="Fa">m</var>. The <var class="Fa">ifp</var> argument is a pointer
to the structure that defines the interface to be tapped. Like
<code class="Fn">bpf_tap</code>(), <code class="Fn">bpf_mtap</code>()
requires a link-header for whatever data link layer type is specified. Note
that <code class="Nm">bpf</code> only reads from the
<var class="Vt">mbuf</var> chain, it does not free it or keep a pointer to
it. This means that an <var class="Vt">mbuf</var> containing the link-header
can be prepended to the chain if necessary. A cleaner interface to achieve
this is provided by <code class="Fn">bpf_mtap2</code>().</p>
<p class="Pp" id="bpf_mtap2">The
<a class="permalink" href="#bpf_mtap2"><code class="Fn">bpf_mtap2</code></a>()
function allows the user to pass a link-header <var class="Fa">data</var>,
of length <var class="Fa">dlen</var>, independent of the
<var class="Vt">mbuf</var> <var class="Fa">m</var>, containing the packet.
This simplifies the passing of some link-headers.</p>
<p class="Pp" id="bpf_filter">The
<a class="permalink" href="#bpf_filter"><code class="Fn">bpf_filter</code></a>()
function executes the filter program starting at <var class="Fa">pc</var> on
the packet <var class="Fa">pkt</var>. The <var class="Fa">wirelen</var>
argument is the length of the original packet and
<var class="Fa">buflen</var> is the amount of data present. The
<var class="Fa">buflen</var> value of 0 is special; it indicates that the
<var class="Fa">pkt</var> is actually a pointer to an mbuf chain
(<var class="Vt">struct mbuf *</var>).</p>
<p class="Pp" id="bpf_validate">The
<a class="permalink" href="#bpf_validate"><code class="Fn">bpf_validate</code></a>()
function checks that the filter code <var class="Fa">fcode</var>, of length
<var class="Fa">flen</var>, is valid.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN
VALUES</a></h1>
<p class="Pp">The <code class="Fn">bpf_filter</code>() function returns -1 (cast
to an unsigned integer) if there is no filter. Otherwise, it returns the
result of the filter program.</p>
<p class="Pp">The <code class="Fn">bpf_validate</code>() function returns 0 when
the program is not a valid filter program.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="EVENT_HANDLERS"><a class="permalink" href="#EVENT_HANDLERS">EVENT
HANDLERS</a></h1>
<p class="Pp"><code class="Nm">bpf</code> invokes
<var class="Fa">bpf_track</var> <a class="Xr">EVENTHANDLER(9)</a> event each
time listener attaches to or detaches from an interface. Pointer to
(<var class="Vt">struct ifnet *</var>) is passed as the first argument,
interface <var class="Fa">dlt</var> follows. Last argument indicates
listener is attached (1) or detached (0). Note that handler is invoked with
<code class="Nm">bpf</code> global lock held, which implies restriction on
sleeping and calling <code class="Nm">bpf</code> subsystem inside
<a class="Xr">EVENTHANDLER(9)</a> dispatcher. Note that handler is not
called for write-only listeners.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">tcpdump(1)</a>, <a class="Xr">bpf(4)</a>,
<a class="Xr">EVENTHANDLER(9)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">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 <span class="Ux">BSD</span> 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.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp"><span class="An">Steven McCanne</span>, of Lawrence Berkeley
Laboratory, implemented BPF in Summer 1990. Much of the design is due to
<span class="An">Van Jacobson</span>. This manpage was written by
<span class="An">Orla McGann</span>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">May 11, 2012</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
