Cross Reference: /freebsd-10.2-release/share/man/man4/bpf.4

Deleted Added

sdiff udiff text old ( 71895 ) new ( 76175 )

full compact

bpf.4 (71895)	bpf.4 (76175)
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 --- 6 unchanged lines hidden (view full) --- 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.\"	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 --- 6 unchanged lines hidden (view full) --- 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 71895 2001-02-01 16:38:02Z ru $	23.\" $FreeBSD: head/share/man/man4/bpf.4 76175 2001-05-01 09:15:30Z schweikh $
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	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	32.Cd 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, --- 18 unchanged lines hidden (view full) --- 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.	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, --- 18 unchanged lines hidden (view full) --- 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.	67Each descriptor that accepts the packet receives its own copy.
68.Pp 69Reads from these files return the next group of packets	68.Pp 69Reads from these files return the next group of packets
70that have matched the filter.	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	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	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	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,	83headers. Currently, only Ethernet,
84.Tn SLIP , 85and 86.Tn PPP 87drivers have been modified to interact with 88.Nm . 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 96file descriptor. The writes are unbuffered, meaning only one 97packet can be processed per write. 98Currently, only writes to Ethernets and 99.Tn SLIP	84.Tn SLIP , 85and 86.Tn PPP 87drivers have been modified to interact with 88.Nm . 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 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.	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>	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>	112 #include
113.Ed 114.Pp	113.Ed 114.Pp
115Additionally,	115Additionally,
116.Dv BIOCGETIF 117and 118.Dv BIOCSETIF 119require 120.Aq Pa sys/socket.h 121and 122.Aq Pa net/if.h . 123.Pp --- 17 unchanged lines hidden (view full) --- 141.Pq Li u_int 142Sets the buffer length for reads on 143.Nm 144files. The buffer must be set before the file is attached to an interface 145with 146.Dv BIOCSETIF . 147If the requested buffer size cannot be accommodated, the closest 148allowable size will be set and returned in the argument.	116.Dv BIOCGETIF 117and 118.Dv BIOCSETIF 119require 120.Aq Pa sys/socket.h 121and 122.Aq Pa net/if.h . 123.Pp --- 17 unchanged lines hidden (view full) --- 141.Pq Li u_int 142Sets the buffer length for reads on 143.Nm 144files. The buffer must be set before the file is attached to an interface 145with 146.Dv BIOCSETIF . 147If the requested buffer size cannot be accommodated, the closest 148allowable size will be set and returned in the argument.
149A read call will result in	149A read call will result in
150.Er EIO 151if it is passed a buffer that is not this size. 152.It Dv BIOCGDLT 153.Pq Li u_int 154Returns the type of the data link layer underlying the attached interface. 155.Er EINVAL 156is returned if no interface has been specified. 157The device types, prefixed with 158.Dq Li DLT_ , 159are defined in 160.Aq Pa net/bpf.h . 161.It Dv BIOCPROMISC 162Forces the interface into promiscuous mode. 163All packets, not just those destined for the local host, are processed. 164Since more than one file can be listening on a given interface, 165a listener that opened its interface non-promiscuously may receive 166packets promiscuously. This problem can be remedied with an	150.Er EIO 151if it is passed a buffer that is not this size. 152.It Dv BIOCGDLT 153.Pq Li u_int 154Returns the type of the data link layer underlying the attached interface. 155.Er EINVAL 156is returned if no interface has been specified. 157The device types, prefixed with 158.Dq Li DLT_ , 159are defined in 160.Aq Pa net/bpf.h . 161.It Dv BIOCPROMISC 162Forces the interface into promiscuous mode. 163All packets, not just those destined for the local host, are processed. 164Since more than one file can be listening on a given interface, 165a listener that opened its interface non-promiscuously may receive 166packets promiscuously. This problem can be remedied with an
167appropriate filter.	167appropriate filter.
168.It Dv BIOCFLUSH 169Flushes the buffer of incoming packets, 170and resets the statistics that are returned by BIOCGSTATS. 171.It Dv BIOCGETIF 172.Pq Li "struct ifreq" 173Returns the name of the hardware interface that the file is listening on. 174The name is returned in the ifr_name field of 175the --- 4 unchanged lines hidden (view full) --- 180.Pq Li "struct ifreq" 181Sets the hardware interface associate with the file. This 182command must be performed before any packets can be read. 183The device is indicated by name using the 184.Li ifr_name 185field of the 186.Li ifreq 187structure.	168.It Dv BIOCFLUSH 169Flushes the buffer of incoming packets, 170and resets the statistics that are returned by BIOCGSTATS. 171.It Dv BIOCGETIF 172.Pq Li "struct ifreq" 173Returns the name of the hardware interface that the file is listening on. 174The name is returned in the ifr_name field of 175the --- 4 unchanged lines hidden (view full) --- 180.Pq Li "struct ifreq" 181Sets the hardware interface associate with the file. This 182command must be performed before any packets can be read. 183The device is indicated by name using the 184.Li ifr_name 185field of the 186.Li ifreq 187structure.
188Additionally, performs the actions of	188Additionally, performs the actions of
189.Dv BIOCFLUSH . 190.It Dv BIOCSRTIMEOUT 191.It Dv BIOCGRTIMEOUT 192.Pq Li "struct timeval" 193Set or get the read timeout parameter. 194The argument 195specifies the length of time to wait before timing 196out on a read request. --- 10 unchanged lines hidden (view full) --- 207}; 208.Ed 209.Pp 210The fields are: 211.Bl -hang -offset indent 212.It Li bs_recv 213the number of packets received by the descriptor since opened or reset 214(including any buffered since the last read call);	189.Dv BIOCFLUSH . 190.It Dv BIOCSRTIMEOUT 191.It Dv BIOCGRTIMEOUT 192.Pq Li "struct timeval" 193Set or get the read timeout parameter. 194The argument 195specifies the length of time to wait before timing 196out on a read request. --- 10 unchanged lines hidden (view full) --- 207}; 208.Ed 209.Pp 210The fields are: 211.Bl -hang -offset indent 212.It Li bs_recv 213the number of packets received by the descriptor since opened or reset 214(including any buffered since the last read call);
215and	215and
216.It Li bs_drop 217the number of packets which were accepted by the filter but dropped by the 218kernel because of buffer overflows 219(i.e., the application's reads aren't keeping up with the packet traffic). 220.El 221.It Dv BIOCIMMEDIATE 222.Pq Li u_int 223Enable or disable 224.Dq immediate mode , 225based on the truth value of the argument. 226When immediate mode is enabled, reads return immediately upon packet 227reception. Otherwise, a read will block until either the kernel buffer 228becomes full or a timeout occurs. 229This is useful for programs like 230.Xr rarpd 8 231which must respond to messages in real time.	216.It Li bs_drop 217the number of packets which were accepted by the filter but dropped by the 218kernel because of buffer overflows 219(i.e., the application's reads aren't keeping up with the packet traffic). 220.El 221.It Dv BIOCIMMEDIATE 222.Pq Li u_int 223Enable or disable 224.Dq immediate mode , 225based on the truth value of the argument. 226When immediate mode is enabled, reads return immediately upon packet 227reception. Otherwise, a read will block until either the kernel buffer 228becomes full or a timeout occurs. 229This is useful for programs like 230.Xr rarpd 8 231which must respond to messages in real time.
232The default for a new file is off.	232The default for a new file is off.
233.It Dv BIOCSETF 234.Pq Li "struct bpf_program" 235Sets the filter program used by the kernel to discard uninteresting 236packets. An array of instructions and its length is passed in using 237the following structure: 238.Bd -literal 239struct bpf_program { 240 int bf_len;	233.It Dv BIOCSETF 234.Pq Li "struct bpf_program" 235Sets the filter program used by the kernel to discard uninteresting 236packets. An array of instructions and its length is passed in using 237the following structure: 238.Bd -literal 239struct bpf_program { 240 int bf_len;
241 struct bpf_insn *bf_insns;	241 struct bpf_insn *bf_insns;
242}; 243.Ed 244.Pp 245The filter program is pointed to by the 246.Li bf_insns	242}; 243.Ed 244.Pp 245The filter program is pointed to by the 246.Li bf_insns
247field while its length in units of	247field while its length in units of
248.Sq Li struct bpf_insn 249is given by the 250.Li bf_len 251field. 252Also, the actions of 253.Dv BIOCFLUSH 254are performed. 255See section --- 70 unchanged lines hidden (view full) --- 326.It Li bh_hdrlen 327The length of the 328.Nm 329header, which may not be equal to 330.\" XXX - not really a function call 331.Fn sizeof "struct bpf_hdr" . 332.El 333.Pp	248.Sq Li struct bpf_insn 249is given by the 250.Li bf_len 251field. 252Also, the actions of 253.Dv BIOCFLUSH 254are performed. 255See section --- 70 unchanged lines hidden (view full) --- 326.It Li bh_hdrlen 327The length of the 328.Nm 329header, which may not be equal to 330.\" XXX - not really a function call 331.Fn sizeof "struct bpf_hdr" . 332.El 333.Pp
334The	334The
335.Li bh_hdrlen 336field exists to account for 337padding between the header and the link level protocol. 338The purpose here is to guarantee proper alignment of the packet	335.Li bh_hdrlen 336field exists to account for 337padding between the header and the link level protocol. 338The purpose here is to guarantee proper alignment of the packet
339data structures, which is required on alignment sensitive	339data structures, which is required on alignment sensitive
340architectures and improves performance on many other architectures.	340architectures and improves performance on many other architectures.
341The packet filter insures that the	341The packet filter insures that the
342.Li bpf_hdr 343and the network layer 344header will be word aligned. Suitable precautions 345must be taken when accessing the link layer protocol fields on alignment 346restricted machines. (This isn't a problem on an Ethernet, since 347the type field is a short falling on an even offset, 348and the addresses are probably accessed in a bytewise fashion). 349.Pp --- 12 unchanged lines hidden (view full) --- 362.Pp 363For example, if 364.Sq Li p 365points to the start of a packet, this expression 366will advance it to the next packet: 367.Dl p = (char )p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen) 368.Pp 369*For the alignment mechanisms to work properly, the	342.Li bpf_hdr 343and the network layer 344header will be word aligned. Suitable precautions 345must be taken when accessing the link layer protocol fields on alignment 346restricted machines. (This isn't a problem on an Ethernet, since 347the type field is a short falling on an even offset, 348and the addresses are probably accessed in a bytewise fashion). 349.Pp --- 12 unchanged lines hidden (view full) --- 362.Pp 363For example, if 364.Sq Li p 365points to the start of a packet, this expression 366will advance it to the next packet: 367.Dl p = (char )p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen) 368.Pp 369*For the alignment mechanisms to work properly, the
370buffer passed to	370buffer passed to