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