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