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