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