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