1.\" Copyright (c) 2004 FreeBSD Inc. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL [your name] OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd May 11, 2012 26.Dt BPF 9 27.Os 28.\" 29.Sh NAME 30.Nm bpf 31.Nd "Berkeley Packet Filter" 32.\" 33.Sh SYNOPSIS 34.In net/bpf.h 35.\" 36.Ft void 37.Fn bpfattach "struct ifnet *ifp" "u_int dlt" "u_int hdrlen" 38.Ft void 39.Fo bpfattach2 40.Fa "struct ifnet *ifp" "u_int dlt" "u_int hdrlen" "struct bpf_if **driverp" 41.Fc 42.Ft void 43.Fn bpfdetach "struct ifnet *ifp" 44.Ft void 45.Fn bpf_tap "struct ifnet *ifp" "u_char *pkt" "u_int *pktlen" 46.Ft void 47.Fn bpf_mtap "struct ifnet *ifp" "struct mbuf *m" 48.Ft void 49.Fn bpf_mtap2 "struct bpf_if *bp" "void *data" "u_int dlen" "struct mbuf *m" 50.Ft u_int 51.Fo bpf_filter 52.Fa "const struct bpf_insn *pc " "u_char *pkt" "u_int wirelen" "u_int buflen" 53.Fc 54.Ft int 55.Fn bpf_validate "const struct bpf_insn *fcode" "int flen" 56.\" 57.Sh DESCRIPTION 58The Berkeley Packet Filter provides a raw interface, 59that is protocol independent, 60to data link layers. 61It allows all packets on the network, 62even those destined for other hosts, 63to be passed from a network interface to user programs. 64Each program may specify a filter, 65in the form of a 66.Nm 67filter machine program. 68The 69.Xr bpf 4 70manual page 71describes the interface used by user programs. 72This manual page describes the functions used by interfaces to pass packets to 73.Nm 74and the functions for testing and running 75.Nm 76filter machine programs. 77.Pp 78The 79.Fn bpfattach 80function 81attaches a network interface to 82.Nm . 83The 84.Fa ifp 85argument 86is a pointer to the structure that defines the interface to be 87attached to an interface. 88The 89.Fa dlt 90argument 91is the data link-layer type: 92.Dv DLT_NULL 93(no link-layer encapsulation), 94.Dv DLT_EN10MB 95(Ethernet), 96.Dv DLT_IEEE802_11 97(802.11 wireless networks), 98etc. 99The rest of the link layer types can be found in 100.In net/bpf.h . 101The 102.Fa hdrlen 103argument 104is the fixed size of the link header; 105variable length headers are not yet supported. 106The 107.Nm 108system will hold a pointer to 109.Fa ifp->if_bpf . 110This variable will set to a 111.Pf non- Dv NULL 112value when 113.Nm 114requires packets from this interface to be tapped using the functions below. 115.Pp 116The 117.Fn bpfattach2 118function 119allows multiple 120.Nm 121instances to be attached to a single interface, 122by registering an explicit 123.Fa if_bpf 124rather than using 125.Fa ifp->if_bpf . 126It is then possible to run 127.Xr tcpdump 1 128on the interface for any data link-layer types attached. 129.Pp 130The 131.Fn bpfdetach 132function detaches a 133.Nm 134instance from an interface, 135specified by 136.Fa ifp . 137The 138.Fn bpfdetach 139function 140should be called once for each 141.Nm 142instance attached. 143.Pp 144The 145.Fn bpf_tap 146function 147is used by an interface to pass the packet to 148.Nm . 149The packet data (including link-header), 150pointed to by 151.Fa pkt , 152is of length 153.Fa pktlen , 154which must be a contiguous buffer. 155The 156.Fa ifp 157argument 158is a pointer to the structure that defines the interface to be tapped. 159The packet is parsed by each processes filter, 160and if accepted, 161it is buffered for the process to read. 162.Pp 163The 164.Fn bpf_mtap 165function is like 166.Fn bpf_tap 167except that it is used to tap packets that are in an 168.Vt mbuf 169chain, 170.Fa m . 171The 172.Fa ifp 173argument 174is a pointer to the structure that defines the interface to be tapped. 175Like 176.Fn bpf_tap , 177.Fn bpf_mtap 178requires a link-header for whatever data link layer type is specified. 179Note that 180.Nm 181only reads from the 182.Vt mbuf 183chain, 184it does not free it or keep a pointer to it. 185This means that an 186.Vt mbuf 187containing the link-header 188can be prepended to the chain if necessary. 189A cleaner interface to achieve this is provided by 190.Fn bpf_mtap2 . 191.Pp 192The 193.Fn bpf_mtap2 194function 195allows the user to pass a link-header 196.Fa data , 197of length 198.Fa dlen , 199independent of the 200.Vt mbuf 201.Fa m , 202containing the packet. 203This simplifies the passing of some link-headers. 204.Pp 205The 206.Fn bpf_filter 207function 208executes the filter program starting at 209.Fa pc 210on the packet 211.Fa pkt . 212The 213.Fa wirelen 214argument 215is the length of the original packet and 216.Fa buflen 217is the amount of data present. 218The 219.Fa buflen 220value of 0 is special; it indicates that the 221.Fa pkt 222is actually a pointer to an mbuf chain 223.Pq Vt "struct mbuf *" . 224.Pp 225The 226.Fn bpf_validate 227function 228checks that the filter code 229.Fa fcode , 230of length 231.Fa flen , 232is valid. 233.\" 234.Sh RETURN VALUES 235The 236.Fn bpf_filter 237function returns \-1 238(cast to an unsigned integer) 239if there is no filter. 240Otherwise, it returns the result of the filter program. 241.Pp 242The 243.Fn bpf_validate 244function 245returns 0 when the program is not a valid filter program. 246.\" 247.Sh EVENT HANDLERS 248.Nm 249invokes 250.Fa bpf_track 251.Xr EVENTHANDLER 9 252event each time listener attaches to or detaches from an interface. 253Pointer to 254.Pq Vt "struct ifnet *" 255is passed as the first argument, interface 256.Fa dlt 257follows. 258Last argument indicates listener is attached (1) or detached (0). 259Note that handler is invoked with 260.Nm 261global lock held, which implies restriction on sleeping and calling 262.Nm 263subsystem inside 264.Xr EVENTHANDLER 9 265dispatcher. 266Note that handler is not called for write-only listeners. 267.\" 268.Sh SEE ALSO 269.Xr tcpdump 1 , 270.Xr bpf 4 , 271.Xr EVENTHANDLER 9 272.\" 273.Sh HISTORY 274The Enet packet filter was created in 1980 by Mike Accetta and 275Rick Rashid at Carnegie-Mellon University. 276Jeffrey Mogul, 277at Stanford, 278ported the code to 279.Bx 280and continued its development from 1983 on. 281Since then, 282it has evolved into the Ultrix Packet Filter at 283.Tn DEC , 284a 285.Tn STREAMS 286.Tn NIT 287module under 288.Tn SunOS 2894.1, and 290.Tn BPF . 291.\" 292.Sh AUTHORS 293.An -nosplit 294.An Steven McCanne , 295of Lawrence Berkeley Laboratory, implemented BPF in Summer 1990. 296Much of the design is due to 297.An Van Jacobson . 298This manpage was written by 299.An Orla McGann . 300