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