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