xref: /netbsd/share/man/man4/bpf.4 (revision c4a72b64)
1.\" -*- nroff -*-
2.\"
3.\"	$NetBSD: bpf.4,v 1.22 2002/10/16 20:05:20 wennmach Exp $
4.\"
5.\" Copyright (c) 1990, 1991, 1992, 1993, 1994
6.\"	The Regents of the University of California.  All rights reserved.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that: (1) source code distributions
10.\" retain the above copyright notice and this paragraph in its entirety, (2)
11.\" distributions including binary code include the above copyright notice and
12.\" this paragraph in its entirety in the documentation or other materials
13.\" provided with the distribution, and (3) all advertising materials mentioning
14.\" features or use of this software display the following acknowledgement:
15.\" ``This product includes software developed by the University of California,
16.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
17.\" the University nor the names of its contributors may be used to endorse
18.\" or promote products derived from this software without specific prior
19.\" written permission.
20.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
21.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
22.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
23.\"
24.\" This document is derived in part from the enet man page (enet.4)
25.\" distributed with 4.3BSD Unix.
26.\"
27.Dd August 29, 2002
28.Dt BPF 4
29.Os
30.Sh NAME
31.Nm bpf
32.Nd Berkeley Packet Filter raw network interface
33.Sh SYNOPSIS
34.Cd "pseudo-device bpfilter 16"
35.Sh DESCRIPTION
36The Berkeley Packet Filter
37provides a raw interface to data link layers in a protocol
38independent fashion.
39All packets on the network, even those destined for other hosts,
40are accessible through this mechanism.
41.Pp
42The packet filter appears as a character special device,
43.Pa /dev/bpf0 ,
44.Pa /dev/bpf1 ,
45etc.
46After opening the device, the file descriptor must be bound to a
47specific network interface with the
48.Dv BIOSETIF
49ioctl.
50A given interface can be shared by multiple listeners, and the filter
51underlying each descriptor will see an identical packet stream.
52The total number of open
53files is limited to the value given in the kernel configuration; the
54example given in the SYNOPSIS above 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
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 "" .
74This size is returned by the
75.Dv BIOCGBLEN
76ioctl (see below), and under
77BSD, can 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, SLIP and PPP drivers have been
84modified to interact with
85.Nm "" .
86.Pp
87Since packet data is in network byte order, applications should use the
88.Xr byteorder 3
89macros to extract multi-byte values.
90.Pp
91A packet can be sent out on the network by writing to a
92.Nm
93file descriptor.  The writes are unbuffered, meaning only one
94packet can be processed per write.
95Currently, only writes to Ethernets and SLIP links are supported.
96.Sh IOCTLS
97The
98.Xr ioctl 2
99command codes below are defined in \*[Lt]net/bpf.h\*[Gt].  All commands require
100these includes:
101.Bd -literal -offset indent
102#include \*[Lt]sys/types.h\*[Gt]
103#include \*[Lt]sys/time.h\*[Gt]
104#include \*[Lt]sys/ioctl.h\*[Gt]
105#include \*[Lt]net/bpf.h\*[Gt]
106.Ed
107.Pp
108Additionally,
109.Dv BIOCGETIF
110and
111.Dv BIOCSETIF
112require
113.Pa \*[Lt]net/if.h\*[Gt] .
114.Pp
115The (third) argument to the
116.Xr ioctl 2
117should be a pointer to the type indicated.
118.Bl -tag -width indent -offset indent
119.It Dv "BIOCGBLEN (u_int)"
120Returns the required buffer length for reads on
121.Nm
122files.
123.It Dv "BIOCSBLEN (u_int)"
124Sets the buffer length for reads on
125.Nm
126files.  The buffer must be set before the file is attached to an interface
127with
128.Dv BIOCSETIF .
129If the requested buffer size cannot be accommodated, the closest
130allowable size will be set and returned in the argument.
131A read call will result in EIO if it is passed a buffer that is not this size.
132.It Dv BIOCGDLT (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 \*[Lt]net/bpf.h\*[Gt].
139.It Dv BIOCGDLTLIST (struct bpf_dltlist)
140Returns an array of available type of the data link layer
141underlying the attached interface:
142.Bd -literal -offset indent
143struct bpf_dltlist {
144	u_int bfl_len;
145	u_int *bfl_list;
146};
147.Ed
148.Pp
149The available type is returned to the array pointed to the
150.Va bfl_list
151field while its length in u_int is supplied to the
152.Va bfl_len
153field.
154.Er ENOMEM
155is returned if there is not enough buffer.  The
156.Va bfl_len
157field is modified on return to indicate the actual length in u_int
158of the array returned.
159If
160.Va bfl_list
161is
162Dv NULL ,
163the
164.Va bfl_len
165field is returned to indicate the required length of an array in u_int.
166.It Dv BIOCSDLT (u_int)
167Change the type of the data link layer underlying the attached interface.
168.Er EINVAL
169is returned if no interface has been specified or the specified
170type is not available for the interface.
171.It Dv BIOCPROMISC
172Forces the interface into promiscuous mode.
173All packets, not just those destined for the local host, are processed.
174Since more than one file can be listening on a given interface,
175a listener that opened its interface non-promiscuously may receive
176packets promiscuously.  This problem can be remedied with an
177appropriate filter.
178.Pp
179The interface remains in promiscuous mode until all files listening
180promiscuously are closed.
181.It Dv BIOCFLUSH
182Flushes the buffer of incoming packets,
183and resets the statistics that are returned by
184.Dv BIOCGSTATS .
185.It Dv BIOCGETIF (struct ifreq)
186Returns the name of the hardware interface that the file is listening on.
187The name is returned in the ifr_name field of
188.Fa ifr .
189All other fields are undefined.
190.It Dv BIOCSETIF (struct ifreq)
191Sets the hardware interface associate with the file.  This
192command must be performed before any packets can be read.
193The device is indicated by name using the
194.Dv ifr_name
195field of the
196.Fa ifreq .
197Additionally, performs the actions of
198.Dv BIOCFLUSH .
199.It Dv BIOCSRTIMEOUT, BIOCGRTIMEOUT (struct timeval)
200Set or get the read timeout parameter.
201The
202.Fa timeval
203specifies the length of time to wait before timing
204out on a read request.
205This parameter is initialized to zero by
206.Xr open 2 ,
207indicating no timeout.
208.It Dv BIOCGSTATS (struct bpf_stat)
209Returns the following structure of packet statistics:
210.Bd -literal -offset indent
211struct bpf_stat {
212	u_int bs_recv;
213	u_int bs_drop;
214};
215.Ed
216.Pp
217The fields are:
218.Bl -tag -width bs_recv -offset indent
219.It Va bs_recv
220the number of packets received by the descriptor since opened or reset
221(including any buffered since the last read call);
222and
223.It Va bs_drop
224the number of packets which were accepted by the filter but dropped by the
225kernel because of buffer overflows
226(i.e., the application's reads aren't keeping up with the packet traffic).
227.El
228.It Dv BIOCIMMEDIATE (u_int)
229Enable or disable
230.Dq immediate mode ,
231based on the truth value of the argument.
232When immediate mode is enabled, reads return immediately upon packet
233reception.  Otherwise, a read will block until either the kernel buffer
234becomes full or a timeout occurs.
235This is useful for programs like
236.Xr rarpd 8 ,
237which must respond to messages in real time.
238The default for a new file is off.
239.It Dv BIOCSETF (struct bpf_program)
240Sets the filter program used by the kernel to discard uninteresting
241packets.  An array of instructions and its length is passed in using
242the following structure:
243.Bd -literal -offset indent
244struct bpf_program {
245	int bf_len;
246	struct bpf_insn *bf_insns;
247};
248.Ed
249.Pp
250The filter program is pointed to by the
251.Va bf_insns
252field while its length in units of
253.Sq struct bpf_insn
254is given by the
255.Va bf_len
256field.
257Also, the actions of
258.Dv BIOCFLUSH
259are performed.
260.Pp
261See section
262.Sy FILTER MACHINE
263for an explanation of the filter language.
264.It Dv BIOCVERSION (struct bpf_version)
265Returns the major and minor version numbers of the filter language currently
266recognized by the kernel.  Before installing a filter, applications must check
267that the current version is compatible with the running kernel.  Version
268numbers are compatible if the major numbers match and the application minor
269is less than or equal to the kernel minor.  The kernel version number is
270returned in the following structure:
271.Bd -literal -offset indent
272struct bpf_version {
273	u_short bv_major;
274	u_short bv_minor;
275};
276.Ed
277.Pp
278The current version numbers are given by
279.Dv BPF_MAJOR_VERSION
280and
281.Dv BPF_MINOR_VERSION
282from \*[Lt]net/bpf.h\*[Gt].
283An incompatible filter
284may result in undefined behavior (most likely, an error returned by
285.Xr ioctl 2
286or haphazard packet matching).
287.It Dv BIOCSRSIG BIOCGRSIG (u_int signal)
288Set or get the receive signal.  This signal will be sent to the process or process group
289specified by FIOSETOWN.  It defaults to SIGIO.
290.El
291.Sh STANDARD IOCTLS
292.Nm
293now supports several standard
294.Xr ioctl 2 's
295which allow the user to do async and/or non-blocking I/O to an open
296.I bpf
297file descriptor.
298.Bl -tag -width indent -offset indent
299.It Dv FIONREAD (int)
300Returns the number of bytes that are immediately available for reading.
301.It Dv SIOCGIFADDR (struct ifreq)
302Returns the address associated with the interface.
303.It Dv FIONBIO (int)
304Set or clear non-blocking I/O.  If arg is non-zero, then doing a
305.Xr read 2
306when no data is available will return -1 and
307.Va errno
308will be set to
309.Er EAGAIN .
310If arg is zero, non-blocking I/O is disabled.  Note:  setting this
311overrides the timeout set by
312.Dv BIOCSRTIMEOUT .
313.It Dv FIOASYNC (int)
314Enable or disable async I/O.  When enabled (arg is non-zero), the process or
315process group specified by FIOSETOWN will start receiving SIGIO's when packets
316arrive.
317Note that you must do an FIOSETOWN in order for this to take affect, as
318the system will not default this for you.
319The signal may be changed via
320.Dv BIOCSRSIG .
321.It Dv FIOSETOWN FIOGETOWN (int)
322Set or get the process or process group (if negative) that should receive SIGIO
323when packets are available.
324The signal may be changed using
325.Dv BIOCSRSIG
326(see above).
327.El
328.Sh BPF HEADER
329The following structure is prepended to each packet returned by
330.Xr read 2 :
331.Bd -literal -offset indent
332struct bpf_hdr {
333	struct timeval bh_tstamp;
334	u_long bh_caplen;
335	u_long bh_datalen;
336	u_short bh_hdrlen;
337};
338.Ed
339.Pp
340The fields, whose values are stored in host order, and are:
341.Bl -tag -width bh_datalen -offset indent
342.It Va bh_tstamp
343The time at which the packet was processed by the packet filter.
344.It Va bh_caplen
345The length of the captured portion of the packet.  This is the minimum of
346the truncation amount specified by the filter and the length of the packet.
347.It Va bh_datalen
348The length of the packet off the wire.
349This value is independent of the truncation amount specified by the filter.
350.It Va bh_hdrlen
351The length of the BPF header, which may not be equal to
352.Em sizeof(struct bpf_hdr) .
353.El
354.Pp
355The
356.Va bh_hdrlen
357field exists to account for
358padding between the header and the link level protocol.
359The purpose here is to guarantee proper alignment of the packet
360data structures, which is required on alignment sensitive
361architectures and and improves performance on many other architectures.
362The packet filter ensures that the
363.Va bpf_hdr
364and the
365.Em network layer
366header will be word aligned.  Suitable precautions
367must be taken when accessing the link layer protocol fields on alignment
368restricted machines.  (This isn't a problem on an Ethernet, since
369the type field is a short falling on an even offset,
370and the addresses are probably accessed in a bytewise fashion).
371.Pp
372Additionally, individual packets are padded so that each starts
373on a word boundary.  This requires that an application
374has some knowledge of how to get from packet to packet.
375The macro
376.Dv BPF_WORDALIGN
377is defined in
378.Pa \*[Lt]net/bpf.h\*[Gt]
379to facilitate this process.
380It rounds up its argument
381to the nearest word aligned value (where a word is BPF_ALIGNMENT bytes wide).
382.Pp
383For example, if
384.Sq Va p
385points to the start of a packet, this expression
386will advance it to the next packet:
387.Pp
388.Dl p = (char *)p + BPF_WORDALIGN(p-\*[Gt]bh_hdrlen + p-\*[Gt]bh_caplen)
389.Pp
390For the alignment mechanisms to work properly, the
391buffer passed to
392.Xr read 2
393must itself be word aligned.
394.Xr malloc 3
395will always return an aligned buffer.
396.Sh FILTER MACHINE
397A filter program is an array of instructions, with all branches forwardly
398directed, terminated by a
399.Sy return
400instruction.
401Each instruction performs some action on the pseudo-machine state,
402which consists of an accumulator, index register, scratch memory store,
403and implicit program counter.
404.Pp
405The following structure defines the instruction format:
406.Bd -literal -offset indent
407struct bpf_insn {
408	u_short	code;
409	u_char 	jt;
410	u_char 	jf;
411	long k;
412};
413.Ed
414.Pp
415The
416.Va k
417field is used in different ways by different instructions,
418and the
419.Va jt
420and
421.Va jf
422fields are used as offsets
423by the branch instructions.
424The opcodes are encoded in a semi-hierarchical fashion.
425There are eight classes of instructions: BPF_LD, BPF_LDX, BPF_ST, BPF_STX,
426BPF_ALU, BPF_JMP, BPF_RET, and BPF_MISC.  Various other mode and
427operator bits are or'd into the class to give the actual instructions.
428The classes and modes are defined in \*[Lt]net/bpf.h\*[Gt].
429.Pp
430Below are the semantics for each defined BPF instruction.
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,
436interpreted as a word (n=4),
437unsigned halfword (n=2), or unsigned byte (n=1).
438M[i] gives the i'th word in the scratch memory store, which is only
439addressed in word units.  The memory store is indexed from 0 to BPF_MEMWORDS-1.
440.Va k ,
441.Va jt ,
442and
443.Va jf
444are the corresponding fields in the
445instruction definition.
446.Dq len
447refers to the length of the packet.
448.Bl -tag -width indent -offset indent
449.It Sy BPF_LD
450These instructions copy a value into the accumulator.  The type of the
451source operand is specified by an
452.Dq addressing mode
453and can be a constant
454.Sy ( BBPF_IMM ) ,
455packet data at a fixed offset
456.Sy ( BPF_ABS ) ,
457packet data at a variable offset
458.Sy ( BPF_IND ) ,
459the packet length
460.Sy ( BPF_LEN ) ,
461or a word in the scratch memory store
462.Sy ( BPF_MEM ) .
463For
464.Sy BPF_IND
465and
466.Sy BPF_ABS ,
467the data size must be specified as a word
468.Sy ( BPF_W ) ,
469halfword
470.Sy ( BPF_H ) ,
471or byte
472.Sy ( BPF_B ) .
473The semantics of all the recognized BPF_LD instructions follow.
474.Bl -column "BPF_LD+BPF_W+BPF_ABS" "A \*[Lt]- P[k:4]" -width indent -offset indent
475.It Sy BPF_LD+BPF_W+BPF_ABS Ta A \*[Lt]- P[k:4]
476.It Li Sy BPF_LD+BPF_H+BPF_ABS Ta A \*[Lt]- P[k:2]
477.It Li Sy BPF_LD+BPF_B+BPF_ABS Ta A \*[Lt]- P[k:1]
478.It Li Sy BPF_LD+BPF_W+BPF_IND Ta A \*[Lt]- P[X+k:4]
479.It Li Sy BPF_LD+BPF_H+BPF_IND Ta A \*[Lt]- P[X+k:2]
480.It Li Sy BPF_LD+BPF_B+BPF_IND Ta A \*[Lt]- P[X+k:1]
481.It Li Sy BPF_LD+BPF_W+BPF_LEN Ta A \*[Lt]- len
482.It Li Sy BPF_LD+BPF_IMM Ta A \*[Lt]- k
483.It Li Sy BPF_LD+BPF_MEM Ta A \*[Lt]- M[k]
484.El
485.It Sy BPF_LDX
486These instructions load a value into the index register.  Note that
487the addressing modes are more restricted than those of the accumulator loads,
488but they include
489.Sy BPF_MSH ,
490a hack for efficiently loading the IP header length.
491.Bl -column "BPF_LDX+BPF_W+BPF_IMM" "X \*[Lt]- k" -width indent -offset indent
492.It Sy BPF_LDX+BPF_W+BPF_IMM Ta X \*[Lt]- k
493.It Li Sy BPF_LDX+BPF_W+BPF_MEM Ta X \*[Lt]- M[k]
494.It Li Sy BPF_LDX+BPF_W+BPF_LEN Ta X \*[Lt]- len
495.It Li Sy BPF_LDX+BPF_B+BPF_MSH Ta X \*[Lt]- 4*(P[k:1]\*[Am]0xf)
496.El
497.It Sy BPF_ST
498This instruction stores the accumulator into the scratch memory.
499We do not need an addressing mode since there is only one possibility
500for the destination.
501.Bl -column "BPF_ST" "M[k] \*[Lt]- A" -width indent -offset indent
502.It Sy BPF_ST Ta M[k] \*[Lt]- A
503.El
504.It Sy BPF_STX
505This instruction stores the index register in the scratch memory store.
506.Bl -column "BPF_STX" "M[k] \*[Lt]- X" -width indent -offset indent
507.It Sy BPF_STX Ta M[k] \*[Lt]- X
508.El
509.It Sy BPF_ALU
510The alu instructions perform operations between the accumulator and
511index register or constant, and store the result back in the accumulator.
512For binary operations, a source mode is required
513.Sy ( BPF_K
514or
515.Sy BPF_X ) .
516.Bl -column "BPF_ALU+BPF_ADD+BPF_K" "A \*[Lt]- A + k" -width indent -offset indent
517.It Sy BPF_ALU+BPF_ADD+BPF_K Ta A \*[Lt]- A + k
518.It Li Sy BPF_ALU+BPF_SUB+BPF_K Ta A \*[Lt]- A - k
519.It Li Sy BPF_ALU+BPF_MUL+BPF_K Ta A \*[Lt]- A * k
520.It Li Sy BPF_ALU+BPF_DIV+BPF_K Ta A \*[Lt]- A / k
521.It Li Sy BPF_ALU+BPF_AND+BPF_K Ta A \*[Lt]- A \*[Am] k
522.It Li Sy BPF_ALU+BPF_OR+BPF_K Ta A \*[Lt]- A | k
523.It Li Sy BPF_ALU+BPF_LSH+BPF_K Ta A \*[Lt]- A \*[Lt]\*[Lt] k
524.It Li Sy BPF_ALU+BPF_RSH+BPF_K Ta A \*[Lt]- A \*[Gt]\*[Gt] k
525.It Li Sy BPF_ALU+BPF_ADD+BPF_X Ta A \*[Lt]- A + X
526.It Li Sy BPF_ALU+BPF_SUB+BPF_X Ta A \*[Lt]- A - X
527.It Li Sy BPF_ALU+BPF_MUL+BPF_X Ta A \*[Lt]- A * X
528.It Li Sy BPF_ALU+BPF_DIV+BPF_X Ta A \*[Lt]- A / X
529.It Li Sy BPF_ALU+BPF_AND+BPF_X Ta A \*[Lt]- A \*[Am] X
530.It Li Sy BPF_ALU+BPF_OR+BPF_X Ta A \*[Lt]- A | X
531.It Li Sy BPF_ALU+BPF_LSH+BPF_X Ta A \*[Lt]- A \*[Lt]\*[Lt] X
532.It Li Sy BPF_ALU+BPF_RSH+BPF_X Ta A \*[Lt]- A \*[Gt]\*[Gt] X
533.It Li Sy BPF_ALU+BPF_NEG Ta A \*[Lt]- -A
534.El
535.It Sy BPF_JMP
536The jump instructions alter flow of control.  Conditional jumps
537compare the accumulator against a constant
538.Sy ( BPF_K )
539or the index register
540.Sy ( BPF_X ) .
541If the result is true (or non-zero),
542the true branch is taken, otherwise the false branch is taken.
543Jump offsets are encoded in 8 bits so the longest jump is 256 instructions.
544However, the jump always
545.Sy ( BPF_JA )
546opcode uses the 32 bit
547.Va k
548field as the offset, allowing arbitrarily distant destinations.
549All conditionals use unsigned comparison conventions.
550.Bl -column "BPF_JMP+BPF_JGE+BPF_K" "pc += (A \*[Ge] k) ? jt : jf" -width indent -offset indent
551.It Sy BPF_JMP+BPF_JA Ta pc += k
552.It Li Sy BPF_JMP+BPF_JGT+BPF_K Ta "pc += (A \*[Gt] k) ? jt : jf"
553.It Li Sy BPF_JMP+BPF_JGE+BPF_K Ta "pc += (A \*[Ge] k) ? jt : jf"
554.It Li Sy BPF_JMP+BPF_JEQ+BPF_K Ta "pc += (A == k) ? jt : jf"
555.It Li Sy BPF_JMP+BPF_JSET+BPF_K Ta "pc += (A \*[Am] k) ? jt : jf"
556.It Li Sy BPF_JMP+BPF_JGT+BPF_X Ta "pc += (A \*[Gt] X) ? jt : jf"
557.It Li Sy BPF_JMP+BPF_JGE+BPF_X Ta "pc += (A \*[Ge] X) ? jt : jf"
558.It Li Sy BPF_JMP+BPF_JEQ+BPF_X Ta "pc += (A == X) ? jt : jf"
559.It Li Sy BPF_JMP+BPF_JSET+BPF_X Ta "pc += (A \*[Am] X) ? jt : jf"
560.El
561.It Sy BPF_RET
562The return instructions terminate the filter program and specify the amount
563of packet to accept (i.e., they return the truncation amount).  A return
564value of zero indicates that the packet should be ignored.
565The return value is either a constant
566.Sy ( BPF_K )
567or the accumulator
568.Sy ( BPF_A ) .
569.Bl -column "BPF_RET+BPF_A" "accept A bytes" -width indent -offset indent
570.It Sy BPF_RET+BPF_A Ta accept A bytes
571.It Li Sy BPF_RET+BPF_K Ta accept k bytes
572.El
573.It Sy BPF_MISC
574The miscellaneous category was created for anything that doesn't
575fit into the above classes, and for any new instructions that might need to
576be added.  Currently, these are the register transfer instructions
577that copy the index register to the accumulator or vice versa.
578.Bl -column "BPF_MISC+BPF_TAX" "X \*[Lt]- A" -width indent -offset indent
579.It Sy BPF_MISC+BPF_TAX Ta X \*[Lt]- A
580.It Li Sy BPF_MISC+BPF_TXA Ta A \*[Lt]- X
581.El
582.El
583.Pp
584The BPF interface provides the following macros to facilitate
585array initializers:
586.Bd -unfilled -offset indent
587.Sy BPF_STMT No (opcode, operand)
588.Sy BPF_JUMP No (opcode, operand, true_offset, false_offset)
589.Ed
590.Sh FILES
591.Pa /dev/bpf0 ,
592.Pa /dev/bpf1 ,
593.Pa ...
594.Sh EXAMPLES
595The following filter is taken from the Reverse ARP Daemon.  It accepts
596only Reverse ARP requests.
597.Bd -literal -offset indent
598struct bpf_insn insns[] = {
599	BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
600	BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3),
601	BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
602	BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1),
603	BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) +
604	    sizeof(struct ether_header)),
605	BPF_STMT(BPF_RET+BPF_K, 0),
606};
607.Ed
608.Pp
609This filter accepts only IP packets between host 128.3.112.15 and
610128.3.112.35.
611.Bd -literal -offset indent
612struct bpf_insn insns[] = {
613	BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
614	BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8),
615	BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 26),
616	BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2),
617	BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30),
618	BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4),
619	BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3),
620	BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30),
621	BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1),
622	BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
623	BPF_STMT(BPF_RET+BPF_K, 0),
624};
625.Ed
626.Pp
627Finally, this filter returns only TCP finger packets.  We must parse
628the IP header to reach the TCP header.  The
629.Sy BPF_JSET
630instruction checks that the IP fragment offset is 0 so we are sure
631that we have a TCP header.
632.Bd -literal -offset indent
633struct bpf_insn insns[] = {
634	BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
635	BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10),
636	BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23),
637	BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8),
638	BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
639	BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0),
640	BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14),
641	BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14),
642	BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0),
643	BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16),
644	BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1),
645	BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
646	BPF_STMT(BPF_RET+BPF_K, 0),
647};
648.Ed
649.Sh SEE ALSO
650.Xr ioctl 2 ,
651.Xr read 2 ,
652.Xr select 2 ,
653.Xr signal 3 ,
654.Xr tcpdump 8
655.Rs
656.%T "The BSD Packet Filter: A New Architecture for User-level Packet Capture"
657.%A S. McCanne
658.%A V. Jacobson
659.%J Proceedings of the 1993 Winter USENIX
660.%C Technical Conference, San Diego, CA
661.Re
662.Sh HISTORY
663The Enet packet filter was created in 1980 by Mike Accetta and
664Rick Rashid at Carnegie-Mellon University.  Jeffrey Mogul, at
665Stanford, ported the code to BSD and continued its development from
6661983 on.  Since then, it has evolved into the Ultrix Packet Filter
667at DEC, a STREAMS NIT module under SunOS 4.1, and BPF.
668.Sh AUTHORS
669Steven McCanne, of Lawrence Berkeley Laboratory, implemented BPF in
670Summer 1990.  The design was in collaboration with Van Jacobson,
671also of Lawrence Berkeley Laboratory.
672.Sh BUGS
673The read buffer must be of a fixed size (returned by the
674.Dv BIOCGBLEN
675ioctl).
676.Pp
677A file that does not request promiscuous mode may receive promiscuously
678received packets as a side effect of another file requesting this
679mode on the same hardware interface.  This could be fixed in the kernel
680with additional processing overhead.  However, we favor the model where
681all files must assume that the interface is promiscuous, and if
682so desired, must utilize a filter to reject foreign packets.
683.Pp
684Data link protocols with variable length headers are not currently supported.
685.Pp
686Under SunOS, if a BPF application reads more than 2^31 bytes of
687data, read will fail in
688.Er EINVAL .
689You can either fix the bug in SunOS,
690or lseek to 0 when read fails for this reason.
691.Pp
692.Dq Immediate mode
693and the
694.Dq read timeout
695are misguided features.
696This functionality can be emulated with non-blocking mode and
697.Xr select 2 .
698