share/man/man4/bpf.4

   1 .\" Copyright (c) 1990 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that: (1) source code distributions
   6 .\" retain the above copyright notice and this paragraph in its entirety, (2)
   7 .\" distributions including binary code include the above copyright notice and
   8 .\" this paragraph in its entirety in the documentation or other materials
   9 .\" provided with the distribution, and (3) all advertising materials mentioning
  10 .\" features or use of this software display the following acknowledgement:
  11 .\" ``This product includes software developed by the University of California,
  12 .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
  13 .\" the University nor the names of its contributors may be used to endorse
  14 .\" or promote products derived from this software without specific prior
  15 .\" written permission.
  16 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  17 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  18 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  19 .\"
  20 .\" This document is derived in part from the enet man page (enet.4)
  21 .\" distributed with 4.3BSD Unix.
  22 .\"
  23 .\" $FreeBSD: src/share/man/man4/bpf.4,v 1.21.2.11 2002/04/07 04:57:13 dd Exp $
  24 .\"
  25 .Dd January 16, 1996
  26 .Dt BPF 4
  27 .Os
  28 .Sh NAME
  29 .Nm bpf
  30 .Nd Berkeley Packet Filter
  31 .Sh SYNOPSIS
  32 .Cd pseudo-device bpf
  33 .Sh DESCRIPTION
  34 The Berkeley Packet Filter
  35 provides a raw interface to data link layers in a protocol
  36 independent fashion.
  37 All packets on the network, even those destined for other hosts,
  38 are accessible through this mechanism.
  39 .Pp
  40 The packet filter appears as a character special device,
  41 .Pa /dev/bpf0 ,
  42 .Pa /dev/bpf1 ,
  43 etc.
  44 After opening the device, the file descriptor must be bound to a
  45 specific network interface with the
  46 .Dv BIOCSETIF
  47 ioctl.
  48 A given interface can be shared by multiple listeners, and the filter
  49 underlying each descriptor will see an identical packet stream.
  50 .Pp
  51 A separate device file is required for each minor device.
  52 If a file is in use, the open will fail and
  53 .Va errno
  54 will be set to
  55 .Er EBUSY .
  56 .Pp
  57 Associated with each open instance of a
  58 .Nm
  59 file is a user-settable packet filter.
  60 Whenever a packet is received by an interface,
  61 all file descriptors listening on that interface apply their filter.
  62 Each descriptor that accepts the packet receives its own copy.
  63 .Pp
  64 Reads from these files return the next group of packets
  65 that have matched the filter.
  66 To improve performance, the buffer passed to read must be
  67 the same size as the buffers used internally by
  68 .Nm .
  69 This size is returned by the
  70 .Dv BIOCGBLEN
  71 ioctl (see below), and
  72 can be set with
  73 .Dv BIOCSBLEN .
  74 Note that an individual packet larger than this size is necessarily
  75 truncated.
  76 .Pp
  77 The packet filter will support any link level protocol that has fixed length
  78 headers.  Currently, only Ethernet,
  79 .Tn SLIP ,
  80 and
  81 .Tn PPP
  82 drivers have been modified to interact with
  83 .Nm .
  84 .Pp
  85 Since packet data is in network byte order, applications should use the
  86 .Xr byteorder 3
  87 macros to extract multi-byte values.
  88 .Pp
  89 A packet can be sent out on the network by writing to a
  90 .Nm
  91 file descriptor.  The writes are unbuffered, meaning only one
  92 packet can be processed per write.
  93 Currently, only writes to Ethernets and
  94 .Tn SLIP
  95 links are supported.
  96 .Sh IOCTLS
  97 The
  98 .Xr ioctl 2
  99 command codes below are defined in
 100 .Aq Pa net/bpf.h .
 101 All commands require
 102 these includes:
 103 .Bd -literal
 104         #include <sys/types.h>
 105         #include <sys/time.h>
 106         #include <sys/ioctl.h>
 107         #include <net/bpf.h>
 108 .Ed
 109 .Pp
 110 Additionally,
 111 .Dv BIOCGETIF
 112 and
 113 .Dv BIOCSETIF
 114 require
 115 .Aq Pa sys/socket.h
 116 and
 117 .Aq Pa net/if.h .
 118 .Pp
 119 In addition to
 120 .Dv FIONREAD
 121 and
 122 .Dv SIOCGIFADDR ,
 123 the following commands may be applied to any open
 124 .Nm
 125 file.
 126 The (third) argument to
 127 .Xr ioctl 2
 128 should be a pointer to the type indicated.
 129 .Bl -tag -width BIOCGRTIMEOUT
 130 .It Dv BIOCGBLEN
 131 .Pq Li u_int
 132 Returns the required buffer length for reads on
 133 .Nm
 134 files.
 135 .It Dv BIOCSBLEN
 136 .Pq Li u_int
 137 Sets the buffer length for reads on
 138 .Nm
 139 files.  The buffer must be set before the file is attached to an interface
 140 with
 141 .Dv BIOCSETIF .
 142 If the requested buffer size cannot be accommodated, the closest
 143 allowable size will be set and returned in the argument.
 144 A read call will result in
 145 .Er EIO
 146 if it is passed a buffer that is not this size.
 147 .It Dv BIOCGDLT
 148 .Pq Li u_int
 149 Returns the type of the data link layer underlying the attached interface.
 150 .Er EINVAL
 151 is returned if no interface has been specified.
 152 The device types, prefixed with
 153 .Dq Li DLT_ ,
 154 are defined in
 155 .Aq Pa net/bpf.h .
 156 .It Dv BIOCPROMISC
 157 Forces the interface into promiscuous mode.
 158 All packets, not just those destined for the local host, are processed.
 159 Since more than one file can be listening on a given interface,
 160 a listener that opened its interface non-promiscuously may receive
 161 packets promiscuously.  This problem can be remedied with an
 162 appropriate filter.
 163 .It Dv BIOCFLUSH
 164 Flushes the buffer of incoming packets,
 165 and resets the statistics that are returned by BIOCGSTATS.
 166 .It Dv BIOCGETIF
 167 .Pq Li "struct ifreq"
 168 Returns the name of the hardware interface that the file is listening on.
 169 The name is returned in the ifr_name field of
 170 the
 171 .Li ifreq
 172 structure.
 173 All other fields are undefined.
 174 .It Dv BIOCSETIF
 175 .Pq Li "struct ifreq"
 176 Sets the hardware interface associate with the file.  This
 177 command must be performed before any packets can be read.
 178 The device is indicated by name using the
 179 .Li ifr_name
 180 field of the
 181 .Li ifreq
 182 structure.
 183 Additionally, performs the actions of
 184 .Dv BIOCFLUSH .
 185 .It Dv BIOCSRTIMEOUT
 186 .It Dv BIOCGRTIMEOUT
 187 .Pq Li "struct timeval"
 188 Set or get the read timeout parameter.
 189 The argument
 190 specifies the length of time to wait before timing
 191 out on a read request.
 192 This parameter is initialized to zero by
 193 .Xr open 2 ,
 194 indicating no timeout.
 195 .It Dv BIOCGSTATS
 196 .Pq Li "struct bpf_stat"
 197 Returns the following structure of packet statistics:
 198 .Bd -literal
 199 struct bpf_stat {
 200         u_int bs_recv;    /* number of packets received */
 201         u_int bs_drop;    /* number of packets dropped */
 202 };
 203 .Ed
 204 .Pp
 205 The fields are:
 206 .Bl -hang -offset indent
 207 .It Li bs_recv
 208 the number of packets received by the descriptor since opened or reset
 209 (including any buffered since the last read call);
 210 and
 211 .It Li bs_drop
 212 the number of packets which were accepted by the filter but dropped by the
 213 kernel because of buffer overflows
 214 (i.e., the application's reads aren't keeping up with the packet traffic).
 215 .El
 216 .It Dv BIOCIMMEDIATE
 217 .Pq Li u_int
 218 Enable or disable
 219 .Dq immediate mode ,
 220 based on the truth value of the argument.
 221 When immediate mode is enabled, reads return immediately upon packet
 222 reception.  Otherwise, a read will block until either the kernel buffer
 223 becomes full or a timeout occurs.
 224 This is useful for programs like
 225 .Xr rarpd 8
 226 which must respond to messages in real time.
 227 The default for a new file is off.
 228 .It Dv BIOCSETF
 229 .Pq Li "struct bpf_program"
 230 Sets the filter program used by the kernel to discard uninteresting
 231 packets.  An array of instructions and its length is passed in using
 232 the following structure:
 233 .Bd -literal
 234 struct bpf_program {
 235         int bf_len;
 236         struct bpf_insn *bf_insns;
 237 };
 238 .Ed
 239 .Pp
 240 The filter program is pointed to by the
 241 .Li bf_insns
 242 field while its length in units of
 243 .Sq Li struct bpf_insn
 244 is given by the
 245 .Li bf_len
 246 field.
 247 Also, the actions of
 248 .Dv BIOCFLUSH
 249 are performed.
 250 See section
 251 .Sx "FILTER MACHINE"
 252 for an explanation of the filter language.
 253 .It Dv BIOCVERSION
 254 .Pq Li "struct bpf_version"
 255 Returns the major and minor version numbers of the filter language currently
 256 recognized by the kernel.  Before installing a filter, applications must check
 257 that the current version is compatible with the running kernel.  Version
 258 numbers are compatible if the major numbers match and the application minor
 259 is less than or equal to the kernel minor.  The kernel version number is
 260 returned in the following structure:
 261 .Bd -literal
 262 struct bpf_version {
 263         u_short bv_major;
 264         u_short bv_minor;
 265 };
 266 .Ed
 267 .Pp
 268 The current version numbers are given by
 269 .Dv BPF_MAJOR_VERSION
 270 and
 271 .Dv BPF_MINOR_VERSION
 272 from
 273 .Aq Pa net/bpf.h .
 274 An incompatible filter
 275 may result in undefined behavior (most likely, an error returned by
 276 .Fn ioctl
 277 or haphazard packet matching).
 278 .It Dv BIOCSHDRCMPLT
 279 .It Dv BIOCGHDRCMPLT
 280 .Pq Li u_int
 281 Set or get the status of the
 282 .Dq header complete
 283 flag.
 284 Set to zero if the link level source address should be filled in automatically
 285 by the interface output routine.  Set to one if the link level source
 286 address will be written, as provided, to the wire.  This flag is initialized
 287 to zero by default.
 288 .It Dv BIOCSSEESENT
 289 .It Dv BIOCGSEESENT
 290 .Pq Li u_int
 291 Set or get the flag determining whether locally generated packets on the
 292 interface should be returned by BPF.  Set to zero to see only incoming
 293 packets on the interface.  Set to one to see packets originating
 294 locally and remotely on the interface.  This flag is initialized to one by
 295 default.
 296 .El
 297 .Sh BPF HEADER
 298 The following structure is prepended to each packet returned by
 299 .Xr read 2 :
 300 .Bd -literal
 301 struct bpf_hdr {
 302         struct timeval bh_tstamp;     /* time stamp */
 303         u_long bh_caplen;             /* length of captured portion */
 304         u_long bh_datalen;            /* original length of packet */
 305         u_short bh_hdrlen;            /* length of bpf header (this struct
 306                                          plus alignment padding */
 307 };
 308 .Ed
 309 .Pp
 310 The fields, whose values are stored in host order, and are:
 311 .Pp
 312 .Bl -tag -compact -width bh_datalen
 313 .It Li bh_tstamp
 314 The time at which the packet was processed by the packet filter.
 315 .It Li bh_caplen
 316 The length of the captured portion of the packet.  This is the minimum of
 317 the truncation amount specified by the filter and the length of the packet.
 318 .It Li bh_datalen
 319 The length of the packet off the wire.
 320 This value is independent of the truncation amount specified by the filter.
 321 .It Li bh_hdrlen
 322 The length of the
 323 .Nm
 324 header, which may not be equal to
 325 .\" XXX - not really a function call
 326 .Fn sizeof "struct bpf_hdr" .
 327 .El
 328 .Pp
 329 The
 330 .Li bh_hdrlen
 331 field exists to account for
 332 padding between the header and the link level protocol.
 333 The purpose here is to guarantee proper alignment of the packet
 334 data structures, which is required on alignment sensitive
 335 architectures and improves performance on many other architectures.
 336 The packet filter insures that the
 337 .Li bpf_hdr
 338 and the network layer
 339 header will be word aligned.  Suitable precautions
 340 must be taken when accessing the link layer protocol fields on alignment
 341 restricted machines.  (This isn't a problem on an Ethernet, since
 342 the type field is a short falling on an even offset,
 343 and the addresses are probably accessed in a bytewise fashion).
 344 .Pp
 345 Additionally, individual packets are padded so that each starts
 346 on a word boundary.  This requires that an application
 347 has some knowledge of how to get from packet to packet.
 348 The macro
 349 .Dv BPF_WORDALIGN
 350 is defined in
 351 .Aq Pa net/bpf.h
 352 to facilitate
 353 this process.  It rounds up its argument
 354 to the nearest word aligned value (where a word is
 355 .Dv BPF_ALIGNMENT
 356 bytes wide).
 357 .Pp
 358 For example, if
 359 .Sq Li p
 360 points to the start of a packet, this expression
 361 will advance it to the next packet:
 362 .Dl p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen)
 363 .Pp
 364 For the alignment mechanisms to work properly, the
 365 buffer passed to
 366 .Xr read 2
 367 must itself be word aligned.
 368 The
 369 .Xr malloc 3
 370 function
 371 will always return an aligned buffer.
 372 .Sh FILTER MACHINE
 373 A filter program is an array of instructions, with all branches forwardly
 374 directed, terminated by a
 375 .Em return
 376 instruction.
 377 Each instruction performs some action on the pseudo-machine state,
 378 which consists of an accumulator, index register, scratch memory store,
 379 and implicit program counter.
 380 .Pp
 381 The following structure defines the instruction format:
 382 .Bd -literal
 383 struct bpf_insn {
 384         u_short code;
 385         u_char  jt;
 386         u_char  jf;
 387         u_long k;
 388 };
 389 .Ed
 390 .Pp
 391 The
 392 .Li k
 393 field is used in different ways by different instructions,
 394 and the
 395 .Li jt
 396 and
 397 .Li jf
 398 fields are used as offsets
 399 by the branch instructions.
 400 The opcodes are encoded in a semi-hierarchical fashion.
 401 There are eight classes of instructions:
 402 .Dv BPF_LD ,
 403 .Dv BPF_LDX ,
 404 .Dv BPF_ST ,
 405 .Dv BPF_STX ,
 406 .Dv BPF_ALU ,
 407 .Dv BPF_JMP ,
 408 .Dv BPF_RET ,
 409 and
 410 .Dv BPF_MISC .
 411 Various other mode and
 412 operator bits are or'd into the class to give the actual instructions.
 413 The classes and modes are defined in
 414 .Aq Pa net/bpf.h .
 415 .Pp
 416 Below are the semantics for each defined
 417 .Nm
 418 instruction.
 419 We use the convention that A is the accumulator, X is the index register,
 420 P[] packet data, and M[] scratch memory store.
 421 P[i:n] gives the data at byte offset
 422 .Dq i
 423 in the packet,
 424 interpreted as a word (n=4),
 425 unsigned halfword (n=2), or unsigned byte (n=1).
 426 M[i] gives the i'th word in the scratch memory store, which is only
 427 addressed in word units.  The memory store is indexed from 0 to
 428 .Dv BPF_MEMWORDS
 429 - 1.
 430 .Li k ,
 431 .Li jt ,
 432 and
 433 .Li jf
 434 are the corresponding fields in the
 435 instruction definition.
 436 .Dq len
 437 refers to the length of the packet.
 438 .Pp
 439 .Bl -tag -width BPF_STXx
 440 .It Dv BPF_LD
 441 These instructions copy a value into the accumulator.  The type of the
 442 source operand is specified by an
 443 .Dq addressing mode
 444 and can be a constant
 445 .Pq Dv BPF_IMM ,
 446 packet data at a fixed offset
 447 .Pq Dv BPF_ABS ,
 448 packet data at a variable offset
 449 .Pq Dv BPF_IND ,
 450 the packet length
 451 .Pq Dv BPF_LEN ,
 452 or a word in the scratch memory store
 453 .Pq Dv BPF_MEM .
 454 For
 455 .Dv BPF_IND
 456 and
 457 .Dv BPF_ABS ,
 458 the data size must be specified as a word
 459 .Pq Dv BPF_W ,
 460 halfword
 461 .Pq Dv BPF_H ,
 462 or byte
 463 .Pq Dv BPF_B .
 464 The semantics of all the recognized
 465 .Dv BPF_LD
 466 instructions follow.
 467 .Pp
 468 .Bl -tag -width "BPF_LD+BPF_W+BPF_IND" -compact
 469 .It Li BPF_LD+BPF_W+BPF_ABS
 470 A <- P[k:4]
 471 .It Li BPF_LD+BPF_H+BPF_ABS
 472 A <- P[k:2]
 473 .It Li BPF_LD+BPF_B+BPF_ABS
 474 A <- P[k:1]
 475 .It Li BPF_LD+BPF_W+BPF_IND
 476 A <- P[X+k:4]
 477 .It Li BPF_LD+BPF_H+BPF_IND
 478 A <- P[X+k:2]
 479 .It Li BPF_LD+BPF_B+BPF_IND
 480 A <- P[X+k:1]
 481 .It Li BPF_LD+BPF_W+BPF_LEN
 482 A <- len
 483 .It Li BPF_LD+BPF_IMM
 484 A <- k
 485 .It Li BPF_LD+BPF_MEM
 486 A <- M[k]
 487 .El
 488 .It Dv BPF_LDX
 489 These instructions load a value into the index register.  Note that
 490 the addressing modes are more restrictive than those of the accumulator loads,
 491 but they include
 492 .Dv BPF_MSH ,
 493 a hack for efficiently loading the IP header length.
 494 .Pp
 495 .Bl -tag -width "BPF_LDX+BPF_W+BPF_MEM" -compact
 496 .It Li BPF_LDX+BPF_W+BPF_IMM
 497 X <- k
 498 .It Li BPF_LDX+BPF_W+BPF_MEM
 499 X <- M[k]
 500 .It Li BPF_LDX+BPF_W+BPF_LEN
 501 X <- len
 502 .It Li BPF_LDX+BPF_B+BPF_MSH
 503 X <- 4*(P[k:1]&0xf)
 504 .El
 505 .It Dv BPF_ST
 506 This instruction stores the accumulator into the scratch memory.
 507 We do not need an addressing mode since there is only one possibility
 508 for the destination.
 509 .Pp
 510 .Bl -tag -width "BPF_ST" -compact
 511 .It Li BPF_ST
 512 M[k] <- A
 513 .El
 514 .It Dv BPF_STX
 515 This instruction stores the index register in the scratch memory store.
 516 .Pp
 517 .Bl -tag -width "BPF_STX" -compact
 518 .It Li BPF_STX
 519 M[k] <- X
 520 .El
 521 .It Dv BPF_ALU
 522 The alu instructions perform operations between the accumulator and
 523 index register or constant, and store the result back in the accumulator.
 524 For binary operations, a source mode is required
 525 .Dv ( BPF_K
 526 or
 527 .Dv BPF_X ) .
 528 .Pp
 529 .Bl -tag -width "BPF_ALU+BPF_MUL+BPF_K" -compact
 530 .It Li BPF_ALU+BPF_ADD+BPF_K
 531 A <- A + k
 532 .It Li BPF_ALU+BPF_SUB+BPF_K
 533 A <- A - k
 534 .It Li BPF_ALU+BPF_MUL+BPF_K
 535 A <- A * k
 536 .It Li BPF_ALU+BPF_DIV+BPF_K
 537 A <- A / k
 538 .It Li BPF_ALU+BPF_AND+BPF_K
 539 A <- A & k
 540 .It Li BPF_ALU+BPF_OR+BPF_K
 541 A <- A | k
 542 .It Li BPF_ALU+BPF_LSH+BPF_K
 543 A <- A << k
 544 .It Li BPF_ALU+BPF_RSH+BPF_K
 545 A <- A >> k
 546 .It Li BPF_ALU+BPF_ADD+BPF_X
 547 A <- A + X
 548 .It Li BPF_ALU+BPF_SUB+BPF_X
 549 A <- A - X
 550 .It Li BPF_ALU+BPF_MUL+BPF_X
 551 A <- A * X
 552 .It Li BPF_ALU+BPF_DIV+BPF_X
 553 A <- A / X
 554 .It Li BPF_ALU+BPF_AND+BPF_X
 555 A <- A & X
 556 .It Li BPF_ALU+BPF_OR+BPF_X
 557 A <- A | X
 558 .It Li BPF_ALU+BPF_LSH+BPF_X
 559 A <- A << X
 560 .It Li BPF_ALU+BPF_RSH+BPF_X
 561 A <- A >> X
 562 .It Li BPF_ALU+BPF_NEG
 563 A <- -A
 564 .El
 565 .It Dv BPF_JMP
 566 The jump instructions alter flow of control.  Conditional jumps
 567 compare the accumulator against a constant
 568 .Pq Dv BPF_K
 569 or the index register
 570 .Pq Dv BPF_X .
 571 If the result is true (or non-zero),
 572 the true branch is taken, otherwise the false branch is taken.
 573 Jump offsets are encoded in 8 bits so the longest jump is 256 instructions.
 574 However, the jump always
 575 .Pq Dv BPF_JA
 576 opcode uses the 32 bit
 577 .Li k
 578 field as the offset, allowing arbitrarily distant destinations.
 579 All conditionals use unsigned comparison conventions.
 580 .Pp
 581 .Bl -tag -width "BPF_JMP+BPF_KSET+BPF_X" -compact
 582 .It Li BPF_JMP+BPF_JA
 583 pc += k
 584 .It Li BPF_JMP+BPF_JGT+BPF_K
 585 pc += (A > k) ? jt : jf
 586 .It Li BPF_JMP+BPF_JGE+BPF_K
 587 pc += (A >= k) ? jt : jf
 588 .It Li BPF_JMP+BPF_JEQ+BPF_K
 589 pc += (A == k) ? jt : jf
 590 .It Li BPF_JMP+BPF_JSET+BPF_K
 591 pc += (A & k) ? jt : jf
 592 .It Li BPF_JMP+BPF_JGT+BPF_X
 593 pc += (A > X) ? jt : jf
 594 .It Li BPF_JMP+BPF_JGE+BPF_X
 595 pc += (A >= X) ? jt : jf
 596 .It Li BPF_JMP+BPF_JEQ+BPF_X
 597 pc += (A == X) ? jt : jf
 598 .It Li BPF_JMP+BPF_JSET+BPF_X
 599 pc += (A & X) ? jt : jf
 600 .El
 601 .It Dv BPF_RET
 602 The return instructions terminate the filter program and specify the amount
 603 of packet to accept (i.e., they return the truncation amount).  A return
 604 value of zero indicates that the packet should be ignored.
 605 The return value is either a constant
 606 .Pq Dv BPF_K
 607 or the accumulator
 608 .Pq Dv BPF_A .
 609 .Pp
 610 .Bl -tag -width "BPF_RET+BPF_K" -compact
 611 .It Li BPF_RET+BPF_A
 612 accept A bytes
 613 .It Li BPF_RET+BPF_K
 614 accept k bytes
 615 .El
 616 .It Dv BPF_MISC
 617 The miscellaneous category was created for anything that doesn't
 618 fit into the above classes, and for any new instructions that might need to
 619 be added.  Currently, these are the register transfer instructions
 620 that copy the index register to the accumulator or vice versa.
 621 .Pp
 622 .Bl -tag -width "BPF_MISC+BPF_TAX" -compact
 623 .It Li BPF_MISC+BPF_TAX
 624 X <- A
 625 .It Li BPF_MISC+BPF_TXA
 626 A <- X
 627 .El
 628 .El
 629 .Pp
 630 The
 631 .Nm
 632 interface provides the following macros to facilitate
 633 array initializers:
 634 .Fn BPF_STMT opcode operand
 635 and
 636 .Fn BPF_JUMP opcode operand true_offset false_offset .
 637 .Sh EXAMPLES
 638 The following filter is taken from the Reverse ARP Daemon.  It accepts
 639 only Reverse ARP requests.
 640 .Bd -literal
 641 struct bpf_insn insns[] = {
 642         BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
 643         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3),
 644         BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
 645         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1),
 646         BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) +
 647                  sizeof(struct ether_header)),
 648         BPF_STMT(BPF_RET+BPF_K, 0),
 649 };
 650 .Ed
 651 .Pp
 652 This filter accepts only IP packets between host 128.3.112.15 and
 653 128.3.112.35.
 654 .Bd -literal
 655 struct bpf_insn insns[] = {
 656         BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
 657         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8),
 658         BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 26),
 659         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2),
 660         BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30),
 661         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4),
 662         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3),
 663         BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30),
 664         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1),
 665         BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
 666         BPF_STMT(BPF_RET+BPF_K, 0),
 667 };
 668 .Ed
 669 .Pp
 670 Finally, this filter returns only TCP finger packets.  We must parse
 671 the IP header to reach the TCP header.  The
 672 .Dv BPF_JSET
 673 instruction
 674 checks that the IP fragment offset is 0 so we are sure
 675 that we have a TCP header.
 676 .Bd -literal
 677 struct bpf_insn insns[] = {
 678         BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
 679         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10),
 680         BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23),
 681         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8),
 682         BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
 683         BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0),
 684         BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14),
 685         BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14),
 686         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0),
 687         BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16),
 688         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1),
 689         BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
 690         BPF_STMT(BPF_RET+BPF_K, 0),
 691 };
 692 .Ed
 693 .Sh SEE ALSO
 694 .Xr tcpdump 1 ,
 695 .Xr ioctl 2 ,
 696 .Xr byteorder 3 ,
 697 .Xr ng_bpf 4
 698 .Rs
 699 .%A McCanne, S.
 700 .%A Jacobson V.
 701 .%T "An efficient, extensible, and portable network monitor"
 702 .Re
 703 .Sh FILES
 704 .Bl -tag -compact -width /dev/bpfXXX
 705 .It Pa /dev/bpf Ns Sy n
 706 the packet filter device
 707 .El
 708 .Sh BUGS
 709 The read buffer must be of a fixed size (returned by the
 710 .Dv BIOCGBLEN
 711 ioctl).
 712 .Pp
 713 A file that does not request promiscuous mode may receive promiscuously
 714 received packets as a side effect of another file requesting this
 715 mode on the same hardware interface.  This could be fixed in the kernel
 716 with additional processing overhead.  However, we favor the model where
 717 all files must assume that the interface is promiscuous, and if
 718 so desired, must utilize a filter to reject foreign packets.
 719 .Pp
 720 Data link protocols with variable length headers are not currently supported.
 721 .Sh HISTORY
 722 The Enet packet filter was created in 1980 by Mike Accetta and
 723 Rick Rashid at Carnegie-Mellon University.  Jeffrey Mogul, at
 724 Stanford, ported the code to
 725 .Bx
 726 and continued its development from
 727 1983 on.  Since then, it has evolved into the Ultrix Packet Filter
 728 at
 729 .Tn DEC ,
 730 a
 731 .Tn STREAMS
 732 .Tn NIT
 733 module under
 734 .Tn SunOS 4.1 ,
 735 and
 736 .Tn BPF .
 737 .Sh AUTHORS
 738 .An -nosplit
 739 .An Steven McCanne ,
 740 of Lawrence Berkeley Laboratory, implemented BPF in
 741 Summer 1990.  Much of the design is due to
 742 .An Van Jacobson .